# Why Are Exported GLB Textures Transparent and How to Fix Alpha Blending in TRELLIS.2

> Fix transparent GLB textures from TRELLIS.2. Learn why exported GLB files ignore alpha channels and how to correct alpha blending for accurate rendering.

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

---

**Exported GLB files from microsoft/TRELLIS.2 default to `alphaMode="OPAQUE"`, which ignores the embedded alpha channel and causes textures to render as solid rather than transparent.**

When generating 3D assets with **microsoft/TRELLIS.2**, the exported GLB files contain complete texture data including alpha channels, yet they appear opaque in standard viewers. This behavior stems from the GLTF specification's default material settings, which require explicit configuration to enable **alpha blending**. By adjusting the material properties either during the export process or through post-processing, you can activate transparency support for your generated models.

## Understanding the Root Cause of Opaque GLB Textures

### The GLTF Specification Default

According to the GLTF/GLB specification, a material's **alphaMode** property defaults to `OPAQUE` unless explicitly modified. Consequently, rendering engines ignore the alpha channel in the base color texture even when the channel contains valid transparency data.

As noted in the repository's documentation:

> "The `.glb` file is exported in **OPAQUE** mode by default. Although the alpha channel is preserved within the texture map, it is not active initially. To enable transparency, import the asset into your 3D software and manually connect the texture's alpha channel to the material's opacity or alpha input."

This design choice ensures compatibility with the widest range of rendering engines but requires manual intervention when transparency is desired.

## How to Fix Alpha Blending in TRELLIS.2 GLB Exports

You can resolve transparency issues by setting `alphaMode` to either `BLEND` (for smooth transparency) or `MASK` (for binary cutout transparency). Implement this fix either during the initial export or by modifying the generated file afterward.

### Method 1: Modify the Export Pipeline in postprocess.py

The most efficient approach is to adjust material properties within the `to_glb` pipeline before the file is written. In [`o-voxel/o_voxel/postprocess.py`](https://github.com/microsoft/TRELLIS.2/blob/main/o-voxel/o_voxel/postprocess.py), iterate through the mesh materials and explicitly set the alpha mode:

```python

# Inside o-voxel/o_voxel/postprocess.py before calling mesh.export(...)

for mat in mesh.materials:
    # Enable alpha blending for the material

    mat.alphaMode = "BLEND"          # or "MASK" for binary alpha

    mat.alphaCutoff = 0.5            # optional, used with MASK

    # Ensure the base color texture includes alpha

    if mat.baseColorTexture:
        mat.baseColorTexture.source = "path/to/texture_with_alpha.png"

```

This ensures all exported assets from your TRELLIS.2 instance include the correct alpha configuration automatically.

### Method 2: Post-Process with pygltflib

If you need to fix existing GLB files without regenerating them, use the `pygltflib` library to modify the material definitions:

```python
from pygltflib import GLTF2, Material

gltf = GLTF2().load("sample.glb")

# Assume the first material; adjust all if needed

for mat in gltf.materials:
    mat.alphaMode = "BLEND"          # Enable blending

    # Optionally set a cutoff for MASK mode

    # mat.alphaCutoff = 0.5

gltf.save("sample_blended.glb")

```

This method is ideal for batch processing exported assets or when working with pre-generated GLB files from the [`example.py`](https://github.com/microsoft/TRELLIS.2/blob/main/example.py) or [`example_texturing.py`](https://github.com/microsoft/TRELLIS.2/blob/main/example_texturing.py) workflows.

### Method 3: Adjust Materials Using Trimesh

For Python-based pipelines already using geometric processing, `trimesh` provides direct access to GLTF material properties:

```python
import trimesh

glb = trimesh.load("sample.glb")
for material in glb.visual.materials:
    material.alphaMode = "BLEND"     # trimesh respects GLTF alphaMode

glb.export("sample_blended.glb")

```

This approach integrates seamlessly with existing mesh processing workflows and maintains the texture data while updating the transparency settings.

## Key Implementation Files in the Repository

Understanding the file structure helps locate where **alpha blending** configurations can be modified:

- **[`o-voxel/o_voxel/postprocess.py`](https://github.com/microsoft/TRELLIS.2/blob/main/o-voxel/o_voxel/postprocess.py)**: Core export routine that assembles the mesh, performs UV unwrapping, texture baking, and writes the GLB. Modifying material properties here controls the default alpha mode.
- **[`README.md`](https://github.com/microsoft/TRELLIS.2/blob/main/README.md)**: Contains the explicit documentation regarding GLB assets being exported in `OPAQUE` mode and manual transparency enablement instructions.
- **[`example.py`](https://github.com/microsoft/TRELLIS.2/blob/main/example.py) & [`example_texturing.py`](https://github.com/microsoft/TRELLIS.2/blob/main/example_texturing.py)**: Demonstrate typical usage of `to_glb` and how the exported GLB can be further processed.

## Summary

- **microsoft/TRELLIS.2** exports GLB files with `alphaMode="OPAQUE"` by default, ignoring embedded alpha channels.
- To enable **transparent textures**, change `alphaMode` to `"BLEND"` for smooth transparency or `"MASK"` for binary cutouts.
- Fix transparency either during export in [`o-voxel/o_voxel/postprocess.py`](https://github.com/microsoft/TRELLIS.2/blob/main/o-voxel/o_voxel/postprocess.py) or post-process using `pygltflib` or `trimesh`.
- The `alphaCutoff` parameter (typically `0.5`) controls the threshold when using `MASK` mode.

## Frequently Asked Questions

### Why do my TRELLIS.2 exports appear solid instead of transparent?

The `to_glb` pipeline in microsoft/TRELLIS.2 follows the GLTF specification default of `alphaMode="OPAQUE"`. This setting instructs rendering engines to ignore the alpha channel in your textures, displaying them as fully opaque regardless of the actual texture data.

### What is the difference between BLEND and MASK alpha modes?

`BLEND` enables smooth transparency gradients using the full range of the alpha channel, ideal for glass or semi-transparent materials. `MASK` provides binary transparency (fully opaque or fully transparent) based on an `alphaCutoff` threshold (commonly `0.5`), which is more efficient for foliage or fence materials.

### Can I fix GLB transparency without modifying the TRELLIS.2 source code?

Yes. You can post-process exported files using Python libraries like `pygltflib` or `trimesh` to update the `alphaMode` property. Load the GLB, iterate through materials to set `alphaMode="BLEND"`, and save the modified file without touching the original TRELLIS.2 codebase.

### Which file controls the GLB export settings in TRELLIS.2?

The export logic resides in [`o-voxel/o_voxel/postprocess.py`](https://github.com/microsoft/TRELLIS.2/blob/main/o-voxel/o_voxel/postprocess.py), which handles mesh assembly, UV unwrapping, and GLB generation. This is where the `to_glb` pipeline executes and where you would inject code to modify default material properties before writing the file.