Skip to content

Element and Feature¤

compas_model.elements.element ¤

Classes¤

Element ¤

Element(
    geometry: Brep | Mesh | None = None,
    transformation: Transformation | None = None,
    features: Sequence[Feature | FeatureType] | None = None,
    material: Material | None = None,
    name: str | None = None,
    **kwargs: Any,
)

Base class for all elements in the model.

Parameters:

  • geometry (Brep | Mesh | None, default: None ) –

    The complete geometry of the element.

  • transformation (Transformation | None, default: None ) –

    The transformation of the element defining its location in the model. This transformation is relative to the combined transformation of the ancestors of the element up to the model root. If no transformation is provided (default), the geometry of the element is taken as-is.

  • features (Sequence[Feature | FeatureType] | None, default: None ) –

    A list of features that define the detailed geometry of the element. Features are defined in the local coordinate system of the element.

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

    The material of the element.

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

    The name of the element.

Attributes¤
geometry_revision property ¤
geometry_revision: int

int: Runtime revision of geometry derived from this element.

The revision increases whenever element or model changes invalidate computed geometry. It is runtime-only and is not serialized.

Methods:¤
add_feature ¤
add_feature(feature: Feature) -> None

Add a feature to the list of features of the element.

Parameters:

apply_features ¤
apply_features() -> Mesh | Brep

Apply the features to the (base) geometry.

Returns:

  • Mesh or Brep –

    The geometry with features applied.

compute_aabb ¤
compute_aabb(inflate: float = 1.0) -> Box

Computes the Axis Aligned Bounding Box (AABB) of the geometry of the element.

Parameters:

  • inflate (float, default: 1.0 ) –

    Inflate the bounding box by this scaling factor.

Returns:

  • Box –

    The AABB of the element.

compute_collision_mesh ¤
compute_collision_mesh(inflate: float = 1.0) -> Mesh

Computes the collision geometry of the geometry of the element.

Parameters:

  • inflate (float, default: 1.0 ) –

    Inflate the bounding box by this scaling factor.

Returns:

  • Mesh –

    The collision geometry of the element.

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

Compute the contacts between this element and another element.

Parameters:

  • other (Element) –

    The other element.

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

    A distance tolerance.

  • minimum_area (float, default: 0.01 ) –

    The minimum area of the contact polygon.

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

    The contact class to use for the generated contacts.

Returns:

  • list[Contact] –

    The contacts between the elements.

compute_elementgeometry ¤
compute_elementgeometry(include_features: bool = False) -> Brep | Mesh

Compute the geometry of the element in local coordinates.

This is the parametric representation of the element, without considering its location in the model or its interaction(s) with connected elements.

Parameters:

  • include_features (bool, default: False ) –

    If True, the features should be included in the element geometry.

Returns:

  • Mesh or Brep –

    The geometry in local coordinates.

compute_modelgeometry ¤
compute_modelgeometry() -> Brep | Mesh

Compute the geometry of the element in model coordinates and taking into account the effect of interactions with connected elements.

Returns:

  • Mesh or Brep –

    The geometry in model coordinates.

compute_modeltransformation ¤
compute_modeltransformation() -> Transformation

Compute the transformation to model coordinates of this element based on its position in the spatial hierarchy of the model.

Returns:

compute_obb ¤
compute_obb(inflate: float = 1.0) -> Box

Computes the Oriented Bounding Box (OBB) of the geometry of the element.

Parameters:

  • inflate (float, default: 1.0 ) –

    Inflate the bounding box by this scaling factor.

Returns:

  • Box –

    The OBB of the element.

compute_point ¤
compute_point() -> Point

Computes a reference point for the element geometry (e.g. the centroid).

Returns:

  • Point –

    The reference point.

compute_surface_mesh ¤
compute_surface_mesh(
    meshsize_min: float | None = None, meshsize_max: float | None = None
) -> Mesh

Computes the triangulated surface mesh of the element's model geometry.

Parameters:

  • meshsize_min (float | None, default: None ) –

    Minimum size of the mesh elements.

  • meshsize_max (float | None, default: None ) –

    Maximum size of the mesh elements.

Returns:

  • Mesh –

    The triangular mesh.

compute_volumetric_mesh ¤
compute_volumetric_mesh(
    meshsize_min: float | None = None, meshsize_max: float | None = None
) -> VolMesh

Computes the tetrahedral volumetric mesh of the element's model geometry.

Parameters:

  • meshsize_min (float | None, default: None ) –

    Minimum size of the mesh elements.

  • meshsize_max (float | None, default: None ) –

    Maximum size of the mesh elements.

Returns:

is_collision ¤
is_collision(
    other: Element,
    precision: str = "fast",
    tolerance: float = 0.0,
    include_touching: bool = True,
) -> bool

Determine whether this element collides with another element.

Parameters:

  • other (Element) –

    The other element.

  • 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.

Returns:

  • bool –

    For fast checks, False guarantees separation and True identifies a conservative collision candidate. Precise mesh checks classify intersection of the triangulated surfaces; precise BRep checks classify native Open CASCADE shapes.

Raises:

  • ValueError –

    If the requested precision is unsupported.

  • TypeError –

    If the elements use different or unsupported geometry types.

  • ImportError –

    If a precise collision backend is unavailable.

  • NotImplementedError –

    If the requested touching or tolerance semantics are unavailable for the selected representation.

Notes

Mesh and BRep collision pipelines are intentionally separate. This method does not convert or compare mixed representations.

transform ¤
transform(transformation: Transformation) -> None

Transforms the element.

Parameters:

  • transformation (Transformation) –

    The transformation to be applied.

transformed ¤
transformed(transformation: Transformation) -> Element

Creates a transformed copy of the element.

Parameters:

  • transformation (Transformation) –

    The transformation to be applied to the copy of the element.

Returns:

  • Element –

    The transformed copy.

Feature ¤

Feature(name: str | None = None)

Base class for all element features.

Parameters:

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

    The name of the feature.

Methods:¤
apply ¤
apply(shape: Mesh | Brep) -> Mesh | Brep

Apply the feature to the given shape, which represents the base geometry of the host element of the feature.