UltraShape-1.0:基于3D扩散框架的高保真几何生成项目

High-Fidelity 3D Shape Generation via Scalable Geometric Refinement

Branch1Tags0

UltraShape 1.0:基于可扩展几何细化的高保真 3D 形状生成

arXiv Project Page HuggingFace Models


UltraShape 1.0 Teaser

📖 摘要

本报告介绍了 UltraShape 1.0,这是一个用于高保真 3D 几何生成的可扩展 3D 扩散框架。所提出的方法采用两阶段生成流水线:首先合成粗略的全局结构,然后对其进行细化以生成细节丰富、高质量的几何形状。

为支持可靠的 3D 生成,我们开发了一套全面的数据处理流水线,其中包括新颖的** watertight 处理方法和高质量数据过滤**。该流水线通过移除低质量样本、填补孔洞和增厚薄壁结构,同时保留细粒度几何细节,从而提升了公开可用 3D 数据集的几何质量。

为实现细粒度几何细化,我们在扩散过程中将空间定位与几何细节合成解耦。我们通过在固定空间位置执行基于体素的细化来实现这一点,其中源自粗略几何的体素查询提供了通过** RoPE**编码的显式位置锚点,使扩散模型能够专注于在一个精简的、结构化的解空间内合成局部几何细节。

大量评估表明,UltraShape 1.0 在数据处理质量和几何生成方面均与现有的开源方法具有竞争力。

🔥 最新动态

  • [2025-12-25] 📄 我们在 arXiv 上发布了 UltraShape 1.0 的技术报告。
  • [2025-12-26] 🚀 我们发布了推理代码和预训练模型。
  • [2025-12-31] 🚀 我们发布了训练代码。

🗓️ 待办清单

🛠️ 安装与使用

1. 环境配置

git clone https://github.com/PKU-YuanGroup/UltraShape-1.0.git
cd UltraShape-1.0
# 1. Create and activate the environment
conda create -n ultrashape python=3.10
conda activate ultrashape

# 2. Install PyTorch (CUDA 12.1 recommended)
pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu121

# 3. Install dependencies
pip install -r requirements.txt

# 4. Install cubvh (Required for MC acceleration)
pip install git+https://github.com/ashawkey/cubvh --no-build-isolation

# For Training & Sampling (Optional)
pip install --no-build-isolation "git+https://github.com/facebookresearch/pytorch3d.git@stable"
pip install https://data.pyg.org/whl/torch-2.5.0%2Bcu121/torch_cluster-1.6.3%2Bpt25cu121-cp310-cp310-linux_x86_64.whl

⬇️ 模型权重

请从 Hugging Face [ infinith/UltraShape ] 下载预训练权重,并将其放置在您的检查点目录中(例如 ./checkpoints/)。

2. 生成粗略网格

首先,使用 Hunyuan3D-2.1 从您的输入图像生成粗略网格。

代码库:Tencent-Hunyuan/Hunyuan3D-2.1

按照 Hunyuan3D-2.1 代码库中的说明获取初始网格文件(例如 .glb 或 .obj)。

3. 生成精细化网格

获取粗略网格后,使用提供的脚本运行精细化阶段。

运行推理脚本:

sh scripts/run.sh

image:参考图像的路径。

mesh:粗略网格的路径。

output_dir:用于保存优化结果的目录。

ckpt:已下载的 UltraShape 检查点的路径。

step:DiT 推理采样步数。默认值为 50,可减少至 12 以加快生成速度。

或者,您可以运行 gradio 应用程序进行交互式推理:

python scripts/gradio_app.py --ckpt <path_to_checkpoint>

低显存

  1. 使用较小的 num_latents 值(建议尝试 8192)
  2. 使用较小的 chunk_size(建议尝试 2048)
  3. 在 gradio_app.py 和 infer_dit_refine.py 中尝试使用 --low_vram 参数

4. 数据准备与训练

首先,准备数据,包括 watertight 网格和渲染图像。 然后,按如下方式运行采样脚本:

python scripts/sampling.py \
    --mesh_json data/mesh_paths.json \
    --output_dir data/sample

此处,mesh_json 是一个包含 watertight meshes 文件路径的列表。

多节点训练脚本如下:

sh train.sh [node_idx]

training_data_list:包含 train.json 和 val.json 的文件夹,其中存储了数据集的 ID 列表。

sample_pcd_dir:包含采样 .npz 文件的目录。

image_data_json:渲染图像的文件路径。

您可以在 train.sh 中切换 VAE 和 DiT 训练,并在其中指定输出目录和配置文件。

🔗 BibTeX

如果您觉得本仓库有帮助,请引用我们的报告:

@article{jia2025ultrashape,
    title={UltraShape 1.0: High-Fidelity 3D Shape Generation via Scalable Geometric Refinement},
    author={Jia, Tanghui and Yan, Dongyu and Hao, Dehao and Li, Yang and Zhang, Kaiyi and He, Xianyi and Li, Lanjiong and Chen, Jinnan and Jiang, Lutao and Yin, Qishen and Quan, Long and Chen, Ying-Cong and Yuan, Li},
    journal={arxiv preprint arXiv:2512.21185},
    year={2025}
}

致谢

我们的代码基于 Hunyuan3D-2.1 的出色工作构建而成。我们方法的核心思想深受 LATTICE 的启发。我们衷心感谢这些工作对 3D 生成领域的贡献。也请考虑引用 Hunyuan3D 2.1 和 LATTICE:

Introduction

High-Fidelity 3D Shape Generation via Scalable Geometric Refinement

Customize your domain