1. 개요
StreamRoger는 Orbbec Femto Bolt(RGB-D) 4대를 4대의 PC에 분산 배치해 실시간 바디트래킹과 Depth Occlusion 합성을 수행하는 AR 무대 시스템의 코드명입니다.
- 용도 ① — 오페라 「고양이 마에스트로 에다」(ARKO 공연예술창작산실 2027 올해의 신작 후보) 무대기술: Depth Occlusion + 실시간 아바타(고양이 리타겟)
- 용도 ② — 보쎄스A&T 재도전성공패키지 아이템: 글래스리스 라이브 AR 플랫폼
자매 프로젝트 XR_Maestro(F:\XR_Maestro)와 워커·NDI·WinRM 분산 인프라를 공유합니다.
SSOT 원칙 — 시스템 스펙·역할의 단일 진실 원천은 repo 내부 파일입니다: pc_sync/config/roles.toml(네트워크·역할), CLAUDE.md/AGENTS.md(PC 프로파일·모듈·마일스톤), pc_sync/profiles/*.json.
2. 핵심 아키텍처
단일 소스 원칙
Femto Bolt + Azure Kinect Body Tracking SDK(K4ABT) 조합으로 Depth와 스켈레톤이 동일 좌표계에서 나옵니다. 이것이 오클루전 정합의 핵심입니다.
듀얼 페이즈
- Phase A — 사전 무대 3D 스캔 (StageScanner → 정적 메시)
- Phase B — 공연 실시간 스켈레톤 트래킹 + 아바타 합성
운용 모드 3종
| 모드 | 구성 | 용도 |
|---|
| Mode1 | K4ABT Full + 실시간 Depth Mesh 오클루전 | 리허설 |
| Mode2 | Mode1 + 외부 모캅 연동 | 고품질 폴백 (미구현) |
| Mode3 | 정적 메시 오클루전 | 공연 권장 |
마일스톤 현황
| 단계 | 내용 | 상태 |
|---|
| M1 | Depth 스트림·메시 | 완료 |
| M2 | Body Tracking·아바타 | 완료 |
| M3 | 오클루전 합성 | 완료 |
| M4 | 깊이 보정·안정화 (DepthSmoothing.compute 5커널) | 구현 완료 튜닝·현장검증 남음 |
| M5 | 핸드 제스처 | 미착수 (우선순위 낮음) |
| M6 | 연출 시스템·송출 (NDI 코드만, 연출 UI 없음) | 부분 |
| M7 | 장면 프리셋 | 완료 |
3. 4PC 분산 구성
| PC | 이더넷 IP (폐쇄망) | 담당 카메라 | GPU | 상태 (07-17) |
|---|
| Main (VOCES) | 192.168.1.100 (Wi-Fi .50 = 인터넷) | Femto A (로컬) | RTX 4070 Ti SUPER 16GB | 정상 |
| Worker1 | 192.168.1.11 | Femto B (우전방) | RTX 4060 Laptop 8GB | 정상 (64ef462 pull 완료) |
| Worker2 | 192.168.1.12 | Femto C (좌후방) | RTX 4060 Laptop 8GB | 다운 IP 탈취 |
| Worker3 | 192.168.1.13 | Femto D (우후방) | RTX 4060 Laptop 8GB | 다운 WoL 무반응 |
- 네트워크: 폐쇄망 스위치 ipTime H8008S2 (GbE, CAT6). KinectNetServer = UDP 11000 + TCP 11000~11010
- 센서 동기화: 현재 전 센서 STANDALONE 운용 (2026-06-23 결정). Sync Hub 하드웨어 동기는 공연 화질 필요 시 복구
- 워커 원격제어: WinRM (
_tools/WorkerCtl.psm1, 자격증명 ~/.winrm_admin.cred) + Parsec(GUI)
근본 문제 — 인터넷 공유기와 폐쇄망이 동일 192.168.1.0/24 대역을 공유 중이라 워커 IP가 타 기기에 탈취되는 사고가 반복됩니다. 항구 해결책은 Stage2(폐쇄망 대역 분리). 폐쇄망에 라우터·인터넷 결선 금지.
4. 디렉토리 구조 (주요)
F:\DepthOcclusionAR\
├─ CLAUDE.md / AGENTS.md — 센서·GPU DLL 원칙, PC 프로파일, 모듈·마일스톤 (AGENTS.md는 로컬 미러)
├─ multicam_config.json — 4센서 등록(LOCAL + .11/.12/.13) + camPose 캘리브레이션
├─ Assets\
│ ├─ Scripts\HologramViewer\ — 핵심 런타임 코드 (아래 표)
│ ├─ Editor\ — 씬 빌더·셋업 자동화 (StreamRogerMainSetup, EdaHybrid*SceneSetup 등)
│ ├─ AzureKinectExamples\ — rfilkov K4A 에셋 (KinectManager·인터페이스·NetClient)
│ ├─ Red_Deer\ — Cartoon Cats 팩 (에다 고양이 아바타, URP 변환됨)
│ └─ *.unity — 씬 (§5)
├─ pc_sync\ — 4PC 동기화·운용 인프라
│ ├─ config\roles.toml — 4PC 네트워크·역할·방화벽 SSOT
│ ├─ scripts\ — PreFlight-Check·Start/Stop-StreamRoger·converge·bootstrap
│ ├─ profiles\*.json — PC별 프로파일
│ └─ messages\INBOX_*.md — PC 간 메시지
├─ 연구 보고서\ — 분산 바디트래킹 구현 가이드 v1.4, 하드웨어 결선 가이드
├─ docs\ — K4ABT 정확도 연구, 아바타 교체 가이드, 본 문서
└─ 공연현장_뎁스오클루전_운영_체크리스트.md — 본공연 T-60~T-0 체크리스트
핵심 런타임 코드 (Assets/Scripts/HologramViewer/)
| 파일 | 역할 |
|---|
KinectDepthOccluder.cs | Depth 기반 오클루전 코어 (DepthSmoothing.compute 파이프라인 연결) |
HologramViewerController.cs | 운용 모드 전환·합성 총괄 (Mode1/2/3, 뷰센서) |
UserBodyBlenderURP.cs / KinectBackgroundRenderer.cs | URP 합성·배경 렌더 |
EdaBodySelector.cs | 에다 배우 선택·락 (SoloLock: 시야 1인 자동 락) |
EdaAvatarDriver.cs | K4ABT → 휴머노이드 아바타 구동 (upperBodyOnly 토글 보유) |
ProceduralLegDriver.cs order 300 | 하체 절차적 보행 (walk/trot 게이트 + 2본 IK) |
GenericBoneBinder.cs order 400 | 섀도우 휴머노이드 → 고양이 Generic 리그 전사 |
SimpleSpringChain.cs order 450 | 꼬리·귀 스프링 체인 |
RetargetDebugVisualizer.cs order 500 | 스켈레톤 3계층 시각 디버거 (F1~F4) |
ViewSensorSwitcher.cs | 4뷰 카메라 전환 ([ ]) |
5. 씬 구성
| 씬 | 용도 | 비고 |
|---|
StreamRogerMain.unity | Main PC 운용 씬 — 스트리밍 수집·오클루전 스택 + 정적메시 파이프라인 | 에다 아바타 스택 없음 (씬 분열 — 통합 여부 결정 대기) |
DepthOcclusionAR.unity | 레거시 통합 씬 — 에다 아바타 스택(HVC·EdaAvatarDriver·EdaBodySelector) 보유 | 하이브리드 테스트 씬의 복제 원본 |
StreamRogerWorker.unity | 워커 PC 송출 씬 (KinectNetServer) | 워커 로컬 전용 |
MultiCameraSetup.unity | 다카메라 포즈 캘리브레이션 (R 강제보정) | worker3 4번째 캘리브레이션 미완 |
EdaHybridTest.unity | 상체 라이브/하체 절차적 하이브리드 검증 (단일 standalone) | 빌더: EdaHybridTestSceneSetup |
EdaHybridCatTest.unity | 4족 고양이 라이브 리타겟 검증 (현재 작업 씬) | 빌더: EdaHybridCatTestSceneSetup |
씬 재생성 원칙 — 하이브리드 테스트 씬은 수동 편집하지 말고 빌더 메뉴로 재생성합니다: Tools > DepthOcclusionAR > Hybrid > Create ... Test Scene... 체인은 DepthOcclusionAR.unity → EdaHybridTest → EdaHybridCatTest 순 복제이며, standalone 강제·DistributedTestManager 비활성·FullModel 설정이 빌더에 내장되어 있습니다.
6. 고양이 리타겟 테스트 (섀도우 휴머노이드 리그)
인간 배우의 고양이 흉내 연기를 퍼펫티어 없이 4족 고양이 아바타로 실시간 복제하는 파이프라인입니다.
데이터 흐름
Femto Bolt (K4ABT 스켈레톤)
→ EdaBodySelector (시야 1인 자동 락)
→ EdaAvatarDriver (상체 라이브, upperBodyOnly=true) [order 기본]
→ ProceduralLegDriver (하체 절차적 보행, 루트 속도 기반) [order 300]
→ ⟨비가시 섀도우 휴머노이드⟩
→ GenericBoneBinder (고양이 Generic 본으로 전사) [order 400]
· 야우 → 고양이 루트 이관 (rest 기준 잔차 분리)
· 척추 spine_02~05 누적 가중
· 사지: 위치 기반 2본 IK (바인드 절대화)
→ SimpleSpringChain (꼬리·귀) [order 450]
→ RetargetDebugVisualizer (시각 진단) [order 500]
Play 검증 키 바인딩
| 키 | 기능 | 소속 |
|---|
| T | 섀도우 휴머노이드 메시 표시/숨김 | GenericBoneBinder |
| R | 기준 재캡처 (배우 현재 위치·방향을 원점으로) | GenericBoneBinder |
| H | Hybrid ↔ Full-live 전환 | ProceduralLegDriver |
| P | 절차적 다리 on/off | ProceduralLegDriver |
| G + 화살표 | Mock root 이동 (카메라 없이 보행 검증) | ProceduralLegDriver |
| F1 | K4ABT 원시 스켈레톤 (초록=Tracked / 노랑=Inferred) | RetargetDebugVisualizer |
| F2 | 섀도우 리그 본 라인 (시안) | RetargetDebugVisualizer |
| F3 | 고양이 리그 본 라인 (주황) | RetargetDebugVisualizer |
| F4 | X-Ray (깊이 무시) on/off | RetargetDebugVisualizer |
HUD 배치
- 좌상단 — ProceduralLegDriver (하이브리드·보행 상태)
- 우상단 — GenericBoneBinder (본 발견 수·Tracked·yawDelta·게인)
- 좌하단 — RetargetDebugVisualizer (토글 상태 + 관절 신뢰도 집계)
검증 절차 요약
- 씬
EdaHybridCatTest 오픈 → ▶ Play → 우상단 HUD 「본 발견 26/26」 확인
- Console에
[K4ABT] Body tracker started + FullModel 로드 확인, NetClient 접속 에러가 없어야 정상
- 카메라 시야에 혼자 진입 → 자동 락 (Tracked: True) → 원하는 원점에서 R
- 걷기·회전·팔 뻗기·웅크리기·네발 기기(핵심) 테스트 — F1 스켈레톤으로 추적 붕괴 여부 관찰
- 진단법: F1이 무너지면 K4ABT 추적 문제 / F1 정상인데 고양이만 이상하면 전사(바인더) 문제
7. 운용 자동화 (pc_sync/scripts/)
| 스크립트 | 기능 |
|---|
PreFlight-Check.ps1 | 공연 전 점검 (네트워크·센서·서비스) |
Start-StreamRoger.ps1 | 전체 기동 + SHOW_MODE 마커 생성 (공연 중 converge git pull 차단) |
Stop-StreamRoger.ps1 | 전체 종료 + SHOW_MODE 해제 |
converge.ps1 | 평시 5분 주기 SSOT 수렴 (git pull·방화벽·NIC Private 자가치유) |
bootstrap.ps1 -Role Worker1/2/3 | 워커 셋업 자동화 |
- 워커 이상 시 1차 확인: converge 로그(
pc_sync/state/.local/*.log)와 python 설치 여부
pc_sync/PAUSE_AUTOPUSH 마커 존재 시 converge 자동 push 정지 (현재 활성 — 전 PC)- Main→워커 /32 영구 경로 필요 (Wi-Fi 누수 방지). 어댑터 재설정 시 증발 가능성 있음
8. 주의사항 · 반복 함정
| 함정 | 내용 · 대처 |
|---|
| K4ABT = CUDA 11 전용 | K4ABT 1.1.2는 CUDA 11 전용. Blackwell(RTX 5080+)은 DirectML 강제. ONNX Runtime 단독 교체 시 크래시 |
| Body Tracking SDK 설치 필수 | k4abt.dll이 C:\Program Files\Azure Kinect Body Tracking SDK\tools\에서 CUDA 공급자를 찾음. 프로젝트 내 DLL 복사만으로는 무효 → SDK 설치 + Unity 완전 재시작 |
| Plugins DLL 우선 로드 | Unity는 SDK/Kinect4AzureSDK/Plugins/의 native DLL을 프로젝트 루트보다 우선 로드 — CUDA DLL 12종은 Plugins 폴더에 |
| GPU 종속 DLL repo 금지 | CUDA/TensorRT/DirectML/ONNX DLL은 .gitignore — 각 머신 SDK에서 복사 |
| 강제종료 잔여물 | Unity 강제종료 후 Temp\UnityLockfile·__Backupscenes가 남아 재실행·배치를 차단. 삭제 후 재시작. 강제종료해도 프로세스가 좀비로 살아남을 수 있음 — 작업관리자에서 Unity.exe 확인 |
| DistributedTestManager 함정 07-17 발견 | Awake([DefaultExecutionOrder(-1000)])가 KinectManager.useMultiCamConfig를 강제로 켜서 multicam_config의 NetClient 3대를 부활시킴. enabled=false로는 Awake를 못 막음 → GameObject 자체를 비활성화. 워커 다운 상태에서는 연결 타임아웃 폭주로 에디터 프리즈 |
| 모든 센서 바디트래킹 필수 | 성능 위해 끄지 말 것 — 가림 상황 트래킹 유지 목적 |
| 신품 Femto Bolt | D:\orbbec_viewer\OrbbecViewer.exe 1회 실행 → .normalized 마커 확인 (펌웨어 timestamp stale 방지) |
| 재Play 시 센서 재오픈 | Stop 직후 재Play는 디바이스 미해제로 행 가능 — 몇 초 대기 후 Play, 세션당 Play 최소화 |
9. 현재 상태 (2026-07-17 밤 기준)
- Git: HEAD
64ef462 (섀도우 휴머노이드 리그) = origin/master 동기. 미커밋: 07-17 수정분(DTM 비활성·FullModel·시각 디버거·빌더) + Assets/Toon Golden Valley(사용자 임포트, 보류)
- 07-17 프리즈 사건 해결: 에디터 다운 2회의 원인 = DistributedTestManager의 NetClient 부활 + 죽은 워커 접속 폭주 → 씬 2개 GO 비활성화 + 빌더 재발 방지 + FullModel 전환 완료 (컴파일 검증 0 에러)
- 시각 디버거: RetargetDebugVisualizer 추가 — 씬 재생성(빌더 메뉴) 후 사용 가능
- 다음 액션: ① 고양이 리타겟 실기 Play 검증 (네발 자세 K4ABT 품질 핵심) ② worker2·3 복구 (물리 점검 + Stage2 대역 분리) ③ worker3 4번째 캘리브레이션 ④ M6 연출 UI 착수