# How O-Voxel Handles Arbitrary Topology and Non-Manifold Geometry in 3D Generation

> Discover how O-Voxel uses sparse voxel grids and CUDA-accelerated topology repair to handle arbitrary topology and non-manifold geometry for robust 3D generation.

- Repository: [Microsoft/TRELLIS.2](https://github.com/microsoft/TRELLIS.2)
- Tags: how-to-guide
- Published: 2026-08-03

---

**O-Voxel encodes 3D shapes as sparse voxel grids to represent arbitrary topology—including disconnected components, holes, and non-manifold structures—then applies CUDA-accelerated topology repair via CuMesh utilities to generate clean, manifold meshes only after the generation phase.**

The microsoft/TRELLIS.2 repository introduces O-Voxel, a 3D generation framework that decouples shape representation from mesh constraints. By leveraging sparse voxel grids as its primary data structure, O-Voxel eliminates the topological limitations inherent in traditional mesh-based generators, enabling the creation of complex geometries that would otherwise require intricate manifold preservation during synthesis.

## Sparse Voxel Representation as the Foundation

O-Voxel builds its 3D output on a **sparse voxel grid** rather than a fixed-topology mesh. This representation stores occupied cells independently, allowing the encoding of any topology without connectivity constraints.

The `Voxel` class in [`trellis2/representations/voxel/voxel_model.py`](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/representations/voxel/voxel_model.py) serves as the core container. It holds a sparse coordinate list and attribute tensor, imposing no mesh adjacency requirements:

```python
from trellis2.representations.voxel.voxel_model import Voxel

voxel = Voxel(
    origin=[0.0, 0.0, 0.0],
    voxel_size=0.01,
    coords=coord_tensor,          # (N, 3) integer voxel indices

    attrs=attr_tensor,            # (N, C) per-voxel attributes

    layout={'color': slice(0, 3), 'material': slice(3, 6)},
)

```

Because each voxel exists independently in the coordinate tensor, the representation naturally supports disconnected components, arbitrary genus, and non-manifold configurations without structural preprocessing.

## Differentiable Rasterization Without Topological Constraints

The rendering pipeline operates directly on the sparse voxel set, bypassing the topological restrictions that plague mesh-based differentiable renderers. The `VoxelRenderer.render` method in [`o-voxel/o_voxel/rasterize.py`](https://github.com/microsoft/TRELLIS.2/blob/main/o-voxel/o_voxel/rasterize.py) projects voxels into image space using a CUDA-accelerated rasterizer that processes the voxel list regardless of spatial arrangement.

```python
from o_voxel.rasterize import VoxelRenderer

renderer = VoxelRenderer({'resolution': 512, 'near': 0.1, 'far': 5.0})
rendered = renderer.render(
    position=voxel.position,      # world-space positions

    attrs=voxel.attrs,
    voxel_size=voxel.voxel_size,
    extrinsics=cam_extr,
    intrinsics=cam_int,
)

```

This approach ensures that the rendering gradient flows back to the generator even when the underlying geometry contains non-manifold edges or self-intersections, as the rasterizer treats each voxel as a discrete primitive rather than a face in a connected mesh.

## Topology Repair and Non-Manifold Geometry Resolution

After generation and rasterization, O-Voxel extracts a mesh—typically via Dual-Contouring—and subjects it to rigorous topology cleaning. The post-processing module in [`o-voxel/o_voxel/postprocess.py`](https://github.com/microsoft/TRELLIS.2/blob/main/o-voxel/o_voxel/postprocess.py) utilizes the **CuMesh** library to resolve non-manifold configurations before final output.

### The Post-Processing Pipeline

The `clean_mesh` function executes a sequence of repair operations on the extracted geometry:

- **`mesh.remove_duplicate_faces()`** – Eliminates degenerate faces that would confuse manifold algorithms
- **`mesh.repair_non_manifold_edges()`** – Fixes edges belonging to more than two faces, converting non-manifold structures into valid manifold meshes
- **`mesh.remove_small_connected_components()`** – Discards tiny isolated voxel clusters that represent noise rather than structure
- **`mesh.fill_holes()`** – Closes small perforations that break manifoldness
- **`mesh.unify_face_orientations()`** – Ensures consistent winding order across all faces

These steps appear in both the standard simplification pipeline and an optional remeshing path that rebuilds topology from scratch using Dual-Contouring (lines 40-56 and 70-78 in [`postprocess.py`](https://github.com/microsoft/TRELLIS.2/blob/main/postprocess.py)).

```python
from o_voxel.postprocess import clean_mesh

cleaned_mesh = clean_mesh(
    vertices=raw_vertices,
    faces=raw_faces,
    aabb=aabb,
    grid_size=grid_sz,
    voxel_size=voxel.voxel_size,
    attr_volume=attr_volume,
    attr_layout=voxel.layout,
    remesh=False,                 # Set True to use Dual-Contouring remeshing

)

```

By deferring mesh extraction until after generation, O-Voxel allows the neural network to predict arbitrary topologies during training while guaranteeing manifold outputs for downstream applications.

## Summary

- **Sparse voxel grids** serve as the primary representation in [`trellis2/representations/voxel/voxel_model.py`](https://github.com/microsoft/TRELLIS.2/blob/main/trellis2/representations/voxel/voxel_model.py), enabling disconnected components and non-manifold geometry during the generation phase.
- **CUDA rasterization** in [`o-voxel/o_voxel/rasterize.py`](https://github.com/microsoft/TRELLIS.2/blob/main/o-voxel/o_voxel/rasterize.py) processes voxel primitives independently, supporting arbitrary topology without connectivity constraints.
- **CuMesh-based repair** in [`o-voxel/o_voxel/postprocess.py`](https://github.com/microsoft/TRELLIS.2/blob/main/o-voxel/o_voxel/postprocess.py) resolves non-manifold edges, fills holes, and removes duplicate faces after mesh extraction.
- **Dual-Contouring integration** provides an optional remeshing path that reconstructs topology from scratch while preserving geometric fidelity.

## Frequently Asked Questions

### What is non-manifold geometry in 3D generation?

Non-manifold geometry refers to mesh configurations where edges connect more than two faces or vertices exist in topological configurations that cannot exist in physical 2D manifolds embedded in 3D space. Traditional mesh-based generators often constrain their outputs to prevent these configurations during synthesis, whereas O-Voxel allows them during generation and repairs them afterward.

### Why does O-Voxel use voxels instead of meshes for generation?

Voxels provide **topology-agnostic representation**—each occupied cell is independent, allowing the network to generate arbitrary shapes including holes, handles, and disconnected components without worrying about mesh validity constraints. This decouples the complexity of the generation task from the topological requirements of the final output format.

### How does the topology repair process work in O-Voxel?

After extracting an initial mesh from the voxel grid, O-Voxel passes the geometry through CuMesh utilities that detect and repair non-manifold edges, remove duplicate faces, fill holes, and eliminate small disconnected components. This cleaning stage ensures the final mesh is manifold and suitable for texturing and simulation, regardless of how complex the intermediate voxel topology was.

### Can O-Voxel handle disconnected components and holes?

Yes. Because the primary representation is a sparse coordinate list rather than a connected mesh, O-Voxel naturally supports **disconnected components** and **arbitrary genus** (holes and handles). The post-processing pipeline preserves these features when they represent meaningful geometry while removing noise through the small-component filter.