TRELLIS.2-4B

TRELLIS.2-4B

Microsoft's 4B image to 3D model that turns a single picture into a textured 3D mesh with PBR materials, at resolutions up to 1536, for people with a large NVIDIA GPU.

Made by microsoft on Hugging Face. These notes are Mindket's, written from its model page and model card; the model's own files and license are on Hugging Face.

About

What it is: TRELLIS.2-4B is Microsoft's model for turning a single image into a 3D asset. The output is a mesh with PBR materials, which covers color, opacity and how light reacts. The model is a 4 billion parameter flow-matching transformer. It works on a sparse voxel structure called O-Voxel.

O-Voxel stores both shape and appearance. It handles open surfaces, non-manifold geometry and closed shapes without a lossy conversion step.

Who it suits: It suits 3D artists, game developers and researchers who have a strong NVIDIA GPU and want a 3D draft from a picture. The card asks for at least 24 GB of GPU memory.

Industry | Who uses it | How they use it | Example
Games and media | 3D artists | Turn concept art into a starting mesh | A prop built from one picture
Product design | Designers | Draft a 3D model from a product photo | A rough model of a gadget
Research | Graphics researchers | Study sparse voxel generation | Testing at several resolutions
Software | Developers | Add image to 3D to a pipeline | An asset generator for a tool

Skip it if you have no NVIDIA GPU with 24 GB, or you need a Windows setup, since the card tests Linux only.

Where to use it:

• Linux with an NVIDIA GPU, which is the tested setup
• Python with the project's own trellis2 library
• The official code repository, which holds the install steps
• Windows, macOS or Linux, with Python, for the file download alone

Use case | Who | What they get back
Image to 3D | Artists and developers | A mesh with PBR materials from one picture
Shape-conditioned texturing | 3D artists | Textures for an input mesh and reference image
Mesh and O-Voxel conversion | Researchers | Fast conversion between the two forms

How to set it up: You need a few things in place first.

• Linux, the only system the card says is tested
• An NVIDIA GPU with at least 24 GB, with A100 and H100 verified
• The CUDA Toolkit to compile some packages, with version 12.4 recommended
• Conda to manage dependencies, and Python 3.8 or newer

1. Follow the official code repository for installation and dependencies.
2. Download the model files, or let the pipeline fetch them by name.
3. Run the Python script from the next section.

pip install -U huggingface_hub
hf download microsoft/TRELLIS.2-4B

How to use it: You set up the environment, load the pipeline from the model name, open an image and run the pipeline. The result is a mesh, which you can simplify before rendering because of a limit in the renderer.

import os
os.environ['OPENCV_IO_ENABLE_OPENEXR'] = '1'
os.environ["PYTORCH_CUDA_ALLOC_CONF"] = "expandable_segments:True"  # Can save GPU memory
import cv2
import imageio
from PIL import Image
import torch
from trellis2.utils import render_utils
from trellis2.renderers import EnvMap
import o_voxel

# 1. Setup Environment Map
envmap = EnvMap(torch.tensor(
    cv2.cvtColor(cv2.imread('assets/hdri/forest.exr', cv2.IMREAD_UNCHANGED), cv2.COLOR_BGR2RGB),
    dtype=torch.float32, device='cuda'
))

# 2. Load Pipeline
pipeline.cuda()

# 3. Load Image & Run
image = Image.open("assets/example_image/T.png")
mesh = pipeline.run(image)[0]
mesh.simplify(16777216) # nvdiffrast limit

Put your own value in its key setting first.

Resolution | Time on an H100
512 | about 3 seconds
1024 | about 17 seconds
1536 | about 60 seconds

Example: You run the script on the example image from the repository. The pipeline returns a mesh, and the call that follows simplifies it. On an H100, a 512 resolution run takes about 3 seconds and a 1536 run about 60 seconds.

For newcomers and experts: Start at the lowest resolution, which is the quickest, and use one clear picture of a single object. Check the result for small holes before you use it anywhere.

The sparse 3D VAE downsamples space by a factor of 16. A 1024 cubed asset is encoded into only about 9.6K latent tokens. The card says this costs negligible perceptual quality. The model is a pre-trained foundation model with no preference alignment, so style varies and you may need to try a few inputs.

Title: Inference time on an H100, from the card
Resolution 512: 3 seconds
Resolution 1024: 17 seconds
Resolution 1536: 60 seconds

Set up the environment and load the pipeline
Open a single image
Run the pipeline
Get a mesh with PBR materials

Good to know:

• License: MIT
• Cost to run: none named, but you need an NVIDIA GPU with at least 24 GB
• Data it reaches: it downloads files from Hugging Face onto your machine and reads the images you give it
• Not for: strictly watertight geometry without post-processing, since raw meshes can have small holes, and the card names scripts for filling them

On Hugging Face, 13 November 2026

• Task: image to 3d
• Library: trellis2
• Downloads in the last 30 days: 2,566,439
• Likes: 1,481
• License: mit
• Languages: en
• Quantized versions: 3
• Fine-tunes: 7
• Tags: trellis2, image-to-3d

Links

• Model: https://huggingface.co/microsoft/TRELLIS.2-4B
• Files: https://huggingface.co/microsoft/TRELLIS.2-4B/tree/main

Get the model

Download its files with Hugging Face's command line:

pip install -U huggingface_hub
hf download microsoft/TRELLIS.2-4B

Then follow the usage in its model card. Nothing in this kit runs by itself.