Working with In-Memory Geometry
The in-memory geometry feature retrieves geometry data directly in memory instead of reading from temporary disk files.
Prerequisites
Before using in-memory geometry, ensure you have:
- Data Exchange SDK
- Understanding of asynchronous programming in C#
- Familiarity with
IDisposablepattern and resource management - Sufficient system memory for your geometry data
Overview
By default, when you read geometry from an exchange, the SDK downloads geometry assets and saves them as temporary files on disk. Your code then receives FileGeometry objects containing file paths to these temporary files.
With the in-memory geometry feature, you can configure the SDK to load geometry data directly into memory and return MemoryStreamGeometry objects that provide stream-based access to the geometry data without disk I/O.
Benefits
- Eliminates disk I/O overhead for improved performance
- Enables deployment in environments with restricted disk access
- Provides direct stream-based access to geometry data
- Reduces latency by removing file system operations
Considerations
- Requires sufficient system memory to hold geometry data
- Requires explicit disposal of
MemoryStreamGeometryobjects - Best suited for scenarios where geometry fits in available memory
- May not be appropriate for extremely large geometry files
Retrieval Methods
The SDK provides two methods for retrieving geometry. Both support in-memory retrieval via GeometryOutputOptions:
| Method | Use Case |
|---|---|
GetElementGeometriesAsync |
Geometry assigned to specific elements (most common) |
GetGeometriesAsync |
Geometry assigned at the model/root level |
This tutorial focuses on GetElementGeometriesAsync. For model-level geometry, see Retrieving Model-Level Geometry.
When to Use In-Memory Geometry
Appropriate Scenarios
In-memory geometry is well-suited for the following scenarios:
- Cloud or containerized applications where disk I/O is slow or restricted
- High-performance processing of multiple geometry files
- Streaming workflows that pipe geometry data to other systems or APIs
- Temporary geometry processing with immediate disposal
- Deployments in Docker or Kubernetes with ephemeral containers
Scenarios to Avoid
In-memory geometry may not be appropriate for:
- Geometry files that exceed available system memory
- Memory-constrained environments
- Long-term storage requirements
- Applications where file-based processing is sufficient
Enable In-Memory Geometry
To enable in-memory geometry retrieval, set the ReturnGeometryAsMemoryStream property to true on the GeometryOutputOptions object when calling GetElementGeometriesAsync:
// Configure options to return geometry as memory streams
var geometryOptions = new GeometryOutputOptions
{
ReturnGeometryAsMemoryStream = true,
GeometryFilters = GeometryFilters.All
};
// Retrieve geometries - they will be returned as MemoryStreamGeometry
var geometries = await dataModel.GetElementGeometriesAsync(
elements,
cancellationToken,
geometryOptions
);
Work with MemoryStreamGeometry
When in-memory geometry is enabled, the SDK returns MemoryStreamGeometry objects instead of FileGeometry objects.
API Reference
The MemoryStreamGeometry class provides the following members:
| Member | Type | Description |
|---|---|---|
GetStream() |
Method | Returns a MemoryStream containing geometry data with position reset to 0 |
SizeInBytes |
Property | Gets the size of the geometry data in bytes |
Format |
Property | Gets the geometry format (Step, Obj, Ifc, Bimdex, etc.) |
RenderStyle |
Property | Gets the associated render style |
Dispose() |
Method | Releases memory resources. Must be called to prevent memory leaks. |
Important
You must callDispose()or use ausingstatement to release memory resources and prevent memory leaks.
Basic Usage Example
var geometryOptions = new GeometryOutputOptions
{
ReturnGeometryAsMemoryStream = true
};
var geometries = await dataModel.GetElementGeometriesAsync(
elements,
cancellationToken,
geometryOptions
);
foreach (var elementGeometries in geometries.Values)
{
foreach (var geometry in elementGeometries)
{
// Use using statement to ensure disposal
using (var memoryGeometry = geometry as MemoryStreamGeometry)
{
if (memoryGeometry != null)
{
Console.WriteLine($"Format: {memoryGeometry.Format}");
Console.WriteLine($"Size: {memoryGeometry.SizeInBytes:N0} bytes");
// Access the geometry data stream
var stream = memoryGeometry.GetStream();
// Process the stream (e.g., send to API, parse, etc.)
await ProcessGeometryStream(stream, memoryGeometry.Format);
}
} // Automatically disposed here
}
}
Dispose Resources Properly
MemoryStreamGeometry implements IDisposable and must be disposed to release memory resources. Failure to dispose causes memory leaks.
Important
Always disposeMemoryStreamGeometryobjects using ausingstatement or explicitDispose()call to prevent memory leaks.
Recommended Pattern: Using Statement
var geometries = await dataModel.GetElementGeometriesAsync(
elements,
cancellationToken,
new GeometryOutputOptions { ReturnGeometryAsMemoryStream = true }
);
foreach (var elementGeometries in geometries.Values)
{
foreach (var geometry in elementGeometries)
{
// Using statement ensures disposal even if exceptions occur
using (var memoryGeometry = geometry as MemoryStreamGeometry)
{
if (memoryGeometry != null)
{
var stream = memoryGeometry.GetStream();
// Process the stream
await ProcessGeometry(stream, memoryGeometry.Format);
}
} // Automatically disposed here
}
}
Alternative Pattern: Try-Finally
MemoryStreamGeometry memoryGeometry = null;
try
{
var geometries = await dataModel.GetElementGeometriesAsync(
elements,
cancellationToken,
new GeometryOutputOptions { ReturnGeometryAsMemoryStream = true }
);
var firstGeometry = geometries.Values.FirstOrDefault()?.FirstOrDefault();
memoryGeometry = firstGeometry as MemoryStreamGeometry;
if (memoryGeometry != null)
{
var stream = memoryGeometry.GetStream();
await ProcessGeometry(stream, memoryGeometry.Format);
}
}
finally
{
memoryGeometry?.Dispose();
}
Incorrect Pattern: No Disposal
// Incorrect - causes memory leak
var geometries = await dataModel.GetElementGeometriesAsync(
elements,
cancellationToken,
new GeometryOutputOptions { ReturnGeometryAsMemoryStream = true }
);
foreach (var geometry in geometries.Values.First())
{
var memoryGeometry = geometry as MemoryStreamGeometry;
var stream = memoryGeometry.GetStream();
// Process...
// WARNING: No disposal - causes memory leak
}
Complete Example
The following example demonstrates processing in-memory geometry for all elements in an exchange:
public async Task ProcessExchangeGeometryInMemory(
IElementDataModel dataModel,
CancellationToken cancellationToken)
{
// Configure options for in-memory geometry
var geometryOptions = new GeometryOutputOptions
{
ReturnGeometryAsMemoryStream = true,
GeometryFilters = GeometryFilters.Brep | GeometryFilters.Mesh,
BrepOutputFormat = BrepOutputFormat.STEP,
MeshOutputFormat = MeshOutputFormat.OBJ
};
try
{
// Get element list for count validation
var elementList = dataModel.Elements.ToList();
// Get geometries for all elements
var geometries = await dataModel.GetElementGeometriesAsync(
elementList,
cancellationToken,
geometryOptions
);
// Note: GetElementGeometriesAsync may return partial results if some
// elements fail to translate. Validate the count if completeness is required.
if (geometries.Count != elementList.Count)
{
var missing = elementList.Count - geometries.Count;
Console.WriteLine($"Warning: {missing} elements failed geometry translation");
}
Console.WriteLine($"Retrieved geometry for {geometries.Count} elements");
// Process each element's geometries
foreach (var kvp in geometries)
{
var element = kvp.Key;
var elementGeometries = kvp.Value;
Console.WriteLine($"\nElement: {element.Name} ({element.Id})");
Console.WriteLine($"Geometries: {elementGeometries.Count()}");
foreach (var geometry in elementGeometries)
{
// Use using statement for automatic disposal
using (var memoryGeometry = geometry as MemoryStreamGeometry)
{
if (memoryGeometry == null)
continue;
Console.WriteLine($" Format: {memoryGeometry.Format}");
Console.WriteLine($" Size: {memoryGeometry.SizeInBytes:N0} bytes");
// Get the stream (position is reset to 0)
var stream = memoryGeometry.GetStream();
// Process based on format
switch (memoryGeometry.Format)
{
case GeometryFormat.Step:
await ProcessStepGeometry(stream);
break;
case GeometryFormat.Obj:
await ProcessObjGeometry(stream);
break;
case GeometryFormat.Ifc:
await ProcessIfcGeometry(stream);
break;
default:
Console.WriteLine($" Unsupported format: {memoryGeometry.Format}");
break;
}
} // Disposed here automatically
}
}
}
catch (OutOfMemoryException ex)
{
Console.WriteLine($"Out of memory: {ex.Message}");
// Consider falling back to file-based geometry
throw;
}
catch (Exception ex)
{
Console.WriteLine($"Error processing geometry: {ex.Message}");
throw;
}
}
private static readonly HttpClient _httpClient = new HttpClient();
private async Task ProcessStepGeometry(MemoryStream stream)
{
// Example: Send to external API
var content = new StreamContent(stream);
content.Headers.ContentType = new MediaTypeHeaderValue("application/step");
var response = await _httpClient.PostAsync(
"https://api.example.com/geometry/process",
content
);
response.EnsureSuccessStatusCode();
}
private async Task ProcessObjGeometry(MemoryStream stream)
{
// Example: Parse OBJ data
stream.Position = 0;
using (var reader = new StreamReader(stream, leaveOpen: true))
{
string line;
int vertexCount = 0;
int faceCount = 0;
while ((line = await reader.ReadLineAsync()) != null)
{
if (line.StartsWith("v "))
vertexCount++;
else if (line.StartsWith("f "))
faceCount++;
}
Console.WriteLine($" Vertices: {vertexCount}, Faces: {faceCount}");
}
}
private async Task ProcessIfcGeometry(MemoryStream stream)
{
// Example: Save to cloud storage
await UploadToCloudStorage(stream, "geometry.ifc");
}
Handling Partial Results
GetElementGeometriesAsync may return fewer geometries than requested when individual elements fail to translate. The SDK logs errors for failed elements and returns successfully translated geometries.
Why Partial Results Occur
Individual elements may fail due to:
- Unsupported geometry formats
- Corrupted geometry data
- Translation engine limitations
Rather than failing the entire operation, the SDK processes what it can.
Validating Results
For operations requiring complete data, validate the result count:
var elementList = dataModel.Elements.ToList();
var geometries = await dataModel.GetElementGeometriesAsync(
elementList,
cancellationToken,
geometryOptions
);
if (geometries.Count != elementList.Count)
{
var missing = elementList.Count - geometries.Count;
throw new InvalidOperationException(
$"Geometry translation incomplete: {missing} of {elementList.Count} failed."
);
}
Validation Strategies
| Scenario | Approach |
|---|---|
| Visualization, previews | Accept partial results |
| Production workflows | Require 90–95% success rate |
| Billing, compliance, export | Require 100% success |
Threshold validation example:
var successRate = (double)geometries.Count / elementList.Count;
if (successRate < 0.90)
{
throw new InvalidOperationException(
$"Success rate {successRate:P1} below required threshold."
);
}
Batch Processing
When processing large models in batches, validate each batch:
var allGeometries = new List<GeometryResult>();
foreach (var batch in dataModel.Elements.Chunk(100))
{
var batchList = batch.ToList();
var geometries = await dataModel.GetElementGeometriesAsync(
batchList,
cancellationToken,
geometryOptions
);
if (geometries.Count != batchList.Count)
{
logger.Warning($"Batch: {batchList.Count - geometries.Count} elements failed");
}
allGeometries.AddRange(geometries);
}
Monitoring Failures
Monitor SDK logs for translation failures:
[ERROR] Translation failure in InternalToGeometries : {error details}
[INFO] Original AssetInfo count = 100, Valid = 95, Skipped = 5
For detailed migration patterns, see the Migration Guide.
Performance Comparison
The following sections compare the performance characteristics of file-based and in-memory geometry retrieval.
File-Based (Default)
// Default: Returns FileGeometry
var geometries = await dataModel.GetElementGeometriesAsync(elements);
foreach (var geometry in geometries.Values.First())
{
var fileGeometry = geometry as FileGeometry;
// Read from disk file
var data = await File.ReadAllBytesAsync(fileGeometry.FilePath);
await ProcessData(data);
}
Performance Characteristics:
- Downloads geometry and writes to temporary disk location
- Application reads data from disk when needed
- Includes disk I/O overhead for both write and read operations
- Suitable for geometry of any size
- No explicit disposal required
In-Memory Approach
// In-Memory: Returns MemoryStreamGeometry
var options = new GeometryOutputOptions { ReturnGeometryAsMemoryStream = true };
var geometries = await dataModel.GetElementGeometriesAsync(elements, cancellationToken, options);
foreach (var geometry in geometries.Values.First())
{
using (var memoryGeometry = geometry as MemoryStreamGeometry)
{
// Direct memory access - no disk I/O
var stream = memoryGeometry.GetStream();
await ProcessStream(stream);
}
}
Performance Characteristics:
- Downloads geometry and loads directly into memory
- Provides immediate access without disk I/O
- Eliminates disk write and read overhead
- Performance improvement varies based on workload and system configuration
- Requires explicit disposal
Migration from Previous Versions
If you are upgrading from SDK v6.x and directly instantiating geometry wrapper classes (Step, Ifc, Obj, Bimdex), note that constructor signatures have changed.
Previous SDK Versions
// OLD: Constructors took byte[]
byte[] stepData = GetStepData();
var step = new Step(stepData);
byte[] objData = GetObjData();
byte[] mtlData = GetMtlData();
var obj = new Obj(objData, mtlData, "material");
Current SDK Version
// NEW: Constructors take MemoryStream
var stepData = GetStepData();
using var stepStream = new MemoryStream(stepData);
var step = new Step(stepStream);
var objData = GetObjData();
var mtlData = GetMtlData();
using var objStream = new MemoryStream(objData);
using var mtlStream = new MemoryStream(mtlData);
var obj = new Obj(objStream, mtlStream, "material");
// NOTE: Wrapper classes now implement IDisposable
step.Dispose();
obj.Dispose();
Changed Methods/Properties
| Class | Old | New |
|---|---|---|
Step |
Constructor: Step(byte[] data) |
Constructor: Step(MemoryStream stream) |
Ifc |
Constructor: Ifc(byte[] data) |
Constructor: Ifc(MemoryStream stream) |
Obj |
Constructor: Obj(byte[], byte[], string) |
Constructor: Obj(MemoryStream, MemoryStream, string) |
Bimdex |
Constructor: Bimdex(byte[] data) |
Constructor: Bimdex(MemoryStream stream) |
| All | Property: byte[] Data |
Method: MemoryStream GetStream() |
| All | N/A | Implements IDisposable |
Troubleshooting
Partial Results (Missing Geometries)
Problem: GetElementGeometriesAsync returns fewer geometries than expected.
Solution: See Handling Partial Results above for validation strategies.
OutOfMemoryException
Problem: Application crashes with OutOfMemoryException when loading large geometry.
Solution:
- Don’t use in-memory geometry for very large models
- Process geometry in batches instead of all at once
- Fall back to file-based geometry for large geometry assets
- Increase available memory or optimize geometry filtering
// Process in batches to manage memory
const int batchSize = 50;
var elementBatches = dataModel.Elements
.Select((e, i) => new { Element = e, Index = i })
.GroupBy(x => x.Index / batchSize)
.Select(g => g.Select(x => x.Element).ToList());
foreach (var batch in elementBatches)
{
var options = new GeometryOutputOptions { ReturnGeometryAsMemoryStream = true };
var geometries = await dataModel.GetElementGeometriesAsync(batch, cancellationToken, options);
// Process batch...
// Dispose all geometries in batch
foreach (var geomList in geometries.Values)
{
foreach (var geom in geomList.OfType<MemoryStreamGeometry>())
{
geom.Dispose();
}
}
}
Memory Leaks
Problem: Application memory usage grows continuously and doesn’t decrease.
Solution: Ensure all MemoryStreamGeometry objects are disposed.
// Use using statements
using (var memoryGeometry = geometry as MemoryStreamGeometry)
{
// ... use geometry
}
// Or explicit disposal
try
{
// ... use geometry
}
finally
{
memoryGeometry?.Dispose();
}
ObjectDisposedException
Problem: ObjectDisposedException when calling GetStream().
Solution: Don’t access geometry after disposing it. Restructure code to process before disposal.
// Incorrect approach
MemoryStreamGeometry memoryGeometry;
using (memoryGeometry = geometry as MemoryStreamGeometry)
{
// ...
}
var stream = memoryGeometry.GetStream(); // Exception - object already disposed
// Correct approach
using (var memoryGeometry = geometry as MemoryStreamGeometry)
{
var stream = memoryGeometry.GetStream();
// Process stream before disposal
await ProcessStream(stream);
} // Disposed after processing complete
Best Practices
Follow these guidelines when working with in-memory geometry:
- Use
usingstatements: Ensures disposal occurs even when exceptions are thrown - Process and dispose promptly: Minimize the lifetime of
MemoryStreamGeometryobjects - Implement batch processing: For large models, process geometry in batches to manage memory consumption
- Monitor memory usage: Track memory consumption during development and testing
- Evaluate appropriateness: Use in-memory geometry where it provides clear benefits
- Plan for fallback: Implement file-based fallback for unexpectedly large geometry
- Test with production data: Validate memory requirements using production-scale models
Retrieving Model-Level Geometry
For geometry assigned at the model/root level (not tied to individual elements), use GetGeometriesAsync. This method accepts the same GeometryOutputOptions as GetElementGeometriesAsync:
var geometryOptions = new GeometryOutputOptions
{
ReturnGeometryAsMemoryStream = true,
GeometryFilters = GeometryFilters.Mesh | GeometryFilters.Brep
};
// Retrieve model-level geometry
var modelGeometries = await dataModel.GetGeometriesAsync(geometryOptions);
foreach (var geometry in modelGeometries)
{
using (var memoryGeometry = geometry as MemoryStreamGeometry)
{
if (memoryGeometry != null)
{
var stream = memoryGeometry.GetStream();
// Process the geometry stream
}
}
}
Use GetGeometriesAsync when your exchange contains geometry at the root level rather than assigned to specific elements.
Summary
The in-memory geometry feature provides performance improvements and enables cloud and containerized deployment scenarios by eliminating disk I/O operations. This feature requires careful memory management through proper disposal patterns.
Key Points:
- Enable by setting
GeometryOutputOptions.ReturnGeometryAsMemoryStreamtotrue - Returns
MemoryStreamGeometryobjects with direct stream access - Requires explicit disposal to prevent memory leaks
- Best suited for cloud environments, high-performance scenarios, and streaming workflows
- Not appropriate for extremely large geometry or memory-constrained environments
Next Steps
Now that you understand in-memory geometry, explore these related topics:
- Creating Geometry - Learn how to create and upload geometry to exchanges
- Controlling Geometry Opacity - Control visual rendering of geometry
- Geometry Parameters - Work with geometry transformation and styling parameters
See Also
- IDisposable Pattern - Microsoft documentation on resource disposal
- Best Practices for HttpClient - Microsoft guidance on HttpClient usage
- Asynchronous Programming - C# async/await patterns