SMD-TRELLIS.2

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

Red panda explorer

The shape and texture students each use four steps. Geometry previews are rendered from the exported GLB with a neutral material and soft studio lighting. The textured turntable uses the GLB base-color texture under three diffuse lights on a pale background.

Input image	Geometry only	Textured turntable

Download GLB · Geometry turntable · Four geometry views · Textured studio view · Material channels · Environment-lit PBR turntable

Seed: 42. Turntables: 180 rendered views, 30 fps.

Case settings · Generation receipt · Geometry render settings · Textured studio settings · Textured turntable settings · Geometry turntable settings

Models

Variant	Weights	Steps	Size
shape	LoRA	4	0.60 GB
texture	LoRA	4	0.30 GB

The shape and texture adapters affect separate stages and are loaded together in the example. Each distilled stage uses four evaluations; upstream sparse-structure generation keeps its own sampler. Four steps does not describe the total computation of the complete 3D pipeline.

Run

Base: microsoft/TRELLIS.2-4B.

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-TRELLIS.2 --local-dir SMD-TRELLIS.2
cd SMD-TRELLIS.2
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. The default preview and turntable show the textured mesh under the included environment lighting. materials.png separately shows the shading, normals and material channels.

The first run downloads the upstream base components to the Hugging Face cache. Plan disk space for those components as well as the released weights; subsequent runs reuse the cache.

The turntable starts from the front at a fixed elevation. Use --preview-yaw to choose another starting view. Render neutral geometry views of an exported GLB with:

python render_geometry.py outputs/sample.glb --output outputs/geometry

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.

Reproduce the pale-background textured turntable shown above from the exported GLB:

python render_geometry.py outputs/sample.glb --textured --output outputs/textured_preview --frames 180 --fps 30 --resolution 768

This diffuse preview uses the base-color texture; the environment-lit PBR turntable and material channels remain available separately.

GPU mesh postprocessing in the exporter is not byte-deterministic: repeated runs can produce different final triangulation and UV packing. Reproducibility checks should compare the sampled geometry/texture inputs and rendered results as well as recording the GLB hash.

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 reads the root config.json, whose shape and texture entries preserve the released stage sampling configurations, and falls back to shape/sampling.json and texture/sampling.json when the root config is absent; 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 shape/sampling.json and texture/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.

License and attribution

Base components retain the terms described in the microsoft/TRELLIS.2-4B 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.