🎬ActionMesh: A fast video to animated mesh model with unprecedented quality. Generate animated mesh seamlessly importable into any 3D software in less than a minute.

ActionMesh – 동영상을 애니메이션 3D 메시로 변환

기능 소개

ActionMesh는 짧은 동영상(16‑31 프레임)에서 완전한 3D 애니메이션 메시를 생성하는 연구용 모델입니다. 두 가지 방식으로 작동합니다:

Video → 4D – 동영상만 제공하면 시스템이 피사체의 움직임과 정확히 일치하는 새로운 메시를 구축합니다.
{Video + 3D} → 4D – 기존 정적 메시(예: .glb 파일)를 제공하면, 원래의 토폴로지와 텍스처를 유지하면서 동영상의 움직임에 따라 애니메이션화합니다.

출력물은 프레임별 .glb 파일 시퀀스, Blender에서 가져올 수 있는 단일 애니메이션 .glb 파일, 또는 애니메이션 렌더링 동영상으로 받을 수 있습니다.

중요성

비전과 그래픽스의 결합 – 동영상 이해(DINOv2, SAM2, 배경 제거)와 3D 확산 모델을 결합하여 지오메트리와 움직임을 합성합니다.
인터랙티브 데모를 위한 빠른 속도 – H100 GPU에서 기본 실행 시 약 75초, "fast" 플래그 사용 시 약 45초가 소요됩니다.
저사양 RAM 옵션 – --low_ram을 사용하여 Colab T4 (12 GB)에서도 실행 가능하므로, 고성능 GPU가 없는 연구자도 기술을 활용할 수 있습니다.
오픈 소스 벤치마크 – 함께 제공되는 ActionBench 데이터셋(128개의 동영상 ↔ 애니메이션 포인트 클라우드 쌍)을 통해 커뮤니티에서 향후 방법론을 평가하고 비교할 수 있습니다.

시작하기 (퀵스타트)

# clone and install
git clone git@github.com:facebookresearch/actionmesh.git && cd actionmesh
git submodule update --init --recursive
pip install -r requirements.txt -e .

# simple video‑to‑mesh run (replace paths as needed)
python inference/video_to_animated_mesh.py \
    --input assets/examples/davis_camel \
    --blender_path /path/to/blender   # optional, for .glb export

더 빠른 추론 모드를 사용하려면 --fast를, 저사양 GPU(예: Colab)를 사용하는 경우 --low_ram을 추가하세요.

주요 구성 요소 및 의존성

구성 요소	역할	설치 / 소스
PyTorch 2.4 / CUDA 12.1	핵심 딥러닝 프레임워크
PyTorch3D	애니메이션 메시 렌더링 ({video+3D} 모드 및 벤치마크 평가에 필요)
Blender 3.5.1	프레임별 메시를 단일 애니메이션 GLB로 변환
TripoSG	형상 사전 정보의 백본으로 사용되는 이미지-3D 생성기
DINOv2‑large	강력한 프레임 특징을 제공하는 비전 인코더
RMBG‑1.4	마스크가 없을 때 자동 배경 제거
Diffusers / Transformers	기반 확산 및 Transformer 구현

입력 요구 사항

동영상: .mp4 또는 PNG 프레임 폴더.
길이: 16‑31 프레임 (추가 프레임은 무시됨).
마스크는 선택 사항입니다. 마스크가 없으면 파이프라인이 RMBG를 실행하여 전경을 잘라냅니다. 최상의 결과를 위해 README에서는 SAM2 데모를 사용하여 깨끗한 마스크를 생성할 것을 권장합니다.

출력 형식

출력	내용	사용 방법
`mesh_000.glb`, `mesh_001.glb`, …	타임스텝당 하나의 메시 – 사용자 지정 렌더링 파이프라인에 유용
`animated_mesh.glb`	애니메이션이 포함된 단일 파일 – Blender 3.5.1로 드래그 앤 드롭
`rendered.mp4`	PyTorch3D로 렌더링된 동영상 – 빠른 시각적 확인

벤치마크 및 성능

하드웨어	모드	시간	품질 참고
H100 GPU	기본	~75 s	최고 품질
H100 GPU	`--fast`	~45 s	품질 약간 저하
Colab T4 (12 GB)	`--low_ram` + `--fast`	~1 min 30 s	프로토타이핑에 적합

커뮤니티 리소스

Hugging Face 데모 – facebook/ActionMesh에서 인터랙티브 웹 UI 제공.
Colab 노트북 – 바로 실행 가능한 노트북 (ActionMesh.ipynb).
ActionBench 데이터셋 – 평가를 위해 Hugging Face (facebook/actionbench)에 호스팅됨.

라이선스 및 인용

코드는 저장소의 LICENSE 파일에 따라 배포됩니다. 연구에 이 방법을 사용하는 경우 CVPR 2026 논문을 인용하십시오(전체 bibtex는 README에 제공됨).

위의 모든 정보는 저장소의 README에서 직접 가져온 것이며, 외부적인 추측은 포함되지 않았습니다.

facebookresearch/actionmesh