中文阅读 日本語で読む

Hunyuan3D-2GP: 3D Generation for the GPU Poor

GPU Poor version by DeepBeepMeep. This great video generator can now run smoothly with less than 6 GB of VRAM.

This is another integration of the mmgp 3.1 module that allows easy to setup advanced and fast offloading.
https://github.com/deepbeepmeep/mmgp

Join our Wechat and Discord group to discuss and find help from us.

Wechat Group	Xiaohongshu	X	Discord

---

“ Living out everyone’s imagination on creating and manipulating 3D assets.”

🔥 News

• Jan 25, 2025: 💬 Hunyuan3D-2.0GP by Deepbeepmeep: Synced code with original repo.Many thanks to YanWenKun for the work.

• Jan 23, 2025: 💬 Hunyuan3D-2.0GP by Deepbeepmeep: added lighning fix in rendering window

• Jan 23, 2025: 💬 Hunyuan3D-2.0GP by Deepbeepmeep: added Windows support thanks to MrForExample and sdbds + omitted optimization that keeps under VRAM 6GB with profile 4 or 5

• Jan 22, 2025: 💬 Hunyuan3D-2.0GP by Deepbeepmeep: low VRAM support and unlocked text to 3D generator

• Jan 21, 2025: 💬 Release Hunyuan3D 2.0. Please give it a try!

• Jan 23, 2025: 💬 We thank community members for creating Windows installation tool, ComfyUI support with ComfyUI-Hunyuan3DWrapper and ComfyUI-3D-Pack and other awesome extensions.

• Jan 21, 2025: 💬 Enjoy exciting 3D generation on our website Hunyuan3D Studio!

• Jan 21, 2025: 💬 Release inference code and pretrained models of Hunyuan3D 2.0.

• Jan 21, 2025: 💬 Release Hunyuan3D 2.0. Please give it a try via huggingface space and our official site!

Abstract

We present Hunyuan3D 2.0, an advanced large-scale 3D synthesis system for generating high-resolution textured 3D assets. This system includes two foundation components: a large-scale shape generation model - Hunyuan3D-DiT, and a large-scale texture synthesis model - Hunyuan3D-Paint. The shape generative model, built on a scalable flow-based diffusion transformer, aims to create geometry that properly aligns with a given condition image, laying a solid foundation for downstream applications. The texture synthesis model, benefiting from strong geometric and diffusion priors, produces high-resolution and vibrant texture maps for either generated or hand-crafted meshes. Furthermore, we build Hunyuan3D-Studio - a versatile, user-friendly production platform that simplifies the re-creation process of 3D assets. It allows both professional and amateur users to manipulate or even animate their meshes efficiently. We systematically evaluate our models, showing that Hunyuan3D 2.0 outperforms previous state-of-the-art models, including the open-source models and closed-source models in geometry details, condition alignment, texture quality, and e.t.c.

How to run the Gradio app

1. Follow the installation instructions below

2. Enter either one of the commande lines in bash session

To run the image to 3D generator:

python gradio_app.py

To run the text to 3D generator:

python gradio_app.py --enable_t23d

By default the memory profile assumes 9 GB of VRAM (profile 2). If you have less but at least 6 GB of VRAM add --profile 5

To run the image to 3D generator with optimized memory management:

python gradio_app.py --profile 5

To run the text to 3D generator with optimized memory management:

python gradio_app.py --enable_t23d --profile 5

You can choose between 5 profiles depending on your hardware:

• HighRAM_HighVRAM (1): at least 48 GB of RAM and 12 GB of VRAM
• HighRAM_LowVRAM (2): at least 48 GB of RAM and 6 GB of VRAM
• LowRAM_HighVRAM (3): at least 32 GB of RAM and 12 GB of VRAM
• LowRAM_LowVRAM (4): at least 32 GB of RAM and 6 GB of VRAM
• VerylowRAM_LowVRAM (5): at least 24 GB of RAM and 6 GB of VRAM

Usualy the lower the profile the faster the generation.

Other GPU Poor Applications

• HuanyuanVideoGP: https://github.com/deepbeepmeep/HunyuanVideoGP :
  One of the best open source Text to Video generator

• FluxFillGP: https://github.com/deepbeepmeep/FluxFillGP :
  One of the best inpainting / outpainting tools based on Flux that can run with less than 12 GB of VRAM.

• Cosmos1GP: https://github.com/deepbeepmeep/Cosmos1GP :
  This application include two models: a text to world generator and a image / video to world (probably the best open source image to video generator).

• OminiControlGP: https://github.com/deepbeepmeep/OminiControlGP :
  A Flux derived application very powerful that can be used to transfer an object of your choice in a prompted scene. With mmgp you can run it with only 6 GB of VRAM.

• YuE GP: https://github.com/deepbeepmeep/YuEGP :
  A great song generator (instruments + singer's voice) based on prompted Lyrics and a genre description. Thanks to mmgp you can run it with less than 10 GB of VRAM without waiting forever.

Architecture

Hunyuan3D 2.0 features a two-stage generation pipeline, starting with the creation of a bare mesh, followed by the synthesis of a texture map for that mesh. This strategy is effective for decoupling the difficulties of shape and texture generation and also provides flexibility for texturing either generated or handcrafted meshes.

Performance

We have evaluated Hunyuan3D 2.0 with other open-source as well as close-source 3d-generation methods. The numerical results indicate that Hunyuan3D 2.0 surpasses all baselines in the quality of generated textured 3D assets and the condition following ability.

Model	CMMD(⬇)	FID_CLIP(⬇)	FID(⬇)	CLIP-score(⬆)
Top Open-source Model1	3.591	54.639	289.287	0.787
Top Close-source Model1	3.600	55.866	305.922	0.779
Top Close-source Model2	3.368	49.744	294.628	0.806
Top Close-source Model3	3.218	51.574	295.691	0.799
Hunyuan3D 2.0	3.193	49.165	282.429	0.809

Generation results of Hunyuan3D 2.0:

Pretrained Models

Model	Date	Params	Huggingface
Hunyuan3D-DiT-v2-0	2025-01-21	2.6B	Download
Hunyuan3D-Paint-v2-0	2025-01-21	1.3B	Download
Hunyuan3D-Delight-v2-0	2025-01-21	1.3B	Download

🤗 Get Started with Hunyuan3D 2.0

You may follow the next steps to use Hunyuan3D 2.0 via code or the Gradio App.

Install Requirements

To use the application on Windows (without WSL) you will need to install Microsoft Visual Studio 2022 or later. If you get an error during the execution of onr of the python setup.py below you will need to set the path to the C++ compiler by running the following script (once you have located the installation path of VS Studio which may differ):

"C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\Tools\VsDevCmd" -arch=x64 

In any case please make sure you have Python 3.10 installed, you may create a conda environnment:

conda create -n Hunyuan3D-2GP python==3.10.9 

Then install the required libraries:

pip install torch==2.5.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/test/cu124
pip install -r requirements.txt
# for texture
cd hy3dgen/texgen/custom_rasterizer
python3 setup.py install
cd ../../..
cd hy3dgen/texgen/differentiable_renderer
bash compile_mesh_painter.sh OR python3 setup.py install (on Windows)

API Usage

We designed a diffusers-like API to use our shape generation model - Hunyuan3D-DiT and texture synthesis model - Hunyuan3D-Paint.

You could assess Hunyuan3D-DiT via:

from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline

pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')
mesh = pipeline(image='assets/demo.png')[0]

The output mesh is a trimesh object, which you could save to glb/obj (or other format) file.

For Hunyuan3D-Paint, do the following:

from hy3dgen.texgen import Hunyuan3DPaintPipeline
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline

# let's generate a mesh first
pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2')
mesh = pipeline(image='assets/demo.png')[0]

pipeline = Hunyuan3DPaintPipeline.from_pretrained('tencent/Hunyuan3D-2')
mesh = pipeline(mesh, image='assets/demo.png')

Please visit minimal_demo.py for more advanced usage, such as text to 3D and texture generation for handcrafted mesh.

Gradio App

You could also host a Gradio App in your own computer via:

pip3 install gradio==3.39.0
python3 gradio_app.py

Don't forget to visit Hunyuan3D for quick use, if you don't want to host yourself.

📑 Open-Source Plan

• Inference Code
• Model Checkpoints
• ComfyUI
• TensorRT Version

🔗 BibTeX

If you found this repository helpful, please cite our report:

@misc{hunyuan3d22025tencent,
    title={Hunyuan3D 2.0: Scaling Diffusion Models for High Resolution Textured 3D Assets Generation},
    author={Tencent Hunyuan3D Team},
    year={2025},
    eprint={2501.12202},
    archivePrefix={arXiv},
    primaryClass={cs.CV}
}

@misc{yang2024hunyuan3d,
    title={Hunyuan3D 1.0: A Unified Framework for Text-to-3D and Image-to-3D Generation},
    author={Tencent Hunyuan3D Team},
    year={2024},
    eprint={2411.02293},
    archivePrefix={arXiv},
    primaryClass={cs.CV}
}

Community Resources

Thanks for the contributions of community members, here we have these great extensions of Hunyuan3D 2.0:

• ComfyUI-3D-Pack
• ComfyUI-Hunyuan3DWrapper
• Hunyuan3D-2-for-windows
• 📦 A bundle for running on Windows | 整合包

Acknowledgements

We would like to thank the contributors to the DINOv2, Stable Diffusion, FLUX, diffusers, HuggingFace, CraftsMan3D, and Michelangelo repositories, for their open research and exploration.

Star History