Friedrich-M/UniMate

UniMate – 다양한 스켈레톤을 애니메이션화하는 통합 모델

정의

텍스트 프롬프트에서 모든 리깅된 스켈레톤(인간, 동물, 로봇, 추상 객체 포함)에 대한 3D 관절 모션을 생성하는 연구급 딥러닝 모델.
UniML3D 데이터셋으로 훈련 – 13.8k 텍스트 페어 모션 클립으로 7.4k 다양한 토폴로지(이족, 사족, 조류, 해양, 곤충, 뱀형, 강체 리그)의 스켈레톤을 포함.

중요성

기존 텍스트-투-애니메이션 시스템은 단일 캐릭터 토폴로지로 제한됩니다. UniMate는 관절의 표준 표현을 학습하여 스켈레톤별 미세 조정이나 테스트 시간 최적화 없이 보지 못한 리그에 적용할 수 있습니다.
모델은 실시간으로 작동하여 대화형 애플리케이션(게임, VR, 로봇 시뮬레이션)에 적합합니다.

주요 구성 요소

구성 요소	기능
모델 아키텍처	두 가지 어텐션 변형 제공: `graph_adaln`(시공간 그래프 인식 어텐션) 및 `full_cross_attn`(관절-시간 토큰에 대한 표준 Transformer). 둘 다 고정된 FLAN-T5 인코더를 통해 텍스트로 조건화할 수 있습니다.
훈련 목표	플로우 매칭 확산: 네트워크는 노이즈와 대상 모션 사이의 선형 보간 속도를 예측합니다. 손실은 마스크된 L2, 측지 회전 항, 속도 평활 항을 결합합니다.
데이터 파이프라인	`data_process/` 스크립트는 원시 자산(Mixamo, Objaverse-XL, Truebones)을 통합 UniML3D 형식으로 변환합니다: 내보내기, 렌더링, 캡션, 관절 주석, 특징 추출. `rig_preprocess` 도구를 사용하면 모든 GLB/FBX/GLTF 리그를 동일한 형식으로 가져올 수 있으며, LLM 생성 관절 레이블을 검토할 수 있습니다.
추론	`unimate.inference.sample`은 리그와 프롬프트에서 훈련된 체크포인트를 구동하여 애니메이션 GLB/FBX 파일을 출력합니다. 배치 샘플링, 분류기 없는 안내(`--cfg_scale`), 프롬프트당 여러 반복을 지원합니다.
유틸리티	텍스트 임베딩 사전 계산, 훈련 재개, 디버그 렌더링 시각화, 생성된 모션으로 메시를 구동하는 간단한 스크립트.

시작하기

환경 생성

conda create -n unimate python=3.10 -y
conda activate unimate
pip install "setuptools<81"
pip install -r requirements.txt --no-build-isolation

데이터셋 다운로드(약 88GB) 및 릴리스된 체크포인트:

hf download Linzhan/UniML3D --repo-type dataset --local-dir dataset
hf download Linzhan/UniMate --repo-type model --local-dir outputs \
    --include "unimate_uniml3d_f60_v3/*.json" \
    --include "unimate_uniml3d_f60_v3/*.npy" \
    --include "unimate_uniml3d_f60_v3/checkpoints/checkpoint_step_150000.pt"

빠른 데모 실행(몇 가지 전처리된 자산 애니메이션화):

python -m unimate.inference.sample \
    --exp_dir outputs/unimate_uniml3d_f60_v3 \
    --test_cases_json assets/examples/examples.json \
    --num_repetitions 3 \
    --output_dir outputs/samples/examples
SKIP_INVALID=1 bash scripts/run_animate_motion.sh outputs/samples/examples

Garfield 모델, 건담, 상어 등의 객체에 대한 애니메이션 GLB/FBX 파일을 얻을 수 있습니다.

자체 모델 훈련

구성 파일은 configs/에 있습니다. 데이터셋 선택, 프레임 길이, 어텐션 유형, 캡션 조건화(예: uniml3d_60frames_graph_adaln.json)를 인코딩합니다.

🤗 Accelerate로 시작:

accelerate launch -m unimate.training.train --config configs/uniml3d_60frames_graph_adaln.json

멀티 GPU: --num_processes N 추가.
파이프라인은 매우 불균일한 스켈레톤 수에 걸친 균형 샘플링, 관절 축 패딩, 데이터 증강(관절 추가, 리프 제거, 체인 풀링, 뼈 길이 섭동)을 처리합니다.
체크포인트, 로그, 시각적 디버그 렌더링은 outputs/<experiment>/에 기록됩니다.

자체 리그 사용("Bring your own rig")

GLB/FBX/GLTF 파일을 폴더에 배치합니다.
전처리 도구 실행:
```
python -m data_process.rig_preprocess.process <path_to_folder>
```
도구는 LLM으로 관절에 레이블을 지정하고, 관절 이름과 방향에 대한 검토 UI를 표시하며, 추론 스크립트가 기대하는 표준 자산 디렉토리를 생성합니다.
동일한 sample 명령으로 애니메이션화하고 --asset을 새로 생성된 디렉토리로 지정합니다.

응용 분야

게임/VR 콘텐츠 제작 – 수동으로 애니메이션을 작성하지 않고 캐릭터나 소품에 대한 다양한 모션 클립을 빠르게 생성.
로봇 시뮬레이션 – 임의의 운동학 트리를 가진 로봇에 대한 그럴듯한 이동 또는 조작 시퀀스 생성.
영화 및 VFX 프로토타이핑 – 환상적인 생물이나 기계적 리그에 대한 모션 아이디어 탐색.
저장소는 동일한 모델을 사용하는 세 가지 제로샷 다운스트림 작업(예: 모션 편집, 스타일 전송)도 보여주지만, 자세한 내용은 논문에 있습니다.

링크 및 리소스

프로젝트 페이지 및 논문: https://linzhanmou.com/unimate/ (arXiv: 2609.05415)
대화형 데모: https://linzhanmou.com/unimate/interactive.html
데이터셋: https://huggingface.co/datasets/Linzhan/UniML3D
모델 체크포인트: https://huggingface.co/Linzhan/UniMate
GitHub 저장소: https://github.com/Friedrich-M/UniMate (이 README)

TL;DR

UniMate는 모든 리깅된 3D 스켈레톤에서 작동하는 오픈 소스 확산 기반 텍스트-투-애니메이션 모델입니다. 대규모 다중 토폴로지 데이터셋, 완전한 훈련 코드, 사용자 지정 자산 전처리 파이프라인, 즉시 실행 가능한 추론 스크립트가 함께 제공됩니다. 범용 실시간 모션 생성기가 필요한 연구자와 개발자에게 적합합니다.