CorridorKey

“传统的键控器在猜测哪里是透明，而 CorridorKey 在重建原本应该存在的颜色。”

在影视后期中，绿幕抠图（Chroma Keying）始终是一个令人头疼的难题。尤其是当拍摄对象的边缘与绿色背景混合时（如发丝、运动模糊、焦外虚化），传统工具往往只能输出一个生硬的二值遮罩，强行切断那些微妙的半透明像素，导致合成效果虚假、边缘锯齿严重。

由开发者 nikopueringer 构建的 CorridorKey，正是为了解决这个核心的“分离”问题而生。它不是另一个简单的滤镜，而是一个基于神经网络的物理精确分离引擎。

核心突破：不仅仅是抠图，更是“还原”

CorridorKey 的工作逻辑与传统算法截然不同：

• 传统方法：计算像素与绿色的差异，生成一个 Alpha 通道。对于混合像素，往往直接丢弃或简单插值，导致颜色失真。
• CorridorKey：输入一帧原始绿幕画面和一个粗略的 Alpha 提示，神经网络会预测两个关键输出：
  1. 直出颜色 (Unmultiplied Color)：重建前景物体在没有绿幕干扰下的真实颜色。即使是高度透明的发丝尖端的绿色溢出，也会被主动还原为头发原本的颜色。
  2. 线性 Alpha 通道：生成一个干净、平滑、包含微妙透明度变化的 Matte。

结果：你得到的不再是一个需要反复修饰的“剪影”，而是一个可以直接用于 Nuke、Fusion 或 Resolve 进行高级合成的物理精确前景。

功能特性

• 🎨 物理精确分离：完美保留头发丝、运动模糊、玻璃反光等半透明细节。不再是“切掉”背景，而是“算出”前景。
• 📐 分辨率无关：引擎支持动态缩放推理，可处理 4K 甚至更高分辨率的图像序列，内部使用原生 2048x2048 高保真主干网络进行预测。
• 🎬 VFX 标准输出：原生支持 16-bit / 32-bit 线性浮点 EXR 格式。色彩空间、伽马曲线完全符合电影工业标准，无损耗保留动态范围。
• 🧹 自动清理：内置形态学清理系统，自动修剪残留的跟踪标记（Tracking Markers）或微小的背景噪点，减少人工 rotoscope 工作量。
• 🤖 智能提示生成：可选集成 GVM (Generative Video Matting) 和 VideoMaMa 模块，自动从视频中生成高质量的粗略 Alpha 提示，实现全自动化流程。

硬件要求：高性能是前提

CorridorKey 是一个重量级工具，对显存（VRAM）有较高要求：

注：对于显存低于 24GB 的用户，目前社区正在探索优化方案，但官方版本尚未支持。

快速开始：三步开启电影级抠图

第一步：安装环境

项目使用 uv 管理依赖，一键搞定 Python 环境和包安装。

Windows 用户：

1. 下载仓库，双击 Install_CorridorKey_Windows.bat。
2. 脚本会自动安装 uv、Python、依赖及 CorridorKey 主模型。
3. (可选) 运行 Install_GVM_Windows.bat 下载可选的大模型权重。

Linux / Mac 用户：

# 1. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 同步依赖
uv sync

# 3. 手动下载模型 (必须)
# 将 CorridorKey_v1.0.pth 下载并重命名为 CorridorKey.pth 放入 CorridorKeyModule/checkpoints/
# 可选：下载 GVM 或 VideoMaMa 权重

第二步：准备素材与提示

CorridorKey 需要两个输入：

1. 原始 RGB 图像/视频：sRGB 或 Linear 伽马均可。
2. 粗略 Alpha 提示：一个黑白遮罩，大致框选主体即可，无需精确。
   • 自动生成：向导可调用 GVM（全自动，适合人物）或 VideoMaMa（需粗略掩码，可控性强）生成提示。
   • 手动提供：你可以用任何简单工具（甚至 Photoshop 魔棒）画一个粗糙的遮罩。

第三步：运行向导

CorridorKey 提供了一个交互式命令行向导，极大简化了操作流程。

Windows: 将视频文件或文件夹拖放到 CorridorKey_DRAG_CLIPS_HERE_local.bat 上。
Linux/Mac: 拖放到 ./CorridorKey_DRAG_CLIPS_HERE_local.sh 或运行脚本。

向导流程：

1. 自动组织：脚本会自动创建标准的文件夹结构 (Input/, AlphaHint/, Matte/, FG/)。
2. 生成提示：若缺少 Alpha 提示，向导会询问是否调用 GVM/VideoMaMa 自动生成。
3. 参数配置：设置伽马空间、去溢强度 (Despill)、自动去斑阈值等。
4. 开始推理：引擎开始处理，输出以下结果：
   • /Matte: 纯净的线性 Alpha 通道 (EXR)。
   • /FG: 去溢后的直出前景颜色 (sRGB，需转线性使用)。这是 CorridorKey 的灵魂所在。
   • /Processed: 预乘好的 RGBA 图像 (EXR)，可直接用于 Premiere/Resolve 预览。
   • /Comp: 简单的棋盘格预览图 (PNG)。

工作流程示意

[原始绿幕素材] + [粗略 Alpha 提示] 
       ⬇️
[CorridorKey 神经网络]
       ⬇️
[重建真实颜色] + [生成线性 Matte]
       ⬇️
[EXR 输出] ➡️ [Nuke/Fusion/Resolve 合成]

高级配置与故障排除

• 设备选择：默认自动检测 (CUDA > MPS > CPU)。可通过 --device 标志或 CORRIDORKEY_DEVICE 环境变量强制指定。
• Mac 用户 (Apple Silicon)：
  • 支持 MPS (PyTorch 后端) 和 MLX (原生 Metal 后端)。
  • 推荐使用 MLX 以获得更佳性能：

    uv pip install corridorkey-mlx@git+https://github.com/nikopueringer/corridorkey-mlx.git
    export CORRIDORKEY_BACKEND=mlx
    

  • 若遇算子错误，设置 PYTORCH_ENABLE_MPS_FALLBACK=1。
• 测试：项目包含无需 GPU 的单元测试，可快速验证环境配置：

  uv sync --group dev
  uv run pytest
  

📜 许可与社区

• 许可证：基于 CC BY-NC-SA 4.0 变体。
  • ✅ 允许免费用于个人及商业项目（作为内部工具处理图像）。
  • ❌ 禁止将模型推理打包成付费 API 服务出售。
  • ❌ 禁止重新打包出售本工具。
  • ℹ️ 任何衍生作品必须保留 "CorridorKey" 名称并采用相同许可证。
• 未来计划：作者表示，若有足够多的社区需求，将开源训练代码和数据集，以便社区共同微调出更强大的模型。