TRELLIS.2: from one image to a 3D model, explained for home creators
Imagine taking a picture of an old lantern and turning it into an object you can rotate, relight and place in your own game. TRELLIS.2 brings that workflow within reach: it generates a three-dimensional asset with surface materials from a single image. Understanding how it works also helps explain what a home computer can realistically do with it.
Official repository: Microsoft TRELLIS.2 on GitHub. Explore the project page or try the official online demo.
The people behind the project
The research brings together Microsoft Research, Microsoft AI, Tsinghua University and the University of Science and Technology of China, or USTC. Jianfeng Xiang is the first author, with work carried out during an internship at Microsoft Research; Jiaolong Yang is the corresponding author. The full team comprises Jianfeng Xiang, Xiaoxue Chen, Sicheng Xu, Ruicheng Wang, Zelong Lv, Yu Deng, Hongyuan Zhu, Yue Dong, Hao Zhao, Nicholas Jing Yuan and Jiaolong Yang. Their paper, Native and Compact Structured Latents for 3D Generation, appeared on arXiv on 16 December 2025. Paper and publication history; team affiliations.
What comes out of a photograph
The output is a spatial object rather than another flat picture. Export produces a mesh of vertices and triangles, with textures and materials. The official example saves a GLB file for further use in 3D software. Export example.
A single photograph cannot determine the hidden back of an object. The model proposes that missing structure using patterns learned during training. A convincing lantern may therefore differ from the real lantern behind it. Treat the result as a generated interpretation and inspect the back, underside and openings. It is especially useful for visual creation; accurate dimensions still require measurement.
Training happens before you use it
The researchers train the system with existing 3D assets and their appearance. The published preparation toolkit includes datasets such as ObjaverseXL, ABO, HSSD and TexVerse. At home, you download pretrained weights and generate new results: this is inference. You do not need to repeat the research training. The 4B designation describes roughly four billion generative-model parameters, not the polygon count of the output. Dataset preparation; pretrained model.
From image to object, step by step
- Prepare the image. Preprocessing removes the background or uses an existing alpha channel. DINOv3 extracts numerical visual features to guide generation. Image feature extractor.
- Propose a spatial layout. A first stage predicts which parts of a sparse 3D grid the object occupies.
- Generate its shape. A second stage predicts compact geometry information in the active regions.
- Generate material properties. A third stage uses the image and geometry to generate surface information in the same spatial domain. Pipeline implementation.
- Decode and export. The compact information becomes mesh geometry and surface attributes, ready for conversion to a textured GLB. O-Voxel library.
The generative models use flow matching. In everyday terms, a random numerical starting point becomes an organized object description through a series of image-guided updates. This is a multi-stage sampling process; the published configuration uses 12 steps in each main stage. A seed selects the starting randomness, allowing you to compare alternatives. Model configuration; sampling code.
O-Voxel and the importance of representation
A pixel is a small square in an image; a voxel is a cell in a three-dimensional grid. A sparse grid spends storage on useful regions rather than filling all surrounding empty space. O-Voxel combines shape information and surface attributes. Its Flexible Dual Grid can represent sharp edges, open surfaces and complex interior structures, without requiring every input to become a sealed shell. Think of a thin leaf or a hollow ornament. The representation's capacity does not guarantee that every generated example gets those structures right. O-Voxel documentation.
A Sparse Compression VAE learns to encode detailed assets as shorter spatial descriptions and decode them again. Separate VAEs handle shape and material. Generation works on that compact latent representation. The reported 16× spatial downsampling concerns resolution along spatial axes, not a universal 16× file-size reduction. Similarly, 512³, 1024³ and 1536³ describe voxel-grid resolutions, not image sizes or output triangle counts. Research paper: compression.
Materials that respond to new light
PBR means physically based rendering. Instead of supplying only a color that may already contain photographed highlights, the system models base color, roughness, metallic and opacity. Roughness controls whether reflections are sharp or spread out; metallic changes the material's reflection behavior; opacity describes transparency. This makes the asset more useful under new lighting. Opacity alone is not a complete simulation of every optical effect in glass. Microsoft Research's material explanation.
How fast is it?
| Voxel resolution | Reported shape + material generation |
|---|---|
| 512³ | about 3 seconds |
| 1024³ | about 17 seconds |
| 1536³ | about 60 seconds |
These measurements use an NVIDIA H100. They are not home-PC promises or complete installation-to-export timings. Initial model downloads, loading, previews and export take additional time. Published performance figures.
Three ways to try it at home
| Your situation | Practical route |
|---|---|
| Laptop or PC without a suitable GPU | Try Microsoft's online demo; computation takes place remotely. |
| Linux with a suitable NVIDIA GPU and at least 24 GB VRAM | Investigate the official local setup and compatibility. |
| More experiments without buying a GPU | Consider rented Linux GPU time; check pricing, storage and shutdown arrangements. |
The official demo is a useful starting point. Upload one simple object, rotate the result and try the export. Availability and queues depend on the service. This route uploads your image; a phone may act as its client, but does not perform the generation itself.
Local hardware and installation
The official requirements specify Linux and an NVIDIA GPU with at least 24 GB memory; A100 and H100 are the verified devices. VRAM is GPU memory, separate from system RAM. A computer with 32 GB system RAM and an 8 GB GPU does not meet that 24 GB VRAM requirement. Cards with 8, 12 or 16 GB are below the published requirement; community modifications need separate evaluation. Meeting the memory figure alone does not verify a particular GPU or every mode. Official requirements.
You also need the NVIDIA driver, a suitable CUDA Toolkit, compilation tools, Conda and storage/RAM headroom for weights and builds. The current installer creates Python 3.10 with PyTorch 2.6.0 and CUDA 12.4. PyTorch alone does not replace the toolkit needed to compile extensions. Installer source.
For an already prepared Linux environment, the documented workflow is:
git clone -b main https://github.com/microsoft/TRELLIS.2.git --recursive
cd TRELLIS.2
. ./setup.sh --new-env --basic --flash-attn --nvdiffrast --nvdiffrec --cumesh --o-voxel --flexgemm
conda activate trellis2
python app.py
Open the address printed in the terminal. Start with resolution 512 and one object; use Generate, inspect the preview, then Extract GLB and Download GLB. Initial weight downloads can take much longer than a generation. These research-software installation commands were checked against the documentation, not independently executed for this article. Application source and controls.
The configuration also loads DINOv3 and BRIA RMBG-2.0. Their downloads may require a Hugging Face account, acceptance of conditions and local authentication. An access-denied error may be a model-permission issue rather than a GPU failure. Keep access tokens in local authentication, outside published code.
Windows and other GPU platforms
WSL 2 with Linux and CUDA is a possible experimental route for Windows users. General CUDA support in WSL does not establish a tested TRELLIS.2 installation on every PC. Follow NVIDIA's WSL guide, which manages the GPU driver on the Windows side. The installer contains ROCm branches, but some dependencies are CUDA-only; that does not establish turnkey support for arbitrary AMD cards. Native macOS is not the documented reference path. An online demo remains accessible without reproducing the local research stack. Current platform branches.
A practical lantern-to-game experiment
- Photograph your own lantern or draw a simple prop. Show one unobstructed object, preferably with some front and side visible, against a quiet background.
- Generate at a lower resolution. Save the input and seed. Check the back, handle, base and openings, then compare another seed or a clearer input.
- Export GLB and import it into Blender using glTF 2.0. Inspect scale, orientation, mesh density and materials.
- For a game, reduce polygon and texture budgets, create appropriate collision and consider levels of detail. These are production tasks after generation.
- Import the prepared asset into the game engine. Godot recommends glTF 2.0 and supports GLB. A static object does not automatically acquire animation, a character skeleton or game behavior. Godot import documentation.
Two export details matter. First, the default GLB uses OPAQUE material mode, even if a texture preserves alpha. You must connect alpha and enable a suitable transparent material mode in the destination software. Second, the project already provides a separate workflow for texturing your existing mesh using a reference image. Transparency note; existing-mesh texturing example.
Printing and commercial use
A generated asset can be a starting point for 3D printing. Inspect watertightness, holes, wall thickness, scale and stability first. The model card explicitly notes occasional holes and topology problems. A visually convincing thin surface may not be printable, and PBR metal or color does not transfer into ordinary printing material. For a functional cover or gear, measure and design the critical dimensions in CAD. Known limitations.
The TRELLIS.2 code and main weights use MIT licensing, but dependencies have their own terms. DINOv3 has a separate license. BRIA identifies the available RMBG-2.0 weights as non-commercial and requires a separate agreement for commercial use. Check the components actually used and rights to your input image before building a commercial workflow. TRELLIS.2 license; BRIA terms; DINOv3 terms.
Why the excitement is justified
The exciting part is the shorter journey between an idea and an editable spatial starting point. A hobbyist can explore a scene, an independent developer can prototype props and an experienced artist can investigate variations. Open code, geometry you can edit and materials you can relight give the creator something to develop further. The most useful expectation is creative acceleration with human inspection and finishing.
Editorial note: sources checked on 21 October 2026. We used the paper, official code and model cards; we did not install or independently benchmark TRELLIS.2. Timings are the authors' measurements. Both accompanying images are AI-generated conceptual illustrations, not TRELLIS.2 outputs.