Skip to content

Model¤

compas_model.models.model ¤

Classes¤

Model ¤

Model(name: str | None = None, unit: ModelUnit = 'M', **kwargs: object)

Class representing a general model of hierarchically organised elements, with interactions.

Notes

A model has an element tree to store the hierarchical relationships between elements, and an interaction graph to store the interactions between pairs of elements. Model elements are contained in the tree hierarchy in tree nodes, and in the interaction graph in graph nodes.

Every model element can appear only once in the tree, and only once in the graph. This means that every element can have only one hierarchical parent. At the same time, independently of the hierarchy, every element can have many interactions with other elements.

Attributes¤
unit property writable ¤
unit: ModelUnit

ModelUnit: Length unit used by model coordinate values.

Methods:¤
add_collection ¤
add_collection(
    collection: Collection | str, attributes: dict[str, object] | None = None
) -> Collection

Add a collection or create one from a name.

add_element ¤
add_element(
    element: Element | ElementType,
    parent: Element | None = None,
    material: Material | None = None,
) -> Element | ElementType

Add an element to the model.

Parameters:

  • element (Element | ElementType) –

    The element to add.

  • parent (Element | None, default: None ) –

    The parent element of the element. If None, the element will be added directly under the root element.

  • material (Material | None, default: None ) –

    A material to assign to the element. Note that the material should have already been added to the model before it can be assigned.

Returns:

  • Element –

    The element added to the model.

Raises:

  • ValueError –

    If the parent node is not a GroupNode.

  • ValueError –

    If a material is provided that is not part of the model.

add_elements ¤
add_elements(
    elements: list[ElementType],
    parent: Element | None = None,
    material: Material | None = None,
) -> list[ElementType]

Add a list of elements to the model.

Parameters:

  • elements (list[ElementType]) –

    The elements to add.

  • parent (Element | None, default: None ) –

    The parent element of the elements. If None, the elements will be added directly under the root element.

  • material (Material | None, default: None ) –

    A material to assign to the elements. Note that the material should have already been added to the model before it can be assigned.

Returns:

  • list[Element] –

    The list of elements added to the model.

Raises:

  • ValueError –

    If the parent node is not a GroupNode.

  • ValueError –

    If a material is provided that is not part of the model.

add_group ¤
add_group(name: str | None = None) -> Group

Add a group to the model.

Parameters:

  • name (str | None, default: None ) –

    The name of the group.

Returns:

  • Group –

    The group added to the model.

add_interaction ¤
add_interaction(
    a: Element, b: Element, modifier: Modifier | None = None
) -> tuple[int, int]

Add an interaction between two elements of the model.

Parameters:

  • a (Element) –

    The first element.

  • b (Element) –

    The second element.

Returns:

  • tuple[int, int] –

    The edge of the interaction graph representing the interaction between the two elements.

Raises:

  • Exception –

    If one or both of the elements are not in the graph.

Notes

In future implementations, adding an interaction should implicitly take care of adding modifiers onto the interaction edges, based on the registered modifiers of the source nodes.

In the current implementation, modifiers have to be added explicitly using :meth:add_modifiers. This method will add an interaction edge from the source of the modifier to its target if needed and store the modifier object on it.

add_material ¤
add_material(material: Material) -> None

Add a material to the model.

Parameters:

  • material (Material) –

    A material.

add_modifier ¤
add_modifier(source: Element, target: Element, modifier: Modifier) -> list[Modifier]

Add a modifier between two elements, with one the source of the modifier and the other the target.

Parameters:

  • source (Element) –

    The source element.

  • target (Element) –

    The target element.

  • modifier (Modifier) –

    The modifier.

Returns:

  • list[Modifier] –

    All modifiers stored on the interaction edge between source and target.

Notes

This element should implement the protocol specified by the modifier. The methods of the source element defined by the protocol are used to compute the tools involved in the modification. The tools are used by the modifier to apply the modification to the model geometry of the target element.

The modifier defines the protocol for the modification. The protocol should be implemented by the source element. The protocol methods of the source element are used to compute the modification tool. The modifier applies the modification to the target using this tool.

add_or_get_material ¤
add_or_get_material(material: Material) -> Material

Add a material to the model or retrieve an existing instance of the same type.

Parameters:

  • material (Material) –

    A material.

Returns:

  • Material –

    The added or existing material.

assign_material ¤
assign_material(
    material: Material,
    element: Element | None = None,
    elements: list[Element] | None = None,
) -> None

Assign a material to an element or a list of elements.

Parameters:

  • material (Material) –

    The material.

  • element (Element | None, default: None ) –

    The element to assign the material to.

  • elements (list[Element] | None, default: None ) –

    The list of elements to assign the material to.

Raises:

  • ValueError –

    If neither element or elements is provided.

  • ValueError –

    If both element and elements are provided.

  • ValueError –

    If the material is not part of the model.

  • ValueError –

    If the provided element or one of the elements in the provided element list is not part of the model.

collections ¤
collections() -> Iterator[Collection]

Iterate over non-hierarchical element collections.

collections_for_element ¤
collections_for_element(element: Element) -> list[Collection]

Return all collections containing an element.

collision_candidates ¤
collision_candidates() -> Generator[tuple[Element, Element], None, None]

Yield broad-phase collision candidates from the model elements.

Yields:

Notes

Each unordered pair is yielded at most once and an element is never paired with itself. Candidate bounding volumes overlap, but the element geometries may not. Precise collision checks are required to reject broad-phase false positives.

collisions ¤
collisions(
    precision: str = "fast", tolerance: float = 0.0, include_touching: bool = True
) -> Generator[tuple[Element, Element], None, None]

Yield colliding element pairs.

Parameters:

  • precision (str, default: 'fast' ) –

    "fast" for conservative bounds or "precise" for representation-specific geometric collision.

  • tolerance (float, default: 0.0 ) –

    The maximum separation considered a collision.

  • include_touching (bool, default: True ) –

    If True, boundary contact is considered a collision.

Yields:

Notes

The model BVH first removes pairs whose element AABBs do not overlap. Remaining pairs are dispatched to either precise mesh-surface or native Open CASCADE BRep collision. Mesh and BRep geometry are never mixed.

compute_bvh ¤
compute_bvh(
    nodetype: type[ElementAABBNode] | type[ElementOBBNode] = ElementAABBNode,
    max_depth: int | None = None,
    leafsize: int = 1,
) -> ElementBVH

Compute the Bounding Volume Hierarchy (BVH) of the elements for fast collision checks.

Parameters:

  • nodetype (type[ElementAABBNode] | type[ElementOBBNode], default: ElementAABBNode ) –

    The type of bounding volume node used in the tree.

  • max_depth (int | None, default: None ) –

    The maximum depth used for constructing the BVH.

  • leafsize (int, default: 1 ) –

    The number of elements contained in a BVH leaf node.

Returns:

compute_contacts ¤
compute_contacts(
    tolerance: float = 1e-06,
    minimum_area: float = 0.01,
    contacttype: type[Contact] = Contact,
) -> None

Compute the contacts between the block elements of this model.

Computing contacts is done independently of the existing interaction edges. Derived contacts on existing edges are replaced atomically. An edge created by this method is removed when its contact disappears, unless it has subsequently acquired modifiers. Explicit interaction edges are always preserved.

The search is conducted entirely based on the BVH of the elements contained in the model. It is a spatial search that creates topological connections between elements based on their geometrical interaction.

Parameters:

  • tolerance (float, default: 1e-06 ) –

    The distance tolerance.

  • minimum_area (float, default: 0.01 ) –

    The minimum contact size.

  • contacttype (type[Contact], default: Contact ) –

    The contact class to use for the generated contacts.

Raises:

  • ValueError –

    If tolerance or minimum_area is negative.

Notes

Broad-phase candidates are found by expanding each element AABB by the absolute tolerance. Mesh-to-mesh and BRep-to-BRep pairs are evaluated separately; mixed representation pairs are ignored.

All contact geometry is computed before the interaction graph is changed. If one computation fails, the graph remains unchanged.

compute_kdtree ¤
compute_kdtree() -> KDTree

Compute the KD tree of the elements for fast nearest neighbour queries.

The KD tree is built using the reference points of the elements of the model.

Returns:

  • KDTree –

    The computed KD tree.

element_by_guid ¤
element_by_guid(guid: str) -> Element

Return the model element with the requested GUID.

element_nnbrs ¤
element_nnbrs(element: Element, k: int = 1) -> list[tuple[Element, float]]

Find the nearest neighbours to a root element.

Parameters:

  • element (Element) –

    The root element.

  • k (int, default: 1 ) –

    The number of nearest neighbours that should be returned.

Returns:

  • list[tuple[Element, float]] –

    A list of nearest neighbours, with each neighbour defined as an element and the distance of that element to the root element.

elements ¤
elements() -> Iterator[Element]

Iterate over the elements contained in the model.

Returns:

find_all_elements_of_type ¤
find_all_elements_of_type(elementtype: type[Element]) -> list[Element]

Find all model elements of a given type.

Parameters:

Returns:

  • list[Element] –

    The elements of the requested type.

find_collection_with_name ¤
find_collection_with_name(name: str) -> Collection | None

Return the first collection with the requested name.

find_element_with_name ¤
find_element_with_name(name: str) -> Element | None

Returns True if the model contains an element with the given name.

Parameters:

  • name (str) –

    The name to check.

Returns:

  • Element or None –

    The element with the name, if found.

has_element ¤
has_element(element: Element) -> bool

Returns True if the model contains the given element.

Parameters:

  • element (Element) –

    The element to check.

Returns:

  • bool –

    True if the model contains the element.

has_element_with_name ¤
has_element_with_name(name: str) -> bool

Returns True if the model contains an element with the given name.

Parameters:

  • name (str) –

    The name to check.

Returns:

  • bool –

    True if the model contains an element with the name.

has_interaction ¤
has_interaction(a: Element, b: Element) -> bool

Returns True if two elements have an interaction set between them.

Parameters:

  • a (Element) –

    The first element.

  • b (Element) –

    The second element.

Returns:

  • bool –

    True if the elements have an interaction.

has_material ¤
has_material(material: Material) -> bool

Verify that the model contains a specific material.

Parameters:

  • material (Material) –

    A model material.

Returns:

  • bool –

    True if the model contains the material.

materials ¤
materials() -> Iterator[Material]

Iterate over the materials stored in the model.

Returns:

  • Iterator[Material] –

    The materials stored in the model.

point_nnbrs ¤
point_nnbrs(point: Point, k: int = 1) -> list[tuple[Element, float]]

Find the nearest neighbours to a point.

Parameters:

  • point (Point) –

    The root point.

  • k (int, default: 1 ) –

    The number of nearest neighbours that should be returned.

Returns:

  • list[tuple[Element, float]] –

    A list of nearest neighbours, with each neighbour defined as an element and the distance of that element to the root element.

remove_collection ¤
remove_collection(collection: Collection) -> None

Remove a collection without removing its member elements.

remove_element ¤
remove_element(element: Element) -> None

Remove an element from the model.

Parameters:

  • element (Element) –

    The element to remove.

remove_elements_of_type ¤
remove_elements_of_type(elementtype: type[Element]) -> list[Element]

Remove all model elements of a given type.

Parameters:

Returns:

remove_interaction ¤
remove_interaction(a: Element, b: Element) -> None

Remove the interaction between two elements.

Parameters:

transform ¤
transform(transformation: Transformation) -> None

Transform the model and all that it contains.

Parameters: