Direct API Reference

The Direct API is an interface layer between the primary user interface API (the Builders) and the OpenCascade (OCCT) API. This API is based on the CadQuery Direct API (thank you to all of the CadQuery contributors that made this possible) with the following major changes:

• PEP8 compliance

• New Axis class

• New ShapeList class enabling sorting and filtering of shape objects

• Literal strings replaced with Enums

Geometric Objects

The geometric classes defined by build123d are defined below. This parameters to the CAD objects described in the following section are frequently of these types.

class Axis(*args, **kwargs)

Axis defined by point and direction

Parameters

• origin (VectorLike) – start point

• direction (VectorLike) – direction

• edge (Edge) – origin & direction defined by start of edge

Variables

• position (Vector) – the global position of the axis origin

• direction (Vector) – the normalized direction vector

• wrapped (gp_Ax1) – the OCP axis object

__copy__() → Axis

Return copy of self

__deepcopy__(_memo) → Axis

Return deepcopy of self

__neg__() → Axis

Flip direction operator -

angle_between(other: Axis) → float

calculate angle between axes

Computes the angular value, in degrees, between the direction of self and other between 0° and 360°.

Parameters

other (Axis) – axis to compare to

Returns

angle between axes

Return type

float

classmethod from_occt(axis: gp_Ax1) → Axis

Create an Axis instance from the occt object

is_coaxial(other: Axis, angular_tolerance: float = 1e-05, linear_tolerance: float = 1e-05) → bool

are axes coaxial

True if the angle between self and other is lower or equal to angular_tolerance and the distance between self and other is lower or equal to linear_tolerance.

Parameters

• other (Axis) – axis to compare to

• angular_tolerance (float, optional) – max angular deviation. Defaults to 1e-5.

• linear_tolerance (float, optional) – max linear deviation. Defaults to 1e-5.

Returns

axes are coaxial

Return type

bool

is_normal(other: Axis, angular_tolerance: float = 1e-05) → bool

are axes normal

Returns True if the direction of this and another axis are normal to each other. That is, if the angle between the two axes is equal to 90° within the angular_tolerance.

Parameters

• other (Axis) – axis to compare to

• angular_tolerance (float, optional) – max angular deviation. Defaults to 1e-5.

Returns

axes are normal

Return type

bool

is_opposite(other: Axis, angular_tolerance: float = 1e-05) → bool

are axes opposite

Returns True if the direction of this and another axis are parallel with opposite orientation. That is, if the angle between the two axes is equal to 180° within the angular_tolerance.

Parameters

• other (Axis) – axis to compare to

• angular_tolerance (float, optional) – max angular deviation. Defaults to 1e-5.

Returns

axes are opposite

Return type

bool

is_parallel(other: Axis, angular_tolerance: float = 1e-05) → bool

are axes parallel

Returns True if the direction of this and another axis are parallel with same orientation or opposite orientation. That is, if the angle between the two axes is equal to 0° or 180° within the angular_tolerance.

Parameters

• other (Axis) – axis to compare to

• angular_tolerance (float, optional) – max angular deviation. Defaults to 1e-5.

Returns

axes are parallel

Return type

bool

located(new_location: Location)

relocates self to a new location possibly changing position and direction

property location: Location

Return self as Location

reverse() → Axis

Return a copy of self with the direction reversed

to_plane() → Plane

Return self as Plane

class BoundBox(bounding_box: Bnd_Box)

A BoundingBox for a Shape

add(obj: Union[tuple[float, float, float], Vector, BoundBox], tol: Optional[float] = None) → BoundBox

Returns a modified (expanded) bounding box

obj can be one of several things:

1. a 3-tuple corresponding to x,y, and z amounts to add

2. a vector, containing the x,y,z values to add

3. another bounding box, where a new box will be created that encloses both.

This bounding box is not changed.

Parameters

• obj – Union[tuple[float:

• float –

• float] –

• Vector –

• BoundBox] –

• tol – float: (Default value = None)

Returns:

center() → Vector

Return center of the bounding box

property diagonal: float

body diagonal length (i.e. object maximum size)

static find_outside_box_2d(bb1: BoundBox, bb2: BoundBox) → Optional[BoundBox]

Compares bounding boxes

Compares bounding boxes. Returns none if neither is inside the other. Returns the outer one if either is outside the other.

BoundBox.is_inside works in 3d, but this is a 2d bounding box, so it doesn’t work correctly plus, there was all kinds of rounding error in the built-in implementation i do not understand.

Parameters

• bb1 – BoundBox:

• bb2 – BoundBox:

Returns:

is_inside(second_box: BoundBox) → bool

Is the provided bounding box inside this one?

Parameters

b2 – BoundBox:

Returns:

to_align_offset(align: Tuple[float, float]) → Tuple[float, float]

Amount to move object to achieve the desired alignment

class Color(*args, **kwargs)

Color object based on OCCT Quantity_ColorRGBA.

Variables

wrapped (Quantity_ColorRGBA) – the OCP color object

__copy__() → Color

Return copy of self

__deepcopy__(_memo) → Color

Return deepcopy of self

to_tuple()

Value as tuple

class Location(*args)

Location in 3D space. Depending on usage can be absolute or relative.

This class wraps the TopLoc_Location class from OCCT. It can be used to move Shape objects in both relative and absolute manner. It is the preferred type to locate objects in build123d.

Variables

wrapped (TopLoc_Location) – the OCP location object

T

alias of TypeVar(‘T’, bound=Union[Location, Shape])

__copy__() → Location

Lib/copy.py shallow copy

__deepcopy__(_memo) → Location

Lib/copy.py deep copy

__eq__(other: Location) → bool

Compare Locations

__mul__(other: T) → T

Combine locations

__neg__() → Location

Flip the orientation without changing the position operator -

__pow__(exponent: int) → Location

inverse() → Location

Inverted location

property orientation: Vector

Extract orientation/rotation component of self

Returns

orientation part of Location

Return type

Vector

property position: Vector

Extract Position component of self

Returns

Position part of Location

Return type

Vector

to_axis() → Axis

Convert the location into an Axis

to_tuple() → tuple[tuple[float, float, float], tuple[float, float, float]]

Convert the location to a translation, rotation tuple.

property x_axis: Axis

Default X axis when used as a plane

property y_axis: Axis

Default Y axis when used as a plane

property z_axis: Axis

Default Z axis when used as a plane

class LocationEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Custom JSON Encoder for Location values

Example:

data_dict = {
    "part1": {
        "joint_one": Location((1, 2, 3), (4, 5, 6)),
        "joint_two": Location((7, 8, 9), (10, 11, 12)),
    },
    "part2": {
        "joint_one": Location((13, 14, 15), (16, 17, 18)),
        "joint_two": Location((19, 20, 21), (22, 23, 24)),
    },
}
json_object = json.dumps(data_dict, indent=4, cls=LocationEncoder)
with open("sample.json", "w") as outfile:
    outfile.write(json_object)
with open("sample.json", "r") as infile:
    copy_data_dict = json.load(infile, object_hook=LocationEncoder.location_hook)

default(o: Location) → dict

Return a serializable object

static location_hook(obj) → dict

Convert Locations loaded from json to Location objects

Example

read_json = json.load(infile, object_hook=LocationEncoder.location_hook)

class Pos(*args, **kwargs)

A position only sub-class of Location

Rot

alias of Rotation

class Matrix(matrix=None)

A 3d , 4x4 transformation matrix.

Used to move geometry in space.

The provided “matrix” parameter may be None, a gp_GTrsf, or a nested list of values.

If given a nested list, it is expected to be of the form:

[[m11, m12, m13, m14],

[m21, m22, m23, m24], [m31, m32, m33, m34]]

A fourth row may be given, but it is expected to be: [0.0, 0.0, 0.0, 1.0] since this is a transform matrix.

Variables

wrapped (gp_GTrsf) – the OCP transformation function

__copy__() → Matrix

Return copy of self

__deepcopy__(_memo) → Matrix

Return deepcopy of self

inverse() → Matrix

Invert Matrix

multiply(other)

Matrix multiplication

rotate(axis: Axis, angle: float)

General rotate about axis

transposed_list() → Sequence[float]

Needed by the cqparts gltf exporter

class Plane(*args, **kwargs)

A plane is positioned in space with a coordinate system such that the plane is defined by the origin, x_dir (X direction), y_dir (Y direction), and z_dir (Z direction) of this coordinate system, which is the “local coordinate system” of the plane. The z_dir is a vector normal to the plane. The coordinate system is right-handed.

A plane allows the use of local 2D coordinates, which are later converted to global, 3d coordinates when the operations are complete.

Planes can be created from faces as workplanes for feature creation on objects.

Name	x_dir	y_dir	z_dir
XY	+x	+y	+z
YZ	+y	+z	+x
ZX	+z	+x	+y
XZ	+x	+z	-y
YX	+y	+x	-z
ZY	+z	+y	-x
front	+x	+z	-y
back	-x	+z	+y
left	-y	+z	-x
right	+y	+z	+x
top	+x	+y	+z
bottom	+x	-y	-z

Parameters

• gp_pln (gp_Pln) – an OCCT plane object

• origin (Union[tuple[float, float, float], Vector]) – the origin in global coordinates

• x_dir (Union[tuple[float, float, float], Vector], optional) – an optional vector representing the X Direction. Defaults to None.

• z_dir (Union[tuple[float, float, float], Vector], optional) – the normal direction for the plane. Defaults to (0, 0, 1).

Variables

• origin (Vector) – global position of local (0,0,0) point

• x_dir (Vector) – x direction

• y_dir (Vector) – y direction

• z_dir (Vector) – z direction

• local_coord_system (gp_Ax3) – OCP coordinate system

• forward_transform (Matrix) – forward location transformation matrix

• reverse_transform (Matrix) – reverse location transformation matrix

• wrapped (gp_Pln) – the OCP plane object

Raises

• ValueError – z_dir must be non null

• ValueError – x_dir must be non null

• ValueError – the specified x_dir is not orthogonal to the provided normal

Returns

A plane

Return type

Plane

__copy__() → Plane

Return copy of self

__deepcopy__(_memo) → Plane

Return deepcopy of self

__eq__(other: Plane)

Are planes equal operator ==

__mul__(other: Union[Location, 'Shape']) → Union[Plane, List[Plane], 'Shape']

__ne__(other: Plane)

Are planes not equal operator !+

__neg__() → Plane

Reverse z direction of plane operator -

contains(obj: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float], Axis], tolerance: float = 1e-06) → bool

Is this point or Axis fully contained in this plane?

Parameters

• obj (Union[VectorLike,Axis]) – point or Axis to evaluate

• tolerance (float, optional) – comparison tolerance. Defaults to TOLERANCE.

Returns

self contains point or Axis

Return type

bool

find_intersection(axis: Axis) → Optional[Vector]

Find intersection of axis and plane

from_local_coords(obj: Union[tuple, Vector, Any, BoundBox])

Reposition the object relative from this plane

Parameters

• obj – Union[VectorLike, Shape, BoundBox] an object to reposition. Note that

• classes. (type Any refers to all topological) –

Returns

an object of the same type, but repositioned to world coordinates

static get_topods_face_normal(face: TopoDS_Face) → Vector

Find the normal at the center of a TopoDS_Face

property location: Location

Return Location representing the origin and z direction

location_between(other: Plane) → Location

Return a location representing the translation from self to other

move(loc: Location) → Plane

Change the position & orientation of self by applying a relative location

Parameters

loc (Location) – relative change

Returns

relocated plane

Return type

Plane

offset(amount: float) → Plane

Move the Plane by amount in the direction of z_dir

property origin: Vector

Get the Plane origin

reverse() → Plane

Reverse z direction of plane

rotated(rotation: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]] = (0, 0, 0), ordering: Optional[Union[Extrinsic, Intrinsic]] = None) → Plane

Returns a copy of this plane, rotated about the specified axes

Since the z axis is always normal the plane, rotating around Z will always produce a plane that is parallel to this one.

The origin of the workplane is unaffected by the rotation.

Rotations are done in order x, y, z. If you need a different order, manually chain together multiple rotate() commands.

Parameters

• rotation (VectorLike, optional) – (xDegrees, yDegrees, zDegrees). Defaults to (0, 0, 0).

• ordering (Union[Intrinsic, Extrinsic], optional) – order of rotations in Intrinsic or Extrinsic rotation mode, defaults to Intrinsic.XYZ

Returns

a copy of this plane rotated as requested.

Return type

Plane

shift_origin(locator: Union[Axis, VectorLike, 'Vertex']) → Plane

shift plane origin

Creates a new plane with the origin moved within the plane to the point of intersection of the axis or at the given Vertex. The plane’s x_dir and z_dir are unchanged.

Parameters

locator (Union[Axis, VectorLike, Vertex]) – Either Axis that intersects the new plane origin or Vertex within Plane.

Raises

• ValueError – Vertex isn’t within plane

• ValueError – Point isn’t within plane

• ValueError – Axis doesn’t intersect plane

Returns

plane with new origin

Return type

Plane

to_gp_ax2() → gp_Ax2

Return gp_Ax2 version of the plane

to_local_coords(obj: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float], Any, BoundBox])

Reposition the object relative to this plane

Parameters

• obj – Union[VectorLike, Shape, BoundBox] an object to reposition. Note that

• classes. (type Any refers to all topological) –

Returns

an object of the same type, but repositioned to local coordinates

class Rotation(*args, **kwargs)

Subclass of Location used only for object rotation

Variables

• X (float) – rotation in degrees about X axis

• Y (float) – rotation in degrees about Y axis

• Z (float) – rotation in degrees about Z axis

• Intrinsic.XYZ (optionally specify rotation ordering with Intrinsic or Extrinsic enums, defaults to) –

class Vector(*args, **kwargs)

Create a 3-dimensional vector

Parameters

• x (float) – x component

• y (float) – y component

• z (float) – z component

• vec (Union[Vector, Sequence(float), gp_Vec, gp_Pnt, gp_Dir, gp_XYZ]) – vector representations

Note that if no z value is provided it’s assumed to be zero. If no values are provided the returned Vector has the value of 0, 0, 0.

Variables

wrapped (gp_Vec) – the OCP vector object

property X: float

Get x value

property Y: float

Get y value

property Z: float

Get z value

__abs__() → float

Vector length operator abs()

__add__(vec: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → Vector

Mathematical addition operator +

__copy__() → Vector

Return copy of self

__deepcopy__(_memo) → Vector

Return deepcopy of self

__eq__(other: Vector) → bool

Vectors equal operator ==

__mul__(scale: float) → Vector

Mathematical multiply operator *

__neg__() → Vector

Flip direction of vector operator -

__rmul__(scale: float) → Vector

Mathematical multiply operator *

__sub__(vec: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → Vector

Mathematical subtraction operator -

__truediv__(denom: float) → Vector

Mathematical division operator /

add(vec: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → Vector

Mathematical addition function

center() → Vector

Returns

The center of myself is myself. Provided so that vectors, vertices, and other shapes all support a common interface, when center() is requested for all objects on the stack.

cross(vec: Vector) → Vector

Mathematical cross function

distance_to_plane(plane: Plane) → float

Minimum unsigned distance between vector and plane

dot(vec: Vector) → float

Mathematical dot function

get_angle(vec: Vector) → float

Unsigned angle between vectors

get_signed_angle(vec: Vector, normal: Optional[Vector] = None) → float

Signed Angle Between Vectors

Return the signed angle in degrees between two vectors with the given normal based on this math: angle = atan2((Va × Vb) ⋅ Vn, Va ⋅ Vb)

Parameters

• v (Vector) – Second Vector

• normal (Vector, optional) – normal direction. Defaults to None.

Returns

Angle between vectors

Return type

float

property length: float

Vector length

multiply(scale: float) → Vector

Mathematical multiply function

normalized() → Vector

Scale to length of 1

project_to_line(line: Vector) → Vector

Returns a new vector equal to the projection of this Vector onto the line represented by Vector <line>

Parameters

line (Vector) – project to this line

Returns

Returns the projected vector.

Return type

Vector

project_to_plane(plane: Plane) → Vector

Vector is projected onto the plane provided as input.

Parameters

args – Plane object

Returns the projected vector.

plane: Plane:

Returns:

reverse() → Vector

Return a vector with the same magnitude but pointing in the opposite direction

rotate(axis: Axis, angle: float) → Vector

Rotate about axis

Rotate about the given Axis by an angle in degrees

Parameters

• axis (Axis) – Axis of rotation

• angle (float) – angle in degrees

Returns

rotated vector

Return type

Vector

signed_distance_from_plane(plane: Plane) → float

Signed distance from plane to point vector.

sub(vec: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → Vector

Mathematical subtraction function

to_dir() → gp_Dir

Convert to OCCT gp_Dir object

to_pnt() → gp_Pnt

Convert to OCCT gp_Pnt object

to_tuple() → tuple[float, float, float]

Return tuple equivalent

transform(affine_transform: Matrix) → Vector

Apply affine transformation

property wrapped: gp_Vec

OCCT object

Topological Objects

The topological object classes defined by build123d are defined below.

Note that the Mixin1D and Mixin3D classes add supplementary functionality specific to 1D (Edge and Wire) and 3D (Compound and ~topology.Solid) objects respectively. Note that a Compound may be contain only 1D, 2D (Face) or 3D objects.

class Compound(obj: TopoDS_Shape, label: str = '', color: Color = None, material: str = '', joints: dict[str, Joint] = None, parent: Compound = None, children: Iterable[Shape] = None)

class Compound(shapes: Iterable[Shape], label: str = '', color: Color = None, material: str = '', joints: dict[str, Joint] = None, parent: Compound = None, children: Iterable[Shape] = None)

A Compound in build123d is a topological entity representing a collection of geometric shapes grouped together within a single structure. It serves as a container for organizing diverse shapes like edges, faces, or solids. This hierarchical arrangement facilitates the construction of complex models by combining simpler shapes. Compound plays a pivotal role in managing the composition and structure of intricate 3D models in computer-aided design (CAD) applications, allowing engineers and designers to work with assemblies of shapes as unified entities for efficient modeling and analysis.

center(center_of: CenterOf = CenterOf.MASS) → Vector

Return center of object

Find center of object

Parameters

center_of (CenterOf, optional) – center option. Defaults to CenterOf.MASS.

Raises

• ValueError – Center of GEOMETRY is not supported for this object

• NotImplementedError – Unable to calculate center of mass of this object

Returns

center

Return type

Vector

cut(*to_cut: Shape) → Compound

Remove a shape from another one

Parameters

*to_cut – Shape:

Returns:

do_children_intersect(include_parent: bool = False, tolerance: float = 1e-05) → tuple[bool, tuple[Shape, Shape], float]

Do Children Intersect

Determine if any of the child objects within a Compound/assembly intersect by intersecting each of the shapes with each other and checking for a common volume.

Parameters

• include_parent (bool, optional) – check parent for intersections. Defaults to False.

• tolerance (float, optional) – maximum allowable volume difference. Defaults to 1e-5.

Returns

do the object intersect, intersecting objects, volume of intersection

Return type

tuple[bool, tuple[Shape, Shape], float]

fuse(*to_fuse: Shape, glue: bool = False, tol: Optional[float] = None) → Compound

Fuse shapes together

Parameters

• *to_fuse – Shape:

• glue – bool: (Default value = False)

• tol – float: (Default value = None)

Returns:

get_type(obj_type: Union[Type[Edge], Type[Face], Type[Shell], Type[Solid], Type[Wire]]) → list[Union[Edge, Face, Shell, Solid, Wire]]

Extract the objects of the given type from a Compound. Note that this isn’t the same as Faces() etc. which will extract Faces from Solids.

Parameters

obj_type (Union[Edge, Face, Solid]) – Object types to extract

Returns

Extracted objects

Return type

list[Union[Edge, Face, Solid]]

intersect(*to_intersect: Shape) → Compound

Construct shape intersection

Parameters

*to_intersect – Shape:

Returns:

classmethod make_compound(shapes: Iterable[Shape]) → Compound

Create a compound out of a list of shapes :param shapes: Iterable[Shape]:

Returns:

classmethod make_text(txt: str, font_size: float, font: str = 'Arial', font_path: ~typing.Optional[str] = None, font_style: ~build123d.build_enums.FontStyle = FontStyle.REGULAR, align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>), position_on_path: float = 0.0, text_path: ~typing.Optional[~typing.Union[~topology.Edge, ~topology.Wire]] = None) → Compound

2D Text that optionally follows a path.

The text that is created can be combined as with other sketch features by specifying a mode or rotated by the given angle. In addition, edges have been previously created with arc or segment, the text will follow the path defined by these edges. The start parameter can be used to shift the text along the path to achieve precise positioning.

Parameters

• txt – text to be rendered

• font_size – size of the font in model units

• font – font name

• font_path – path to font file

• font_style – text style. Defaults to FontStyle.REGULAR.

• align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER).

• position_on_path – the relative location on path to position the text, between 0.0 and 1.0. Defaults to 0.0.

• text_path – a path for the text to follows. Defaults to None - linear text.

Returns

a Compound object containing multiple Faces representing the text

Examples:

fox = Compound.make_text(
    txt="The quick brown fox jumped over the lazy dog",
    font_size=10,
    position_on_path=0.1,
    text_path=jump_edge,
)

classmethod make_triad(axes_scale: float) → Compound

The coordinate system triad (X, Y, Z axes)

property volume: float

volume - the volume of this Compound

class Edge(obj: Optional[TopoDS_Shape] = None, label: str = '', color: Optional[Color] = None, parent: Optional[Compound] = None)

An Edge in build123d is a fundamental element in the topological data structure representing a one-dimensional geometric entity within a 3D model. It encapsulates information about a curve, which could be a line, arc, or other parametrically defined shape. Edge is crucial in for precise modeling and manipulation of curves, facilitating operations like filleting, chamfering, and Boolean operations. It serves as a building block for constructing complex structures, such as wires and faces.

property arc_center: Vector

center of an underlying circle or ellipse geometry.

close() → Union[Edge, Wire]

Close an Edge

distribute_locations(count: int, start: float = 0.0, stop: float = 1.0, positions_only: bool = False) → list[build123d.geometry.Location]

Distribute Locations

Distribute locations along edge or wire.

Parameters

• self – Union[Wire:Edge]:

• count (int) – Number of locations to generate

• start (float) – position along Edge|Wire to start. Defaults to 0.0.

• stop (float) – position along Edge|Wire to end. Defaults to 1.0.

• positions_only (bool) – only generate position not orientation. Defaults to False.

Returns

locations distributed along Edge|Wire

Return type

list[Location]

Raises

ValueError – count must be two or greater

find_tangent(angle: float) → list[float]

Find the parameter values of self where the tangent is equal to angle.

Parameters

angle (float) – target angle in degrees

Returns

u values between 0.0 and 1.0

Return type

list[float]

intersections(edge: Optional[Union[Axis, Edge]] = None, tolerance: float = 1e-06) → ShapeList[Vector]

Determine the points where a 2D edge crosses itself or another 2D edge

Parameters

• edge (Union[Axis, Edge]) – curve to compare with

• tolerance (float, optional) – the precision of computing the intersection points. Defaults to TOLERANCE.

Returns

list of intersection points

Return type

ShapeList[Vector]

classmethod make_bezier(*cntl_pnts: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], weights: Optional[list[float]] = None) → Edge

Create a rational (with weights) or non-rational bezier curve. The first and last control points represent the start and end of the curve respectively. If weights are provided, there must be one provided for each control point.

Parameters

• cntl_pnts (sequence[VectorLike]) – points defining the curve

• weights (list[float], optional) – control point weights list. Defaults to None.

Raises

• ValueError – Too few control points

• ValueError – Too many control points

• ValueError – A weight is required for each control point

Returns

bezier curve

Return type

Edge

classmethod make_circle(radius: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00)), start_angle: float = 360.0, end_angle: float = 360, angular_direction: AngularDirection = AngularDirection.COUNTER_CLOCKWISE) → Edge

make circle

Create a circle centered on the origin of plane

Parameters

• radius (float) – circle radius

• plane (Plane, optional) – base plane. Defaults to Plane.XY.

• start_angle (float, optional) – start of arc angle. Defaults to 360.0.

• end_angle (float, optional) – end of arc angle. Defaults to 360.

• angular_direction (AngularDirection, optional) – arc direction. Defaults to AngularDirection.COUNTER_CLOCKWISE.

Returns

full or partial circle

Return type

Edge

classmethod make_ellipse(x_radius: float, y_radius: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00)), start_angle: float = 360.0, end_angle: float = 360.0, angular_direction: AngularDirection = AngularDirection.COUNTER_CLOCKWISE) → Edge

make ellipse

Makes an ellipse centered at the origin of plane.

Parameters

• x_radius (float) – x radius of the ellipse (along the x-axis of plane)

• y_radius (float) – y radius of the ellipse (along the y-axis of plane)

• plane (Plane, optional) – base plane. Defaults to Plane.XY.

• start_angle (float, optional) – Defaults to 360.0.

• end_angle (float, optional) – Defaults to 360.0.

• angular_direction (AngularDirection, optional) – arc direction. Defaults to AngularDirection.COUNTER_CLOCKWISE.

Returns

full or partial ellipse

Return type

Edge

classmethod make_helix(pitch: float, height: float, radius: float, center: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]] = (0, 0, 0), normal: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]] = (0, 0, 1), angle: float = 0.0, lefthand: bool = False) → Wire

Make a helix with a given pitch, height and radius. By default a cylindrical surface is used to create the helix. If the :angle: is set (the apex given in degree) a conical surface is used instead.

Parameters

• pitch (float) – distance per revolution along normal

• height (float) – total height

• radius (float) –

• center (VectorLike, optional) – Defaults to (0, 0, 0).

• normal (VectorLike, optional) – Defaults to (0, 0, 1).

• angle (float, optional) – conical angle. Defaults to 0.0.

• lefthand (bool, optional) – Defaults to False.

Returns

helix

Return type

Wire

classmethod make_line(point1: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], point2: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → Edge

Create a line between two points

Parameters

• point1 – VectorLike: that represents the first point

• point2 – VectorLike: that represents the second point

Returns

A linear edge between the two provided points

classmethod make_mid_way(first: Edge, second: Edge, middle: float = 0.5) → Edge

make line between edges

Create a new linear Edge between the two provided Edges. If the Edges are parallel but in the opposite directions one Edge is flipped such that the mid way Edge isn’t truncated.

Parameters

• first (Edge) – first reference Edge

• second (Edge) – second reference Edge

• middle (float, optional) – factional distance between Edges. Defaults to 0.5.

Returns

linear Edge between two Edges

Return type

Edge

classmethod make_spline(points: list[Union[build123d.geometry.Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]], tangents: Optional[list[Union[build123d.geometry.Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]] = None, periodic: bool = False, parameters: Optional[list[float]] = None, scale: bool = True, tol: float = 1e-06) → Edge

Spline

Interpolate a spline through the provided points.

Parameters

• points (list[VectorLike]) – the points defining the spline

• tangents (list[VectorLike], optional) – start and finish tangent. Defaults to None.

• periodic (bool, optional) – creation of periodic curves. Defaults to False.

• parameters (list[float], optional) – the value of the parameter at each interpolation point. (The interpolated curve is represented as a vector-valued function of a scalar parameter.) If periodic == True, then len(parameters) must be len(interpolation points) + 1, otherwise len(parameters) must be equal to len(interpolation points). Defaults to None.

• scale (bool, optional) – whether to scale the specified tangent vectors before interpolating. Each tangent is scaled, so it’s length is equal to the derivative of the Lagrange interpolated curve. I.e., set this to True, if you want to use only the direction of the tangent vectors specified by tangents , but not their magnitude. Defaults to True.

• tol (float, optional) – tolerance of the algorithm (consult OCC documentation). Used to check that the specified points are not too close to each other, and that tangent vectors are not too short. (In either case interpolation may fail.). Defaults to 1e-6.

Raises

• ValueError – Parameter for each interpolation point

• ValueError – Tangent for each interpolation point

• ValueError – B-spline interpolation failed

Returns

the spline

Return type

Edge

classmethod make_spline_approx(points: list[Union[build123d.geometry.Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]], tol: float = 0.001, smoothing: Optional[Tuple[float, float, float]] = None, min_deg: int = 1, max_deg: int = 6) → Edge

Approximate a spline through the provided points.

Parameters

• points (list[Vector]) –

• tol (float, optional) – tolerance of the algorithm. Defaults to 1e-3.

• smoothing (Tuple[float, float, float], optional) – optional tuple of 3 weights use for variational smoothing. Defaults to None.

• min_deg (int, optional) – minimum spline degree. Enforced only when smoothing is None. Defaults to 1.

• max_deg (int, optional) – maximum spline degree. Defaults to 6.

Raises

ValueError – B-spline approximation failed

Returns

spline

Return type

Edge

classmethod make_tangent_arc(start: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], tangent: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], end: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → Edge

Tangent Arc

Makes a tangent arc from point start, in the direction of tangent and ends at end.

Parameters

• start (VectorLike) – start point

• tangent (VectorLike) – start tangent

• end (VectorLike) – end point

Returns

circular arc

Return type

Edge

classmethod make_three_point_arc(point1: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], point2: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], point3: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → Edge

Three Point Arc

Makes a three point arc through the provided points

Parameters

• point1 (VectorLike) – start point

• point2 (VectorLike) – middle point

• point3 (VectorLike) – end point

Returns

a circular arc through the three points

Return type

Edge

param_at_point(point: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → float

Parameter at point of Edge

project_to_shape(target_object: Shape, direction: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None, center: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None) → list[Edge]

Project Edge

Project an Edge onto a Shape generating new wires on the surfaces of the object one and only one of direction or center must be provided. Note that one or more wires may be generated depending on the topology of the target object and location/direction of projection.

To avoid flipping the normal of a face built with the projected wire the orientation of the output wires are forced to be the same as self.

Parameters

• target_object – Object to project onto

• direction – Parallel projection direction. Defaults to None.

• center – Conical center of projection. Defaults to None.

• target_object – Shape:

• direction – VectorLike: (Default value = None)

• center – VectorLike: (Default value = None)

Returns

Projected Edge(s)

Raises

ValueError – Only one of direction or center must be provided

reversed() → Edge

Return a copy of self with the opposite orientation

to_axis() → Axis

Translate a linear Edge to an Axis

to_wire() → Wire

Edge as Wire

trim(start: float, end: float) → Edge

Create a new edge by keeping only the section between start and end.

Parameters

• start (float) – 0.0 <= start < 1.0

• end (float) – 0.0 < end <= 1.0

Raises

ValueError – start >= end

Returns

trimmed edge

Return type

Edge

class Face(obj: TopoDS_Shape, label: str = '', color: Color = None, parent: Compound = None)

class Face(outer_wire: Wire, inner_wires: Iterable[Wire] = None, label: str = '', color: Color = None, parent: Compound = None)

A Face in build123d represents a 3D bounded surface within the topological data structure. It encapsulates geometric information, defining a face of a 3D shape. These faces are integral components of complex structures, such as solids and shells. Face enables precise modeling and manipulation of surfaces, supporting operations like trimming, filleting, and Boolean operations.

__neg__() → Face

Reverse normal operator -

center(center_of=CenterOf.GEOMETRY) → Vector

Center of Face

Return the center based on center_of

Parameters

center_of (CenterOf, optional) – centering option. Defaults to CenterOf.GEOMETRY.

Returns

center

Return type

Vector

property center_location: Location

Location at the center of face

chamfer_2d(distance: float, distance2: float, vertices: Iterable[Vertex], edge: Optional[Edge] = None) → Face

Apply 2D chamfer to a face

Parameters

• distance (float) – chamfer length

• distance2 (float) – chamfer length

• vertices (Iterable[Vertex]) – vertices to chamfer

• edge (Edge) – identifies the side where length is measured. The vertices must be part of the edge

Raises

• ValueError – Cannot chamfer at this location

• ValueError – One or more vertices are not part of edge

Returns

face with a chamfered corner(s)

Return type

Face

fillet_2d(radius: float, vertices: Iterable[Vertex]) → Face

Apply 2D fillet to a face

Parameters

• radius – float:

• vertices – Iterable[Vertex]:

Returns:

property geometry: str

geometry of planar face

inner_wires() → ShapeList[Wire]

Extract the inner or hole wires from this Face

is_coplanar(plane: Plane) → bool

Is this planar face coplanar with the provided plane

is_inside(point: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], tolerance: float = 1e-06) → bool

Point inside Face

Returns whether or not the point is inside a Face within the specified tolerance. Points on the edge of the Face are considered inside.

Parameters

• point (VectorLike) – tuple or Vector representing 3D point to be tested

• tolerance (float) – tolerance for inside determination. Defaults to 1.0e-6.

• point – VectorLike:

• tolerance – float: (Default value = 1.0e-6)

Returns

indicating whether or not point is within Face

Return type

bool

property length: float

length of planar face

classmethod make_bezier_surface(points: list[list[Union[build123d.geometry.Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]], weights: Optional[list[list[float]]] = None) → Face

Construct a Bézier surface from the provided 2d array of points.

Parameters

• points (list[list[VectorLike]]) – a 2D list of control points

• weights (list[list[float]], optional) – control point weights. Defaults to None.

Raises

• ValueError – Too few control points

• ValueError – Too many control points

• ValueError – A weight is required for each control point

Returns

a potentially non-planar face

Return type

Face

classmethod make_from_wires(outer_wire: Wire, inner_wires: Optional[Iterable[Wire]] = None) → Face

Makes a planar face from one or more wires

Parameters

• outer_wire (Wire) – closed perimeter wire

• inner_wires (list[Wire], optional) – holes. Defaults to None.

Raises

• ValueError – outer wire not closed

• ValueError – wires not planar

• ValueError – inner wire not closed

• ValueError – internal error

Returns

planar face potentially with holes

Return type

Face

make_holes(interior_wires: list[Wire]) → Face

Make Holes in Face

Create holes in the Face ‘self’ from interior_wires which must be entirely interior. Note that making holes in faces is more efficient than using boolean operations with solid object. Also note that OCCT core may fail unless the orientation of the wire is correct - use Wire(forward_wire.wrapped.Reversed()) to reverse a wire.

Example

For example, make a series of slots on the curved walls of a cylinder.

Parameters

• interior_wires – a list of hole outline wires

• interior_wires – list[Wire]:

Returns

‘self’ with holes

Return type

Face

Raises

• RuntimeError – adding interior hole in non-planar face with provided interior_wires

• RuntimeError – resulting face is not valid

classmethod make_plane(plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00))) → Face

Create a unlimited size Face aligned with plane

classmethod make_rect(width: float, height: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00))) → Face

Make a Rectangle centered on center with the given normal

Parameters

• width (float, optional) – width (local x).

• height (float, optional) – height (local y).

• plane (Plane, optional) – base plane. Defaults to Plane.XY.

Returns

The centered rectangle

Return type

Face

classmethod make_surface(exterior: Union[Wire, Iterable[Edge]], surface_points: Optional[Iterable[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]] = None, interior_wires: Optional[Iterable[Wire]] = None) → Face

Create Non-Planar Face

Create a potentially non-planar face bounded by exterior (wire or edges), optionally refined by surface_points with optional holes defined by interior_wires.

Parameters

• exterior (Union[Wire, list[Edge]]) – Perimeter of face

• surface_points (list[VectorLike], optional) – Points on the surface that refine the shape. Defaults to None.

• interior_wires (list[Wire], optional) – Hole(s) in the face. Defaults to None.

Raises

• RuntimeError – Internal error building face

• RuntimeError – Error building non-planar face with provided surface_points

• RuntimeError – Error adding interior hole

• RuntimeError – Generated face is invalid

Returns

Potentially non-planar face

Return type

Face

classmethod make_surface_from_array_of_points(points: list[list[Union[build123d.geometry.Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]], tol: float = 0.01, smoothing: Optional[Tuple[float, float, float]] = None, min_deg: int = 1, max_deg: int = 3) → Face

Approximate a spline surface through the provided 2d array of points.

Parameters

• points (list[list[VectorLike]]) – a 2D list of points

• tol (float, optional) – tolerance of the algorithm. Defaults to 1e-2.

• smoothing (Tuple[float, float, float], optional) – optional tuple of 3 weights use for variational smoothing. Defaults to None.

• min_deg (int, optional) – minimum spline degree. Enforced only when smoothing is None. Defaults to 1.

• max_deg (int, optional) – maximum spline degree. Defaults to 3.

Raises

ValueError – B-spline approximation failed

Returns

a potentially non-planar face defined by points

Return type

Face

classmethod make_surface_from_curves(edge1: Edge, edge2: Edge) → Face

classmethod make_surface_from_curves(wire1: Wire, wire2: Wire) → Face

make_surface_from_curves

Create a ruled surface out of two edges or two wires. If wires are used then these must have the same number of edges.

Parameters

• curve1 (Union[Edge,Wire]) – side of surface

• curve2 (Union[Edge,Wire]) – opposite side of surface

Returns

potentially non planar surface

Return type

Face

normal_at(surface_point: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]] = None) → Vector

normal_at(u: float, v: float) → Vector

normal_at

Computes the normal vector at the desired location on the face.

Parameters

surface_point (VectorLike, optional) – a point that lies on the surface where the normal. Defaults to None.

Returns

surface normal direction

Return type

Vector

offset(amount: float) → Face

Return a copy of self moved along the normal by amount

outer_wire() → Wire

Extract the perimeter wire from this Face

position_at(u: float, v: float) → Vector

Computes a point on the Face given u, v coordinates.

Parameters

• u (float) – the horizontal coordinate in the parameter space of the Face, between 0.0 and 1.0

• v (float) – the vertical coordinate in the parameter space of the Face, between 0.0 and 1.0

Returns

point on Face

Return type

Vector

project_to_shape(target_object: Shape, direction: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], taper: float = 0) → ShapeList[Face]

Project Face to target Object

Project a Face onto a Shape generating new Face(s) on the surfaces of the object.

A projection with no taper is illustrated below:

Note that an array of faces is returned as the projection might result in faces on the “front” and “back” of the object (or even more if there are intermediate surfaces in the projection path). faces “behind” the projection are not returned.

Parameters

• target_object (Shape) – Object to project onto

• direction (VectorLike) – projection direction

• taper (float, optional) – taper angle. Defaults to 0.

Returns

Face(s) projected on target object ordered by distance

Return type

ShapeList[Face]

project_to_shape_alt(target_object: Shape, direction: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → Union[None, Face, Compound]

Return the Faces contained within the first projection of self onto the target.

Parameters

• target_object (Shape) – Object to project onto

• direction (VectorLike) – projection direction

Returns

projection

Return type

Union[None, Face, Compound]

classmethod sew_faces(faces: Iterable[Face]) → list[ShapeList[Face]]

sew faces

Group contiguous faces and return them in a list of ShapeList

Parameters

faces (Iterable[Face]) – Faces to sew together

Raises

RuntimeError – OCCT SewedShape generated unexpected output

Returns

grouped contiguous faces

Return type

list[ShapeList[Face]]

classmethod sweep(profile: Union[Edge, Wire], path: Union[Edge, Wire], transition=Transition.RIGHT) → Face

Sweep a 1D profile along a 1D path

Parameters

• profile (Union[Edge, Wire]) – the object to sweep

• path (Union[Wire, Edge]) – the path to follow when sweeping

• transition (Transition, optional) – handling of profile orientation at C1 path discontinuities. Defaults to Transition.RIGHT.

Returns

resulting face, may be non-planar

Return type

Face

thicken(depth: float, normal_override: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None) → Solid

Thicken Face

Create a solid from a potentially non planar face by thickening along the normals.

Non-planar faces are thickened both towards and away from the center of the sphere.

Parameters

• depth (float) – Amount to thicken face(s), can be positive or negative.

• normal_override (Vector, optional) – The normal_override vector can be used to indicate which way is ‘up’, potentially flipping the face normal direction such that many faces with different normals all go in the same direction (direction need only be +/- 90 degrees from the face normal). Defaults to None.

Raises

RuntimeError – Opencascade internal failures

Returns

The resulting Solid object

Return type

Solid

property volume: float

volume - the volume of this Face, which is always zero

property width: float

width of planar face

wire() → Wire

Return the outerwire, generate a warning if inner_wires present

class Mixin1D

Methods to add to the Edge and Wire classes

__matmul__(position: float) → Vector

Position on wire operator @

__mod__(position: float) → Vector

Tangent on wire operator %

center(center_of: CenterOf = CenterOf.GEOMETRY) → Vector

Center of object

Return the center based on center_of

Parameters

center_of (CenterOf, optional) – centering option. Defaults to CenterOf.GEOMETRY.

Returns

center

Return type

Vector

common_plane(*lines: Union[Edge, Wire]) → Union[None, Plane]

Find the plane containing all the edges/wires (including self). If there is no common plane return None. If the edges are coaxial, select one of the infinite number of valid planes.

Parameters

lines (sequence of Union[Edge,Wire]) – edges in common with self

Returns

Either the common plane or None

Return type

Union[None, Plane]

end_point() → Vector

The end point of this edge.

Note that circles may have identical start and end points.

property is_closed: bool

Are the start and end points equal?

property is_forward: bool

Does the Edge/Wire loop forward or reverse

property length: float

Edge or Wire length

location_at(distance: float, position_mode: PositionMode = PositionMode.PARAMETER, frame_method: FrameMethod = FrameMethod.FRENET, planar: bool = False) → Location

Locations along curve

Generate a location along the underlying curve.

Parameters

• distance (float) – distance or parameter value

• position_mode (PositionMode, optional) – position calculation mode. Defaults to PositionMode.PARAMETER.

• frame_method (FrameMethod, optional) – moving frame calculation method. Defaults to FrameMethod.FRENET.

• planar (bool, optional) – planar mode. Defaults to False.

Returns

A Location object representing local coordinate system

at the specified distance.

Return type

Location

locations(distances: Iterable[float], position_mode: PositionMode = PositionMode.PARAMETER, frame_method: FrameMethod = FrameMethod.FRENET, planar: bool = False) → list[build123d.geometry.Location]

Locations along curve

Generate location along the curve

Parameters

• distances (Iterable[float]) – distance or parameter values

• position_mode (PositionMode, optional) – position calculation mode. Defaults to PositionMode.PARAMETER.

• frame_method (FrameMethod, optional) – moving frame calculation method. Defaults to FrameMethod.FRENET.

• planar (bool, optional) – planar mode. Defaults to False.

Returns

A list of Location objects representing local coordinate

systems at the specified distances.

Return type

list[Location]

normal() → Vector

Calculate the normal Vector. Only possible for planar curves.

Returns

normal vector

Args:

Returns:

offset_2d(distance: float, kind: Kind = Kind.ARC, side: Side = Side.BOTH, closed: bool = True) → Union[Edge, Wire]

2d Offset

Offsets a planar edge/wire

Parameters

• distance (float) – distance from edge/wire to offset

• kind (Kind, optional) – offset corner transition. Defaults to Kind.ARC.

• side (Side, optional) – side to place offset. Defaults to Side.BOTH.

• closed (bool, optional) – if Side!=BOTH, close the LEFT or RIGHT offset. Defaults to True.

Raises

• RuntimeError – Multiple Wires generated

• RuntimeError – Unexpected result type

Returns

offset wire

Return type

Wire

param_at(distance: float) → float

Parameter along a curve

Compute parameter value at the specified normalized distance.

Parameters

d (float) – normalized distance (0.0 >= d >= 1.0)

Returns

parameter value

Return type

float

perpendicular_line(length: float, u_value: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00))) → Edge

Create a line on the given plane perpendicular to and centered on beginning of self

Parameters

• length (float) – line length

• u_value (float) – position along line between 0.0 and 1.0

• plane (Plane, optional) – plane containing perpendicular line. Defaults to Plane.XY.

Returns

perpendicular line

Return type

Edge

position_at(distance: float, position_mode: PositionMode = PositionMode.PARAMETER) → Vector

Position At

Generate a position along the underlying curve.

Parameters

• distance (float) – distance or parameter value

• position_mode (PositionMode, optional) – position calculation mode. Defaults to PositionMode.PARAMETER.

Returns

position on the underlying curve

Return type

Vector

positions(distances: Iterable[float], position_mode: PositionMode = PositionMode.PARAMETER) → list[build123d.geometry.Vector]

Positions along curve

Generate positions along the underlying curve

Parameters

• distances (Iterable[float]) – distance or parameter values

• position_mode (PositionMode, optional) – position calculation mode. Defaults to PositionMode.PARAMETER.

Returns

positions along curve

Return type

list[Vector]

project(face: Face, direction: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], closest: bool = True) → Union[Mixin1D, list[Mixin1D]]

Project onto a face along the specified direction

Parameters

• face – Face:

• direction – VectorLike:

• closest – bool: (Default value = True)

Returns:

property radius: float

Calculate the radius.

Note that when applied to a Wire, the radius is simply the radius of the first edge.

Args:

Returns

radius

Raises

ValueError – if kernel can not reduce the shape to a circular edge

start_point() → Vector

The start point of this edge

Note that circles may have identical start and end points.

tangent_angle_at(location_param: float = 0.5, position_mode: PositionMode = PositionMode.PARAMETER, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00))) → float

Compute the tangent angle at the specified location

Parameters

• location_param (float, optional) – distance or parameter value. Defaults to 0.5.

• position_mode (PositionMode, optional) – position calculation mode. Defaults to PositionMode.PARAMETER.

• plane (Plane, optional) – plane line was constructed on. Defaults to Plane.XY.

Returns

angle in degrees between 0 and 360

Return type

float

tangent_at(position: Union[float, Vector, tuple[float, float], tuple[float, float, float], Iterable[float]] = 0.5, position_mode: PositionMode = PositionMode.PARAMETER) → Vector

Find the tangent at a given position on the 1D shape where the position is either a float (or int) parameter or a point that lies on the shape.

Parameters

• position (Union[float, VectorLike]) – distance, parameter value, or point on shape. Defaults to 0.5.

• position_mode (PositionMode, optional) – position calculation mode. Defaults to PositionMode.PARAMETER.

Raises

ValueError – invalid position

Returns

tangent value

Return type

Vector

property volume: float

volume - the volume of this Edge or Wire, which is always zero

class Mixin3D

Additional methods to add to 3D Shape classes

center(center_of: CenterOf = CenterOf.MASS) → Vector

Return center of object

Find center of object

Parameters

center_of (CenterOf, optional) – center option. Defaults to CenterOf.MASS.

Raises

• ValueError – Center of GEOMETRY is not supported for this object

• NotImplementedError – Unable to calculate center of mass of this object

Returns

center

Return type

Vector

chamfer(length: float, length2: Optional[float], edge_list: Iterable[Edge], face: Optional[Face] = None) → Self

Chamfer

Chamfers the specified edges of this solid.

Parameters

• length (float) – length > 0, the length (length) of the chamfer

• length2 (Optional[float]) – length2 > 0, optional parameter for asymmetrical chamfer. Should be None if not required.

• edge_list (Iterable[Edge]) – a list of Edge objects, which must belong to this solid

• face (Face) – identifies the side where length is measured. The edge(s) must be part of the face

Returns

Chamfered solid

Return type

Self

dprism(basis: Optional[Face], bounds: list[Union[Face, Wire]], depth: Optional[float] = None, taper: float = 0, up_to_face: Optional[Face] = None, thru_all: bool = True, additive: bool = True) → Solid

Make a prismatic feature (additive or subtractive)

Parameters

• basis (Optional[Face]) – face to perform the operation on

• bounds (list[Union[Face,Wire]]) – list of profiles

• depth (float, optional) – depth of the cut or extrusion. Defaults to None.

• taper (float, optional) – in degrees. Defaults to 0.

• up_to_face (Face, optional) – a face to extrude until. Defaults to None.

• thru_all (bool, optional) – cut thru_all. Defaults to True.

• additive (bool, optional) – Defaults to True.

Returns

prismatic feature

Return type

Solid

fillet(radius: float, edge_list: Iterable[Edge]) → Self

Fillet

Fillets the specified edges of this solid.

Parameters

• radius (float) – float > 0, the radius of the fillet

• edge_list (Iterable[Edge]) – a list of Edge objects, which must belong to this solid

Returns

Filleted solid

Return type

Any

hollow(faces: Optional[Iterable[Face]], thickness: float, tolerance: float = 0.0001, kind: Kind = Kind.ARC) → Solid

Hollow

Return the outer shelled solid of self.

Parameters

• faces (Optional[Iterable[Face]]) – faces to be removed,

• list. (which must be part of the solid. Can be an empty) –

• thickness (float) – shell thickness - positive shells outwards, negative shells inwards.

• tolerance (float, optional) – modelling tolerance of the method. Defaults to 0.0001.

• kind (Kind, optional) – intersection type. Defaults to Kind.ARC.

Raises

ValueError – Kind.TANGENT not supported

Returns

A hollow solid.

Return type

Solid

is_inside(point: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], tolerance: float = 1e-06) → bool

Returns whether or not the point is inside a solid or compound object within the specified tolerance.

Parameters

• point – tuple or Vector representing 3D point to be tested

• tolerance – tolerance for inside determination, default=1.0e-6

• point – VectorLike:

• tolerance – float: (Default value = 1.0e-6)

Returns

bool indicating whether or not point is within solid

max_fillet(edge_list: Iterable[Edge], tolerance=0.1, max_iterations: int = 10) → float

Find Maximum Fillet Size

Find the largest fillet radius for the given Shape and edges with a recursive binary search.

Example

max_fillet_radius = my_shape.max_fillet(shape_edges) max_fillet_radius = my_shape.max_fillet(shape_edges, tolerance=0.5, max_iterations=8)

Parameters

• edge_list (Iterable[Edge]) – a sequence of Edge objects, which must belong to this solid

• tolerance (float, optional) – maximum error from actual value. Defaults to 0.1.

• max_iterations (int, optional) – maximum number of recursive iterations. Defaults to 10.

Raises

• RuntimeError – failed to find the max value

• ValueError – the provided Shape is invalid

Returns

maximum fillet radius

Return type

float

offset_3d(openings: Optional[Iterable[Face]], thickness: float, tolerance: float = 0.0001, kind: Kind = Kind.ARC) → Solid

Shell

Make an offset solid of self.

Parameters

• openings (Optional[Iterable[Face]]) – faces to be removed, which must be part of the solid. Can be an empty list.

• thickness (float) – offset amount - positive offset outwards, negative inwards

• tolerance (float, optional) – modelling tolerance of the method. Defaults to 0.0001.

• kind (Kind, optional) – intersection type. Defaults to Kind.ARC.

Raises

ValueError – Kind.TANGENT not supported

Returns

A shelled solid.

Return type

Solid

class Shape(obj: Optional[TopoDS_Shape] = None, label: str = '', color: Optional[Color] = None, parent: Optional[Compound] = None)

Base class for all CAD objects such as Edge, Face, Solid, etc.

Parameters

• obj (TopoDS_Shape, optional) – OCCT object. Defaults to None.

• label (str, optional) – Defaults to ‘’.

• color (Color, optional) – Defaults to None.

• parent (Compound, optional) – assembly parent. Defaults to None.

Variables

• wrapped (TopoDS_Shape) – the OCP object

• label (str) – user assigned label

• color (Color) – object color

• (dict[str (joints) – Joint]): dictionary of joints bound to this object (Solid only)

• children (Shape) – list of assembly children of this object (Compound only)

• topo_parent (Shape) – assembly parent of this object

__add__(other: Union[list[Shape], Shape]) → Self

fuse shape to self operator +

__and__(other: Shape) → Self

intersect shape with self operator &

__copy__() → Self

Return shallow copy or reference of self

Create an copy of this Shape that shares the underlying TopoDS_TShape.

Used when there is a need for many objects with the same CAD structure but at different Locations, etc. - for examples fasteners in a larger assembly. By sharing the TopoDS_TShape, the memory size of such assemblies can be greatly reduced.

Changes to the CAD structure of the base object will be reflected in all instances.

__deepcopy__(memo) → Self

Return deepcopy of self

__eq__(other) → bool

Are shapes same operator ==

__hash__() → int

Return has code

__rmul__(other)

right multiply for positioning operator *

__sub__(other: Shape) → Self

cut shape from self operator -

property area: float

area -the surface area of all faces in this Shape

bounding_box(tolerance: Optional[float] = None) → BoundBox

Create a bounding box for this Shape.

Parameters

tolerance (float, optional) – Defaults to None.

Returns

A box sized to contain this Shape

Return type

BoundBox

classmethod cast(obj: TopoDS_Shape, for_construction: bool = False) → Self

Returns the right type of wrapper, given a OCCT object

center() → Vector

All of the derived classes from Shape need a center method

clean() → Self

Remove internal edges

Returns

Original object with extraneous internal edges removed

Return type

Shape

closest_points(other: Union[Shape, Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → tuple[build123d.geometry.Vector, build123d.geometry.Vector]

Points on two shapes where the distance between them is minimal

property color: Union[None, Color]

Get the shape’s color. If it’s None, get the color of the nearest ancestor, assign it to this Shape and return this value.

static combined_center(objects: Iterable[Shape], center_of: CenterOf = CenterOf.MASS) → Vector

combined center

Calculates the center of a multiple objects.

Parameters

• objects (Iterable[Shape]) – list of objects

• center_of (CenterOf, optional) – centering option. Defaults to CenterOf.MASS.

Raises

ValueError – CenterOf.GEOMETRY not implemented

Returns

center of multiple objects

Return type

Vector

compound() → Compound

Return the Compound

compounds() → ShapeList[Compound]

compounds - all the compounds in this Shape

static compute_mass(obj: Shape) → float

Calculates the ‘mass’ of an object.

Parameters

• obj – Compute the mass of this object

• obj – Shape:

Returns:

copy() → Self

Here for backwards compatibility with cq-editor

cut(*to_cut: Shape) → Self

Remove the positional arguments from this Shape.

Parameters

*to_cut – Shape:

Returns:

distance(other: Shape) → float

Minimal distance between two shapes

Parameters

other – Shape:

Returns:

distance_to(other: Union[Shape, Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → float

Minimal distance between two shapes

distance_to_with_closest_points(other: Union[Shape, Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → tuple[float, build123d.geometry.Vector, build123d.geometry.Vector]

Minimal distance between two shapes and the points on each shape

distances(*others: Shape) → Iterator[float]

Minimal distances to between self and other shapes

Parameters

*others – Shape:

Returns:

edge() → Edge

Return the Edge

edges() → ShapeList[Edge]

edges - all the edges in this Shape

export_brep(file: Union[str, BytesIO]) → bool

Export this shape to a BREP file

Parameters

file – Union[str, BytesIO]:

Returns:

export_step(file_name: str, **kwargs) → IFSelect_ReturnStatus

Export this shape to a STEP file.

kwargs is used to provide optional keyword arguments to configure the exporter.

Parameters

• file_name (str) – Path and filename for writing.

• kwargs – used to provide optional keyword arguments to configure the exporter.

Returns

OCCT return status

Return type

IFSelect_ReturnStatus

export_stl(file_name: str, tolerance: float = 0.001, angular_tolerance: float = 0.1, ascii_format: bool = False) → bool

Export STL

Exports a shape to a specified STL file.

Parameters

• file_name (str) – The path and file name to write the STL output to.

• tolerance (float, optional) – A linear deflection setting which limits the distance between a curve and its tessellation. Setting this value too low will result in large meshes that can consume computing resources. Setting the value too high can result in meshes with a level of detail that is too low. The default is a good starting point for a range of cases. Defaults to 1e-3.

• angular_tolerance (float, optional) – Angular deflection setting which limits the angle between subsequent segments in a polyline. Defaults to 0.1.

• ascii_format (bool, optional) – Export the file as ASCII (True) or binary (False) STL format. Defaults to False (binary).

Returns

Success

Return type

bool

classmethod extrude(obj: Union[Vertex, Edge, Wire, Face, Shell], direction: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → Self

Extrude a Shape in the provided direction. * Vertices generate Edges * Edges generate Faces * Wires generate Shells * Faces generate Solids * Shells generate Compounds

Parameters

direction (VectorLike) – direction and magnitude of extrusion

Raises

• ValueError – Unsupported class

• RuntimeError – Generated invalid result

Returns

extruded shape

Return type

Union[Edge, Face, Shell, Solid, Compound]

face() → Face

Return the Face

faces() → ShapeList[Face]

faces - all the faces in this Shape

faces_intersected_by_axis(axis: Axis, tol: float = 0.0001) → ShapeList[Face]

Line Intersection

Computes the intersections between the provided axis and the faces of this Shape

Parameters

• axis (Axis) – Axis on which the intersection line rests

• tol (float, optional) – Intersection tolerance. Defaults to 1e-4.

Returns

A list of intersected faces sorted by distance from axis.position

Return type

list[Face]

find_intersection(axis: Axis) → list[tuple[build123d.geometry.Vector, build123d.geometry.Vector]]

Find point and normal at intersection

Return both the point(s) and normal(s) of the intersection of the axis and the shape

Parameters

axis (Axis) – axis defining the intersection line

Returns

Point and normal of intersection

Return type

list[tuple[Vector, Vector]]

fix() → Self

fix - try to fix shape if not valid

fuse(*to_fuse: Shape, glue: bool = False, tol: Optional[float] = None) → Self

Fuse a sequence of shapes into a single shape.

Parameters

• to_fuse (sequence Shape) – shapes to fuse

• glue (bool, optional) – performance improvement for some shapes. Defaults to False.

• tol (float, optional) – tolerance. Defaults to None.

Returns

fused shape

Return type

Shape

property geom_type: GeomType

Gets the underlying geometry type.

Args:

Returns:

hash_code() → int

Returns a hashed value denoting this shape. It is computed from the TShape and the Location. The Orientation is not used.

Args:

Returns:

intersect(*to_intersect: Union[Shape, Axis, Plane]) → Shape

Intersection of the arguments and this shape

Parameters

to_intersect (sequence of Union[Shape, Axis, Plane]) – Shape(s) to intersect with

Returns

Resulting object may be of a different class than self

Return type

Shape

is_equal(other: Shape) → bool

Returns True if two shapes are equal, i.e. if they share the same TShape with the same Locations and Orientations. Also see is_same().

Parameters

other – Shape:

Returns:

property is_manifold: bool

Check if each edge in the given Shape has exactly two faces associated with it (skipping degenerate edges). If so, the shape is manifold.

Returns

is the shape manifold or water tight

Return type

bool

is_null() → bool

Returns true if this shape is null. In other words, it references no underlying shape with the potential to be given a location and an orientation.

Args:

Returns:

is_same(other: Shape) → bool

Returns True if other and this shape are same, i.e. if they share the same TShape with the same Locations. Orientations may differ. Also see is_equal()

Parameters

other – Shape:

Returns:

is_valid() → bool

Returns True if no defect is detected on the shape S or any of its subshapes. See the OCCT docs on BRepCheck_Analyzer::IsValid for a full description of what is checked.

Args:

Returns:

locate(loc: Location) → Self

Apply a location in absolute sense to self

Parameters

loc – Location:

Returns:

located(loc: Location) → Self

Apply a location in absolute sense to a copy of self

Parameters

loc (Location) – new absolute location

Returns

copy of Shape at location

Return type

Shape

property location: Location

Get this Shape’s Location

mesh(tolerance: float, angular_tolerance: float = 0.1)

Generate triangulation if none exists.

Parameters

• tolerance – float:

• angular_tolerance – float: (Default value = 0.1)

Returns:

mirror(mirror_plane: Optional[Plane] = None) → Self

Applies a mirror transform to this Shape. Does not duplicate objects about the plane.

Parameters

mirror_plane (Plane) – The plane to mirror about. Defaults to Plane.XY

Returns

The mirrored shape

move(loc: Location) → Self

Apply a location in relative sense (i.e. update current location) to self

Parameters

loc – Location:

Returns:

moved(loc: Location) → Self

Apply a location in relative sense (i.e. update current location) to a copy of self

Parameters

loc (Location) – new location relative to current location

Returns

copy of Shape moved to relative location

Return type

Shape

property orientation: Vector

Get the orientation component of this Shape’s Location

property position: Vector

Get the position component of this Shape’s Location

project_faces(faces: Union[list[Face], Compound], path: Union[Wire, Edge], start: float = 0) → Compound

Projected Faces following the given path on Shape

Project by positioning each face of to the shape along the path and projecting onto the surface.

Note that projection may result in distortion depending on the shape at a position along the path.

Parameters

• faces (Union[list[Face], Compound]) – faces to project

• path – Path on the Shape to follow

• start – Relative location on path to start the faces. Defaults to 0.

Returns

The projected faces

project_to_viewport(viewport_origin: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], viewport_up: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]] = (0, 0, 1), look_at: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None) → tuple[ShapeList[Edge], ShapeList[Edge]]

Project a shape onto a viewport returning visible and hidden Edges.

Parameters

• viewport_origin (VectorLike) – location of viewport

• viewport_up (VectorLike, optional) – direction of the viewport y axis. Defaults to (0, 0, 1).

• look_at (VectorLike, optional) – point to look at. Defaults to None (center of shape).

Returns

visible & hidden Edges

Return type

tuple[ShapeList[Edge],ShapeList[Edge]]

relocate(loc: Location)

Change the location of self while keeping it geometrically similar

Parameters

loc (Location) – new location to set for self

rotate(axis: Axis, angle: float) → Self

rotate a copy

Rotates a shape around an axis.

Parameters

• axis (Axis) – rotation Axis

• angle (float) – angle to rotate, in degrees

Returns

a copy of the shape, rotated

scale(factor: float) → Self

Scales this shape through a transformation.

Parameters

factor – float:

Returns:

shape_type() → typing_extensions.Literal[Vertex, Edge, Wire, Face, Shell, Solid, Compound]

Return the shape type string for this class

shell() → Shell

Return the Shell

shells() → ShapeList[Shell]

shells - all the shells in this Shape

show_topology(limit_class: typing_extensions.Literal[Compound, Edge, Face, Shell, Solid, Vertex, Wire] = 'Vertex', show_center: Optional[bool] = None) → str

Display internal topology

Display the internal structure of a Compound ‘assembly’ or Shape. Example:

>>> c1.show_topology()

c1 is the root         Compound at 0x7f4a4cafafa0, Location(...))
├──                    Solid    at 0x7f4a4cafafd0, Location(...))
├── c2 is 1st compound Compound at 0x7f4a4cafaee0, Location(...))
│   ├──                Solid    at 0x7f4a4cafad00, Location(...))
│   └──                Solid    at 0x7f4a11a52790, Location(...))
└── c3 is 2nd          Compound at 0x7f4a4cafad60, Location(...))
    ├──                Solid    at 0x7f4a11a52700, Location(...))
    └──                Solid    at 0x7f4a11a58550, Location(...))

Parameters

• limit_class – type of displayed leaf node. Defaults to ‘Vertex’.

• show_center (bool, optional) – If None, shows the Location of Compound ‘assemblies’ and the bounding box center of Shapes. True or False forces the display. Defaults to None.

Returns

tree representation of internal structure

Return type

str

solid() → Solid

Return the Solid

solids() → ShapeList[Solid]

solids - all the solids in this Shape

split(plane: Plane, keep: Keep = Keep.TOP) → Self

Split this shape by the provided plane.

Parameters

• plane (Plane) – plane to segment shape

• keep (Keep, optional) – which object(s) to save. Defaults to Keep.TOP.

Returns

result of split

Return type

Shape

tessellate(tolerance: float, angular_tolerance: float = 0.1) → Tuple[list[build123d.geometry.Vector], list[Tuple[int, int, int]]]

General triangulated approximation

to_arcs(tolerance: float = 0.001) → Face

Approximate planar face with arcs and straight line segments.

Parameters

tolerance (float, optional) – Approximation tolerance. Defaults to 1e-3.

Returns

approximated face

Return type

Face

to_splines(degree: int = 3, tolerance: float = 0.001, nurbs: bool = False) → T

Approximate shape with b-splines of the specified degree.

Parameters

• degree (int, optional) – Maximum degree. Defaults to 3.

• tolerance (float, optional) – Approximation tolerance. Defaults to 1e-3.

• nurbs (bool, optional) – Use rational splines. Defaults to False.

Returns

_description_

Return type

T

to_vtk_poly_data(tolerance: Optional[float] = None, angular_tolerance: Optional[float] = None, normals: bool = False) → vtkPolyData

Convert shape to vtkPolyData

Parameters

• tolerance – float:

• angular_tolerance – float: (Default value = 0.1)

• normals – bool: (Default value = True)

Returns: data object in VTK consisting of points, vertices, lines, and polygons

transform_geometry(t_matrix: Matrix) → Self

Apply affine transform

WARNING: transform_geometry will sometimes convert lines and circles to splines, but it also has the ability to handle skew and stretching transformations.

If your transformation is only translation and rotation, it is safer to use transform_shape(), which doesn’t change the underlying type of the geometry, but cannot handle skew transformations.

Parameters

t_matrix (Matrix) – affine transformation matrix

Returns

a copy of the object, but with geometry transformed

Return type

Shape

transform_shape(t_matrix: Matrix) → Self

Apply affine transform without changing type

Transforms a copy of this Shape by the provided 3D affine transformation matrix. Note that not all transformation are supported - primarily designed for translation and rotation. See :transform_geometry: for more comprehensive transformations.

Parameters

t_matrix (Matrix) – affine transformation matrix

Returns

copy of transformed shape with all objects keeping their type

Return type

Shape

transformed(rotate: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]] = (0, 0, 0), offset: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]] = (0, 0, 0)) → Self

Transform Shape

Rotate and translate the Shape by the three angles (in degrees) and offset.

Parameters

• rotate (VectorLike, optional) – 3-tuple of angles to rotate, in degrees. Defaults to (0, 0, 0).

• offset (VectorLike, optional) – 3-tuple to offset. Defaults to (0, 0, 0).

Returns

transformed object

Return type

Shape

translate(vector: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → Self

Translates this shape through a transformation.

Parameters

vector – VectorLike:

Returns:

vertex() → Vertex

Return the Vertex

vertices() → ShapeList[Vertex]

vertices - all the vertices in this Shape

wire() → Wire

Return the Wire

wires() → ShapeList[Wire]

wires - all the wires in this Shape

class ShapeList(iterable=(), /)

Subclass of list with custom filter and sort methods appropriate to CAD

__and__(other: ShapeList)

Intersect two ShapeLists operator &

__getitem__(key: int) → T

__getitem__(key: slice) → ShapeList[T]

Return slices of ShapeList as ShapeList

__gt__(sort_by: Union[Axis, SortBy] = ((0.0, 0.0, 0.0), (0.0, 0.0, 1.0)))

Sort operator >

__lshift__(group_by: Union[Axis, SortBy] = ((0.0, 0.0, 0.0), (0.0, 0.0, 1.0)))

Group and select smallest group operator <<

__lt__(sort_by: Union[Axis, SortBy] = ((0.0, 0.0, 0.0), (0.0, 0.0, 1.0)))

Reverse sort operator <

__or__(filter_by: Union[Axis, GeomType] = ((0.0, 0.0, 0.0), (0.0, 0.0, 1.0)))

Filter by axis or geomtype operator |

__rshift__(group_by: Union[Axis, SortBy] = ((0.0, 0.0, 0.0), (0.0, 0.0, 1.0)))

Group and select largest group operator >>

__sub__(other: ShapeList) → ShapeList

Differences between two ShapeLists operator -

compound() → Compound

Return the Compound

compounds() → ShapeList[Compound]

compounds - all the compounds in this ShapeList

edge() → Edge

Return the Edge

edges() → ShapeList[Edge]

edges - all the edges in this ShapeList

face() → Face

Return the Face

faces() → ShapeList[Face]

faces - all the faces in this ShapeList

filter_by(filter_by: Union[ShapePredicate, Axis, Plane, GeomType], reverse: bool = False, tolerance: float = 1e-05) → ShapeList[T]

filter by Axis, Plane, or GeomType

Either: - filter objects of type planar Face or linear Edge by their normal or tangent (respectively) and sort the results by the given axis, or - filter the objects by the provided type. Note that not all types apply to all objects.

Parameters

• filter_by (Union[Axis,Plane,GeomType]) – axis, plane, or geom type to filter and possibly sort by. Filtering by a plane returns faces/edges parallel to that plane.

• reverse (bool, optional) – invert the geom type filter. Defaults to False.

• tolerance (float, optional) – maximum deviation from axis. Defaults to 1e-5.

Raises

ValueError – Invalid filter_by type

Returns

filtered list of objects

Return type

ShapeList

filter_by_position(axis: Axis, minimum: float, maximum: float, inclusive: tuple[bool, bool] = (True, True)) → ShapeList[T]

filter by position

Filter and sort objects by the position of their centers along given axis. min and max values can be inclusive or exclusive depending on the inclusive tuple.

Parameters

• axis (Axis) – axis to sort by

• minimum (float) – minimum value

• maximum (float) – maximum value

• inclusive (tuple[bool, bool], optional) – include min,max values. Defaults to (True, True).

Returns

filtered object list

Return type

ShapeList

property first: T

First element in the ShapeList

group_by(group_by: Union[Callable[[Shape], K], Axis, Edge, Wire, SortBy] = ((0.0, 0.0, 0.0), (0.0, 0.0, 1.0)), reverse=False, tol_digits=6) → GroupBy[T, K]

group by

Group objects by provided criteria and then sort the groups according to the criteria. Note that not all group_by criteria apply to all objects.

Parameters

• group_by (SortBy, optional) – group and sort criteria. Defaults to Axis.Z.

• reverse (bool, optional) – flip order of sort. Defaults to False.

• tol_digits (int, optional) – Tolerance for building the group keys by round(key, tol_digits)

Returns

sorted list of ShapeLists

Return type

GroupBy[K, ShapeList]

property last: T

Last element in the ShapeList

shell() → Shell

Return the Shell

shells() → ShapeList[Shell]

shells - all the shells in this ShapeList

solid() → Solid

Return the Solid

solids() → ShapeList[Solid]

solids - all the solids in this ShapeList

sort_by(sort_by: Union[Axis, Edge, Wire, SortBy] = ((0.0, 0.0, 0.0), (0.0, 0.0, 1.0)), reverse: bool = False) → ShapeList[T]

sort by

Sort objects by provided criteria. Note that not all sort_by criteria apply to all objects.

Parameters

• sort_by (SortBy, optional) – sort criteria. Defaults to SortBy.Z.

• reverse (bool, optional) – flip order of sort. Defaults to False.

Returns

sorted list of objects

Return type

ShapeList

sort_by_distance(other: Union[Shape, Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], reverse: bool = False) → ShapeList[T]

Sort by distance

Sort by minimal distance between objects and other

Parameters

• other (Union[Shape,VectorLike]) – reference object

• reverse (bool, optional) – flip order of sort. Defaults to False.

Returns

Sorted shapes

Return type

ShapeList

vertex() → Vertex

Return the Vertex

vertices() → ShapeList[Vertex]

vertices - all the vertices in this ShapeList

wire() → Wire

Return the Wire

wires() → ShapeList[Wire]

wires - all the wires in this ShapeList

class Shell(obj: TopoDS_Shape, label: str = '', color: Color = None, parent: Compound = None)

class Shell(face: Face, label: str = '', color: Color = None, parent: Compound = None)

class Shell(faces: Iterable[Face], label: str = '', color: Color = None, parent: Compound = None)

A Shell is a fundamental component in build123d’s topological data structure representing a connected set of faces forming a closed surface in 3D space. As part of a geometric model, it defines a watertight enclosure, commonly encountered in solid modeling. Shells group faces in a coherent manner, playing a crucial role in representing complex shapes with voids and surfaces. This hierarchical structure allows for efficient handling of surfaces within a model, supporting various operations and analyses.

center() → Vector

Center of mass of the shell

classmethod make_shell(faces: Iterable[Face]) → Shell

Create a Shell from provided faces

property volume: float

volume - the volume of this Shell if manifold, otherwise zero

class Solid(obj: TopoDS_Shape, label: str = '', color: Color = None, material: str = '', joints: dict[str, Joint] = None, parent: Compound = None)

class Solid(shell: Shell, label: str = '', color: Color = None, material: str = '', joints: dict[str, Joint] = None, parent: Compound = None)

A Solid in build123d represents a three-dimensional solid geometry in a topological structure. A solid is a closed and bounded volume, enclosing a region in 3D space. It comprises faces, edges, and vertices connected in a well-defined manner. Solid modeling operations, such as Boolean operations (union, intersection, and difference), are often performed on Solid objects to create or modify complex geometries.

classmethod extrude_linear_with_rotation(section: Union[Face, Wire], center: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], normal: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], angle: float, inner_wires: Optional[list[Wire]] = None) → Solid

Extrude with Rotation

Creates a ‘twisted prism’ by extruding, while simultaneously rotating around the extrusion vector.

Parameters

• section (Union[Face,Wire]) – cross section

• vec_center (VectorLike) – the center point about which to rotate

• vec_normal (VectorLike) – a vector along which to extrude the wires

• angle (float) – the angle to rotate through while extruding

• inner_wires (list[Wire], optional) – holes - only used if section is of type Wire. Defaults to None.

Returns

extruded object

Return type

Solid

classmethod extrude_taper(profile: Face, direction: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], taper: float, flip_inner: bool = True) → Solid

Extrude a cross section with a taper

Extrude a cross section into a prismatic solid in the provided direction.

Note that two difference algorithms are used. If direction aligns with the profile normal (which must be positive), the taper is positive and the profile contains no holes the OCP LocOpe_DPrism algorithm is used as it generates the most accurate results. Otherwise, a loft is created between the profile and the profile with a 2D offset set at the appropriate direction.

Parameters

• section (Face]) – cross section

• normal (VectorLike) – a vector along which to extrude the wires. The length of the vector controls the length of the extrusion.

• taper (float) – taper angle in degrees.

• flip_inner (bool, optional) – outer and inner geometry have opposite tapers to allow for part extraction when injection molding.

Returns

extruded cross section

Return type

Solid

classmethod extrude_until(section: Face, target_object: Union[Compound, Solid], direction: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], until: Until = Until.NEXT) → Union[Compound, Solid]

Extrude section in provided direction until it encounters either the NEXT or LAST surface of target_object. Note that the bounding surface must be larger than the extruded face where they contact.

Parameters

• section (Face) – Face to extrude

• target_object (Union[Compound, Solid]) – object to limit extrusion

• direction (VectorLike) – extrusion direction

• until (Until, optional) – surface to limit extrusion. Defaults to Until.NEXT.

Raises

ValueError – provided face does not intersect target_object

Returns

extruded Face

Return type

Union[Compound, Solid]

classmethod from_bounding_box(bbox: BoundBox) → Solid

A box of the same dimensions and location

classmethod make_box(length: float, width: float, height: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00))) → Solid

make box

Make a box at the origin of plane extending in positive direction of each axis.

Parameters

• length (float) –

• width (float) –

• height (float) –

• plane (Plane, optional) – base plane. Defaults to Plane.XY.

Returns

Box

Return type

Solid

classmethod make_cone(base_radius: float, top_radius: float, height: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00)), angle: float = 360) → Solid

make cone

Make a cone with given radii and height

Parameters

• base_radius (float) –

• top_radius (float) –

• height (float) –

• plane (Plane) – base plane. Defaults to Plane.XY.

• angle (float, optional) – arc size. Defaults to 360.

Returns

Full or partial cone

Return type

Solid

classmethod make_cylinder(radius: float, height: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00)), angle: float = 360) → Solid

make cylinder

Make a cylinder with a given radius and height with the base center on plane origin.

Parameters

• radius (float) –

• height (float) –

• plane (Plane) – base plane. Defaults to Plane.XY.

• angle (float, optional) – arc size. Defaults to 360.

Returns

Full or partial cylinder

Return type

Solid

classmethod make_loft(objs: Iterable[Union[Vertex, Wire]], ruled: bool = False) → Solid

make loft

Makes a loft from a list of wires and vertices, where vertices can be the first, last, or first and last elements.

Parameters

• objs (list[Vertex, Wire]) – wire perimeters or vertices

• ruled (bool, optional) – stepped or smooth. Defaults to False (smooth).

Raises

ValueError – Too few wires

Returns

Lofted object

Return type

Solid

classmethod make_solid(shell: Shell) → Solid

Create a Solid object from the surface shell

classmethod make_sphere(radius: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00)), angle1: float = -90, angle2: float = 90, angle3: float = 360) → Solid

Sphere

Make a full or partial sphere - with a given radius center on the origin or plane.

Parameters

• radius (float) –

• plane (Plane) – base plane. Defaults to Plane.XY.

• angle1 (float, optional) – Defaults to -90.

• angle2 (float, optional) – Defaults to 90.

• angle3 (float, optional) – Defaults to 360.

Returns

sphere

Return type

Solid

classmethod make_torus(major_radius: float, minor_radius: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00)), start_angle: float = 0, end_angle: float = 360, major_angle: float = 360) → Solid

make torus

Make a torus with a given radii and angles

Parameters

• major_radius (float) –

• minor_radius (float) –

• plane (Plane) – base plane. Defaults to Plane.XY.

• start_angle (float, optional) – start major arc. Defaults to 0.

• end_angle (float, optional) – end major arc. Defaults to 360.

Returns

Full or partial torus

Return type

Solid

classmethod make_wedge(delta_x: float, delta_y: float, delta_z: float, min_x: float, min_z: float, max_x: float, max_z: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00))) → Solid

Make a wedge

Parameters

• delta_x (float) –

• delta_y (float) –

• delta_z (float) –

• min_x (float) –

• min_z (float) –

• max_x (float) –

• max_z (float) –

• plane (Plane) – base plane. Defaults to Plane.XY.

Returns

wedge

Return type

Solid

classmethod revolve(section: Union[Face, Wire], angle: float, axis: Axis, inner_wires: Optional[list[Wire]] = None) → Solid

Revolve

Revolve a cross section about the given Axis by the given angle.

Parameters

• section (Union[Face,Wire]) – cross section

• angle (float) – the angle to revolve through

• axis (Axis) – rotation Axis

• inner_wires (list[Wire], optional) – holes - only used if section is of type Wire. Defaults to [].

Returns

the revolved cross section

Return type

Solid

classmethod sweep(section: Union[Face, Wire], path: Union[Wire, Edge], inner_wires: Optional[list[Wire]] = None, make_solid: bool = True, is_frenet: bool = False, mode: Optional[Union[Vector, Wire, Edge]] = None, transition: Transition = Transition.TRANSFORMED) → Solid

Sweep

Sweep the given cross section into a prismatic solid along the provided path

Parameters

• section (Union[Face, Wire]) – cross section to sweep

• path (Union[Wire, Edge]) – sweep path

• inner_wires (list[Wire]) – holes - only used if section is a wire

• make_solid (bool, optional) – return Solid or Shell. Defaults to True.

• is_frenet (bool, optional) – Frenet mode. Defaults to False.

• mode (Union[Vector, Wire, Edge, None], optional) – additional sweep mode parameters. Defaults to None.

• transition (Transition, optional) – handling of profile orientation at C1 path discontinuities. Defaults to Transition.TRANSFORMED.

Returns

the swept cross section

Return type

Solid

classmethod sweep_multi(profiles: Iterable[Union[Wire, Face]], path: Union[Wire, Edge], make_solid: bool = True, is_frenet: bool = False, mode: Optional[Union[Vector, Wire, Edge]] = None) → Solid

Multi section sweep

Sweep through a sequence of profiles following a path.

Parameters

• profiles (Iterable[Union[Wire, Face]]) – list of profiles

• path (Union[Wire, Edge]) – The wire to sweep the face resulting from the wires over

• make_solid (bool, optional) – Solid or Shell. Defaults to True.

• is_frenet (bool, optional) – Select frenet mode. Defaults to False.

• mode (Union[Vector, Wire, Edge, None], optional) – additional sweep mode parameters. Defaults to None.

Returns

swept object

Return type

Solid

property volume: float

volume - the volume of this Solid

class Wire(obj: TopoDS_Shape, label: str = '', color: Color = None, parent: Compound = None)

class Wire(edge: Edge, label: str = '', color: Color = None, parent: Compound = None)

class Wire(wire: Wire, label: str = '', color: Color = None, parent: Compound = None)

class Wire(wire: Curve, label: str = '', color: Color = None, parent: Compound = None)

class Wire(edges: Iterable[Edge], sequenced: bool = False, label: str = '', color: Color = None, parent: Compound = None)

A Wire in build123d is a topological entity representing a connected sequence of edges forming a continuous curve or path in 3D space. Wires are essential components in modeling complex objects, defining boundaries for surfaces or solids. They store information about the connectivity and order of edges, allowing precise definition of paths within a 3D model.

chamfer_2d(distance: float, distance2: float, vertices: Iterable[Vertex], edge: Optional[Edge] = None) → Wire

Apply 2D chamfer to a wire

Parameters

• distance (float) – chamfer length

• distance2 (float) – chamfer length

• vertices (Iterable[Vertex]) – vertices to chamfer

• edge (Edge) – identifies the side where length is measured. The vertices must be part of the edge

Returns

chamfered wire

Return type

Wire

close() → Wire

Close a Wire

classmethod combine(wires: Iterable[Union[Wire, Edge]], tol: float = 1e-09) → ShapeList[Wire]

Combine a list of wires and edges into a list of Wires.

Parameters

• wires (Iterable[Union[Wire, Edge]]) – unsorted

• tol (float, optional) – tolerance. Defaults to 1e-9.

Returns

Wires

Return type

ShapeList[Wire]

fillet_2d(radius: float, vertices: Iterable[Vertex]) → Wire

Apply 2D fillet to a wire

Parameters

• radius (float) –

• vertices (Iterable[Vertex]) – vertices to fillet

Returns

filleted wire

Return type

Wire

fix_degenerate_edges(precision: float) → Wire

Fix a Wire that contains degenerate (very small) edges

Parameters

precision (float) – minimum value edge length

Returns

fixed wire

Return type

Wire

classmethod make_circle(radius: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00))) → Wire

Makes a circle centered at the origin of plane

Parameters

• radius (float) – circle radius

• plane (Plane) – base plane. Defaults to Plane.XY

Returns

a circle

Return type

Wire

classmethod make_convex_hull(edges: Iterable[Edge], tolerance: float = 0.001) → Wire

Create a wire of minimum length enclosing all of the provided edges.

Note that edges can’t overlap each other.

Parameters

• edges (Iterable[Edge]) – edges defining the convex hull

• tolerance (float) – allowable error as a fraction of each edge length. Defaults to 1e-3.

Raises

ValueError – edges overlap

Returns

convex hull perimeter

Return type

Wire

classmethod make_ellipse(x_radius: float, y_radius: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00)), start_angle: float = 360.0, end_angle: float = 360.0, angular_direction: AngularDirection = AngularDirection.COUNTER_CLOCKWISE, closed: bool = True) → Wire

make ellipse

Makes an ellipse centered at the origin of plane.

Parameters

• x_radius (float) – x radius of the ellipse (along the x-axis of plane)

• y_radius (float) – y radius of the ellipse (along the y-axis of plane)

• plane (Plane, optional) – base plane. Defaults to Plane.XY.

• start_angle (float, optional) – _description_. Defaults to 360.0.

• end_angle (float, optional) – _description_. Defaults to 360.0.

• angular_direction (AngularDirection, optional) – arc direction. Defaults to AngularDirection.COUNTER_CLOCKWISE.

• closed (bool, optional) – close the arc. Defaults to True.

Returns

an ellipse

Return type

Wire

classmethod make_polygon(vertices: Iterable[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]], close: bool = True) → Wire

Create an irregular polygon by defining vertices

Parameters

• vertices (Iterable[VectorLike]) –

• close (bool, optional) – close the polygon. Defaults to True.

Returns

an irregular polygon

Return type

Wire

classmethod make_rect(width: float, height: float, plane: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, 0.00, 1.00))) → Wire

Make Rectangle

Make a Rectangle centered on center with the given normal

Parameters

• width (float) – width (local x)

• height (float) – height (local y)

• plane (Plane, optional) – plane containing rectangle. Defaults to Plane.XY.

Returns

The centered rectangle

Return type

Wire

classmethod make_wire(edges: Iterable[Edge], sequenced: bool = False) → Wire

Build a Wire from the provided unsorted Edges. If sequenced is True the Edges are placed in such that the end of the nth Edge is coincident with the n+1th Edge forming an unbroken sequence. Note that sequencing a list is relatively slow.

Parameters

• edges (Iterable[Edge]) – Edges to assemble

• sequenced (bool, optional) – arrange in order. Defaults to False.

Raises

• ValueError – Edges are disconnected and can’t be sequenced.

• RuntimeError – Wire is empty

Returns

assembled edges

Return type

Wire

order_edges() → ShapeList[Edge]

Return the edges in self ordered by wire direction and orientation

param_at_point(point: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]) → float

Parameter at point on Wire

project_to_shape(target_object: Shape, direction: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None, center: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None) → list[Wire]

Project Wire

Project a Wire onto a Shape generating new wires on the surfaces of the object one and only one of direction or center must be provided. Note that one or more wires may be generated depending on the topology of the target object and location/direction of projection.

To avoid flipping the normal of a face built with the projected wire the orientation of the output wires are forced to be the same as self.

Parameters

• target_object – Object to project onto

• direction – Parallel projection direction. Defaults to None.

• center – Conical center of projection. Defaults to None.

• target_object – Shape:

• direction – VectorLike: (Default value = None)

• center – VectorLike: (Default value = None)

Returns

Projected wire(s)

Raises

ValueError – Only one of direction or center must be provided

stitch(other: Wire) → Wire

Attempt to stich wires

Parameters

other – Wire:

Returns:

to_wire() → Wire

Return Wire - used as a pair with Edge.to_wire when self is Wire | Edge

trim(start: float, end: float) → Wire

Create a new wire by keeping only the section between start and end.

Parameters

• start (float) – 0.0 <= start < 1.0

• end (float) – 0.0 < end <= 1.0

Raises

ValueError – start >= end

Returns

trimmed wire

Return type

Wire

class Vertex

class Vertex(v: TopoDS_Vertex)

class Vertex(X: float, Y: float, Z: float)

class Vertex(v: Iterable[float])

class Vertex(v: tuple[float])

A Vertex in build123d represents a zero-dimensional point in the topological data structure. It marks the endpoints of edges within a 3D model, defining precise locations in space. Vertices play a crucial role in defining the geometry of objects and the connectivity between edges, facilitating accurate representation and manipulation of 3D shapes. They hold coordinate information and are essential for constructing complex structures like wires, faces, and solids.

__add__(other: Union[Vertex, Vector, Tuple[float, float, float]]) → Vertex

Add

Add to a Vertex with a Vertex, Vector or Tuple

Parameters

other – Value to add

Raises

TypeError – other not in [Tuple,Vector,Vertex]

Returns

Result

Example

part.faces(“>z”).vertices(“<y and <x”).val() + (0, 0, 15)

which creates a new Vertex 15 above one extracted from a part. One can add or subtract a Vertex , Vector or tuple of float values to a Vertex.

__sub__(other: Union[Vertex, Vector, tuple]) → Vertex

Subtract

Substract a Vertex with a Vertex, Vector or Tuple from self

Parameters

other – Value to add

Raises

TypeError – other not in [Tuple,Vector,Vertex]

Returns

Result

Example

part.faces(“>z”).vertices(“<y and <x”).val() - Vector(10, 0, 0)

center() → Vector

The center of a vertex is itself!

to_tuple() → tuple[float, float, float]

Return vertex as three tuple of floats

property volume: float

volume - the volume of this Vertex, which is always zero

class Curve(obj: TopoDS_Shape, label: str = '', color: Color = None, material: str = '', joints: dict[str, Joint] = None, parent: Compound = None, children: Iterable[Shape] = None)

class Curve(shapes: Iterable[Shape], label: str = '', color: Color = None, material: str = '', joints: dict[str, Joint] = None, parent: Compound = None, children: Iterable[Shape] = None)

A Compound containing 1D objects - aka Edges

__matmul__(position: float) → Vector

Position on curve operator @ - only works if continuous

__mod__(position: float) → Vector

Tangent on wire operator % - only works if continuous

wires() → list[Wire]

A list of wires created from the edges

class Part(obj: TopoDS_Shape, label: str = '', color: Color = None, material: str = '', joints: dict[str, Joint] = None, parent: Compound = None, children: Iterable[Shape] = None)

class Part(shapes: Iterable[Shape], label: str = '', color: Color = None, material: str = '', joints: dict[str, Joint] = None, parent: Compound = None, children: Iterable[Shape] = None)

A Compound containing 3D objects - aka Solids

class Sketch(obj: TopoDS_Shape, label: str = '', color: Color = None, material: str = '', joints: dict[str, Joint] = None, parent: Compound = None, children: Iterable[Shape] = None)

class Sketch(shapes: Iterable[Shape], label: str = '', color: Color = None, material: str = '', joints: dict[str, Joint] = None, parent: Compound = None, children: Iterable[Shape] = None)

A Compound containing 2D objects - aka Faces

Import/Export

Methods and functions specific to exporting and importing build123d objects are defined below.

Shape.export_brep(file: Union[str, BytesIO]) → bool

Export this shape to a BREP file

Parameters

file – Union[str, BytesIO]:

Returns:

Shape.export_stl(file_name: str, tolerance: float = 0.001, angular_tolerance: float = 0.1, ascii_format: bool = False) → bool

Export STL

Exports a shape to a specified STL file.

Parameters

• file_name (str) – The path and file name to write the STL output to.

• tolerance (float, optional) – A linear deflection setting which limits the distance between a curve and its tessellation. Setting this value too low will result in large meshes that can consume computing resources. Setting the value too high can result in meshes with a level of detail that is too low. The default is a good starting point for a range of cases. Defaults to 1e-3.

• angular_tolerance (float, optional) – Angular deflection setting which limits the angle between subsequent segments in a polyline. Defaults to 0.1.

• ascii_format (bool, optional) – Export the file as ASCII (True) or binary (False) STL format. Defaults to False (binary).

Returns

Success

Return type

bool

Shape.export_step(file_name: str, **kwargs) → IFSelect_ReturnStatus

Export this shape to a STEP file.

kwargs is used to provide optional keyword arguments to configure the exporter.

Parameters

• file_name (str) – Path and filename for writing.

• kwargs – used to provide optional keyword arguments to configure the exporter.

Returns

OCCT return status

Return type

IFSelect_ReturnStatus

Shape.export_stl(file_name: str, tolerance: float = 0.001, angular_tolerance: float = 0.1, ascii_format: bool = False) → bool

Export STL

Exports a shape to a specified STL file.

Parameters

• file_name (str) – The path and file name to write the STL output to.

• tolerance (float, optional) – A linear deflection setting which limits the distance between a curve and its tessellation. Setting this value too low will result in large meshes that can consume computing resources. Setting the value too high can result in meshes with a level of detail that is too low. The default is a good starting point for a range of cases. Defaults to 1e-3.

• angular_tolerance (float, optional) – Angular deflection setting which limits the angle between subsequent segments in a polyline. Defaults to 0.1.

• ascii_format (bool, optional) – Export the file as ASCII (True) or binary (False) STL format. Defaults to False (binary).

Returns

Success

Return type

bool

import_brep(file_name: str) → Shape

Import shape from a BREP file

Parameters

file_name (str) – brep file

Raises

ValueError – file not found

Returns

build123d object

Return type

Shape

import_step(file_name: str) → Compound

Extract shapes from a STEP file and return them as a Compound object.

Parameters

file_name (str) – file path of STEP file to import

Raises

ValueError – can’t open file

Returns

contents of STEP file

Return type

Compound

import_stl(file_name: str) → Face

Extract shape from an STL file and return it as a Face reference object.

Note that importing with this method and creating a reference is very fast while creating an editable model (with Mesher) may take minutes depending on the size of the STL file.

Parameters

file_name (str) – file path of STL file to import

Raises

ValueError – Could not import file

Returns

STL model

Return type

Face

import_svg(svg_file: Union[str, Path, TextIO], *, flip_y: bool = True, ignore_visibility: bool = False, label_by: str = 'id', is_inkscape_label: bool = False) → ShapeList[Union[Wire, Face]]

Parameters

• svg_file (Union[str, Path, TextIO]) – svg file

• flip_y (bool, optional) – flip objects to compensate for svg orientation. Defaults to True.

• ignore_visibility (bool, optional) – Defaults to False.

• label_by (str, optional) – xml attribute. Defaults to “id”.

• is_inkscape_label (bool, optional) – flag to indicate that the attribute is an Inkscape label like inkscape:label - label_by would be set to label in this case. Defaults to False.

Raises

ValueError – unexpected shape type

Returns

objects contained in svg

Return type

ShapeList[Union[Wire, Face]]

import_svg_as_buildline_code(file_name: str) → tuple[str, str]

translate_to_buildline_code

Translate the contents of the given svg file into executable build123d/BuildLine code.

Parameters

file_name (str) – svg file name

Returns

code, builder instance name

Return type

tuple[str, str]

Joint Object

Base Joint class which is used to position Solid and Compound objects relative to each other are defined below. The Joints section contains the class description of the derived Joint classes.

class Joint(label: str, parent: Union[Solid, Compound])

Abstract Base Joint class - used to join two components together

Parameters

parent (Union[Solid, Compound]) – object that joint to bound to

Variables

• label (str) – user assigned label

• parent (Shape) – object joint is bound to

• connected_to (Joint) – joint that is connect to this joint

abstract connect_to(other: Joint)

All derived classes must provide a connect_to method

abstract relative_to(other: Joint) → Location

Return relative location to another joint

abstract property symbol: Compound

A CAD object positioned in global space to illustrate the joint