User Manual

1. Getting Started & the Document Model

This chapter sets up the vocabulary and mental model the rest of the manual assumes: what kind of app FlywheelCAD is, how the GUI and the Python script relate to each other, and what a document actually is on disk. Later chapters (Sketching, Selection, Bodies, Components) build on this foundation.

1.1 What FlywheelCAD is

FlywheelCAD is a Python-first, constraint-driven CAD application. You draw and edit sketches interactively in the UI, and you can script everything in .py files — plain Python. Either way, geometry is solved by constraints and dimensions, and closed sketch areas become 3D bodies (extrude/revolve) that you combine with boolean operations. The pipeline is always the same: 2D sketch → region → 3D solid. You draw constrained 2D geometry on a plane, identify a closed region, then extrude/revolve/loft it into a body; bodies then combine via booleans and transforms. Units are unitless numbers — treat them as millimetres — and angles are always in degrees.

The workflow is intentionally hybrid: UI for fast interaction, Python for reproducibility and reuse.

1.2 The script ⇄ GUI duality

A FlywheelCAD document is a Python script. Opening a document re-executes the script to rebuild the geometry; saving writes the script. There is no separate binary model — the script is the source of truth. The script doesn't manipulate the model directly: each cad.*(...) call emits a command, and the host runs the accumulated commands in order — solving 2D sketches with a constraint solver, then building the 3D solids.

Every script starts the same way:

# the entire boilerplate
from flywheelcad import *
cad = FlywheelCAD()

When executed, this Python script emits intermediate CAD commands to stdout; the app parses and executes those commands. In practice this means the UI and the script panel are two views onto the same thing — a reasonable way to work is to rough in geometry and constraints in the UI, then treat the script panel as the source of truth for repeatability, moving reusable generation logic out into sibling helper modules as a design grows (see §1.5).

1.3 3D mode and Sketch mode GUI

The window has five main parts:

The main canvas is in one of two modes at a time:

• 3D mode — orbit/pan/zoom the model, select bodies and topology points, create custom sketch planes from selected 3D points, and run boolean operations on selected bodies.
• Sketch mode — a single 2D sketch plane with its own toolbar for drawing tools, constraints, dimensions, and variables.

Switch views from the View menu: ⌘0 is the 3D model, ⌘1–⌘9 open sketch planes in sidebar order (further planes live in an "Other Sketches" submenu). The View menu also holds the projection toggle, Zoom to Fit (⇧⌘F), and the Mesh Quality submenu. The toolbar's mode pull-down offers the same plane list plus the two "New Sketch…" commands.

This section is only an orientation. Drawing tools, constraint/dimension entry, and selection behavior in each mode are covered in the Sketching and Selection chapters.

1.4 Running scripts & the busy state

The right panel's script editor has an Execute button. Running the script re-executes it from scratch: the script emits intermediate CAD commands to stdout, and the app parses and executes those commands to rebuild the document's sketches and bodies.

The button's full behaviour is clear & run: the existing model is discarded and rebuilt from the script text as it currently stands. There is no partial-apply — the script is the definition, so running it is how any edit takes effect, whether you typed it yourself or the GUI appended it for you.

What the busy state looks like, and what it holds

While solving or replaying, the sketch canvas shows an overlay rather than a beachball-style block: Executing Script... while a script is being replayed, Computing... while the solver is working. The window stays responsive throughout.

Two things behave differently while a run is in flight:

• Picking is held. Clicks that would select a point, area or body are refused until the run finishes — the geometry on screen still belongs to the previous run, so a pick would resolve against a model that is about to be replaced. Camera navigation (orbit, pan, zoom) keeps working.
• A failed run does not leave you with a half-built model. How that is achieved depends on how far the run got. An error caught before any geometry changes — a Python exception, a parse error, a validation refusal — leaves the existing model completely untouched. A failure during the rebuild is different: a full run clears the model before replaying it, so there genuinely is a torn state at that moment, and the app recovers by automatically re-running the last script that completed cleanly. Either way you end up looking at a coherent model, and the error is reported.

Editing the script. That callout is about the model — the geometry has no undo stack of its own. The script pane, by contrast, is an ordinary text editor: ⌘Z and ⇧⌘Z undo and redo your typing, and ⌘F opens a find bar (⌥⌘F adds a replace row; Replace and Replace All are undoable with ⌘Z). Matching is a plain case-insensitive substring search — tick Case sensitive to change that. Operations performed in the 3D view or the sketch canvas are not undoable: they rewrite the script, and the way back is to edit the script text.

1.5 Documents: flat .py vs .fwcad bundles

A document is saved in one of two formats. The API is identical either way.

New documents start as bundles. Everything else works the same in both formats — the bundle's main.py is the script you edit, and its folder is the working directory that imports resolve against.

File-menu commands for bundles (all operate on the focused document):

• File ▸ Convert to Project Bundle… — package a flat .py (and its whole dependency closure) into a new .fwcad. The original flat file is left untouched.
• File ▸ Export as Flat Script… — the reverse: write a bundle back out as a flat .py plus its lib/ folder, for sharing as loose files.
• File ▸ Show Project Contents — reveal the document's files in Finder (the bundle's insides, or a flat file's folder). Because a bundle hides its contents behind one icon, use this rather than hand-navigating in Finder.
• File ▸ Open Script in External Editor — open the script (main.py inside a bundle) in your default .py editor. The document watches the file, so external edits round-trip back into the app.

1.6 A minimal first script Script

Every script starts with the same two-line boilerplate, then follows the 2D sketch → region → 3D solid pipeline from §1.1. This one sketches a circle on the xy plane, turns it into a region, and extrudes it into a cylinder:

from flywheelcad import *
cad = FlywheelCAD()

cad.with_sketch("xy")                 # draw on the standard XY plane
p1 = cad.point2d(0, 0)                # a 2D point, named "p1" from the LHS
c1 = cad.circle2d(p1, radius=10)      # circle: center point + radius

r1 = region(loop=[c1], inside=(0, 0)) # closed region from the circle

body1 = cad.extrude("xy", r1, 5)      # extrude the region 5 units

Run it (or open the document) and the app parses the emitted commands, solves the sketch, and builds body1 as a 10-unit-radius, 5-unit-tall cylinder.

1.7 Settings: per-user preferences (⌘,) GUI

FlywheelCAD ▸ Settings… (⌘,) opens a single three-tab window shared by every open document. Everything in it is a per-user, per-Mac preference about how the app looks and feels — not a property of any document. Nothing here is written into your script, and nothing here travels with a file you send to someone else. That boundary is deliberate: a document default with no cad.* call behind it would silently evaporate the moment the file was opened on another machine, so anything that must survive the trip lives in the script instead (per-body quality=, cad.set_cell_size, cad.set_color, export=).

General

Viewport

Interaction

2. Sketch Elements & Planes

This chapter covers the 2D geometry primitives you sketch with, and the planes they live on. Locking those primitives down with geometric and dimensional constraints is Chapter 3; turning a closed sketch into a 3D body (regions) is Chapter 4.

2.1 Sketch context & the built-in planes

cad.with_sketch(plane_name) sets the current sketch context — every 2D primitive you create afterward (point2d, line2d, circle2d, …) lands on that plane, until you call with_sketch again. There are three standard planes, plus any custom planes you define (§2.7):

Plane names are suffix-free — write xy, never xy_plane.

Each plane has an origin point. Calling with_sketch ensures that origin's reference exists and injects it into your script as a bare variable — origin_xy, origin_yz, origin_zx for the standard planes, or origin_<planeName> for a custom one — so you can use it immediately without assigning it yourself:

cad.with_sketch("xy")
c1 = cad.circle2d(origin_xy, 20)   # origin_xy exists as soon as with_sketch("xy") ran

2.2 Points

Two calls create points, in two different coordinate spaces:

cad.with_sketch("xy")
p1 = cad.point2d(0, 0)
p2 = cad.point2d(40, 0)
l1 = cad.line2d(p1, p2)

anchor = cad.point(10, 0, 5)   # a fixed 3D reference point, not tied to any sketch

cad.point takes an optional name= to control the script name it's emitted under, instead of an auto-generated one.

2.3 Lines & construction geometry

cad.line2d(p1, p2, construction=False) draws a line between two 2D points on the current sketch.

p1 = cad.point2d(-20, -10)
p2 = cad.point2d(20, -10)
l1 = cad.line2d(p1, p2)

Pass construction=True to any 2D primitive — not just lines — to make it a construction element: rendered dashed and excluded from region detection. Use construction geometry for guides, axes, and symmetry lines.

b = cad.point2d(0, -20)
t = cad.point2d(0, 20)
axis = cad.line2d(b, t, construction=True)   # a symmetry axis, not part of any region

In the sketch toolbar, the Construction toggle (shortcut X) does the same for elements you draw interactively — dashed, excluded from area detection.

2.4 Circles, arcs & ellipses

c1 = cad.circle2d(origin_xy, 20)

center = cad.point2d(0, 0)
start = cad.point2d(10, 0)
end = cad.point2d(0, 10)
a1 = cad.arc2d(center, start, end, clockwise=False)

f1 = cad.point2d(-8, 0)
f2 = cad.point2d(8, 0)
rim = cad.point2d(0, 6)
e1 = cad.ellipse2d(f1, f2, rim)

2.5 Splines

cad.spline2d(points, closed=False, construction=False) draws a cubic spline through an ordered list of 2D points. closed=True joins the last point back to the first.

p0 = cad.point2d(0, 0)
p1 = cad.point2d(10, 15)
p2 = cad.point2d(30, 10)
p3 = cad.point2d(40, 0)
s1 = cad.spline2d([p0, p1, p2, p3], closed=False)

2.6 Text Script

cad.text(string, size=10.0, font="Helvetica", at=(0.0, 0.0), angle=0.0, direction=None, distance=None, align="left", quality=None, export=None, plane=None) renders string as sketch geometry using a system font's glyph outlines. size is the target cap height in millimeters, calibrated against the font's actual measured cap height (not its raw em-square), so results look right across different fonts.

Two modes, selected by distance:

• Outline mode (distance=None, the default) — drops each glyph's closed contours into the current sketch as fixed splines. Counters (the bowl of "A"/"e", the loop of "g", …) become holes automatically when the sketch is later extruded via extrude(plane, region(loop=[...]), ...) — no manual hole bookkeeping.
• Solid mode (distance=<mm>, must be > 0) — additionally extrudes each glyph (counters cut as holes) into its own body on the current plane, distance mm deep. Glyphs are not unioned into one body — call cad.bool_union(...) yourself if you want a single solid.

plane= builds the text on that sketch plane without switching the ambient current sketch — handy for placing a label on a face while you keep working elsewhere. If that plane isn't the one shown in the 2D sketch view, the new outline splines won't be visible there until you cad.with_sketch(...) to it; a solid-mode body still meshes and renders in 3D regardless.

align ("left" | "center" | "right") positions the rendered run relative to at, the baseline-origin point in the current sketch's mm coordinates. angle (degrees, CCW-positive) rotates the whole run in the sketch plane about at; direction=(dx, dy) is sugar that sets angle from a vector, e.g. direction=(0, 1) runs the text "up" the +Y axis.

cad.with_sketch("xy")
letters = cad.text("HELLO", size=10, at=(0, 0))
# outline mode: letters is a list of 5 Refs, one per glyph's outer contour

label = cad.text("A1", size=8, distance=2, align="center")
# solid mode: extrudes each glyph 2mm deep, one body per glyph

cad.text returns one Ref per character position in string: the glyph's outer contour spline in outline mode, or the glyph's extruded body in solid mode. A position with no visible glyph (e.g. a space) creates nothing, so its Ref simply won't resolve if used. Hole/counter contours are still created and individually addressable as <name>_<i>_h<k> even though they aren't returned.

Body ▸ Text… GUI opens a sheet that authors the same cad.text(...) line for you: Text, Size (cap height, mm), Font, Align, At (pre-filled from a single selected sketch point), Extrude depth (blank = flat outline), and an Angle field under Advanced. The sheet always targets the current sketch plane — switch planes first (⌘1–⌘9 or the mode pull-down) if you want the text elsewhere.

2.7 Custom sketch planes

cad.create_sketch_plane(p1, p2, p3, name=None) defines a new sketch plane from three points: its origin is p1, and its normal is (p2 - p1) × (p3 - p1). The three points may be body-topology points (e.g. body1.v0), existing sketch points, or standalone reference points made with cad.point(...).

From body-topology points — after an extrude/revolve, a body exposes its far-face vertices as attributes (body.v0, body.v1, …; holes: body.h0_v0; symmetric extrudes split into body.pos_v0/body.neg_v0):

box = cad.extrude("xy", rect_region, 20)
endface = cad.create_sketch_plane(box.v0, box.v1, box.v2, name="endface")
cad.with_sketch("endface")

From explicit coordinates — useful for laying out a series of parametric planes, e.g. one plane per spanwise station before a cad.loft(...):

p1 = cad.point(0, 0, 0)
p2 = cad.point(100, 0, 0)
p3 = cad.point(0, 0, 20)
station1 = cad.create_sketch_plane(p1, p2, p3, name="station1")
cad.with_sketch("station1")

In the GUI, Sketch ▸ New Sketch from Coordinates… GUI opens a dialog with a sketch name and three X/Y/Z rows (origin + two points); it creates the three points and the plane, logging them exactly as above. Sketch ▸ New Sketch from 3 Selected Points does the same from three points selected in the 3D view.

3. Constraints, Dimensions & Variables

A freshly-drawn sketch is just points floating where you clicked. This chapter makes it parametric: constraints pin geometric relationships (horizontal, tangent, concentric…), dimensions pin numeric values (a length, a radius, an angle), and variables let one number drive several dimensions at once so the whole sketch resizes from a single edit.

3.1 How the sketch solver thinks

Every 2D primitive you draw — point2d, line2d, circle2d, arc2d, ellipse2d, spline2d — starts out with free coordinates. Constraints and dimensions are equations laid on top of those coordinates; the solver adjusts whatever is still free until every equation is satisfied at once. A plain cad.variable(30.0) — no fixed, no driving — is treated the same way: an ordinary least-squares unknown that the solver may move to make the rest of the sketch consistent, rather than a value you set. §3.4 covers the two ways to take a value out of the solver's hands.

Because it's a solve and not a fixed recipe, touching one dimension can ripple through the whole sketch. Editing a driving variable with cad.update(...) re-solves the sketch's constraints afterward; cad.ensure_convergence() forces that solve to happen immediately, without waiting for the next edit, so a script can inspect fully-solved positions before continuing.

In the GUI, the Sketch Mode toolbar's Constraint menu and Dimension menu apply these to selected entities, and the Variables panel manages named dimension variables (and their display precision). None of that is separate, hidden state: each action still appends or edits a line in your script and re-runs it, the same as everywhere else in FlywheelCAD. A practical workflow is to rough in geometry in the UI, add constraints and dimensions from those dropdowns, name the shared dimensions in the Variables panel, and treat the resulting script as the source of truth for repeatability.

3.2 Geometric constraints

Constraints take existing sketch elements and relate them; none of them take a numeric value (that's a dimension, §3.3) and most return nothing — the relationship is the effect. A few — the tangency constraints — construct and return the tangency point itself, since the solver needs somewhere to anchor it.

A worked pair: a slot whose two ends are equal circles, centred on a construction line, mirrored about it, and pinned so the solver cannot drift the whole assembly.

cad.with_sketch("xy")
axis  = cad.line2d(cad.point2d(-30, 0), cad.point2d(30, 0), construction=True)
left  = cad.circle2d(cad.point2d(-20, 0), 6)
right = cad.circle2d(cad.point2d( 20, 0), 6)

cad.equal_radius(left, right)              # same hole size, one dimension drives both
cad.point_on_line(left, axis)              # a circle where a point is expected means its centre
cad.point_on_line(right, axis)
cad.symmetry_line(left, right, axis)
cad.fixed(axis)                            # pin the axis so the pair cannot slide as a unit

The relational constraints, each on a minimal figure:

# coincident: two separately-drawn points become one point
a = cad.point2d(0, 0)
b = cad.point2d(0.2, 0)
cad.coincident(a, b)

# collinear: two segments share one infinite line
cad.collinear(cad.line2d(a, cad.point2d(10, 0)),
              cad.line2d(cad.point2d(20, 1), cad.point2d(30, 1)))

# concentric: two circles share a centre
cad.concentric(cad.circle2d(cad.point2d(0, 40), 10),
               cad.circle2d(cad.point2d(1, 41), 4))

# equal_lines: two edges hold the same length
cad.equal_lines(cad.line2d(cad.point2d(0, 60), cad.point2d(10, 60)),
                cad.line2d(cad.point2d(0, 70), cad.point2d(9, 70)))

# point_on_ellipse / ellipse_tangent_line
e  = cad.ellipse2d(cad.point2d(-6, 90), cad.point2d(6, 90), cad.point2d(0, 96))
cad.point_on_ellipse(cad.point2d(6, 90), e)
guide = cad.line2d(cad.point2d(-20, 100), cad.point2d(20, 100))
tp = cad.ellipse_tangent_line(e, guide)    # returns the tangency point

# spline_tangent_line: anchor the tangency at one control point
sp = cad.spline2d([cad.point2d(0, 120), cad.point2d(10, 128), cad.point2d(20, 120)])
cad.spline_tangent_line(sp, guide, control_point_index=0)

Out-of-plane relations take a plane rather than a line:

p1 = cad.point(0, 0, 5)
p2 = cad.point(0, 0, -5)
cad.point_on_plane(p1, "xy")               # hold a 3D point on a plane
cad.symmetry_plane(p1, p2, "xy")           # and mirror a pair across it

cad.merge_points is the canonical spelling of the weld that cad.coincident performs (see the callout below): it replaces one point with the other, so the sketch ends with a single point and no residual constraint. Reach for it by name when the duplicate was a mistake rather than a relationship; the result is the same either way.

keep = cad.point2d(0, 0)
dupe = cad.point2d(0, 0)
cad.merge_points(dupe, keep)               # dupe's references are rebound to keep

cad.horizontal(line=l1)
cad.vertical(line=l2)
cad.perpendicular(line1=l1, line2=l2)
cad.point_on_circle(point=p1, circle=c1)

tangent_pt = cad.circle_tangent_line(circle=c1, line=ground)  # c1 rests tangent on `ground`
cad.circle_tangent_circle(circle1=outer, circle2=satellite)    # `satellite` kisses `outer`

cad.vertical(line=mirror_axis)
cad.symmetry_line(p1=sym_left, p2=sym_right, symmetry_line=mirror_axis)

cad.horizontal(l1);  cad.parallel(l1, l2)   # positional form, also accepted

3.3 Dimensions

Dimensions pin a numeric value onto geometry — a length, a radius, an angle, a distance. The value can be a plain number, a cad.variable(...) (§3.4), or a linear expression built from variables with +, -, *, /.

A ratio between two variables, and the plane origin fetched explicitly:

width  = cad.variable(60, driving=True)
height = cad.variable(30)
cad.fraction(height, width, 0.5)             # height is always half the width

o = cad.origin("xy")                         # same point as the injected origin_xy
cad.coincident(cad.point2d(0, 0), o)

Dimension labels carry a position of their own. Dragging one in the sketch writes a cad.label_offset(key, dx, dy) line, where key identifies the dimension and dx/dy nudge the label away from its default spot. It moves annotation only — no geometry, no constraint, no effect on the solve.

cad.label_offset("length:l1", 4, -2)         # shift that dimension's label

cad.length(line=l1, length=40)
cad.distance(p0=a, p1=b, distance=25)
cad.distance(a, b, 25)                       # positional form, also accepted
cad.radius(circle=c1, radius=8)
cad.angle(line1=l1, line2=l2, angle=90)
cad.point_line_distance(point=p, line=l1, distance=5)

# a dimension's value may be an expression of variables (+ - * /)
d1 = cad.variable(80.0)
d2 = cad.variable(12.0)
cad.length(line=l2, length=d1 * 2 + d2)

Prefer these explicit cad.length / cad.radius / cad.distance calls for dimensions in Python rather than trying to encode a value some other way — it keeps the script's intent legible and matches what the Dimension menu itself writes.

3.4 Variables & parametric dimensions

cad.variable(value=None, fixed=False, driving=False, name=None) declares a scalar you can bind into one or more dimensions. name= fixes the name it appears under in the Variables panel and the script, rather than letting it be inferred from the assignment (§2.2). Its two boolean flags decide how much control the solver keeps over it:

w = cad.variable(240.0, fixed=True)     # a permanent constant
cad.length(line=l1, length=w)

pitch = cad.variable(30.0, driving=True) # editable later
cad.length(line=l2, length=pitch * 0.5)

cad.update({pitch: {"value": 45.0}})     # edits `pitch`; sketch re-solves
cad.update({p1: {"x": 10.0, "y": 20.0}}) # plain points update the same way

Variables outside dimensions

A cad.variable, or an expression of variables, is also accepted where a primitive or a placement takes a number. There it is resolved to its number when the script runs; only a dimension keeps it as a live expression.

w    = cad.variable(80.0, driving=True)
hole = cad.variable(9.0, driving=True)
c  = cad.point2d(w * 0.35, 25)      # a starting guess at x = 28 — no constraint added
h1 = cad.circle2d(c, hole / 2)      # radius 4.5, plus cad.radius(circle=h1, radius=hole / 2): linked

** has no spelling in a document expression, so a ** 2 collapses to its number and the link is lost. A variable declared without value= has no number until the solver runs, so it cannot be resolved in these positions; the error names the argument and says why. Numeric strings such as "12" are refused wherever a number is expected.

3.5 Editing operations: fillet, trim, mirror, pattern, merge

Fillet

cad.fillet(line1, line2, radius, name=None) rounds the corner where two elements — lines, arcs, or a mix of both — meet at a shared endpoint. Both elements retract to their tangent points and a tangent arc of radius bridges the gap; tangency and radius stay constrained, so the fillet remains valid across re-solves rather than being baked in once. The original variables keep referring to the now-retracted elements, and the call returns the new arc — feed it into a region loop between them, e.g. region(loop=[l1, f1, l2, ...]).

f1 = cad.fillet(l1, l2, radius=4)   # line-line corner
f2 = cad.fillet(l3, a1, radius=2)   # line-arc corner also works

FlywheelCAD rejects a fillet when the join is already tangent-continuous (there's no corner to round) or when the requested radius doesn't leave part of both elements intact.

In the GUI, Modify ▸ Fillet Corner… GUI opens the radius sheet for the corner implied by your current selection; the same command sits in the Sketch Mode toolbar's More (⋯) menu as Fillet…. The menu item is disabled until the selection actually describes a fillettable corner, so a greyed-out Fillet Corner… means "these two elements don't meet at a shared endpoint", not "the feature is missing".

Trim

cad.trim(element, near) trims an element in place at its nearest intersection. The original variable is updated to the surviving piece; the call returns (element, split_ref), where split_ref is only valid when the trim actually produced a second piece. A trim tool is also available directly on the Sketch Mode toolbar, and as Modify ▸ Trim (T).

l1, l1_split = cad.trim(l1, near=(12, 4))

Mirror

cad.mirror_elements(elements, symmetry_line) mirrors a list of sketch elements across a line in the current sketch, producing their reflected counterparts.

cad.mirror_elements([l1, l2, c1], symmetry_line=axis)   # mirror three elements across `axis`

Modify ▸ Mirror (M) GUI — also in the Sketch Mode toolbar's More (⋯) menu — does exactly the same thing from a selection, and it appends exactly one cad.mirror_elements(...) line no matter how many elements you mirrored. Select the elements you want reflected and then, last, the line to reflect them across; the command reads the final selected element as the symmetry line. Lines, circles, ellipses and arcs are mirrorable, and the menu item stays disabled until the selection satisfies both rules (at least one mirrorable element, and a line selected last), so the refusals below are ordinarily unreachable from the GUI:

• fewer than two elements selected, or the last one isn't a line;
• nothing mirrorable in the selection once the symmetry line is set aside;
• a participant — a source element, one of its defining points, or the axis — that has no script name yet, because a mirror line has to be able to refer to what it mirrors. Draw the geometry first, then mirror it.

Each mirrored copy is addressable as <source>_m — mirroring l1 gives you l1_m. Mirror the same source again (across a second axis, say) and the next copies take _m2, _m3, and so on, so repeat mirrors never collide and every reflected element stays individually nameable from the script.

Pattern

Modify ▸ Pattern… GUI — also in the Sketch Mode toolbar's More (⋯) menu — repeats the selected geometry in a circle around a centre point, and the copies stay linked: move the source and every copy follows, in the same solve, with no re-run.

Select the elements you want repeated and then, last, the point to rotate them around — the same "the last thing you select is the operand" convention Mirror uses for its symmetry line. Then give the panel two numbers:

• Count — how many there are in total, including the original.
• Step (°) — degrees between neighbours, not a total sweep. Six copies at 60° is a full circle; six at 15° is a 75° fan. The panel shows the total underneath as you type.

The step is deliberately a per-copy angle rather than a sweep, because it is the number the document keeps: it lands in a cad.variable(..., driving=True), so editing it in the Variables panel re-fans the whole ring immediately, with no re-execution. That is the same recipe the "Repeating sketch geometry" callout in §10.1 spells out by hand — the menu item simply writes it for you.

Points, lines, circles, arcs and ellipses. Anything the pattern cannot copy — a spline, or a selected area — is refused with a sentence naming it, rather than being silently skipped while the rest of your selection is patterned.

A patterned ring adds no redundant equation, whichever of those kinds it copies, so the solver badge stays quiet on a sketch that is genuinely fine. Getting there took a fix and a measurement rather than an assumption. Every ellipse in every document used to carry one redundant equation of its own, patterned or not — the point that defines an ellipse's rim was being constrained to lie on the ellipse it defines, which is always true and so contributed an equation that could never move anything. Arcs were long assumed to have the same problem; measuring showed they never did, and a bare arc has always been exactly determined.

Arcs are linked slightly differently from everything else, and the emitted loop shows it. Most copied geometry is held by a two-constraint "star" per defining point: a construction spoke from the pattern centre, an equal_lines fixing its radius and an angle fixing its bearing. An arc cannot use that for all three of its points, because creating the copy introduces a radius of its own and pins both endpoints to it — two constraints where the star has already accounted for the geometry, which would leave every copy carrying one redundant equation. So the loop stars the arc's centre and one endpoint, and holds the other endpoint with a single angle between the source arc's centre-to-endpoint construction line and the copy's:

r0 = cad.line2d(ac, aend, construction=True)      # source radius line, once
for k1, k2 in enumerate(ring(6, step=60)[1:], start=1):
    # ... the usual star for the centre and the START point ...
    pend = cad.point2d(*polar(rEnd, aEnd + k2))   # seeded, NOT starred
    ak = cad.arc2d(pc, pstart, pend)
    rk = cad.line2d(pc, pend, construction=True)
    cad.angle(line1=r0, line2=rk, angle=step * k1)

If the endpoint it would normally use is unavailable — because it is the pattern centre, or because a neighbouring patterned arc already relies on it — the loop simply uses the arc's other endpoint instead. Only when both are unavailable does it fall back to the plain star for that arc and accept one redundant equation, rather than refusing your selection: the geometry is correct either way.

What it writes is an ordinary, readable for loop — not an opaque command — so the count is a number in the script you can edit afterwards:

d1 = cad.variable(60, driving=True)
l2 = cad.line2d(p0, p1, construction=True)
for k1, k2 in enumerate(ring(6, step=60)[1:], start=1):
    p3 = cad.point2d(*polar(10, 0 + k2, center=(0, 0)))
    l4 = cad.line2d(p0, p3, construction=True)
    cad.equal_lines(line1=l2, line2=l4)
    cad.angle(line1=l2, line2=l4, angle=d1 * k1)

The construction lines are the pattern's scaffolding — one from the centre to each copied point — and the two constraints per point are what hold the ring together: equal_lines keeps every copy the same distance out, and the signed angle puts it k steps around. Each copied defining point costs one construction line and two constraints, so patterning a rectangle pays for all four corners; the count is capped to keep that bill finite.

Two refusals worth knowing, because both are about geometry rather than typing:

• a selected point sitting on the centre has no direction to be rotated in, so the pattern is refused — merge it into the centre point if that is what you meant;
• a line that starts at the centre is fine, and is the common case: the copies share the hub and fan out from it, which is how you draw wheel spokes.

Merge points

cad.merge_points(source, target) welds two sketch points into one shared identity — the canonical form of what cad.coincident(p0, p1) (§3.2) spells as a constraint. Modify ▸ Merge Points GUI does the same for the points selected in the sketch canvas. Because it is a merge rather than a residual equation, there is nothing for the solver to keep re-checking afterwards: the two variables simply refer to the same point from then on.

3.6 Solver diagnostics

FlywheelCAD's sketch solver doesn't expose a separate diagnostics API beyond the pieces already covered in this chapter — the vocabulary for keeping a sketch well-determined is the fixed / driving / free choice from §3.4. Pin what must never move with fixed=True, pin-but-tunable values with driving=True, and leave everything else free so the solver has room to satisfy the constraints you've added — an under-constrained sketch simply has more free coordinates than equations pinning them, and the solver settles on whichever consistent configuration is closest to where you drew it.

cad.ensure_convergence() forces a solve of the current sketch on demand, useful when a script needs fully-settled coordinates before it keeps building rather than waiting for the next dimension or update to trigger one.

cad.update({width: {"value": 45}})
cad.ensure_convergence()                     # settle now, before reading positions
body = cad.extrude("xy", profile, 10)

The one case the API validates directly and loudly is the contradiction in §3.4: fixed=True together with driving=True raises a ValueError at the cad.variable(...) call itself. For anything else — a script that runs without error but produces geometry that didn't change the way you expected — check for plain Python mistakes first, prefer the explicit dimension calls in §3.3 over improvising a value some other way, and use the script panel's error line to locate the runtime or validation failure quickly.

4. Regions — from Sketch to Solid

A region is the closed 2D area a sketch hands to a 3D operation — extrude, revolve, loft. Getting the loop right is what most first-time failures come down to: this chapter is the fast path through it.

4.1 What a region is

A region is identified by a directed boundary loop, optional holes, and an optional inside point:

r = cad.region(
    loop=[l1, l2, l3, l4],     # ordered boundary; consecutive elements share endpoints
    holes=[[hole_circle]],     # list of hole loops (each a list of elements)
    inside=(x, y),             # a point KNOWN to be inside the material (2D coords)
)

region(...) (the top-level free function) and cad.region(...) (the method) are equivalent — both build the same region object and take identical loop=/holes=/inside= keywords, and an optional name= label. loop= is the only required argument; calling region() with no loop raises region requires loop=[...] immediately, before the script even reaches the CAD engine.

A region isn't geometry itself — it's an instruction for how to read the sketch. Pass it straight into a body call:

body = cad.extrude("xy", region(loop=[l1, l2, l3, l4]), 5)

4.2 Loops, holes & inside points

A square with a circular hole through it:

body = cad.extrude("xy", region(loop=[l1, l2, l3, l4], holes=[[c1]]), 5)

A full disk, bounded by a single circle:

body = cad.extrude("xy", region(loop=[c1], inside=(0, 0)), 5)

4.3 Direction & seam cancellation

A loop is directed: list the boundary elements in traversal order. Every element has an intrinsic direction — lines run p1 → p2, circles/arcs/ellipses run counter-clockwise, splines follow control-point order. If an element runs against its natural direction for this particular loop, reverse it:

A face picked out of a circle crossed by chords — down the left arc, east along l10, then back up l7 and west along l4 against their intrinsic p1→p2 directions:

body = cad.extrude("xy", region(loop=[c1, l10, rev(l7), rev(l4)]), 5)

Compare that to the full-disk case above — region(loop=[c1], inside=(0, 0)). Leaving the internal chords out of the loop entirely (rather than tracing around them) is what makes it the whole disk instead of one wedge: the chord seams that would otherwise bound adjacent faces cancel, and only the outer arc c1 remains as the boundary.

4.4 Common region errors

axis = cad.line2d(b, t, construction=True)   # fine as a revolve axis...
# ...but never reference `axis` inside a region loop= or holes= list

5. Body Generation

This chapter turns the regions you built in Chapter 4 into 3D bodies, then combines and repositions them. Every call below returns a body ref you reuse downstream — as a boolean input, a transform source, or a mate-anchor host.

5.1 Extrude

cad.extrude(plane, region, distance, direction=None, quality=None, export=None, edge_radius=None, twist=None, twist_center=None, offset=None, draft=None) pushes a region straight off its sketch plane along the plane normal.

body = cad.extrude("xy", region(loop=[l1, l2, l3, l4]), 10.0,
                   edge_radius=1.5, draft=3, twist=45)

5.2 Revolve

cad.revolve(plane, region, axis_line, angle, quality=None, export=None, edge_radius=None) sweeps a region around an axis line drawn in the same sketch. axis_line is a (construction) line; angle is in degrees — 360 makes a full body of revolution, less than 360 a partial one. edge_radius rounds every sharp edge of the body, same as extrude.

# Cup profile revolved 180 degrees about l1 (the left edge, x = 0)
rbody = cad.revolve("xy", region(loop=[l1, l2, l3, l4]), l1, 180.0, edge_radius=2.0)

5.3 Loft & multi-loft

Two lofting calls, both bridging profiles on different sketch planes with a single solid:

lbody = cad.loft(start_plane="xy", start_region=region(loop=[c1]),
                 end_plane="zx", end_region=region(loop=[c2]), edge_radius=1.0)

mbody = cad.multi_loft(
    [plane0, plane1, plane2],
    [region0, region1, region2],
)

5.4 Sweep, helix & paths

A sweep drags a 2D profile along a 3D path. Build the path first — with cad.helix, cad.path, or cad.path3d — then pass it to cad.sweep(...). A path call returns a path handle, not a body.

cad.helix(radius, pitch, turns, axis_origin=(0,0,0), axis_dir=(0,0,1), start_angle=0.0, left_handed=False, name=None)

A helical path about an axis. radius/pitch are the coil radius and axial rise per full turn; turns may be fractional; start_angle is the initial angular offset in degrees (like every other angle in the API) of the path's θ=0 radial direction; left_handed flips the winding sense (the axial rise along axis_dir stays monotonic either way).

cad.path(plane, chain, name=None)

An open, directed rail on a sketch plane: lines/arcs/splines end-to-end, e.g. chain=[l1, rev(a2), s3] (rev(...) traverses an element against its intrinsic direction, exactly as in a region loop). Unlike a region loop, the chain is open — it never closes, and a closed element (full circle/ellipse, closed spline) cannot appear in it.

rail = cad.path("xy", chain=[l1, rev(a2), s3])

The plane is passed positionally and the chain by keyword — the form the app writes when you build a rail in the GUI.

cad.path3d(points, closed=False, up=None, name=None)

A free 3D curve through named point refs (results of cad.point(x,y,z), not raw tuples). A non-uniform (chordal) Catmull-Rom curve is fit through the points, then framed with a rotation-minimizing frame (RMF) so the section does not spuriously twist along a curving, non-planar rail. up optionally seeds the section's start orientation (e.g. a rectangular tube's flat), re-orthogonalized against the first tangent; the default is a deterministic auto-perpendicular direction. closed=True is not yet supported and raises an error.

cad.sweep(plane=None, region=None, path=None, sections=None, twist=0.0, quality=None, name=None, export=None, edge_radius=None)

Pass exactly one of two profile forms:

• Single profile — plane/region, authored exactly like extrude/revolve: cad.sweep("xy", region(loop=[c1]), path1).
• sections — a list of sweep_section(fraction=…, plane=…, region=…) (≥ 2 entries) the profile morphs between, keyed by arc-length fraction along path. Fractions must be strictly increasing, the first exactly 0.0 and the last exactly 1.0. Holes are not supported in this form (a single region= sweep keeps full hole support). Mutually exclusive with plane/region.

twist adds a total twist in degrees of the section over the whole path length, spun about the profile origin (useful for orienting e.g. a thread tooth or a rectangular wire flat).

# A spring: wire circle drawn CENTERED AT THE SKETCH ORIGIN.
cad.with_sketch("xy")
wire = cad.circle2d(cad.point2d(0, 0), 1.2)      # profile radius, NOT the coil radius
path1 = cad.helix(radius=8, pitch=4, turns=5)    # coil radius lives on the path
spring = cad.sweep("xy", region(loop=[wire]), path1)

# A taper: big circle -> small circle along a straight rail, via sections=
p1 = cad.point(0, 0, 0)
p2 = cad.point(0, 0, 20)
rail = cad.path3d(points=[p1, p2])
cad.with_sketch("xy")
big = cad.circle2d(cad.point2d(0, 0), 5)
cad.with_sketch("zx")
small = cad.circle2d(cad.point2d(0, 0), 1)
taper = cad.sweep(path=rail, sections=[
    sweep_section(fraction=0.0, plane="xy", region=region(loop=[big])),
    sweep_section(fraction=1.0, plane="zx", region=region(loop=[small])),
])

5.5 Boolean operations

cad.bool_union, cad.bool_difference, and cad.bool_intersection all share the signature (*bodies, quality=None, export=None, blend=None, radius=None, name=None) — variadic (at least two bodies), keeping the result and consuming the inputs.

blend/radius shape the seam where two bodies meet:

u = cad.bool_union(a, b, c)                             # more than two is fine
d = cad.bool_difference(box, tool, blend="smooth", radius=2)
i = cad.bool_intersection(a, b, blend="chamfer", radius=1.5)

5.6 Offset & shell

cad.offset(body, distance=None, quality=None, name=None) grows or shrinks a body's surface uniformly. distance is required — positive expands outward, negative shrinks inward — and omitting it raises offset requires distance immediately, in Python, before the call reaches the CAD engine. Unlike the transforms, cad.offset takes no export=; set that afterwards with cad.set_export(...) (§8.7) if you need to exclude the result.

There is no dedicated shell call; hollow a body by differencing a shrunk copy from the original:

big = cad.offset(box, 2)     # grow outward in every direction
small = cad.offset(box, -2)  # shrink inward
shell = cad.bool_difference(big, small)   # hollow shell

5.7 Body transforms

These operate on any body — including a component instance ref — and each returns a new body; the source stays, so they duplicate-and-transform rather than move in place. Every one that returns a body also accepts quality=, export= and name= (§2.2); cad.delete_body returns nothing and takes none of them.

b2 = cad.move(b, translate=(10, 0, 0))
b3 = cad.rotate(b, axis=(0, 0, 1), angle=45)
b4 = cad.scale(b, factor=2)
b5 = cad.mirror_body(b, plane="yz")
b6 = cad.copy(b)
cad.delete_body(b)

5.8 Patterns

A pattern is one script line that produces many bodies: count - 1 copies of a seed body, with the seed left where it is. The point of the opcode — as opposed to a hand-written loop of cad.move(...) calls — is that the whole array has a single editable line. Change count, spacing or angle there and every copy follows.

row = cad.pattern_linear(peg, direction=(1, 0, 0), count=4, spacing=10, name="row")
ring = cad.pattern_circular(bolt, axis=(0, 0, 1), count=6, angle=360, name="ring")
fan = cad.pattern_circular(blade, axis=(0, 0, 1), count=3, angle=90, center=(20, 0, 0), name="fan")

count includes the seed. count=4 is the seed plus three copies (at 10, 20 and 30 mm above), and it must be between 2 and 1000 — for a bigger repeat, write a python loop, which also gives you per-command cancellation. direction is normalized, so only its direction matters and neighbours are always spacing mm apart; a negative spacing patterns backwards.

The copies are ordinary bodies named row_1, row_2, … after the variable you assign to — or after an explicit name=; one of the two is required. They are also injected as bare python names, so cad.hide(row_2) works, and the call returns [seed, copy_1, …] with the seed first. If the assignment is inside a loop, or the same variable is assigned more than once elsewhere in the file, the base name itself is numbered too (row_1, with copies row_1_1, row_1_2, …) — pick a distinct name per pattern to avoid it.

6. Selection & the 3D View

The 3D view is where you inspect the model — orbit around it, check a boolean result, confirm a hole lines up. It's also where you pick the points that feed custom sketch planes, mates, and dimensions, so the same click can be inspection or input depending on what you do next.

6.1 Navigating the 3D view GUI

The main canvas shows either the 3D scene view or the 2D sketch editor. In 3D mode you orbit, pan, and zoom the model, select bodies and topology points, and run boolean operations on selected bodies.

Camera gestures

The camera treats +Z as up, matching the coordinate convention the rest of the app uses, so orbiting keeps the model's vertical axis vertical rather than letting the view roll freely.

6.2 Selecting points & areas GUI

Click an entity to select it. Dragging a selection window left-to-right is a containment selection (only entities fully inside the window); dragging right-to-left is a crossing selection (anything the window touches). Clicking inside a closed region in select mode makes an area selection — selected areas are tinted.

Picking the individual points that feed a custom plane (§6.4) or a mate (chapter 7) works the same way everywhere in the app: ⌘-click each point in the 3D view to add it to the selection.

6.3 Body topology points

After an extrude or revolve, a body exposes its far-face vertices as named, selectable points — the same points you can pick in the 3D view (§6.2) and pass to create_sketch_plane in a script (§2.7).

The exact set of names depends on the body. When you're not sure what a body exposes, it's more reliable to build reference geometry with cad.point(x, y, z) and use that instead.

6.4 Custom planes from topology GUI

You don't have to type coordinates to define a custom sketch plane. Select three points in the 3D view — topology points (§6.3), existing sketch points, or standalone reference points — then use Sketch ▸ New Sketch from 3 Selected Points. It creates the plane from that selection and switches into the new sketch, logging the equivalent script lines: the point references, a create_sketch_plane(p1, p2, p3, name=...) call, and a with_sketch(...) to enter it.

Pick the points in the order you want them to act as p1, p2, p3 — the plane's origin lands on the first point, and its normal follows from all three, exactly as create_sketch_plane computes it (§2.7).

Sketch ▸ New Sketch from Coordinates… is the typed alternative: a dialog with a sketch name and three X/Y/Z rows (origin plus two points), for when you want a plane at explicit coordinates rather than picked off existing geometry — useful for laying out a series of parametric planes, e.g. one station per spanwise cut before a loft.

6.5 What selection drives

Selected points and entities are the input to several other workflows, covered in their own chapters:

• Mates — chapter 7. ⌘-click the points involved, then use the link icon in the 3D toolbar or Component ▸ Mate Points.
• Custom sketch planes — §6.4 above, or the scripted form in §2.7.
• Boolean operations — run on whichever bodies are currently selected.
• Dimensions — in sketch mode, the Dimension menu applies dimensional constraints and variable bindings to the selected entities.

7. Components, Placement & Mates

7.1 The mental model

FlywheelCAD assemblies are built from components — reusable parts defined once — that you instance (place copies of) into a design and then position with placement transforms or mates. Whether you work in the 3D view or type Python, the result is the same: lines in your script. Understanding that equivalence is the key to the whole workflow.

7.1.1 Components, instances, anchors

7.1.2 Everything is a script line

The GUI never holds hidden assembly state. Inserting a part, mating two points, or placing a component all do one thing: append (or edit) a line in your script and re-run it. Every dialog that changes geometry shows you the exact line it is about to write before you confirm. This means you can always drop to the script to fine-tune what the GUI produced, and anything the GUI can build, you can hand-write.

7.2 Inserting components

There are two GUI paths to bring a part in (from an installed library, or from a loose .py file) and the underlying script primitives they emit. All GUI paths copy the part into your project so the document stays self-contained.

7.2.1 From a library GUI

Reusable catalog parts (motors, bearings, fasteners) come from component libraries — folders of ordinary Python component modules. The standard library ships inside the app. Add your own by dropping a folder (downloaded or git cloned) into:

~/Documents/FlywheelCAD/Libraries/   # one folder per library

• Component ▸ Insert from Library… — browses installed libraries, shows each factory's parameters (leave a field blank to keep the factory default), copies the files in, and appends the script lines:

  from lib.standard.steppers import stepper
  part1 = stepper(cad, size=17)
  inst1 = cad.instance(part1)

• Component ▸ Update from Library — refreshes vendored files whose source library has a newer version. Locally edited copies, and files from libraries you have since uninstalled, are reported in the console and never overwritten.

Library parts export named anchors ready to mate against. The standard stepper, for example, exposes mount_face, shaft_tip, shaft_base, and bolt_0…bolt_3:

cad.mate_coincident(bracket_1, "hole_0", "inst1.bolt_0")

7.2.2 From a loose file GUI

Two commands bring a loose .py that is not part of a library into the project, always by copying it in (never referencing it in place):

• Component ▸ Insert Component from File… — copies a standalone component and places one instance. The command inspects the file:
  • A factory module (functions taking cad as the first argument) opens a parameter sheet, then appends from <mod> import <factory> / part = <factory>(cad, …) / inst = cad.instance(part).
  • A fixed-instance component (a with cad.component("name") file) is placed directly with import <mod> / cad.instance("name").
  • A plain helper (neither) is declined, with a pointer to Add File to Project.
  The file's own sibling imports are copied along with it.
• File ▸ Add File to Project… — copies a helper module to the project root so your script can import it by name. A non-identifier filename like my-helper.py is renamed to my_helper.py; a name clash prompts before replacing. This does not edit your script — you write the import yourself, since a helper may be imported by another module rather than main.py.

7.2.3 Defining a component Script

Define a part once inside a with cad.component(...) block. Components are defined flat — never nest with blocks — and nested by reference (see §7.2.5).

with cad.component("bracket"):
    cad.with_sketch("xy")
    # ... sketch + region ...
    body = cad.extrude("xy", r, 5)
    cad.set_color(body, "steel", finish="metallic")
    cad.component_export(body)                              # assembly-visible result
    cad.component_export_point("hole", cad.point(10, 0, 0)) # named anchor for mating

7.2.4 Parametric components Script

Build a distinct component per parameter set, memoized by its parameters, so the same parameters always reuse one build:

def make_wing(span, chord):
    def build():
        cad.with_sketch("xy")
        # ... use span / chord ...
        cad.component_export(skin)
    return cad.parametric("wing", build, span=span, chord=chord)

WING = make_wing(span=46, chord=18)   # returns a component name

cad.parametric(prefix, build, **params) builds the component once per unique parameter set and returns its name (a handle for cad.instance). The build callable takes no arguments and emits the component's geometry and exports. A reserved label= keyword sets a display name and never affects the memoization key. Related helpers: cad.component_name(prefix, *parts) builds the deterministic name, and cad.has_component(name) reports whether one was already emitted this run.

name = cad.component_name("bracket", 40, 6)  # the deterministic name for these params
if not cad.has_component(name):              # emit the geometry only once per run
    cad.parametric("bracket", build_bracket, length=40, thickness=6)
arm = cad.instance(name)

7.2.5 Instancing a component Script

cad.instance(component, …) places a component into the assembly and returns a body ref that is usable anywhere a body is — booleans, transforms, set_color, and as a mate anchor host.

b1 = cad.instance("bracket")                            # at the origin
b2 = cad.instance("bracket", translate=(50, 0, 0))      # placed
b3 = cad.instance("bracket", mirror_plane="zx")         # mirrored
b4 = cad.instance(WING, scale=2, angle=10, axis=(0,0,1))# transforms compose
jig = cad.instance("jig", export=False)                 # excluded from mesh export

Nesting is by instancing: place another component inside a with cad.component block and re-export the instance — panel = cad.instance(WING); cad.component_export(panel). Larger projects split components into sibling .py files that an assembly file imports; the folder is on the import path, so import fuselage resolves a sibling fuselage.py.

7.2.6 Where the files live: vendoring & bundles

Inserting a part is copy-on-use: the module is copied ("vendored") into your document folder under lib/<library>/, so the document stays self-contained and a later library update never silently changes your design. The vendored file carries a provenance header and shows up as a read-only library tab in the script panel — don't edit it; to customize a part, copy the file up into your document folder as a normal user module.

Where that lib/ folder physically lands depends on which of the two document formats you're in — beside the script for a flat .py, inside the package for a .fwcad bundle. Both formats, and the File menu commands that convert between them, are covered in §1.5; nothing about vendoring differs between them.

7.2.7 The rest of the Component menu GUI

§7.2.1 and §7.2.2 cover the two ways to bring a part in. The same Component menu also holds the commands for authoring parts and for maintaining your libraries:

7.3 Moving & placing components

There are three ways to position a part, in increasing order of "let the software figure it out": a fixed placement transform baked into the instance, standalone body transforms, and mates that position a part relative to others (§7.4). FlywheelCAD is script-backed — there is no free-drag of an instance in the viewport; positioning is expressed as script lines (which the mate tools write for you).

7.3.1 Placement transform on the instance

Any combination of scale / rotate (axis+angle, optional center) / mirror_plane / translate may be passed to cad.instance together. They compose in a fixed order — scale first, translate last (scale → rotate → mirror → translate), regardless of the order you write the keywords.

FlywheelCAD: cad.instance(..., quality='ultra') ignored — per-instance mesh
quality is not persisted. A placed part inherits its quality from the component
definition; set quality inside the component instead.

7.3.2 Body transforms

These operate on any body (including an instance ref) and each returns a new body — the source stays, so they duplicate-and-transform rather than move in place. Every one that returns a body also accepts quality=, export= and name=; cad.delete_body takes none of them. This table is the same one as §5.7, repeated here because placing a part is where you reach for it most; §5.7 carries the fuller notes.

7.3.3 Placement vs. mates: which to use

• Placement transform — the part sits at fixed coordinates you type. Simplest; best when a part's position is absolute and won't follow anything.
• Mate — the part is positioned relative to another point or part, and re-derived every run. Best when parts should track each other as the design changes (move the target, the mated part follows). See §7.4.

7.4 Mates

A mate positions one instance relative to points in the assembly, and is re-evaluated on every run so the instance follows its target. There are three flavors — two closed-form "snaps" and one solved pose.

7.4.1 Anchors & targets

Mates connect an instance's anchor (something the component exported) to a target (any point in the assembly). Valid targets include:

• another instance's anchor — b1.hole (attribute form) or the equivalent string "b1.hole";
• a body-topology point picked in the 3D view;
• a free sketch point (cad.point / cad.point2d).

An instance ref exposes its exported anchors as attributes: if b1 = cad.instance("bracket") and the component did cad.component_export_point("hole", …), then b1.hole is that anchor in assembly space. Multi-body export parts surface as <instance>_<name>; exported points surface as <instance>.<name>.

7.4.2 The four mate types

cad.mate_coincident(instance, anchor, target, offset=None) — closed-form snap

Moves instance so its exported anchor coincides with target, plus an optional (dx,dy,dz) offset. Position only; orientation is untouched.

cad.mate_coincident(b2, "hole", b1.hole, offset=(0, 0, 5))

cad.mate_align(instance, anchor1, anchor2, target1, target2, offset=None) — snap + orient

Positions and orients: anchor1 coincides with target1 (+ optional offset), and the direction anchor1→anchor2 is rotated to become parallel to target1→target2. The instance moves; the two targets do not.

# b2's "a1" snaps onto t1 (+offset); the a1->a2 direction on b2
# is rotated parallel to the t1->t2 direction.
cad.mate_align(b2, "a1", "a2", t1, t2, offset=(0, 0, 0))

cad.mate(instance, anchor, target) — solved 6-DOF pose

A constraint the assembly solver satisfies. Unlike the snaps (which each fire once, in isolation), several cad.mate(...) on one instance are solved together as a rigid 6-DOF pose — e.g. three point mates fully fix both position and orientation. There is no offset= (the snaps have one).

cad.mate(b2, "p0", target0)
cad.mate(b2, "p1", target1)
cad.mate(b2, "p2", target2)   # three points -> full pose

cad.mate_axis(instance, anchor1, anchor2, target1, target2) — solved collinear axes

The second solved kind, and the only mate that deliberately leaves the part loose: it holds the instance axis anchor1→anchor2 collinear with the assembly axis target1→target2 and does nothing else — the anchors are never dropped onto the targets, so the part can still slide along that shared axis and spin about it. That is the shape a rail, a shaft or a bolt wants. It drives the same 6 DOFs as cad.mate, so the two solve together; there is no offset=.

# b2's a1->a2 axis is held collinear with the t1->t2 axis.
cad.mate_axis(b2, "a1", "a2", t1, t2)
# optional: pin the slide too, with a point ON that axis.
cad.mate(b2, "a1", point_on_axis)

step = cad.variable(90, driving=True)
hub = cad.point2d(0, 0)
seat0 = cad.point2d(40, 0, name="seat0")
l0 = cad.line2d(hub, seat0, construction=True)
for k, angle in enumerate(ring(4)):
    if k == 0:
        continue
    sk = cad.point2d(*polar(40, angle), name="seat%d" % k)
    lk = cad.line2d(hub, sk, construction=True)
    cad.equal_lines(line1=l0, line2=lk)
    cad.angle(line1=l0, line2=lk, angle=step * k)

for k in range(4):
    inst = cad.instance(peg)
    cad.mate(inst, "base", "seat%d" % k)

7.4.3 Mating from the 3D view GUI

You don't have to hand-write a mate. ⌘-click the points involved in the 3D view (a long-press on the model opens a "Points" popover for points hidden behind geometry, so you're never stuck), then click the link icon in the 3D toolbar — or use Component ▸ Mate Points, which does the same. A confirmation dialog shows the mate in plain English and the exact script line it will append; Mate appends it and re-runs, Cancel leaves the script untouched.

Which mate you get depends on how many points you selected:

7.4.4 Targets are references the solver never moves

A mate's target is a reference the solver never moves: the instance is pulled onto the target, never the target onto the instance. A free cad.point2d used as a target stays exactly where your sketch put it. This is what makes mate chains predictable — but also why chaining solved mates is restricted (below).

7.4.5 Mates the app refuses

A few combinations cannot be made to work — they look like they build but land the part in the wrong place, sometimes by tens of millimetres. FlywheelCAD refuses them identically whether you build them in the viewport or type them: the mate dialog disables Mate and shows the reason, and a script containing the same shape fails the run with that same reason rather than rendering something wrong.

Warned, not refused: if a cad.mate_axis's two targets collapse onto one point — something an edit elsewhere can cause — the run names that mate, leaves it out of the solve for that run, and builds everything else. Move a target apart and the next run picks it back up.

Always fine: mating onto an anchor of an instance that has no solved mate — that is what most assemblies do (cad.mate_coincident(arm, "hub", servo_inst.spline_tip)). Two identical cad.mate lines are a warning, not an error: the duplicate is dropped before the solve and the geometry is unaffected.

7.5 Worked example: a small assembly

Define a bracket component, place a stepper from the library, and mate the bracket's hole onto the stepper's bolt circle. This is the shape most assemblies take — components defined/inserted first, then instanced, then mated (emit in dependency order).

# 1. A user component with an exported anchor
with cad.component("bracket"):
    cad.with_sketch("xy")
    # ... sketch a plate + hole, build `plate` ...
    cad.component_export(plate)
    cad.component_export_point("hole_0", cad.point(10, 0, 0))

# 2. A catalog part from the standard library (what Insert from Library writes)
from lib.standard.steppers import stepper
motor = stepper(cad, size=17)
motor_inst = cad.instance(motor)                 # anchors: mount_face, bolt_0..3, shaft_tip...

# 3. Place the bracket and snap its hole onto the motor's first bolt
bracket_1 = cad.instance("bracket")
cad.mate_coincident(bracket_1, "hole_0", motor_inst.bolt_0, offset=(0, 0, 2))

To also orient the bracket, give it a second anchor and use a 4-point align (or select the four points in the viewport and click the link icon):

cad.mate_align(bracket_1, "hole_0", "edge", motor_inst.bolt_0, motor_inst.bolt_1)

8. Appearance, Quality & Export

This chapter covers how bodies look (color and finish), how visible they are in the 3D view, how finely they mesh — both as a document-wide default and per body — how the app tells you when a mesh came out coarser than requested, and how bodies leave the app as a 3MF, STL, OBJ or glTF file.

8.1 Colors & finishes

cad.set_color(body, color, finish=None) sets a body's display color and optional finish. It is display-only — it never affects geometry. Every body op also returns a chainable ref, so body.set_color(...) works the same way:

cad.set_color(body, "#C62828", finish="glossy")    # hex
cad.set_color(body, "red")                          # named color (defaults to glossy)
cad.extrude("xy", r, 10).set_color((0.2, 0.4, 1.0), finish="metallic")  # chainable, RGB tuple

finish is one of "matte", "glossy", "metallic", "glass" (translucent); it's optional and defaults to glossy when omitted.

8.2 Body visibility

cad.hide(*bodies) and cad.show(*bodies) hide or reveal one or more bodies in the 3D view. Each argument may be a BodyRef/Ref or a body-name string (e.g. a component instance part that has no Python variable). Visibility persists across save/reopen, and a hidden body is not exported until it is shown again (§8.7). At least one body is required — calling either with no arguments is an error.

cutter = cad.bool_difference(block, tool)
cad.hide(scaffold_a, "tail_i_fin")
cad.show(scaffold_a)                         # reveal it again; a later line wins

8.3 Document mesh quality

cad.set_quality(quality) sets the running document's default mesh-quality tier — the fallback for any body that doesn't pass its own quality= argument. It bakes into curve tessellation (sagitta) at the moment each body is created, and into the dual-contouring cell size at mesh time.

Each tier is really two numbers: the cell size it aims for (how fine a dual-contouring lattice it would like) and the cell budget, a cap on how many cells it may use along any one axis. Whichever of the two binds first wins — so on a small body the cell size decides, and on a large one the budget does, which is why a big part can look coarse at a tier that renders a small part beautifully.

What precision's two numbers actually mean

Precision's 0.1 mm is a floor, not a target: it is the finest cell the tier will ever ask for, and the budget only ever makes cells coarser than that, never finer. One consequence is worth internalising because it saves a lot of confused benchmarking: precision is identical to ultra for any body small enough that ultra already reaches 0.1 mm. The two tiers share the same floor. Precision differs only where the budget binds — that is, on large parts — which is exactly the case it exists for. If a 20 mm bracket looks the same at Ultra and Precision, nothing is broken; that is the design.

The floor itself is adjustable in Settings ▸ General ▸ Precision cell size (§1.7), and because it is a floor, moving it only affects parts small enough to reach it — the setting's own help text puts that boundary at roughly 13 cm. It is a per-Mac preference and is not saved with the document; cad.set_cell_size (§8.4) is the portable equivalent.

Precision's 1289 is a request and a ceiling, not a promise. A 1289³ lattice is an enormous amount of memory, and whether a given machine can serve it depends on the machine and on the body. So a precision body big enough for the budget to matter is measured first: the app searches for the largest lattice, up to 1289, whose predicted memory this device can actually serve for that body, and meshes at that. On a smaller machine a big body therefore commonly gets a smaller-but-fitting budget rather than the full 1289 — and that is a deliberate, chosen outcome, not a failure. If even the fitted budget turns out not to fit, the older behaviour still applies underneath: the quality ladder steps the body down a tier (precision → ultra → high → …) until it does.

In every one of those cases the body is geometrically correct — it is a correct mesh at a coarser resolution, never a wrong shape. What changes is only how much fine detail survives. When the resolution the body actually got differs from what you asked for, the app tells you rather than leaving you to guess; that is what §8.5 is about.

from flywheelcad import *
cad = FlywheelCAD()
cad.set_quality("high")   # must come before the first body-creating command

body1 = cad.extrude("xy", region, 10)                 # meshes (and tessellates) at "high"
body2 = cad.extrude("xy", region2, 5, quality="ultra") # per-body override still wins

8.3b Document presentation unit

cad.set_units(units) sets the running document's presentation unit — "mm", "cm", or "in" — for GUI entry/readout conversion and 3MF export only.

cad.set_units("in")                       # no ordering requirement — may appear anywhere
p1 = cad.point2d(0, 0)
c1 = cad.circle2d(p1, 12.5)               # still 12.5 MM, not 12.5 inches
body1 = cad.extrude("xy", region, 10)     # still a 10mm extrude

It is a document setting, not a component one, with the same __name__ == "__main__" behaviour as cad.set_quality(...): a set_units(...) line inside a component module has no effect when that module is imported by an assembly (silently ignored, with a stderr warning); the component's own line still applies when that file is opened and run standalone. The View ▸ Document Units menu logs (or updates) this line and applies it, the same way the Mesh Quality menu does, so the choice is part of the document and survives save/reopen. STL and OBJ export always stay millimetres, regardless of this setting — the slicer ecosystem's own convention.

8.3c Document default cell size

cad.set_default_cell_size(cell_size) sets the dual-contouring cell size, in millimetres, for every body that does not set its own — the document-wide sibling of the per-body cad.set_cell_size(body, cell_size) in §8.4 below.

cad.set_default_cell_size(0.2)            # must come before the first body
p1 = cad.point2d(0, 0)
c1 = cad.circle2d(p1, 12.5)
body1 = cad.extrude("xy", cad.region(loop=[c1], inside=(0, 0)), 10)

Which cell size a body actually gets, most specific first: its own cad.set_cell_size(...), then this document default, then the Precision floor in Settings (Precision quality only), then the quality tier’s own cell size.

Ordering matters here, unlike the document unit: a swept body bakes its path density from this value the moment the sweep command runs, so the line must appear before the first body-creating command — the same rule cad.set_quality(...) has, for the same reason. A script may call it at most once, and it is not allowed inside a with cad.component(...) block (components inherit the assembly’s default automatically). A value below 1e-6 mm — or zero, or negative — is refused outright, never silently clamped, and the message is the same one the View ▸ Default Cell Size… sheet shows. Leaving the line out means “let the quality tier decide”; a headless render’s --quality flag overrides it exactly as it overrides cad.set_quality(...). The View ▸ Default Cell Size… menu logs (or updates) this line — or removes it, with Clear — and re-runs the script, so the choice is part of the document and survives save/reopen.

8.4 Per-body resolution

Sampled meshing (booleans, offsets, lofts, rounded/drafted extrudes) uses a quality tier whose cell budget is relative to the body's size — a large body gets large cells, so small features (grooves, pockets, thin rods) can lose detail even at quality="ultra". cad.set_cell_size(body, cell_size) gives such a body an absolute dual-contouring cell size in model units instead, overriding the quality tier's relative budget. It's chainable as body.set_cell_size(cell_size).

wing = cad.bool_difference(skin, cutter)
cad.set_cell_size(wing, 0.8)      # 0.8-unit cells regardless of body size
wing.set_cell_size(0.8)           # chainable form

It applies to sampled (DC) meshing only — exactly-meshed plain extrudes/revolves ignore it, since they're already exact. The value is clamped to a hard total-cell cap; the console warns when the clamp engages. There is also a hard minimum: a cell size below 1e-6 mm (one nanometre) is refused outright rather than accepted, because at that scale it is always a typo'd exponent or a unit mix-up rather than modelling intent. The same floor is enforced by the Body Inspector's Cell size field (§8.6), so the GUI can never author a line the next run would reject.

A body may carry both a quality tier and a cell size. The explicit cell size wins for the cell size, and the total-cell budget becomes the larger of the two — setting a cell size never lowers the ceiling the quality tier already granted. The one exception is the adaptive-boolean path (chapter 5.5): a sharp boolean over a blended or offset operand has its own fixed 192-cells/axis cap that neither quality= nor set_cell_size can raise. When that cap is what decided a body's resolution, the app says so on the body itself — see §8.5.

Unlike the Precision cell floor in Settings (§1.7), which is a per-Mac preference, cad.set_cell_size is a line in your script: it travels with the file and produces the same resolution on any machine that can afford it. When a particular body must be meshed at a particular resolution everywhere, this is the call to reach for.

8.5 Mesh outcome notices — when a body meshes coarser than you asked

"The body is on screen" and "the body is what you asked for" are two different claims, and for a long time only the first was visible. A body that quietly meshed at a lower resolution than its tier requested looks, from the outside, exactly like a modelling mistake: an edge that should be crisp is soft, a groove you know is there doesn't show. Mesh outcome notices exist so you can tell those two situations apart at a glance. A body that meshed below its request is not a modelling error and usually not something you can fix by re-drawing — it is a device or route limit, and this is how you find out that's what happened.

Where the notices appear

The three outcomes

Three distinct things can happen, and they mean genuinely different things.

1. Quality downgraded. The requested tier could not be served on this device at all, so the body stepped down the ladder (precision → ultra → high → standard → preview) until one fit. The notice reads:

Meshed at ultra instead of precision: this body needs more memory
than is available at precision on this device.

This is badged as degraded — it shows in the chip, on the sidebar row, and in orange in the Inspector. The body is correct; it is coarser than you asked. The practical responses are to reduce what you're asking for (a lower tier costs less and may be indistinguishable at the size that matters), to split a very large body, or to accept it.

2. Adaptive resolution capped. This one is worth reading carefully, because it is the one where continuing to turn the dial genuinely will not help. A sharp bool_difference/bool_intersection whose operand is itself a blend="smooth"/"chamfer" result — or an offset — routes through a CPU-only adaptive boolean mesher (§5.5) whose base grid is fixed at 192 cells per axis, no matter what tier or cell size you name. When that fixed grid materially undershoots what you asked for, the notice reads:

Meshed by the adaptive boolean mesher at ~41% of the requested resolution
(its base grid is capped); once capped, raising quality or set_cell_size
does not refine this body further.

The percentage is that body's actual linear cell count against its requested one. The last clause is the actionable part: once this notice fires, quality="ultra", quality="precision" and cad.set_cell_size(...) are all no-ops for this body. Turning them up costs you meshing time and buys nothing. What does change the outcome is changing the shape of the operation, because the cap belongs to the route, not to the body:

• Give the boolean itself a blend= ("smooth" or "chamfer" with a radius) instead of leaving it sharp — a blended boolean is not on the capped route.
• Reorder the model so the blended/offset result isn't an operand of a later sharp cut — for example, cut first and blend the result, rather than blending first and cutting the blended body.
• Where the rounding is small and local, consider edge_radius= on the original extrude/revolve (§5.1) rather than a blended boolean feeding a later difference.

This notice is also badged as degraded, since the request could not be met. It carries no "actual tier" figure, because 192 is a raw cell count on the adaptive mesher's own grid and not a quality tier — naming a tier would misdescribe what capped it.

3. Resolution fitted. The body was meshed at the largest cell budget this device can actually serve for it, which was smaller than the tier's own budget — the machine-fitted budget described in §8.3. The notice reads:

Meshed at precision with a 704^3-cell budget instead of 1289^3: that is
the largest lattice this device can serve for this body. The body is correct.

with a distinct wording when the fit was driven all the way down to its own lower clamp and even that is predicted to be tight. This outcome is informational and deliberately not badged: no chip, no sidebar arrow, Inspector text in plain secondary colour rather than orange. The reasoning is that the request was met — at a budget chosen for the machine rather than discovered by failing — and on a memory-constrained Mac it is the routine result of any large precision body. Badging a routine, correct outcome as a failure would train you to ignore the badge, which is precisely what would make the other two useless.

8.6 The Body Inspector GUI

The floating Properties Inspector card (§1.3) is read-only. To change a body's per-body settings from the GUI, select exactly one body and use Body ▸ Inspect / Edit…, which opens a separate modal sheet. What it offers depends on the body:

• an extruded body exposes its Distance and Edge radius;
• a revolved body exposes its Angle (°) and Edge radius;
• every other body type (booleans, offsets, lofts, sweeps, transforms, instance parts) says so plainly — “Geometry of this body type is derived from its inputs and is not directly editable here” — and offers only the mesh settings below.

All body types then get the same three controls:

Cancel closes without touching anything. Save applies the edit — which, because a FlywheelCAD document is its script, means editing the script line that created the body.

8.7 Mesh export: 3MF, STL, OBJ & glTF

Four mesh formats — glTF in both of its containers — ship on the Body menu, all fed by the same set of bodies and the same save-panel flow:

3MF, STL and OBJ do not carry the finish ("matte"/"glossy"/"metallic"/"glass") — for them it is a viewport shading property, and translucency reaches 3MF and OBJ only because it rides on the colour's alpha channel. glTF carries it: the finish becomes the material's metallic and roughness factors, and a translucent colour becomes a blended material.

All of them export the selected bodies when there is a selection in the 3D view, and every exportable body otherwise — the same rule the headless CLI follows. The two halves of that rule behave differently, and it is worth knowing which you are in: with no selection, visibility and the export flag both decide — the flag picks among the visible bodies, so a body with export off is left out, and a hidden body is left out whatever its flag says (§8.2), which is how a boolean's consumed operands drop out of the file on their own; with an explicit selection the app ships exactly the bodies you picked, hidden ones included, which is what makes "select this one part and export just it" work on a part that is normally excluded. If any exported body's mesh looks topologically suspicious, or its geometry no longer matches the script, a warning alert naming up to five of them (plus a count of the rest) appears first — and whenever that alert appears, its first line also says how many hidden bodies the file leaves out; dismissing it takes you to the save panel, where you can still back out. A hidden count on its own raises no alert: on a model built from booleans that would be a modal before every save. Exporting with nothing to write says so plainly rather than doing nothing, and distinguishes the two reasons — nothing built yet, or everything built is hidden.

Choosing what gets exported

cad.set_export(body, value=True) sets whether a body is included in the export. body may be a BodyRef/Ref or a body-name string (e.g. a component instance part whose name has no Python variable), and it's chainable as body.set_export(value). Despite the historical name, the flag governs every mesh format, not just 3MF — a body excluded here is absent from the STL, the OBJ and the glTF too, whenever you export without a selection.

cad.set_export(part, False)
part.set_export(False)          # chainable form

Export can also be set at creation time: most body ops take an export=False keyword (excludes that body), and cad.instance(component, export=False) excludes the whole instance — and all of its parts — at once. In the GUI, the Include in export toggle in the Body Inspector (§8.6) sets the same flag for one body.

9. Section & Projection

Section and projection derive 2D geometry back out of a 3D body — a cross-section curve or a projected outline — drawn onto a sketch plane for reference or as the basis of a drawing view.

9.1 Cross-sections

cad.section(body, plane) cuts body at plane and draws the resulting curve onto that sketch plane, returning a Ref.

s = cad.section(box, "yz")   # cross-section curve at a plane

What comes out depends on the body and the cut:

9.2 Projections

cad.project(body, plane) projects body's edges onto plane and draws the result onto that sketch plane, returning a Ref.

sp = cad.project(box, "yz")   # silhouette projection onto a plane

9.3 Projected points

cad.project_point(point, plane) projects a single 3D point onto plane, returning a Ref. point takes anything that resolves to a 3D point — a body's topology vertex (body.v0, see §6.3) or a reference point from cad.point(x, y, z).

pp = cad.project_point(box.v0, "zx")

9.4 Refresh behavior

section, project, and project_point are snapshots, not live geometry: they capture the body as it stood when the line ran, and only update on a full re-run of the script — not incrementally as you edit other parts of the model.

10. Reference & Troubleshooting

A one-stop index of the cad API and the failure modes you'll actually hit — read this chapter when you know roughly what you want and just need the exact call, or when a script won't run and you need to know why.

10.1 API quick reference

All calls are on cad = FlywheelCAD() unless noted. This is an index, not a tutorial — each group cross-references the chapter with the full explanation.

Sketch context & planes

Elements (geometry creation)

name= overrides the script name that would otherwise be inferred from the assignment (or auto-generated when there is none) — see §2.2. cad.trim is the one element call without it: its results are named after the element it trims.

Geometric constraints

No return value except where noted.

Dimensions, variables & updates

Dimension values accept linear expressions of variables: cad.length(line=l1, length=d1 * 2 + d2).

Regions

Loop matching is rotation-invariant and reversal-lenient. Intrinsic directions: lines run p1→p2, circles/arcs/ellipses run counter-clockwise, splines follow control-point order.

Bodies (3D)

cad.with_sketch("xy")
step = cad.variable(60, driving=True)        # the editable dimension
c  = cad.point2d(0, 0)
p0 = cad.point2d(25, 0)
l0 = cad.line2d(c, p0, construction=True)

for k, angle in enumerate(ring(6)):
    if k == 0:
        continue                              # k = 0 is the source itself
    x, y = polar(25, angle)
    pk = cad.point2d(x, y)
    lk = cad.line2d(c, pk, construction=True)
    cad.equal_lines(line1=l0, line2=lk)                    # same radius as the source
    cad.angle(line1=l0, line2=lk, angle=step * k)          # k steps around from it

Booleans & transforms

Booleans are variadic and keep-result (consume their inputs); transforms are keep-both (source stays, a new body is returned). Every call here that returns a body accepts quality=, name= and — except cad.offset — export=; cad.delete_body takes none of them.

Components, instances & mates

Appearance, quality & export

Section & projection

10.2 Common errors

FlywheelCAD's API is deliberately fail-loud: rather than coercing a value, guessing at an intent, or quietly ignoring an argument, it stops and says so. Each error below is nearly always a one-line edit, because the message names its own replacement. The tables cover the errors you will actually meet, grouped by where they come from.

Renamed and removed spellings

Values the API refuses rather than coerces

Document-setting rules

These three concern cad.set_quality(...), which is a document setting and is policed as one (§8.3) — cad.set_default_cell_size(...) (§8.3c) is policed by the identical rule shapes, with the call name swapped in the message. A script that breaks more than one rule is told about the first.

Everything else

10.3 Pitfalls checklist

Run down this list before trusting a generated or hand-written script:

• from flywheelcad import * and cad = FlywheelCAD() at the top.
• cad.with_sketch(...) set before each batch of 2D geometry.
• Every element assigned to a unique, descriptive variable (names come from the LHS — don't shadow or reuse).
• Region loop is closed and directed; use rev(...) for reversed elements; include inside=(x, y) for any region with holes/ambiguity.
• Region inside and point2d use sketch 2D coordinates, not world coordinates.
• Bodies built only after their region exists; booleans after their input bodies; mates after their instances + exported anchors.
• Angles are in degrees; revolve uses angle=360 for a full solid.
• cad.sweep profiles are drawn centered at the sketch origin — the coil radius/offset lives in the cad.helix(...) path, never both places.
• Transforms are keep-both — capture the returned new body; the source stays.
• cad.move takes translate=(x, y, z) — never positional offsets, never dx=/dy=/dz=. Old documents commonly need this one edit.
• export= and cad.set_export(...) take a real True/False — never a string, never 0/1.
• Sweep sections are built with sweep_section(...), not the removed bare section(...); cad.section(body, plane) is a different call entirely.
• A quality= on a cad.instance(...) line does nothing — set quality inside the component definition.
• Components defined flat; nest by instancing + re-exporting, never by nested with blocks.
• No randomness / wall-clock time / external mutable state (re-execution must be deterministic and stable).

10.4 Workflow recommendations

1. Rough in geometry in the UI.
2. Add constraints and dimensions from the dropdowns.
3. Open the Variables panel and name shared dimensions.
4. Use the script panel as the source of truth for repeatability.
5. Move reusable generation logic into sibling helper modules.
6. Keep feature scripts small and composable by import.