Element Controller

Lifecycle and structural manipulation of model elements.

Domain of element existence: creation of every kind of element from parameters or geometry, duplication and mirroring, deletion, type conversion between element kinds, selection and identification, GUID management, grouping into details/containers, and high-level structural edits (processes, end-profile cuts, joinery operations). This is the entry point for any operation that adds, removes, or fundamentally transforms what exists in the model.

`activate_parts_without_situation() -> list[ElementId]`

Activates the parts situation for elements without a situation.

Returns:

Type	Description
`list[ElementId]`	The list of IDs of the elements for which the parts situation was activated.

`activate_rv_without_situation() -> list[ElementId]`

Activates the rough volume situation for elements without a situation.

Returns:

Type	Description
`list[ElementId]`	The list of IDs of the elements for which the rough volume situation was activated.

`add_created_elements_to_undo(element_id_list: list[ElementId]) -> None`

Adds created elements to the undo stack.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to add.	required

`add_element_to_detail(element_id_list: list[ElementId], detail: int) -> None`

Adds elements to a detail.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be added to the detail.	required
`detail`	`int`	The ID of the detail.	required

`add_elements_to_detail(element_id_list: list[ElementId], detail: int) -> None`

Adds elements to a detail.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be added to the detail.	required
`detail`	`int`	The ID of the detail.	required

`add_elements_to_undo(element_id_list: list[ElementId], cmd: int) -> None`

Add elements to the undo stack.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to add.	required
`cmd`	`int`	The command associated with the undo.	required

`add_modified_elements_to_undo(element_id_list: list[ElementId]) -> None`

Adds modified elements to the undo stack.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to add.	required

`apply_transformation_coordinate(element_id_list: list[ElementId], old_point: point_3d, old_x_local_direction: point_3d, old_y_local_direction: point_3d, new_point: point_3d, new_x_local_direction: point_3d, new_y_local_direction: point_3d) -> None`

Apply transformation coordinate to elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to modify.	required
`old_point`	`point_3d`	The old point.	required
`old_x_local_direction`	`point_3d`	The old X local direction.	required
`old_y_local_direction`	`point_3d`	The old Y local direction.	required
`new_point`	`point_3d`	The new point.	required
`new_x_local_direction`	`point_3d`	The new X local direction.	required
`new_y_local_direction`	`point_3d`	The new Y local direction.	required

`auto_set_parts_situation(element_id_list: list[ElementId]) -> None`

Automatically sets the parts situation for a list of elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to process.	required

`auto_set_rough_volume_situation(element_id_list: list[ElementId]) -> None`

Automatically sets the rough volume situation for a list of elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to process.	required

`cast_ray_and_get_element_intersections(element_id_list: list[ElementId], ray_start_position: point_3d, ray_end_position: point_3d, radius: float) -> hit_result`

Casts a ray through the 3D model and calculates all intersection points between the ray and specified elements. This function performs ray casting against each specified element to find intersection points.For each element hit by the ray, it returns the element ID and all points where the ray intersects with that element. The ray is defined by a start point, end point, and radius.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	List of element IDs to test against the ray.	required
`ray_start_position`	`point_3d`	3D start point of the ray.	required
`ray_end_position`	`point_3d`	3D end point of the ray.	required
`radius`	`float`	Radius of the ray cylinder (allows testing against a volume rather than just a line).	required

Examples:

>>> import element_controller as ec
>>> from cadwork import point_3d
>>> ray_start = point_3d(0, 0, 0)
>>> ray_end = point_3d(1000, 0, 0)
>>> hit_result = ec.cast_ray_and_get_element_intersections(ec.get_active_identifiable_element_ids(), ray_start, ray_end, 40.0)
>>> print(hits.get_hit_element_ids())
>>> for element in hits.get_hit_element_ids():
>>>     print(f"ElementID {element}: {hits.get_hit_vertices_by_element(element)}")
>>>     for pos in hits.get_hit_vertices_by_element(element):
>>>         ec.create_node(pos)

Returns:

Type	Description
`hit_result`	Contains list of elements that were hit by the ray and list of vertices that are queried via ElementID.

`chamfer_edge(element_id: ElementId, edge_start: point_3d, edge_end: point_3d, length: float) -> None`

Chamfers an edge of an element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required
`edge_start`	`point_3d`	The start point of the edge.	required
`edge_end`	`point_3d`	The end point of the edge.	required
`length`	`float`	The length of the chamfer.	required

`check_element_duplicates(element_id_list: list[ElementId]) -> list[ElementId]`

Checks for duplicate elements in the provided list.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of element IDs to check for duplicates.	required

Returns:

Type	Description
`list[ElementId]`	The list of duplicate elements.

`check_element_id(element_id: ElementId) -> bool`

Check if the provided element ID exists.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`bool`	True if the element ID exists, false otherwise.

`check_if_elements_are_in_collision(first_element_id: ElementId, second_element_id: ElementId) -> bool`

Check if two elements are in collision.

Parameters:

Name	Type	Description	Default
`first_element_id`	`ElementId`	The ID of the first element.	required
`second_element_id`	`ElementId`	The ID of the second element.	required

Returns:

Type	Description
`bool`	True if the elements are in collision, false otherwise.

`check_if_elements_are_in_contact(first_element_id: ElementId, second_element_id: ElementId) -> bool`

Check if two elements are in contact.

Parameters:

Name	Type	Description	Default
`first_element_id`	`ElementId`	The ID of the first element.	required
`second_element_id`	`ElementId`	The ID of the second element.	required

Returns:

Type	Description
`bool`	True if the elements are in contact, false otherwise.

`check_if_point_is_in_element(point: point_3d, element_id: ElementId) -> bool`

Check if a point is inside an element.

Parameters:

Name	Type	Description	Default
`point`	`point_3d`	The point to check.	required
`element_id`	`ElementId`	The ID of the element to check against.	required

Returns:

Type	Description
`bool`	True if the point is inside the element, false otherwise.

`check_if_point_is_on_element(point: point_3d, element_id: ElementId) -> bool`

Check if a point is on the surface of an element.

Parameters:

Name	Type	Description	Default
`point`	`point_3d`	The point to check.	required
`element_id`	`ElementId`	The ID of the element to check against.	required

Returns:

Type	Description
`bool`	True if the point is on the surface of the element, false otherwise.

`clear_errors() -> None`

Clears all errors.

`convert_auxiliary_to_beam(element_id_list: list[ElementId]) -> None`

Converts auxiliary elements to beams.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to convert.	required

`convert_auxiliary_to_panel(element_id_list: list[ElementId]) -> None`

Converts auxiliary elements to panel.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to convert.	required

`convert_beam_to_panel(element_id_list: list[ElementId]) -> None`

Converts beams to panels.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required

`convert_bolt_to_standardconnector(element_id_list: list[ElementId], standard_element_name: str) -> None`

Converts bolts to standard connectors.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of bolts to convert.	required
`standard_element_name`	`str`	The name of the standard element.	required

`convert_circular_beam_to_drilling(element_id_list: list[ElementId]) -> None`

Converts circular beams to drillings.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of element IDs to convert.	required

`convert_container_to_container_block(element_id_list: list[ElementId]) -> None`

Converts a container to a container block.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to convert.	required

`convert_drilling_to_circular_beam(element_id_list: list[ElementId]) -> None`

Converts drilling to circular beam.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of element IDs to convert.	required

`convert_elements_to_auxiliary_elements(element_id_list: list[ElementId]) -> None`

Converts elements to auxiliary elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be converted.	required

`convert_lines_to_surfaces(element_id_list: list[ElementId]) -> list[ElementId]`

Converts lines to surfaces.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of element IDs to convert.	required

Returns:

Type	Description
`list[ElementId]`	The list of element IDs that were converted.

`convert_panel_to_beam(element_id_list: list[ElementId]) -> None`

Converts panels to beams.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required

`convert_surfaces_to_roof_surfaces(element_id_list: list[ElementId], roof_name: str) -> None`

Converts surfaces to roof surfaces.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to convert.	required
`roof_name`	`str`	The name of the roof surface.	required

`convert_surfaces_to_volume(element_id_list: list[ElementId]) -> ElementId`

Converts surfaces to volume.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of element IDs to convert.	required

Returns:

Type	Description
`ElementId`	The ID of the created volume element.

`copy_elements(element_id_list: list[ElementId], copy_vector: point_3d) -> list[int]`

Copy a list of elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`copy_vector`	`point_3d`	The vector by which to copy the elements.	required

Returns:

Type	Description
`list[int]`	The IDs of the copied elements.

`create_auto_container_from_standard(element_id_list: list[ElementId], output_name: str, standard_element_name: str) -> ElementId`

Create an auto container from a standard element.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be used in the auto container.	required
`output_name`	`str`	The name of the output.	required
`standard_element_name`	`str`	The name of the standard element.	required

Returns:

Type	Description
`ElementId`	The id of the created auto container element.

`create_auto_container_from_standard_with_reference(element_id_list: list[ElementId], output_name: str, standard_element_name: str, reference_id: ElementId) -> ElementId`

Creates an auto container from a standard element with a reference.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be used in the auto container.	required
`output_name`	`str`	The name of the output.	required
`standard_element_name`	`str`	The name of the standard element.	required
`reference_id`	`ElementId`	The ID of the reference element.	required

Returns:

Type	Description
`ElementId`	The ID of the created auto container element.

`create_auto_export_solid_from_standard(element_id_list: list[ElementId], output_name: str, standard_element_name: str) -> ElementId`

Creates an auto export solid from a standard element.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to use.	required
`output_name`	`str`	The output name.	required
`standard_element_name`	`str`	The standard element name.	required

Returns:

Type	Description
`ElementId`	The element ID of the created solid.

`create_auto_export_solid_from_standard_with_reference(element_id_list: list[ElementId], output_name: str, standard_element_name: str, reference_id: ElementId) -> ElementId`

Creates an auto export solid from a standard element with a reference.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be used in the export solid.	required
`output_name`	`str`	The name of the output.	required
`standard_element_name`	`str`	The name of the standard element.	required
`reference_id`	`ElementId`	The ID of the reference element.	required

Returns:

Type	Description
`ElementId`	The id of the created auto export solid element.

`create_bounding_box_global(element_id_list: list[ElementId]) -> ElementId`

Creates a global bounding box for a list of elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements for which to create the bounding box.	required

Returns:

Type	Description
`ElementId`	The ID of the created bounding box element.

`create_bounding_box_local(reference_element: ElementId, element_id_list: list[ElementId]) -> ElementId`

Creates a local bounding box for a list of elements relative to a reference element.

Parameters:

Name	Type	Description	Default
`reference_element`	`ElementId`	The ID of the reference element.	required
`element_id_list`	`list[ElementId]`	The list of elements for which to create the bounding box.	required

Returns:

Type	Description
`ElementId`	The ID of the created bounding box element.

`create_circular_axis_points(diameter: float, first_point: point_3d, second_point: point_3d) -> ElementId`

Creates a circular axis using points.

Parameters:

Name	Type	Description	Default
`diameter`	`float`	The diameter of the circular axis.	required
`first_point`	`point_3d`	The first point defining the axis.	required
`second_point`	`point_3d`	The second point defining the axis.	required

Examples:

>>> axis_diameter = 50.
>>> axis_start_pt = cadwork.point_3d(100., 100., 0.)
>>> axis_end_pt = cadwork.point_3d(100., 100., 300.)
>>> circular_axis_id = ec.create_circular_axis_points(axis_diameter, axis_start_pt, axis_end_pt)

Returns:

Type	Description
`ElementId`	The ID of the created circular axis element.

`create_circular_axis_vector(diameter: float, length: float, starting_point: point_3d, axis_direction: point_3d) -> ElementId`

Creates a circular axis using a vector.

Parameters:

Name	Type	Description	Default
`diameter`	`float`	The diameter of the circular axis.	required
`length`	`float`	The length of the circular axis.	required
`starting_point`	`point_3d`	The starting point.	required
`axis_direction`	`point_3d`	The direction of the X-axis.	required

Examples:

>>> axis_diameter = 60.
>>> axis_length = 400.
>>> axis_start_pt = cadwork.point_3d(200., 200., 200.)
>>> axis_direction = cadwork.point_3d(0., 1., 0.)  # Direction along Y axis
>>> circular_axis_id = ec.create_circular_axis_vector(axis_diameter, axis_length, axis_start_pt, axis_direction)

Returns:

Type	Description
`ElementId`	The ID of the created circular axis element.

`create_circular_beam_points(diameter: float, first_point: point_3d, second_point: point_3d, third_point: point_3d) -> ElementId`

Creates a circular beam using points.

Parameters:

Name	Type	Description	Default
`diameter`	`float`	The diameter of the beam.	required
`first_point`	`point_3d`	The first point.	required
`second_point`	`point_3d`	The second point.	required
`third_point`	`point_3d`	The third point.	required

Examples:

>>> beam_diameter = 120.
>>> beam_axis_start_pt = cadwork.point_3d(0., 0., 0.)
>>> beam_axis_end_pt = cadwork.point_3d(0., 0., 3000.)
>>> length_vector = (beam_axis_end_pt - beam_axis_start_pt).normalized()
>>> beam_axis_y = cadwork.point_3d(1., 0., 0.)
>>> beam_axis_z = length_vector.cross(beam_axis_y).normalized()
>>> beam_orientation_pt = beam_axis_start_pt + beam_axis_z
>>> beam_id = ec.create_circular_beam_points(beam_diameter, beam_axis_start_pt, beam_axis_end_pt, beam_orientation_pt)

Returns:

Type	Description
`ElementId`	The ID of the created circular beam.

`create_circular_beam_vectors(diameter: float, length: float, starting_point: point_3d, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Creates a circular beam using vectors.

Parameters:

Name	Type	Description	Default
`diameter`	`float`	The diameter of the beam.	required
`length`	`float`	The length of the beam.	required
`starting_point`	`point_3d`	The starting point of the beam.	required
`x_local_direction`	`point_3d`	The local X direction vector.	required
`z_local_direction`	`point_3d`	The local Z direction vector.	required

Examples:

>>> beam_diameter = 100.
>>> beam_length = 3500.
>>> origin_point = cadwork.point_3d(200., 200., 200.)
>>> x_direction = cadwork.point_3d(0., 1., 0.)  # Beam aligned with Y axis
>>> z_direction = cadwork.point_3d(0., 0., 1.)  # Z orientation (arbitrary for circular beam)
>>> beam_id = ec.create_circular_beam_vectors(beam_diameter, beam_length, origin_point, x_direction, z_direction)

Returns:

Type	Description
`ElementId`	The ID of the created circular beam.

`create_circular_mep(diameter: float, points: list[point_3d]) -> ElementId`

Create a circular MEP (Mechanical, Electrical, and Plumbing) element.

Parameters:

Name	Type	Description	Default
`diameter`	`float`	The diameter of the circular MEP.	required
`points`	`list[point_3d]`	The points defining the circular MEP.	required

Returns:

Type	Description
`ElementId`	The ID of the created circular MEP element.

`create_drilling_points(diameter: float, first_point: point_3d, second_point: point_3d) -> ElementId`

Creates drilling using points.

Parameters:

Name	Type	Description	Default
`diameter`	`float`	The diameter of the drilling.	required
`first_point`	`point_3d`	The starting point of the drilling.	required
`second_point`	`point_3d`	The ending point of the drilling.	required

Examples:

>>> drill_diameter = 30.
>>> drill_start_pt = cadwork.point_3d(100., 100., 0.)
>>> drill_end_pt = cadwork.point_3d(100., 100., 200.)
>>> drilling_id = ec.create_drilling_points(drill_diameter, drill_start_pt, drill_end_pt)

Returns:

Type	Description
`ElementId`	The ID of the created drilling.

`create_drilling_vectors(diameter: float, length: float, starting_point: point_3d, drilling_direction: point_3d) -> ElementId`

Creates drilling using vectors.

Parameters:

Name	Type	Description	Default
`diameter`	`float`	The diameter of the drilling.	required
`length`	`float`	The length of the drilling.	required
`starting_point`	`point_3d`	The starting point of the drilling.	required
`drilling_direction`	`point_3d`	The direction of the drilling.	required

Examples:

>>> drill_diameter = 12.
>>> drill_length = 180.
>>> drill_start_pt = cadwork.point_3d(200., 200., 50.)
>>> drill_direction = cadwork.point_3d(0., 0., 1.)  # Drilling in Z direction
>>> drilling_id = ec.create_drilling_vectors(drill_diameter, drill_length, drill_start_pt, drill_direction)

Returns:

Type	Description
`ElementId`	The ID of the created drilling.

`create_line_points(first_point: point_3d, second_point: point_3d) -> ElementId`

Creates a line using points.

Parameters:

Name	Type	Description	Default
`first_point`	`point_3d`	The first point of the line.	required
`second_point`	`point_3d`	The second point of the line.	required

Examples:

>>> line_start_pt = cadwork.point_3d(0., 0., 0.)
>>> line_end_pt = cadwork.point_3d(500., 500., 0.)
>>> line_id = ec.create_line_points(line_start_pt, line_end_pt)

Returns:

Type	Description
`ElementId`	The ID of the created line.

`create_line_vectors(length: float, starting_point: point_3d, line_direction: point_3d) -> ElementId`

Creates a line using vectors.

Parameters:

Name	Type	Description	Default
`length`	`float`	The length of the line.	required
`starting_point`	`point_3d`	The starting point of the line.	required
`line_direction`	`point_3d`	The direction of the line.	required

Examples:

>>> line_length = 1000.
>>> line_start_pt = cadwork.point_3d(200., 0., 200.)
>>> line_direction = cadwork.point_3d(1., 1., 0.).normalized()  # 45 degree line in XY plane
>>> line_id = ec.create_line_vectors(line_length, line_start_pt, line_direction)

Returns:

Type	Description
`ElementId`	The ID of the created line.

`create_linear_optimization(element_id_list: list[ElementId], optimization_number: int, total_length: float, start_cut: float, end_cut: float, saw_kerf: float, is_production_list: bool) -> ElementId`

create linear optimization

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be optimized.	required
`optimization_number`	`int`	The optimization number, nested parent element id.	required
`total_length`	`float`	The total length for the optimization.	required
`start_cut`	`float`	The start cut for the optimization.	required
`end_cut`	`float`	The end cut for the optimization.	required
`saw_kerf`	`float`	The saw kerf for the optimization.	required
`is_production_list`	`bool`	A flag indicating if this is a production list.	required

Returns:

Type	Description
`ElementId`	The ID of the created linear optimization element.

`create_multi_wall(element_id_list: list[ElementId]) -> None`

Creates a multi-wall structure.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to use in the multi-wall structure.	required

`create_node(node_position: point_3d) -> ElementId`

Creates a node.

Parameters:

Name	Type	Description	Default
`node_position`	`point_3d`	The position of the node.	required

Examples:

>>> node_position = cadwork.point_3d(250., 250., 100.)
>>> node_id = ec.create_node(node_position)

Returns:

Type	Description
`ElementId`	The ID of the created node.

`create_normal_axis_points(first_point: point_3d, second_point: point_3d) -> ElementId`

Creates a normal axis using points.

Parameters:

Name	Type	Description	Default
`first_point`	`point_3d`	The first point of the axis.	required
`second_point`	`point_3d`	The second point of the axis.	required

Examples:

>>> axis_start_pt = cadwork.point_3d(0., 0., 0.)
>>> axis_end_pt = cadwork.point_3d(0., 0., 2000.)
>>> axis_id = ec.create_normal_axis_points(axis_start_pt, axis_end_pt)

Returns:

Type	Description
`ElementId`	The id of the created normal axis.

`create_normal_axis_vectors(length: float, starting_point: point_3d, axis_direction: point_3d) -> ElementId`

Creates a normal axis using vectors.

Parameters:

Name	Type	Description	Default
`length`	`float`	The length of the axis.	required
`starting_point`	`point_3d`	The starting point of the axis.	required
`axis_direction`	`point_3d`	The direction vector of the axis.	required

Examples:

>>> axis_length = 1500.
>>> axis_start_pt = cadwork.point_3d(200., 200., 0.)
>>> axis_direction = cadwork.point_3d(1., 0., 0.)  # Direction along X axis
>>> axis_id = ec.create_normal_axis_vectors(axis_length, axis_start_pt, axis_direction)

Returns:

Type	Description
`ElementId`	The id of the created normal axis.

`create_polygon_beam(polygon_vertices: vertex_list, thickness: float, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Creates a polygon beam.

Parameters:

Name	Type	Description	Default
`polygon_vertices`	`vertex_list`	The vertices of the polygon.	required
`thickness`	`float`	The thickness of the beam.	required
`x_local_direction`	`point_3d`	The x local direction of the beam.	required
`z_local_direction`	`point_3d`	The z local direction of the beam.	required

Examples:

>>> # Create a triangular beam
>>> vertices = cadwork.vertex_list()
>>> vertices.append(cadwork.point_3d(0., 0., 0.))
>>> vertices.append(cadwork.point_3d(200., 0., 0.))
>>> vertices.append(cadwork.point_3d(100., 173.2, 0.))  # Equilateral triangle
>>> beam_thickness = 1000.  # Length of the beam
>>> extrusion_vector = cadwork.point_3d(0., 0., 1.)  # Direction of extrusion
>>> z_vector = cadwork.point_3d(1., 0., 0.)  # Orientation vector
>>> polygon_beam_id = ec.create_polygon_beam(vertices, beam_thickness, extrusion_vector, z_vector)

Returns:

Type	Description
`ElementId`	The ID of the created polygon beam.

`create_polygon_panel(polygon_vertices: vertex_list, thickness: float, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Creates a polygon panel.

Parameters:

Name	Type	Description	Default
`polygon_vertices`	`vertex_list`	The vertices of the polygon.	required
`thickness`	`float`	The thickness of the panel.	required
`x_local_direction`	`point_3d`	The X-axis direction of the panel.	required
`z_local_direction`	`point_3d`	The Z-axis direction of the panel.	required

Examples:

>>> # Create a hexagonal panel
>>> vertices = cadwork.vertex_list()
>>> import math
>>> radius = 500.
>>> sides = 6
>>> for i in range(sides):
...     angle = 2 * math.pi * i / sides
...     vertices.append(cadwork.point_3d(radius * math.cos(angle), radius * math.sin(angle), 0.))
>>> vertices.append(vertices[0]) # Close the polygon
>>> panel_thickness = 20.
>>> extrusion_vector = cadwork.point_3d(0., 0., 1.)  # Normal direction
>>> z_vector = cadwork.point_3d(1., 0., 0.)  # Orientation vector
>>> polygon_panel_id = ec.create_polygon_panel(vertices, panel_thickness, extrusion_vector, z_vector)

Returns:

Type	Description
`ElementId`	The ID of the created polygon panel element.

`create_rectangular_beam_points(width: float, height: float, first_point: point_3d, second_point: point_3d, third_point: point_3d) -> ElementId`

Creates a rectangular beam using points.

Parameters:

Name	Type	Description	Default
`width`	`float`	The width of the beam.	required
`height`	`float`	The height of the beam.	required
`first_point`	`point_3d`	The first point.	required
`second_point`	`point_3d`	The second point.	required
`third_point`	`point_3d`	The third point.	required

Examples:

>>> beam_width = 200.
>>> beam_height = 400.
>>> beam_axis_start_pt =  cadwork.point_3d(300., 0., 0.)
>>> beam_axis_end_pt = cadwork.point_3d(300., 0., 4000.)
>>> length_vector = (beam_axis_end_pt - beam_axis_start_pt).normalized()
>>> beam_axis_y = cadwork.point_3d(1., 0., 0.)
>>> beam_axis_z = length_vector.cross(beam_axis_y).normalized()
>>> beam_height_axis_pt = beam_axis_start_pt + beam_axis_z
>>> beam_id = ec.create_rectangular_beam_points(beam_width, beam_height, beam_axis_start_pt,  beam_axis_end_pt,  beam_height_axis_pt )

Returns:

Type	Description
`ElementId`	The ID of the created rectangular beam.

`create_rectangular_beam_vectors(width: float, height: float, length: float, starting_point: point_3d, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Creates a rectangular beam using vectors.

Parameters:

Name	Type	Description	Default
`width`	`float`	The width of the beam.	required
`height`	`float`	The height of the beam.	required
`length`	`float`	The length of the beam.	required
`starting_point`	`point_3d`	The starting point.	required
`x_local_direction`	`point_3d`	The direction of the X-axis.	required
`z_local_direction`	`point_3d`	The direction of the Z-axis.	required

Examples:

>>> beam_width = 150.
>>> beam_height = 300.
>>> beam_length = 4000.
>>> origin_point = cadwork.point_3d(0., 0., 0.)
>>> x_direction = cadwork.point_3d(1., 0., 0.)  # Direction along length
>>> z_direction = cadwork.point_3d(0., 0., 1.)  # Direction along height
>>> beam_id = ec.create_rectangular_beam_vectors(beam_width, beam_height, beam_length, origin_point, x_direction, z_direction)

Returns:

Type	Description
`ElementId`	The ID of the created rectangular beam.

`create_rectangular_mep(width: float, depth: float, points: list[point_3d]) -> ElementId`

Create a rectangular MEP (Mechanical, Electrical, and Plumbing) element.

Parameters:

Name	Type	Description	Default
`width`	`float`	The width of the rectangular MEP.	required
`depth`	`float`	The depth of the rectangular MEP.	required
`points`	`list[point_3d]`	The points defining the rectangular MEP.	required

Returns:

Type	Description
`ElementId`	The ID of the created rectangular MEP element.

`create_rectangular_panel_points(width: float, thickness: float, first_point: point_3d, second_point: point_3d, third_point: point_3d) -> ElementId`

Create a rectangular panel using points.

Parameters:

Name	Type	Description	Default
`width`	`float`	The width of the panel.	required
`thickness`	`float`	The thickness of the panel.	required
`first_point`	`point_3d`	The first corner point of the panel.	required
`second_point`	`point_3d`	The second corner point of the panel.	required
`third_point`	`point_3d`	The third corner point of the panel.	required

Examples:

>>> panel_width = 1200.
>>> panel_thickness = 27.
>>> panel_corner_pt = cadwork.point_3d(0., 0., 0.)
>>> panel_length_pt = cadwork.point_3d(0., 2400., 0.)
>>> # Calculate a point to define panel orientation
>>> normal_vector = cadwork.point_3d(0., 0., 1.)  # Panel normal in Z direction
>>> orientation_pt = panel_corner_pt + normal_vector
>>> panel_id = ec.create_rectangular_panel_points(panel_width, panel_thickness, panel_corner_pt, panel_length_pt, orientation_pt)

Returns:

Type	Description
`ElementId`	The ID of the created rectangular panel.

`create_rectangular_panel_vectors(width: float, thickness: float, length: float, starting_point: point_3d, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Create a rectangular panel using vectors.

Parameters:

Name	Type	Description	Default
`width`	`float`	The width of the panel.	required
`thickness`	`float`	The thickness of the panel.	required
`length`	`float`	The length of the panel.	required
`starting_point`	`point_3d`	The starting point of the panel.	required
`x_local_direction`	`point_3d`	The local X direction vector.	required
`z_local_direction`	`point_3d`	The local Z direction vector.	required

Examples:

>>> panel_width = 1000.
>>> panel_thickness = 20.
>>> panel_length = 2000.
>>> origin_point = cadwork.point_3d(0., 0., 100.)
>>> x_direction = cadwork.point_3d(1., 0., 0.)  # Direction along length
>>> z_direction = cadwork.point_3d(0., 0., 1.)  # Panel normal direction
>>> panel_id = ec.create_rectangular_panel_vectors(panel_width, panel_thickness, panel_length, origin_point, x_direction, z_direction)

Returns:

Type	Description
`ElementId`	The ID of the created rectangular panel.

`create_spline_line(spline_points: vertex_list) -> ElementId`

Creates a spline line.

Parameters:

Name	Type	Description	Default
`spline_points`	`vertex_list`	The points defining the spline.	required

Examples:

>>> # Create a spline through multiple points
>>> points = cadwork.vertex_list()
>>> points.append(cadwork.point_3d(0., 0., 0.))
>>> points.append(cadwork.point_3d(500., 200., 0.))
>>> points.append(cadwork.point_3d(1000., 0., 200.))
>>> points.append(cadwork.point_3d(1500., -100., 100.))
>>> spline_id = ec.create_spline_line(points)

Returns:

Type	Description
`ElementId`	The ID of the created spline.

`create_square_beam_points(width: float, first_point: point_3d, second_point: point_3d, third_point: point_3d) -> ElementId`

Creates a square beam using points.

Parameters:

Name	Type	Description	Default
`width`	`float`	The width of the beam.	required
`first_point`	`point_3d`	The first point.	required
`second_point`	`point_3d`	The second point.	required
`third_point`	`point_3d`	The third point.	required

Examples:

>>> beam_width = 100.
>>> beam_axis_start_pt = cadwork.point_3d(500., 500., 0.)
>>> beam_axis_end_pt = cadwork.point_3d(500., 500., 2500.)
>>> length_vector = (beam_axis_end_pt - beam_axis_start_pt).normalized()
>>> reference_vector = cadwork.point_3d(0., 1., 0.)
>>> beam_axis_z = length_vector.cross(reference_vector).normalized()
>>> orientation_pt = beam_axis_start_pt + beam_axis_z
>>> beam_id = ec.create_square_beam_points(beam_width, beam_axis_start_pt, beam_axis_end_pt, orientation_pt)

Returns:

Type	Description
`ElementId`	The ID of the created square beam.

`create_square_beam_vectors(width: float, length: float, starting_point: point_3d, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Creates a square beam using vectors.

Parameters:

Name	Type	Description	Default
`width`	`float`	The width of the beam.	required
`length`	`float`	The length of the beam.	required
`starting_point`	`point_3d`	The starting point of the beam.	required
`x_local_direction`	`point_3d`	The local X direction vector.	required
`z_local_direction`	`point_3d`	The local Z direction vector.	required

Examples:

>>> beam_width = 120.
>>> beam_length = 2800.
>>> origin_point = cadwork.point_3d(0., 0., 500.)
>>> x_direction = cadwork.point_3d(1., 0., 0.)  # Direction along length
>>> z_direction = cadwork.point_3d(0., 0., 1.)  # Direction for orientation
>>> beam_id = ec.create_square_beam_vectors(beam_width, beam_length, origin_point, x_direction, z_direction)

Returns:

Type	Description
`ElementId`	The ID of the created square beam.

`create_standard_beam_points(standard_element_name: str, first_point: point_3d, second_point: point_3d, third_point: point_3d) -> ElementId`

Creates a standard beam using points.

Parameters:

Name	Type	Description	Default
`standard_element_name`	`str`	The name of the standard element.	required
`first_point`	`point_3d`	The first point.	required
`second_point`	`point_3d`	The second point.	required
`third_point`	`point_3d`	The third point.	required

Examples:

>>> std_beam_name = "Standard-Timber-120x240"  # Name as found in standard elements library
>>> beam_start_pt = cadwork.point_3d(0., 0., 0.)
>>> beam_end_pt = cadwork.point_3d(0., 0., 3000.)
>>> # Calculate orientation point
>>> length_vector = (beam_end_pt - beam_start_pt).normalized()
>>> ref_vector = cadwork.point_3d(1., 0., 0.)
>>> orientation_vector = length_vector.cross(ref_vector).normalized()
>>> orientation_pt = beam_start_pt + orientation_vector
>>> std_beam_id = ec.create_standard_beam_points(std_beam_name, beam_start_pt, beam_end_pt, orientation_pt)

Returns:

Type	Description
`ElementId`	The ID of the created standard beam.

`create_standard_beam_vectors(standard_element_name: str, length: float, starting_point: point_3d, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Creates a standard beam using vectors.

Parameters:

Name	Type	Description	Default
`standard_element_name`	`str`	The name of the standard element.	required
`length`	`float`	The length of the beam.	required
`starting_point`	`point_3d`	The starting point of the beam.	required
`x_local_direction`	`point_3d`	The local X direction vector.	required
`z_local_direction`	`point_3d`	The local Z direction vector.	required

Examples:

>>> std_beam_name = "Standard-Timber-100x100"  # Name as found in standard elements library
>>> beam_length = 2500.
>>> origin_point = cadwork.point_3d(100., 100., 100.)
>>> x_direction = cadwork.point_3d(1., 0., 0.)  # Direction along length
>>> z_direction = cadwork.point_3d(0., 0., 1.)  # Orientation vector
>>> std_beam_id = ec.create_standard_beam_vectors(std_beam_name, beam_length, origin_point, x_direction, z_direction)

Returns:

Type	Description
`ElementId`	The ID of the created standard beam.

`create_standard_element_from_guid_points(guid: str, first_point: point_3d, second_point: point_3d, third_point: point_3d) -> ElementId`

Creates a standard element from GUID points.

Parameters:

Name	Type	Description	Default
`guid`	`str`	The GUID of the standard element.	required
`first_point`	`point_3d`	The first point.	required
`second_point`	`point_3d`	The second point.	required
`third_point`	`point_3d`	The third point.	required

Returns:

Type	Description
`ElementId`	The id of the created standard element.

`create_standard_element_from_guid_vectors(guid: str, length: float, starting_point: point_3d, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Creates a standard element from GUID vectors.

Parameters:

Name	Type	Description	Default
`guid`	`str`	The GUID of the standard element.	required
`length`	`float`	The length of the element.	required
`starting_point`	`point_3d`	The starting point of the element.	required
`x_local_direction`	`point_3d`	The X-axis direction vector.	required
`z_local_direction`	`point_3d`	The Z-axis direction vector.	required

Returns:

Type	Description
`ElementId`	The ID of the created standard element.

`create_standard_panel_points(standard_element_name: str, first_point: point_3d, second_point: point_3d, third_point: point_3d) -> ElementId`

Creates a standard panel using points.

Parameters:

Name	Type	Description	Default
`standard_element_name`	`str`	The name of the standard element.	required
`first_point`	`point_3d`	The first point.	required
`second_point`	`point_3d`	The second point.	required
`third_point`	`point_3d`	The third point.	required

Examples:

>>> std_panel_name = "Standard-Panel-27mm"  # Name as found in standard elements library
>>> panel_corner_pt = cadwork.point_3d(0., 0., 0.)
>>> panel_width_pt = cadwork.point_3d(1200., 0., 0.)
>>> # Calculate normal point for panel orientation (assuming Z is up)
>>> panel_normal = cadwork.point_3d(0., 0., 1.)
>>> orientation_pt = panel_corner_pt + panel_normal
>>> std_panel_id = ec.create_standard_panel_points(std_panel_name, panel_corner_pt, panel_width_pt, orientation_pt)

Returns:

Type	Description
`ElementId`	The id of the created standard panel.

`create_standard_panel_vectors(standard_element_name: str, length: float, starting_point: point_3d, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Creates a standard panel using vectors.

Parameters:

Name	Type	Description	Default
`standard_element_name`	`str`	The name of the standard element.	required
`length`	`float`	The length of the panel.	required
`starting_point`	`point_3d`	The starting point of the panel.	required
`x_local_direction`	`point_3d`	The local X direction vector.	required
`z_local_direction`	`point_3d`	The local Z direction vector.	required

Examples:

>>> std_panel_name = "Standard-Panel-20mm"  # Name as found in standard elements library
>>> panel_length = 2400.
>>> origin_point = cadwork.point_3d(0., 0., 0.)
>>> x_direction = cadwork.point_3d(1., 0., 0.)  # Direction along length
>>> z_direction = cadwork.point_3d(0., 0., 1.)  # Panel normal direction
>>> std_panel_id = ec.create_standard_panel_vectors(std_panel_name, panel_length, origin_point, x_direction, z_direction)

Returns:

Type	Description
`ElementId`	The id of the created standard panel.

`create_standard_steel_points(standard_element_name: str, first_point: point_3d, second_point: point_3d, third_point: point_3d) -> ElementId`

Creates a standard steel element using points.

Parameters:

Name	Type	Description	Default
`standard_element_name`	`str`	The name of the standard element.	required
`first_point`	`point_3d`	The first point.	required
`second_point`	`point_3d`	The second point.	required
`third_point`	`point_3d`	The third point.	required

Examples:

>>> std_steel_name = "IPE 200"  # Name of standard steel profile from library
>>> steel_start_pt = cadwork.point_3d(0., 0., 500.)
>>> steel_end_pt = cadwork.point_3d(3000., 0., 500.)
>>> # Calculate orientation point
>>> length_vector = (steel_end_pt - steel_start_pt).normalized()
>>> up_vector = cadwork.point_3d(0., 0., 1.)
>>> side_vector = length_vector.cross(up_vector).normalized()
>>> orientation_pt = steel_start_pt + up_vector
>>> steel_id = ec.create_standard_steel_points(std_steel_name, steel_start_pt, steel_end_pt, orientation_pt)

Returns:

Type	Description
`ElementId`	The id of the created standard steel element.

`create_standard_steel_vectors(standard_element_name: str, length: float, starting_point: point_3d, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Creates a standard steel element using vectors.

Parameters:

Name	Type	Description	Default
`standard_element_name`	`str`	The name of the standard element.	required
`length`	`float`	The length of the element.	required
`starting_point`	`point_3d`	The starting point of the element.	required
`x_local_direction`	`point_3d`	The local X direction vector.	required
`z_local_direction`	`point_3d`	The local Z direction vector.	required

Examples:

>>> std_steel_name = "HEA 220"  # Name of standard steel profile from library
>>> steel_length = 4500.
>>> origin_point = cadwork.point_3d(200., 0., 200.)
>>> x_direction = cadwork.point_3d(0., 1., 0.)  # Direction along Y axis
>>> z_direction = cadwork.point_3d(0., 0., 1.)  # Up direction
>>> steel_id = ec.create_standard_steel_vectors(std_steel_name, steel_length, origin_point, x_direction, z_direction)

Returns:

Type	Description
`ElementId`	The id of the created standard steel element.

`create_surface(surface_vertices: vertex_list) -> ElementId`

Creates a surface from a list of vertices.

Parameters:

Name	Type	Description	Default
`surface_vertices`	`vertex_list`	The list of vertices defining the surface.	required

Examples:

>>> # Create a rectangular surface
>>> vertices = cadwork.vertex_list()
>>> vertices.append(cadwork.point_3d(0., 0., 0.))
>>> vertices.append(cadwork.point_3d(1000., 0., 0.))
>>> vertices.append(cadwork.point_3d(1000., 800., 0.))
>>> vertices.append(cadwork.point_3d(0., 800., 0.))
>>> surface_id = ec.create_surface(vertices)

Returns:

Type	Description
`ElementId`	The ID of the created surface element.

`create_text_object(text: str, position: point_3d, x_local_direction: point_3d, z_local_direction: point_3d, size: float) -> ElementId`

Creates a text object.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text content.	required
`position`	`point_3d`	The position of the text.	required
`x_local_direction`	`point_3d`	The x local direction of the text.	required
`z_local_direction`	`point_3d`	The z local direction of the text.	required
`size`	`float`	The size of the text.	required

Examples:

>>> text_content = "Cadwork API"
>>> text_position = cadwork.point_3d(0., 0., 0.)
>>> x_direction = cadwork.point_3d(1., 0., 0.)  # Text direction
>>> z_direction = cadwork.point_3d(0., 0., 1.)  # Text orientation
>>> text_height = 200.
>>> text_id = ec.create_text_object(text_content, text_position, x_direction, z_direction, text_height)

Returns:

Type	Description
`ElementId`	The ID of the created text object.

`create_text_object_with_font(text: str, position: point_3d, x_local_direction: point_3d, z_local_direction: point_3d, size: float, font_name: str) -> ElementId`

Creates a text object with a specific font.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to be displayed in the text object.	required
`position`	`point_3d`	The position of the text object.	required
`x_local_direction`	`point_3d`	The X-axis direction of the text object.	required
`z_local_direction`	`point_3d`	The Z-axis direction of the text object.	required
`size`	`float`	The size of the text object.	required
`font_name`	`str`	The font name.	required

Examples:

>>> text_content = "Custom Text"
>>> text_position = cadwork.point_3d(0., 0., 0.)
>>> x_direction = cadwork.point_3d(1., 0., 0.)  # Text direction
>>> z_direction = cadwork.point_3d(0., 0., 1.)  # Text orientation
>>> text_height = 150.
>>> font = "Arial"
>>> text_id = ec.create_text_object_with_font(text_content, text_position, x_direction, z_direction, text_height, font)

Returns:

Type	Description
`ElementId`	The element ID of the created text object.

`create_text_object_with_options(position: point_3d, x_local_direction: point_3d, z_local_direction: point_3d, text_options: text_object_options) -> ElementId`

Creates a text object with the specified options.

Parameters:

Name	Type	Description	Default
`position`	`point_3d`	The position of the text object.	required
`x_local_direction`	`point_3d`	The X-axis direction of the text object.	required
`z_local_direction`	`point_3d`	The Z-axis direction of the text object.	required
`text_options`	`text_object_options`	The options for the text object.	required

Examples:

>>> text_position = cadwork.point_3d(0., 0., 0.)
>>> x_direction = cadwork.point_3d(1., 0., 0.)  # Text direction
>>> z_direction = cadwork.point_3d(0., 0., 1.)  # Text orientation
>>> options = cadwork.text_object_options()
>>> options.set_text("Advanced Text")
>>> options.set_height(200.)
>>> options.set_font_name("Verdana")
>>> options.set_bold(True)
>>> text_id = ec.create_text_object_with_options(text_position, x_direction, z_direction, options)

Returns:

Type	Description
`ElementId`	The ID of the created text object.

`create_truncated_cone_beam_points(start_diameter: float, end_diameter: float, first_point: point_3d, second_point: point_3d, third_point: point_3d) -> ElementId`

Creates a truncated cone beam using points.

Parameters:

Name	Type	Description	Default
`start_diameter`	`float`	The starting diameter of the beam.	required
`end_diameter`	`float`	The ending diameter of the beam.	required
`first_point`	`point_3d`	The first point.	required
`second_point`	`point_3d`	The second point.	required
`third_point`	`point_3d`	The third point.	required

Examples:

>>> start_dia = 200.
>>> end_dia = 150.
>>> cone_start_pt = cadwork.point_3d(0., 0., 0.)
>>> cone_end_pt = cadwork.point_3d(0., 0., 3000.)
>>> # Calculate orientation point
>>> length_vector = (cone_end_pt - cone_start_pt).normalized()
>>> ref_vector = cadwork.point_3d(1., 0., 0.)
>>> orientation_vector = length_vector.cross(ref_vector).normalized()
>>> orientation_pt = cone_start_pt + orientation_vector
>>> cone_id = ec.create_truncated_cone_beam_points(start_dia, end_dia, cone_start_pt, cone_end_pt, orientation_pt)

Returns:

Type	Description
`ElementId`	The ID of the created beam.

`create_truncated_cone_beam_vectors(start_diameter: float, end_diameter: float, length: float, starting_point: point_3d, x_local_direction: point_3d, z_local_direction: point_3d) -> ElementId`

Creates a truncated cone beam using vectors.

Parameters:

Name	Type	Description	Default
`start_diameter`	`float`	The starting diameter of the beam.	required
`end_diameter`	`float`	The ending diameter of the beam.	required
`length`	`float`	The length of the beam.	required
`starting_point`	`point_3d`	The starting point.	required
`x_local_direction`	`point_3d`	The direction of the X-axis.	required
`z_local_direction`	`point_3d`	The direction of the Z-axis.	required

Examples:

>>> start_dia = 120.
>>> end_dia = 80.
>>> cone_length = 2500.
>>> origin_point = cadwork.point_3d(0., 0., 0.)
>>> x_direction = cadwork.point_3d(0., 0., 1.)  # Direction along Z axis
>>> z_direction = cadwork.point_3d(1., 0., 0.)  # Orientation vector
>>> cone_id = ec.create_truncated_cone_beam_vectors(start_dia, end_dia, cone_length, origin_point, x_direction, z_direction)

Returns:

Type	Description
`ElementId`	The ID of the created beam.

`cut_beam_end_profile(element_id_list: list[ElementId], profile_name: str, on_start_face: bool, on_end_face: bool) -> None`

Add end profile to beam elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to modify.	required
`profile_name`	`str`	The name of the profile to add.	required
`on_start_face`	`bool`	Cut on the start face?	required
`on_end_face`	`bool`	Cut on the end face?	required

`cut_corner_lap(element_id_list: list[ElementId], depth: float, clearance_base: float, clearance_side: float, backcut: float, drilling_count: UnsignedInt, drilling_diameter: float, drilling_tolerance: float) -> None`

Cuts a corner-lap joint with specific parameters.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be cut.	required
`depth`	`float`	The vertical depth of the lap cut applied to each element.	required
`clearance_base`	`float`	Additional clearance applied at the bottom (base) of the lap cut for fitting tolerance.	required
`clearance_side`	`float`	Additional clearance on the side faces of the cut to prevent tight joints or interference.	required
`backcut`	`float`	A small offset or undercut applied to the outer face of the cut to improve fit or reduce friction.	required
`drilling_count`	`UnsignedInt`	The number of drill holes to create for fasteners (e.g., bolts or dowels).	required
`drilling_diameter`	`float`	The diameter of each drill hole.	required
`drilling_tolerance`	`float`	The tolerance applied to the hole size for bolt head clearance or easier insertion.	required

`cut_cross_lap(element_id_list: list[ElementId], depth: float, clearance_base: float, clearance_side: float, drilling_count: UnsignedInt, drilling_diameter: float, drilling_tolerance: float) -> None`

Cuts a cross-lap joint with specific parameters.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be cut.	required
`depth`	`float`	The vertical depth of the cross-lap cut, typically half the thickness of the material.	required
`clearance_base`	`float`	Additional clearance at the bottom of the cut to ensure a proper fit between intersecting elements.	required
`clearance_side`	`float`	Additional clearance on the side walls of the cut to prevent tight fits or friction.	required
`drilling_count`	`UnsignedInt`	The number of drill holes to create for fasteners (e.g., bolts or dowels).	required
`drilling_diameter`	`float`	The diameter of each drill hole.	required
`drilling_tolerance`	`float`	The tolerance applied to the hole size for bolt head clearance or easier insertion.	required

`cut_diagonal_cut(element_id_list: list[ElementId], length: float, clearance_length: float, drilling_count: UnsignedInt, drilling_diameter: float, drilling_tolerance: float) -> None`

Cut a diagonal cut joint with specific parameters.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be cut.	required
`length`	`float`	The total length of the diagonal cut applied along the element.	required
`clearance_length`	`float`	Additional clearance along the cut length to ensure proper fitting between elements.	required
`drilling_count`	`UnsignedInt`	The number of drill holes to create for fasteners (e.g., bolts or dowels).	required
`drilling_diameter`	`float`	The diameter of each drill hole.	required
`drilling_tolerance`	`float`	The tolerance applied to the hole size for bolt head clearance or easier insertion.	required

`cut_double_shoulder(element_id_list: list[ElementId], connecting_element_id_list: list[ElementId]) -> None`

Cuts a double shoulder joint using the current 3D cutting options.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`connecting_element_id_list`	`list[ElementId]`	The list of elements that intersect or connect with the cut elements, used to determine the cutting geometry.	required

`cut_double_tenon(element_id_list: list[ElementId], depth1: float, depth2: float, clearance: float, backcut: float, drilling_count: UnsignedInt, drilling_diameter: float, drilling_tolerance: float) -> None`

Cut a double tenon joint with specific parameters.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be cut.	required
`depth1`	`float`	The depth of the first tenon shoulder.	required
`depth2`	`float`	The depth of the second tenon shoulder.	required
`clearance`	`float`	Additional clearance applied around the tenons for fitting tolerance during assembly.	required
`backcut`	`float`	A small undercut or inward offset to ensure the tenons fit without surface interference.	required
`drilling_count`	`UnsignedInt`	The number of drill holes to create for fasteners (e.g., bolts or dowels).	required
`drilling_diameter`	`float`	The diameter of each drill hole.	required
`drilling_tolerance`	`float`	The tolerance applied to the hole size for bolt head clearance or easier insertion.	required

`cut_element_with_plane(element_id: ElementId, cut_plane_normal_vector: point_3d, distance_from_global_origin: float) -> bool`

Cut an element with a plane.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required
`cut_plane_normal_vector`	`point_3d`	The normal vector of the cut plane.	required
`distance_from_global_origin`	`float`	The distance from the global origin to the cut plane.	required

Examples:

>>> import math
>>> beam_height = 240.
>>> beam_id = ec.create_rectangular_beam_vectors(120., beam_height, 3000., cadwork.point_3d(0., 0., 0.),
...                                             cadwork.point_3d(0., 0., 1.), cadwork.point_3d(0., 1., 0.))
>>> # Define plane normal vector (30° from vertical in Y-Z plane)
>>> angle_rad = math.radians(30)
>>> plane_normal = cadwork.point_3d(0., -math.sin(angle_rad), math.cos(angle_rad)).normalized()
>>> # Calculate distance from origin to plane
>>> plane_point = cadwork.point_3d(0., beam_height * .5, 1500.)  # Point for the cut plane
>>> distance = plane_point.dot(plane_normal)  # Distance from origin to plane
>>> # To measure (check result) the distance correctly in cadwork, create a parallel plane to the cut plane
>>> # with the result of distance as the offset. This plane should hit through the origin (0, 0, 0).
>>> print(f"Plane normal: {plane_normal}, Distance: {distance}")
>>> result = ec.cut_element_with_plane(beam_id, plane_normal, distance)
>>> print(f"Cut operation successful: {result}")

Returns:

Type	Description
`bool`	True if the cut operation was successful, false otherwise.

`cut_element_with_processing_group(soft_element: ElementId, processing: ElementId) -> None`

Cuts an element with a processing group.

Parameters:

Name	Type	Description	Default
`soft_element`	`ElementId`	The ID of the element to be cut.	required
`processing`	`ElementId`	The ID of the processing group.	required

`cut_elements_with_miter(first_id: ElementId, second_id: ElementId) -> bool`

Cut two elements with a miter joint.

Parameters:

Name	Type	Description	Default
`first_id`	`ElementId`	The ID of the first element.	required
`second_id`	`ElementId`	The ID of the second element.	required

Returns:

Type	Description
`bool`	True if the cut operation was successful, false otherwise.

`cut_elements_with_overmeasure(hard_element_id_list: list[ElementId], soft_element_id_list: list[ElementId]) -> None`

Cuts elements with overmeasure.

Parameters:

Name	Type	Description	Default
`hard_element_id_list`	`list[ElementId]`	The list of hard elements.	required
`soft_element_id_list`	`list[ElementId]`	The list of soft elements.	required

`cut_half_lap(element_id_list: list[ElementId], length: float, clearance_length: float, clearance_depth: float, drilling_count: UnsignedInt, drilling_diameter: float, drilling_tolerance: float) -> None`

Cut a half-lap joint with specific parameters.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be cut.	required
`length`	`float`	The length of the half-lap joint along the main axis of the elements.	required
`clearance_length`	`float`	Additional clearance along the length of the cut to ensure proper fitting.	required
`clearance_depth`	`float`	Additional clearance in the depth direction to avoid tight joints or surface interference.	required
`drilling_count`	`UnsignedInt`	The number of drill holes to create for fasteners (e.g., bolts or dowels).	required
`drilling_diameter`	`float`	The diameter of each drill hole.	required
`drilling_tolerance`	`float`	The tolerance applied to the hole size for bolt head clearance or easier insertion.	required

`cut_heel_shoulder(element_id_list: list[ElementId], connecting_element_id_list: list[ElementId]) -> None`

Cuts heel with current 3D options

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`connecting_element_id_list`	`list[ElementId]`	The list of elements that intersect or connect with the cut elements, used to determine the cutting geometry.	required

`cut_log_corner_joint(settings_name: str, element_id_list: list[ElementId]) -> None`

Cuts log corner joint.

Parameters:

Name	Type	Description	Default
`settings_name`	`str`	The name of the settings to be used for the cut.	required
`element_id_list`	`list[ElementId]`	The list of elements to be cut.	required

`cut_scarf_diagonal(element_id_list: list[ElementId], length: float, depth: float, clearance_length: float, clearance_depth: float, drilling_count: UnsignedInt, drilling_diameter: float, drilling_tolerance: float) -> None`

Cuts a diagonal scarf joint (lengthwise) with specific parameters.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements on which the diagonal scarf cut will be applied.	required
`length`	`float`	The total length of the scarf joint measured along the element’s axis.	required
`depth`	`float`	The vertical depth of the initial straight section before the diagonal cut begins.	required
`clearance_length`	`float`	Additional clearance along the length direction to facilitate proper fitting of the joint.	required
`clearance_depth`	`float`	Additional clearance along the depth direction to avoid tight joints or misalignment.	required
`drilling_count`	`UnsignedInt`	The number of drill holes for mechanical fasteners (e.g., bolts or dowels).	required
`drilling_diameter`	`float`	The diameter of each drill hole.	required
`drilling_tolerance`	`float`	Tolerance added to the hole diameter for ease of insertion or head fit.	required

`cut_scarf_straight(element_id_list: list[ElementId], length: float, depth: float, clearance_length: float, clearance_depth: float, clearance_hook: float, drilling_count: UnsignedInt, drilling_diameter: float, drilling_tolerance: float) -> None`

Cuts a straight scarf joint (lengthwise) with specific parameters.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to apply the scarf cut to.	required
`length`	`float`	The total length of the scarf joint cut, measured along the element’s longitudinal axis.	required
`depth`	`float`	The depth of the vertical cut where both side join.	required
`clearance_length`	`float`	Additional clearance along the length direction to ensure proper fitting of the joint.	required
`clearance_depth`	`float`	Additional clearance in the depth direction to avoid tight fits or interference.	required
`clearance_hook`	`float`	Clearance added specifically at the hook or notch feature of the joint, if any.	required
`drilling_count`	`UnsignedInt`	The number of holes to be drilled, typically for bolts, pegs, or dowels to reinforce the joint.	required
`drilling_diameter`	`float`	The diameter of each drilled hole.	required
`drilling_tolerance`	`float`	The tolerance added to the hole size for easier assembly or bolt head fitting.	required

`cut_scarf_with_wedge(element_id_list: list[ElementId], length: float, depth: float, clearance_length: float, clearance_depth: float, wedge_width: float, drilling_count: UnsignedInt, drilling_diameter: float, drilling_tolerance: float) -> None`

Cuts a diagonal scarf joint with an added wedge, using specific parameters.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements on which to apply the scarf-with-wedge cut.	required
`length`	`float`	The total length of the scarf joint, measured along the main axis of the element.	required
`depth`	`float`	The vertical depth of the straight portion of the cut before the diagonal section.	required
`clearance_length`	`float`	Additional clearance along the length direction for proper fit of the joint.	required
`clearance_depth`	`float`	Additional clearance in the depth direction to avoid interference.	required
`wedge_width`	`float`	The width of the wedge feature inserted or carved as part of the joint geometry.	required
`drilling_count`	`UnsignedInt`	The number of drill holes used to secure the joint (e.g., for bolts, pegs, or dowels).	required
`drilling_diameter`	`float`	The diameter of the drilled holes.	required
`drilling_tolerance`	`float`	Tolerance applied to the hole size, often used for easier bolt fitting or head clearance.	required

`cut_shoulder(element_id_list: list[ElementId], connecting_element_id_list: list[ElementId]) -> None`

Cuts shoulder with current 3D options.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`connecting_element_id_list`	`list[ElementId]`	The list of elements that intersect or connect with the cut elements, used to determine the cutting geometry.	required

`cut_simple_scarf(element_id_list: list[ElementId], length: float, depth: float, clearance_length: float, clearance_depth: float, drilling_count: UnsignedInt, drilling_diameter: float, drilling_tolerance: float) -> None`

Cut a simple scarf joint with specific parameters.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be cut.	required
`length`	`float`	The distance between the two starting points of the cut.	required
`depth`	`float`	The vertical depth of the initial straight cut before the diagonal cut begins.	required
`clearance_length`	`float`	The additional length clearance applied along the initial (depth) cut.	required
`clearance_depth`	`float`	The additional depth clearance applied along the diagonal cut.	required
`drilling_count`	`UnsignedInt`	The number of drill holes to be created for fasteners (e.g., bolts or dowels).	required
`drilling_diameter`	`float`	The diameter of each drill hole.	required
`drilling_tolerance`	`float`	The tolerance applied to the hole size, typically for fitting the bolt head or allowing easier assembly.	required

`cut_t_lap(element_id_list: list[ElementId], depth: float, clearance_base: float, clearance_side: float, backcut: float, drilling_count: UnsignedInt, drilling_diameter: float, drilling_tolerance: float) -> None`

Cuts a T-lap joint with specific parameters.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be cut.	required
`depth`	`float`	The vertical depth of the cut where the intersecting element will be placed.	required
`clearance_base`	`float`	Additional clearance at the base (bottom) of the cut to ensure a proper fit.	required
`clearance_side`	`float`	Additional clearance on the side faces of the cut to avoid tight fitting.	required
`backcut`	`float`	A small offset or undercut applied inward to improve fitting during assembly.	required
`drilling_count`	`UnsignedInt`	The number of drill holes to create for fasteners (e.g., bolts or dowels).	required
`drilling_diameter`	`float`	The diameter of each drill hole.	required
`drilling_tolerance`	`float`	The tolerance applied to the hole size for bolt head clearance or easier insertion.	required

`delete_all_element_end_types(element_id_list: list[ElementId]) -> None`

Deletes all end types of the elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required

`delete_all_element_processes(element_id_list: list[ElementId]) -> None`

Deletes all processes of the elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required

`delete_elements(element_id_list: list[ElementId]) -> None`

Deletes the specified elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required

`delete_elements_with_undo(element_id_list: list[ElementId]) -> None`

Deletes the provided elements with undo functionality.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to delete.	required

`delete_processes_keep_cutting_bodies(element_id_list: list[ElementId], keep_cutting_elements_only: bool) -> list[ElementId]`

Gets the cutting bodies of all processes (and deletes processes), like Ctrl+D Action

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be processed.	required
`keep_cutting_elements_only`	`bool`	True if the return element id contains only cutting elements, false otherwise.	required

Returns:

Type	Description
`list[ElementId]`	The id list of all removed geometry, cuttings bodies.

`extrude_surface_to_auxiliary_vector(surface: ElementId, vector: point_3d) -> ElementId`

Extrudes a surface to create an auxiliary element.

Parameters:

Name	Type	Description	Default
`surface`	`ElementId`	The surface to extrude.	required
`vector`	`point_3d`	The vector to extrude along.	required

Returns:

Type	Description
`ElementId`	The id of the created auxiliary element.

`extrude_surface_to_beam_vector(surface: ElementId, vector: point_3d) -> ElementId`

Extrudes a surface to create a beam element.

Parameters:

Name	Type	Description	Default
`surface`	`ElementId`	The surface to extrude.	required
`vector`	`point_3d`	The vector to extrude along.	required

Returns:

Type	Description
`ElementId`	The id of the created beam element.

`extrude_surface_to_panel_vector(surface: ElementId, vector: point_3d) -> ElementId`

Extrudes a surface to create a panel element.

Parameters:

Name	Type	Description	Default
`surface`	`ElementId`	The surface to extrude.	required
`vector`	`point_3d`	The vector to extrude along.	required

Returns:

Type	Description
`ElementId`	The id of the created panel element.

`fillet_edge(element_id: ElementId, edge_start: point_3d, edge_end: point_3d, radius: float) -> None`

Fillet an edge of an element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required
`edge_start`	`point_3d`	The start point of the edge.	required
`edge_end`	`point_3d`	The end point of the edge.	required
`radius`	`float`	The radius of the fillet.	required

`filter_elements(element_id_list: list[ElementId], element_filter: element_filter) -> list[ElementId]`

Filters a list of elements based on a provided filter.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to filter.	required
`element_filter`	`element_filter`	The filter to apply to the list of elements.	required

Examples:

>>> import cadwork
>>> import element_controller as ec
>>> your_element_filter = cadwork.element_filter()
>>> your_element_filter.set_name("beam")
>>> filtered_elements = ec.filter_elements(ec.get_active_identifiable_element_ids(), your_element_filter)
>>> print(filtered_elements)

Returns:

Type	Description
`list[ElementId]`	The filtered list of element IDs.

`get_active_identifiable_element_ids() -> list[ElementId]`

Get a list of all active identifiable elements.

Returns:

Type	Description
`list[ElementId]`	A list of IDs of all active identifiable elements.

`get_all_identifiable_element_ids() -> list[ElementId]`

Retrieves a list of all identifiable elements.

Returns:

Type	Description
`list[ElementId]`	A list of all identifiable element IDs.

`get_all_nesting_raw_parts() -> list[ElementId]`

Get a list of all raw parts in a nesting operation.

Returns:

Type	Description
`list[ElementId]`	The list of IDs of all raw parts in a nesting operation.

`get_bounding_box_vertices_global(element_id_list: list[ElementId]) -> list[point_3d]`

Get the global bounding box vertices for a list of elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements for which to retrieve the bounding box vertices.	required

Returns:

Type	Description
`list[point_3d]`	The list of vertices representing the global bounding box of the elements.

`get_bounding_box_vertices_local(reference_element: ElementId, element_id_list: list[ElementId]) -> list[point_3d]`

Retrieves the local bounding box vertices for a list of elements relative to a reference element.

Parameters:

Name	Type	Description	Default
`reference_element`	`ElementId`	The ID of the reference element.	required
`element_id_list`	`list[ElementId]`	The list of elements for which to retrieve the bounding box vertices.	required

Returns:

Type	Description
`list[point_3d]`	The list of vertices representing the local bounding box of the elements.

`get_container_content_elements(element_id: ElementId) -> list[ElementId]`

Get the content elements of a container.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`list[ElementId]`	The list of content elements.

`get_coordinate_system_data_nesting_child(nesting_parent_id: ElementId, nesting_child_id: ElementId) -> coordinate_system_data`

Get the coordinate system of nesting child

Parameters:

Name	Type	Description	Default
`nesting_parent_id`	`ElementId`	The nesting parent id.	required
`nesting_child_id`	`ElementId`	The nesting child id.	required

Returns:

Type	Description
`coordinate_system_data`	A global element coordinate-system of the nested child element consisting of a Point1, a Point2 and a Point3. You can get the local placement by subtracting the parent coordinate - system with child coordinate - system.

`get_edge_selection(element_id_list: list[ElementId]) -> edge_list`

Retrieves the edge selection of the provided elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of element IDs.	required

Returns:

Type	Description
`edge_list`	The list of edges selected.

`get_element_active_point(element_id: ElementId) -> active_point_result`

Gets the active point associated with an element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Examples:

>>> import cadwork
>>> import element_controller as ec
>>> [element_id] = ec.get_active_identifiable_element_ids()
>>> result = ec.get_element_active_point(element_id)
>>> if result:
...     ec.create_node(result.point)
... else:
...     print("No active point set for element.")

Returns:

Type	Description
`active_point_result`	True/False plus point data when available.

`get_element_cadwork_guid(element_id: ElementId) -> str`

Get the Cadwork GUID of a specific element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`str`	The Cadwork GUID of the element.

`get_element_contact_facets(first_id: ElementId, second_id: ElementId) -> facet_list`

Retrieves the contact facets between two elements.

Parameters:

Name	Type	Description	Default
`first_id`	`ElementId`	The ID of the first element.	required
`second_id`	`ElementId`	The ID of the second element.	required

Returns:

Type	Description
`facet_list`	The list of contact facets between the two elements.

`get_element_contact_vertices(first_id: ElementId, second_id: ElementId) -> list[point_3d]`

Get the contact vertices between two elements.

Parameters:

Name	Type	Description	Default
`first_id`	`ElementId`	The ID of the first element.	required
`second_id`	`ElementId`	The ID of the second element.	required

Returns:

Type	Description
`list[point_3d]`	The list of contact vertices between the two elements.

`get_element_detail_path() -> str`

Get the detail path of the element module.

Returns:

Type	Description
`str`	The detail path of the element module.

`get_element_from_cadwork_guid(cadwork_guid: str) -> ElementId`

Gets element from cadwork guid.

Parameters:

Name	Type	Description	Default
`cadwork_guid`	`str`	The cadwork guid.	required

Returns:

Type	Description
`ElementId`	The element ID.

`get_element_module_properties_for_element(element_id: ElementId) -> element_module_properties`

Retrieves the module properties for a specific element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`element_module_properties`	The module properties of the element.

`get_element_raw_interface_vertices(first_id: ElementId, second_id: ElementId) -> list[point_3d]`

Get the raw interface vertices between two elements.

Parameters:

Name	Type	Description	Default
`first_id`	`ElementId`	The ID of the first element.	required
`second_id`	`ElementId`	The ID of the second element.	required

Returns:

Type	Description
`list[point_3d]`	The list of raw interface vertices between the two elements.

`get_element_type_description(element_id: ElementId) -> str`

Retrieves the type description of a specific element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`str`	The type description of the element.

`get_elements_in_collision(element_id: ElementId) -> list[ElementId]`

Retrieves a list of elements in collision with a specific element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The ID of the element to check for collision.	required

Returns:

Type	Description
`list[ElementId]`	A list of IDs of the elements in collision with the specified element.

`get_elements_in_contact(element_id: ElementId) -> list[ElementId]`

Retrieves a list of elements in contact with a specific element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The ID of the element to check for contact.	required

Returns:

Type	Description
`list[ElementId]`	The list of IDs of the elements in contact with the specified element.

`get_export_solid_content_elements(element_id: ElementId) -> list[ElementId]`

Get the content elements of an export solid.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`list[ElementId]`	The list of content elements.

`get_facets_with_lasso(element_id_list: list[ElementId]) -> facet_list`

Retrieves the facets of elements within a lasso selection.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to check for facets within the lasso selection.	required

Returns:

Type	Description
`facet_list`	The list of facets selected.

`get_inactive_all_identifiable_element_ids() -> list[ElementId]`

Get a list of all inactive identifiable elements.

Returns:

Type	Description
`list[ElementId]`	A list of IDs of all inactive identifiable elements.

`get_inactive_visible_identifiable_element_ids() -> list[ElementId]`

Get a list of all inactive visible identifiable elements.

Returns:

Type	Description
`list[ElementId]`	A list of IDs of all inactive visible identifiable elements.

`get_invisible_identifiable_element_ids() -> list[ElementId]`

Get a list of all invisible identifiable elements.

Returns:

Type	Description
`list[ElementId]`	A list of IDs of all invisible identifiable elements.

`get_is_element_group_multi_select_mode() -> bool`

Gets whether the current element group selection mode is setup to select multiple elements.

Returns:

Type	Description
`bool`	True if the current element group selection mode is set to multi select, false otherwise.

`get_is_element_group_single_select_mode() -> bool`

Gets whether the current element group selection mode is setup to select single elements.

Returns:

Type	Description
`bool`	True if the current element group selection mode is set to single select, false otherwise.

`get_joined_elements(element_id: ElementId) -> list[ElementId]`

Retrieves the IDs of elements that have been joined with the specified element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`list[ElementId]`	The list of IDs of the joined elements.

`get_nesting_parent_id(element_id: ElementId) -> ElementId`

Get the parent ID of a nested element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`ElementId`	The ID of the parent element.

`get_opening_variant_ids(element_id_list: list[ElementId], opening_type: int) -> list[int]`

Get the opening variant IDs for a list of elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of element IDs.	required
`opening_type`	`int`	The type of opening to check for. Unknown = 0, Window = 1, Door = 2.	required

Returns:

Type	Description
`list[int]`	The list of opening variant IDs.

`get_parent_container_id(element_id: ElementId) -> ElementId`

Get the parent container ID of a nested element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`ElementId`	The ID of the parent element.

`get_reference_element(element_id: ElementId) -> ElementId`

Get the reference element for a given element.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`ElementId`	The reference element ID.

`get_standard_beam_list() -> list[str]`

Retrieves a list of standard beam names.

Returns:

Type	Description
`list[str]`	The list of standard beam names.

`get_standard_container_list() -> list[str]`

Retrieves a list of standard container names.

Returns:

Type	Description
`list[str]`	The list of standard container names.

`get_standard_export_solid_list() -> list[str]`

Retrieves a list of standard export solid names.

Returns:

Type	Description
`list[str]`	The list of standard export solid names.

`get_standard_panel_list() -> list[str]`

Retrieves a list of standard panel names.

Returns:

Type	Description
`list[str]`	The list of standard panel names.

`get_text_object_options(element_id: ElementId) -> text_object_options`

Retrieves the text object options for a specific element e.g. font, text content, etc.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The ID of the element to retrieve options for.	required

Returns:

Type	Description
`text_object_options`	The text object options for the specified element.

`get_user_element_ids() -> list[ElementId]`

Gets a list of user element IDs.

Returns:

Type	Description
`list[ElementId]`	The user element IDs.

`get_user_element_ids_with_count(count: int) -> list[ElementId]`

Retrieves a list of user element IDs.

Parameters:

Name	Type	Description	Default
`count`	`int`	The maximal number of elements to select.	required

Returns:

Type	Description
`list[ElementId]`	The list of user element IDs.

`get_user_element_ids_with_existing(element_id_list: list[ElementId]) -> list[ElementId]`

Retrieve a list of user element IDs that exist in the provided list.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to check for existence.	required

Returns:

Type	Description
`list[ElementId]`	The list of existing user element IDs.

`get_variant_sibling_element_ids(element_id: ElementId) -> list[ElementId]`

Retrieves a list of variant sibling element IDs.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

Returns:

Type	Description
`list[ElementId]`	The list of variant sibling element IDs.

`get_visible_identifiable_element_ids() -> list[ElementId]`

Get a list of all visible identifiable elements.

Returns:

Type	Description
`list[ElementId]`	A list of IDs of all visible identifiable elements.

`glide_elements(element_id_list: list[ElementId], glide_origin_point: point_3d) -> None`

Glides elements to a specified point.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to glide.	required
`glide_origin_point`	`point_3d`	The glide origin point.	required

`join_elements(element_id_list: list[ElementId]) -> None`

Joins the specified elements together.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required

`join_top_level_elements(element_id_list: list[ElementId]) -> None`

Joins the specified top-level elements together.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required

`make_redo() -> None`

Performs a redo operation, reapplying the last undone change.

`make_undo() -> None`

Performs an undo operation, reverting the last change made.

`map_elements(element_id_list: list[ElementId], map_query: element_map_query) -> dict[str, list[ElementId]]`

Maps a list of elements based on a provided map query.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to map.	required
`map_query`	`element_map_query`	The map query to apply to the list of elements.	required

Examples:

>>> import cadwork
>>> import element_controller as ec
>>> your_map_query = cadwork.element_map_query()
>>> your_map_query.set_by_subgroup()
>>> mapped_items = ec.map_elements(ec.get_active_identifiable_element_ids(), your_map_query)
>>> print(mapped_items)

Returns:

Type	Description
`dict[str, list[ElementId]]`	The map of elements that pass the map query.

`mirror_copy_elements(element_id_list: list[ElementId], plane: point_3d, plane_distance: float) -> list[ElementId]`

Copies elements by mirroring them across a plane.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The ID of the element to copy.	required
`plane`	`point_3d`	The plane to mirror across.	required
`plane_distance`	`float`	The distance from the plane.	required

Returns:

Type	Description
`list[ElementId]`	The list of IDs of the copied elements.

`mirror_move_elements(element_id_list: list[ElementId], plane: point_3d, plane_distance: float) -> None`

Mirrors and moves elements across a plane.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of element IDs to mirror and move.	required
`plane`	`point_3d`	The plane to mirror across.	required
`plane_distance`	`float`	The distance from the plane.	required

`move_element(element_id_list: list[ElementId], move_vector: point_3d) -> None`

Moves the provided element by a specified vector.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`move_vector`	`point_3d`	The vector by which to move the elements.	required

`move_element_with_undo(element_id_list: list[ElementId], vector: point_3d) -> None`

Moves an element with undo functionality.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`vector`	`point_3d`	The vector to move the element.	required

`parts_situation_manual(cover: ElementId, add_childs: list[ElementId], remove_childs: list[ElementId]) -> None`

Manually sets the parts situation for a cover element.

Parameters:

Name	Type	Description	Default
`cover`	`ElementId`	The cover element ID.	required
`add_childs`	`list[ElementId]`	The list of child element IDs to add.	required
`remove_childs`	`list[ElementId]`	The list of child element IDs to remove.	required

`recreate_elements(element_id_list: list[ElementId]) -> None`

Recreate elements based on the provided list.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to recreate.	required

`remove_standard_beam(guid: str) -> None`

Removes a standard beam.

Parameters:

Name	Type	Description	Default
`guid`	`str`	The unique identifier of the standard connector axis to be removed.	required

`remove_standard_connector_axis(guid: str) -> None`

Removes a standard connector axis.

Parameters:

Name	Type	Description	Default
`guid`	`str`	The unique identifier of the standard connector axis to be removed.	required

`remove_standard_container(guid: str) -> None`

Removes a standard container.

Parameters:

Name	Type	Description	Default
`guid`	`str`	The unique identifier of the standard container to be removed.	required

`remove_standard_export_solid(guid: str) -> None`

Removes a standard export solid.

Parameters:

Name	Type	Description	Default
`guid`	`str`	The unique identifier of the standard export solid to be removed.	required

`remove_standard_panel(guid: str) -> None`

Removes a standard panel.

Parameters:

Name	Type	Description	Default
`guid`	`str`	The unique identifier of the standard panel to be removed.	required

`replace_physical_drillings_with_drilling_axes(element_id_list: list[ElementId], mininum_diameter: float, maximum_diameter: float) -> list[ElementId]`

Replaces physical drillings with drilling axes based on diameter range.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to process.	required
`mininum_diameter`	`float`	The minimum diameter of the drilling.	required
`maximum_diameter`	`float`	The maximum diameter of the drilling.	required

Returns:

Type	Description
`list[ElementId]`	The list of IDs of the elements where the replacement was successful.

`reset_element_cadwork_guid(element_id: ElementId) -> None`

Sets the Cadwork Guid of an element to NULL.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required

`rotate_elements(element_id_list: list[ElementId], origin: point_3d, rotation_axis: point_3d, rotation_angle: float) -> None`

Rotate the provided elements around a specified axis.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required
`origin`	`point_3d`	The origin point of the rotation.	required
`rotation_axis`	`point_3d`	The axis around which to rotate the elements.	required
`rotation_angle`	`float`	The angle by which to rotate the elements un degree.	required

`rough_volume_situation_manual(cover: ElementId, add_partner: list[ElementId], remove_partner: list[ElementId]) -> None`

Manually sets the rough volume situation for a cover element.

Parameters:

Name	Type	Description	Default
`cover`	`ElementId`	The cover element ID.	required
`add_partner`	`list[ElementId]`	The list of partner element IDs to add.	required
`remove_partner`	`list[ElementId]`	The list of partner element IDs to remove.	required

`set_container_contents(container_id: ElementId, element_id_list: list[ElementId]) -> None`

Sets the contents of a container.

Parameters:

Name	Type	Description	Default
`container_id`	`ElementId`	The ID of the container to set the contents for.	required
`element_id_list`	`list[ElementId]`	The list of element IDs to set as the contents of the container.	required

`set_double_shoulder_options(options: double_shoulder_options) -> None`

Sets the double shoulder cut options.

Parameters:

Name	Type	Description	Default
`options`	`double_shoulder_options`	The double shoulder options to set.	required

`set_element_detail_path(path: str) -> None`

Sets the detail path for the element.

Parameters:

Name	Type	Description	Default
`path`	`str`	The detail path.	required

`set_element_group_multi_select_mode() -> None`

Switches the current element group selection mode so that all elements of a group are selected when selecting one of it.

`set_element_group_single_select_mode() -> None`

Switches the current element group selection mode so that single elements of a group are selectable.

`set_element_module_properties_for_elements(element_id_list: list[ElementId], properties: element_module_properties) -> None`

Sets the element module properties for elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to modify.	required
`properties`	`element_module_properties`	The properties to set.	required

`set_export_solid_contents(export_solid_id: ElementId, element_id_list: list[ElementId]) -> None`

Sets the contents of an export solid.

Parameters:

Name	Type	Description	Default
`export_solid_id`	`ElementId`	The ID of the export solid to set the contents for.	required
`element_id_list`	`list[ElementId]`	The list of element IDs to set as the contents of the export solid.	required

`set_heel_shoulder_options(options: heel_shoulder_options) -> None`

Sets the heel shoulder cut options.

Parameters:

Name	Type	Description	Default
`options`	`heel_shoulder_options`	The heel shoulder options to set.	required

`set_line_to_marking_line(element_id_list: list[ElementId]) -> None`

Sets the line to the marking line.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to modify.	required

`set_line_to_normal_line(element_id_list: list[ElementId]) -> None`

Sets the line to the normal line.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to modify.	required

`set_parent_opening_variants_opening_angle(element_id_list: list[ElementId], angle: float) -> None`

Sets the opening angle of the parent opening variants.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of element IDs to set the opening angle for.	required
`angle`	`float`	The opening angle to set.	required

`set_shoulder_options(options: shoulder_options) -> None`

Sets the shoulder cut options.

Parameters:

Name	Type	Description	Default
`options`	`shoulder_options`	The shoulder options to set.	required

`slice_element_with_plane(element_id: ElementId, cut_plane_normal_vector: point_3d, distance_from_global_origin: float) -> bool`

Slice an element with a plane.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The element id.	required
`cut_plane_normal_vector`	`point_3d`	The normal vector of the cut plane.	required
`distance_from_global_origin`	`float`	The distance from the global origin to the slicing plane.	required

Examples:

>>> import math
>>> # Create a panel to slice
>>> panel_width = 1200.
>>> panel_thickness = 20.
>>> panel_length = 2400.
>>> panel_id = ec.create_rectangular_panel_vectors(panel_width, panel_thickness, panel_length, 
...                                              cadwork.point_3d(0., 0., 0.),
...                                              cadwork.point_3d(1., 0., 0.), 
...                                              cadwork.point_3d(0., 0., 1.))
>>> # Define plane normal vector (45° in XY plane)
>>> angle_rad = math.radians(45)
>>> plane_normal = cadwork.point_3d(math.cos(angle_rad), math.sin(angle_rad), 0.).normalized()
>>> # Calculate distance from origin to plane - slice through center of panel
>>> panel_center = cadwork.point_3d(panel_length/2., panel_width/2., 0.)
>>> ec.create_node(panel_center)  # Create a node at the center of the panel
>>> distance = panel_center.dot(plane_normal)  # Distance from origin to plane
>>> # Verify plane equation: dot(point_on_plane, normal) = distance
>>> # Any point on the plane should satisfy this equation
>>> print(f"Plane normal: {plane_normal}, Distance: {distance}")
>>> # Slice the panel
>>> result = ec.slice_element_with_plane(panel_id, plane_normal, distance)
>>> print(f"Slice operation successful: {result}")
>>> # Note: slice_element_with_plane keeps both parts as a joined element

Returns:

Type	Description
`bool`	True if the slicing operation was successful, false otherwise.

`slice_elements_with_plane_and_get_new_elements(element_id: ElementId, cut_plane_normal_vector: point_3d, distance_from_global_origin: float) -> list[ElementId]`

Slices an element with a plane and returns the new elements.

Parameters:

Name	Type	Description	Default
`element_id`	`ElementId`	The ID of the element to be sliced.	required
`cut_plane_normal_vector`	`point_3d`	The normal vector of the cutting plane.	required
`distance_from_global_origin`	`float`	The distance from the global origin to the cutting plane.	required

Examples:

>>> import math
>>> # Create a beam to slice
>>> beam_width = 150.
>>> beam_height = 300.
>>> beam_length = 4000.
>>> beam_id = ec.create_rectangular_beam_vectors(beam_width, beam_height, beam_length,
...                                            cadwork.point_3d(0., 0., 0.),
...                                            cadwork.point_3d(1., 0., 0.),
...                                            cadwork.point_3d(0., 0., 1.))
>>> # Define a vertical cutting plane through the middle of the beam
>>> plane_normal = cadwork.point_3d(1., 0., 0.)  # Normal vector points along X-axis
>>> # A point on the plane (midpoint of the beam)
>>> plane_point = cadwork.point_3d(beam_length/2., 0., 0.)
>>> distance = plane_point.dot(plane_normal)  # Distance from origin to plane
>>> # Verify with additional points on the plane
>>> test_point = cadwork.point_3d(beam_length/2., 100., 200.)
>>> on_plane = abs(test_point.dot(plane_normal) - distance) < 0.001
>>> print(f"Test point is on plane: {on_plane}")
>>> # Slice the beam at the midpoint and get the resulting pieces
>>> new_element_ids = ec.slice_elements_with_plane_and_get_new_elements(beam_id, plane_normal, distance)
>>> print(f"Created {len(new_element_ids)} new element_id_list: {new_element_ids}")
>>> # Visualization: different pen colors for the new elements
>>> for i, new_id in enumerate(new_element_ids):
...     vc.set_color([new_id], i+5)

Returns:

Type	Description
`list[ElementId]`	The list of IDs of the new elements created by the slicing operation.

`solder_elements(element_id_list: list[ElementId]) -> list[ElementId]`

Solders elements together.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required

Returns:

Type	Description
`list[ElementId]`	The list of soldered element IDs.

`split_elements(element_id_list: list[ElementId]) -> None`

Splits elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The elements to split.	required

`start_element_module_calculation(covers: list[ElementId]) -> None`

Starts the calculation of the element module for a list of covers.

Parameters:

Name	Type	Description	Default
`covers`	`list[ElementId]`	The list of cover element IDs.	required

`start_element_module_calculation_silently(covers: list[ElementId]) -> None`

Starts the calculation of the element module for a list of covers silently (without user interaction).

Parameters:

Name	Type	Description	Default
`covers`	`list[ElementId]`	The list of covers for which to start the element module calculation.	required

`start_standard_element_dialog(standard_element_type: standard_element_type) -> str`

Starts the standard element dialogue based on the chosen element type.

Parameters:

Name	Type	Description	Default
`standard_element_type`	`standard_element_type`	The type of the standard element to create.	required

Returns:

Type	Description
`str`	The GUID of the selected standard element if the item is valid, else null.

`stretch_end_facet(element_id_list: list[ElementId], stretch_vector: point_3d) -> None`

Stretch the end facet of the given elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be stretched.	required
`stretch_vector`	`point_3d`	A vector that defines the stretch direction and distance.	required

`stretch_start_facet(element_id_list: list[ElementId], stretch_vector: point_3d) -> None`

Stretch the start facet of the given elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The list of elements to be stretched.	required
`stretch_vector`	`point_3d`	A vector that defines the stretch direction and distance.	required

`subtract_elements(hard_elements: list[ElementId], soft_elements: list[ElementId]) -> list[ElementId]`

Subtracts the volume of hard_elements from soft_elements (boolean difference). Soft elements are cut in place and keep their IDs.

Parameters:

Name	Type	Description	Default
`hard_elements`	`list[ElementId]`	The cutter elements. Not modified.	required
`soft_elements`	`list[ElementId]`	The elements to be cut. Modified in place.	required

Returns:

Type	Description
`list[ElementId]`	list[ElementId]: Additional element IDs produced when a soft element is split into multiple disconnected pieces by the subtraction. Does not include the IDs from `soft_elements`.

`subtract_elements_with_undo(hard_element_id_list: list[ElementId], soft_element_id_list: list[ElementId], with_undo: bool) -> list[ElementId]`

Subtracts the volume of hard_elements from soft_elements (boolean difference) with undo functionality. Soft elements are cut in place and keep their IDs.

Parameters:

Name	Type	Description	Default
`hard_element_id_list`	`list[ElementId]`	The cutter elements. Not modified.	required
`soft_element_id_list`	`list[ElementId]`	The elements to be cut. Modified in place.	required
`with_undo`	`bool`	Indicate whether the operation should be added to the undo stack.	required

Returns:

Type	Description
`list[ElementId]`	list[ElementId]: Additional element IDs produced when a soft element is split into multiple disconnected pieces by the subtraction. Does not include the IDs from `soft_elements`.

`unjoin_elements(element_id_list: list[ElementId]) -> bool`

Unjoins the specified elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required

Returns:

Type	Description
`bool`	True if the operation was successful, false if an error occured.

`unjoin_top_level_elements(element_id_list: list[ElementId]) -> bool`

Unjoins the specified top-level elements.

Parameters:

Name	Type	Description	Default
`element_id_list`	`list[ElementId]`	The element id list.	required

Returns:

Type	Description
`bool`	True if the operation was successful, false if an error occured.