emilianavt/OpenSeeFace

OpenSeeFace – 아바타 애니메이션을 위한 실시간 얼굴 랜드마크 추적기

개요 – OpenSeeFace는 웹캠이나 비디오 스트림에서 66개의 얼굴 랜드마크(및 시선과 눈 깜빡임 정보)를 감지하는 경량 크로스 플랫폼 라이브러리입니다. 핵심 모델은 MobileNetV3 기반 신경망을 ONNX로 내보낸 것이며, onnxruntime을 사용하여 CPU에서 빠르게 실행됩니다(단일 코어에서 30~60 fps). 이는 완전한 아바타 조종 앱이 아니며, 추적 데이터를 UDP로 스트리밍하여 다른 프로그램(Unity, Godot, VSeeFace, VTube Studio 등)이 3D/2D 아바타를 애니메이션화할 수 있도록 합니다.

중요성 – 실시간 아바타 조종에는 노이즈가 많은 조명, 낮은 해상도, 다양한 머리 자세에서도 작동하는 안정적이고 지연 시간이 짧은 얼굴 랜드마크가 필요합니다. OpenSeeFace는 약간의 정밀도를 희생하는 대신 견고함과 속도를 우선시하여 라이브 스트리밍, VTubing 및 CPU 리소스가 제한된 기타 대화형 미디어에 적합합니다.

주요 기능

기능	세부 정보
얼굴 랜드마크 모델	66개 포인트(iBUG-68 유사) 및 준 3D 윤곽 포인트; 눈 깜빡임, 시선 정보 포함.
모델 변형	5가지 사전 학습 모델(-1 … 3). 초고속/저정확도에서 저속/고정확도까지(CPU 코어 하나에서 약 213 fps → 44 fps).
ONNX Runtime 추론	GPU 없이 Windows, Linux, macOS에서 실행; Windows용 빌드된 `facetracker.exe` 제공.
UDP 출력	프레임별 랜드마크 데이터를 바이너리 패킷으로 전송; 캡처 PC를 격리하기 위해 별도 머신에서 수신 가능.
Unity 통합	`OpenSee`, `OpenSeeShowPoints`, `OpenSeeLauncher`, `OpenSeeIKTarget`, `OpenSeeExpression` 구성 요소가 패킷 수신, 시각화, IK 구동 및 사용자별 표정 학습을 처리.
크로스 언어 지원	추적기는 Python 3 스크립트(`facetracker.py`)이며 직접 실행하거나 컴파일된 실행 파일로 실행 가능; 최소한의 의존성(onnxruntime, OpenCV, Pillow, NumPy).
표정 분류기	사용자별로 보정하고 저장/로드할 수 있는 선택적 SVM 기반 표정 감지기.
견고성	부분적 가림, 안경, 저조도 및 넓은 머리 자세 범위에서 작동; 얼굴 감지는 사용자 지정 히트맵 회귀 모델 또는 RetinaFace 사용.

일반적인 워크플로우

추적기 시작 – facetracker.exe(Windows) 또는 python facetracker.py(모든 OS)를 실행합니다. 카메라나 비디오 파일을 선택하고 모델(--model 0-3)을 선택한 후, 필요에 따라 --visualize를 활성화하여 로컬에서 랜드마크를 확인합니다.
데이터 스트리밍 – 스크립트는 랜드마크 좌표(및 선택적 시선/눈 깜빡임 플래그)가 포함된 UDP 패킷을 전송합니다.
Unity에서 사용 – OpenSee 구성 요소를 GameObject에 추가합니다. 백그라운드 스레드에서 패킷을 수신하고 trackingData를 통해 노출합니다. OpenSeeShowPoints를 사용하여 포인트를 시각화하거나 VRM/Live2D 아바타 컨트롤러에 데이터를 전달합니다.
선택적 표정 학습 – OpenSeeExpression을 추가하고 표정별로 몇 가지 예제를 기록하여 SVM을 학습시킨 다음, 아바타 로직에서 IsExpressionActive("smile")을 쿼리합니다.

강점

CPU 전용 실시간 성능 – GPU 불필요; 저사양 노트북이나 스트리밍 장비에 적합.
악조건에서의 견고성 – 저조도, 노이즈, 부분적 가림 현상에서 많은 유사 솔루션(MediaPipe 등)보다 우수한 성능.
모듈식 설계 – UDP 스트리밍을 통해 캡처와 렌더링을 분리하여 지연 시간 스파이크를 줄이고 카메라 개인정보를 보호.
다양한 모델 크기 – 다수 얼굴을 위한 빠른 모델이나 1인 스트리밍을 위한 고품질 모델 선택 가능.
오픈 소스 및 허용적 라이선스 – BSD-2-clause 라이선스로 상업 프로젝트에 쉽게 포함 가능.

제한 사항

눈 영역 정확도 – 눈 주변의 랜드마크 위치는 전용 시선 추적기보다 덜 정확함; 눈 깜빡임 감지는 작동하지만 세밀한 시선 추적은 지터가 발생할 수 있음.
CPU 부하 – 30 fps로 단일 얼굴을 추적하면 CPU 코어 하나를 거의 다 사용함; 프레임 속도가 높거나 여러 얼굴을 추적하면 사용량이 비례하여 증가.
내장 아바타 렌더러 없음 – 직접 Unity/Unreal/Godot 통합을 제공해야 함(샘플 프로젝트는 제공되지만 완전한 최종 사용자 앱은 아님).
Linux onnxruntime 로딩 문제 – 일부 사용자는 라이브러리를 로드하기 위해 실행 파일 스택(execstack -c …)을 조정해야 할 수 있음.

빠른 시작

# 의존성 설치 (uv 권장)
uv sync --locked          # 가상 환경 생성
uv run facetracker.py --visualize 3 -c 0   # 웹캠, 모델 3, 랜드마크 표시

Unity에서:

빈 GameObject 생성.
OpenSee 및 OpenSeeShowPoints 구성 요소 추가.
Play를 누르면 추적기가 시작됨(또는 OpenSeeLauncher로 수동 시작).

라이선스

코드와 사전 학습된 모델은 BSD 2-clause 라이선스로 릴리스됩니다. 타사 라이브러리 라이선스는 릴리스 바이너리의 `Licenses` 폴더에 포함되어 있습니다.

추가 정보

Unity 샘플 프로젝트 – https://github.com/emilianavt/OpenSeeFaceSample
데모 영상 – https://www.youtube.com/watch?v=AaNap_ud_3I
관련 아바타 조종 앱 – VSeeFace (https://www.vseeface.icu/)는 OpenSeeFace 데이터를 사용합니다.