📖 摘要
本报告介绍了UltraShape 1.0——一个可扩展的三维扩散框架，用于生成高保真三维几何体。该方案采用两阶段生成流程：首先生成粗糙的全局结构，然后进行细化以产出细节丰富的高质量几何体。
为实现可靠的三维生成，我们开发了完整的数据处理流程，包含创新的水密处理方法与高质量数据过滤。该流程通过剔除低质量样本、填补孔洞及加厚薄壁结构来提升公开三维数据集的几何质量，同时保留细粒度几何细节。
为实现细粒度几何优化，我们在扩散过程中将空间定位与几何细节合成进行解耦。具体通过在固定空间位置执行体素级优化，其中从粗糙几何体导出的体素查询通过RoPE编码提供显式位置锚点，使扩散模型能专注于在结构化简化的解空间内合成局部几何细节。
大量实验表明，UltraShape 1.0在数据处理质量与几何生成方面均与现有开源方案具有竞争力。
🔥 动态
- [2025-12-25]📄 我们已在arXiv发布UltraShape 1.0技术报告
- [2025-12-26]🚀 我们发布了推理代码与预训练模型
- [2025-12-31]🚀 我们发布了训练代码
🗓️ 待办事项
- 发布推理代码
- 发布预训练权重（Hugging Face）
- 发布训练代码
- 发布数据处理脚本
🛠️ 安装与使用
1. 环境配置
gitclone https://github.com/PKU-YuanGroup/UltraShape-1.0.gitcdUltraShape-1.0# 1. Create and activate the environmentconda create -n ultrashapepython=3.10conda activate ultrashape# 2. Install PyTorch (CUDA 12.1 recommended)pipinstalltorch==2.5.1torchvision==0.20.1torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu121# 3. Install dependenciespipinstall-r requirements.txt# 4. Install cubvh (Required for MC acceleration)pipinstallgit+https://github.com/ashawkey/cubvh --no-build-isolation# For Training & Sampling (Optional)pipinstall--no-build-isolation"git+https://github.com/facebookresearch/pytorch3d.git@stable"pipinstallhttps://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. 生成优化后的网格
获得粗粒度网格后，使用提供的脚本运行优化阶段。
运行推理脚本：
shscripts/run.shimage: 参考图像的路径。
mesh: 粗粒度网格的路径。
output_dir: 保存优化结果的目录。
ckpt: 下载的 UltraShape 检查点路径。
step: DiT 推理采样步数。默认为 50 步，可减少至 12 步以加速生成。
或者，您可以运行 gradio 应用进行交互式推理：
python scripts/gradio_app.py --ckpt<path_to_checkpoint>低显存模式
- 使用较低的num_latents值（建议尝试8192）
- 使用较小的chunk_size（建议尝试2048）
- 在gradio_app.py和infer_dit_refine.py脚本中尝试添加–low_vram参数
4. 数据准备与训练
首先准备数据，包括水密网格和渲染图像。
然后按以下方式运行采样脚本：
python scripts/sampling.py \ --mesh_json data/mesh_paths.json \ --output_dir data/sample此处，mesh_json 是一个包含水密网格文件路径的列表。
多节点训练脚本为：
sh train.sh [node_idx]training_data_list：包含train.json和val.json的文件夹，存储数据集的ID列表。
sample_pcd_dir：包含采样.npz文件的目录。
image_data_json：渲染图像的文件路径。
您可以在train.sh中切换VAE和DiT训练，并在其中指定输出目录和配置文件。
🔗 引用格式
如果您觉得本仓库有帮助，请引用我们的报告：
@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：
- Hunyuan3D-2.1
- Lattice3D
代码
https://github.com/PKU-YuanGroup/UltraShape-1.0
