Objects

Objects are Python classes that take parameters as inputs and create 1D, 2D or 3D Shapes. For example, a Torus is defined by a major and minor radii. In Builder mode, objects are positioned with Locations while in Algebra mode, objects are positioned with the * operator and shown in these examples:

with BuildPart() as disk:
    with BuildSketch():
        Circle(a)
        with Locations((b, 0.0)):
            Rectangle(c, c, mode=Mode.SUBTRACT)
        with Locations((0, b)):
            Circle(d, mode=Mode.SUBTRACT)
    extrude(amount=c)

sketch = Circle(a) - Pos(b, 0.0) * Rectangle(c, c) - Pos(0.0, b) * Circle(d)
disk = extrude(sketch, c)

The following sections describe the 1D, 2D and 3D objects:

Align

2D/Sketch and 3D/Part objects can be aligned relative to themselves, either centered, or justified right or left of each Axis. The following diagram shows how this alignment works in 2D:

For example:

with BuildSketch():
    Circle(1, align=(Align.MIN, Align.MIN))

creates a circle who’s minimal X and Y values are on the X and Y axis and is located in the top right corner. The Align enum has values: MIN, CENTER and MAX.

In 3D the align parameter also contains a Z align value but otherwise works in the same way.

Note that the align will also accept a single Align value which will be used on all axes - as shown here:

with BuildSketch():
    Circle(1, align=Align.MIN)

Mode

With the Builder API the mode parameter controls how objects are combined with lines, sketches, or parts under construction. The Mode enum has values:

ADD: fuse this object to the object under construction
SUBTRACT: cut this object from the object under construction
INTERSECT: intersect this object with the object under construction
REPLACE: replace the object under construction with this object
PRIVATE: don’t interact with the object under construction at all

The Algebra API doesn’t use the mode parameter - users combine objects with operators.

1D Objects

The following objects all can be used in BuildLine contexts. Note that 1D objects are not affected by Locations in Builder mode.

Bezier

Curve defined by control points and weights

CenterArc

Arc defined by center, radius, & angles

DoubleTangentArc

Arc defined by point/tangent pair & other curve

EllipticalCenterArc

Elliptical arc defined by center, radii & angles

FilletPolyline

Polyline with filleted corners defined by pts and radius

Helix

Helix defined pitch, radius and height

IntersectingLine

Intersecting line defined by start, direction & other line

JernArc

Arc define by start point, tangent, radius and angle

Line

Line defined by end points

PolarLine

Line defined by start, angle and length

Polyline

Multiple line segments defined by points

RadiusArc

Arc define by two points and a radius

SagittaArc

Arc define by two points and a sagitta

Spline

Curve define by points

TangentArc

Curve define by two points and a tangent

ThreePointArc

Curve define by three points

Reference

class BaseLineObject(curve: Union[Edge, Wire], mode: Mode = Mode.ADD)[source]

Base class for all BuildLine objects

Parameters

curve (Union[Edge,Wire]) – edge to create
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class Bezier(*cntl_pnts: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], weights: Optional[list[float]] = None, mode: Mode = Mode.ADD)[source]

Line Object: Bezier Curve

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.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class CenterArc(center: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], radius: float, start_angle: float, arc_size: float, mode: Mode = Mode.ADD)[source]

Line Object: Center Arc

Add center arc to the line.

Parameters

center (VectorLike) – center point of arc
radius (float) – arc radius
start_angle (float) – arc staring angle
arc_size (float) – arc size
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class DoubleTangentArc(pnt: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], tangent: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], other: Union[Curve, Edge, Wire], keep: Keep = Keep.TOP, mode: Mode = Mode.ADD)[source]

Line Object: Double Tangent Arc

Create an arc defined by a point/tangent pair and another line which the other end is tangent to.

Contains a solver.

Parameters

pnt (VectorLike) – starting point of tangent arc
tangent (VectorLike) – tangent at starting point of tangent arc
other (Union[Curve, Edge, Wire]) – reference line
keep (Keep, optional) – selector for which arc to keep when two arcs are possible. The arc generated with TOP or BOTTOM depends on the geometry and isn’t necessarily easy to predict. Defaults to Keep.TOP.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

RunTimeError – no double tangent arcs found

class EllipticalCenterArc(center: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], x_radius: float, y_radius: float, start_angle: float = 0.0, end_angle: float = 90.0, rotation: float = 0.0, angular_direction: AngularDirection = AngularDirection.COUNTER_CLOCKWISE, mode: Mode = Mode.ADD)[source]

Line Object: Elliptical Center Arc

Makes an arc of an ellipse from a center point.

Parameters

center (VectorLike) – ellipse center
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)
start_angle (float, optional) – Defaults to 0.0.
end_angle (float, optional) – Defaults to 90.0.
rotation (float, optional) – amount to rotate arc. Defaults to 0.0.
angular_direction (AngularDirection, optional) – arc direction. Defaults to AngularDirection.COUNTER_CLOCKWISE.
plane (Plane, optional) – base plane. Defaults to Plane.XY.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class FilletPolyline(*pts: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float], Iterable[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]], radius: float, close: bool = False, mode: Mode = Mode.ADD)[source]

Line Object: FilletPolyline

Add a sequence of straight lines defined by successive points that are filleted to a given radius.

Parameters

pts (Union[VectorLike, Iterable[VectorLike]]) – sequence of two or more points
radius (float) – radius of filleted corners
close (bool, optional) – close by generating an extra Edge. Defaults to False.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

ValueError – Two or more points not provided
ValueError – radius must be positive

class Helix(pitch: float, height: float, radius: float, center: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]] = (0, 0, 0), direction: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]] = (0, 0, 1), cone_angle: float = 0, lefthand: bool = False, mode: Mode = Mode.ADD)[source]

Line Object: Helix

Add a helix to the line.

Parameters

pitch (float) – distance between successive loops
height (float) – helix size
radius (float) – helix radius
center (VectorLike, optional) – center point. Defaults to (0, 0, 0).
direction (VectorLike, optional) – direction of central axis. Defaults to (0, 0, 1).
cone_angle (float, optional) – conical angle. Defaults to 0.
lefthand (bool, optional) – left handed helix. Defaults to False.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class IntersectingLine(start: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], direction: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], other: Union[Curve, Edge, Wire], mode: Mode = Mode.ADD)[source]

Intersecting Line Object: Line

Add a straight line that intersects another line at a given parameter and angle.

Parameters

start (VectorLike) – start point
direction (VectorLike) – direction to make line
other (Edge) – stop at the intersection of other
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class JernArc(start: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], tangent: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], radius: float, arc_size: float, mode: Mode = Mode.ADD)[source]

Circular tangent arc with given radius and arc_size

Parameters

start (VectorLike) – start point
tangent (VectorLike) – tangent at start point
radius (float) – arc radius
arc_size (float) – arc size in degrees (negative to change direction)
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Variables

start (Vector) – start point
end_of_arc (Vector) – end point of arc
center_point (Vector) – center of arc

class Line(*pts: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float], Iterable[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]], mode: Mode = Mode.ADD)[source]

Line Object: Line

Add a straight line defined by two end points.

Parameters

pts (Union[VectorLike, Iterable[VectorLike]]) – sequence of two points
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

ValueError – Two point not provided

class PolarLine(start: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], length: float, angle: Optional[float] = None, direction: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None, length_mode: LengthMode = LengthMode.DIAGONAL, mode: Mode = Mode.ADD)[source]

Line Object: Polar Line

Add line defined by a start point, length and angle.

Parameters

start (VectorLike) – start point
length (float) – line length
angle (float) – angle from the local “X” axis.
length_mode (LengthMode, optional) – length value specifies a diagonal, horizontal or vertical value. Defaults to LengthMode.DIAGONAL
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

ValueError – Either angle or direction must be provided

class Polyline(*pts: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float], Iterable[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]], close: bool = False, mode: Mode = Mode.ADD)[source]

Line Object: Polyline

Add a sequence of straight lines defined by successive point pairs.

Parameters

pts (Union[VectorLike, Iterable[VectorLike]]) – sequence of two or more points
close (bool, optional) – close by generating an extra Edge. Defaults to False.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

ValueError – Two or more points not provided

class RadiusArc(start_point: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], end_point: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], radius: float, short_sagitta: bool = True, mode: Mode = Mode.ADD)[source]

Line Object: Radius Arc

Add an arc defined by two end points and a radius

Parameters

start_point (VectorLike) – start
end_point (VectorLike) – end
radius (float) – radius
short_sagitta (bool) – If True selects the short sagitta, else the long sagitta crossing the center. Defaults to True.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

ValueError – Insufficient radius to connect end points

class SagittaArc(start_point: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], end_point: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], sagitta: float, mode: Mode = Mode.ADD)[source]

Line Object: Sagitta Arc

Add an arc defined by two points and the height of the arc (sagitta).

Parameters

start_point (VectorLike) – start
end_point (VectorLike) – end
sagitta (float) – arc height
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class Spline(*pts: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float], Iterable[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]], tangents: Optional[Iterable[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]] = None, tangent_scalars: Optional[Iterable[float]] = None, periodic: bool = False, mode: Mode = Mode.ADD)[source]

Line Object: Spline

Add a spline through the provided points optionally constrained by tangents.

Parameters

pts (Union[VectorLike, Iterable[VectorLike]]) – sequence of two or more points
tangents (Iterable[VectorLike], optional) – tangents at end points. Defaults to None.
tangent_scalars (Iterable[float], optional) – change shape by amplifying tangent. Defaults to None.
periodic (bool, optional) – make the spline periodic. Defaults to False.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class TangentArc(*pts: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float], Iterable[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]], tangent: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], tangent_from_first: bool = True, mode: Mode = Mode.ADD)[source]

Line Object: Tangent Arc

Add an arc defined by two points and a tangent.

Parameters

pts (Union[VectorLike, Iterable[VectorLike]]) – sequence of two points
tangent (VectorLike) – tangent to constrain arc
tangent_from_first (bool, optional) – apply tangent to first point. Note, applying tangent to end point will flip the orientation of the arc. Defaults to True.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

ValueError – Two points are required

class ThreePointArc(*pts: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float], Iterable[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]]], mode: Mode = Mode.ADD)[source]

Line Object: Three Point Arc

Add an arc generated by three points.

Parameters

pts (Union[VectorLike, Iterable[VectorLike]]) – sequence of three points
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

ValueError – Three points must be provided

2D Objects

Arrow

Arrow with head and path for shaft

ArrowHead

Arrow head with multiple types

Circle

Circle defined by radius

DimensionLine

Dimension line

Ellipse

Ellipse defined by major and minor radius

ExtensionLine

Extension lines for distance or angles

Polygon

Polygon defined by points

Rectangle

Rectangle defined by width and height

RectangleRounded

Rectangle with rounded corners defined by width, height, and radius

RegularPolygon

RegularPolygon defined by radius and number of sides

SlotArc

SlotArc defined by arc and height

SlotCenterPoint

SlotCenterPoint defined by two points and a height

SlotCenterToCenter

SlotCenterToCenter defined by center separation and height

SlotOverall

SlotOverall defined by end-to-end length and height

TechnicalDrawing

A technical drawing with descriptions

Text

Text defined by string and font parameters

Trapezoid

Trapezoid defined by width, height and interior angles

Triangle

Triangle defined by one side & two other sides or interior angles

Reference

class BaseSketchObject(obj: Union[Compound, Face], rotation: float = 0, align: Optional[Union[Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align]]] = None, mode: Mode = Mode.ADD)[source]

Base class for all BuildSketch objects

Parameters

face (Face) – face to create
rotation (float, optional) – angles to rotate objects. Defaults to 0.
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to None.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class Arrow(arrow_size: float, shaft_path: Union[Edge, Wire], shaft_width: float, head_at_start: bool = True, head_type: HeadType = HeadType.CURVED, mode: Mode = Mode.ADD)[source]

Sketch Object: Arrow with shaft

Parameters

arrow_size (float) – arrow head tip to tail length
shaft_path (Union[Edge, Wire]) – line describing the shaft shape
shaft_width (float) – line width of shaft
head_at_start (bool, optional) – Defaults to True.
head_type (HeadType, optional) – arrow head shape. Defaults to HeadType.CURVED.
mode (Mode, optional) – _description_. Defaults to Mode.ADD.

class ArrowHead(size: float, head_type: HeadType = HeadType.CURVED, rotation: float = 0, mode: Mode = Mode.ADD)[source]

Sketch Object: ArrowHead

Parameters

size (float) – tip to tail length
head_type (HeadType, optional) – arrow head shape. Defaults to HeadType.CURVED.
rotation (float, optional) – rotation in degrees. Defaults to 0.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class Circle(radius: float, align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Sketch Object: Circle

Add circle(s) to the sketch.

Parameters

radius (float) – circle size
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER).
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class DimensionLine(path: Union[Wire, Edge, list[Union[build123d.geometry.Vector, build123d.topology.Vertex, tuple[float, float, float]]]], draft: Optional[Draft] = None, sketch: Optional[Sketch] = None, label: Optional[str] = None, arrows: tuple[bool, bool] = (True, True), tolerance: Optional[Union[float, tuple[float, float]]] = None, label_angle: bool = False, mode: Mode = Mode.ADD)[source]

Sketch Object: DimensionLine

Create a dimension line typically for internal measurements. Typically used for (but not restricted to) inside dimensions, a dimension line often as arrows on either side of a dimension or label.

There are three options depending on the size of the text and length of the dimension line: Type 1) The label and arrows fit within the length of the path Type 2) The text fit within the path and the arrows go outside Type 3) Neither the text nor the arrows fit within the path

Parameters

path (PathDescriptor) – a very general type of input used to describe the path the dimension line will follow.
draft (Draft) – instance of Draft dataclass
sketch (Sketch) – the Sketch being created to check for possible overlaps. In builder mode the active Sketch will be used if None is provided.
label (str, optional) – a text string which will replace the length (or arc length) that would otherwise be extracted from the provided path. Providing a label is useful when illustrating a parameterized input where the name of an argument is desired not an actual measurement. Defaults to None.
arrows (tuple[bool, bool], optional) – a pair of boolean values controlling the placement of the start and end arrows. Defaults to (True, True).
tolerance (Union[float, tuple[float, float]], optional) – an optional tolerance value to add to the extracted length value. If a single tolerance value is provided it is shown as ± the provided value while a pair of values are shown as separate + and - values. Defaults to None.
label_angle (bool, optional) – a flag indicating that instead of an extracted length value, the size of the circular arc extracted from the path should be displayed in degrees.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

ValueError – Only 2 points allowed for dimension lines
ValueError – No output - no arrows selected

dimension: length of the dimension

class Ellipse(x_radius: float, y_radius: float, rotation: float = 0, align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Sketch Object: Ellipse

Add ellipse(s) to sketch.

Parameters

x_radius (float) – horizontal radius
y_radius (float) – vertical radius
rotation (float, optional) – angles to rotate objects. Defaults to 0.
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER).
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class ExtensionLine(border: Union[Wire, Edge, list[Union[build123d.geometry.Vector, build123d.topology.Vertex, tuple[float, float, float]]]], offset: float, draft: Draft, sketch: Optional[Sketch] = None, label: Optional[str] = None, arrows: tuple[bool, bool] = (True, True), tolerance: Optional[Union[float, tuple[float, float]]] = None, label_angle: bool = False, project_line: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None, mode: Mode = Mode.ADD)[source]

Sketch Object: Extension Line

Create a dimension line with two lines extending outward from the part to dimension. Typically used for (but not restricted to) outside dimensions, with a pair of lines extending from the edge of a part to a dimension line.

Parameters

border (PathDescriptor) – a very general type of input defining the object to be dimensioned. Typically this value would be extracted from the part but is not restricted to this use.
offset (float) – a distance to displace the dimension line from the edge of the object
draft (Draft) – instance of Draft dataclass
label (str, optional) – a text string which will replace the length (or arc length) that would otherwise be extracted from the provided path. Providing a label is useful when illustrating a parameterized input where the name of an argument is desired not an actual measurement. Defaults to None.
arrows (tuple[bool, bool], optional) – a pair of boolean values controlling the placement of the start and end arrows. Defaults to (True, True).
tolerance (Union[float, tuple[float, float]], optional) – an optional tolerance value to add to the extracted length value. If a single tolerance value is provided it is shown as ± the provided value while a pair of values are shown as separate + and - values. Defaults to None.
label_angle (bool, optional) – a flag indicating that instead of an extracted length value, the size of the circular arc extracted from the path should be displayed in degrees. Defaults to False.
project_line (Vector, optional) – Vector line which to project dimension against. Defaults to None.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

dimension: length of the dimension

class Polygon(*pts: ~typing.Union[~build123d.geometry.Vector, tuple[float, float], tuple[float, float, float], ~typing.Iterable[float], ~typing.Iterable[~typing.Union[~build123d.geometry.Vector, tuple[float, float], tuple[float, float, float], ~typing.Iterable[float]]]], rotation: float = 0, align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Sketch Object: Polygon

Add polygon(s) defined by given sequence of points to sketch.

Note that the order of the points define the normal of the Face that is created in Algebra mode, where counter clockwise order creates Faces with their normal being up while a clockwise order will have a normal that is down. In Builder mode, all Faces added to the sketch are up.

Parameters

pts (Union[VectorLike, Iterable[VectorLike]]) – sequence of points defining the vertices of the polygon
rotation (float, optional) – angles to rotate objects. Defaults to 0.
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER).
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class Rectangle(width: float, height: float, rotation: float = 0, align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Sketch Object: Rectangle

Add rectangle(s) to sketch.

Parameters

width (float) – horizontal size
height (float) – vertical size
rotation (float, optional) – angles to rotate objects. Defaults to 0.
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER).
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class RectangleRounded(width: float, height: float, radius: float, rotation: float = 0, align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Sketch Object: RectangleRounded

Add rectangle(s) with filleted corners to sketch.

Parameters

width (float) – horizontal size
height (float) – vertical size
radius (float) – fillet radius
rotation (float, optional) – angles to rotate objects. Defaults to 0.
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER).
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class RegularPolygon(radius: float, side_count: int, major_radius: bool = True, rotation: float = 0, align: tuple[build123d.build_enums.Align, build123d.build_enums.Align] = (<Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Sketch Object: Regular Polygon

Add regular polygon(s) to sketch.

Parameters

radius (float) – distance from origin to vertices (major), or optionally from the origin to side (minor) with major_radius = False
side_count (int) – number of polygon sides
major_radius (bool) – If True the radius is the major radius, else the radius is the minor radius (also known as inscribed radius). Defaults to True.
rotation (float, optional) – angles to rotate objects. Defaults to 0.
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER).
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

apothem: float: radius of the inscribed circle or minor radius

radius: float: radius of the circumscribed circle or major radius

class SlotArc(arc: Union[Edge, Wire], height: float, rotation: float = 0, mode: Mode = Mode.ADD)[source]

Sketch Object: Arc Slot

Add slot(s) following an arc to sketch.

Parameters

arc (Union[Edge, Wire]) – center line of slot
height (float) – diameter of end circles
rotation (float, optional) – angles to rotate objects. Defaults to 0.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class SlotCenterPoint(center: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], point: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], height: float, rotation: float = 0, mode: Mode = Mode.ADD)[source]

Sketch Object: Center Point Slot

Add a slot(s) defined by the center of the slot and the center of one of the circular arcs at the end. The other end will be generated to create a symmetric slot.

Parameters

center (VectorLike) – slot center point
point (VectorLike) – slot center of arc point
height (float) – diameter of end circles
rotation (float, optional) – angles to rotate objects. Defaults to 0.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class SlotCenterToCenter(center_separation: float, height: float, rotation: float = 0, mode: Mode = Mode.ADD)[source]

Sketch Object: Center to Center points Slot

Add slot(s) defined by the distance between the center of the two end arcs.

Parameters

center_separation (float) – distance between two arc centers
height (float) – diameter of end circles
rotation (float, optional) – angles to rotate objects. Defaults to 0.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class SlotOverall(width: float, height: float, rotation: float = 0, align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Sketch Object: Center to Center points Slot

Add slot(s) defined by the overall with of the slot.

Parameters

width (float) – overall width of the slot
height (float) – diameter of end circles
rotation (float, optional) – angles to rotate objects. Defaults to 0.
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER).
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class TechnicalDrawing(designed_by: str = 'build123d', design_date: date = datetime.date(2024, 4, 22), page_size: PageSize = PageSize.A4, title: str = 'Title', sub_title: str = 'Sub Title', drawing_number: str = 'B3D-1', sheet_number: Optional[int] = None, drawing_scale: float = 1.0, nominal_text_size: float = 10.0, line_width: float = 0.5, mode: Mode = Mode.ADD)[source]

Sketch Object: TechnicalDrawing

The border of a technical drawing with external frame and text box.

Parameters

designed_by (str, optional) – Defaults to “build123d”.
design_date (date, optional) – Defaults to date.today().
page_size (PageSize, optional) – Defaults to PageSize.A4.
title (str, optional) – drawing title. Defaults to “Title”.
sub_title (str, optional) – drawing sub title. Defaults to “Sub Title”.
drawing_number (str, optional) – Defaults to “B3D-1”.
sheet_number (int, optional) – Defaults to None.
drawing_scale (float, optional) – displays as 1:value. Defaults to 1.0.
nominal_text_size (float, optional) – size of title text. Defaults to 10.0.
line_width (float, optional) – Defaults to 0.5.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

margin = 5

page_sizes = {<PageSize.A0>: (1189, 841), <PageSize.A1>: (841, 594), <PageSize.A2>: (594, 420), <PageSize.A3>: (420, 297), <PageSize.A4>: (297, 210), <PageSize.A5>: (210, 148.5), <PageSize.A6>: (148.5, 105), <PageSize.A7>: (105, 74), <PageSize.A8>: (74, 52), <PageSize.A9>: (52, 37), <PageSize.A10>: (37, 26), <PageSize.LETTER>: (279.4, 215.89999999999998), <PageSize.LEGAL>: (355.59999999999997, 215.89999999999998), <PageSize.LEDGER>: (431.79999999999995, 279.4)}

class 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>), path: ~typing.Optional[~typing.Union[~build123d.topology.Edge, ~build123d.topology.Wire]] = None, position_on_path: float = 0.0, rotation: float = 0, mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Sketch Object: Text

Add text(s) to the sketch.

Parameters

txt (str) – text to be rendered
font_size (float) – size of the font in model units
font (str, optional) – font name. Defaults to “Arial”.
font_path (str, optional) – system path to font library. Defaults to None.
font_style (Font_Style, optional) – style. Defaults to Font_Style.REGULAR.
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER).
path (Union[Edge, Wire], optional) – path for text to follow. Defaults to None.
position_on_path (float, optional) – the relative location on path to position the text, values must be between 0.0 and 1.0. Defaults to 0.0.
rotation (float, optional) – angles to rotate objects. Defaults to 0.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class Trapezoid(width: float, height: float, left_side_angle: float, right_side_angle: ~typing.Optional[float] = None, rotation: float = 0, align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Sketch Object: Trapezoid

Add trapezoid(s) to the sketch.

Parameters

width (float) – horizontal width
height (float) – vertical height
left_side_angle (float) – bottom left interior angle
right_side_angle (float, optional) – bottom right interior angle. If not provided, the trapezoid will be symmetric. Defaults to None.
rotation (float, optional) – angles to rotate objects. Defaults to 0.
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER).
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

ValueError – Give angles result in an invalid trapezoid

class Triangle(*, a: Optional[float] = None, b: Optional[float] = None, c: Optional[float] = None, A: Optional[float] = None, B: Optional[float] = None, C: Optional[float] = None, align: Union[None, Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align]] = None, rotation: float = 0, mode: Mode = Mode.ADD)[source]

Sketch Object: Triangle

Add any triangle to the sketch by specifying the length of any side and any two other side lengths or interior angles. Note that the interior angles are opposite the side with the same designation (i.e. side ‘a’ is opposite angle ‘A’).

Parameters

a (float, optional) – side ‘a’ length. Defaults to None.
b (float, optional) – side ‘b’ length. Defaults to None.
c (float, optional) – side ‘c’ length. Defaults to None.
A (float, optional) – interior angle ‘A’ in degrees. Defaults to None.
B (float, optional) – interior angle ‘B’ in degrees. Defaults to None.
C (float, optional) – interior angle ‘C’ in degrees. Defaults to None.
rotation (float, optional) – angles to rotate objects. Defaults to 0.
align (Union[Align, tuple[Align, Align]], optional) – align min, center, or max of object. Defaults to None.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

Raises

ValueError – One length and two other values were not provided

A: interior angle ‘A’ in degrees

B: interior angle ‘B’ in degrees

C: interior angle ‘C’ in degrees

a: length of side ‘a’

b: length of side ‘b’

c: length of side ‘c’

3D Objects

Box

Box defined by length, width, height

Cone

Cone defined by radii and height

CounterBoreHole

Counter bore hole defined by radii and depths

CounterSinkHole

Counter sink hole defined by radii and depth and angle

Cylinder

Cylinder defined by radius and height

Hole

Hole defined by radius and depth

Sphere

Sphere defined by radius and arc angles

Torus

Torus defined major and minor radii

Wedge

Wedge defined by lengths along multiple Axes

Reference

class BasePartObject(part: Union[Part, Solid], rotation: Union[tuple[float, float, float], Rotation] = (0, 0, 0), align: Optional[Union[Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align, build123d.build_enums.Align]]] = None, mode: Mode = Mode.ADD)[source]

Base class for all BuildPart objects & operations

Parameters

solid (Solid) – object to create
rotation (RotationLike, optional) – angles to rotate about axes. Defaults to (0, 0, 0).
align (Union[Align, tuple[Align, Align, Align]], optional) – align min, center, or max of object. Defaults to None.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.

class Box(length: float, width: float, height: float, rotation: ~typing.Union[tuple[float, float, float], ~build123d.geometry.Rotation] = (0, 0, 0), align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Part Object: Box

Create a box(es) and combine with part.

Parameters

length (float) – box size
width (float) – box size
height (float) – box size
rotation (RotationLike, optional) – angles to rotate about axes. Defaults to (0, 0, 0).
align (Union[Align, tuple[Align, Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER).
mode (Mode, optional) – combine mode. Defaults to Mode.ADD.

class Cone(bottom_radius: float, top_radius: float, height: float, arc_size: float = 360, rotation: ~typing.Union[tuple[float, float, float], ~build123d.geometry.Rotation] = (0, 0, 0), align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Part Object: Cone

Create a cone(s) and combine with part.

Parameters

bottom_radius (float) – cone size
top_radius (float) – top size, could be zero
height (float) – cone size
arc_size (float, optional) – angular size of cone. Defaults to 360.
rotation (RotationLike, optional) – angles to rotate about axes. Defaults to (0, 0, 0).
align (Union[Align, tuple[Align, Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER).
mode (Mode, optional) – combine mode. Defaults to Mode.ADD.

class CounterBoreHole(radius: float, counter_bore_radius: float, counter_bore_depth: float, depth: Optional[float] = None, mode: Mode = Mode.SUBTRACT)[source]

Part Operation: Counter Bore Hole

Create a counter bore hole in part.

Parameters

radius (float) – hole size
counter_bore_radius (float) – counter bore size
counter_bore_depth (float) – counter bore depth
depth (float, optional) – hole depth - None implies through part. Defaults to None.
mode (Mode, optional) – combination mode. Defaults to Mode.SUBTRACT.

class CounterSinkHole(radius: float, counter_sink_radius: float, depth: Optional[float] = None, counter_sink_angle: float = 82, mode: Mode = Mode.SUBTRACT)[source]

Part Operation: Counter Sink Hole

Create a counter sink hole in part.

Parameters

radius (float) – hole size
counter_sink_radius (float) – counter sink size
depth (float, optional) – hole depth - None implies through part. Defaults to None.
counter_sink_angle (float, optional) – cone angle. Defaults to 82.
mode (Mode, optional) – combination mode. Defaults to Mode.SUBTRACT.

class Cylinder(radius: float, height: float, arc_size: float = 360, rotation: ~typing.Union[tuple[float, float, float], ~build123d.geometry.Rotation] = (0, 0, 0), align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Part Object: Cylinder

Create a cylinder(s) and combine with part.

Parameters

radius (float) – cylinder size
height (float) – cylinder size
arc_size (float, optional) – angular size of cone. Defaults to 360.
rotation (RotationLike, optional) – angles to rotate about axes. Defaults to (0, 0, 0).
align (Union[Align, tuple[Align, Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER).
mode (Mode, optional) – combine mode. Defaults to Mode.ADD.

class Hole(radius: float, depth: Optional[float] = None, mode: Mode = Mode.SUBTRACT)[source]

Part Operation: Hole

Create a hole in part.

Parameters

radius (float) – hole size
depth (float, optional) – hole depth - None implies through part. Defaults to None.
mode (Mode, optional) – combination mode. Defaults to Mode.SUBTRACT.

class Sphere(radius: float, arc_size1: float = -90, arc_size2: float = 90, arc_size3: float = 360, rotation: ~typing.Union[tuple[float, float, float], ~build123d.geometry.Rotation] = (0, 0, 0), align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Part Object: Sphere

Create a sphere(s) and combine with part.

Parameters

radius (float) – sphere size
arc_size1 (float, optional) – angular size of sphere. Defaults to -90.
arc_size2 (float, optional) – angular size of sphere. Defaults to 90.
arc_size3 (float, optional) – angular size of sphere. Defaults to 360.
rotation (RotationLike, optional) – angles to rotate about axes. Defaults to (0, 0, 0).
align (Union[Align, tuple[Align, Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER).
mode (Mode, optional) – combine mode. Defaults to Mode.ADD.

class Torus(major_radius: float, minor_radius: float, minor_start_angle: float = 0, minor_end_angle: float = 360, major_angle: float = 360, rotation: ~typing.Union[tuple[float, float, float], ~build123d.geometry.Rotation] = (0, 0, 0), align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Part Object: Torus

Create a torus(es) and combine with part.

Parameters

major_radius (float) – torus size
minor_radius (float) – torus size
major_arc_size (float, optional) – angular size of torus. Defaults to 0.
minor_arc_size (float, optional) – angular size or torus. Defaults to 360.
rotation (RotationLike, optional) – angles to rotate about axes. Defaults to (0, 0, 0).
align (Union[Align, tuple[Align, Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER).
mode (Mode, optional) – combine mode. Defaults to Mode.ADD.

class Wedge(xsize: float, ysize: float, zsize: float, xmin: float, zmin: float, xmax: float, zmax: float, rotation: ~typing.Union[tuple[float, float, float], ~build123d.geometry.Rotation] = (0, 0, 0), align: ~typing.Union[~build123d.build_enums.Align, tuple[build123d.build_enums.Align, build123d.build_enums.Align, build123d.build_enums.Align]] = (<Align.CENTER>, <Align.CENTER>, <Align.CENTER>), mode: ~build123d.build_enums.Mode = Mode.ADD)[source]

Part Object: Wedge

Create a wedge(s) and combine with part.

Parameters

xsize (float) – distance along the X axis
ysize (float) – distance along the Y axis
zsize (float) – distance along the Z axis
xmin (float) – minimum X location
zmin (float) – minimum Z location
xmax (float) – maximum X location
zmax (float) – maximum Z location
rotation (RotationLike, optional) – angles to rotate about axes. Defaults to (0, 0, 0).
align (Union[Align, tuple[Align, Align, Align]], optional) – align min, center, or max of object. Defaults to (Align.CENTER, Align.CENTER, Align.CENTER).
mode (Mode, optional) – combine mode. Defaults to Mode.ADD.

Custom Objects

All of the objects presented above were created using one of three base object classes: BaseLineObject , BaseSketchObject , and BasePartObject . Users can use these base object classes to easily create custom objects that have all the functionality of the core objects.

Here is an example of a custom sketch object specially created as part of the design of this playing card storage box (see the playing_cards.py example):

class Club(BaseSketchObject):
    def __init__(
        self,
        height: float,
        rotation: float = 0,
        align: tuple[Align, Align] = (Align.CENTER, Align.CENTER),
        mode: Mode = Mode.ADD,
    ):
        with BuildSketch() as club:
            with BuildLine():
                l0 = Line((0, -188), (76, -188))
                b0 = Bezier(l0 @ 1, (61, -185), (33, -173), (17, -81))
                b1 = Bezier(b0 @ 1, (49, -128), (146, -145), (167, -67))
                b2 = Bezier(b1 @ 1, (187, 9), (94, 52), (32, 18))
                b3 = Bezier(b2 @ 1, (92, 57), (113, 188), (0, 188))
                mirror(about=Plane.YZ)
            make_face()
            scale(by=height / club.sketch.bounding_box().size.Y)
        super().__init__(obj=club.sketch, rotation=rotation, align=align, mode=mode)

Here the new custom object class is called Club and it’s a sub-class of BaseSketchObject . The __init__ method contains all of the parameters used to instantiate the custom object, specially a height, rotation, align, and mode - your objects may contain a sub or super set of these parameters but should always contain a mode parameter such that it can be combined with a builder’s object.

Next is the creation of the object itself, in this case a sketch of the club suit.

The final line calls the __init__ method of the super class - i.e. BaseSketchObject with its parameters.

That’s it, now the Club object can be used anywhere a Circle would be used - with either the Algebra or Builder API.