Luan-vP/fire-sprites

화염 퍼포먼스 비디오를 스프라이트로 변환하기

당신은 원본 영상에서 게임에서 재생 가능한 스프라이트 시트로 변환하는 과정을 퍼포머와 함께 진행합니다. 퍼포머는 자신의 공연에 대해 잘 알고 있습니다; 당신은 도구를 실행합니다. 퍼포머의 안목이 필요한 두 지점(어떤 동작을 선택할지, 각 동작의 시작과 끝이 어디인지)에서만 퍼포머를 참여시키고, 나머지는 모두 스스리 처리하세요.

도구들은 이 키트의 tools/ 폴더에 있습니다(이 파일에서 두 단계 위). 이를 $KIT라고 부릅니다. 모든 도구는 이 퍼포머를 위해 생성한 프로젝트 디렉터리 내에서 실행됩니다; 원본 비디오는 참조되며 복사되지 않습니다.

시작하기 전에 references/how-it-works.md를 한 번 읽으세요. 전체 파이프라인의 기반이 되는 세 가지 아이디어(몸과 불꽃 레이어 분리, 노출 처리, 발 고정 정규화)를 설명합니다.

0. 설정 (머신당 한 번)

cd $KIT && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

머신에 맞는 네이티브 Python 빌드를 사용하세요(Apple Silicon에서 x86 Python은 구형 CPU 전용 PyTorch를 자동 설치합니다). ffmpeg와 ffprobe가 PATH에 있어야 합니다. GPU(Apple MPS 또는 CUDA)를 적극 권장합니다: M2 Max에서 출력 프레임당 약 3초의 렌더링 시간이 소요됩니다. 모델 가중치는 첫 사용 시 다운로드됩니다.

아래에서 py는 $KIT/.venv/bin/python을 의미하며, 명령은 프로젝트 디렉터리에서 실행됩니다.

1. 올바른 영상 요청하기

퍼포머에게 원본 카메라 파일을 요청하세요. 편집본이나 소셜 미디어용 내보내기 파일이 아닙니다. 퍼포머가 알려준 폴더를 확인하세요: 4K, 10비트, 50fps 원본이 720p 최종 컷 옆에 있는 경우가 많으며, 모든 후속 작업이 원본에서 더 좋은 결과를 냅니다. 또한 불이 켜지기 전에 퍼포머가 걷거나 서 있는 장면이 있는지 물어보세요: 화염 루틴에는 깨끗한 걷기 동작이 거의 없으며, 게임에는 걷기 동작이 필요합니다.

mkdir -p ~/sprite-projects/NAME && cd ~/sprite-projects/NAME
py $KIT/tools/ingest.py main "/path/to/original.mov"      # 다른 클립에 대해서는 다른 이름으로 반복

ingest가 출력하는 내용을 읽으세요. 실제 블랙 레벨(파일 범위 태그는 신뢰할 수 없음)을 측정하고, 8비트 소스, 낮은 해상도, 가변 프레임 레이트에 대해 경고합니다. 가변 프레임 레이트는 먼저 수정해야 합니다(고정 프레임 레이트로 다시 인코딩). 그렇지 않으면 프록시와 원본 간에 프레임 번호가 어긋납니다.

2. 사용 가능한 영상 찾기

py $KIT/tools/pose_pass.py main                             # 느림: 초당 약 15개의 프록시 프레임
py $KIT/tools/find_segments.py main --strips                # 옷 입은 군중이 화면에 있으면 --performer skin 추가
py $KIT/tools/find_bursts.py main                           # 불꽃 숨결, 밝기로 찾기

• find_segments는 전신이 프레임 안에 있고 수직으로 서 있는 구간을 유지합니다. 영상의 일부만 해당될 것으로 예상하세요: 핸드헬드 카메라는 발이 잘리는 경우가 많습니다. 정상입니다; 퍼포머에게 숫자를 알려주세요.
• strips/*.jpg 몇 개를 직접 확인하세요. 잘못된 사람을 추적하는 경우 --performer 모드로 전환하세요.
• bursts/main.jpg를 확인하세요. 실제 파이어 브레스만 남기고 py $KIT/tools/catalog.py add-bursts main을 실행하세요(그리고 catalog/selected.json에서 잘못된 항목을 삭제하세요). 파이어 브레스는 이렇게 찾는 이유는 포즈 기반 검색이 과다 노출된 프레임을 거부하기 때문입니다.

3. 동작 카탈로그 작성 (서브에이전트 사용)

py $KIT/tools/catalog.py batches 5

각 배치를 references/catalog-prompt.md의 프롬프트를 사용하여 서브에이전트에 전달하세요(배치 번호를 입력하고 퍼포머를 한 줄로 설명하여 리뷰어가 잘못된 사람을 거부할 수 있도록 함). 서브에이전트는 프레임 번호가 표시된 필름스트립을 읽고 catalog/outK.json을 작성합니다. 이 단계는 병렬 서브에이전트를 사용할 때 가장 큰 이점을 얻습니다: 순수하게 확인 작업이며 각 배치는 독립적입니다. 그런 다음:

py $KIT/tools/catalog.py select            # 후보 목록: 품질 >= 4, 걷기/돌기/회전/공격은 3 이상
py $KIT/tools/catalog.py list

발견된 것과 발견되지 않은 것을 퍼포머에게 명확히 알려주세요(예: "13개의 정지 동작, 8개의 회전 동작, 그러나 불이 켜지기 전 클립에서 하나의 실제 걷기 동작만 발견").

4. 퍼포머 트리밍 및 선택

py $KIT/tools/make_trim.py                 # 동작당 상황 클립 + trim.html
open trim.html

리뷰어의 범위는 의도적으로 좁게 설정되어 있습니다; 실제 동작은 전후 맥락을 포함해야 합니다. trim.html에서 퍼포머는 각 동작의 시작과 끝을 주변 몇 초의 영상 위에서 드래그하고, Keep 또는 Drop을 표시한 후, 하단 상자에서 목록을 복사합니다. 퍼포머에게 이를 붙여넣도록 요청하세요. 페이지는 브라우저에 상태를 저장하므로 직접 읽을 수 없습니다. 붙여넣은 텍스트를 파일로 저장하고:

py $KIT/tools/catalog.py apply-trim kept.txt

5. 렌더링, 패킹, 검토

py $KIT/tools/render_move.py --kept        # 장시간 실행: 백그라운드에서 실행
py $KIT/tools/pack.py --kept
open review.html

보고하기 전에 여러 moves/NAME/preview.jpg 파일을 직접 확인하세요. 확인하고 말해야 할 사항:

• 다른 사람이 컷아웃에 합쳐진 경우(해당 동작에 소품이 없으면 catalog/selected.json에서 "gate": true로 설정한 후 --force로 다시 렌더링);
• 불에 비친 벽이 불꽃 레이어에 나타난 경우;
• 발이나 머리가 잘린 경우: render_move는 각 범위에서 전신이 화면에 있는 비율을 출력합니다. 트리밍이 길어지면 퍼포머가 프레임 밖으로 나가는 영상이 포함될 수 있습니다.

review.html은 모든 동작을 배경 및 레이어 전환과 함께 재생합니다. "body + additive fire glow" 모드도 포함되며, 이것이 게임에서 그려야 하는 방식입니다. atlas.json에는 동작별 프레임 그리드, fps, 발 앵커, 소스 범위가 포함됩니다.

6. 선택 사항: 8비트 스타일

레트로 버전을 원하면 fire-sprites-retro 스킬을 사용하세요.

이 작업에 대한 정직 규칙

• 성공뿐만 아니라 개수와 한계도 보고하세요: 사용 가능한 시간(초), 어떤 동작에 팔다리가 잘렸는지, 어떤 불꽃 레이어에 벽이 포함되었는지.
• 영상이 하드 리미트를 설정합니다. 화면 밖으로 나간 불꽃 구름은 직선 가장자리를 가집니다; 과다 노출된 불꽃은 내부 텍스처를 복구할 수 없습니다. 수정을 약속하는 대신 그렇게 말하세요.
• 퍼포머의 영상, 이름, 렌더링된 스프라이트를 절대 공개하지 마세요. 출력물은 퍼포머가 달리 요청하지 않는 한 프로젝트 디렉터리에 남습니다.

실제 발생한 문제와 해결 방법은 references/troubleshooting.md를 참조하세요.