compas_timber.base

Classes

TimberElement

TimberElement(frame, length, width, height, features=None, **kwargs)

Base class for all timber elements.

This is an abstract class and should not be instantiated directly.

Parameters:

• frame (:class:`compas.geometry.Frame`) –

  The frame representing the beam's local coordinate system in its hierarchical context. Defaults to None, in which case the world coordinate system is used.

• length (float) –

  Length of the timber element.

• width (float) –

  Width of the timber element.

• height (float) –

  Height of the timber element.

• features (list[:class:`~compas_timber.fabrication.Feature`], default: None ) –

  List of features to apply to this element.

• **kwargs (dict, default: {} ) –

  Additional keyword arguments.

Attributes:

• frame (:class:`compas.geometry.Frame`) –

  The coordinate system of this element in model space. This property may be different from the constructor parameter if the element belongs to a model hierarchy.

• is_beam (bool) –

  True if the element is a beam.

• is_plate (bool) –

  True if the element is a plate.

• is_group_element (bool) –

  True if the element can be used as container for other elements.

• features (list[:class:`~compas_timber.parts.Feature`]) –

  A list of features applied to the element.

• geometry (:class:`compas.geometry.Geometry`) –

  The geometry of the element in the model's global coordinates.

Source code in src/compas_timber/base.py

def __init__(self, frame, length, width, height, features=None, **kwargs):
    super().__init__(transformation=Transformation.from_frame(frame), features=features)
    self.attributes = {}
    self.attributes.update(kwargs)
    self.length = length
    self.width = width
    self.height = height
    self._blank = None
    self._ref_frame = None
    self.debug_info = []

Attributes

geometry property

geometry

The geometry of the element in the model's global coordinates.

ref_frame property

ref_frame

Reference frame for machining processings according to BTLx standard. The origin is at the bottom far corner of the element. The ref_frame is always in model coordinates.

Methods:

add_feature

add_feature(feature)

Adds a feature to the element.

Parameters:

• feature (:class:`~compas_timber.fabrication.BTLxProcessing`) –

  The feature to be added.

Source code in src/compas_timber/base.py

def add_feature(self, feature):
    # type: (BTLxProcessing) -> None
    """Adds a feature to the element.

    Parameters
    ----------
    feature : :class:`~compas_timber.fabrication.BTLxProcessing`
        The feature to be added.

    """
    self.add_features(feature)

add_features

add_features(features)

Adds one or more features to the element.

Parameters:

• features (:class:`~compas_timber.fabrication.BTLxProcessing` | list(:class:`~compas_timber.fabrication.BTLxProcessing`)) –

  The feature or features to be added described as a BTLxProcessing or a list of BTLxProcessings.

Source code in src/compas_timber/base.py

def add_features(self, features):
    # type: (BTLxProcessing | list[BTLxProcessing]) -> None
    """Adds one or more features to the element.

    Parameters
    ----------
    features : :class:`~compas_timber.fabrication.BTLxProcessing` | list(:class:`~compas_timber.fabrication.BTLxProcessing`)
        The feature or features to be added described as a BTLxProcessing or a list of BTLxProcessings.

    """
    clear_element_cache(self)
    if not isinstance(features, list):
        features = [features]
    self._features.extend(features)  # type: ignore

back_side

back_side(ref_side_index)

Returns the previous side before the reference side, following the right-hand rule with the thumb along the beam's frame x-axis. This method does not consider the start and end sides of the beam (RS5 & RS6).

Parameters:

• ref_side_index (int) –

  The index of the reference side to which the back side should be calculated.

Returns:

• frame ( :class:`~compas.geometry.Frame` ) –

  The frame of the back side of the beam relative to the reference side.

Source code in src/compas_timber/base.py

def back_side(self, ref_side_index):
    # type: (int) -> Frame
    """Returns the previous side before the reference side, following the right-hand rule with the thumb along the beam's frame x-axis.
    This method does not consider the start and end sides of the beam (RS5 & RS6).

    Parameters
    ----------
    ref_side_index : int
        The index of the reference side to which the back side should be calculated.

    Returns
    -------
    frame : :class:`~compas.geometry.Frame`
        The frame of the back side of the beam relative to the reference side.
    """
    return self.ref_sides[(ref_side_index - 1) % 4]

compute_modelgeometry

compute_modelgeometry()

Same as parent but handles standalone elements.

Source code in src/compas_timber/base.py

def compute_modelgeometry(self):
    """Same as parent but handles standalone elements."""
    if not self.model:
        return self.elementgeometry.transformed(self.transformation)
    return super().compute_modelgeometry()

compute_modeltransformation

compute_modeltransformation()

Same as parent but handles standalone elements.

Source code in src/compas_timber/base.py

def compute_modeltransformation(self):
    """Same as parent but handles standalone elements."""
    if not self.model:
        return self.transformation
    return super().compute_modeltransformation()

front_side

front_side(ref_side_index)

Returns the next side after the reference side, following the right-hand rule with the thumb along the beam's frame x-axis. This method does not consider the start and end sides of the beam (RS5 & RS6).

Parameters:

• ref_side_index (int) –

  The index of the reference side to which the front side should be calculated.

Returns:

• frame ( :class:`~compas.geometry.Frame` ) –

  The frame of the front side of the beam relative to the reference side.

Source code in src/compas_timber/base.py

def front_side(self, ref_side_index):
    # type: (int) -> Frame
    """Returns the next side after the reference side, following the right-hand rule with the thumb along the beam's frame x-axis.
    This method does not consider the start and end sides of the beam (RS5 & RS6).

    Parameters
    ----------
    ref_side_index : int
        The index of the reference side to which the front side should be calculated.

    Returns
    -------
    frame : :class:`~compas.geometry.Frame`
        The frame of the front side of the beam relative to the reference side.
    """
    return self.ref_sides[(ref_side_index + 1) % 4]

get_dimensions_relative_to_side

get_dimensions_relative_to_side(ref_side_index)

Returns the dimensions of a timber element with respect to the Y- axis and Normal of the given reference side.

Parameters:

• ref_side_index (int) –

  The index of the reference side to which the dimensions should be calculated.

Returns:

• tuple(float, float) –

  Y-axis dimension, Normal direction dimension. - Y-axis dimension: The element dimension along y-axis of reference side. - Normal dimension: The element dimension normal to the reference side.

Source code in src/compas_timber/base.py

def get_dimensions_relative_to_side(self, ref_side_index):
    # type: (int) -> tuple[float, float]
    """Returns the dimensions of a timber element with respect to the Y- axis and Normal of the given reference side.

    Parameters
    ----------
    ref_side_index : int
        The index of the reference side to which the dimensions should be calculated.

    Returns
    -------
    tuple(float, float)
        Y-axis dimension, Normal direction dimension.
            - Y-axis dimension: The element dimension along y-axis of reference side.
            - Normal dimension: The element dimension normal to the reference side.
    """
    if ref_side_index in [1, 3]:
        return self.height, self.width
    return self.width, self.height

opp_side

opp_side(ref_side_index)

Returns the the side that is directly across from the reference side, following the right-hand rule with the thumb along the beam's frame x-axis. This method does not consider the start and end sides of the beam (RS5 & RS6).

Parameters:

• ref_side_index (int) –

  The index of the reference side to which the opposite side should be calculated.

Returns:

• frame ( :class:`~compas.geometry.Frame` ) –

  The frame of the opposite side of the beam relative to the reference side.

Source code in src/compas_timber/base.py

def opp_side(self, ref_side_index):
    # type: (int) -> Frame
    """Returns the the side that is directly across from the reference side, following the right-hand rule with the thumb along the beam's frame x-axis.
    This method does not consider the start and end sides of the beam (RS5 & RS6).

    Parameters
    ----------
    ref_side_index : int
        The index of the reference side to which the opposite side should be calculated.

    Returns
    -------
    frame : :class:`~compas.geometry.Frame`
        The frame of the opposite side of the beam relative to the reference side.
    """
    return self.ref_sides[(ref_side_index + 2) % 4]

remove_blank_extension

remove_blank_extension()

Remove blank extension from the element.

This method is intended to be overridden by subclasses.

Source code in src/compas_timber/base.py

def remove_blank_extension(self):
    """Remove blank extension from the element.

    This method is intended to be overridden by subclasses.
    """
    pass

remove_features

remove_features(features=None)

Removes one or more features from the element.

Parameters:

• features (:class:`~compas_timber.fabrication.BTLxProcessing` | list(:class:`~compas_timber.fabrication.BTLxProcessing`) | None, default: None ) –

  The feature or features to be removed described as a BTLxProcessing or a list of BTLxProcessings. If None, all features will be removed.

Source code in src/compas_timber/base.py

def remove_features(self, features=None):
    # type: (None | BTLxProcessing | list[BTLxProcessing]) -> None
    """Removes one or more features from the element.

    Parameters
    ----------
    features : :class:`~compas_timber.fabrication.BTLxProcessing` | list(:class:`~compas_timber.fabrication.BTLxProcessing`) | None
        The feature or features to be removed described as a BTLxProcessing or a list of BTLxProcessings.
        If None, all features will be removed.

    """
    clear_element_cache(self)
    if features is None:
        self._features = []
    else:
        if not isinstance(features, list):
            features = [features]
        self._features = [f for f in self._features if f not in features]

reset

reset()

Resets the element to its initial state by removing all features, extensions, and debug_info.

Source code in src/compas_timber/base.py

def reset(self):
    """Resets the element to its initial state by removing all features, extensions, and debug_info."""
    self.remove_features()
    self.remove_blank_extension()
    self.debug_info = []

side_as_surface

side_as_surface(side_index)

Returns the requested side of the beam as a parametric planar surface.

Parameters:

• side_index (int) –

  The index of the reference side to be returned. 0 to 5.

Source code in src/compas_timber/base.py

def side_as_surface(self, side_index):
    # type: (int) -> compas.geometry.PlanarSurface
    """Returns the requested side of the beam as a parametric planar surface.

    Parameters
    ----------
    side_index : int
        The index of the reference side to be returned. 0 to 5.

    """
    # TODO: maybe this should be the default representation of the ref sides?
    ref_side = self.ref_sides[side_index]
    if side_index in (0, 2):  # top + bottom
        xsize = self.blank_length
        ysize = self.width
    elif side_index in (1, 3):  # sides
        xsize = self.blank_length
        ysize = self.height
    elif side_index in (4, 5):  # ends
        xsize = self.width
        ysize = self.height
    return PlanarSurface(xsize, ysize, frame=ref_side, name=ref_side.name)

transformation_to_local

transformation_to_local()

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

Returns:

• class:`compas.geometry.Transformation` –

Source code in src/compas_timber/base.py

def transformation_to_local(self):
    """Compute the transformation to local coordinates of this element
    based on its position in the spatial hierarchy of the model.

    Returns
    -------
    :class:`compas.geometry.Transformation`

    """
    # type: () -> Transformation
    return self.modeltransformation.inverted()

Functions:

clear_element_cache

clear_element_cache(element)

Clear the cached data of element after its own data changed (geometry, features, transformation).

Its model-space data is derived from it, so this also calls :func:clear_model_cache.

Parameters:

• element (:class:`compas_model.elements.Element`) –

Source code in src/compas_timber/base.py

def clear_element_cache(element):
    """Clear the cached data of `element` after its own data changed (geometry, features, transformation).

    Its model-space data is derived from it, so this also calls :func:`clear_model_cache`.

    Parameters
    ----------
    element : :class:`compas_model.elements.Element`

    """
    for name in getattr(element, "ELEMENT_CACHE", ELEMENT_CACHE):
        setattr(element, name, None)
    clear_model_cache(element)

clear_model_cache

clear_model_cache(element)

Clear the cached model-space data of element and of all its descendants, after its placement changed.

The descendants' placement is composed from element's, so their model-space data is cleared too.

Parameters:

• element (:class:`compas_model.elements.Element`) –

Source code in src/compas_timber/base.py

def clear_model_cache(element):
    """Clear the cached model-space data of `element` and of all its descendants, after its placement changed.

    The descendants' placement is composed from `element`'s, so their model-space data is cleared too.

    Parameters
    ----------
    element : :class:`compas_model.elements.Element`

    """
    for e in [node.element for node in element.treenode.traverse()] if element.treenode else [element]:
        for name in getattr(e, "MODEL_CACHE", MODEL_CACHE):
            setattr(e, name, None)