compas_timber.connections ¤

Classes¤

BallNodeJoint ¤

BallNodeJoint(beams=None, base_interface=None, ball_diameter=None, **kwargs)

Represents a ball node type joint which joins the ends of multiple beams, trimming the main beam.

Please use BallNodeJoint.create() to properly create an instance of this class and associate it with an model.

Parameters:

beams ( list(:class:`~compas_timber.elements.Beam`), default: None ) –

The beams to be joined.
base_interface (:class:`~compas_timber.connections.FastenerTimberInterface`, default: None ) –

Describes the interface between the fastener and each of the timber elements.
ball_diameter (float, default: None ) –

The diameter of the ball node.

Attributes:

elements (list(:class:`~compas_timber.elements.Element`)) –

The elements joined by this joint.
generated_elements (list(:class:`~compas_timber.elements.Element`)) –

The elements generated by this joint.

Attributes¤

node_point `property` ¤

node_point

Returns the point at which the beams are joined, essentially the average of their intersection points.

Functions¤

add_features ¤

add_features()

Adds the features of the joint as generated by FastenerTimberInterface to the timber elements. In this joint, the fastener adapt to the beams, therefore, the joint creates the FastenerTimberInterface and adds it to the fastener.

create `classmethod` ¤

create(model, *elements, **kwargs)

Creates an instance of the BallNodeJoint and creates the new connection in model.

This differs fom the generic Joint.create() method in that it passes the beams to the constructor of the BallNodeJoint as a list instead of as separate arguments.

beams are expected to have been added to model before calling this method.

This code does not verify that the given beams are adjacent and/or lie in a topology which allows connecting them. This is the responsibility of the calling code.

A ValueError is raised if beams contains less than two Beam objects.

Parameters:

model (:class:`~compas_timber.model.TimberModel`) –

The model to which the beams and this joing belong.
elements (list(:class:`~compas_timber.elements.Beam`), default: () ) –

A list containing beams that whould be joined together

Returns:

class:`compas_timber.connections.Joint` –

The instance of the created joint.

ButtJoint ¤

ButtJoint(
    main_beam: Beam = None,
    cross_beam: Beam = None,
    mill_depth: float | None = None,
    modify_cross: bool = True,
    butt_plane: Plane | None = None,
    force_pocket: bool = False,
    conical_tool: bool = False,
    **kwargs,
)

Represents an L-Butt type joint which joins two beam in their ends, trimming the main beam.

This joint type is compatible with beams in L topology.

Please use LButtJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The main beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The cross beam to be joined.
mill_depth (float, default: None ) –

The depth of the pocket to be milled in the cross beam. This will be ignored if butt_plane is provided.
modify_cross (bool, default: False ) –

If True, the cross beam will be extended to the opposite face of the main beam and cut with the same plane.
butt_plane (:class:`~compas.geometry.Plane`, default: None ) –

The plane used to cut the main beam. If not provided, the closest side of the cross beam will be used.
force_pocket (bool, default: False ) –

If True applies a :~compas_timber.fabrication.Pocket feature instead of a :~compas_timber.fabrication.Lap on the cross beam. Default is False.
conical_tool (bool, default: False ) –

If True it can apply smaller than 90 degrees angles to the TiltSide parameters of the :~compas_timber.fabrication.Pocket feature. Default is False.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

The main beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`) –

The cross beam to be joined.
mill_depth (float) –

The depth of the pocket to be milled in the cross beam.
modify_cross (bool, default False) –

If True, the cross beam will be extended to the opposite face of the main beam and cut with the same plane.
butt_plane (:class:`~compas.geometry.Plane`, optional) –

The plane used to cut the main beam. If not provided, the closest side of the cross beam will be used.
force_pocket (bool) –

If True applies a :~compas_timber.fabrication.Pocket feature instead of a :~compas_timber.fabrication.Lap on the cross beam. Default is False.
conical_tool (bool) –

If True it can apply smaller than 90 degrees angles to the TiltSide parameters of the :~compas_timber.fabrication.Pocket feature. Default is False.
features (list[BTLxProcessing]) –

List of features to be applied to the cross beam and main beam.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features() -> None

Removes this joint's previously generated features and adds new features to each beam.

Cluster ¤

Cluster(joints)

Groups together the clustered joints and offers access to the beams

Parameters:

joints (list[:class:`~compas_timber.connections.Joint`]) –

The joints that are part of this cluster.

Attributes:

joints (list[:class:`~compas_timber.connections.Joint`]) –

The joints that are part of this cluster.
elements (set[:class:`~compas_timber.elements.Element`]) –

List of unique instances of elements that are part of this cluster.
location (:class:`~compas.geometry.Point`) –

The approximated location of the cluster, effectively the location of the first joint.

Attributes¤

topology `property` ¤

topology

Returns the topology of the joint if there is only one joint, otherwise TOPO_UNKNOWN.

ConnectionSolver ¤

Provides tools for detecting beam intersections and joint topologies.

Functions¤

find_intersecting_pairs `classmethod` ¤

find_intersecting_pairs(beams, rtree=False, max_distance=0.0)

Finds pairs of intersecting beams in the given list of beams.

Parameters:

beams (list(:class:`~compas_timber.elements.Beam`)) –

A list of beam objects.
rtree (bool, default: False ) –

When set to True R-tree will be used to search for neighboring beams.
max_distance (float, default: 0.0 ) –

When rtree is True, an additional distance apart with which non-touching beams are still considered intersecting.

Returns:

list(set(:class:`~compas_timber.elements.Beam`, :class:`~compas_timber.elements.Beam`)) –

List containing sets or neightboring pairs beams.

find_topology ¤

find_topology(beam_a, beam_b, max_distance=None)

If beam_a and beam_b intersect within the given max_distance, return the topology type of the intersection.

If the topology is role-sensitive, the method outputs the beams in a consistent specific order (e.g. main beam first, cross beam second), otherwise, the beams are outputted in the same order as they were inputted.

Parameters:

beam_a (:class:`~compas_timber.elements.Beam`) –

First beam from intersecting pair.
beam_b (:class:`~compas_timber.elements.Beam`) –

Second beam from intersecting pair.
max_distance (float, default: None ) –

Maximum distance, in design units, at which two beams are considered intersecting.

Returns:

class:`~compas_timber.connections.BeamSolverResult` –

The topology results of the intersection between the two beams.

Joint ¤

Joint(
    elements=None, topology=None, location=None, name=None, element_guids=None, **kwargs
)

Base class for a joint connecting two beams.

This is a base class and should not be instantiated directly. Use the create() class method of the respective implementation of Joint instead.

Parameters:

topology (literal, one of :class:`JointTopology`, default: None ) –

The topology by which the two elements connected with this joint interact.
location (:class:`~compas.geometry.Point`, default: None ) –

The estimated location of the interaction point of the two elements connected with this joint.

Attributes:

name (str) –

The name of the joint. Corresponds to the class name.
elements (tuple(:class:`~compas_model.elements.Element`)) –

The elements joined by this joint.
generated_elements (list(:class:`~compas_model.elements.Element`)) –

A list of elements that were generated by this joint.
ends (dict(str, str)) –

Maps the GUID of each element to start or end, depending on which end of the element is connected by this joint.
interactions (list(tuple(:class:`~compas_model.elements.Element`, :class:`~compas_model.elements.Element`))) –

A list of tuples containing the elements that are interacting with each other through this joint.
features (list(:class:`~compas_timber.fabrication.BTLxProcessing`)) –

A list of features that were added to the elements by this joint.
topology (literal, one of :class:`JointTopology`) –

The topology by which the two elements connected with this joint interact.
location (:class:`~compas.geometry.Point`) –

The estimated location of the interaction point of the two elements connected with this joint.

Returned by:

API Reference
- model Classes TimberModel Functions get_joints_for_element
- structural Classes BeamStructuralElementSolver Functions add_structural_segments

Used by:

API Reference
- connections Functions get_clusters_from_joint_candidates
- structural Classes

Functions¤

add_extensions ¤

add_extensions()

Adds the extensions defined by this joint to affected beam(s). This is optional and should only be implemented by joints that require it.

Notes

Extensions are added to all beams before the features are added.

Raises:

:class:`~compas_timber.connections.BeamJoiningError` –

Should be raised whenever the joint was not able to calculate the extensions to be applied to the beams.

add_features ¤

add_features()

Adds the features defined by this joint to affected beam(s).

Raises:

:class:`~compas_timber.connections.BeamJoiningError` –

Should be raised whenever the joint was not able to calculate the features to be applied to the beams.

check_elements_compatibility `classmethod` ¤

check_elements_compatibility(elements, raise_error=False)

Checks if the cluster of beams complies with the requirements for the Joint.

Parameters:

elements (list of :class:`~compas_timber.elements.Beam`) –

The beams to check.
raise_error (bool, default: False ) –

If True, raises a BeamJoiningError if the requirements are not met.

Returns:

bool –

True if the cluster complies with the requirements, False otherwise.

create `classmethod` ¤

create(model, *elements, **kwargs)

Creates an instance of this joint and creates the new connection in model.

elements are expected to have been added to model before calling this method.

This code does not verify that the given elements are adjacent and/or lie in a topology which allows connecting them. This is the responsibility of the calling code.

Parameters:

model (:class:`~compas_timber.model.TimberModel`) –

The model to which the elements and this joint belong.
*elements (:class:`~compas_model.elements.Element`, default: () ) –

The elements to be connected by this joint. The number of elements must comply with the Joint class's MIN_ELEMENT_COUNT and MAX_ELEMENT_COUNT attributes.
**kwargs (dict, default: {} ) –

Additional keyword arguments that are passed to the joint's constructor.

Returns:

class:`compas_timber.connections.Joint` –

The instance of the created joint.

element_count_complies `classmethod` ¤

element_count_complies(elements)

Checks if the number of elements complies with the joint's requirements.

Parameters:

elements (list(:class:`~compas_model.elements.Element`)) –

The elements to be checked.

Returns:

bool –

promote_cluster `classmethod` ¤

promote_cluster(model, cluster, reordered_elements=None, **kwargs)

Creates an instance of this joint from a cluster of elements.

Parameters:

model (:class:`~compas_timber.model.TimberModel`) –

The model to which the elements and this joint belong.
cluster (:class:`~compas_model.clusters.Cluster`) –

The cluster containing the elements to be connected by this joint.
reordered_elements (list(:class:`~compas_model.elements.Element`), default: None ) –

The elements to be connected by this joint. If not provided, the elements of the cluster will be used. This is used to explicitly define the element order.
**kwargs (dict, default: {} ) –

Additional keyword arguments that are passed to the joint's constructor.

Returns:

class:`compas_timber.connections.Joint` –

The instance of the created joint.

promote_joint_candidate `classmethod` ¤

promote_joint_candidate(model, candidate, reordered_elements=None, **kwargs)

Creates an instance of this joint from a joint candidate.

Parameters:

model (:class:`~compas_timber.model.TimberModel`) –

The model to which the elements and this joint belong.
candidate (:class:`~compas_timber.connections.JointCandidate`) –

The joint candidate to be converted.
reordered_elements (list(:class:`~compas_model.elements.Element`), default: None ) –

The elements to be connected by this joint. If not provided, the elements of the generic joint will be used. This is used to explicitly define the element order.
**kwargs (dict, default: {} ) –

Additional keyword arguments that are passed to the joint's constructor.

Returns:

class:`compas_timber.connections.Joint` –

The instance of the created joint.

restore_elements_from_keys ¤

restore_elements_from_keys(model)

Restores the reference to the elements associated with this joint.

During serialization, :class:compas_timber.elements.Beam objects are serialized by :class:compas_timber.model.Model. To avoid circular references, Joint only stores the keys of the respective elements.

This method is called by :class:compas_timber.model.TimberModel during de-serialization to restore the references. Since the roles of the elements are joint specific (e.g. main/cross beam) this method should be implemented by the concrete implementation.

Examples:

See :class:compas_timber.connections.TButtJoint.

JointCandidate ¤

JointCandidate(element_a=None, element_b=None, distance=None, **kwargs)

A JointCandidate is an information-only joint, which does not add any features to the elements it connects.

It is used to create a first-pass joinery information which can be later grouped into a Clusters and then promoted to concrete joints.

Please use JointCandidate.create() to properly create an instance of this class and associate it with an model.

Parameters:

element_a (:class:`~compas_timber.elements.TimberElement`, default: None ) –

First element to be joined.
element_b (:class:`~compas_timber.elements.TimberElement`, default: None ) –

Second element to be joined.
distance (float | None, default: None ) –

Distance between the elements.

Attributes:

element_a (:class:`~compas_timber.elements.TimberElement`) –

First element to be joined.
element_b (:class:`~compas_timber.elements.TimberElement`) –

Second element to be joined.
distance (float | None) –

Distance between the elements.

Returned by:

API Reference model Classes TimberModel Functions get_candidates_for_element

Functions¤

add_features ¤

add_features()

This joint does not add any features.

JointTopology ¤

Enumeration of the possible joint topologies.

Attributes:

TOPO_UNKNOWN –
TOPO_I - end-to-end joint between two parallel beams –
TOPO_L - end-to-end joint between two non-parallel beams –
TOPO_T - end-to-middle joint between two beams –
TOPO_X - middle-to-middle joint between two beams –
TOPO_Y - joint between three or more beams where all beams meet at their ends –
TOPO_K - joint between three or more beams where at least one beam meet in the middle –
TOPO_EDGE_EDGE - joint between two plates where the edges of both plates are aligned –
TOPO_EDGE_FACE - joint between two plates where one plate is aligned with the face of the other –

Used by:

API Reference connections Classes

Functions¤

get_name `classmethod` ¤

get_name(value)

Returns the string representation of given topology value.

For use in logging.

Parameters:

value (int) –

One of [JointTopology.TOPO_I, JointTopology.TOPO_L, JointTopology.TOPO_T, JointTopology.TOPO_X, JointTopology.TOPO_Y, JointTopology.TOPO_K, JointTopology.TOPO_EDGE_EDGE, JointTopology.TOPO_EDGE_FACE, JointTopology.TOPO_UNKNOWN]

Returns:

str –

One of ["TOPO_I", "TOPO_L", "TOPO_T", "TOPO_X", "TOPO_Y", "TOPO_K", "TOPO_EDGE_EDGE", "TOPO_EDGE_FACE", "TOPO_UNKNOWN"]

LButtJoint ¤

LButtJoint(
    main_beam=None,
    cross_beam=None,
    mill_depth=None,
    modify_cross=True,
    reject_i=False,
    butt_plane=None,
    back_plane=None,
    **kwargs,
)

Represents an L-Butt type joint which joins two beam in their ends, trimming the main beam.

This joint type is compatible with beams in L topology.

Please use LButtJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The main beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The cross beam to be joined.
mill_depth (float, default: None ) –

The depth of the pocket to be milled in the cross beam. This will be ignored if butt_plane is provided.
small_beam_butts (bool, default: False ) –

If True, the beam with the smaller cross-section will be trimmed. Otherwise, the main beam will be trimmed.
modify_cross (bool, default: False ) –

If True, the cross beam will be extended to the opposite face of the main beam and cut with the same plane.
butt_plane (:class:`~compas.geometry.Plane`, default: None ) –

The plane used to cut the main beam. If not provided, the closest side of the cross beam will be used.
back_plane (:class:`~compas.geometry.Plane`, default: None ) –

The plane used to cut the cross beam. If not provided, the back side of the main beam will be used.
reject_i (bool, default: False ) –

If True, the joint will reject beams in I topology.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

The main beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`) –

The cross beam to be joined.
mill_depth (float) –

The depth of the pocket to be milled in the cross beam.
modify_cross (bool, default False) –

If True, the cross beam will be extended to the opposite face of the main beam and cut with the same plane.
butt_plane (:class:`~compas.geometry.Plane`, optional) –

The plane used to cut the main beam. If not provided, the closest side of the cross beam will be used.
back_plane (:class:`~compas.geometry.Plane`, optional) –

The plane used to cut the cross beam. If not provided, the back side of the main beam will be used.
reject_i (bool, default False) –

If True, the joint will reject beams in I topology.

LFrenchRidgeLapJoint ¤

LFrenchRidgeLapJoint(
    beam_a=None, beam_b=None, flip_lap_side=False, drillhole_diam=None, **kwargs
)

Represents an L-FrenchRidgeLap type joint which joins two beams at their ends, by lapping them with a ridge. The joint can only be created between two beams that are aligned and have the same dimensions.

This joint type is compatible with beams in L topology.

Please use LFrenchRidgeLapJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

beam_a (:class:`~compas_timber.elements.Beam`, default: None ) –

The first beam to be joined.
beam_b (:class:`~compas_timber.elements.Beam`, default: None ) –

The second beam to be joined.
flip_lap_side (bool, default: False ) –

If True, the lap is flipped to the other side of the beams.
drillhole_diam (float, default: None ) –

Diameter of the drill hole to be made in the joint.

Attributes:

beam_a (:class:`~compas_timber.elements.Beam`) –

The first beam to be joined.
beam_b (:class:`~compas_timber.elements.Beam`) –

The second beam to be joined.
flip_lap_side (bool) –

If True, the lap is flipped to the other side of the beams.
drillhole_diam (float) –

Diameter of the drill hole to be made in the joint.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

This method is automatically called when joint is created by the call to Joint.create().

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features()

Adds the necessary features to the beams.

This method is called during the Model.process_joinery() process after the joint has been instantiated and added to the model. It is executed after the beam extensions have been added via Joint.add_extensions().

check_elements_compatibility `classmethod` ¤

check_elements_compatibility(elements, raise_error=False)

Checks if the cluster of beams complies with the requirements for the LFrenchRidgeLapJoint.

Parameters:

elements (list(:class:`~compas_model.elements.Beam`)) –

The elements to be checked.
raise_error (bool, default: False ) –

If True, raises a :class:~compas_timber.errors.BeamJoiningError if the cluster does not comply with the requirements. If False, returns False instead.

Returns:

bool –

True if the cluster complies with the requirements, False otherwise.

LLapJoint ¤

LLapJoint(beam_a=None, beam_b=None, flip_lap_side=False, cut_plane_bias=0.5, **kwargs)

Represents an L-Lap type joint which joins the ends of two beams with a lap.

This joint type is compatible with beams in L topology.

Please use LLapJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

beam_a (:class:`~compas_timber.elements.Beam`, default: None ) –

The first beam to be joined.
beam_b (:class:`~compas_timber.elements.Beam`, default: None ) –

The second beam to be joined.
flip_lap_side (bool, default: False ) –

If True, the lap is flipped to the other side of the beams.
cut_plane_bias (float, default: 0.5 ) –

Allows lap to be shifted deeper into one beam or the other. Value should be between 0 and 1.0 without completely cutting through either beam. Default is 0.5.

Attributes:

beam_a (:class:`~compas_timber.elements.Beam`) –

The first beam to be joined.
beam_b (:class:`~compas_timber.elements.Beam`) –

The second beam to be joined.
flip_lap_side (bool) –

If True, the lap is flipped to the other side of the beams.
cut_plane_bias (float) –

Allows lap to be shifted deeper into one beam or the other. Value should be between 0 and 1.0 without completely cutting through either beam. Default is 0.5.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features()

Adds the required joint features to both beams.

LMiterJoint ¤

LMiterJoint(
    beam_a=None,
    beam_b=None,
    cutoff=None,
    miter_plane=None,
    ref_side_miter=False,
    clean=False,
    **kwargs,
)

Represents an L-Miter type joint which joins two beam in their ends, trimming them with a plane at the bisector angle between the beams' centerlines.

This joint type is compatible with beams in L topology.

Please use LMiterJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

beam_a (:class:`~compas_timber.elements.Beam`, default: None ) –

First beam to be joined.
beam_b (:class:`~compas_timber.elements.Beam`, default: None ) –

Second beam to be joined.
cutoff (bool, default: None ) –

If True, the beams will be trimmed with a plane perpendicular to the bisector (miter) plane of the beams.
miter_plane (:class:`~compas.geometry.Plane`, default: None ) –

A plane that defines the miter cut location and orientation. If not provided, it will be calculated automatically. If provided, miter_type will be automatically set to MiterType.USER_DEFINED.
ref_side_miter (:bool, default: False ) –

If True, the miter plane will be calculated based on the reference sides of the beams instead of the bisector of the centerlines.
clean (bool, default: False ) –

if True, cleaning cuts will be applied to each beam based on the back sides of the other beam.

Attributes:

beam_a (:class:`~compas_timber.elements.Beam`) –

First beam to be joined.
beam_b (:class:`~compas_timber.elements.Beam`) –

Second beam to be joined.
cutoff (bool) –

If True, the beams will be trimmed with a plane perpendicular to the bisector (miter) plane of the beams.
miter_plane (:class:`~compas.geometry.Plane`) –

A user-defined plane that defines the miter cut location and orientation.
ref_side_miter (:bool) –

If True, the miter plane will be calculated based on the reference sides of the beams instead of the bisector of the centerlines.
clean (bool) –

if True, cleaning cuts will be applied to each beam based on the back sides of the other beam.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

This method is automatically called when joint is created by the call to Joint.create().

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features()

Adds the required extension and trimming features to both beams.

This method is automatically called when joint is created by the call to Joint.create().

LTenonMortiseJoint ¤

LTenonMortiseJoint(main_beam=None, cross_beam=None, modify_cross=False, **kwargs)

Represents a TenonMortise type joint which joins two beams, one of them at its end (main) and the other one along its centerline (cross) or both of them at their ends. A tenon is added on the main beam, and a corresponding mortise is made on the cross beam to fit the main beam's tenon.

This joint type is compatible with beams in L topology.

Please use LTenonMortiseJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

Second beam to be joined.
start_y (float) –

Start position of the tenon along the y-axis of the main beam.
start_depth (float) –

Depth of the tenon from the surface of the main beam.
rotation (float) –

Rotation of the tenon around the main beam's axis.
length (float) –

Length of the tenon along the main beam.
width (float) –

Width of the tenon.
height (float) –

Height of the tenon.
tenon_shape (:class:`~compas_timber.fabrication.TenonShapeType`) –

Shape of the tenon. One of :class:~compas_timber.fabrication.TenonShapeType: AUTOMATIC, SQUARE, ROUND, ROUNDED, RADIUS. Defaults to TenonShapeType.ROUND.
shape_radius (float) –

The radius used to define the shape of the tenon, if applicable.
modify_cross (bool, default: False ) –

If True, the cross beam will be extended to the opposite face of the main beam and cut with the same plane.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`) –

Second beam to be joined.
main_beam_guid (str) –

GUID of the main beam.
cross_beam_guid (str) –

GUID of the cross beam.
start_y (float) –

Start position of the tenon along the y-axis of the main beam.
start_depth (float) –

Depth of the tenon from the surface of the main beam.
rotation (float) –

Rotation of the tenon around the main beam's axis.
length (float) –

Length of the tenon along the main beam.
width (float) –

Width of the tenon.
height (float) –

Height of the tenon.
tenon_shape (:class:`~compas_timber.fabrication.TenonShapeType`) –

Shape of the tenon. One of :class:~compas_timber.fabrication.TenonShapeType: AUTOMATIC, SQUARE, ROUND, ROUNDED, RADIUS.
shape_radius (float) –

The radius used to define the shape of the tenon, if applicable.
modify_cross (bool) –

If True, the cross beam will be extended to the opposite face of the main beam and cut with the same plane.
features (list) –

List of features or machining processings applied to the elements.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

This method is automatically called when joint is created by the call to Joint.create().

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features()

Adds the required trimming features to both beams.

This method is automatically called when joint is created by the call to Joint.create().

LapJoint ¤

LapJoint(beam_a=None, beam_b=None, flip_lap_side=False, cut_plane_bias=0.5, **kwargs)

Abstract Lap type joint with functions common to L-Lap, T-Lap, and X-Lap Joints.

Do not instantiate directly. Please use **LapJoint.create() to properly create an instance of lap sub-class and associate it with an model.

Parameters:

beam_a (:class:`~compas_timber.elements.Beam`, default: None ) –

The first beam to be joined.
beam_b (:class:`~compas_timber.elements.Beam`, default: None ) –

The second beam to be joined.
flip_lap_side (bool, default: False ) –

If True, the lap is flipped to the other side of the beams.

Attributes:

elements (list of :class:`~compas_timber.elements.Beam`) –

The beams to be joined.
beam_a (:class:`~compas_timber.elements.Beam`) –

The first beam to be joined.
beam_b (:class:`~compas_timber.elements.Beam`) –

The second beam to be joined.
flip_lap_side (bool) –

If True, the lap is flipped to the other side of the beams.

Attributes¤

cutting_plane_a `property` ¤

cutting_plane_a

The face of the beam_b that cuts the beam_a, as a plane.

cutting_plane_b `property` ¤

cutting_plane_b

The face of the beam_a that cuts the beam_b, as a plane.

ref_side_index_a `property` ¤

ref_side_index_a

The reference side index of the beam_a.

ref_side_index_b `property` ¤

ref_side_index_b

The reference side index of the beam_b.

MortiseTenonJoint ¤

MortiseTenonJoint(
    main_beam=None,
    cross_beam=None,
    start_y=None,
    start_depth=None,
    rotation=None,
    length=None,
    width=None,
    height=None,
    tenon_shape=None,
    shape_radius=None,
    **kwargs,
)

Base class for mortise-tenon joints.

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

This class stores shared parameter handling, serialization, and feature creation helpers used by mortise-tenon joint variants.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

Second beam to be joined.
start_y (float, default: None ) –

Start position of the tenon along the y-axis of the main beam.
start_depth (float, default: None ) –

Depth of the tenon from the surface of the main beam.
rotation (float, default: None ) –

Rotation of the tenon around the main beam's axis.
length (float, default: None ) –

Length of the tenon along the main beam.
width (float, default: None ) –

Width of the tenon.
height (float, default: None ) –

Height of the tenon.
tenon_shape (str, default: None ) –

Shape of the tenon. One of :class:~compas_timber.fabrication.TenonShapeType: AUTOMATIC, SQUARE, ROUND, ROUNDED, RADIUS. Defaults to TenonShapeType.ROUND.
shape_radius (float, default: None ) –

The radius used to define the shape of the tenon, if applicable.
**kwargs (dict, default: {} ) –

Additional keyword arguments.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`) –

Second beam to be joined.
main_beam_guid (str) –

GUID of the main beam.
cross_beam_guid (str) –

GUID of the cross beam.
start_y (float) –

Start position of the tenon along the y-axis of the main beam.
start_depth (float) –

Depth of the tenon from the surface of the main beam.
rotation (float) –

Rotation of the tenon around the main beam's axis.
length (float) –

Length of the tenon along the main beam.
width (float) –

Width of the tenon.
height (float) –

Height of the tenon.
tenon_shape (str) –

Shape of the tenon. One of :class:~compas_timber.fabrication.TenonShapeType: AUTOMATIC, SQUARE, ROUND, ROUNDED, RADIUS.
shape_radius (float) –

The radius used to define the shape of the tenon, if applicable.
features (list) –

List of features or machining processings applied to the elements.

Functions¤

get_main_extension ¤

get_main_extension()

Return the start/end extension lengths for the main beam.

Raises:

BeamJoiningError –

If the extension could not be calculated.

PanelJoint ¤

PanelJoint(
    panel_a: Panel | None = None,
    panel_b: Panel | None = None,
    topology: JointTopology | None = None,
    a_segment_index: int | None = None,
    b_segment_index: int | None = None,
    **kwargs,
)

Models a plate to plate interaction.

Parameters:

panel_a (:class:`compas_timber.elements.Panel`, default: None ) –

The first plate.
panel_b (:class:`compas_timber.elements.Panel`, default: None ) –

The second plate.
topology (literal(JointTopology), default: None ) –

The topology in which the plates are connected.
a_segment_index (int, default: None ) –

The index of the segment in panel_a's outline where the plates are connected.
b_segment_index (int, default: None ) –

The index of the segment in panel_b's outline where the plates are connected.
**kwargs (dict, default: {} ) –

Additional keyword arguments to pass to the parent class.

Attributes:

panel_a (:class:`compas_timber.elements.Panel`) –

The first plate.
panel_b (:class:`compas_timber.elements.Panel`) –

The second plate.
panels (tuple of :class:`compas_timber.elements.Panel`) –

The panels that are connected.
interface_a (:class:`compas.geometry.PlanarSurface`) –

The interface surface of panel_a where it meets panel_b.
interface_b (:class:`compas.geometry.PlanarSurface`) –

The interface surface of panel_b where it meets panel_a.

PanelLButtJoint ¤

PanelLButtJoint(
    panel_a: Panel | None = None,
    panel_b: Panel | None = None,
    topology: JointTopology | None = None,
    a_segment_index: int | None = None,
    b_segment_index: int | None = None,
    **kwargs,
)

Creates a plate-to-plate butt-joint connection.

Attributes¤

cross_panel `property` ¤

cross_panel: Panel

Return the cross plate.

main_panel `property` ¤

main_panel: Panel

Return the main plate.

PanelMiterJoint ¤

PanelMiterJoint(
    panel_a: Panel | None = None,
    panel_b: Panel | None = None,
    topology: JointTopology | None = None,
    a_segment_index: int | None = None,
    b_segment_index: int | None = None,
    **kwargs,
)

Creates a mitered edge plate-to-plate connection.

PanelTButtJoint ¤

PanelTButtJoint(
    panel_a: Panel | None = None,
    panel_b: Panel | None = None,
    topology: JointTopology | None = None,
    a_segment_index: int | None = None,
    b_segment_index: int | None = None,
    **kwargs,
)

Creates a plate-to-plate butt-joint connection.

Attributes¤

cross_panel `property` ¤

cross_panel: Panel

Return the cross plate.

main_panel `property` ¤

main_panel: Panel

Return the main plate.

PlateButtJoint ¤

PlateButtJoint(
    plate_a=None,
    plate_b=None,
    topology=None,
    a_segment_index=None,
    b_segment_index=None,
    **kwargs,
)

Creates a plate-to-plate butt-joint connection.

Attributes¤

cross_plate `property` ¤

cross_plate

Return the cross plate.

cross_segment_index `property` `writable` ¤

cross_segment_index

Return the index of the segment in the cross plate outline.

main_plate `property` ¤

main_plate

Return the main plate.

main_segment_index `property` `writable` ¤

main_segment_index

Return the index of the segment in the main plate outline.

PlateConnectionSolver ¤

Provides tools for detecting plate intersections and joint topologies.

Functions¤

do_segments_overlap `staticmethod` ¤

do_segments_overlap(segment_a, segment_b)

Checks if two segments overlap.

Parameters:

segment_a (:class:`~compas.geometry.Segment`) –

The first segment.
segment_b (:class:`~compas.geometry.Segment`) –

The second segment.

Returns:

bool –

True if the segments overlap, False otherwise.

does_segment_intersect_outline `staticmethod` ¤

does_segment_intersect_outline(segment, polyline, tol=TOL)

Checks if a segment intersects with the outline of a polyline.

Parameters:

segment (:class:`~compas.geometry.Segment`) –

The segment to check for intersection.
polyline (:class:`~compas.geometry.Polyline`) –

The polyline whose outline is checked for intersection.
tol (float, default: TOL ) –

Tolerance for intersection check.

Returns:

bool –

True if the segment intersects with the outline of the polyline, False otherwise.

find_topology ¤

find_topology(plate_a, plate_b, max_distance=TOLERANCE, tol=TOLERANCE)

Calculates the topology of the intersection between two plates. requires that one edge of a plate lies on the plane of the other plate. When TOPOLOGY_EDGE_FACE is found, the plates are returned in reverse order, with the main plate first and the cross plate second.

Parameters:

plate_a (:class:`~compas_timber.elements.Plate`) –

First potential intersecting plate.
plate_b (:class:`~compas_timber.elements.Plate`) –

Second potential intersecting plate.
tol (float, default: TOLERANCE ) –

General tolerance to use for mathematical computations.
max_distance (float, default: TOLERANCE ) –

Maximum distance, in desigen units, at which two plates are considered intersecting.

Returns:

class:`~compas_timber.connections.PlateSolverResult` –

PlateJoint ¤

PlateJoint(
    plate_a=None,
    plate_b=None,
    topology=None,
    a_segment_index=None,
    b_segment_index=None,
    **kwargs,
)

Models a plate to plate interaction.

Parameters:

plate_a (:class:`compas_timber.elements.Plate`, default: None ) –

The first plate.
plate_b (:class:`compas_timber.elements.Plate`, default: None ) –

The second plate.
topology (literal(JointTopology), default: None ) –

The topology in which the plates are connected.
a_segment_index (int, default: None ) –

The index of the segment in plate_a's outline where the plates are connected.
b_segment_index (int, default: None ) –

The index of the segment in plate_b's outline where the plates are connected.
location (:class:`compas.geometry.Point`) –

The location of the joint. If not provided, defaults to the origin.
**kwargs (dict, default: {} ) –

Additional keyword arguments to pass to the parent class.

Attributes:

plate_a (:class:`compas_timber.elements.Plate`) –

The first plate.
plate_b (:class:`compas_timber.elements.Plate`) –

The second plate.
plates (tuple of :class:`compas_timber.elements.Plate`) –

The plates that are connected.

Functions¤

add_extensions ¤

add_extensions()

Adjusts plate outlines to outer shape required for the joint.

add_features ¤

add_features()

Adds features to the plates based on the joint. this should be implemented in subclasses if needed.

calculate_topology ¤

calculate_topology(allow_reordering=False)

Calculate the topology of the joint based on the plates.

promote_joint_candidate `classmethod` ¤

promote_joint_candidate(model, candidate, reordered_elements=None, **kwargs)

Creates an instance of this joint from a generic joint.

Parameters:

model (:class:`~compas_timber.model.TimberModel`) –

The model to which the elements and this joint belong.
candidate (:class:`~compas_timber.connections.Joint`) –

The generic joint to be converted.
reordered_elements (list(:class:`~compas_model.elements.Element`), default: None ) –

The elements to be connected by this joint. If not provided, the elements of the generic joint will be used. This is used to explicitly define the element order.
**kwargs (dict, default: {} ) –

Additional keyword arguments that are passed to the joint's constructor.

Returns:

class:`compas_timber.connections.Joint` –

The instance of the created joint.

PlateJointCandidate ¤

PlateJointCandidate(plate_a=None, plate_b=None, **kwargs)

A PlateJointCandidate is an information-only joint for plate connections.

It is used to create a first-pass joinery information which can be later used to create concrete joints.

Parameters:

plate_a (:class:`~compas_timber.elements.Plate`, default: None ) –

First plate to be joined.
plate_b (:class:`~compas_timber.elements.Plate`, default: None ) –

Second plate to be joined.

Attributes:

plate_a (:class:`~compas_timber.elements.Plate`) –

First plate to be joined.
plate_b (:class:`~compas_timber.elements.Plate`) –

Second plate to be joined.

PlateLButtJoint ¤

PlateLButtJoint(
    plate_a=None,
    plate_b=None,
    topology=None,
    a_segment_index=None,
    b_segment_index=None,
    **kwargs,
)

Creates a plate-to-plate butt-joint connection.

PlateMiterJoint ¤

PlateMiterJoint(
    plate_a=None,
    plate_b=None,
    topology=None,
    a_segment_index=None,
    b_segment_index=None,
    **kwargs,
)

Creates a mitered edge plate-to-plate connection.

PlateTButtJoint ¤

PlateTButtJoint(
    plate_a=None,
    plate_b=None,
    topology=None,
    a_segment_index=None,
    b_segment_index=None,
    **kwargs,
)

Creates a plate-to-plate butt-joint connection.

TBirdsmouthJoint ¤

TBirdsmouthJoint(main_beam=None, cross_beam=None, mill_depth=None, **kwargs)

Represents a T-Birdsmouth type joint which joins two beams, one of them at it's end (main) and the other one along it's centerline (cross).

This joint type is compatible with beams in T topology.

Please use TBirdsmouth.create() to properly create an instance of this class and associate it with a model.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

Second beam to be joined.
mill_depth (float, default: None ) –

The depth of the pockets to be milled on the cross beam.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`) –

Second beam to be joined.
mill_depth (float) –

The depth of the pockets to be milled on the cross beam.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

This method is automatically called when joint is created by the call to Joint.create().

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features()

Adds the required trimming features to both beams.

This method is automatically called when joint is created by the call to Joint.create().

TButtJoint ¤

TButtJoint(
    main_beam=None,
    cross_beam=None,
    mill_depth=None,
    butt_plane=None,
    fastener=None,
    **kwargs,
)

Represents a T-Butt type joint which joins the end of a beam along the length of another beam, trimming the main beam.

This joint type is compatible with beams in T topology.

Please use TButtJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The main beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The cross beam to be joined.
mill_depth (float, default: None ) –

The depth of the pocket to be milled in the cross beam.
butt_plane (:class:`~compas.geometry.Plane`, default: None ) –

The plane used to cut the main beam. If not provided, the closest side of the cross beam will be used.
fastener (:class:`~compas_timber.elements.Fastener`, default: None ) –

The fastener to be used in the joint.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

The main beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`) –

The cross beam to be joined.
mill_depth (float) –

The depth of the pocket to be milled in the cross beam.

Attributes¤

interactions `property` ¤

interactions

Returns interactions between elements used by this joint.

TDovetailJoint ¤

TDovetailJoint(
    main_beam=None,
    cross_beam=None,
    start_y=None,
    start_depth=None,
    rotation=None,
    length=None,
    width=None,
    cone_angle=None,
    dovetail_shape=None,
    tool_angle=None,
    tool_diameter=None,
    tool_height=None,
    **kwargs,
)

Represents a T-Dovetail type joint which joins two beams, one of them at its end (main) and the other one along its centerline (cross). A dovetail cut is made on the main beam, and a corresponding notch is made on the cross beam to fit the main beam.

This joint type is compatible with beams in T topology.

Please use TDovetailJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

Second beam to be joined.
start_y (float, default: None ) –

Start position of the dovetail cut along the y-axis of the main beam.
start_depth (float, default: None ) –

Depth of the dovetail cut from the surface of the main beam.
rotation (float, default: None ) –

Rotation of the dovetail cut around the main beam's axis.
length (float, default: None ) –

Length of the dovetail cut along the main beam.
width (float, default: None ) –

Width of the dovetail cut.
cone_angle (float, default: None ) –

The angle of the dovetail cut, determining the taper of the joint.
dovetail_shape (str, default: None ) –

Shape of the dovetail cut. One of :class:~compas_timber.fabrication.TenonShapeType: AUTOMATIC, SQUARE, ROUND, ROUNDED, RADIUS. Defaults to TenonShapeType.RADIUS.
tool_angle (float, default: None ) –

The angle of the tool used to create the dovetail cut.
tool_diameter (float, default: None ) –

The diameter of the tool used to create the dovetail cut.
tool_height (float, default: None ) –

The height of the tool used to create the dovetail cut.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`) –

Second beam to be joined.
start_y (float) –

Start position of the dovetail cut along the y-axis of the main beam.
start_depth (float) –

Depth of the dovetail cut from the surface of the main beam.
rotation (float) –

Rotation of the dovetail cut around the main beam's axis.
length (float) –

Length of the dovetail cut along the main beam.
width (float) –

Width of the dovetail cut.
cone_angle (float) –

The angle of the dovetail cut, determining the taper of the joint.
dovetail_shape (str) –

Shape of the dovetail cut. One of :class:~compas_timber.fabrication.TenonShapeType: AUTOMATIC, SQUARE, ROUND, ROUNDED, RADIUS.
tool_angle (float) –

The angle of the tool used to create the dovetail cut.
tool_diameter (float) –

The diameter of the tool used to create the dovetail cut.
tool_height (float) –

The height of the tool used to create the dovetail cut.
features (list) –

List of features or machining processings applied to the joint.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

This method is automatically called when joint is created by the call to Joint.create().

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features()

Adds the required trimming features to both beams.

This method is automatically called when joint is created by the call to Joint.create().

define_dovetail_tool ¤

define_dovetail_tool(tool_angle, tool_diameter, tool_height)

Define the parameters for the dovetail feature based on a defined dovetail cutting tool.

Parameters:

tool_angle (float) –

The angle of the dovetail cutter tool.
tool_diameter (float) –

The diameter of the dovetail cutter tool.
tool_height (float) –

The height of the dovetail cutter tool.

TLapJoint ¤

TLapJoint(
    main_beam=None, cross_beam=None, flip_lap_side=False, cut_plane_bias=0.5, **kwargs
)

Represents a T-Lap type joint which joins the end of a beam along the length of another beam with a lap.

This joint type is compatible with beams in T topology.

Please use TLapJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The main beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The cross beam to be joined.
flip_lap_side (bool, default: False ) –

If True, the lap is flipped to the other side of the beams.
cut_plane_bias (float, default: 0.5 ) –

Allows lap to be shifted deeper into one beam or the other. Value should be between 0 and 1.0 without completely cutting through either beam. Default is 0.5.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

The main beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`) –

The cross beam to be joined.
flip_lap_side (bool) –

If True, the lap is flipped to the other side of the beams.
cut_plane_bias (float) –

Allows lap to be shifted deeper into one beam or the other. Value should be between 0 and 1.0 without completely cutting through either beam. Default is 0.5.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

This method is automatically called when joint is created by the call to Joint.create().

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features()

Adds the required extension and trimming features to both beams.

This method is automatically called when joint is created by the call to Joint.create().

TOliGinaJoint ¤

TOliGinaJoint(main_beam, cross_beam, **kwargs)

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

This method is automatically called when joint is created by the call to Joint.create().

Raises:

BeamJoiningError –

If the extension could not be calculated.

TStepJoint ¤

TStepJoint(
    main_beam=None,
    cross_beam=None,
    step_shape=None,
    step_depth=None,
    heel_depth=None,
    tenon_mortise_height=None,
    **kwargs,
)

Represents an T-Step type joint which joins two beams, one of them at it's end (main) and the other one along it's centerline (cross). Two or more cuts are is made on the main beam and a notch is made on the cross beam to fit the main beam.

This joint type is compatible with beams in T topology.

Please use TStepJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

Second beam to be joined.
step_shape (str, default: None ) –

The shape of the step cut. One of :class:~compas_timber.fabrication.StepShapeType: STEP, HEEL, TAPERED_HEEL, or DOUBLE. The shape type takes priority: depths irrelevant to the chosen shape are ignored and forced to zero. Defaults to StepShapeType.STEP.
step_depth (float, default: None ) –

Depth of the step cut. Applicable only to shape types with a step component (STEP, DOUBLE). Defaults to a value proportional to the cross beam's cross-section.
heel_depth (float, default: None ) –

Depth of the heel cut. Applicable only to shape types with a heel component (HEEL, TAPERED_HEEL, DOUBLE). Defaults to a value proportional to the cross beam's cross-section.
tenon_mortise_height (float, default: None ) –

Height of the tenon/mortise feature. If None, no tenon or mortise is created.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`) –

Second beam to be joined.
step_shape (str) –

The shape of the step cut. One of :class:~compas_timber.fabrication.StepShapeType: STEP, HEEL, TAPERED_HEEL, or DOUBLE.
step_depth (float) –

Depth of the step cut. Applicable only to shape types with a step component (STEP, DOUBLE). Zero otherwise.
heel_depth (float) –

Depth of the heel cut. Applicable only to shape types with a heel component (HEEL, TAPERED_HEEL, DOUBLE). Zero otherwise.
tenon_mortise_height (float) –

Height of the tenon/mortise feature. None if not created.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

This method is automatically called when joint is created by the call to Joint.create().

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features()

Adds the required trimming features to both beams.

This method is automatically called when joint is created by the call to Joint.create().

check_elements_compatibility `classmethod` ¤

check_elements_compatibility(elements, raise_error=False)

Checks if the cluster of beams complies with the requirements for the TStepJoint.

Parameters:

elements (list of :class:`~compas_timber.model.TimberElement`) –

The cluster of elements to be checked.
raise_error (bool, default: False ) –

Whether to raise an error if the elements are not compatible. If False, the method will return False instead of raising an error.

Returns:

bool –

True if the cluster complies with the requirements, False otherwise.

TTenonMortiseJoint ¤

TTenonMortiseJoint(
    main_beam=None,
    cross_beam=None,
    start_y=None,
    start_depth=None,
    rotation=None,
    length=None,
    width=None,
    height=None,
    tenon_shape=None,
    shape_radius=None,
    **kwargs,
)

Represents a TenonMortise type joint which joins two beams, one of them at its end (main) and the other one along its centerline (cross) or both of them at their ends. A tenon is added on the main beam, and a corresponding mortise is made on the cross beam to fit the main beam's tenon.

This joint type is compatible with beams in T topology.

Please use TTenonMortiseJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

Second beam to be joined.
start_y (float, default: None ) –

Start position of the tenon along the y-axis of the main beam.
start_depth (float, default: None ) –

Depth of the tenon from the surface of the main beam.
rotation (float, default: None ) –

Rotation of the tenon around the main beam's axis.
length (float, default: None ) –

Length of the tenon along the main beam.
width (float, default: None ) –

Width of the tenon.
height (float, default: None ) –

Height of the tenon.
tenon_shape (str, default: None ) –

Shape of the tenon. One of :class:~compas_timber.fabrication.TenonShapeType: AUTOMATIC, SQUARE, ROUND, ROUNDED, RADIUS. Defaults to TenonShapeType.ROUND.
shape_radius (float, default: None ) –

The radius used to define the shape of the tenon, if applicable.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

First beam to be joined.
cross_beam (:class:`~compas_timber.elements.Beam`) –

Second beam to be joined.
main_beam_guid (str) –

GUID of the main beam.
cross_beam_guid (str) –

GUID of the cross beam.
start_y (float) –

Start position of the tenon along the y-axis of the main beam.
start_depth (float) –

Depth of the tenon from the surface of the main beam.
rotation (float) –

Rotation of the tenon around the main beam's axis.
length (float) –

Length of the tenon along the main beam.
width (float) –

Width of the tenon.
height (float) –

Height of the tenon.
tenon_shape (str) –

Shape of the tenon. One of :class:~compas_timber.fabrication.TenonShapeType: AUTOMATIC, SQUARE, ROUND, ROUNDED, RADIUS.
shape_radius (float) –

The radius used to define the shape of the tenon, if applicable.
features (list) –

List of features or machining processings applied to the elements.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

This method is automatically called when joint is created by the call to Joint.create().

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features()

Adds the required trimming features to both beams.

This method is automatically called when joint is created by the call to Joint.create().

XLapJoint ¤

XLapJoint(beam_a=None, beam_b=None, flip_lap_side=False, cut_plane_bias=0.5, **kwargs)

Represents an X-Lap type joint which joins the two beams somewhere along their length with a lap.

This joint type is compatible with beams in X topology.

Please use XLapJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

beam_a (:class:`~compas_timber.elements.Beam`, default: None ) –

The first beam to be joined.
beam_b (:class:`~compas_timber.elements.Beam`, default: None ) –

The second beam to be joined.
flip_lap_side (bool, default: False ) –

If True, the lap is flipped to the other side of the beams.
cut_plane_bias (float, default: 0.5 ) –

Allows lap to be shifted deeper into one beam or the other. Value should be between 0 and 1.0 without completely cutting through either beam. Default is 0.5.

Attributes:

beam_a (:class:`~compas_timber.elements.Beam`) –

The first beam to be joined.
beam_b (:class:`~compas_timber.elements.Beam`) –

The second beam to be joined.
flip_lap_side (bool) –

If True, the lap is flipped to the other side of the beams.
cut_plane_bias (float) –

Allows lap to be shifted deeper into one beam or the other. Value should be between 0 and 1.0 without completely cutting through either beam. Default is 0.5.

Functions¤

add_features ¤

add_features()

Adds the required extension and trimming features to both beams.

This method is automatically called when joint is created by the call to Joint.create().

XNotchJoint ¤

XNotchJoint(notch_beam=None, solid_beam=None, **kwargs)

Represents an X-Notch type joint which joins the two beams somewhere along their length with a notch applied on the main_beam. This joint type is typically used to connect two beams whose centerlines are offseted from each other, resulting in one resting on top of the other through a notch.

This joint type is compatible with beams in X topology.

Please use XNotchJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

notch_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The first beam to be joined. This beam will have a notch applied to it.
solid_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The second beam to be joined. No features are applied to this beam.

Attributes:

notch_beam (:class:`~compas_timber.elements.Beam`) –

The first beam to be joined. This beam will have a notch applied to it.
solid_beam (:class:`~compas_timber.elements.Beam`) –

The second beam to be joined. No features are applied to this beam.

Attributes¤

main_ref_side_index `property` ¤

main_ref_side_index

The reference side index of the main beam.

Functions¤

add_features ¤

add_features()

Adds the required extension and trimming features to both beams.

This method is automatically called when joint is created by the call to Joint.create().

YButtJoint ¤

YButtJoint(
    main_beam=None, cross_beam_a=None, cross_beam_b=None, mill_depth=None, **kwargs
)

Represents a Y-Butt type joint which joins the ends of three beams, trimming the main beam with a double cut and the cross beams with a miter cut.

Please use YButtJoint.create() to properly create an instance of this class and associate it with a model.

Parameters:

main_beam (:class:`~compas_timber.elements.Beam`, default: None ) –

The main beam to be joined.
cross_beam_a (:class:`~compas_timber.elements.Beam`, default: None ) –

The first cross beam to be joined.
cross_beam_b (:class:`~compas_timber.elements.Beam`, default: None ) –

The second cross beam to be joined.
mill_depth (float, default: None ) –

The depth of the pocket to be milled in the cross beams.

Attributes:

main_beam (:class:`~compas_timber.elements.Beam`) –

The main beam to be joined.
cross_beams (:class:`~compas_timber.elements.Beam`) –

The cross beam to be joined.
mill_depth (float) –

The depth of the pocket to be milled in the cross beams.

Functions¤

add_extensions ¤

add_extensions()

Calculates and adds the necessary extensions to the beams.

This method is automatically called when joint is created by the call to Joint.create().

Raises:

BeamJoiningError –

If the extension could not be calculated.

add_features ¤

add_features()

Adds the required extension and trimming features to both beams.

This method is automatically called when joint is created by the call to Joint.create().

check_elements_compatibility `classmethod` ¤

check_elements_compatibility(elements, raise_error=False)

Checks if the cluster of beams complies with the requirements for the YButtJoint.

Parameters:

elements (list of :class:`~compas_timber.elements.Beam`) –

The beams to check.
raise_error (bool, default: False ) –

If True, raises a BeamJoiningError if the requirements are not met.

Returns:

bool –

True if the cluster complies with the requirements, False otherwise.

Functions¤

beam_ref_side_incidence ¤

beam_ref_side_incidence(beam_a, beam_b, ignore_ends=True)

Returns a map of ref_side indices of beam_b and the angle of their normal with beam_a's centerline.

This is used to find a cutting plane when joining the two beams.

Parameters:

beam_a (:class:`~compas_timber.elements.Beam`) –

The beam that attaches with one of its ends to the side of beam_b.
beam_b (:class:`~compas_timber.elements.Beam`) –

The other beam.
ignore_ends (bool, default: True ) –

If True, only the first four ref_sides of beam_b are considered. Otherwise all ref_sides are considered.

Returns:

dict(int, float) –

A map of ref_side indices of beam_b and their respective angle with beam_a's centerline.

beam_ref_side_incidence_with_vector ¤

beam_ref_side_incidence_with_vector(beam_a, vector, ignore_ends=True)

Returns a map of ref_side indices of beam_b and the angle of their normal with a given vector.

This is used to find a cutting plane when joining two beams where one beam is represented by the normal of one of it's reference sides.

Parameters:

beam_a (:class:`~compas_timber.elements.Beam`) –

The beam for which ref_side angles will be calculated.
vector (:class:`~compas.geometry.Vector`) –

The vector to compare against the ref_sides' normals.
ignore_ends (bool, default: True ) –

If True, only the first four ref_sides of beam_a are considered. Otherwise all ref_sides are considered.

Returns:

dict(int, float) –

A map of ref_side indices of beam_a and their respective angle with the given vector.

find_neighboring_elements ¤

find_neighboring_elements(elements, inflate_by=0.0)

Finds neighboring pairs of beams in the given list of beams, using R-tree search.

The inputs to the R-tree algorithm are the axis-aligned bounding boxes of the beams (beam.aabb), enlarged by the inflate_by amount. The returned elements are sets containing pairs of Beam objects.

Parameters:

elements (list(:class:`~compas_timber.elements.Beam`)) –

The list of beams in which neighboring beams should be identified.
inflate_by ((optional, float), default: 0.0 ) –

A value in design units by which the regarded bounding boxes should be inflated.

Returns:

list(set(:class:`~compas_timber.elements.Beam`, :class:`~compas_timber.elements.Beam`)) –

Notes

This is a pluggable. In order to use this function, a compatible plugin has to be available. For example, in Rhino, the function :func:~compas_timber.rhino.find_neighboring_elements will be used.

get_clusters_from_joint_candidates ¤

get_clusters_from_joint_candidates(candidates, max_distance=None, exclude=None)

Gets a sorted list of Cluster objects from a model's JointCandidates run model.connect_adjacent_beams() first to populate the model's joint_candidates

Parameters:

candiates –

The joint candidates to be grouped into Clusters
max_distance (float, default: None ) –

Maximum distance between joints to be considered co-located.
exclude (set[Joint] | None, default: None ) –

Joints to exclude from clustering.

Returns:

list[:class:`~compas_timber.connections.Cluster`] –

Clusters sorted largest-first.

point_centerline_towards_joint ¤

point_centerline_towards_joint(beam_a, beam_b)

Returns the centerline vector of beam_a pointing towards the joint with beam_b.

Parameters:

beam_a (:class:`~compas_timber.elements.Beam`) –

The beam that attaches with one of its ends to the side of beam_b.
beam_b (:class:`~compas_timber.elements.Beam`) –

The other beam.

Returns:

class:`~compas.geometry.Vector` –

The centerline vector of beam_a pointing towards the joint with beam_b.

compas_timber.connections ¤

Classes¤

BallNodeJoint ¤

Attributes¤

node_point property ¤

Functions¤

add_features ¤

create classmethod ¤

ButtJoint ¤

Functions¤

add_extensions ¤

add_features ¤

Cluster ¤

Attributes¤

topology property ¤

ConnectionSolver ¤

Functions¤

find_intersecting_pairs classmethod ¤

find_topology ¤

Joint ¤

Functions¤

add_extensions ¤

add_features ¤

check_elements_compatibility classmethod ¤

create classmethod ¤

element_count_complies classmethod ¤

promote_cluster classmethod ¤

promote_joint_candidate classmethod ¤

restore_elements_from_keys ¤

JointCandidate ¤

Functions¤

add_features ¤

JointTopology ¤

Functions¤

get_name classmethod ¤

LButtJoint ¤

LFrenchRidgeLapJoint ¤

Functions¤

add_extensions ¤

add_features ¤

check_elements_compatibility classmethod ¤

LLapJoint ¤

Functions¤

add_extensions ¤

add_features ¤

LMiterJoint ¤

Functions¤

add_extensions ¤

add_features ¤

LTenonMortiseJoint ¤

Functions¤

add_extensions ¤

add_features ¤

LapJoint ¤

Attributes¤

cutting_plane_a property ¤

cutting_plane_b property ¤

ref_side_index_a property ¤

ref_side_index_b property ¤

MortiseTenonJoint ¤

Functions¤

get_main_extension ¤

PanelJoint ¤

PanelLButtJoint ¤

Attributes¤

cross_panel property ¤

main_panel property ¤

PanelMiterJoint ¤

PanelTButtJoint ¤

Attributes¤

cross_panel property ¤

main_panel property ¤

PlateButtJoint ¤

Attributes¤

cross_plate property ¤

cross_segment_index property writable ¤

main_plate property ¤

main_segment_index property writable ¤

PlateConnectionSolver ¤

Functions¤

node_point `property` ¤

create `classmethod` ¤

topology `property` ¤

find_intersecting_pairs `classmethod` ¤

check_elements_compatibility `classmethod` ¤

create `classmethod` ¤

element_count_complies `classmethod` ¤

promote_cluster `classmethod` ¤

promote_joint_candidate `classmethod` ¤

get_name `classmethod` ¤

check_elements_compatibility `classmethod` ¤

cutting_plane_a `property` ¤

cutting_plane_b `property` ¤

ref_side_index_a `property` ¤

ref_side_index_b `property` ¤

cross_panel `property` ¤

main_panel `property` ¤

cross_panel `property` ¤

main_panel `property` ¤

cross_plate `property` ¤

cross_segment_index `property` `writable` ¤

main_plate `property` ¤

main_segment_index `property` `writable` ¤

do_segments_overlap `staticmethod` ¤

does_segment_intersect_outline `staticmethod` ¤

promote_joint_candidate `classmethod` ¤

interactions `property` ¤

check_elements_compatibility `classmethod` ¤

main_ref_side_index `property` ¤

check_elements_compatibility `classmethod` ¤