# 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。