MeshAnything V2：
艺术家创作的网格生成
结合邻接网格标记化

Yiwen Chen^1,2, Yikai Wang³*, Yihao Luo⁴, Zhengyi Wang^2,3,
Zilong Chen^2,3, Jun Zhu^2,3, Chi Zhang⁵*, Guosheng Lin¹*
^*通讯作者。
¹南洋理工大学S-Lab, ²盛数,
³清华大学, ⁴帝国理工学院, ⁵西湖大学

目录

• 目录
• 安装
• 使用
• 训练
• 重要提示
• 致谢
• BibTeX

安装

我们的环境已在Ubuntu 22和CUDA 11.8（A800）上测试通过。

1. 克隆我们的仓库并创建Conda环境

git clone https://github.com/buaacyw/MeshAnythingV2.git && cd MeshAnythingV2
conda create -n MeshAnythingV2 python==3.10.13 -y
conda activate MeshAnythingV2
pip install torch==2.1.1 torchvision==0.16.1 torchaudio==2.1.1 --index-url https://download.pytorch.org/whl/cu118
pip install -r requirements.txt
pip install -r training_requirements.txt # 如果你想进行训练
pip install flash-attn --no-build-isolation
pip install -U gradio

使用

邻接网格标记化与解标记化的实现

# 我们在adjacent_mesh_tokenization.py中发布了邻接网格标记化的实现。
# 解标记化请查看MeshAnything/models/meshanything_v2.py中的adjacent_detokenize函数。
python adjacent_mesh_tokenization.py

对于文本/图像到艺术家创作网格的转换，我们建议先使用Rodin将文本或图像转化为密集网格，然后再将该密集网格输入给我们。

# 将Rodin的输出obj文件放入rodin_result目录，并使用以下命令生成艺术家创作的网格。
# 我们建议使用--mc标志先用Marching Cubes对输入网格进行预处理。这有助于我们将推理点云对齐到我们的训练域。
python main.py --input_dir rodin_result --out_dir mesh_output --input_type mesh --mc

网格命令行推理

重要提示：如果您的网格输入不是由Marching Cubes生成的，我们建议您先用Marching Cubes对其进行预处理（只需添加--mc即可）。

# 文件夹输入
python main.py --input_dir examples --out_dir mesh_output --input_type mesh

# 单个文件输入
python main.py --input_path examples/wand.obj --out_dir mesh_output --input_type mesh

# 先用Marching Cubes预处理
python main.py --input_dir examples --out_dir mesh_output --input_type mesh --mc

# Marching Cubes的分辨率默认为128。对于一些精细的网格，这个分辨率可能不够。提高分辨率会增加预处理时间，但通常能获得更好的效果。
# 可以通过以下方式调整：--mc_level 7 -> 128 (2^7), --mc_level 8 -> 256 (2^8)。
# 256分辨率Marching Cube示例。
python main.py --input_dir examples --out_dir mesh_output --input_type mesh --mc --mc_level 8

点云命令行推理

# 注意：如果您想使用自己的点云，请确保包含法线信息。
# 文件格式应为.npy文件，形状为(N, 6)，其中N是点的数量。前3列是坐标，后3列是法线。

# 文件夹推理
python main.py --input_dir pc_examples --out_dir pc_output --input_type pc_normal

# 单个文件推理
python main.py --input_path pc_examples/grenade.npy --out_dir pc_output --input_type pc_normal

本地Gradio演示

python app.py

训练

第一步：下载数据集

我们提供了部分来自Objaverse的已处理数据集。您可以从https://huggingface.co/datasets/Yiwen-ntu/MeshAnythingV2/tree/main下载。

下载后，将train.npz和test.npz放入dataset目录。

如果您更倾向于自行处理数据，请参考data_process.py。

第二步：下载点云编码器检查点

从https://huggingface.co/Maikou/Michelangelo/tree/main/checkpoints/aligned_shape_latents下载米开朗基罗的点云编码器，并将其放入`meshanything_train/miche/checkpoints/aligned_shape_latents/shapevae-256.ckpt`。

第三步：训练与评估

# 多GPU训练
accelerate launch --multi_gpu --num_processes 8 train.py  --batchsize_per_gpu 2 --checkpoint_dir training_trial

# 评估
python train.py --batchsize_per_gpu 2 --checkpoint_dir evaluation_trial --pretrained_weights gpt_output/training_trial/xxx_xxx.pth --test_only

重要提示

• 在 A6000 GPU 上生成一个网格大约需要 8GB 显存和 45 秒（具体时间取决于生成网格的面数）。
• 输入网格将被归一化到单位包围盒。为了获得更好的效果，输入网格的向上方向矢量应为 +Y。
• 受计算资源限制，MeshAnything 模型仅在面数少于 1600 的网格上进行训练，无法生成面数超过 1600 的网格。输入网格的形状应足够清晰；否则，仅用 1600 个面难以准确表示。因此，基于前向传播的 3D 生成方法往往因形状质量不足而产生较差的结果。我们建议使用 3D 重建、扫描、基于 SDS 的方法（如 DreamCraft3D）或 Rodin 的输出作为 MeshAnything 的输入。
• 更多示例请参阅：https://huggingface.co/spaces/Yiwen-ntu/MeshAnything/tree/main/examples。

致谢

我们的代码基于以下优秀的开源项目：

• MeshAnything
• MeshGPT
• meshgpt-pytorch
• Michelangelo
• transformers
• vector-quantize-pytorch

BibTeX

@misc{chen2024meshanythingv2artistcreatedmesh,
      title={MeshAnything V2: 基于邻接网格标记化的艺术家创作网格生成}, 
      author={陈艺文、王毅凯、罗一豪、王正一、陈子龙、朱俊、张驰、林国胜},
      year={2024},
      eprint={2408.02555},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2408.02555}, 
}

MeshAnythingV2 快速上手指南

MeshAnythingV2 是一个能够将艺术家创作的网格（或点云）转化为高质量、低面数网格的生成模型。它特别适合作为 3D 重建、扫描或 Rodin 等前向生成模型的后续优化工具。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Ubuntu 22.04 (推荐)
• GPU: NVIDIA GPU (测试环境为 A800/A6000)，显存建议 8GB 以上
• CUDA 版本: 11.8
• Python 版本: 3.10.13
• 依赖管理: Conda

安装步骤

以下命令将克隆代码库并配置完整的运行环境。

1. 克隆仓库并创建 Conda 环境

   git clone https://github.com/buaacyw/MeshAnythingV2.git && cd MeshAnythingV2
   conda create -n MeshAnythingV2 python==3.10.13 -y
   conda activate MeshAnythingV2
   

2. 安装 PyTorch (CUDA 11.8)

   pip install torch==2.1.1 torchvision==0.16.1 torchaudio==2.1.1 --index-url https://download.pytorch.org/whl/cu118
   

3. 安装项目依赖

   pip install -r requirements.txt
   # 如果不需要训练，可跳过下一行
   pip install -r training_requirements.txt 
   pip install flash-attn --no-build-isolation
   pip install -U gradio
   

4. 下载预训练权重 从 Hugging Face 下载权重文件并放置于项目目录（具体路径参考官方 HF 页面结构，通常需放入 gpt_output 或对应 checkpoint 目录）：

   • 权重地址：https://huggingface.co/Yiwen-ntu/MeshAnythingV2/tree/main

基本使用

场景一：网格优化 (Mesh to Artist-Created Mesh)

这是最常用的场景。建议输入由 Rodin、3D 扫描或重建算法生成的密集网格，模型将其转换为拓扑更优的低面数网格。

注意：如果输入网格不是由 Marching Cubes 生成的，强烈建议添加 --mc 参数进行预处理，以对齐训练域。

• 处理文件夹内的所有网格文件：

  python main.py --input_dir examples --out_dir mesh_output --input_type mesh --mc
  

• 处理单个网格文件：

  python main.py --input_path examples/wand.obj --out_dir mesh_output --input_type mesh --mc
  

• 调整预处理精度（默认分辨率 128，对于细节丰富的模型可提升至 256）：

  # --mc_level 8 对应 2^8 = 256 分辨率
  python main.py --input_dir examples --out_dir mesh_output --input_type mesh --mc --mc_level 8
  

场景二：点云生成网格 (Point Cloud to Mesh)

输入需为 .npy 格式，形状为 (N, 6)，其中前 3 列为坐标，后 3 列为法向量。

• 处理点云文件：

  python main.py --input_path pc_examples/grenade.npy --out_dir pc_output --input_type pc_normal
  

场景三：启动本地 Web 演示

如果您希望通过图形界面进行操作，可以启动本地的 Gradio 服务：

python app.py

启动后在浏览器访问显示的本地地址即可。

---

重要提示：

• 模型训练时限制在 1600 个面以内，因此生成的网格面数不会超过此限制。
• 为了获得最佳效果，输入网格的上方向向量应为 +Y 轴。
• 生成一个网格在 A6000 上大约需要 45 秒和 8GB 显存。