📖 Overview

ActionMesh is a fast model for generating animated 3D meshes from videos. It supports two modes:

• Video → 4D (main): generate an animated mesh from a video
• {Video + 3D} → 4D: animate an existing mesh w.r.t. the video, preserving its topology and texture

🆕 Updates

• 2026-02-20: 📊 We release 🤗 facebook/ActionBench, a benchmark dataset of 128 paired videos ↔ animated point-clouds for evaluating animated 3D mesh generation. See actionbench/README.md for evaluation instructions.

• 2026-02-11: {3D+video}→4D - Optionally pass a 3D mesh as input (texture preserved)

• 2026-01-31: Low RAM mode (--low_ram) — Runs on Google Colab T4 GPUs! Try it on Colab

• 2025-01-21: Demo is live! Try it here: 🤗 facebook/ActionMesh

• 2025-01-21: Code released!

⚙️ Installation

Requirements

• GPU: NVIDIA GPU with 32GB VRAM, or 12GB with --low_ram mode (e.g., Google Colab T4)
• PyTorch: Requires PyTorch and torchvision (developed with torch 2.4.0 / CUDA 12.1 and torchvision 0.19.0)

1. Clone and Install Dependencies

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

2. Optional Dependencies

🚀 Quick Start

I - Video → 4D

Generate an animated mesh from an input video:

Note: To export a single animated mesh file (importable in Blender), specify the path to your Blender executable via --blender_path.

python inference/video_to_animated_mesh.py \
    --input assets/examples/davis_camel \
    --blender_path "path/to/blender/executable"  # optional: export animated mesh for Blender

II - {Video + 3D} → 4D

Pass an existing mesh (.GLB) to animate it w.r.t. the video, preserving its topology and texture:

python inference/video_and_3d_to_animated_mesh.py \
    --input assets/examples/panda \
    --mesh_input assets/examples/panda/panda.glb \
    --blender_path "path/to/blender/executable"

Fast & Low RAM Modes

Add --fast for faster inference (as used in the HuggingFace demo), and --low_ram for GPUs with limited VRAM (e.g., Google Colab T4). Both flags can be combined.

Performance comparison on H100 GPU:

Model Downloads

On the first launch, ActionMesh weights and external models are automatically downloaded from HuggingFace:

🎨 Examples

We provide example sequences in assets/examples/ with expected outputs for testing and debugging your installation:

🎬 Input

The --input argument accepts:

• A .mp4 video file
• A folder containing PNG images

The number of input frames should be between 16 and 31 (default is 16). Any additional frames will be ignored.

Masks

Input frames can be provided with or without alpha masks. If no mask is provided, RMBG background removal model is automatically applied to each frame before processing.

Tip: For custom videos, we strongly recommend using the SAM2 demo to isolate the animated subject on a white background, as RMBG may have limited performance on complex scenes. See our SAM2 extraction guide for detailed instructions.

📦 Export

The model exports a folder containing:

🎥 Video output preview

🎞️ Animated mesh file imported in Blender

In the {Video + 3D} → 4D setting, if the input mesh has a texture, it is preserved in `animated_mesh.glb`.

🏛️ License

See the LICENSE file for details about the license under which this code is made available.

🙏 Acknowledgements

ActionMesh builds upon the following open-source projects. We thank the authors for making their work available:

📚 Citation

@inproceedings{ActionMesh2026,
author = {Remy Sabathier, David Novotny, Niloy Mitra, Tom Monnier},
title = {ActionMesh: Animated 3D Mesh Generation with Temporal 3D Diffusion},
year = {2026},
}