Setup

기준 실행 환경: Windows PC 1대, 웹캠 2대

# 저장소 클론
git clone https://github.com/37g55555/Unity-HandTracking.git
cd Unity-HandTracking
# Conda 가상환경 생성
conda env create -f environment.yml
conda activate artifact

Project Structure

Unity-HandTracking
├─ UnityProject
│  ├─ Assets
│  │  ├─ Scenes
│  │  │  ├─ Main.unity
│  │  │  └─ hologramOut.unity
│  │  └─ Scripts
│  ├─ Packages
│  └─ ProjectSettings
├─ python
│  ├─ ShadowMesh.py
│  ├─ MediaPipeTracking.py
│  └─ MediaPipe.task
├─ sf3d
│  ├─ app.py
│  ├─ sf3d
│  ├─ texture_baker
│  └─ uv_unwrapper
└─ output
   ├─ shadowmesh
   ├─ sf3d
   └─ recordings

output\sf3d, output\recordings 폴더는 실행 시 자동으로 생성된다.

Unity 프로젝트 열기

Unity Hub에서 UnityProject 폴더를 프로젝트로 연다.

모델 파일 확인

SF3D와 ControlNet 모델은 sf3d/app.py 실행 중 Hugging Face/diffusers를 통해 로드된다. 필요한 모델 접근 권한이나 Hugging Face 로그인이 필요한 경우, 먼저 해당 가상환경에서 인증을 마쳐야 한다.

Execution Flow

1. 웹캠 2대를 PC에 연결
2. conda activate artifact로 가상환경을 활성화
3. Unity에서 UnityProject/Assets/Scenes/Main.unity를 열기
4. Inspector 경로가 현재 PC 경로와 맞는지 확인
5. Unity Play를 실행

Scripts Overview

Unity Scripts

Python Scripts

Unity Inspector Settings

현재 기본 경로는 아래 로컬 경로를 기준으로 한다.

D:\Unity-HandTracking

다른 PC나 다른 폴더에서 실행할 경우 아래 경로 값을 실제 설치 경로에 맞게 수정해야 한다.

Main.unity

PipelineManager

captureArguments를 아래처럼 바꾸면 웹캠 캡처 없이 기존 shadow mesh 파일을 사용한다.

--mode file

ShadowMeshFileLoader

hologramOut.unity

HologramModelRecorder

Pipeline States

상태는 GameStateManager.PipelineState에서 관리한다.

Outputs

ShadowMesh 출력

위치:

output\shadowmesh

SF3D 출력

위치:

output\sf3d

Hologram Recording 출력

위치:

output\recordings

Troubleshooting

웹캠이 열리지 않을 때

• 웹캠 2대가 모두 연결되어 있는지 확인한다.
• 다른 프로그램이 웹캠을 사용 중인지 확인한다.
• ShadowMesh용 카메라 번호: captureArguments의 --camera 0
• MediaPipe용 카메라 번호: handTrackingArguments의 --camera 1
• 두 카메라가 반대로 잡히면 두 값을 서로 바꾼다.

예:

captureArguments: --mode live --camera 1
handTrackingArguments: --camera 0

SF3D 서버가 안 켜질 때

• conda activate artifact가 되어 있는지 확인한다.
• Hugging Face 모델 접근 권한이 필요한 경우 해당 환경에서 먼저 로그인한다.

GLB가 안 생성될 때

• output\sf3d 폴더가 생성되는지 확인한다.
• SF3D 서버 콘솔에서 texture/model generation 오류가 없는지 확인한다.
• Unity Console에서 SF3DGenerationClient 경고를 확인한다.

Git Ignore / Generated Files

아래 파일과 폴더는 실행 중 생성되는 산출물이므로 git에 올리지 않도록 한다.

UnityProject/Library/
UnityProject/Temp/
UnityProject/Logs/
UnityProject/UserSettings/
UnityProject/obj/
UnityProject/.vs/
UnityProject/.vsconfig
UnityProject/*.csproj
UnityProject/*.sln
output/sf3d/
output/recordings/
__pycache__/
*.pyc

Unity 프로젝트를 열면 .csproj, .sln, Library, Temp 등은 다시 생성됨