V2M4：从单个单目视频重建 4D 网格动画

该存储库是 V2M4 的正式实现（被 ICCV 2025 接受）！🚀

如果您遇到有关论文的任何问题，请随时与我们联系。您可以创建问题或直接向我发送电子邮件 windvchen@gmail.com。也欢迎任何想法交流和讨论。

[07/30/2025] 我们的论文 v2 现已在 ArXiv 上更新（链接）！在本次更新中，我们在附录 B 中添加了更多定量结果，包括不同 3D 基础发生器的比较、密集立体网络以及我们设计选择的消融研究。

[07/25/2025] 增强了实验性 CoTracker3 跟踪功能！

• 添加了一个新参数来控制摄像机与物体的距离，帮助在运动过程中将物体保持在视野内。--tracking_camera_radius
• 引入了调试可视化效果：现在保存跟踪视频和跟踪结果视频，以便于查看。
  此功能的工作原理：通过跟踪渲染帧的关键点，我们正则化网格配准，以在整个动画中保持顶点位置一致。

[07/09/2025] 基准数据发布。👋我们已经在 Google Drive 上发布了我们的评估数据集。基准测试由两个文件夹组成：

• 简单：包含来自 Consistent4D 的 20 个动画视频，以具有简单拓扑和微妙运动的对象为特色。
• complex：包含 20 个动画视频，每个视频都与来自 Mixamo 和 Sketchfab 的原始 4D 文件 （/） 配对。这些示例涵盖了更大规模的对象运动和更复杂的拓扑。.fbx.blend

[07/04/2025] 评估代码发布。

[06/30/2025] 🎉 代码现已公开发布！我们邀请您尝试一下。发布的版本包括除最初论文之外的几个新功能：

• 支持多种最先进的 3D 生成器：TRELLIS、Hunyuan3D-2.0、TripoSG 和 CraftsMan3D
• 集成先进的立体预测技术：DUSt3R 和 VGGT，用于改进相机搜索
• 使用 CoTracker3 跟踪技术增强网格配准

探索这些新功能，让我们知道你的反馈！ 🚀🚀🚀

[06/25/2025] 论文被 ICCV 2025 接受。 🎉🎉

[03/18/2025] 存储库初始化。

• 抽象
• 要求和安装
• 4D网格体动画重建
• 根据重建的结果渲染视频
• 评估
• 结果
• 引文和致谢
• 许可证

我们提出了V2M4，这是一种新颖的4D重建方法，它直接从单个单目视频中生成可用的4D网格动画资产。与依赖多视图图像和视频生成模型先验的现有方法不同，我们的方法基于原生3D网格生成模型。在4D任务中，天真地应用3D网格生成模型为每一帧生成网格可能会导致网格位姿不正确、网格外观未对齐以及网格几何形状和纹理贴图不一致等问题。为了解决这些问题，我们提出了一种结构化的工作流程，包括相机搜索和网格定位、网格外观细化的条件嵌入优化、拓扑一致性的成对网格配准以及纹理一致性的全局纹理图优化。我们的方法输出与主流图形和游戏软件兼容的高质量4D动画资产。在各种动画类型和运动幅度上的实验结果证明了我们方法的通用性和有效性。

1. 硬件要求

   • GPU：1 个高端 NVIDIA GPU，至少 40GB 内存

2. 安装

   • 请按照 Install.md 中的详细说明安装所需的软件包并设置环境。
   • 该代码已使用 Python 3.10 + Pytorch 2.4.0 + CUDA 12.1 进行了测试。

3. 数据

   • 示例中已经有demo-datasets，可以直接运行下面的重建代码查看结果。有关我们论文中使用的完整基准数据集，请访问 Google Drive 下载评估数据集。
   • 如果您想测试自己的视频，请按照演示数据集的格式进行作。（输入图像帧可以是带有背景的 RGB 图像或透明 RGBA 图像。我们还在data_preparation_tools中提供了一些有用的数据准备脚本，以帮助您准备输入数据。（为了获得更好的性能，强烈建议第一帧中的对象具有最小的零件重叠，并且没有零件相互接触。这有助于避免重建过程中的人工拓扑问题。

To reconstruct a 4D mesh animation from a single monocular video, please refer to the following command:

python main.py 
  --root {your_video_folder} 
  --output {your_output_folder} 
  --model Hunyuan   # Performance order in our experiments (from good to bad): Hunyuan ≈ TripoSG > TRELLIS ≈ Craftsman3D. (Actual performance may vary depending on your data and use case.)
  --N 1 
  --n 0 
  --skip 5 
  --seed 42 
  --use_vggt         # (Highly Recommend) Use VGGT for camera search; omit for USING DUSt3R
  --baseline         # (optional) Run the baseline model, i.e., directly use the 3D mesh generator to generate a mesh for each frame without V2M4
  --use_tracking     # (experimental) Use point tracking for mesh registration guidance, will add more memory usage and time cost
  --tracking_camera_radius {radius}  # (experimental) Set the camera tracking radius (this is only valid when using `--use_tracking`) to keep the object visible during motion, default is 8
  --blender_path {your_blender_path}  # Directory path of Blender executable

Argument Descriptions:

• --root: Root directory of the dataset
• --output：结果的输出目录（此文件夹中会保存相当详细的中间结果，用于调试和分析，最终重建的 glb 文件名称为output_animation.glb)
• --model：使用、、或（实验中的性能顺序：Hunyuan ≈ TripoSG > TRELLIS ≈ Craftsman3D。TRELLISHunyuanTripoSGCraftsman
• --N：并行进程总数（默认值：1）
• --n：当前进程的索引（默认值：0）
• --skip：对于大对象移动，每 N 帧跳过一次（默认值：5）
• --seed：用于可重复性的随机种子（默认值：42）
• --baseline：运行基线模型（标志）
• --use_vggt：使用VGGT进行相机搜索（使用DUSt3R时省略）
• --use_tracking：使用点跟踪进行网格配准引导
• --tracking_camera_radius：设置相机跟踪半径，使物体在运动过程中保持可见（默认：8，仅在使用--use_tracking)
• --blender_path：Blender 可执行文件的路径（例如：blender-4.2.1-linux-x64/)

例：

python main.py --root examples --output results --model Hunyuan --N 1 --n 0 --skip 5 --seed 42 --use_vggt --use_tracking --tracking_camera_radius 8 --blender_path blender-4.2.1-linux-x64/

注1：在某些情况下，重建结果可能并不令人满意。我们建议尝试不同的随机种子并调整 --skip 值（对于动作更强烈的视频，使用较小的 --skip 值），以可能获得更好的结果。

注2：如果对象在动画过程中从视图中消失，可能是因为摄像机跟踪半径太小，导致对象在从多个视图渲染时移出帧。要调试，请检查保存的跟踪视频。您可以通过增加 --tracking_camera_radius 值以保持对象可见或禁用跟踪（删除 --use_tracking）来解决此问题。

重建 4D 网格动画后，您可以使用我们提供的脚本从生成的网格序列中渲染视频。此脚本将为每个动画渲染来自重建网格文件的图像和视频。.glb

用法：

python rendering_video.py --result_path {your_results_folder} [--baseline] [--normal] [--interpolate N]

参数说明：

• --result_path：包含重建结果的文件夹的路径（默认值：results)
• --baseline：（可选）还渲染基线网格结果的视频
• --normal：（可选）除了纹理图像之外，还渲染法线贴图
• --interpolate N：（可选）帧之间的插值步长数，以实现更平滑的动画（默认值：1）

例：

python rendering_video.py --result_path results --baseline --normal

输出：这将为每个动画生成以下输出：

• 子文件夹中的单个渲染图像output_final_rendering_images/
• 主要动画视频：output_final_rendering_video.mp4
• 插值动画视频：（如果> 1）output_final_rendering_video_interpolated_{N}.mp4--interpolate
• 法线贴图视频（如果使用标志）--normal
• 基线比较视频（如果使用标志）--baseline

要求：

• 您的结果文件夹应包含带有后缀的重建文件.glb_texture_consistency_sample.glb
• 每个动画的文件（在重建过程中自动生成）extrinsics_list.pkl
• 如果使用 ，还应该存在带有后缀的文件--baseline_baseline_sample.glb

为了根据地面实况视频评估动画重建结果的质量，我们提供了一个全面的评估脚本，用于计算几个广泛使用的视频相似性指标。

评估包括以下指标：FVD、LPIPS、DreamSim 和 CLIP 损失。

cd evaluation
python evaluation.py --gt_videos_path {path_to_GT_videos} --result_videos_path {path_to_V2M4_rendering_videos}

请确保您的视频结构遵循以下格式：

├── path_to_GT_videos/
│   ├── animation1.mp4
│   ├── animation2.mp4
│   └── ...
├── path_to_V2M4_rendering_videos/
│   ├── animation1.mp4
│   ├── animation2.mp4
│   └── ...

以下结果是使用带有 DUSt3R 的 TRELLIS 生成器进行相机搜索获得的，如我们最初的论文中所述。为了提高性能，我们建议尝试我们新支持的型号，例如 Hunyuan3D-2.0 和 VGGT。

如果您发现本文对您的研究有用，请考虑引用：

@inproceedings{chen2025v2m4,
        title={V2M4: 4D Mesh Animation Reconstruction from a Single Monocular Video},
        author={Chen, Jianqi and Zhang, Biao and Tang, Xiangjun and Wonka, Peter},
        booktitle={Proceedings of the IEEE/CVF International Conference on Computer Vision (ICCV)},
        year={2025}
    }

我们衷心感谢以下开源项目的作者和贡献者，他们的工作使这项研究成为可能：TRELLIS、CraftsMan3D、TripoSG、Hunyuan3D-2.0、DUSt3R、VGGT、CoTracker3 等。我们感谢他们对开放研究和更广泛的科学界的承诺。

该项目根据 MIT 许可获得许可。有关详细信息，请参阅许可证。