3d Models

TRELLIS family

The TRELLIS family covers microsoft/TRELLIS-image-large (TRELLIS 1, ~1.2B) and microsoft/TRELLIS.2-4B (TRELLIS.2). Both are image-to-3D. Both are MIT licensed and ungated — no token needed to download weights.

There is no usable pip package (trellis-3d on PyPI ships only the pure-Python tree without the CUDA extensions or real dependency set; nothing exists for TRELLIS.2). Both official Spaces vendor the library source (trellis/ or trellis2/) directly in the Space repo. Deploying means duplicating the official Space or copying its tree — not pip install.

Verify against the live official Space before writing files. Every pin below (torch/CUDA/Python versions, wheel URLs) reflects what the official Space shipped as of 2026-07 and tracks the ZeroGPU runtime, which changes. Fetch the current files first — hf download <space-id> --repo-type space --local-dir . or read https://huggingface.co/spaces/<space-id>/raw/main/requirements.txt — and treat those as source of truth.

TRELLIS.2 recipe (prebuilt-wheels strategy)

The microsoft/TRELLIS.2 Space compiles nothing: every CUDA extension is a prebuilt wheel whose tags match the ZeroGPU runtime exactly (+torch2.11.0.cu130, cp312, built for Blackwell sm_120). Its frontmatter pins python_version: 3.12 and sdk_version: 6.1.0, and requirements.txt (as of 2026-07) is:

Wheel tags, torch pin, and python_version: must agree — see 3d-cuda-extensions.md for the tag anatomy. TRELLIS.2 uses flex_gemm for sparse conv (no spconv).

Module-level setup (order matters — env vars before any torch/trellis import):

Keep autotune_cache.json when duplicating. The Space commits a pre-computed flex_gemm autotune cache so kernel autotuning doesn’t re-run on every fresh ZeroGPU worker. Deleting it makes first-request latency much worse.

GPU functions in the official Space: @spaces.GPU(duration=120) on generation (pipeline.run(...) with per-stage sampler params, pipeline_type of 512 / 1024_cascade / 1536_cascade) and @spaces.GPU(duration=120) on GLB extraction (pipeline.decode_latent(...) + o_voxel.postprocess.to_glb(...)). Generation and extraction are split into two GPU calls with latents passed between them as CPU numpy in gr.State — keep that split; it lets users re-extract at different decimation/texture sizes without regenerating.

TRELLIS 1 recipe (JIT-compile strategy)

The trellis-community/TRELLIS Space demonstrates the other viable strategy: compile nvdiffrast + diff-gaussian-rasterization at first boot on a GPU worker, inside @spaces.GPU(duration=600), using the nvcc that ZeroGPU mounts at runtime (/cuda-image/usr/local/cuda-13.0). Its requirements.txt (torch 2.8.0, spconv-cu120==2.3.6, xformers, rembg, no python_version pin → 3.10) installs everything that can come from PyPI; the JIT step handles the rest with:

• TORCH_CUDA_ARCH_LIST="12.0" (Blackwell — nvcc can’t probe a GPU that isn’t attached yet)
• a sitecustomize.py that no-ops torch.utils.cpp_extension._check_cuda_version (torch built for cu128, nvcc is 13.0)
• pip install --no-build-isolation ./extensions/nvdiffrast (vendored source), then the mip-splatting diff-gaussian-rasterization from a shallow git clone
• afterwards, ctypes.CDLL("<cuda-libdir>/libcudart.so.13", mode=ctypes.RTLD_GLOBAL) so the freshly built extensions find the CUDA 13 runtime

Backend env vars, set at the very top of app.py: SPCONV_ALGO=native, ATTN_BACKEND=xformers. Because ZeroGPU is Blackwell, xformers must be forced onto Cutlass kernels (its Flash-Attn-3 dispatch crashes on sm_120) — the Space monkeypatches xformers.ops.memory_efficient_attention to default op=(fmha.cutlass.FwOp, fmha.cutlass.BwOp). Don’t drop that patch when duplicating.

GPU functions: @spaces.GPU(duration=120) for generate-and-extract-GLB (single- and multi-image modes, 120-frame turntable preview video via render_utils.render_video, GLB via postprocessing_utils.to_glb(gs, mesh, simplify=0.95, texture_size=1024)); bare @spaces.GPU for gaussian .ply extraction. Viewer: LitModel3D from gradio_litmodel3d==0.0.1 (installed at runtime with --no-deps if missing). The Space also sets demo.launch(mcp_server=True) — TRELLIS demos double as MCP servers; keep it.

Deploying a finetuned TRELLIS variant

Both pipelines resolve everything from a pipeline.json at the model repo root, so a finetuned checkpoint that keeps the repo layout is a one-line swap:

If the finetuned repo is private, pass the token via env (HF_TOKEN Space secret) — from_pretrained in the vendored trellis code goes through huggingface_hub and picks it up. If the user only has raw checkpoint files (no pipeline.json), copy pipeline.json + config layout from the base repo into their model repo first.

Picking between the two

• TRELLIS.2 — best quality, PBR materials, 3 resolution tiers; heavier (≥24 GB, fine on ZeroGPU large’s 48 GB), Gradio 6, Python 3.12. Default choice for a new Space.
• TRELLIS 1 — lighter (~16 GB), dual gaussian+mesh output (the gaussian .ply path matters if the user wants splats), multi-image conditioning modes, and the community Space is a cleaner codebase to modify. Choose when the user wants gaussians, multi-image input, or minimal VRAM.

Durations and misc

• Generation: duration=120 is what both official Spaces use; TRELLIS.2 at 1536³ pushes ~60s of pure compute on H100-class hardware, so don’t go below 120.
• Call torch.cuda.empty_cache() at the end of each GPU function (both Spaces do) — sequential calls on a warm worker otherwise accumulate.
• TRELLIS.2’s mesh simplify cap: mesh.simplify(16777216) — nvdiffrast’s face-count limit.
• Preprocessing (alpha-bbox crop, resize to ≤1024, background removal) runs on CPU outside the GPU function.

Mesh workhorses: TripoSR, Stable Fast 3D, SPAR3D, Hunyuan3D

Two groups in this file. The fast tier (TripoSR, SF3D, SPAR3D): single-forward-pass image-to-mesh, seconds per generation, small VRAM, simple codebases — pick when the user wants a snappy demo, a high-traffic public Space (short @spaces.GPU durations = less quota per click and better queue priority), or can accept lower fidelity than TRELLIS.2. And Hunyuan3D-2/2.1 (Tencent): two-stage — a flow-matching DiT generates the shape, then an optional multiview-diffusion “Paint” stage textures it — pick when the user wants textured output and TRELLIS.2 doesn’t fit, or when they finetuned a Hunyuan3D DiT (the 2.1 release includes official training code, so finetuned shape checkpoints are common).

Licenses and gating matter here. The two Stability models are gated: auto — the deploying user must accept the license on the model page, and the Space needs their HF_TOKEN as a secret to download weights at startup; if the gate isn’t accepted, from_pretrained fails with 401 at build — check before publishing. The Hunyuan models are ungated (no token needed) but the community license restricts commercial use — surface that before the user flips a Space public. TripoSR is MIT and needs nothing.

Verify against the live official Space before writing files. Pins below are as of 2026-07. Fetch current files via https://huggingface.co/spaces/<id>/raw/main/<path> first.

TripoSR — the minimal recipe (~200-line app)

The simplest working 3D Space on the Hub, and the best starting skeleton for a from-scratch mesh demo. tsr/ package vendored in the Space; frontmatter pins python_version: 3.10.13, sdk_version: 4.20.1.

One CUDA extension, JIT-built at module import (marching cubes):

requirements.txt carries the build toolchain for it (scikit-build-core>=0.10, pybind11>=2.10, cmake, ninja) plus rembg, onnxruntime, trimesh, omegaconf, einops, transformers, Pillow, huggingface-hub. No torch pin (base image). (A prebuilt torchmcubes Blackwell wheel now exists in the dataset described in requirements.md — cleaner than the JIT build when building fresh.)

Preprocessing on CPU, outside the GPU function: rembg background removal → resize_foreground(image, 0.85) → composite onto gray. UI: input image + “marching cubes resolution” slider (32–320) + two gr.Model3D tabs (OBJ and GLB).

Stable Fast 3D — textured output, source-built extensions

sf3d/ vendored; frontmatter python_version: 3.10.13, sdk_version: 4.41.0. Two vendored extension source dirs built at module import (they’re commented out in requirements.txt with a note — the “HF hack”):

texture_baker is a torch CUDAExtension (the CPPFLAGS="-include utility" is required for its build), uv_unwrapper a plain C++ extension. Other deps of note: open_clip_torch, rembg[gpu], pynanoinstantmeshes + gpytoolbox (remeshing), gradio-litmodel3d==0.0.1.

UI controls that earn their place: foreground ratio, remesh (None/Triangle/Quad), target vertex count, texture size (512–2048). Viewer: LitModel3D with selectable HDR environment maps — textured output deserves image-based lighting (see 3d-outputs.md).

SPAR3D — reference code only, don’t duplicate blindly

Two-stage: point-cloud diffusion → mesh, with a gradio_pointcloudeditor step so users can edit the intermediate point cloud before meshing. Distinctive UI idea worth stealing. But the official Space runs on dedicated L4, not ZeroGPU (no import spaces, torch pinned to 2.5.1, real nvcc assumed) and is currently in BUILD_ERROR. To deploy SPAR3D on ZeroGPU you’d port it: add spaces, drop the torch pin, apply the SF3D extension-build pattern (same vendored texture_baker/uv_unwrapper + a prebuilt pynim wheel), and decorate the two stages. Budget real debugging time; propose SF3D instead unless the user specifically needs the point-cloud editing stage. Its background removal uses transparent-background (InSPyReNet) rather than rembg.

Hunyuan3D-2 / 2.1 — textured two-stage generation

Both official Spaces vendor the model code in the Space repo (hy3dgen/ for 2.0; hy3dshape/ + hy3dpaint/ for 2.1) — there’s a setup.py but nothing is pip-installed; imports resolve from cwd. Two native extensions are handled at module-import time in gradio_app.py:

The cp310 wheel means Python 3.10 — pin python_version: "3.10" explicitly when duplicating so a runtime default bump can’t break it.

Requirements notes (2.1) — fully pinned; the non-obvious entries: --extra-index-url https://download.blender.org/pypi/ + bpy==4.0 (Blender-as-pip; installs headless with no display setup — see 3d-outputs.md → Headless Blender — though the Space’s OBJ→GLB conversion actually runs on trimesh+pygltflib); realesrgan==0.3.0 + basicsr==1.4.2 (texture upscaling — needs the Space’s torchvision_fix.py shim, applied at the top of gradio_app.py and again before the texgen import, because basicsr imports the removed torchvision.transforms.functional_tensor); cupy-cuda12x, pymeshlab, xatlas, open3d, trimesh, pygltflib (mesh stack); no torch pin; pydantic==2.10.6 (gradio compat).

Model loading (module level):

GPU decorators: @spaces.GPU(duration=40–60) shape-only; @spaces.GPU(duration=90) (2.0) / @spaces.GPU(duration=180) (2.1 PBR) shape+texture. VRAM (2.1, per its README): ~10 GB shape, ~21 GB texture, ~29 GB both — fits ZeroGPU large, but the full PBR path is the heaviest recipe in these references; don’t shave the duration.

Output path gotcha (2.1): textured meshes export as OBJ first, then convert to GLB via the Space’s convert_utils (obj2gltf with PBR materials) — direct GLB export from the paint pipeline core-dumps. Keep the conversion step when duplicating.

Serving quirk: both official Spaces use a custom <model-viewer> HTML iframe + FastAPI StaticFiles + gr.mount_gradio_app + manual uvicorn.run instead of demo.launch() — which requires calling from spaces import zero; zero.startup() manually before uvicorn. When building fresh rather than duplicating, skip all of this — export a GLB, show it in gr.Model3D/LitModel3D, and let demo.launch() do its job. Only keep the iframe machinery when duplicating wholesale.

Local-run pattern worth copying: 2.1’s gradio_app.py defines a no-op spaces.GPU decorator when not running on Spaces (ENV != "Huggingface"), so the same file runs on a local GPU box unchanged.

Deploying a finetuned Hunyuan3D variant — the official 2.1 release ships training code (hy3dshape/ includes trainers and configs), so “I finetuned Hunyuan3D, make me a demo” is a real request. The shape pipeline resolves subfolder inside the model repo:

If the user’s repo keeps the official layout (config + checkpoint under the dit subfolder), it’s a repo-id swap; if they saved a bare checkpoint, mirror the base repo’s subfolder structure into their repo first. Finetunes are almost always shape-only — keep the stock Paint stage from the base repo for texturing (it conditions on the input image, not the shape checkpoint). Private repo → HF_TOKEN Space secret.

Which Hunyuan variant: 2.1 — PBR texturing, the one with official training code, the default for finetunes, heaviest. 2.0 — lighter, faster (flashvdm), RGB textures, official Space actually running today (known-good duplicate target); -mini and -mv (multiview-conditioned) subfolder variants live in the same repo. Shape-only demo (skip Paint entirely) — halves the dependency surface (no bpy/realesrgan/basicsr/cupy) and cuts duration to 40–60s; offer it when the user just wants geometry.