mingle/streamingle-unity-utilities
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
streamingle-unity-utilities/CameraAI~/README.md

9.2 KiB
Raw Blame History

Mingle Camera Work AI Unity Package

생성할 새 Unity Timeline에서 캐릭터 모션과 원본 음원을 60 FPS로 추출하고, 완전히 새로 만든 카메라를 비파괴 프리뷰 Timeline으로 불러옵니다. 생성 입력에 Cinemachine Track이나 기존 카메라 애니메이션은 필요하지 않으며, 존재해도 생성 입력으로 사용하지 않습니다. 축적된 작업자 데이터를 재구성하는 고품질 생성 엔진은 CWCameraWorker.exe로 실행됩니다. 워커에 Python 런타임과 라이브러리가 포함되므로 작업 PC에 Python을 별도로 설치하지 않아도 됩니다. 동일한 구간과 음원으로 후보 A/B를 녹화하고 Camera AI Review Portal에 반입할 provenance manifest도 생성합니다.

설치와 씬 요구사항은 저장소의 docs/UNITY_COLLECTION.md를 참고하세요. 워커 빌드와 배포 검증은 docs/CLI_WORKER_PACKAGING.md에 정리되어 있습니다.

Unity Package Manager의 Add package from git URL에는 다음 주소를 사용할 수 있습니다.

https://kindnick-git.duckdns.org/mingle/streamingle-unity-utilities.git?path=/CameraAI~#v0.1.16

배포 패키지에는 Windows x64용 CWCameraWorker 폴더 전체가 포함됩니다. Python은 따로 설치하지 않아도 되지만, Git 패키지의 대용량 바이너리를 받으려면 Unity를 열기 전에 Git과 Git LFS를 설치해야 합니다. Worker는 단일 파일 EXE가 아니므로 CWCameraWorker.exe와 같은 폴더의 _internal 내용을 함께 유지해야 합니다.

카메라 생성에 필요한 준비된 참조 카메라·모션 데이터와 컷 모델은 패키지의 읽기 전용 RuntimeData~에 포함됩니다. 별도의 CW-AI 체크아웃은 필요하지 않습니다. 더 최신의 권한 제어 데이터가 있다면 CWAI_ROOT 환경 변수, Unity 프로젝트 옆의 CW-AI 폴더 또는 생성 창의 고급 · 진단 > 참조 데이터 루트에서 선택적으로 덮어쓸 수 있습니다. 상세 설치 절차는 Documentation~/EXTERNAL_INSTALLATION.md를 참고하세요. 참조 데이터는 읽기 전용이어도 됩니다. 반복 생성 캐시는 기본적으로 현재 Unity 프로젝트의 Library/CWAI에 저장되며, 필요하면 CWAI_CACHE_ROOT 환경 변수로 별도의 쓰기 가능한 위치를 지정할 수 있습니다.

메뉴:

  • Tools/Streamingle/AI 카메라 생성
  • Tools/Streamingle/Timeline/Export Camera Dataset (60 FPS)
  • Tools/Streamingle/Timeline/Create AI Camera Preview
  • Tools/Streamingle/Timeline/Remove AI Camera Preview
  • Tools/Streamingle/Timeline/Render AI Camera A-B

카메라 생성

일반 작업자는 다음 세 단계만 사용하면 됩니다.

  1. Tools > Streamingle > AI 카메라 생성을 엽니다.
  2. 모션 트랙과 Audio Track만 들어 있는 원본 Timeline을 선택하고 새 카메라 생성하기를 누릅니다. 입력 추출, 새 카메라 생성과 Timeline 반영이 자동으로 이어집니다. 실행 중에는 현재 단계, 경과 시간과 예상 남은 시간 범위가 표시됩니다.
  3. 결과를 확인한 뒤 Timeline의 생성 카메라 clip 또는 Hierarchy의 카메라를 선택하고 필요하면 선택한 카메라만 다시 생성 또는 완성본 씬으로 저장을 누릅니다.

Timeline이 하나뿐이면 자동으로 선택됩니다. 특별한 연출 의도가 없다면 연출 설정 (선택)도 열 필요가 없습니다. 샷 거리, 움직임, 인물 구도와 강도를 직접 지정하려는 경우에만 펼칩니다.

경로, 워커 실행 파일, 내부 입력 ID, Seed, 캐시, 수동 가져오기와 로그는 고급 설정 및 관리 안에 있습니다. 기본 생성에서는 입력할 필요가 없습니다.

기본 화면에는 데이터셋 곡을 고르는 절차가 없습니다. 여기서 “입력”은 지금 선택한 새 Timeline 한 개이고, 고품질 워커가 내부적으로 참고하는 누적 작업자 카메라 데이터는 별도의 참조 라이브러리입니다. 새 Timeline을 그 라이브러리 안의 기존 곡과 연결하거나 기존 카메라를 정답으로 제공할 필요가 없습니다.

배포된 워커는 다음 명령을 제공합니다. Unity 생성 창은 generate와 prepare-cache를 호출하고, 설치·배포 확인에는 version과 doctor를 사용합니다.

CWCameraWorker.exe version --json
CWCameraWorker.exe doctor
CWCameraWorker.exe prepare-cache --help
CWCameraWorker.exe generate --help

version --json은 워커의 CLI 계약 버전을 확인하고, doctor는 배포 파일과 필수 데이터 경로를 진단합니다. prepare-cache는 반복 생성용 준비 캐시를 구성하며, generate는 전체 생성과 선택 샷 재생성을 처리합니다.

전체 결과는 카메라별 CinemachineCamera, Animator, Animation Track과 .anim으로 1:1 분리됩니다. 각 카메라의 Transform/Track Offset과 커브를 다른 샷에 영향을 주지 않고 조정할 수 있습니다. 선택 샷 재생성은 기존 clip GUID와 컷 경계를 유지하고 나머지 샷을 보존합니다. Balanced 또는 Editable 키 단순화를 선택하면 위치·Quaternion·렌즈 오차 한도 안에서 키가 축약됩니다.

예상 시간은 Timeline 길이와 준비·후보 캐시 상태를 기준으로 범위로 표시합니다. 같은 PC에서 완료된 전체 생성과 선택 샷 생성 시간을 별도로 누적해 이후 예측을 보정합니다. 준비 캐시 생성 시간은 실제 카메라 생성 기록에 섞지 않습니다.

처음 실행하는 PC에서는 고품질 생성 준비 캐시 만들기 / 갱신을 한 번 실행합니다. 준비 모델 seed와 후보 seed는 분리되어 있으므로 이후 선택 샷 재생성에서 seed가 바뀌어도 같은 무결성 검증 캐시를 재사용합니다.

Seed는 안전 검사를 통과하고 최종 화면에서 서로 구별되는 카메라 후보 중 하나를 결정론적으로 선택합니다. 같은 Seed와 입력은 같은 결과를 재현하며, 안전한 구별 후보가 둘 이상이면 인접 Seed는 다른 후보를 선택합니다. 후보는 최고 안전 후보와의 선택 점수 차이가 허용 범위 안인 경우에만 사용되어, 다양성을 위해 구도 품질을 과도하게 낮추지 않습니다. 다음 샷의 계획 문맥은 최고 안전 후보로 고정되므로, 앞 샷에서 Seed로 고른 후보가 뒤 샷의 후보 풀을 바꾸어 다시 같은 카메라로 수렴하지 않습니다. 명시한 static 연출은 유지되고, 안전한 구별 후보가 하나뿐인 샷은 Seed를 바꿔도 같을 수 있습니다. 기존 결과를 다시 적용하는 기능은 새 후보를 생성하지 않으므로 Seed를 사용하지 않습니다.

metadata.json의 샷별 variationSeed, variationPoolSize, variationIndex, variationApplied, variationQualityEligibleCandidateCount, variationSelectedScoreDeltaFromBest, sequenceContinuationPolicy와 전체 요약 seedVariationPolicy, seedVariationAppliedShotCount, seedVariationPoolSizeMinMedianMax로 Seed가 실제로 적용된 범위와 후보 풀이 하나뿐이었던 예외를 확인할 수 있습니다.

생성된 회전은 AnimationClip에 굽고 런타임 LookAt이나 Tracking Target을 사용하지 않습니다. 캐릭터 관절 envelope와 의미 기반 구도를 검증하며, 안전한 후보가 없으면 결과 생성을 중단합니다. 사용자가 static 또는 움직임 강도 0을 명시했을 때는 정지 의도를 유지합니다.

가져오기, 제거, 전체/선택 샷 재생성은 모두 같은 원본 Director scope만 사용합니다. 씬에 사용할 수 있는 Timeline Director가 하나뿐이면 자동으로 선택됩니다.

현재 씬을 AI Camera Final 복사본으로 저장은 preview Timeline과 생성된 .anim 파일을 Final 전용 asset 폴더로 복제하고, 복사된 씬이 그 복제본을 참조하게 합니다. 따라서 이후 작업 씬에서 preview를 제거하거나 재생성해도 Final 씬의 참조가 끊기지 않습니다.

샷별 JSON 예시는 Samples~/CameraDirections/camera_directives.example.json 에 있습니다.

A/B 렌더

  1. 씬과 Timeline을 저장합니다.
  2. 두 생성 결과 디렉터리의 metadata.json, world_camera.f32, time.f64, 선택적인 shots.json이 완전한지 확인합니다.
  3. A/B 렌더 창에서 두 디렉터리와 [startFrame, endFrameExclusive) 구간을 선택합니다.
  4. 렌더러는 두 후보의 sample rate, frame count, time.f64, song ID, evaluation group, aspect ratio가 같은지 먼저 검증합니다.
  5. 후보마다 원본 씬을 다시 열고 Preview Timeline을 만든 뒤, 기존 RecorderTrack은 mute하고 MainCamera와 Timeline audio를 녹화합니다.
  6. 완료 폴더의 manifest.json과 두 영상을 웹 포털에 함께 반입합니다.

작업 상태는 Library/CWAI/ABRender/active_job.json에 저장되어 Play Mode domain reload 뒤에도 이어집니다. 실패·취소 시 원본 scene setup을 복구하며, 원본 Timeline과 생성 카메라 파일은 수정하지 않습니다.

UniCLI 공개 진입점:

  • AICameraABRenderRunner.StartABRenderForCli(...)
  • AICameraABRenderRunner.GetABRenderStatusForCli(jobId)
  • AICameraABRenderRunner.CancelABRenderForCli(jobId)