ComfyUI-Trellis2: a node wrapper for Microsoft's Trellis.2 3D generation

What the wrapper covers and how the node set grew

ComfyUI-Trellis2 is a ComfyUI wrapper for Microsoft's TRELLIS.2, which the package description calls native and compact structured latents for 3D generation. The repository is a custom node pack, with the expected layout of an __init__.py and a nodes.py at the root, plus a trellis2/ directory for the model code, example_workflows/ for ready-made graphs and a wheels/ directory for the prebuilt binaries.

The changelog in the README is long and dated, which tells you this is an actively iterated wrapper rather than a thin import. The early entries are the core pipeline: the Trellis2ReconstructMesh node on 2026-01-27, a Continue node on 2026-01-21, Simplify Trimesh on 2026-01-20, and a Tiled decoder plus Smooth Normals and Remesh with Quad on the days around it.

The middle of the changelog is where the model work happens. Sparse Generator with ReconViaGen arrived on 2026-04-04, followed the next day by Extract Images from Video for use with it. The Sparse Structure Resolution was raised to 128 on 2026-03-04, described as experimental for cascade pipelines only and able to increase the details.

April 20, 2026 is the busiest single day in the log. It added a whole multi-view family: Sparse MultiView Generator, ImageCond MultiView Generator, Shape MultiView Generator, Shape Cascade MultiView Generator and Tex Slat MultiView Generator. The same day added Fill Holes Nicely with Meshlib and a fix to the DinoV3 Features Extractor.

After that come the projection work on 2026-05-26, the Render MultiView node with Nvdiffrast on 2026-06-02, and then Pixal3D support through the summer: Pixal3D-T model support on 2026-05-13, a fix to Pixal3D on 2026-05-20, Pixal3D MultiView support on 2026-09-07 and the Mesh Texturing Pixal3D MultiView node on 2026-09-08.

The 2026-04-20 entry also says all workflows were recreated, which tells you the example graphs were rebuilt to match the new node set rather than accumulated.

The node families and the mesh operations around them

The node names describe the pipeline in enough detail to reconstruct it.

Generation comes in a sparse family and a dense family. There is a Sparse Generator, a Sparse Generator with ReconViaGen, a Sparse MultiView Generator, an ImageCond MultiView Generator, a Shape MultiView Generator, a Shape Cascade MultiView Generator, a Tex Slat MultiView Generator, a Mesh with Voxel Multi-View Generator, a Mesh with Voxel Advanced Generator and a Mesh with Voxel Cascade Generator. A Trellis2ReconstructMesh node turns the structured latents into a mesh, and a Mesh Refiner node exists for the multiple-images case.

The mesh post-processing side is extensive. Fill Holes with Meshlib and Fill Holes Nicely with Meshlib, Fill Holes with Cumesh, Remesh with Quad, Remesh, Simplify Trimesh, Batch Simplify Mesh and Export, Smooth Normals, Weld Vertices, Smooth Mesh with PyMeshlab, Smooth Trimesh with PyMeshlab, Reconstruct Mesh with Quad, Voxel to Mesh, and a Mesh Cluster threshold option for texturing.

Voxel to Mesh is worth a note because the changelog says it replaces Remeshing to make a watertight mesh. That is a structural change rather than an addition: a watertight mesh is a closed surface with consistent normals, which matters for downstream use in a 3D package, and getting there by reconstruction rather than by remeshing changes the topology of the result.

Texturing has its own set: Mesh Texturing, Mesh Texturing MultiView, Mesh Texturing Pixal3D MultiView, and PreProcess Image with a remove_background option using the rembg package.

The projection family is newer and more experimental. Projection MultiView Texturing is marked experimental, and there are Projection HighPoly to LowPoly and Render MultiView nodes, plus a FOV Custom MoGe Camera node. The README points at an example workflow named Projection_Blender_Qwen_XViews for the projection nodes, and the tree contains a projection/ directory to match.

Rendering and output complete the set: Render MultiView with Nvdiffrast, Export Mesh, and a Preview 3D node that the Export Mesh node is compatible with, with the mesh exported in the model_3d format.

Installing the wheels, and why the Torch version matters so much

The installation section is the least pleasant part of the README, and it exists because of how many compiled extensions the pipeline needs.

The wrapper ships prebuilt wheels in the wheels/ directory, organised by platform and by Torch version. For a standard Python environment on Torch 2.7.0 the commands are:

python -m pip install ComfyUI/custom_nodes/ComfyUI-Trellis2/wheels/Windows/Torch270/cumesh-1.0-cp311-cp311-win_amd64.whl
python -m pip install ComfyUI/custom_nodes/ComfyUI-Trellis2/wheels/Windows/Torch270/nvdiffrast-0.4.0-cp311-cp311-win_amd64.whl

The packages involved are CuMesh, nvdiffrast, nvdiffrec_render, flex_gemm and o_voxel. CuMesh is the meshing library that several nodes depend on, nvdiffrast and nvdiffrec_render are the differentiable rasteriser used by the rendering nodes, flex_gemm is the flexible GEMM kernel for the attention or linear layers, and o_voxel is the voxel representation used by the cascade generators.

The wheel tags encode the Python version and the Torch ABI, which is why the paths carry cp311 and win_amd64. That means the wheels are specific to a Python minor version, a platform and a Torch build, and the directory layout mirrors that. A Torch 2.7.0 wheel will not load against Torch 2.8, and a cp311 wheel will not load on Python 3.12.

The changelog records the maintenance burden this creates. On 2026-03-08 the CuMesh wheels were updated for Torch 2.7, 2.8 and Linux, and on 2026-02-27 wheels were added for Windows with Python 3.13, Torch 2.10.0 and CUDA 13.1. Each Torch release means a new wheel build for each package.

The README states the tested configuration as Windows 11 with Python 3.11 and Torch 2.7.0 with cu128, which is the reference environment for everything else in the document.

The Python dependencies come from the pyproject.toml and requirements.txt, and they are ordinary: meshlib, requests, pymeshlab, opencv-python, scipy, open3d, plotly, trimesh and rembg. The pyproject.toml names the package trellis2 at version 1.0.27, and includes a Comfy Registry section with the publisher id visualbruno and the display name ComfyUI-Trellis2.

Model prerequisites and the Dinov3 dependency

The requirements section is short and one item dominates it.

You need access to the facebook dinov3 models in order to use Trellis.2, specifically the model at the Hugging Face path facebook/dinov3-vitl16-pretrain-lvd1689m. The instruction is to clone that repository into the ComfyUI models folder under facebook/dinov3-vitl16-pretrain-lvd1689m, so the final path is ComfyUI/models/facebook/dinov3-vitl16-pretrain-lvd1689m.

That dependency is structural rather than incidental. DINOv3 is the image feature extractor, and the changelog shows it as a working part of the pipeline rather than an optional extra. On 2026-04-20 there was a fix to the DinoV3 Features Extractor, and on 2026-04-05 the Extract Images from Video node was added for use with the Sparse Generator with ReconViaGen, which is a reconstruction-from-video path that would lean heavily on per-frame features.

The second prerequisite is conditional. To use the TencentARC/Pixal3D-T model, the natten package is required, and the README links the SHI-Labs NATTEN repository. Natten is the neighbourhood attention extension, and the fact that it is a separate install rather than a wheel in the repository is a clue about how the Pixal3D path differs from the main Trellis.2 path.

The tree also holds a moge/ directory and a vggt/ directory. MoGe is the camera geometry model that the FOV Custom MoGe Camera node belongs to, and VGGT is a visual geometry transformer, which is what a multi-view pipeline needs to place several views of the same object in a common frame before generating from them.

There is also a reconviagen_pipeline.json at the root, which is the reconstruction pipeline expressed as data, and a blackwell_fix.py at the root, whose name suggests a workaround for a specific GPU architecture generation.

The long tail of the changelog, and what it reveals about the state of the code

The entries from February 2026 read like a debugging diary, and they are worth reading as a record of what breaks.

On 2026-02-21 there is a fix for a vertical lines bug, and on 2026-02-17 the Triton cache was disabled in an attempt to fix the same bug. That sequence, a workaround attempted and then a targeted fix a few days later, is a familiar pattern in a numerically sensitive pipeline and a good signal about where the fragile parts are.

On 2026-02-09 the Mesh Texturing node was fixed because the mesh_cluster_threshold_cone_half_angle_rad setting was not being used, which is the kind of bug where a parameter exists in the interface and silently does nothing. On 2026-01-20 there was a crash with remove_infinite_vertices in the PostProcess Mesh node, and on 2026-01-27 an attempt to fix a caching issue.

The sampler options are also worth noting. RK4 and RK5 samplers were added on 2026-03-05 with an explicit warning that processing is much slower so you should reduce the number of steps, and a Heun sampler arrived two days later. Higher-order samplers are for people who need the extra steps to converge to a specific result rather than for speed.

The FP8 models and the sdpa and flash_attn_3 backends arrived on 2026-02-26, which is a memory and throughput story: FP8 halves the weight precision, and the alternative attention backends are there so you can choose one that fits your GPU.

Finally, the bug that the maintainers chased for months. The vertical lines issue appears at least three times between 2026-02-17 and 2026-02-21, first as a Triton cache disabling and then as a fix. It is a useful reminder that a wrapper around a research model inherits the model's numerical fragility, and that the wrapper's own bug log is part of the signal when you are deciding whether to depend on it.

Limits: a research wrapper with a moving base and a narrow platform matrix

The limits are visible in what the README documents and in what it does not.

The first is that this is a wrapper, and the wrapper's job is to expose the model as nodes. The nodes go well beyond pure exposure, with the mesh post-processing family, the projection family and the multi-view family, but the modelling capability itself comes from Trellis.2 and the wrapper does not extend it. If you need a capability Trellis.2 does not have, you are back to Python.

The second is the platform and version matrix. The wheels are per platform, per Python minor version and per Torch build, the tested reference is Windows 11 with Python 3.11 and Torch 2.7.0 with cu128, and the changelog shows the wheel set being rebuilt each time Torch releases. The wheels/ directory in the tree holds the Windows builds; the README's instructions are Windows-specific, and where a Linux or macOS wheel is missing the README does not describe building from source, which is the hard path for CuMesh and nvdiffrast.

The third is that some features are explicitly experimental. Projection MultiView Texturing is labelled experimental, the sparse structure resolution of 128 is described as experimental for cascade pipelines only, and the Pixal3D-T model support is not compatible with all nodes, with the README pointing at the example_workflows folder to see which combinations work. That last point is the important one: compatibility in this wrapper is per node pair, not global.

The fourth is the model access requirement. The Dinov3 weights must be fetched from Hugging Face and placed by hand, and Pixal3D-T additionally needs a compiled attention package. A user without a Hugging Face account and a compatible CUDA GPU is out of luck, and the README gives no guidance for that case.

The fifth is the scale of the surface. The node count is in the dozens and the changelog shows active work on several fronts at once, so the documentation you find may describe a node that has since changed behaviour. The wiki is linked in the pyproject.toml URLs section as the documentation source, with the repository itself as the bug tracker.

This wrapper against running Trellis.2 directly and against the other ComfyUI 3D nodes

Two comparisons make the choice clearer.

The first is against running Trellis.2 from its own repository. The upstream is a research codebase with its own scripts, and it will give you the model behaving exactly as its authors intended, with no nodes, no graph and no wheel juggling. The difference in approach is what the wrapper adds. A ComfyUI graph is a saved, shareable, re-runnable description of a pipeline, and a node for each stage means you can swap a sampler, change the resolution, add a projection branch or a Pixal3D texturing pass without touching Python.

The wrapper also adds the things a research script leaves you to do yourself. The mesh post-processing family, filling holes, remeshing, welding, smoothing, decimation and simplification, is the bulk of it, and it exists because a model that outputs a mesh still leaves you with a mesh you cannot use in a 3D package. Fill Holes with Meshlib, Fill Holes with Cumesh, Remesh with Quad, Weld Vertices and Smooth Normals are all steps you would otherwise script.

The cost is the dependency weight and the fragility. You are now running five compiled extension packages, pinned to a Torch build, on top of a ComfyUI install, and the wrapper's own changelog records months of chasing a rendering artefact.

The second comparison is against the other ComfyUI 3D node packs. There are several, and they differ in which underlying model they wrap and how much post-processing they provide. The distinguishing feature of this one is the multi-view and projection work: a Sparse MultiView Generator and Shape MultiView Generator family, a projection branch that takes a high-poly mesh down to a low-poly one and textures it from multiple views, and Render MultiView with Nvdiffrast for the rasterised renders that the projection path needs. If your use case is a single image to a single mesh, that is more machinery than you need, and a simpler wrapper or the upstream script will serve you better.

Editorial conclusion

Adopt ComfyUI-Trellis2 if you already build image-to-3D pipelines in ComfyUI and want Trellis.2 available as nodes rather than as a standalone script. Do not adopt it if you are on a Torch version or platform for which the wrapper has no prebuilt wheel, since the compile-from-source path is not documented here. Verify first that you have the facebook dinov3 models in the ComfyUI models folder under facebook/dinov3-vitl16-pretrain-lvd1689m, that the natten package is installed if you intend to use the Pixal3D-T model, and that the wheel set you install matches your Torch build exactly.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. visualbruno/ComfyUI-Trellis2 on GitHub