Assembly#

This module provides a specialized framework for constructing and managing hierarchical assembly documents of 3D data.

It defines utilities for incremental B-Rep storage, scene tree traversal, and integration with Babylon.js for visualization.

class volmdlr.assembly.AssemblyNode(nodes: list[SceneTreeNode], nodes_locations: list[Location], parent_component_id: int, location: Location | None = None, name: str = '', color: tuple[float, float, float] | None = None, alpha: float = 1.0, metadata: dict[str, Any] | None = None)#

Bases: SceneTreeNode

Composite node representing an assembly of child nodes.

property bounding_box: BoundingBox | None#: Return bounding box for this node.

meshes() → list[Mesh3D]#

Recursively collect all meshes with location transforms applied.

Returns:: List of Mesh3D objects with proper transforms.

property nodes: list[SceneTreeNode]#

Return child nodes.

Returns:: List of child SceneTreeNode.

class volmdlr.assembly.AssemblyPrototype(component_id: int, child_instances: list[Instance] | None = None, representation_node: Node | None = None, name: str = '', color: tuple[float, float, float] | None = None, alpha: float = 1.0, metadata: dict[str, Any] | None = None)#

Bases: Prototype

Reusable assembly model composed of child instances.

meshes() → list[Mesh3D]#

Get the tessellated representations from all child instances.

Returns:: Flattened list of Mesh3D objects.

class volmdlr.assembly.Component(component_id: int, name: str = '', color: tuple[float, float, float] | None = None, alpha: float = 1.0, metadata: dict[str, Any] | None = None)#

Bases: Primitive3D

Base class for all hierarchical assembly graph nodes (Prototypes and Instances).

babylon_data(merge_meshes=True, show_curves: bool = False, ocaf=None)#: Generate data compatible with Babylon.js format.

property doc_model#: Get the parent DocModel reference.

meshes() → list[Mesh3D]#

Get tessellated representation(s) of the component.

Returns:: List of Mesh3D objects.

property node: InstanceOf[SceneTreeNode]#

Get lightweight scene tree node for this component.

Returns:: PartNode or AssemblyNode representing this component.

property shape: Shape#

Get the Shape for this component with transformations applied.

Returns:: Shape object from the component’s node.

class volmdlr.assembly.DocModel(root_prototype: InstanceOf[Prototype] | None = None, brep_path: str | None = None, current_component_id: int = 0, current_node_id: int = 0, _mesh_to_prototype_map: dict[str, int] | None = None, name: str = '')#

Bases: Model

Main document container: ID generation, graph construction, and B-Rep JSON storage.

add_part(part: Shape | Mesh3D) → PartNode#

Add a single part to the model and return its scene node.

Parameters:: part – Shape to add to the document.
Returns:: PartNode representing the added shape.

babylon_data(merge_meshes=True, show_curves: bool = False, ocaf=None)#: Convert the DocModel data into babylon.js schema.

property bounding_box: BoundingBox#

Compute the axis-aligned bounding box of the entire document.

Returns:: BoundingBox object encompassing all geometry in the document.

classmethod dict_to_object(dict_: Dict[str, Any], global_dict=None, pointers_memo=None, path: str = '#', **kwargs: Any) → DocModel#

Reconstruct a DocModel from its JSON-serializable dictionary form.

Parameters:

dict – Dictionary produced by to_dict().
global_dict – Root dict for resolving JSON pointers (internal use).
pointers_memo – Memo dict of already deserialized pointer targets (internal use).
path – Current JSON path (internal use).
kwargs – Additional options (unused).

Returns:

New DocModel instance with state restored.

export_to_json_glb(output_directory: str, compact: bool = False) → str#

Export DocModel with unfolded node tree.

Creates a JSON file with: - prototypes: Shared geometry definitions with GLB file references - nodes: Hierarchical tree with unique reference_path per occurrence

Parameters:

output_directory – Directory where to save the JSON and GLB files.
compact – If True, produce compact JSON without indentation (smaller file size).

Returns:

Path to the generated JSON file.

classmethod from_shapes(shapes: list[Shape], brep_path: str | None = None, name: str = '') → DocModel#

Create a DocModel from a list of Shape primitives by extracting their assembly structure.

Parameters:

shapes – List of Shape objects to process.
brep_path – Optional path to JSON file for B-Rep storage.
name – Optional name for the DocModel.

Returns:

New DocModel instance with extracted assembly structure.

classmethod from_step(step_file: str, name: str = '', reading_unit: Literal['M', 'MM'] = 'M')#

Translate a STEP file into a volume model using Open CASCADE Technology (OCCT).

Parameters:

step_file – The path to the STEP file.
name – A name for the volume model.
reading_unit – The unit of measurement used to read the STEP file. Default is “M” (meters).

classmethod from_step_stream(stream: BinaryFile, name: str = '', reading_unit: Literal['M', 'MM'] = 'M')#

Translate a STEP stream into a volume model using Open CASCADE Technology (OCCT).

Parameters:

stream – The stream of the STEP file.
name – A name for the volume model.
reading_unit – The unit of measurement used to read the STEP file. Default is “M” (meters).

get_meshes()#

Retrieve all discretized meshes for root prototypes.

Returns:: Flattened list of Mesh3D objects.

get_nodes() → list[SceneTreeNode]#: For platform compatibility.

get_shape(node: SceneTreeNode) → Shape#

Retrieve the Shape corresponding to a SceneTreeNode.

Parameters:: node – SceneTreeNode whose shape is desired.
Returns:: Shape object with correct placement and attributes.

get_shape_from_prototype(prototype: Prototype) → Shape | None#

Recursively assemble a Shape from a Prototype definition.

Parameters:: prototype – Prototype object to convert.
Returns:: Combined Shape for assemblies or direct Shape for parts.

property has_brep: bool#

Check if the DocModel has any BREP data.

Returns:: True if at least one prototype has BREP data, False otherwise.

property hierarchical_assembly_graph#

Build or return the Hierarchical Assembly Graph (HAG) of this document.

The HAG represents the hierarchical structure of a CAD assembly using a directed graph:

Nodes represent prototypes: reusable definitions of parts or sub-assemblies. A prototype defines the geometry once, regardless of how many times it appears.
Edges represent instances: physical occurrences of a prototype placed at a specific location within a parent assembly. Each edge stores the transformation (position and orientation) of that particular occurrence.

A MultiDiGraph is used because the same prototype can be instantiated multiple times within the same parent assembly (e.g., 4 identical wheels in a car, 8 bolts in a flange pattern). Each instance has its own edge with a unique location, allowing the graph to fully capture the assembly structure.

Returns:: MultiDiGraph where nodes are prototype IDs and edges are instance relationships.

make_assembly(primitives: list[Shape | Mesh3D | AssemblyNode], locations: list[Location | None] | None = None, name: str = '') → AssemblyNode#

Construct an AssemblyNode from existing Shapes or sub-assemblies.

Parameters:

primitives – List of Shape, Mesh3D or AssemblyNode elements.
locations – Optional corresponding list of Locations for each element.
name – Optional assembly name.

Returns:

AssemblyNode representing the new assembly.

property nodes: list[SceneTreeNode]#

Get the lightweight scene tree nodes for all root components.

Returns:: List of PartNode or AssemblyNode objects at document root.

plot_data(reference_path: str = '#', **kwargs) → list[NetworkxGraph]#: Return the plot_data object for local plot_data usage.

plot_graph#

print_tree() → str#

Print the assembly tree structure and return it as a string.

Returns:: String representation of the assembly tree.

property root_prototype: InstanceOf[Prototype] | None#

Get the single root prototype, creating one if necessary.

Returns:: The root prototype of this document, or None if empty.

set_instance(prototype: Prototype, location: Location | None = None, name: str = '', color: tuple[float, float, float] | None = None, alpha: float = 1.0, metadata: dict[str, Any] | None = None) → Instance#

Create and register a new Instance of an existing Prototype.

Parameters:

prototype – Prototype to instantiate.
location – Placement transform; defaults to identity if None.
name – Optional name.
color – Optional RGB tuple.
alpha – Transparency for visualization.
metadata – Additional data.

Returns:

Created Instance object.

Create and register a new Prototype (part or assembly).

Parameters:

child_instances – Instances for an assembly prototype.
brep_id – Identifier for the B-Rep blob.
mesh – Mesh3D for a part prototype.
name – Optional name.
color – Optional RGBA tuple.
metadata – Additional annotation data.

Returns:

Created Prototype object.

set_triangulation_parameters(relative_linear_deflection: float = 0.005, angular_deflection: float = 0.5, linear_deflection: float | None = None, **kwargs) → None#

Configure mesh tessellation deflection parameters and regenerate the meshes.

Parameters:

relative_linear_deflection – Relative linear deflection for mesh generation, used to compute linear deflection based on bounding box size. Smaller values produce finer meshes.
angular_deflection – Angular deflection in radians. Smaller values, finer meshes.
linear_deflection – Linear deflection for mesh generation. If provided, it overrides the automatic calculation based on bounding box size.

to_dict(use_pointers: bool = True, memo=None, path: str = '#', id_method=True, id_memo=None, **kwargs: Any) → Dict[str, Any]#

Serialize DocModel to a JSON-compatible dictionary.

Parameters:

use_pointers – Whether to use JSON pointer references for deduplication.
memo – Memo dict for tracking serialized objects (internal use).
path – Current JSON path (internal use).
id_method – Whether to use ID-based references (internal use).
id_memo – ID memo dict (internal use).
kwargs – Additional options (unused).

Returns:

Dictionary containing document state and B-Rep data.

to_discrete_model() → VolumeModel#: Create a VolumeModel containing all the meshes.

to_step(filepath: str, preferences=None) → None#: Export a step file of the model.

to_volume_model() → VolumeModel#: Instantiate all shapes and create a VolumeModel.

class volmdlr.assembly.Instance(component_id: int, prototype: InstanceOf[Prototype], location: Location, name: str = '', color: tuple[float, float, float] | None = None, alpha: float = 1.0, metadata: dict[str, Any] | None = None)#

Bases: Component

Occurrence of a Prototype with spatial placement.

Variables:: _non_serializable_attributes – Attributes excluded from serialization.

meshes() → list[Mesh3D]#

Get the transformed mesh representations for this instance.

Returns:: List of Mesh3D objects with location applied.

class volmdlr.assembly.Node(node_id: int, representation: Mesh3D | Any, parent_prototype_id: int, name: str = '')#

Bases: DessiaObject

A Node holds information to its representation and parent component in the assembly tree.

class volmdlr.assembly.PartNode(parent_component_id: int, mesh: Mesh3D | None = None, location: Location | None = None, name: str = '', color: tuple[float, float, float] | None = None, alpha: float = 1.0, metadata: dict[str, Any] | None = None)#

Bases: SceneTreeNode

Lightweight node representing a discrete mesh part in the scene.

property bounding_box: BoundingBox | None#: Return bounding box for this node.

property mesh: Mesh3D#

Return transformed mesh for this node.

Returns:: Mesh3D instance transformed by the node’s location.

class volmdlr.assembly.PartPrototype(component_id: int, brep_id: str | None = None, mesh: Mesh3D | None = None, representation_node: Node | None = None, name: str = '', color: tuple[float, float, float] | None = None, alpha: float = 1.0, metadata: dict[str, Any] | None = None)#

Bases: Prototype

Reusable CAD model linking to a B-Rep identifier.

meshes() → list[Mesh3D]#

Get the tessellated representations of this prototype.

Returns:: List containing the associated Mesh3D.

class volmdlr.assembly.Prototype(component_id: int, name: str = '', representation_node: Any | None = None, color: tuple[float, float, float] | None = None, alpha: float = 1.0, metadata: dict[str, Any] | None = None)#

Bases: Component

Abstract base for all prototypes (parts or sub-assemblies).

Variables:: _non_serializable_attributes – List of attributes excluded from serialization.

property is_root: bool#: Return True if the prototype doesn’t have any parent instance.

class volmdlr.assembly.SceneTreeNode(parent_component_id: int, location: Location, name: str = '', color: tuple[float, float, float] | None = None, alpha: float = 1.0, metadata: dict[str, Any] | None = None)#

Bases: Primitive3D

Lightweight representation of a node within a hierarchical assembly structure.

SceneTreeNode holds metadata and local transformation without loading full B-Rep geometry.

babylon_data(merge_meshes=True, show_curves: bool = False, ocaf=None)#: Generate data compatible with Babylon.js format.

property doc_model#: Get the parent DocModel reference.

property frame: Frame3D#

Return the local coordinate frame of the node.

Returns:: Frame3D object representing this node’s placement.

is_serializable_attribute(attribute_value: Any) → bool#

Determine if an attribute value should be included in serialized output.

Parameters:: attribute_value – Value to test for serialization eligibility.
Returns:: True if the value is a SceneTreeNode, Mesh3D, or homogeneous sequence thereof; False otherwise.

property mesh: Mesh3D | None#: Return the tessellated representation of this node. Base class has no mesh.

meshes() → list[Mesh3D]#: Recursively collect all meshes in this subtree.

property shape: Shape | None#

Get the Shape for this node with transformations applied.

Returns:: Shape object with node’s transformation applied, or None if unavailable.

volmdlr.assembly.update_brep_file(path: str, new_key: str, new_value: str) → None#

Append or update an entry in the “brep_data” section of a JSON file.

Parameters:

path – Filesystem path to the JSON file containing “brep_data”.
new_key – The key to add or update.
new_value – The new value to associate with the key.

Returns:

None

volmdlr.assembly.update_brep_file_using_stream(path: str, new_key: str, new_value: str) → None#

Update a large B-Rep JSON file incrementally without loading it entirely into memory.

This function streams key/value pairs from the existing file to a temporary file, inserts the new entry, and atomically replaces the original file.

Parameters:

path – Filesystem path to the JSON file containing a top-level “brep_data” object.
new_key – The key under which to store the new compressed B-Rep blob.
new_value – The compressed and base64-encoded B-Rep data to insert.

Returns:

None