使用CorridorKey进行AI绿幕抠像：从绿幕素材生成干…

适用于需要从绿幕视频/图像中提取带有准确边缘（如头发、运动模糊）的前景和线性alpha通道的VFX合成场景。

适用场景

解决思路

1. 准备两个输入：RGB绿幕图像（sRGB或线性gamma，sRGB/REC709色域）和粗略的黑白Alpha Hint mask（不需要精确）。
2. 安装uv包管理器：Linux/macOS运行 curl -LsSf https://astral.sh/uv/install.sh | sh；Windows运行 Install_CorridorKey_Windows.bat。
3. 根据设备安装依赖：运行 uv sync（CPU/Apple MPS）、uv sync --extra cuda（NVIDIA GPU）或 uv sync --extra mlx（Apple Silicon MLX）。
4. 下载模型权重（约300MB）：从 https://huggingface.co/nikopueringer/CorridorKey_v1.0/resolve/main/CorridorKey_v1.0.pth 下载，并重命名为 CorridorKey.pth 放到 CorridorKeyModule/checkpoints/ 目录。
5. 可选安装GVM Alpha Hint生成器：运行 uv run hf download geyongtao/gvm --local-dir gvm_core/weights。
6. 可选安装VideoMaMa Alpha Hint生成器：运行 uv run hf download SammyLim/VideoMaMa --local-dir VideoMaMaInferenceModule/checkpoints/VideoMaMa。
7. 可选安装VideoMaMa依赖的stable-video-diffusion模型：运行 uv run hf download stabilityai/stable-video-diffusion-img2vid-xt --local-dir VideoMaMaInferenceModule/checkpoints/stable-video-diffusion-img2vid-xt --include "feature_extractor/*" "image_encoder/*" "vae/*" "model_index.json"。
8. Windows可选安装：运行 Install_GVM_Windows.bat 或 Install_VideoMaMa_Windows.bat。
9. 运行推理：uv run python main.py run_inference --device cuda（或 --device cpu，--device mps）。
10. 列出可用clips/shots：uv run python main.py list。
11. 运行交互式设置向导：uv run python main.py wizard（可加 --win_path /path/to/ClipsForInference）。
12. 使用Docker构建镜像：docker build -t corridorkey:latest .。
13. 使用Docker运行推理：docker run --rm -it --gpus all -e OPENCV_IO_ENABLE_OPENEXR=1 -v "$(pwd)/ClipsForInference:/app/ClipsForInference" -v "$(pwd)/Output:/app/Output" -v "$(pwd)/CorridorKeyModule/checkpoints:/app/CorridorKeyModule/checkpoints" corridorkey:latest run_inference --device cuda。
14. 使用Docker Compose构建：docker compose build。
15. 使用Docker Compose运行推理：docker compose --profile gpu run --rm corridorkey run_inference --device cuda。
16. 使用Docker Compose列出clips：docker compose --profile gpu run --rm corridorkey list。
17. 在多GPU系统上指定GPU：NVIDIA_VISIBLE_DEVICES=0 docker compose --profile gpu run --rm corridorkey run_inference --device cuda。
18. 按目录结构组织数据：输入帧放 ClipsForInference/my_shot/frames/，alpha hints放 ClipsForInference/my_shot/alpha_hints/，可选VideoMaMa手绘hint放 ClipsForInference/my_shot/VideoMamaMaskHint/；输出到 Output/my_shot/foreground/ 和 Output/my_shot/alpha/。
19. Python基本推理：加载 CorridorKeyModel，用 torch.load 加载 CorridorKeyModule/checkpoints/CorridorKey.pth，调用 run_inference(shot_dir=Path("ClipsForInference/my_shot"), output_dir=Path("Output/my_shot"), device=device)。
20. 读写EXR：在 import cv2 之前设置 os.environ["OPENCV_IO_ENABLE_OPENEXR"] = "1"，用 cv2.imread(..., cv2.IMREAD_UNCHANGED | cv2.IMREAD_ANYCOLOR) 读取EXR，转换BGR->RGB处理，写EXR时转回BGRA并保存为float32。
21. 用OpenCV生成粗略alpha hint：定义函数 generate_chroma_key_hint，将图像转HSV，用 lower_green = np.array([35, 50, 50])、upper_green = np.array([85, 255, 255]) 和 cv2.inRange 得到绿色mask，取反得到前景mask，用 cv2.erode 腐蚀（erode_px=5 或8，迭代2次），再用 cv2.GaussianBlur((15,15),5) 模糊，返回灰度mask。
22. 批量处理帧准备shot文件夹：定义函数 prepare_shot_folder，遍历原始帧（*.png, *.exr），复制到 frames_out，用 hint_generator_fn 或默认 generate_chroma_key_hint 生成hint到 hints_out。
23. 使用 clip_manager.py 生成alpha hints（GVM）：调用 generate_alpha_hints_gvm(shot_dir="ClipsForInference/my_shot", device="cuda")。
24. 使用 clip_manager.py 生成alpha hints（VideoMaMa）：先将粗糙mask放入 VideoMamaMaskHint/，然后调用 generate_alpha_hints_videomama(shot_dir="ClipsForInference/my_shot", device="cuda")。
25. 使用 clip_manager.py 生成alpha hints（BiRefNet）：调用 generate_alpha_hints_birefnet(shot_dir="ClipsForInference/my_shot", device="cuda")。
26. Alpha Hint最佳实践（好）：使用腐蚀并稍微模糊的hint，例如 kernel = np.ones((10, 10), np.uint8)，先 cv2.erode(raw_mask, kernel, iterations=3)，再 cv2.GaussianBlur(good_hint, (21, 21), 7)。
27. Alpha Hint最佳实践（坏）：避免使用膨胀的hint，不要运行 cv2.dilate(raw_mask, kernel, iterations=3)。
28. Alpha Hint最佳实践（可接受）：直接使用二值粗略chroma key mask，但不要膨胀。
29. 输出集成：CorridorKey输出 straight (un-premultiplied) RGBA EXRs 线性光，在Nuke中设置colorspace为linear，直接连Merge (over)，无需Unpremult节点。
30. 验证输出是straight alpha：读EXR，检查半透明像素的alpha和颜色，颜色应保持全强度（例如 result[h//2, w//2, :3] 不乘以alpha）。
31. 故障排除（CUDA）：检查 nvidia-smi 支持CUDA 12.8+，重新运行 uv sync --extra cuda，验证 uv run python -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)"。
32. 故障排除（OpenEXR）：在 import cv2 之前设置 export OPENCV_IO_ENABLE_OPENEXR=1 或 os.environ["OPENCV_IO_ENABLE_OPENEXR"] = "1"。
33. 故障排除（VRAM不足）：使用 --device cpu，或减小batch size/用tiled inference，4K需6-8GB VRAM，Apple Silicon用 --device mps。
34. 故障排除（模型文件未找到）：确保文件名是 CorridorKey.pth 在 CorridorKeyModule/checkpoints/，如果是 CorridorKey_v1.0.pth 需重命名。
35. 故障排除（Docker GPU passthrough失败）：测试 docker run --rm --gpus all nvidia/cuda:12.6.3-runtime-ubuntu22.04 nvidia-smi，安装/配置 nvidia-container-toolkit，然后 sudo systemctl restart docker。
36. 故障排除（抠像效果差）：hint太膨胀则多腐蚀；确保输入是sRGB/REC709色域，不要直接传log；极端绿幕溢出考虑先despill；静态物体用VideoMaMa手绘hint，GVM最适合人。

适用边界 · 注意事项

• 不适用于非绿幕背景的抠像（如蓝幕或其他纯色背景），模型是针对绿幕颜色解混训练的。
• 不适用于未进行色彩空间转换的log素材，直接使用会导致结果差，需先转为sRGB/REC709。
• 不适用于需要实时或超低延迟处理且无GPU加速的环境，推理速度受限。