Skip to content

API Reference

Complete reference for all public llmcad symbols.

Shapes

Box(width, length, height, name="", color=None) -> Body

Create a rectangular box centered at the origin.

  • width (float) --- extent along X axis
  • length (float) --- extent along Y axis
  • height (float) --- extent along Z axis
  • name (str) --- optional name
  • color (str | tuple) --- optional color

Named faces: top, bottom, front, back, left, right

Cylinder(diameter, height, name="", color=None) -> Body

Create a cylinder centered at the origin, axis along Z.

  • diameter (float) --- cylinder diameter (not radius)
  • height (float) --- extent along Z axis
  • name (str) --- optional name
  • color (str | tuple) --- optional color

Named faces: top, bottom, wall

Sphere(diameter, name="", color=None) -> Body

Create a sphere centered at the origin.

  • diameter (float) --- sphere diameter (not radius)
  • name (str) --- optional name
  • color (str | tuple) --- optional color

Named faces: surface

Sketches

Rect(width, height) -> SketchPrimitive

Create a rectangular sketch centered at origin on XY plane.

  • width (float) --- width along X
  • height (float) --- height along Y

Circle(diameter) -> SketchPrimitive

Create a circular sketch centered at origin on XY plane.

  • diameter (float) --- circle diameter (not radius)

Ellipse(width, height) -> SketchPrimitive

Create an elliptical sketch centered at origin on XY plane.

  • width (float) --- full width along X
  • height (float) --- full height along Y

Polygon(points) -> SketchPrimitive

Create a polygonal sketch from a list of (x, y) vertices on XY plane.

  • points (list[tuple]) --- list of (x, y) tuples (minimum 3, closed automatically)

Text(txt, size, font="Arial") -> SketchPrimitive

Render text into a sketch shape on XY plane.

  • txt (str) --- text string to render
  • size (float) --- font size in model units
  • font (str) --- system font name (default "Arial")

Sketch

Turtle-style sketch builder for complex 2D profiles.

Methods:

  • start(x, y) -> Sketch --- Set the starting point.
  • line_to(x, y, name=None) -> Sketch --- Draw a line to (x, y).
  • arc_to(x, y, radius=None, sagitta=None, name=None) -> Sketch --- Draw an arc to (x, y). Specify radius (sign controls direction) or sagitta (arc height from chord).
  • close(name=None) -> Sketch --- Close the sketch back to the start.
  • place_on(face_ref, at=None) -> PlacedSketch --- Place on a face.
  • place_at(origin, x_dir=None, normal=None) -> PlacedSketch --- Place at position.
  • to_placed_sketch() -> PlacedSketch --- Convert to PlacedSketch on default XY plane.

Named segments become named faces after extrusion (tag inheritance).

SketchPrimitive

Base class for sketch shapes.

Methods:

  • place_on(face_ref, at=None) -> PlacedSketch --- Place on a face, optionally at a specific position.
  • place_at(origin, x_dir=None, normal=None) -> PlacedSketch --- Place at an arbitrary 3D position and orientation.
  • to_placed_sketch() -> PlacedSketch --- Convert to PlacedSketch on default XY plane.

PlacedSketch

A sketch positioned in 3D space, ready for extrusion.

Properties:

  • normal -> Vec3 --- The extrusion direction (face normal or +Z).

Operations

extrude(sketch, amount=None, through=False, to=None, name="") -> Body

Extrude a 2D sketch into a 3D body.

  • sketch (PlacedSketch | SketchPrimitive | Sketch) --- the sketch to extrude
  • amount (float) --- extrusion distance (positive = outward, negative = inward)
  • through (bool) --- if True, extrude in both directions through the host body (distance from bounding box)
  • to (FaceRef) --- extrude until reaching this face
  • name (str) --- name for the resulting body

revolve(sketch, axis=None, angle=360, name="") -> Body

Revolve a 2D sketch around an axis.

  • sketch (PlacedSketch | SketchPrimitive | Sketch) --- the sketch to revolve
  • axis --- axis of rotation (gp_Ax1, or body.center_axis). Default: Z axis
  • angle (float) --- revolution angle in degrees (default 360)
  • name (str) --- name for the resulting body

loft(sketches, heights, name="") -> Body

Loft between sketches at specified Z-heights.

  • sketches (list) --- list of sketches to loft between
  • heights (list[float]) --- Z-height for each sketch
  • name (str) --- name for the resulting body

Named faces: top (highest Z), bottom (lowest Z).

sweep(path, cross_section=None, name="") -> Body

Sweep a cross-section along a path.

  • path (Sketch | PlacedSketch) --- the sweep path (wire)
  • cross_section (PlacedSketch | SketchPrimitive | Sketch) --- the profile to sweep
  • name (str) --- name for the resulting body

fillet(edges, radius, name="") -> Body

Round edges with a circular cross-section.

  • edges (EdgeRef | list[EdgeRef] | EdgeCollection) --- edges to fillet
  • radius (float) --- fillet radius in mm
  • name (str) --- optional name

chamfer(edges, size, name="") -> Body

Bevel edges with a flat cut.

  • edges (EdgeRef | list[EdgeRef] | EdgeCollection) --- edges to chamfer
  • size (float) --- chamfer size in mm
  • name (str) --- optional name

shell(body, thickness, open=None, name="") -> Body

Hollow out a body, leaving walls of the specified thickness.

  • body (Body) --- the body to hollow
  • thickness (float) --- wall thickness in mm
  • open (list[FaceRef]) --- faces to remove (leave as openings)
  • name (str) --- optional name

After shelling, faces gain .inner and .outer variants.

split(body, tool=None, name="") -> list[Body]

Split body into pieces using a plane or another body. Returns all pieces sorted by volume (largest first).

  • body (Body) --- the body to split
  • tool --- a Body, gp_Pln plane, or None. Default: XZ plane
  • name (str) --- optional name

mirror(body, plane=None, name="") -> Body

Mirror a body about a plane.

  • body (Body) --- the body to mirror
  • plane --- mirror plane (gp_Ax2, gp_Pln). Default: YZ plane
  • name (str) --- optional name

Assembly

place(part, on, at=None, name="") -> Body

Place a part so its center aligns with a position on a face.

  • part (Body) --- the body to place
  • on (FaceRef) --- face to place on
  • at (Position) --- position on the face (default: face center)
  • name (str) --- optional name

Assembly(name="")

A collection of parts and joints forming a mechanical assembly.

Methods:

  • add(part, name="") -> Assembly --- Add a part.
  • add_joint(joint) -> Assembly --- Add a joint.
  • build() -> Body --- Combine all parts into a single Body.

Properties:

  • part -> TopoDS_Shape --- Combined compound shape.

RevoluteJoint

A revolute (rotational) joint between two parts.

Fields:

  • axis (gp_Ax1) --- rotation axis
  • part_a (str) --- first part name
  • part_b (str) --- second part name
  • range (tuple | None) --- (min_angle, max_angle) in degrees

Body

Body

A 3D body with named faces, edges, and boolean operations. Bodies are immutable --- boolean ops return new instances.

Properties:

Property Type Description
name str Body name
part TopoDS_Shape Underlying OCP shape
top FaceRef Top face (+Z)
bottom FaceRef Bottom face (-Z)
front FaceRef Front face (-Y)
back FaceRef Back face (+Y)
right FaceRef Right face (+X)
left FaceRef Left face (-X)
wall FaceRef \| None Cylindrical face (if exists)
faces FaceCollection Dict-like face access
edges EdgeCollection Edge collection
exterior_edges list[EdgeRef] All exterior edges
position Position Center of bounding box
volume float Volume in mm^3
area float Total surface area in mm^2
center_of_mass Vec3 Volumetric center of mass
color tuple \| None RGBA color tuple

Boolean operators:

Operator Operation
body + other Union (fuse)
body - other Cut (subtract)
body & other Intersect

Methods:

FaceRef

FaceRef

A named reference to a face with local coordinate system.

Properties:

Property Type Description
name str Face name
normal Vec3 Outward normal
center Position Face center position
width float Extent along local x_dir
height float Extent along local y_dir
area float Surface area (mm^2)
edges list[EdgeRef] All edges
left_edge EdgeRef Leftmost edge
right_edge EdgeRef Rightmost edge
top_edge EdgeRef Topmost edge
bottom_edge EdgeRef Bottommost edge
long_edges list[EdgeRef] Longest edges
corners CornerSet Named corners (TL, TR, BL, BR)
inner FaceRef \| None Inner face (after shell)
outer FaceRef \| None Outer face (after shell)

EdgeRef

EdgeRef

A reference to an edge.

Properties:

Property Type Description
midpoint Position Edge center position
length float Edge length (mm)
start Position Start point
end Position End point

Operators:

  • edge + edge -> list[EdgeRef] --- Combine edges for fillet/chamfer.

CornerSet

CornerSet

Named corners of a rectangular face.

Properties:

Property Type Description
TL Position Top-left corner
TR Position Top-right corner
BL Position Bottom-left corner
BR Position Bottom-right corner

Iterable: for corner in face.corners: yields all four corners.

Position

Position

A 3D point with face-local offset capabilities.

Properties:

Property Type Description
x float Global X coordinate
y float Global Y coordinate
z float Global Z coordinate
vec Vec3 Underlying vector

Methods:

  • offset(dx=0, dy=0, dz=0) -> Position --- Offset in face-local coordinates (dx=right, dy=up, dz=normal).
  • inset(dx, dy) -> Position --- Move toward face center from a corner.
  • projected_onto(face_ref) -> Position --- Project onto another face's plane.
  • distance_to(other) -> float --- Euclidean distance.

Selectors

X, Y, Z

Axis objects that create filter predicates via Python comparison operators. Import alongside shapes:

from llmcad import Box, X, Y, Z

Operators:

Expression Description
Z.max All items at the maximum Z position
Z.min All items at the minimum Z position
Z == 5.0 Items at Z = 5.0 (with tolerance)
Z > 0 Items with Z center > 0
Z < 10 Items with Z center < 10
Z >= 0 Items with Z center >= 0
Z <= 10 Items with Z center <= 10
Z.between(2, 8) Items with Z center in [2, 8]
(Z > 0) & (X > 0) Compound filter (both must match)

These return AxisFilter objects, passed to filter() as positional arguments.

ShapeList

ShapeList

A list subclass returned by filter() and sort(), supporting further chaining.

Methods:

  • filter(*predicates, type=None, axis=None, normal=None) -> ShapeList --- Filter items (same syntax as collection filter).
  • sort(axis=None, key=None) -> ShapeList --- Sort items by axis position or property.

Indexing:

  • shape_list[0] --- First item (e.g., lowest after sort).
  • shape_list[-1] --- Last item (e.g., highest after sort).
  • shape_list[2:5] --- Slice (returns ShapeList).

FaceCollection

FaceCollection

Dict-like access to named faces on a body, with filtering and sorting.

Access by name:

  • body.faces["name"] --- Get face by name.
  • "name" in body.faces --- Check if face exists.
  • body.faces.start --- Shortcut for body.faces["_start"].
  • body.faces.end --- Shortcut for body.faces["_end"].

Methods:

  • all() -> ShapeList[FaceRef] --- All faces.
  • filter(*predicates, type=None, normal=None) -> ShapeList[FaceRef] --- Filter faces.
  • sort(axis=None, key=None) -> ShapeList[FaceRef] --- Sort faces.

Filter parameters:

Parameter Values Description
positional Z.max, Z > 0, etc. Axis predicates
type "plane", "cylinder", "sphere", "cone", "torus", "bspline" Geometry type
normal "+Z", "-Z", "Z", "+X", "-X", "X", "+Y", "-Y", "Y" Normal direction

Sort parameters:

Parameter Values Description
axis "x", "y", "z" Sort by center position along axis
key "area" Sort by face area

Iterable: for face in body.faces: yields all FaceRef objects.

EdgeCollection

EdgeCollection

Access to edges with filtering and sorting.

Methods:

  • all() -> ShapeList[EdgeRef] --- All edges.
  • filter(*predicates, type=None, axis=None) -> ShapeList[EdgeRef] --- Filter edges.
  • sort(axis=None, key=None) -> ShapeList[EdgeRef] --- Sort edges.

Filter parameters:

Parameter Values Description
positional Z.max, Z > 0, etc. Axis predicates
type "circle", "line", "bspline", "ellipse" Geometry type
axis "X", "Y", "Z" Edges parallel to an axis

Sort parameters:

Parameter Values Description
axis "x", "y", "z" Sort by center position along axis
key "length", "radius" Sort by edge property

Iterable: for edge in body.edges: yields all EdgeRef objects.

Debug Functions

snapshot(body, name, views=None, output_dir=".") -> str

Render multi-view PNG snapshot. Returns path to saved image.

show(body, name=None)

Show body in OCP CAD Viewer (VSCode extension). Requires ocp_vscode.

show_faces(body, name="faces", output_dir=".") -> str

Render isometric view and print face information.

show_edges(body, name="edges", output_dir=".") -> str

Render isometric view with edge count.

measure(a, b) -> float

Print and return distance between two positions.

Export Functions

export_step(body, path) -> str

Export body to STEP format (AP214). Returns path to saved file.

  • body (Body) --- the body to export
  • path (str) --- output file path (e.g. "part.step")

export_stl(body, path, deflection=0.05) -> str

Export body to STL format. Returns path to saved file.

  • body (Body) --- the body to export
  • path (str) --- output file path (e.g. "part.stl")
  • deflection (float) --- mesh quality, smaller = finer (default: 0.05)

export_glb(body, path, deflection=0.05) -> str

Export body to GLB (binary glTF 2.0) format. Returns path to saved file.

  • body (Body) --- the body to export
  • path (str) --- output file path (e.g. "part.glb")
  • deflection (float) --- mesh quality, smaller = finer (default: 0.05)