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

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, iterate through the mesh materials and explicitly set the alpha mode:

# 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:

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 or 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:

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: 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: Contains the explicit documentation regarding GLB assets being exported in OPAQUE mode and manual transparency enablement instructions.
• example.py & 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}