Operations
Operations are functions that take objects as inputs and transform them into new objects. For example, a 2D Sketch can be extruded to create a 3D Part. All operations are Python functions which can be applied using both the Algebra and Builder APIs. It’s important to note that objects created by operations are not affected by Locations, meaning their position is determined solely by the input objects used in the operation.
Here are a couple ways to use extrude(), in Builder and Algebra mode:
with BuildPart() as cylinder:
with BuildSketch():
Circle(radius)
extrude(amount=height)
cylinder = extrude(Circle(radius), amount=height)
The following table summarizes all of the available operations. Operations marked as 1D are applicable to BuildLine and Algebra Curve, 2D to BuildSketch and Algebra Sketch, 3D to BuildPart and Algebra Part.
Operation |
Description |
0D |
1D |
2D |
3D |
Example |
|---|---|---|---|---|---|---|
Add object to builder |
✓ |
✓ |
✓ |
|||
Add bounding box as Shape |
✓ |
✓ |
✓ |
|||
Bevel Vertex or Edge |
✓ |
✓ |
||||
Draw 2D Shape into 3D |
✓ |
|||||
Radius Vertex or Edge |
✓ |
✓ |
||||
Round-off Face along given Edge |
✓ |
|||||
Create 3D Shape from sections |
✓ |
|||||
Create sheet metal parts |
✓ |
|||||
Create a Face from Edges |
✓ |
|||||
Create Convex Hull from Edges |
✓ |
|||||
Mirror about Plane |
✓ |
✓ |
✓ |
|||
Inset or outset Shape |
✓ |
✓ |
✓ |
|||
Project points, lines or Faces |
✓ |
✓ |
✓ |
|||
Create workplane for projection |
||||||
Swing 2D Shape about Axis |
✓ |
|||||
Change size of Shape |
✓ |
✓ |
✓ |
|||
Generate 2D slices from 3D Shape |
✓ |
|||||
Divide object by Plane |
✓ |
✓ |
✓ |
|||
Extrude 1/2D section(s) along path |
✓ |
✓ |
||||
Expand 2D section(s) |
✓ |
|||||
Convert lines to faces |
✓ |
The following table summarizes all of the selectors that can be used within the scope of a Builder. Note that they will extract objects from the builder that is currently within scope without it being explicitly referenced.
Builder |
||||
|---|---|---|---|---|
Selector |
Description |
Line |
Sketch |
Part |
Select edge from current builder |
✓ |
✓ |
✓ |
|
Select edges from current builder |
✓ |
✓ |
✓ |
|
Select face from current builder |
✓ |
✓ |
||
Select faces from current builder |
✓ |
✓ |
||
Select solid from current builder |
✓ |
|||
Select solids from current builder |
✓ |
|||
Select vertex from current builder |
✓ |
✓ |
✓ |
|
Select vertices from current builder |
✓ |
✓ |
✓ |
|
Select wire from current builder |
✓ |
✓ |
✓ |
|
Select wires from current builder |
✓ |
✓ |
✓ |
|
Reference
- add(objects: Union[Edge, Wire, Face, Solid, Compound, Builder, Iterable[Union[Edge, Wire, Face, Solid, Compound, Builder]]], rotation: Optional[Union[float, tuple[float, float, float], Rotation]] = None, clean: bool = True, mode: Mode = Mode.ADD) Compound[source]
Generic Object: Add Object to Part or Sketch
Add an object to a builder.
- BuildPart:
Edges and Wires are added to pending_edges. Compounds of Face are added to pending_faces. Solids or Compounds of Solid are combined into the part.
- BuildSketch:
Edges and Wires are added to pending_edges. Compounds of Face are added to sketch.
- BuildLine:
Edges and Wires are added to line.
- bounding_box(objects: Optional[Union[Shape, Iterable[Shape]]] = None, mode: Mode = Mode.PRIVATE) Union[Sketch, Part][source]
Generic Operation: Add Bounding Box
Applies to: BuildSketch and BuildPart
Add the 2D or 3D bounding boxes of the object sequence
- chamfer(objects: Union[Edge, Vertex, Iterable[Union[Edge, Vertex]]], length: float, length2: Optional[float] = None, angle: Optional[float] = None, reference: Optional[Union[Edge, Face]] = None) Union[Sketch, Part][source]
Generic Operation: chamfer
Applies to 2 and 3 dimensional objects.
Chamfer the given sequence of edges or vertices.
- Parameters
objects (Union[Edge,Vertex] or Iterable of) – edges or vertices to chamfer
length (float) – chamfer size
length2 (float, optional) – asymmetric chamfer size. Defaults to None.
angle (float, optional) – chamfer angle in degrees. Defaults to None.
reference (Union[Edge,Face]) – identifies the side where length is measured. Edge(s) must be part of the face. Vertex/Vertices must be part of edge
- Raises
ValueError – no objects provided
ValueError – objects must be Edges
ValueError – objects must be Vertices
ValueError – Only one of length2 or angle should be provided
ValueError – reference can only be used in conjunction with length2 or angle
- extrude(to_extrude: Optional[Union[Face, Sketch]] = None, amount: Optional[float] = None, dir: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None, until: Optional[Until] = None, target: Optional[Union[Solid, Compound]] = None, both: bool = False, taper: float = 0.0, clean: bool = True, mode: Mode = Mode.ADD) Part[source]
Part Operation: extrude
Extrude a sketch or face by an amount or until another object.
- Parameters
to_extrude (Union[Face, Sketch], optional) – object to extrude. Defaults to None.
amount (float, optional) – distance to extrude, sign controls direction. Defaults to None.
dir (VectorLike, optional) – direction. Defaults to None.
until (Until, optional) – extrude limit. Defaults to None.
target (Shape, optional) – extrude until target. Defaults to None.
both (bool, optional) – extrude in both directions. Defaults to False.
taper (float, optional) – taper angle. Defaults to 0.0.
clean (bool, optional) – Remove extraneous internal structure. Defaults to True.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.
- Raises
ValueError – No object to extrude
ValueError – No target object
- Returns
extruded object
- Return type
- fillet(objects: Union[Edge, Vertex, Iterable[Union[Edge, Vertex]]], radius: float) Union[Sketch, Part, Curve][source]
Generic Operation: fillet
Applies to 2 and 3 dimensional objects.
Fillet the given sequence of edges or vertices. Note that vertices on either end of an open line will be automatically skipped.
- full_round(edge: Edge, invert: bool = False, voronoi_point_count: int = 100, mode: Mode = Mode.REPLACE) tuple[build123d.topology.Sketch, build123d.geometry.Vector, float][source]
Sketch Operation: full_round
Given an edge from a Face/Sketch, modify the face by replacing the given edge with the arc of the Voronoi largest empty circle that will fit within the Face. This “rounds off” the end of the object.
- Parameters
edge (Edge) – target Edge to remove
invert (bool, optional) – make the arc concave instead of convex. Defaults to False.
voronoi_point_count (int, optional) – number of points along each edge used to create the voronoi vertices as potential locations for the center of the largest empty circle. Defaults to 100.
mode (Mode, optional) – combination mode. Defaults to Mode.REPLACE.
- Raises
ValueError – Invalid geometry
- Returns
A tuple where the first value is the modified shape, the second the geometric center of the arc, and the third the radius of the arc
- Return type
- loft(sections: Optional[Union[Face, Sketch, Iterable[Union[Vertex, Face, Sketch]]]] = None, ruled: bool = False, clean: bool = True, mode: Mode = Mode.ADD) Part[source]
Part Operation: loft
Loft the pending sketches/faces, across all workplanes, into a solid.
- Parameters
sections (Vertex, Face, Sketch) – slices to loft into object. If not provided, pending_faces will be used. If vertices are to be used, a vertex can be the first, last, or first and last elements.
ruled (bool, optional) – discontiguous layer tangents. Defaults to False.
clean (bool, optional) – Remove extraneous internal structure. Defaults to True.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.
- make_brake_formed(thickness: float, station_widths: Union[float, Iterable[float]], line: Optional[Union[Edge, Wire, Curve]] = None, side: Side = Side.LEFT, kind: Kind = Kind.ARC, clean: bool = True, mode: Mode = Mode.ADD) Part[source]
Create a part typically formed with a sheet metal brake from a single outline. The line parameter describes how the material is to be bent. Either a single width value or a width value at each vertex or station is provided to control the width of the end part. Note that if multiple values are provided there must be one for each vertex and that the resulting part is composed of linear segments.
- Parameters
thickness (float) – sheet metal thickness
station_widths (Union[float, Iterable[float]]) – width of part at each vertex or a single value. Note that this width is perpendicular to the provided line/plane.
line (Union[Edge, Wire, Curve], optional) – outline of part. Defaults to None.
side (Side, optional) – offset direction. Defaults to Side.LEFT.
kind (Kind, optional) – offset intersection type. Defaults to Kind.ARC.
clean (bool, optional) – clean the resulting solid. Defaults to True.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.
- Raises
ValueError – invalid line type
ValueError – not line provided
ValueError – line not suitable
ValueError – incorrect # of width values
- Returns
sheet metal part
- Return type
- make_face(edges: Optional[Union[Edge, Iterable[Edge]]] = None, mode: Mode = Mode.ADD) Sketch[source]
Sketch Operation: make_face
Create a face from the given perimeter edges.
- make_hull(edges: Optional[Union[Edge, Iterable[Edge]]] = None, mode: Mode = Mode.ADD) Sketch[source]
Sketch Operation: make_hull
Create a face from the convex hull of the given edges
- mirror(objects: Optional[Union[Edge, Wire, Face, Compound, Curve, Sketch, Part, Iterable[Union[Edge, Wire, Face, Compound, Curve, Sketch, Part]]]] = None, about: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, -1.00, 0.00)), mode: Mode = Mode.ADD) Union[Curve, Sketch, Part, Compound][source]
Generic Operation: mirror
Applies to 1, 2, and 3 dimensional objects.
Mirror a sequence of objects over the given plane.
- offset(objects: Optional[Union[Edge, Face, Solid, Compound, Iterable[Union[Edge, Face, Solid, Compound]]]] = None, amount: float = 0, openings: Optional[Union[Face, list[build123d.topology.Face]]] = None, kind: Kind = Kind.ARC, side: Side = Side.BOTH, closed: bool = True, min_edge_length: Optional[float] = None, mode: Mode = Mode.REPLACE) Union[Curve, Sketch, Part, Compound][source]
Generic Operation: offset
Applies to 1, 2, and 3 dimensional objects.
Offset the given sequence of Edges, Faces, Compound of Faces, or Solids. The kind parameter controls the shape of the transitions. For Solid objects, the openings parameter allows selected faces to be open, like a hollow box with no lid.
- Parameters
objects (Union[Edge, Face, Solid, Compound] or Iterable of) – objects to offset
amount (float) – positive values external, negative internal
openings (list[Face], optional) – Defaults to None.
kind (Kind, optional) – transition shape. 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.
min_edge_length (float, optional) – repair degenerate edges generated by offset by eliminating edges of minimum length in offset wire. Defaults to None.
mode (Mode, optional) – combination mode. Defaults to Mode.REPLACE.
- Raises
ValueError – missing objects
ValueError – Invalid object type
- project(objects: Optional[Union[Edge, Face, Wire, Vector, Vertex, Iterable[Union[Edge, Face, Wire, Vector, Vertex]]]] = None, workplane: Optional[Plane] = None, target: Optional[Union[Solid, Compound, Part]] = None, mode: Mode = Mode.ADD) Union[Curve, Sketch, Compound, ShapeList[Vector]][source]
Generic Operation: project
Applies to 0, 1, and 2 dimensional objects.
Project the given objects or points onto a BuildLine or BuildSketch workplane in the direction of the normal of that workplane. When projecting onto a sketch a Face(s) are generated while Edges are generated for BuildLine. Will only use the first if BuildSketch has multiple active workplanes. In algebra mode a workplane must be provided and the output is either a Face, Curve, Sketch, Compound, or ShapeList[Vector].
Note that only if mode is not Mode.PRIVATE only Faces can be projected into BuildSketch and Edge/Wires into BuildLine.
- Parameters
- Raises
ValueError – project doesn’t accept group_by
ValueError – Either a workplane must be provided or a builder must be active
ValueError – Points and faces can only be projected in PRIVATE mode
ValueError – Edges, wires and points can only be projected in PRIVATE mode
RuntimeError – BuildPart doesn’t have a project operation
- project_workplane(origin: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float], Vertex], x_dir: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float], Vertex], projection_dir: Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]], distance: float) Plane[source]
Part Operation: project_workplane
Return a plane to be used as a BuildSketch or BuildLine workplane with a known origin and x direction. The plane’s origin will be the projection of the provided origin (in 3D space). The plane’s x direction will be the projection of the provided x_dir (in 3D space).
- Parameters
- Raises
RuntimeError – Not suitable for BuildLine or BuildSketch
ValueError – x_dir perpendicular to projection_dir
- Returns
workplane aligned for projection
- Return type
- revolve(profiles: Optional[Union[Face, Iterable[Face]]] = None, axis: Axis = ((0.0, 0.0, 0.0), (0.0, 0.0, 1.0)), revolution_arc: float = 360.0, clean: bool = True, mode: Mode = Mode.ADD) Part[source]
Part Operation: Revolve
Revolve the profile or pending sketches/face about the given axis.
- Parameters
profiles (Face, optional) – 2D profile(s) to revolve.
axis (Axis, optional) – axis of rotation. Defaults to Axis.Z.
revolution_arc (float, optional) – angular size of revolution. Defaults to 360.0.
clean (bool, optional) – Remove extraneous internal structure. Defaults to True.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.
- Raises
ValueError – Invalid axis of revolution
- scale(objects: Optional[Union[Shape, Iterable[Shape]]] = None, by: Union[float, tuple[float, float, float]] = 1, mode: Mode = Mode.REPLACE) Union[Curve, Sketch, Part, Compound][source]
Generic Operation: scale
Applies to 1, 2, and 3 dimensional objects.
Scale a sequence of objects. Note that when scaling non-uniformly across the three axes, the type of the underlying object may change to bspline from line, circle, etc.
- section(obj: Optional[Part] = None, section_by: Union[Plane, Iterable[Plane]] = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, -1.00, 0.00)), height: float = 0.0, clean: bool = True, mode: Mode = Mode.PRIVATE) Sketch[source]
Part Operation: section
Slices current part at the given height by section_by or current workplane(s).
- Parameters
obj (Part, optional) – object to section. Defaults to None.
section_by (Plane, optional) – plane(s) to section object. Defaults to None.
height (float, optional) – workplane offset. Defaults to 0.0.
clean (bool, optional) – Remove extraneous internal structure. Defaults to True.
mode (Mode, optional) – combination mode. Defaults to Mode.INTERSECT.
- split(objects: Optional[Union[Edge, Wire, Face, Solid, Iterable[Union[Edge, Wire, Face, Solid]]]] = None, bisect_by: Plane = Plane(o=(0.00, 0.00, 0.00), x=(1.00, 0.00, 0.00), z=(0.00, -1.00, 0.00)), keep: Keep = Keep.TOP, mode: Mode = Mode.REPLACE)[source]
Generic Operation: split
Applies to 1, 2, and 3 dimensional objects.
Bisect object with plane and keep either top, bottom or both.
- Parameters
- Raises
ValueError – missing objects
- sweep(sections: Optional[Union[Compound, Edge, Wire, Face, Solid, Iterable[Union[Compound, Edge, Wire, Face, Solid]]]] = None, path: Optional[Union[Curve, Edge, Wire, Iterable[Edge]]] = None, multisection: bool = False, is_frenet: bool = False, transition: Transition = Transition.TRANSFORMED, normal: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None, binormal: Optional[Union[Edge, Wire]] = None, clean: bool = True, mode: Mode = Mode.ADD) Union[Part, Sketch][source]
Generic Operation: sweep
Sweep pending 1D or 2D objects along path.
- Parameters
sections (Union[Compound, Edge, Wire, Face, Solid]) – cross sections to sweep into object
path (Union[Curve, Edge, Wire], optional) – path to follow. Defaults to context pending_edges.
multisection (bool, optional) – sweep multiple on path. Defaults to False.
is_frenet (bool, optional) – use frenet algorithm. Defaults to False.
transition (Transition, optional) – discontinuity handling option. Defaults to Transition.RIGHT.
normal (VectorLike, optional) – fixed normal. Defaults to None.
binormal (Union[Edge, Wire], optional) – guide rotation along path. Defaults to None.
clean (bool, optional) – Remove extraneous internal structure. Defaults to True.
mode (Mode, optional) – combination. Defaults to Mode.ADD.
- thicken(to_thicken: Optional[Union[Face, Sketch]] = None, amount: Optional[float] = None, normal_override: Optional[Union[Vector, tuple[float, float], tuple[float, float, float], Iterable[float]]] = None, both: bool = False, clean: bool = True, mode: Mode = Mode.ADD) Part[source]
Part Operation: thicken
Create a solid(s) from a potentially non planar face(s) by thickening along the normals.
- Parameters
to_thicken (Union[Face, Sketch], optional) – object to thicken. Defaults to None.
amount (float, optional) – distance to extrude, sign controls direction. Defaults to None.
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.
both (bool, optional) – thicken in both directions. Defaults to False.
clean (bool, optional) – Remove extraneous internal structure. Defaults to True.
mode (Mode, optional) – combination mode. Defaults to Mode.ADD.
- Raises
ValueError – No object to extrude
ValueError – No target object
- Returns
extruded object
- Return type
- trace(lines: Optional[Union[Curve, Edge, Wire, Iterable[Union[Curve, Edge, Wire]]]] = None, line_width: float = 1, mode: Mode = Mode.ADD) Sketch[source]
Sketch Operation: trace
Convert edges, wires or pending edges into faces by sweeping a perpendicular line along them.
- Parameters
- Raises
ValueError – No objects to trace
- Returns
Traced lines
- Return type
- edge(self, select: Select = Select.ALL) Edge
Return Edge
Return an edge.
- edges(self, select: Select = Select.ALL) ShapeList[Edge]
Return Edges
Return either all or the edges created during the last operation.
- face(self, select: Select = Select.ALL) Face
Return Face
Return a face.
- faces(self, select: Select = Select.ALL) ShapeList[Face]
Return Faces
Return either all or the faces created during the last operation.
- solid(self, select: Select = Select.ALL) Solid
Return Solid
Return a solid.
- solids(self, select: Select = Select.ALL) ShapeList[Solid]
Return Solids
Return either all or the solids created during the last operation.
- vertex(self, select: Select = Select.ALL) Vertex
Return Vertex
Return a vertex.
- vertices(self, select: Select = Select.ALL) ShapeList[Vertex]
Return Vertices
Return either all or the vertices created during the last operation.
- wire(self, select: Select = Select.ALL) Wire
Return Wire
Return a wire.