comfyui_region_uv_metadata

ComfyUI Region UV Metadata Nodes

把输入图片里的指定目标区域识别出来，提取 UV 顶点，写进输出图片的 metadata，并额外输出一张带标注的预览图。

同时提供一个读取节点，用来检查 PNG 或 WEBP 里有没有这个 metadata；如果有，就输出一张带区域标识的预览图。

现在也提供一个专门的保存节点，可以直接保存成 PNG 或 WEBP，并把 metadata 一起写进去。

功能

• 输入一张 IMAGE
• 输入多个待识别目标
• 支持英文逗号、中文逗号、顿号、分号、换行分隔
• 输出标注识别区域的预览图 IMAGE
• 输出 metadata 的 JSON 字符串
• 输出一个只能连接到专用保存节点的 metadata_image
• 在保存 PNG 或 WEBP 时把目标区域的 UV 顶点写进对应图片格式的扩展字段
• 提供一个 PNG / WEBP metadata 读取预览节点
• 提供一个 PNG / WEBP 提示词与工作流读取节点
• 提供一个 PNG / WEBP 专用保存节点
• 首次自动下载模型时，节点会显示执行进度

默认写入结构如下：

{
  "region_uv_vertices": {
    "person": [
      {
        "score": 0.93,
        "polygon_uv": [[0.12, 0.18], [0.45, 0.17], [0.48, 0.79], [0.11, 0.81]]
      },
      {
        "score": 0.81,
        "polygon_uv": [[0.52, 0.20], [0.70, 0.19], [0.73, 0.76], [0.50, 0.77]]
      }
    ],
    "car": []
  }
}

安装

把整个目录复制到：

ComfyUI/custom_nodes/comfyui_region_uv_metadata

然后在 ComfyUI 的 Python 环境里安装依赖：

pip install -r ComfyUI/custom_nodes/comfyui_region_uv_metadata/requirements.txt

重启 ComfyUI。

节点

1. Detect Region UV + Build Metadata Image

分类：

Image/Metadata

输入：

• image: ComfyUI 图片输入
• targets_json: 要识别的内容 作用：可以写单个目标、逗号分隔、多行，或者 JSON 数组
• metadata_field: 写入图片 metadata 的字段名，默认 region_uv_vertices 作用：决定最终在 PNG / WEBP 里保存时使用哪个字段名
• box_threshold: Grounding DINO 检测阈值 作用：越高越严格，检测框更少；越低越容易多检
• text_threshold: Grounding DINO 文本匹配阈值 作用：越高越要求文字和区域更匹配；越低更宽松
• max_detections_per_target: 同一个识别内容最多保留几个结果 作用：限制单个目标标签最多输出多少个区域
• polygon_simplify: 多边形简化强度 作用：越大顶点越少、轮廓越粗；越小越贴边但点更多
• min_area_ratio: 过滤小噪点轮廓 作用：按整张图面积比例过滤太小的 mask 区域
• line_thickness: 预览标线粗细 作用：只影响 preview_image 上的描边显示
• font_scale: 预览文字大小 作用：只影响 preview_image 上的标签文字显示

输出：

• metadata_image: 专用图片输出，只能连接 Save Metadata Image As PNG/WEBP
• preview_image: 带区域标注的预览图
• metadata_json: 当前写入内容的 JSON 字符串

建议：

• 如果你只想识别一个大主体，可以先把 box_threshold 提高一点
• 如果你发现轮廓点太多，可以把 polygon_simplify 调大一点
• 如果你发现把小装饰也识别进来了，可以把 min_area_ratio 调大一点

targets_json 现在支持这些写法：

person, dog, car

人，狗，车

person
dog
car

["person", "dog", "car"]

2. Read Region UV Metadata From Image

这个节点会直接读取 PNG 或 WEBP 文件里的 metadata，所以它的输入是上传/选择图片文件，不是普通的 IMAGE 张量。

输入：

• image: 选择一张 PNG 或 WEBP 图片
• metadata_field: 要读取的字段名，默认 region_uv_vertices 作用：决定去图片里读取哪个 metadata 字段
• line_thickness: 预览标线粗细 作用：只影响读取后生成的预览图描边粗细
• font_scale: 预览文字大小 作用：只影响读取后生成的预览图文字大小

输出：

• image: 读取到的原图
• preview_image: 如果找到 metadata，就在图上标出区域
• metadata_json: 读取到的 JSON 字符串
• has_metadata: 是否找到对应 metadata

3. Save Metadata Image As PNG/WEBP

这个节点是专门的输出保存节点，用来把上游图片直接保存成 png 或 webp。

如果你想输出 .webp，不要接内置 Save Image，而是接这个节点。

输入：

• metadata_image: 从 Detect Region UV + Build Metadata Image 输出的专用图片
• filename_prefix: 输出文件名前缀 作用：决定保存文件名开头
• image_format: 选择 png 或 webp，默认 webp 作用：决定最终保存格式
• webp_quality: WEBP 有损质量 作用：数值越高画质越好、文件通常越大
• webp_lossless: 是否使用 WEBP 无损保存 作用：开启后优先保真，文件通常会更大

说明：

• 保存 png 时，会把 metadata 写进 PNG 文本字段
• 保存 webp 时，会把 metadata 写进 WEBP 的 EXIF 字段
• 读取节点会同时兼容这两种写法

建议：

• 日常默认直接用 webp + 95
• 如果你更在意体积，可以关心 webp_quality
• 如果你更在意像素完全不损失，可以打开 webp_lossless

4. Read Comfy Prompt/Workflow From Image

这个节点用来读取图片里内嵌的 ComfyUI prompt 和 workflow。

适合场景：

• 你把 .webp 或 .png 拖回 ComfyUI 时，前端没有自动恢复工作流
• 你想手动检查图片里到底有没有写入 prompt / workflow

输入：

• image: 选择一张 PNG 或 WEBP 图片 作用：从图片里读取内嵌的 ComfyUI prompt 和 workflow

输出：

• prompt_json: 读取到的 prompt JSON
• workflow_json: 读取到的 workflow JSON
• has_prompt: 是否找到 prompt
• has_workflow: 是否找到 workflow

模型策略

当前实现按下面顺序查找模型：

1. 环境变量 COMFY_REGION_GROUNDING_MODEL / COMFY_REGION_SAM2_MODEL
2. 当前节点目录下的本地模型目录：
   • models/grounding-dino-tiny
   • models/sam2.1-hiera-small
3. Hugging Face 自动下载到上面的本地目录

也就是说，如果你不手动放模型，首次运行时会自动从 Hugging Face 下载，并尽量在节点执行时显示进度。

本地模型目录与下载链接

如果你想手动下载模型，请把目录放成这样：

ComfyUI/custom_nodes/comfyui_region_uv_metadata/
  models/
    grounding-dino-tiny/
      config.json
      model.safetensors
      preprocessor_config.json
      tokenizer.json
      tokenizer_config.json
      special_tokens_map.json
      vocab.txt
    sam2.1-hiera-small/
      config.json
      model.safetensors
      preprocessor_config.json

下载页面：

• Grounding DINO Tiny: IDEA-Research/grounding-dino-tiny
• SAM 2.1 Hiera Small: facebook/sam2.1-hiera-small

最简单的做法是打开上面的 Hugging Face 页面，下载整个仓库文件，然后分别放进：

• ComfyUI/custom_nodes/comfyui_region_uv_metadata/models/grounding-dino-tiny
• ComfyUI/custom_nodes/comfyui_region_uv_metadata/models/sam2.1-hiera-small

如果目录里文件齐全，节点就会优先使用本地模型，不再走自动下载。

输出与保存

节点真正写 metadata 的时机，还是你后面接保存节点的时候。

推荐：

• 默认直接接这个插件的 Save Metadata Image As PNG/WEBP
• 保存节点默认就是 webp + 95
• 如果你想要 .png，再把保存节点切到 png

注意：

• 保存成 .png 时，会写进 PNG 对应的 metadata 字段
• 保存成 .webp 时，会写进 WEBP 对应的 metadata 字段
• 如果 ComfyUI 启动时禁用了 metadata，这个字段不会落盘
• 结构保持一致，不区分图片格式
• 单张图时写入结构是：

{
  "你的字段名": {
    "目标1": [
      {
        "score": 0.93,
        "polygon_uv": [[u, v], [u, v]]
      }
    ],
    "目标2": []
  }
}

• 批量图片输入时，同一个字段会写成按 batch_index 分组的列表

识别逻辑

• 用 Grounding DINO 做文本目标检测
• 每个目标默认保留多个高分检测框
• 再用 SAM2 根据框生成分割 mask
• 最后把 mask 转为 UV 多边形顶点

可选本地模型目录

如果你希望随插件一起分发模型，可以手动创建：

comfyui_region_uv_metadata/
  models/
    grounding-dino-tiny/
    sam2.1-hiera-small/

这两个目录里放 Hugging Face 对应模型仓库下载下来的文件即可。