SMD-Hunyuan3D-2.1-Shape

4-step SMD for image-conditioned 3D generation. The student adapters, standalone inference code and reproducible examples are included. Upstream base components are downloaded separately.

Training code · SMD collection

Example

A ceramic-style SMD letter sculpture reconstructed as untextured geometry. The preview uses soft studio lighting and ground shadows; the exported geometry is unchanged.

Input image	Generated geometry	360° turntable

Download GLB · Four geometry views · Turntable

Seed: 42. Steps: 4. Octree resolution: 256. Turntable: 180 rendered views, 30 fps.

Case settings · Generation receipt · Render settings

Models

Variant	Weights	Steps	Size
default	LoRA	4	0.53 GB

Run

Base: tencent/Hunyuan3D-2.1.

Use Linux, Python 3.12 and an NVIDIA GPU with CUDA support. The included inference code does not import the SMD training repository.

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install huggingface-hub
# Sign in to Hugging Face.
hf auth login
hf download zjwfufu/SMD-Hunyuan3D-2.1-Shape --local-dir SMD-Hunyuan3D-2.1-Shape
cd SMD-Hunyuan3D-2.1-Shape
bash install.sh
python infer.py --output outputs

The installation script pins the CUDA extension sources and requires a C++ compiler, Git and CUDA development tools compatible with the installed PyTorch build. This example used PyTorch cu126 with CUDA 12.8 development tools. --image accepts an RGBA input; the packaged example already has an alpha mask. Shape previews show geometry with neutral lighting.

The first run downloads the upstream base components to the Hunyuan3D cache (~/.cache/hy3dgen by default; configurable with HY3DGEN_MODELS). Plan disk space for those components as well as the released weights; subsequent runs reuse the cache.

For the optional studio lighting used in the example, install Blender 4.x and ffmpeg, then render the exported mesh. This changes only the visualization:

blender --background --python render_studio.py -- outputs/sample.glb --geometry --output outputs/studio --frames 180 --fps 30 --resolution 768 --samples 128

Omit --geometry to keep an asset's existing textures. The built-in preview also renders 180 distinct angles at 30 fps; no frame interpolation is used.

Sampling

The released sampler uses raw final-segment scale 1.0. The raw grid is built before the model-specific time shift. The included runner follows sampling.json; changing only an upstream pipeline's step count does not reproduce the student.

External classifier-free guidance is disabled for the students. Any embedded guidance remains specified in sampling.json.

The supplied loader validates and applies all LoRA matrices and saved replacement tensors, with the recorded merge precision. Omitting replacement tensors or using a different base can change the result.

The runner maps the student sigma to Hunyuan embedding-time 1 - sigma and reverses the native velocity sign before the Euler update.

License and attribution

Base components retain the terms described in the tencent/Hunyuan3D-2.1 model card. Original code notices and bundled licenses are retained. Adapter use remains subject to the applicable base-model terms.

The example input was generated with SMD-FLUX.2-Klein-4B and given an alpha mask before reconstruction. The output preview shows untextured geometry under neutral lighting.