3D Model Generation from a Single Image with Hunyuan3D 2.1: Setup and Usage Guide

Hunyuan3D, developed by Tencent, is an open-source image-to-3D system that generates a textured 3D mesh from a single reference image. This guide explains step by step how to set up version 2.1 of the model and run it either via code or through the Gradio interface. It's a practical starting point for those working in archviz and interior visualization who want to quickly generate concept furniture, object or accessory meshes.

What you'll learn

By the end of this guide, you will have learned how to generate a mesh (shape) from an image, apply texture to that mesh, and export the result in glb/obj format. You will also have seen how to launch a local Gradio-based interface on your own computer.

Requirements

• Python 3.10 and PyTorch 2.5.1 (tested with CUDA 12.4).

• NVIDIA GPU: at least 10 GB VRAM recommended for shape generation only, 21 GB for texture generation only, and 29 GB VRAM to run both together.

• Hunyuan3D-Shape-v2-1 (3.3 billion parameters) and Hunyuan3D-Paint-v2-1 (2 billion parameters) model weights are downloaded from Hugging Face.

• The system can run on macOS, Windows and Linux.

Installation steps

1. Install PyTorch with CUDA 12.4 support:

pip install torch==2.5.1 torchvision==0.20.1 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

1. Compile the custom rasterizer and differentiable renderer module required for texture generation:

cd hy3dpaint/custom_rasterizer
pip install -e .
cd ../..
cd hy3dpaint/DifferentiableRenderer
bash compile_mesh_painter.sh
cd ../..

1. Download the pretrained weight used for texture upscaling:

wget https://github.com/xinntao/Real-ESRGAN/releases/download/v0.1.0/RealESRGAN_x4plus.pth -P hy3dpaint/ckpt

1. First generate an untextured mesh from an image, then apply texture using the same image:

import sys
sys.path.insert(0, './hy3dshape')
sys.path.insert(0, './hy3dpaint')
from textureGenPipeline import Hunyuan3DPaintPipeline, Hunyuan3DPaintConfig
from hy3dshape.pipelines import Hunyuan3DDiTFlowMatchingPipeline

shape_pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained('tencent/Hunyuan3D-2.1')
mesh_untextured = shape_pipeline(image='assets/demo.png')[0]

paint_pipeline = Hunyuan3DPaintPipeline(Hunyuan3DPaintConfig(max_num_view=6, resolution=512))
mesh_textured = paint_pipeline(mesh_path, image_path='assets/demo.png')

This code block first runs the shape generation pipeline to obtain an untextured mesh, then feeds the same reference image to the texture generation pipeline to apply a physically based (PBR) texture. The resulting mesh is returned as a trimesh object and can be saved in formats such as glb/obj.

1. If you prefer an interface instead of the command line, you can launch the Gradio app locally:

python3 gradio_app.py --model_path tencent/Hunyuan3D-2.1 --subfolder hunyuan3d-dit-v2-1 --texgen_model_path tencent/Hunyuan3D-2.1 --low_vram_mode

This command loads both the shape and texture models and opens a browser-based interface where you can upload an image and generate a mesh; the --low_vram_mode option can help on systems with limited VRAM.

What this means for architectural visualization

Hunyuan3D is a usable tool for 3D artists and interior designers who want to quickly generate concept-level furniture, accessories or sculpture-like objects from a single photo or render image. Since the generated meshes are in glb/obj format, they can be imported into software such as Blender or 3ds Max and placed into scenes. According to comparative benchmarks published by Tencent, Hunyuan3D surpasses other open and closed-source models in terms of geometric detail, fidelity to the conditioning image, and texture quality; however, it should be noted that these results are based on the vendor's own tests and have not been independently verified. Additionally, the full pipeline (shape+texture), which requires 29 GB VRAM, is a hardware demand beyond most office computers, so access to a powerful workstation or cloud GPU is required.

Common pitfalls

• Trying to run both the shape and texture pipelines simultaneously on a GPU with insufficient VRAM can cause errors or crashes; use --low_vram_mode if necessary.

• Reference images with complex backgrounds or multiple objects can cause the model to infer incorrect geometry; single-object images with plain backgrounds are preferred.

• Failing to match your CUDA version with the one in the PyTorch installation command (cu124) will cause installation errors.

Next steps

You can import the generated glb/obj file into Blender or 3ds Max for scaling, material correction, and scene placement. It would also be useful to compare with the previous version, Hunyuan3D 2.0, to test which version best suits your hardware.

Source and license

This guide has been adapted into English from the official installation and usage instructions in the Hunyuan3D-2 and Hunyuan3D-2.1 model cards published by Tencent on Hugging Face. The license on the Hunyuan3D-2.1 model card is listed as "tencent-hunyuan-community" (a custom community license); code samples have been taken from these sources in their original form.