UI Extractor

从静态图片中自动识别背景类型（棋盘格 / 关键色），去除背景，分离独立的 UI 组件，输出透明 PNG。

触发场景

• 需要从带棋盘格背景的 UI 设计图中提取组件
• 需要从绿幕/蓝幕/白幕/黑幕拍摄图中抠出主体
• 需要将 UI 套件拆分为独立的组件图片
• 需要校正倾斜拍摄的棋盘格图片

工作流程

1. 确认图片路径：用户提供带背景的图片路径。
2. 确认需求：背景类型（auto/chroma/checkerboard）、是否分离元素、是否做透视校正。如果 $ARGUMENTS 非空，解析其中的参数。
3. 执行处理：

cd scripts && uv run ui_extractor.py --input <图片路径> [选项]

参数

示例

# 自动检测背景类型
uv run ui_extractor.py --input ui-design.png

# 明确指定绿幕背景
uv run ui_extractor.py --input photo.jpg --bg-type chroma --bg-color green

# 只去背景不分离元素
uv run ui_extractor.py --input photo.jpg --no-extract

# 棋盘格 + 透视校正
uv run ui_extractor.py --input tilted.png --bg-type checkerboard --warp

# 调试模式
uv run ui_extractor.py --input photo.jpg --debug

4. 展示结果：告知用户输出目录，并展示分离的 UI 组件。

输出文件

<output-dir>/
├── <name>-nobg.png        # 去背景后的完整图（BGRA）
├── <name>-warped.png      # 透视校正后的图（--warp）
├── elements/
│   ├── element_01.png     # 分离的每个 UI 元素
│   ├── element_02.png
│   └── ...
├── metadata.json          # 元素元数据（bbox、面积、坐标等）
├── summary.txt            # 处理摘要
└── debug/                 # --debug 模式输出
    ├── mask_overlay.png
    ├── foreground_mask.png
    ├── corners.png
    └── elements_annotated.png

注意事项

• 自动检测：默认 --bg-type auto 会尝试从四角像素和棋盘格角点检测背景类型
• chroma 算法：直接复制自 spritesheet skill 的 chroma.py（2026-06-16），保持与视频抠图结果一致
• 棋盘格检测：优先用 findChessboardCornersSB（OpenCV 4.5+），失败时回退到基于局部方差的纹理检测
• 透视校正：要求棋盘格完整可见，否则跳过并警告
• 元素分离：基于 findContours(RETR_EXTERNAL)，按面积/长宽比过滤，小于 --min-element-area 的元素会被丢弃

背景色建议

算法细节

详细的算法流程和参数说明见 references/pipeline.md。