nikopueringer/CorridorKey

CorridorKeyMp4.mp4

그린 스크린 (green screen)을 배경으로 무언가를 촬영할 때, 피사체의 가장자리는 필연적으로 초록색 배경과 섞이게 됩니다. 이는 피사체의 색상과 그린 스크린의 색상이 혼합된 픽셀을 생성합니다. 전통적인 키어 (keyer)들은 이러한 색상들을 분리하는 데 어려움을 겪으며, 이로 인해 복잡한 에지 매트 (edge matte)를 구축하거나 수동으로 로토스코핑 (rotoscoping)을 하는 데 수 시간을 소비하게 만듭니다. 심지어 최신 "AI Roto" 솔루션들도 대개 거친 이진 마스크 (binary mask)를 출력하여, 사실적인 합성 (composite)에 필요한 섬세하고 반투명한 픽셀들을 완전히 파괴해 버립니다.

저는 이 언믹싱 (unmixing) 문제를 해결하기 위해 CorridorKey를 만들었습니다.

가공되지 않은 그린 스크린 프레임을 입력하면, 신경망 (neural network)이 전경 객체 (foreground object)를 그린 스크린으로부터 완전히 분리합니다. 모션 블러 (motion blur)나 초점이 맞지 않는 가장자리와 같이 투명도가 매우 높은 픽셀을 포함하여 모든 단일 픽셀에 대해, 모델은 깨끗한 선형 알파 채널 (linear alpha channel)과 함께 전경 요소의 실제, 언멀티플라이드 (un-multiplied)된 순수 색상을 예측합니다. 모델은 단순히 무엇이 불투명하고 무엇이 투명한지를 추측하는 것이 아니라, 마치 그린 스크린이 처음부터 없었던 것처럼 전경 객체의 색상을 능동적으로 재구성합니다.

더 이상 형편없는 매트 (matte)와 싸우거나 "코어 (core)" 키 대 "에지 (edge)" 키 사이에서 고통받을 필요가 없습니다. CorridorKey에 원하는 바를 약간만 힌트로 주면, 모델이 당신을 위해 빛을 분리해 줍니다.

이것은 완전히 새로운 릴리스이며, 개선할 수 있는 많은 방법들을 발견하시리라 확신합니다! 모든 분의 도움을 요청합니다. 아이디어, 작업물, 포크 (forks) 등을 공유하기 위해 "Corridor Creates" Discord에 참여해 주세요! https://discord.gg/zvwUrdWXJm

만약 설치가 간편하고 아티스트 친화적인 사용자 인터페이스 (user interface) 버전의 CorridorKey를 원하신다면, EZ-CorridorKey를 확인해 보세요.

이 프로젝트는 의존성 관리를 위해 uv를 사용합니다. uv는 Python 설치, 가상 환경 (virtual environments), 그리고 패키지 관리를 한 번에 처리하므로, 이와 관련된 사항들을 걱정할 필요가 없습니다. 사용 중인 OS에 맞는 적절한 설치 스크립트를 실행하기만 하면 됩니다.

당연하게도, 저는 모든 것을 테스트하지는 않았습니다. 오류가 발생할 경우, 필요에 따라 코드를 패치하고 풀 리퀘스트 (pull request)를 제출하는 것을 고려해 주세요.

물리적으로 정확한 언믹싱 (Physically Accurate Unmixing): 직선적인 컬러 전경 (color foreground) 및 선형 알파 채널 (linear alpha channels)을 깨끗하게 추출하여, 머리카락, 모션 블러 (motion blur), 그리고 반투명성 (translucency)을 보존합니다.

그린 또는 블루 스크린 (Green or Blue Screen): 그린 및 블루 플레이트 (plates)를 위한 전용 체크포인트 (checkpoints)를 제공합니다. 기본값 (--screen-color auto)으로 CorridorKey는 배치 (batch) 내 첫 번째 클립의 첫 프레임을 샘플링하여 배경 픽셀에서 지배적인 스크린 색상을 선택합니다. 휴리스틱 (heuristic) 과정을 건너뛰고 선택을 강제하려면 --screen-color green 또는 --screen-color blue를 전달하세요. 그 후 디스필 (despill) 과정이 실제로 촬영 대상이 된 채널로부터 스필 (spill)을 제거합니다. 현재 Torch 백엔드만 지원하며, MLX 경로는 블루 MLX 체크포인트가 출시될 때까지 그린 스크린 전용입니다.

해상도 독립성 (Resolution Independent): 엔진은 고유의 2048x2048 고충실도 (high-fidelity) 백본 (backbone)을 사용하여 예측하는 동안, 4K 플레이트를 처리할 수 있도록 추론 (inference)을 동적으로 스케일링합니다.

VFX 표준 출력 (VFX Standard Outputs): 16비트 및 32비트 리니어 부동 소수점 (Linear float) EXR 파일을 네이티브로 읽고 쓰며, Nuke, Fusion 또는 Resolve에서의 통합을 위해 실제 컬러 연산 (color math)을 보존합니다.

자동 클린업 (Auto-Cleanup): CorridorKey의 탐지를 통과해 버린 트래킹 마커 (tracking markers)나 미세한 배경 특징들을 자동으로 제거하기 위한 형태학적 클린업 (morphological cleanup) 시스템을 포함합니다.

이 프로젝트는 96GB의 VRAM을 갖춘 NVIDIA RTX Pro 6000이 장착된 Linux 워크스테이션 (Puget Systems PC)에서 설계 및 구축되었습니다. 커뮤니티는 소비자용 GPU를 위해 이를 적극적으로 최적화하고 있습니다.

가장 최신 빌드는 6-8GB의 VRAM을 가진 컴퓨터에서 작동해야 하며, 통합 메모리 (unified memory)를 사용하는 대부분의 M1+ Mac 시스템에서 실행할 수 있습니다. 네, 심지어 여러분의 오래된 Macbook Pro에서도 작동할 수도 있습니다. Discord를 통해 저희에게 알려주세요!

Windows 사용자 (NVIDIA): Windows에서 GPU 가속 (GPU acceleration)을 네이티브로 실행하려면, 시스템에 CUDA 12.8 이상을 지원하는 NVIDIA 드라이버가 반드시 설치되어 있어야 합니다. 드라이버가 이전 버전의 CUDA만 지원하는 경우, 설치 프로그램은 CPU로 폴백 (fallback)될 가능성이 높습니다.

AMD GPU 사용자 (ROCm): AMD Radeon RX 7000 시리즈 (RDNA3) 및 RX 9000 시리즈 (RDNA4)는 Linux 상의 ROCm을 통해 지원됩니다. Windows에서의 ROCm 지원은 실험적 단계입니다 (torch.compile이 아직 작동하지 않습니다). 아래의 AMD ROCm 설정 섹션을 참조하세요.

GVM (선택 사항): 약 80 GB의 VRAM이 필요하며, 거대한 Stable Video Diffusion 모델을 활용합니다.

VideoMaMa (선택 사항): 이 역시 네이티브로 매우 큰 양의 VRAM을 요구합니다 (원래 80GB 이상). 커뮤니티에서 24GB 미만으로 실행할 수 있도록 아키텍처를 조정하기도 했으나, 그러한 극한의 메모리 최적화가 이 리포지토리 (repository)에는 아직 완전히 구현되지 않았습니다.

BiRefNet (선택 사항): 경량화된 AlphaHint 생성기 옵션입니다.

GVM과 VideoMaMa는 모델 파일 크기가 매우 크고 하드웨어 요구 사항이 극심하기 때문에, 해당 모듈들의 설치는 완전히 선택 사항입니다. 여러분의 편집 프로그램, BiRefNet 또는 기타 방법을 통해 생성된 자체 Alpha Hint를 언제든지 제공할 수 있습니다. AlphaHint가 더 좋을수록 결과물도 더 좋아집니다.

이 프로젝트는 Python 및 모든 종속성 (dependencies)을 관리하기 위해 uv를 사용합니다. uv는 Python 버전, 가상 환경 (virtual environments), 패키지 설치를 한 번에 자동으로 처리하는 pip의 빠르고 현대적인 대체제입니다. Python을 직접 설치할 필요는 없습니다 — uv가 대신 해줍니다.

Windows 사용자용 (자동화):

• 이 리포지토리를 로컬 머신으로 클론 (Clone)하거나 다운로드하세요.
• Install_CorridorKey_Windows.bat 파일을 더블 클릭하세요.

이 과정은 자동으로 uv (필요한 경우)를 설치하고, Python 환경을 설정하며, 모든 종속성 (Dependencies)을 설치하고, CorridorKey 모델을 다운로드합니다. 참고: uv를 처음 설치하는 경우, 이미 열려 있는 터미널 창에서는 이를 인식하지 못할 수 있습니다. 설치 스크립트가 현재 창은 자동으로 처리하지만, 새 터미널을 열었을 때 "'uv' is not recognized" 오류가 발생하면 해당 터미널을 닫고 다시 여세요. - (선택 사항) Install_GVM_Windows.bat 및 Install_VideoMaMa_Windows.bat를 더블 클릭하여 용량이 큰 선택 사항인 Alpha Hint 생성기 가중치 (Weights)를 다운로드하세요.

Linux / Mac 사용자용 (자동화):

• 이 리포지토리 (Repository)를 로컬 머신으로 클론 (Clone)하거나 다운로드하세요.
• 터미널을 열고 bash를 입력하세요. bash를 입력한 후 한 칸 띄어쓰기를 하세요. - Install_CorridorKey_Linux_Mac.sh 파일을 터미널로 드래그 앤 드롭 (Drag and drop)하세요. 그런 다음 엔터를 누르세요. - (선택 사항) 2단계를 다시 수행하세요. 하지만 이번에는 용량이 큰 선택 사항인 Alpha Hint 생성기 가중치를 다운로드하기 위해 Install_GVM_Linux_Mac.sh 및 Install_VideoMaMa_Linux_Mac.sh를 드래그 앤 드롭하세요.

Linux / Mac 사용자용 (수동):

• 이 리포지토리를 로컬 머신으로 클론 (Clone)하거나 다운로드하세요.

• uv가 설치되어 있지 않다면 설치하세요:
  curl -LsSf https://astral.sh/uv/install.sh | sh

• 모든 종속성 (Dependencies)을 설치하세요 (필요한 경우 uv가 Python 3.10+를 자동으로 다운로드합니다):
  uv sync # CPU/MPS (기본값 — 모든 곳에서 작동)
  uv sync --extra cuda # CUDA GPU 가속 (Linux/Windows)
  uv sync --extra mlx # Apple Silicon MLX 가속

AMD ROCm 설정은 아래의 AMD ROCm Setup 섹션을 참조하세요. 모델 다운로드:
CorridorKey v1.0 모델 (~300MB):
첫 실행 시 자동으로 다운로드됩니다. CorridorKeyModule/checkpoints/에서 체크포인트 (Checkpoint)를 찾을 수 없는 경우, 엔진이 CorridorKey의 HuggingFace에서 이를 가져와 CorridorKey_v1.0.safetensors로 저장합니다 (권장 사항 — 더 안전하며 pickle을 사용하지 않음). 레거시(Legacy) .pth

파일이 이미 존재한다면 자동으로 로드됩니다. 수동 다운로드는 필요하지 않습니다.

CorridorKeyBlue 1.0 모델 (~300MB):
전용 블루 스크린 (blue-screen) 체크포인트입니다. --screen-color blue 옵션으로 처음 실행할 때 (또는 자동 감지가 블루 스크린을 선택했을 때) CorridorKeyBlue의 HuggingFace로부터 요청 시 다운로드되며, CorridorKeyBlue_1.0.safetensors로 저장됩니다. 두 모델은 checkpoints/ 디렉토리에 공존하며, 클립에 따라 자동으로 선택됩니다.

GVM 가중치 (Optional):
HuggingFace: geyongtao/gvm

• CLI를 사용하여 다운로드:
  uv run hf download geyongtao/gvm --local-dir gvm_core/weights

VideoMaMa 가중치 (Optional):
HuggingFace: SammyLim/VideoMaMa

• VideoMaMa 파인튜닝 (fine-tuned) 가중치를 다운로드합니다:
  uv run hf download SammyLim/VideoMaMa --local-dir VideoMaMaInferenceModule/checkpoints/VideoMaMa

• VideoMaMa는 Stable Video Diffusion 베이스 모델 (VAE + 이미지 인코더만 필요, ~2.5GB)도 필요로 합니다. stabilityai/stable-video-diffusion-img2vid-xt 에서 라이선스에 동의한 후, 다음을 실행하세요:
  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"

• VideoMaMa는 놀라운 프로젝트입니다. 그들의 리포지토리에 Star를 눌러 지지를 보내주세요!

• VideoMaMa 파인튜닝 (fine-tuned) 가중치를 다운로드합니다:

CorridorKey는 프레임을 처리하기 위해 두 가지 입력이 필요합니다:

원본 RGB 이미지: 처리할 그린 스크린 또는 블루 스크린 푸티지입니다. 이는 sRGB 색역 (REC709 색역과 교체 가능)이 필요하며, 엔진은 sRGB 감마 (gamma) 또는 리니어 감마 (Linear gamma) 커브를 모두 수용할 수 있습니다.

거친 알파 힌트 (Coarse Alpha Hint): 일반적으로 피사체를 분리하는 대략적인 흑백 마스크입니다. 이는 정밀할 필요가 없습니다. 거친 크로마 키 (chroma key) 또는 AI 로토 (AI roto)를 통해 직접 생성할 수 있습니다.

기본적으로 스크린 색상은 첫 번째 프레임의 배경 픽셀(알파 힌트가 어두운 부분)에서 자동 감지됩니다. --screen-color green 또는 --screen-color blue를 전달할 수 있습니다.

감지를 건너뛰고 특정 체크포인트 (checkpoint)를 강제하려면 사용합니다.

저는 AlphaHint를 생성하기 위해 GVM 또는 VideoMaMa를 사용하는 것이 가장 좋은 결과를 얻었기에, 해당 프로젝트들을 재패키징하여 clip_manager.py 내부의 선택적 모듈 (optional modules)로 통합했습니다. 다음은 각 방식의 비교입니다:

GVM: 완전히 자동이며 추가 입력이 필요하지 않습니다. 사람에게는 매우 잘 작동하지만, 무생물 (inanimate objects)에는 어려움을 겪을 수 있습니다.

VideoMaMa: 키잉 (keying)하고자 하는 대상을 알려주는 대략적인 VideoMamaMaskHint (종종 수동 또는 AI로 그려짐)를 제공해야 합니다. 이 방식을 사용하기로 선택했다면, 위저드 (wizard)가 샷 (shot)을 위해 생성한 VideoMamaMaskHint/ 폴더에 마스크 힌트 (mask hint)를 넣어주세요. VideoMaMa의 결과는 환상적이며, 이 마스크 힌트 덕분에 GVM보다 더 쉽게 제어할 수 있습니다.

이 프로젝트들의 제작자들에게 애정을 표현하고 리포지토리 (repos)에 스타 (star)를 눌러주세요. VideoMaMa 및 GVM

아마도 미래에는 AlphaHint를 위한 다른 생성기 (generators)들을 구현할 수도 있습니다! 그전까지는 Alpha Hint가 더 좋을수록 CorridorKey의 최종 결과물도 더 좋아질 것입니다. 마스크 침식 (mask erosion)이나 페더링 (feathering)의 양을 다양하게 실험해 보세요. 이 모델은 거칠고, 흐릿하며, 침식된 마스크로 학습되었으며, 힌트로부터 세부 사항을 채워 넣는 능력이 탁월합니다. 하지만 Alpha Hint가 너무 과하게 확장된 경우, 원치 않는 마스크 세부 사항을 제거하는 데에는 일반적으로 효과가 떨어집니다.

피드백을 주시고 여러분의 결과를 공유해 주세요!

의존성 (dependencies)을 로컬에 설치하고 싶지 않다면, Docker에서 CorridorKey를 실행할 수 있습니다.

전제 조건 (Prerequisites):

• Docker Engine + Docker Compose 플러그인이 설치되어 있어야 합니다.

• 호스트 (Linux)에 NVIDIA 드라이버가 설치되어 있어야 하며, 이 프로젝트에서 사용하는 PyTorch CUDA 12.6 휠 (wheels)과 CUDA 호환성이 있어야 합니다.

• NVIDIA Container Toolkit이 설치되어 Docker에 구성되어 있어야 합니다 (nvidia-smi가 호스트에서 작동해야 하며, docker run --rm --gpus all nvidia/cuda:12.6.3-runtime-ubuntu22.04 nvidia-smi 명령이 성공해야 합니다).

• 이미지 빌드: docker build -t corridorkey:latest .

• 액션을 직접 실행 (예시: 추론 (inference)):
  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" \ -v "$(pwd)/gvm_core/weights:/app/gvm_core/weights" \ -v "$(pwd)/VideoMaMaInferenceModule/checkpoints:/app/VideoMaMaInferenceModule/checkpoints" \ corridorkey:latest run_inference --device cuda

• Docker Compose (반복 실행 시 권장):
  docker compose build
  docker compose --profile gpu run --rm corridorkey run_inference --device cuda
  docker compose --profile gpu run --rm corridorkey list
  docker compose --profile cpu run --rm corridorkey-cpu run_inference --device cpu

• 선택 사항: 멀티 GPU 워크스테이션을 위해 특정 GPU(들)에 고정:
  NVIDIA_VISIBLE_DEVICES=0 docker compose --profile gpu run --rm corridorkey list
  NVIDIA_VISIBLE_DEVICES=1,2 docker compose --profile gpu run --rm corridorkey run_inference --device cuda

참고 사항: