Request

Response

    Controlling Geometry Opacity: Alpha and Transparency

    The Data Exchange SDK provides two distinct mechanisms for controlling geometry opacity: Alpha (color-level) and Transparency (material-level). Understanding when and how to use each is critical for achieving correct visual output, particularly when converting between Data Exchange and OBJ/MTL file formats, as the MTL material specification uses a single dissolve parameter for opacity representation.

    What is Alpha?

    Alpha is the fourth component in RGBA color values, representing per-color opacity. It operates at the color level, allowing different opacity values for individual vertices or faces. Alpha ranges from 0 (fully transparent) to 255 (fully opaque).

    Important: The OBJ/MTL format does not support alpha channels, so the SDK ignores Alpha when exporting to OBJ/MTL.

    What is Transparency?

    Transparency is a material-level property in RenderStyle, representing overall material transparency. It applies uniformly to entire geometries and ranges from 0.0 (fully opaque) to 1.0 (fully transparent).

    Important: Higher Transparency values mean more transparent (0.0 = opaque, 1.0 = transparent). Note that the MTL d (dissolve) parameter is the inverse — it represents opacity (d=0.0 is transparent, d=1.0 is opaque).

    Compare Alpha and Transparency

    AspectAlphaTransparency
    Level Color (per-vertex/per-face) Material (entire geometry)
    Range 0-255 (integer) 0.0-1.0 (float)
    API new RGBA(r, g, b, alpha) new RenderStyle(name, color, transparency)
    OBJ/MTL export Ignored Written as d parameter
    OBJ/MTL import Defaults to 255 Read from d parameter
    Best for Mesh objects, per-face control File-based geometry (OBJ, STEP)

    Choose Alpha for color-level control

    Use Alpha for:

    • Mesh objects with per-face color control
    • Gradient or variable transparency within a single mesh
    • Programmatically generated geometry
    var mesh = new Autodesk.GeometryUtilities.MeshAPI.Mesh()
    {
        MeshColor = new Color(0.8f, 0.8f, 0.8f, 1.0f),
        Vertices = new List<Vertex>
        {
            new Vertex(0.0, 0.0, 0.0),
            new Vertex(10.0, 0.0, 0.0),
            new Vertex(10.0, 10.0, 0.0)
        },
        Faces = new List<Face>
        {
            new Face()
            {
                Corners = new List<int> { 0, 1, 2 },
                FaceColor = new Color(0.2f, 0.6f, 0.9f, 0.5f)  // Blue, 50% transparent
            }
        }
    };
    
    Show More

    Choose Transparency for material-level control

    Use Transparency for:

    • OBJ/MTL files (import or export)
    • Material-level opacity for entire geometries
    • Glass, water, or other translucent materials
    • File-based workflows where material properties are preserved
    var glassColor = new RGBA(180, 200, 220, 255);
    var glassMaterial = new RenderStyle("Glass", glassColor, 0.7);  // 70% transparent
    
    var geometryProps = new GeometryProperties("window.obj", glassMaterial);
    var geometry = elementDataModel.CreateGeometry(geometryProps);
    

    Understand OBJ/MTL file format behavior

    The OBJ/MTL format does not support alpha channels. MTL files use the d (dissolve) parameter for opacity, which maps to Transparency only.

    Export to OBJ/MTL

    The SDK writes Transparency to the MTL d parameter and ignores Alpha.

    var color = new RGBA(255, 100, 50, 128);  // Alpha ignored
    var style = new RenderStyle("Material", color, 0.75);  // Transparency used
    
    // Generated MTL: d 0.25
    

    Import from OBJ/MTL

    The SDK reads Transparency from the d parameter and defaults Alpha to 255.

    // MTL file: d 0.3
    var assets = Client.GeometriesToInternal(new List<AssetInfo> 
    {
        new AssetInfo { Path = "building.obj" }
    });
    
    // Result: Transparency = 0.7, Alpha = 255
    

    Round-trip conversions

    The SDK preserves Transparency in round-trip conversions.

    var imported = Client.GeometriesToInternal(new List<AssetInfo> 
    {
        new AssetInfo { Path = "glass.obj" }
    });
    
    var exported = Client.InternalToGeometries(new List<AssetInfo> 
    {
        new AssetInfo { Path = imported.First().OutputPath, Styles = imported.First().Styles }
    });
    
    // Transparency preserved
    
    Show More

    Create transparent glass windows

    var elementDataModel = ElementDataModel.Create(Client);
    
    var glassColor = new RGBA(150, 180, 220, 255);
    var glassMaterial = new RenderStyle("Glass", glassColor, 0.7);  // 70% transparent
    
    var windowElement = elementDataModel.AddElement("Window_001", "Glass Window");
    var windowCategory = elementDataModel.Classify(windowElement, ClassificationSystem.Category, "Windows");
    var windowFamily = elementDataModel.Classify(windowElement, ClassificationSystem.Family, "Fixed Window", parent: windowCategory);
    var windowType = elementDataModel.DefineType(system: "Type", name: "1200x1500mm", parent: windowFamily);
    elementDataModel.SetType(windowElement, windowType);
    
    var geometryProps = new GeometryProperties("window.obj", glassMaterial);
    var windowGeometry = elementDataModel.CreateGeometry(geometryProps);
    elementDataModel.SetElementGeometry(windowElement, new List<ElementGeometry> { windowGeometry });
    
    Show More

    Create meshes with per-face transparency

    var gradientMesh = new Autodesk.GeometryUtilities.MeshAPI.Mesh()
    {
        MeshColor = new Color(0.8f, 0.8f, 0.8f, 1.0f),
        Vertices = new List<Vertex>
        {
            new Vertex(0.0, 0.0, 0.0),
            new Vertex(10.0, 0.0, 0.0),
            new Vertex(10.0, 10.0, 0.0),
            new Vertex(0.0, 10.0, 0.0)
        },
        Faces = new List<Face>
        {
            new Face()
            {
                Corners = new List<int> { 0, 1, 2 },
                Normals = new List<Normal> { new Normal(0, 0, 1), new Normal(0, 0, 1), new Normal(0, 0, 1) },
                FaceColor = new Color(0.9f, 0.2f, 0.2f, 1.0f)  // Red, opaque
            },
            new Face()
            {
                Corners = new List<int> { 0, 2, 3 },
                Normals = new List<Normal> { new Normal(0, 0, 1), new Normal(0, 0, 1), new Normal(0, 0, 1) },
                FaceColor = new Color(0.2f, 0.2f, 0.9f, 0.3f)  // Blue, 30% opaque
            }
        }
    };
    
    var meshProps = new GeometryProperties(gradientMesh, "GradientPanel");
    var meshGeometry = elementDataModel.CreateMeshGeometry(meshProps);
    
    Show More

    Import OBJ files with transparent materials

    The SDK automatically reads Transparency from the d parameter.

    var importedAssets = Client.GeometriesToInternal(new List<AssetInfo> 
    {
        new AssetInfo { Path = "building_with_glass.obj" }
    });
    
    // Transparency populated from MTL, Alpha = 255
    

    To synchronize Alpha with Transparency for mesh operations:

    foreach (var style in importedAssets.First().Styles)
    {
        style.DiffuseColor = new RGBA(
            style.DiffuseColor.R,
            style.DiffuseColor.G,
            style.DiffuseColor.B,
            (byte)((1.0 - style.Transparency) * 255)
        );
    }
    
    Show More

    Set Transparency for OBJ/MTL workflows

    Always set Transparency for OBJ/MTL files. The SDK ignores Alpha.

    // Recommended
    var material = new RenderStyle("Glass", new RGBA(180, 200, 220, 255), 0.7);
    
    // Not recommended - Alpha ignored
    var material = new RenderStyle("Glass", new RGBA(180, 200, 220, 76), 0.0);
    

    Preserve file colors with null RenderStyle

    Pass null to preserve file colors or a RenderStyle to override.

    // Preserve colors
    var geometry = elementDataModel.CreateGeometry(
        new GeometryProperties("multicolor_model.obj", null)
    );
    
    // Override colors
    var customMaterial = new RenderStyle("Override", new RGBA(200, 50, 50, 255), 0.8);
    var geometry = elementDataModel.CreateGeometry(
        new GeometryProperties("multicolor_model.obj", customMaterial)
    );
    
    Show More

    Troubleshooting

    Transparent geometry appears solid in OBJ exports

    Cause: Alpha set instead of Transparency.

    Solution: Set Transparency.

    var material = new RenderStyle("Glass", new RGBA(200, 220, 255, 255), 0.8);
    

    Transparency changes don’t affect MTL export

    Cause: Modified Alpha instead of Transparency.

    Solution: Modify Transparency.

    style.Transparency = 0.5;
    

    Multi-colored geometry becomes single color

    Cause: RenderStyle overrides file colors.

    Solution: Pass null to preserve colors.

    var geometry = elementDataModel.CreateGeometry(new GeometryProperties("multicolor.obj", null));
    

    Transparency value appears inverted

    Remember: Higher Transparency values mean more transparent. Transparency = 0.9 means 90% transparent (10% opaque).

    Next steps