Working with Geometry Parameters
Attach parameters directly to individual geometry objects for Navisworks export and Rhino interoperability. When you export to Navisworks, each geometry piece displays its specific properties (material, thickness, manufacturer) rather than just element-level properties.
Prerequisites
Before working with geometry parameters, ensure you have:
- Data Exchange SDK
- Understanding of asynchronous programming in C#
- Familiarity with creating and managing elements and geometry
- Basic understanding of parameters and the
IParameterinterface - An element with multiple geometries to test with (optional but recommended)
Overview
The SDK supports parameters at two levels: element and geometry.
Element vs Geometry Parameters
| Aspect | Element Parameters | Geometry Parameters |
|---|---|---|
| Attached to | Element (logical object) | Geometry (visual representation) |
| Scope | Entire element | Individual geometry piece |
| Typical uses | Name, type, category, location, fire rating | Material, thickness, finish, manufacturer |
| Navisworks export | Element-level properties | Per-geometry properties |
| Best for | Object-level metadata | Component-level metadata |
| Example | "Door Type: Single Swing" | Frame: "Material: Wood" |
When to Use Geometry Parameters
Use geometry parameters when:
- Exporting to Navisworks where individual geometry pieces need distinct properties
- Working with Rhino where geometry-level metadata is important
- An element contains multiple geometries with different characteristics
- Properties belong to the visual/physical representation rather than the logical object
Example Scenario:
A door element might contain three geometries:
- Frame geometry:
Material=Wood, Finish=Stained, Thickness=2" - Panel geometry:
Material=Glass, Type=Tempered, Thickness=0.5" - Handle geometry:
Material=Brass, Finish=Polished
These properties belong to the specific geometry pieces, not the door element as a whole.
Backward Compatibility
Geometry parameters are additive:
- Exchanges without geometry parameters continue to work normally
- Existing element parameters remain unchanged
- No breaking changes to existing code
- Connectors that don’t use geometry parameters simply ignore them
Migration from Element Parameters
You don’t need to migrate existing element parameters to geometry parameters. Both coexist and serve different purposes:
Keep as element parameters if:
- Property describes the logical object (name, type, location, fire rating)
- Property applies to all geometries in the element
- Property is used for element-level filtering or reporting
Consider moving to geometry parameters if:
- Property describes physical characteristics of specific pieces (material, thickness, coating)
- Different geometries within the same element have different values
- Navisworks users need to select and inspect individual geometry pieces
- Rhino workflows require geometry-level metadata
No action required:
- Existing exchanges load and save normally
- Element parameters remain fully functional
- Add geometry parameters only where needed for new functionality
Create Parameters on Geometry
Add parameters to geometry using the CreateParameter method. This method is asynchronous and returns the created parameter.
Basic Parameter Creation
// Create geometry
var geometry = ElementDataModel.CreateFileGeometry(
filePath: "component.stp",
format: GeometryFormat.Step
);
// Add a string parameter
var materialParam = await geometry.CreateParameter(
new Parameter("Material", "Steel")
);
// Add a numeric parameter
var thicknessParam = await geometry.CreateParameter(
new Parameter("Thickness", 5.5)
);
// Add a boolean parameter
var isLoadBearingParam = await geometry.CreateParameter(
new Parameter("IsLoadBearing", true)
);
Built-in Parameters
Use built-in parameters from the Autodesk.Parameters namespace:
var param = ParameterDefinition.Create(
Autodesk.Parameters.Parameter.MATERIAL,
ParameterDataType.String
);
((StringParameterDefinition)param).Value = "Concrete";
var createdParam = await geometry.CreateParameter(param);
Custom Parameters
Create custom parameters with full metadata:
var schemaId = "exchange.parameter.custom:manufacturer";
var customParam = ParameterDefinition.Create(schemaId, ParameterDataType.String);
customParam.Name = "Manufacturer";
customParam.Description = "Component manufacturer name";
customParam.IsCustomParameter = true;
customParam.GroupID = Group.General.DisplayName();
((StringParameterDefinition)customParam).Value = "ACME Corp";
var createdParam = await geometry.CreateParameter(customParam);
Multiple Geometries with Different Parameters
var element = ElementDataModel.AddElement("door-001", "Front Door");
var doorCategory = ElementDataModel.Classify(element, ClassificationSystem.Category, "Doors");
var doorFamily = ElementDataModel.Classify(element, ClassificationSystem.Family, "Single", parent: doorCategory);
var doorType = ElementDataModel.DefineType(system: "Type", name: "Standard", parent: doorFamily);
ElementDataModel.SetType(element, doorType);
// Frame geometry
var frameGeometry = ElementDataModel.CreateFileGeometry(
filePath: "door-frame.stp",
format: GeometryFormat.Step
);
await frameGeometry.CreateParameter(new Parameter("Material", "Wood"));
await frameGeometry.CreateParameter(new Parameter("Finish", "Stained"));
element.AddGeometry(frameGeometry);
// Panel geometry
var panelGeometry = ElementDataModel.CreateFileGeometry(
filePath: "door-panel.stp",
format: GeometryFormat.Step
);
await panelGeometry.CreateParameter(new Parameter("Material", "Glass"));
await panelGeometry.CreateParameter(new Parameter("Type", "Tempered"));
element.AddGeometry(panelGeometry);
// Handle geometry
var handleGeometry = ElementDataModel.CreateFileGeometry(
filePath: "door-handle.stp",
format: GeometryFormat.Step
);
await handleGeometry.CreateParameter(new Parameter("Material", "Brass"));
await handleGeometry.CreateParameter(new Parameter("Finish", "Polished"));
element.AddGeometry(handleGeometry);
Read Parameters from Geometry
Retrieve parameters using the Parameters property, which returns an IEnumerable<IParameter>.
Enumerate All Parameters
var geometries = await ElementDataModel.GetElementGeometriesByElementsAsync(
ElementDataModel.Elements
);
foreach (var kvp in geometries)
{
var element = kvp.Key;
var elementGeometries = kvp.Value;
foreach (var geometry in elementGeometries)
{
Console.WriteLine($"Geometry parameters for element '{element.Name}':");
foreach (var param in geometry.Parameters)
{
Console.WriteLine($" {param.Name}: {param.Value}");
}
}
}
Find Specific Parameters
// Find parameter by name
var materialParam = geometry.Parameters
.FirstOrDefault(p => p.Name == "Material");
if (materialParam != null)
{
Console.WriteLine($"Material: {materialParam.Value}");
}
// Find parameter by schema ID
var thicknessParam = geometry.Parameters
.FirstOrDefault(p => p.SchemaId == "exchange.parameter.custom:thickness");
if (thicknessParam != null)
{
Console.WriteLine($"Thickness: {thicknessParam.Value}");
}
Filter Geometries by Parameter Values
// Find all steel geometries
var steelGeometries = new List<ElementGeometry>();
foreach (var geometry in allGeometries)
{
var materialParam = geometry.Parameters
.FirstOrDefault(p => p.Name == "Material");
if (materialParam?.Value?.ToString() == "Steel")
{
steelGeometries.Add(geometry);
}
}
Console.WriteLine($"Found {steelGeometries.Count} steel geometries");
Update Parameters
Update existing geometry parameters using the UpdateParameter method for single updates or UpdateParameters for batch updates.
Update Single Parameter
// Find the parameter to update
var materialParam = geometry.Parameters
.FirstOrDefault(p => p.Name == "Material");
if (materialParam != null)
{
// Update the parameter value
var updatedParam = geometry.UpdateParameter(
materialParam.SchemaId,
new ParameterDataType("Aluminum")
);
Console.WriteLine($"Updated material to: {updatedParam.Value}");
}
Batch Update Multiple Parameters
Batch updates are more efficient when updating multiple parameters:
// Prepare updates dictionary
var updates = new Dictionary<string, ParameterDataType>();
var materialParam = geometry.Parameters.FirstOrDefault(p => p.Name == "Material");
var thicknessParam = geometry.Parameters.FirstOrDefault(p => p.Name == "Thickness");
var finishParam = geometry.Parameters.FirstOrDefault(p => p.Name == "Finish");
if (materialParam != null)
updates[materialParam.SchemaId] = new ParameterDataType("Carbon Fiber");
if (thicknessParam != null)
updates[thicknessParam.SchemaId] = new ParameterDataType(3.5);
if (finishParam != null)
updates[finishParam.SchemaId] = new ParameterDataType("Matte");
// Apply all updates at once
var updatedParams = geometry.UpdateParameters(updates);
foreach (var param in updatedParams)
{
Console.WriteLine($"Updated {param.Name} to {param.Value}");
}
Update with Type Safety
// Get the parameter
var thicknessParam = geometry.Parameters
.FirstOrDefault(p => p.Name == "Thickness");
if (thicknessParam != null)
{
// Ensure type-safe update
if (thicknessParam.Value is double)
{
var updated = geometry.UpdateParameter(
thicknessParam.SchemaId,
new ParameterDataType(6.75)
);
}
}
Delete Parameters
Remove parameters from geometry using the DeleteParameter method.
Delete Single Parameter
// Find the parameter to delete
var obsoleteParam = geometry.Parameters
.FirstOrDefault(p => p.Name == "TemporaryMark");
if (obsoleteParam != null)
{
bool deleted = geometry.DeleteParameter(obsoleteParam.SchemaId);
if (deleted)
{
Console.WriteLine($"Deleted parameter: {obsoleteParam.Name}");
}
}
Delete Multiple Parameters
// Delete all custom parameters
var customParams = geometry.Parameters
.Where(p => p.SchemaId.StartsWith("exchange.parameter.custom:"))
.ToList();
foreach (var param in customParams)
{
bool deleted = geometry.DeleteParameter(param.SchemaId);
Console.WriteLine($"Deleted {param.Name}: {deleted}");
}
Conditional Deletion
// Delete parameters with null or empty values
var emptyParams = geometry.Parameters
.Where(p => p.Value == null || string.IsNullOrEmpty(p.Value.ToString()))
.ToList();
int deletedCount = 0;
foreach (var param in emptyParams)
{
if (geometry.DeleteParameter(param.SchemaId))
{
deletedCount++;
}
}
Console.WriteLine($"Deleted {deletedCount} empty parameters");
Complete Workflow Example
This example demonstrates a complete workflow for Navisworks export with geometry-level parameters:
// Create element representing a structural column
var column = ElementDataModel.AddElement("col-A1", "Column A1");
var columnCategory = ElementDataModel.Classify(column, ClassificationSystem.Category, "Structural Columns");
var columnFamily = ElementDataModel.Classify(column, ClassificationSystem.Family, "Columns", parent: columnCategory);
var columnType = ElementDataModel.DefineType(system: "Type", name: "W14x90", parent: columnFamily);
ElementDataModel.SetType(column, columnType);
// Add element-level parameters
await column.CreateInstanceParameterAsync(
new Parameter("LoadCapacity", "500 kN")
);
await column.CreateInstanceParameterAsync(
new Parameter("FloorLevel", "Level 3")
);
// Create base plate geometry with specific properties
var basePlateGeom = ElementDataModel.CreateFileGeometry(
filePath: "base-plate.stp",
format: GeometryFormat.Step,
renderStyle: new RenderStyle { Color = new Color(128, 128, 128) }
);
await basePlateGeom.CreateParameter(new Parameter("Material", "Steel ASTM A36"));
await basePlateGeom.CreateParameter(new Parameter("Thickness", 1.5));
await basePlateGeom.CreateParameter(new Parameter("Coating", "Galvanized"));
await basePlateGeom.CreateParameter(new Parameter("Manufacturer", "Steel Co"));
// Create column shaft geometry
var shaftGeom = ElementDataModel.CreateFileGeometry(
filePath: "column-shaft.stp",
format: GeometryFormat.Step,
renderStyle: new RenderStyle { Color = new Color(100, 100, 100) }
);
await shaftGeom.CreateParameter(new Parameter("Material", "Steel ASTM A992"));
await shaftGeom.CreateParameter(new Parameter("Section", "W14x90"));
await shaftGeom.CreateParameter(new Parameter("Length", 144.0));
await shaftGeom.CreateParameter(new Parameter("Weight", "90 lb/ft"));
// Create cap plate geometry
var capPlateGeom = ElementDataModel.CreateFileGeometry(
filePath: "cap-plate.stp",
format: GeometryFormat.Step,
renderStyle: new RenderStyle { Color = new Color(128, 128, 128) }
);
await capPlateGeom.CreateParameter(new Parameter("Material", "Steel ASTM A36"));
await capPlateGeom.CreateParameter(new Parameter("Thickness", 1.0));
await capPlateGeom.CreateParameter(new Parameter("Coating", "Painted"));
// Attach geometries to element
column.AddGeometry(basePlateGeom);
column.AddGeometry(shaftGeom);
column.AddGeometry(capPlateGeom);
// Save the exchange
await ElementDataModel.SaveExchangeAsync();
// When exported to NWC and opened in Navisworks:
// - Users can select the entire column and see element-level properties (LoadCapacity, FloorLevel)
// - Users can select individual geometry pieces and see their specific properties
// - Base plate: Material, Thickness, Coating, Manufacturer
// - Shaft: Material, Section, Length, Weight
// - Cap plate: Material, Thickness, Coating
Best Practices
Parameter Naming
Use consistent, descriptive names for geometry parameters:
// Good - clear and consistent
await geometry.CreateParameter(new Parameter("MaterialType", "Steel"));
await geometry.CreateParameter(new Parameter("ThicknessInInches", 2.5));
await geometry.CreateParameter(new Parameter("ManufacturerName", "ACME"));
// Avoid - inconsistent and unclear
await geometry.CreateParameter(new Parameter("mat", "Steel"));
await geometry.CreateParameter(new Parameter("t", 2.5));
await geometry.CreateParameter(new Parameter("mfg", "ACME"));
Error Handling
Always handle potential errors when working with parameters:
try
{
var param = await geometry.CreateParameter(new Parameter("Material", "Steel"));
Console.WriteLine($"Created parameter: {param.Name}");
}
catch (ArgumentNullException ex)
{
Console.WriteLine($"Invalid parameter definition: {ex.Message}");
}
catch (ArgumentException ex)
{
Console.WriteLine($"Parameter already exists: {ex.Message}");
}
catch (Exception ex)
{
Console.WriteLine($"Unexpected error: {ex.Message}");
}
Performance Considerations
Use batch operations when updating multiple parameters:
// Efficient - single operation
var updates = new Dictionary<string, ParameterDataType>
{
{ param1.SchemaId, new ParameterDataType("Value1") },
{ param2.SchemaId, new ParameterDataType(42.0) },
{ param3.SchemaId, new ParameterDataType(true) }
};
geometry.UpdateParameters(updates);
// Inefficient - multiple operations
geometry.UpdateParameter(param1.SchemaId, new ParameterDataType("Value1"));
geometry.UpdateParameter(param2.SchemaId, new ParameterDataType(42.0));
geometry.UpdateParameter(param3.SchemaId, new ParameterDataType(true));
Schema IDs
Use meaningful schema IDs for custom parameters:
// Good - descriptive namespace
var schemaId = "exchange.parameter.structural:loadCapacity";
var param = ParameterDefinition.Create(schemaId, ParameterDataType.Float);
// Avoid - generic or unclear
var schemaId = "custom:param1";
Parameter Persistence
Geometry parameters persist through the exchange lifecycle:
- Parameters are saved when calling
SaveExchangeAsync() - Parameters are included in exchange revisions
- Parameters are exported to NWC format for Navisworks
- Parameters are available when loading exchanges in other connectors
Troubleshooting
Duplicate Parameter Names
Problem: Attempting to create a parameter with a name that already exists.
await geometry.CreateParameter(new Parameter("Material", "Steel"));
await geometry.CreateParameter(new Parameter("Material", "Aluminum")); // Throws exception
Solution: Check if the parameter exists before creating, or use UpdateParameter instead:
var existing = geometry.Parameters.FirstOrDefault(p => p.Name == "Material");
if (existing != null)
{
geometry.UpdateParameter(existing.SchemaId, new ParameterDataType("Aluminum"));
}
else
{
await geometry.CreateParameter(new Parameter("Material", "Aluminum"));
}
Updating Non-Existent Parameters
Problem: Calling UpdateParameter on a parameter that doesn’t exist returns an empty result.
var updated = geometry.UpdateParameter("non-existent-schema-id", new ParameterDataType("value"));
// updated is null or empty
Solution: Verify the parameter exists before updating:
var param = geometry.Parameters.FirstOrDefault(p => p.SchemaId == schemaId);
if (param != null)
{
geometry.UpdateParameter(schemaId, new ParameterDataType("value"));
}
else
{
// Parameter doesn't exist, create it instead
await geometry.CreateParameter(new Parameter("ParameterName", "value"));
}
Type Mismatch on Update
Problem: Attempting to update a parameter with an incompatible type.
// Parameter was created as double
await geometry.CreateParameter(new Parameter("Thickness", 5.5));
// Attempting to update with string fails
geometry.UpdateParameter(param.SchemaId, new ParameterDataType("InvalidType"));
Solution: Ensure type consistency:
var param = geometry.Parameters.FirstOrDefault(p => p.Name == "Thickness");
if (param != null && param.Value is double)
{
geometry.UpdateParameter(param.SchemaId, new ParameterDataType(6.75)); // Correct type
}
Performance with Many Parameters
Problem: Creating or updating hundreds of parameters individually is slow.
// Slow - individual operations
foreach (var prop in properties)
{
await geometry.CreateParameter(new Parameter(prop.Name, prop.Value));
}
Solution: Use batch operations when possible:
// Better - batch update (for updates)
var updates = new Dictionary<string, ParameterDataType>();
foreach (var prop in properties)
{
var existing = geometry.Parameters.FirstOrDefault(p => p.Name == prop.Name);
if (existing != null)
{
updates[existing.SchemaId] = new ParameterDataType(prop.Value);
}
}
geometry.UpdateParameters(updates);
// Note: CreateParameter doesn't have a batch method,
// but is already async so you can await multiple in parallel
var tasks = properties.Select(p =>
geometry.CreateParameter(new Parameter(p.Name, p.Value))
);
await Task.WhenAll(tasks);
Memory Issues with Large Geometry Collections
Problem: Loading parameters for thousands of geometries consumes excessive memory.
Solution: Process geometries in batches:
// Instead of loading all at once
var allGeometries = await ElementDataModel.GetElementGeometriesByElementsAsync(
ElementDataModel.Elements
);
// Process in batches
var batchSize = 100;
var elements = ElementDataModel.Elements.ToList();
for (int i = 0; i < elements.Count; i += batchSize)
{
var batch = elements.Skip(i).Take(batchSize).ToList();
var geometries = await ElementDataModel.GetElementGeometriesByElementsAsync(batch);
// Process this batch
foreach (var kvp in geometries)
{
foreach (var geom in kvp.Value)
{
ProcessGeometryParameters(geom);
}
}
}
See Also
- Creating Geometry - Learn how to create different types of geometry
- Working with In-Memory Geometry - Manage geometry data in memory
- Controlling Geometry Opacity - Control visual properties
- Create an Exchange Container - Element parameters
- Update an Exchange Container - Update workflows