---
base_model:
- tencent/Hunyuan3D-2.1
license: apache-2.0
pipeline_tag: image-to-3d
tags:
- 3d
- geometry-generation
- diffusion
- reconstruction
---
UltraShape 1.0 Refine Model
In this report, we introduce **UltraShape 1.0**, a scalable 3D diffusion framework for high-fidelity 3D geometry generation. The proposed approach adopts a **two-stage generation pipeline**: a coarse global structure is first synthesized (e.g., via Hunyuan3D-2.1) and then refined to produce detailed, high-quality geometry.
To enable fine-grained geometry refinement, we decouple spatial localization from geometric detail synthesis in the diffusion process. We achieve this by performing **voxel-based refinement** at fixed spatial locations, where voxel queries derived from coarse geometry provide explicit positional anchors encoded via **RoPE**, allowing the diffusion model to focus on synthesizing local geometric details within a reduced, structured solution space.
## 🛠️ Installation & Usage
### 1. Environment Setup
```bash
git clone https://github.com/PKU-YuanGroup/UltraShape-1.0.git
cd UltraShape
# 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
```
### 2. Generate Refined Mesh
Once you have a coarse mesh (generated using [Hunyuan3D-2.1](https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1)), use the provided script to run the refinement stage.
Run the inference script:
```bash
sh scripts/run.sh
```
**Parameters in `run.sh`:**
- **image**: Path to the reference image.
- **mesh**: Path to the coarse mesh.
- **output_dir**: Directory to save the refined result.
- **ckpt**: Path to the downloaded UltraShape checkpoint.
## 🔗 BibTeX
If you found this repository helpful, please cite our report:
```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}
}
```
## Acknowledgements
We would like to thank the contributors to the [Hunyuan3D-2.1](https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1), [Lattice](https://lattice3d.github.io/), [Cubvh](https://github.com/ashawkey/cubvh) and [HuggingFace](https://huggingface.co) repositories, for their research and exploration.