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
| Aspect | Alpha | Transparency |
|---|---|---|
| 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
}
}
};
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
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 });
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);
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)
);
}
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)
);
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
- Create an Exchange Container to learn how to create geometry with RenderStyle
- Retrieve Data Exchanges to learn how to retrieve geometry data
- Resolve an element’s render style to read instance-level overrides on the consumer side