commit bb61d2d3b6b852f31a0e508356291aeeb4ead873
Author: Codex <codex@example.local>
Date:   Tue Jun 30 13:39:24 2026 +0800

    Add green screen matting workflow

diff --git a/docs/green_screen_matting_workflow.md b/docs/green_screen_matting_workflow.md
new file mode 100644
index 0000000..c7e0b70
--- /dev/null
+++ b/docs/green_screen_matting_workflow.md
@@ -0,0 +1,442 @@
+# Green Screen Character Matting Workflow
+
+本文档定义一个可执行的离线绿幕人物抠图方案。目标输入是 AI 生成的绿色背景人物图，目标输出是高质量 RGBA PNG，重点处理发丝、衣服边缘、半透明区域、镂空洞和绿色污染。
+
+本方案不使用 YOLO / Faster R-CNN 作为主流程。原因是本任务不是目标检测，而是像素级 alpha matting。
+
+## 1. 目标
+
+- 输入：RGB / PNG 图像，背景主色为绿色，但不要求严格等于 `#00FF00`。
+- 输出：RGBA PNG。
+- 质量要求：
+  - 外部绿幕背景清理干净。
+  - 人物内部镂空洞如果露出绿幕，应透明。
+  - 发丝和衣服边缘尽量保留连续 alpha。
+  - 边缘无明显绿边、黑边、白边。
+  - 输出 debug 和多背景预览图用于质检。
+
+## 2. 非目标
+
+- 不处理实时视频流。
+- 不把 YOLO / Faster R-CNN 作为主体方案。
+- 不依赖输入背景 RGB 精确等于 `#00FF00`。
+- 不把 AI 生成阶段的提示词约束纳入处理工作流。
+
+## 3. 环境
+
+Python 环境使用 conda 环境 `lightML`。该环境后续可按需要安装依赖，方案不依赖当前环境状态。
+
+建议 Python 版本：
+
+```powershell
+conda create -n lightML python=3.10 -y
+conda activate lightML
+python -m pip install -U pip
+```
+
+PyTorch 根据本机 CUDA 版本从官方安装页选择命令。
+
+业务依赖建议：
+
+```powershell
+pip install opencv-python pillow numpy scipy scikit-image transformers accelerate safetensors huggingface_hub tqdm typer rich
+```
+
+首选模型：
+
+```text
+hustvl/vitmatte-small-composition-1k
+```
+
+先用 small 跑通流程和调参；质量不够再切 base 模型。
+
+## 4. 总体流程
+
+```text
+输入 RGB 图
+  ↓
+颜色空间转换：RGB / HSV / Lab
+  ↓
+自适应背景绿色建模
+  ↓
+绿幕置信度估计 Chroma Key
+  ↓
+生成 sure_bg / sure_fg / unknown
+  ↓
+输出 trimap：0 / 128 / 255
+  ↓
+ViTMatte GPU 推理
+  ↓
+trimap 约束 alpha
+  ↓
+alpha 轻量清理
+  ↓
+de-spill 去绿边
+  ↓
+RGBA PNG 导出
+  ↓
+多背景预览质检
+```
+
+## 5. 模块结构
+
+建议目录：
+
+```text
+BgFilter/
+  Samples/
+  Outputs/
+  docs/
+  bgfilter/
+    __init__.py
+    cli.py
+    io.py
+    chroma.py
+    trimap.py
+    vitmatte_infer.py
+    alpha_post.py
+    despill.py
+    qa.py
+  configs/
+    default.yaml
+```
+
+## 6. CLI 设计
+
+单图处理：
+
+```powershell
+conda activate lightML
+
+python -m bgfilter.cli `
+  --input Samples\TestImage.png `
+  --output Outputs\TestImage_rgba.png `
+  --debug-dir Outputs\TestImage_debug `
+  --device cuda
+```
+
+批处理：
+
+```powershell
+python -m bgfilter.cli `
+  --input-dir Samples `
+  --output-dir Outputs `
+  --device cuda
+```
+
+建议参数：
+
+```text
+--model-name hustvl/vitmatte-small-composition-1k
+--device cuda
+--sure-bg-threshold 0.92
+--sure-fg-threshold 0.12
+--unknown-radius-ratio 0.012
+--fg-safe-radius-ratio 0.006
+--despill true
+--debug true
+```
+
+## 7. 自适应背景绿色建模
+
+不能假设背景是精确 `#00FF00`。每张图需要估计实际绿幕颜色分布。
+
+输入 RGB 后，同时计算：
+
+- RGB
+- HSV
+- Lab
+
+先找候选绿色像素：
+
+```text
+G > R + margin
+G > B + margin
+S 较高
+H 位于绿色附近
+```
+
+从候选像素中估计：
+
+```text
+background_rgb_center
+background_hsv_center
+background_lab_center
+background_color_variance
+```
+
+可优先使用全图高置信绿色像素，也可以提高四边 / 四角采样权重，但不能把“边界连通”作为必要规则。
+
+## 8. 绿幕置信度 bg_confidence
+
+为每个像素输出 `0.0 - 1.0` 的背景置信度，而不是直接输出二值 mask。
+
+建议组合特征：
+
+```text
+bg_confidence =
+  hue_conf
+  * saturation_conf
+  * green_dominance_conf
+  * lab_distance_conf
+```
+
+其中：
+
+- `hue_conf`：像素 hue 是否接近估计的背景 hue。
+- `saturation_conf`：绿色背景通常具有较高 saturation。
+- `green_dominance_conf`：G 是否显著高于 R/B。
+- `lab_distance_conf`：Lab 色差是否接近估计背景色。
+
+注意：
+
+- 背景不均匀时，阈值应适度放宽。
+- 中等置信区域不要直接判背景，应交给 unknown。
+- 人物上的绿色反光、绿色饰品、绿色衣服细节可能误判，需要保守处理。
+
+## 9. Trimap 生成
+
+trimap 输出三值：
+
+```text
+0   = sure background
+128 = unknown
+255 = sure foreground
+```
+
+默认逻辑：
+
+```text
+sure_bg:
+  bg_confidence >= 0.92
+
+sure_fg:
+  bg_confidence <= 0.12
+  且距离 sure_bg 边界足够远
+
+unknown:
+  其他区域
+  + sure_bg / sure_fg 交界附近膨胀带
+  + 中置信绿色区域
+  + 发丝、半透明边缘、可疑反光区域
+```
+
+重要要求：
+
+- `sure_bg` 可以包含外部背景，也可以包含人物内部镂空洞。
+- 不要求 `sure_bg` 与图像边界连通。
+- 对低置信或可疑绿色区域，优先放入 `unknown`，不要激进判为背景。
+
+自适应半径：
+
+```text
+long_side = max(width, height)
+unknown_radius = long_side * 0.008 ~ 0.018
+fg_safe_radius = long_side * 0.004 ~ 0.010
+```
+
+例如长边为 1536 px：
+
+```text
+unknown_radius: 12 - 28 px
+fg_safe_radius: 6 - 15 px
+```
+
+## 10. 镂空洞处理
+
+如果镂空洞露出的是绿幕背景，则应被识别为背景或 unknown。
+
+处理原则：
+
+```text
+高置信绿幕区域 -> sure_bg
+中置信绿幕区域 -> unknown
+低置信非绿色区域 -> sure_fg
+```
+
+因此，人物内部的手臂空隙、发丝间隙、衣服结构空洞，只要露出绿幕且置信度足够高，就可以进入 `sure_bg`。
+
+风险：
+
+- 人物身上的绿色饰品、绿色反光、绿色衣物可能被误判成背景。
+- 对这些区域应通过置信度、颜色稳定性、面积、边缘特征降低误删风险。
+
+保守策略：
+
+```text
+非常高置信绿色 -> sure_bg
+中高置信但靠近人物颜色复杂区域 -> unknown
+非绿色稳定区域 -> sure_fg
+```
+
+## 11. ViTMatte 推理
+
+ViTMatte 输入：
+
+```text
+RGB image
+trimap
+```
+
+ViTMatte 输出：
+
+```text
+alpha matte: float32, 0.0 - 1.0
+```
+
+工程注意：
+
+- 优先使用 GPU。
+- 需要处理模型输入尺寸要求。
+- 推荐等比缩放 + padding，而不是直接拉伸。
+- 推理后将 alpha 反向裁剪 / 缩放回原图尺寸。
+
+模型调用建议基于 Hugging Face：
+
+```text
+VitMatteImageProcessor
+VitMatteForImageMatting
+```
+
+## 12. Trimap 约束 Alpha
+
+ViTMatte 输出后必须用 trimap 做强约束：
+
+```text
+trimap == 0   -> alpha = 0
+trimap == 255 -> alpha = 1
+trimap == 128 -> 使用 ViTMatte 预测 alpha
+```
+
+目的：
+
+- 减少背景残留。
+- 减少人物内部透明噪声。
+- 保证确定背景和确定前景的稳定性。
+
+## 13. Alpha 轻量清理
+
+只做轻量后处理，避免破坏发丝。
+
+允许：
+
+```text
+alpha clamp 到 0.0 - 1.0
+移除极小孤立噪点
+填补 sure_fg 内部小透明孔
+unknown 区域轻微 bilateral / guided smoothing
+```
+
+避免：
+
+```text
+大范围腐蚀
+大范围膨胀
+强高斯模糊
+硬阈值化 alpha
+```
+
+## 14. De-spill 去绿边
+
+只在边缘区域做去绿边：
+
+```text
+edge = 0.02 < alpha < 0.98
+```
+
+也可以扩展为：
+
+```text
+edge = alpha 梯度区域 + 外扩 1 - 3 px
+```
+
+处理原则：
+
+```text
+如果 G 明显高于 R/B
+  根据估计背景绿色模型降低 G
+  强度按 alpha 和 bg_confidence 调整
+```
+
+不要全图去绿，否则会影响肤色、白衣阴影、灰色衣物和暗部颜色。
+
+## 15. 输出文件
+
+每张图输出：
+
+```text
+result_rgba.png
+debug/bg_confidence.png
+debug/trimap.png
+debug/alpha.png
+debug/despill_mask.png
+debug/preview_black.png
+debug/preview_white.png
+debug/preview_gray.png
+debug/preview_red.png
+debug/preview_blue.png
+debug/qa_grid.png
+```
+
+## 16. QA 质检
+
+必须生成多背景预览：
+
+```text
+黑底
+白底
+灰底
+红底
+蓝底
+```
+
+检查项：
+
+- 人物外部绿色背景是否清干净。
+- 人物内部镂空洞是否透明。
+- 头发是否断裂或糊成硬边。
+- 深色衣服边缘是否出现黑边。
+- 白色衣服边缘是否出现绿边。
+- 透明区域是否自然。
+- alpha 图是否有明显噪点或孔洞。
+
+## 17. 前置输入声明
+
+以下不是处理工作流的一部分，只是输入建议：
+
+```text
+期望输入为绿色背景人物图。
+背景主色接近绿色，但不要求精确 #00FF00。
+人物主体尽量不要有大面积绿色服装或绿色饰品。
+如果前景本身和背景高度同色，仅靠 chroma key 无法可靠区分，需要人工 hint 或额外模型兜底。
+```
+
+## 18. 第一阶段验收标准
+
+第一阶段实现完成后，使用 `Samples/TestImage.png` 和 `Samples/TestImage2.png` 验收：
+
+```text
+1. 能生成 RGBA PNG。
+2. 能生成 bg_confidence / trimap / alpha debug 图。
+3. 能生成黑白灰红蓝多背景 QA 图。
+4. 外部绿幕基本无残留。
+5. 发丝区域不是硬切边。
+6. 镂空洞露出绿幕时可透明。
+7. 边缘没有明显绿色污染。
+```
+
+## 19. 推荐落地顺序
+
+```text
+1. 实现输入输出和 CLI。
+2. 实现 RGB / HSV / Lab 转换。
+3. 实现背景绿色建模。
+4. 实现 bg_confidence。
+5. 实现 trimap 生成和 debug 输出。
+6. 接入 ViTMatte GPU 推理。
+7. 加 trimap alpha 强约束。
+8. 实现轻量 alpha 清理。
+9. 实现 de-spill。
+10. 实现 QA grid。
+11. 用样例图调默认参数。
+```