Request

Response

    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 IDisposable pattern 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 MemoryStreamGeometry objects
    • 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:

    MethodUse 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
    );
    
    Show More

    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:

    MemberTypeDescription
    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 call Dispose() or use a using statement 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
        }
    }
    
    Show More

    Dispose Resources Properly

    MemoryStreamGeometry implements IDisposable and must be disposed to release memory resources. Failure to dispose causes memory leaks.

    Important
    Always dispose MemoryStreamGeometry objects using a using statement or explicit Dispose() call to prevent memory leaks.

    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();
    }
    
    Show More

    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
    }
    
    Show More

    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");
    }
    
    Show More

    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."
        );
    }
    
    Show More

    Validation Strategies

    ScenarioApproach
    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."
        );
    }
    
    Show More

    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);
    }
    
    Show More

    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);
    }
    
    Show More

    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);
        }
    }
    
    Show More

    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();
    
    Show More

    Changed Methods/Properties

    ClassOldNew
    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();
            }
        }
    }
    
    Show More

    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();
    }
    
    Show More

    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
    
    Show More

    Best Practices

    Follow these guidelines when working with in-memory geometry:

    1. Use using statements: Ensures disposal occurs even when exceptions are thrown
    2. Process and dispose promptly: Minimize the lifetime of MemoryStreamGeometry objects
    3. Implement batch processing: For large models, process geometry in batches to manage memory consumption
    4. Monitor memory usage: Track memory consumption during development and testing
    5. Evaluate appropriateness: Use in-memory geometry where it provides clear benefits
    6. Plan for fallback: Implement file-based fallback for unexpectedly large geometry
    7. 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
            }
        }
    }
    
    Show More

    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.ReturnGeometryAsMemoryStream to true
    • Returns MemoryStreamGeometry objects 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:


    See Also