289 lines
6.8 KiB
Markdown
289 lines
6.8 KiB
Markdown
# ComfyUI-UniversalRemove
|
|
|
|
一个自包含的 ComfyUI remove 核心扩展。
|
|
|
|
## 设计目标
|
|
|
|
- 不硬编码任何本地路径
|
|
- 不依赖其他自定义节点
|
|
- 只使用 ComfyUI 常见核心类型：`IMAGE` / `MASK` / `STRING` / `INT` / `FLOAT`
|
|
- 面向 **图像批 / 视频帧批** 工作，适合作为通用 remove 流程的中间层
|
|
|
|
## 当前提供的节点
|
|
|
|
### 0. `UR Demo Image`
|
|
|
|
生成一个无需外部图片文件的测试图像，主要用于示例工作流和安装验证。
|
|
|
|
### 1. `UR Remove Prompt Builder`
|
|
|
|
输入目标描述，输出三路提示词：
|
|
|
|
- `segmentation_prompt`
|
|
- `remove_positive_prompt`
|
|
- `remove_negative_prompt`
|
|
|
|
用途：
|
|
|
|
- `segmentation_prompt` 给任意文本选目标模块
|
|
- `remove_positive_prompt` 给关键帧修复模型
|
|
- `remove_negative_prompt` 给关键帧修复模型的负向提示
|
|
|
|
### 2. `UR Region Editor`
|
|
|
|
交互式前端 region 编辑器，输出标准 `regions_json`。
|
|
|
|
支持：
|
|
|
|
- 加载本地图片作为编辑背景
|
|
- 加载本地视频作为编辑背景并拖动时间轴
|
|
- 使用当前视频时间写入关键帧编号
|
|
- 绘制矩形区域
|
|
- 绘制圆形区域
|
|
- 绘制多边形区域
|
|
- 删除选中区域
|
|
- 清空全部区域
|
|
|
|
注意：背景图片 / 视频只用于前端交互预览，不会写进 workflow。真正可移植、可复用的是输出的 `regions_json`。
|
|
|
|
### 3. `UR Boxes To Mask Batch`
|
|
|
|
把 JSON 形式的矩形框转换成 `MASK` 批次。
|
|
|
|
支持：
|
|
|
|
- `xyxy`
|
|
- `xywh`
|
|
- 归一化坐标
|
|
- 三种广播模式：
|
|
- `repeat_to_batch`
|
|
- `single_frame_only`
|
|
- `hold_after_frame`
|
|
|
|
用途：
|
|
|
|
- 手工框选移除区域
|
|
- 从外部工具导入 bbox
|
|
|
|
### 4. `UR Regions To Mask Batch`
|
|
|
|
把关键帧 region JSON 转换成整段图像批 / 视频帧批的 `MASK`。
|
|
|
|
支持：
|
|
|
|
- `rect`
|
|
- `circle`
|
|
- `polygon`
|
|
- 单关键帧
|
|
- 多关键帧
|
|
- 四种广播模式：
|
|
- `repeat_to_batch`
|
|
- `single_frame_only`
|
|
- `hold_after_frame`
|
|
- `hold_until_next_keyframe`
|
|
|
|
用途：
|
|
|
|
- 用 JSON 描述“关键帧上的圈选区域”
|
|
- 为视频帧批生成对应 mask
|
|
- 后续接 `UR Mask Processor` / `UR Keyframe Prep` / `UR Soft Composite`
|
|
|
|
### 5. `UR Mask Processor`
|
|
|
|
对 mask 做 remove 常用处理：
|
|
|
|
- 扩张
|
|
- 高斯羽化
|
|
- 预览叠加
|
|
|
|
### 6. `UR Keyframe Prep`
|
|
|
|
从图像批中选出关键帧，并准备 remove 输入：
|
|
|
|
- 选关键帧
|
|
- 对应 mask 对齐
|
|
- 按最长边缩放
|
|
- pad 到指定倍数
|
|
- 用填充色生成 `filled_frame`
|
|
|
|
其中 `filled_frame` 可以直接送进任意关键帧修复 / inpaint / edit 模型。
|
|
|
|
### 7. `UR Soft Composite`
|
|
|
|
一个不依赖 BrushNet 的软融合节点，用于把修复结果融合回原图 / 原视频帧批。
|
|
|
|
## 推荐工作流
|
|
|
|
> 这个扩展刻意只负责 remove 核心流程，不强绑某个检测器、分割器、视频模型或视频 IO 节点。
|
|
|
|
### A. 手工框选 remove
|
|
|
|
```text
|
|
Frames/Image Batch
|
|
-> UR Region Editor
|
|
-> UR Regions To Mask Batch
|
|
-> UR Mask Processor
|
|
-> UR Keyframe Prep
|
|
-> 关键帧修复模型
|
|
-> (可选) 视频传播模型
|
|
-> UR Soft Composite
|
|
-> Output
|
|
```
|
|
|
|
### B. 提示词驱动 remove
|
|
|
|
```text
|
|
Frames/Image Batch
|
|
-> UR Remove Prompt Builder
|
|
-> 任意文本选目标模块（输出 MASK）
|
|
-> UR Mask Processor
|
|
-> UR Keyframe Prep
|
|
-> 关键帧修复模型
|
|
-> (可选) 视频传播模型
|
|
-> UR Soft Composite
|
|
-> Output
|
|
```
|
|
|
|
## 为什么没有内置“文本直接找目标”
|
|
|
|
这是刻意的设计边界：
|
|
|
|
- remove 核心流程应该通用、可复用
|
|
- 文本找目标属于检测 / 分割 / 跟踪能力
|
|
- 这部分通常意味着额外模型、额外权重、额外依赖
|
|
|
|
因此当前版本先把 remove 主流程做成稳定、自包含、无外部节点硬依赖的核心层。
|
|
|
|
如果后续要继续扩展，最自然的下一步是在这个扩展内部新增：
|
|
|
|
- `UR Prompt Mask Locator`
|
|
- `UR Video Track Mask`
|
|
- `UR Model Bundle`
|
|
|
|
但这些应当作为后续迭代，而不是在 V1 就把依赖链做死。
|
|
|
|
## 安装方式
|
|
|
|
把整个目录放进：
|
|
|
|
- `ComfyUI/custom_nodes/ComfyUI-UniversalRemove`
|
|
|
|
然后重启 ComfyUI。
|
|
|
|
## 示例工作流
|
|
|
|
当前已提供一个可直接导入的最小工作流：
|
|
|
|
- `example_workflows/Universal Remove - Interactive Region Editor.json`
|
|
|
|
这个 workflow 的特点：
|
|
|
|
- 只依赖 ComfyUI core + 本扩展
|
|
- 可直接导入并运行，不需要额外图片文件
|
|
- 可用 `UR Region Editor` 交互绘制 `regions_json`
|
|
- 也可以手工编辑 `regions_json`
|
|
- 可预览：
|
|
- mask preview
|
|
- filled keyframe
|
|
- soft composite result
|
|
|
|
这个示例是 **remove 核心流程示例**，不内置外部检测模型或修复模型，因此更适合作为：
|
|
|
|
- remove 管线起点
|
|
- 接入你自己的 inpaint / edit / video propagation 模型前的可运行 scaffold
|
|
|
|
## 测试
|
|
|
|
仓库内已提供基础单元测试：
|
|
|
|
- `tests/test_universal_remove.py`
|
|
|
|
运行方式：
|
|
|
|
```bash
|
|
uv pip install --python /path/to/ComfyUI/.venv/bin/python -r requirements-dev.txt
|
|
/path/to/ComfyUI/.venv/bin/python -m pytest tests/test_universal_remove.py
|
|
```
|
|
|
|
## 视频输入与关键帧圈选
|
|
|
|
当前扩展不内置视频读取器，但已经内置 `UR Region Editor` 前端交互式圈选 UI。
|
|
|
|
推荐接法是：
|
|
|
|
```text
|
|
任意视频读取节点 / 你的脚本
|
|
-> IMAGE frame batch
|
|
-> UR Region Editor 输出 regions_json
|
|
-> UR Regions To Mask Batch
|
|
```
|
|
|
|
也就是说，本扩展支持的是：
|
|
|
|
- 输入视频拆帧后的 `IMAGE` 批次
|
|
- 通过 `frame_index` 指定关键帧
|
|
- 通过 `UR Region Editor` 鼠标绘制或手写 `regions_json` 描述关键帧上的圈选区域
|
|
- 输出整段帧批可用的 `MASK`
|
|
|
|
`UR Region Editor` 的本地视频背景只用于交互定位，不替代实际视频读取节点；真正进入后端计算的是上游 `IMAGE` frame batch 和编辑器输出的 `regions_json`。
|
|
|
|
## region JSON 示例
|
|
|
|
### 单关键帧矩形 + 圆形
|
|
|
|
```json
|
|
[
|
|
{"type": "rect", "frame_index": 0, "x": 160, "y": 120, "w": 260, "h": 140},
|
|
{"type": "circle", "frame_index": 0, "cx": 520, "cy": 250, "r": 70}
|
|
]
|
|
```
|
|
|
|
### 多关键帧多边形
|
|
|
|
```json
|
|
[
|
|
{
|
|
"type": "polygon",
|
|
"frame_index": 0,
|
|
"points": [[120, 160], [240, 150], [280, 260], [150, 290]]
|
|
},
|
|
{
|
|
"type": "polygon",
|
|
"frame_index": 48,
|
|
"points": [[180, 170], [310, 160], [350, 280], [210, 310]]
|
|
}
|
|
]
|
|
```
|
|
|
|
配合 `broadcast_mode=hold_until_next_keyframe` 时，第一个关键帧 mask 会使用到下一个关键帧之前，第二个关键帧 mask 会使用到结尾。
|
|
|
|
## bbox JSON 示例
|
|
|
|
### `xyxy`
|
|
|
|
```json
|
|
[
|
|
[100, 120, 420, 220],
|
|
[520, 50, 700, 160]
|
|
]
|
|
```
|
|
|
|
### `xywh`
|
|
|
|
```json
|
|
[
|
|
{"x": 100, "y": 120, "w": 320, "h": 100},
|
|
{"x": 520, "y": 50, "w": 180, "h": 110}
|
|
]
|
|
```
|
|
|
|
## 备注
|
|
|
|
这个扩展当前最适合做：
|
|
|
|
- 通用 remove 流程骨架
|
|
- 去水印 / 去字幕 / 去 logo
|
|
- 有上游 mask 时的角色移除 / 物体移除
|
|
|
|
如果你下一步要做“文本直接选目标并跟踪整段视频”，建议继续在这个目录里加新节点，而不是让核心 remove 节点反向依赖别的 custom nodes。
|