Python Syntax

Quick start

A plate driven by variables, with a hole whose size follows one of them, built with a helper module that sits next to the main script. Save the two files together — inside a .fwcad bundle, or as a flat .py with the helper beside it:

Plate.fwcad/
  main.py      # the script
  shapes.py    # a helper module, imported by name

# main.py
# flywheelcad-format: 1
from flywheelcad import *
cad = FlywheelCAD()

from shapes import rectangle              # shapes.py sits next to this file

WIDTH = cad.variable(80, driving=True)    # editable in the Variables panel
HEIGHT = cad.variable(50, driving=True)
HOLE_DIA = cad.variable(8, driving=True)
INSET = cad.variable(12, fixed=True)      # a constant

cad.with_sketch("xy")
outline = rectangle(WIDTH, HEIGHT)
bottom, right, top, left = outline

centre = cad.point2d(INSET, INSET)        # starts at (12, 12); no constraint added
hole = cad.circle2d(centre, HOLE_DIA / 2)  # radius 4, plus a linked radius dimension
cad.point_line_distance(point=centre, line=bottom, distance=INSET)
cad.point_line_distance(point=centre, line=left, distance=INSET)

plate = cad.extrude("xy", region(loop=outline, holes=[[hole]],
                                 inside=(WIDTH * 0.75, HEIGHT / 2)), 6)
cad.set_color(plate, "steel", finish="metallic")

# shapes.py
from flywheelcad import *
cad = FlywheelCAD()                       # the same shared object main.py uses


def rectangle(width, height, plane="xy"):
    """A constrained width x height rectangle, lower-left corner on the origin."""
    bl = cad.point2d(0, 0)
    br = cad.point2d(width, 0)            # a variable seeds the point; no constraint added
    tr = cad.point2d(width, height)
    tl = cad.point2d(0, height)
    bottom = cad.line2d(bl, br)
    right = cad.line2d(br, tr)
    top = cad.line2d(tr, tl)
    left = cad.line2d(tl, bl)
    cad.horizontal(line=bottom)
    cad.horizontal(line=top)
    cad.vertical(line=right)
    cad.vertical(line=left)
    cad.coincident(p0=bl, p1=cad.origin(plane))
    cad.length(line=bottom, length=width)  # dimensions keep the variables live
    cad.length(line=right, length=height)
    return [bottom, right, top, left]

Change WIDTH, HEIGHT or HOLE_DIA in the Variables panel and the plate re-solves, because the lengths and the hole radius are dimensions. The point coordinates and the inside= point were only computed from the variables when the script ran; the geometry follows because the dimensions move it, not because the points remember the variables. The sketch is fully constrained: the corner sits on the origin, and the hole centre is held INSET from two edges.

Variables and expressions

A cad.variable, or arithmetic on variables, can go anywhere a number is expected. Only a dimension stores it as a live expression; everywhere else it is resolved to its number when the script runs. The long form, with more examples, is in the user manual: §3.4, Variables outside dimensions.

w = cad.variable(80, driving=True)
hole = cad.variable(9, driving=True)
depth = cad.variable(12, driving=True)

cad.with_sketch("xy")
c = cad.point2d(w * 0.35, 25)            # x = 28: a starting guess, no constraint added
h1 = cad.circle2d(c, hole / 2)           # radius 4.5, plus a linked cad.radius dimension
peg = cad.extrude("xy", region(loop=[h1], inside=(w * 0.35, 25)), depth)   # distance stays live
row = cad.pattern_linear(peg, count=3, spacing=w / 4)   # spacing is recorded as 20

A variable is a symbol, not a number the script can read: w.value raises an error that names the forms above. And a plain cad.variable(40) — neither fixed nor driving — is a free unknown the solver may move; a coordinate taken from it keeps the value it had at that line. Declare values you use as coordinates fixed=True or driving=True.

Setup and planes

Sketch axes: on "xy" sketch x is +X, sketch y is +Y and an extrude goes +Z; on "yz" they are +Y, +Z and +X; on "zx" they are −X, +Z and +Y.

Sketch geometry

There is no cad.* pattern call for sketch geometry. Modify → Pattern… writes an ordinary for loop instead — one construction line plus an equal_lines and an angle per copy, driven by a cad.variable step — so the copies stay linked to the source. The recipe is under Placement helpers and in the manual's §3.5.

Geometric constraints

Constraints relate existing elements. They take no value, and all but the two tangent-line constraints return nothing. The keyword form — cad.horizontal(line=l1) — is what the app writes when you add a constraint in the GUI; the positional form is also accepted. Wherever a constraint or dimension expects a point, you may pass a circle or arc and it means its centre.0.35

Dimensions and variables

A dimension pins a value: a number, a cad.variable, or a linear expression of variables. Dimensions are the only calls that keep an expression live. A dimension written at module level can be edited in the sketch (double-click it); one bound to an expression or to a plain Python variable is left as written by that editor.

w = cad.variable(80, fixed=True)
clearance = cad.variable(12, driving=True)
cad.length(line=l1, length=w * 2 + clearance)

Regions

Bodies from sketches

Each call returns a body ref (for example body1) and also accepts export=: False leaves the body out of mesh export. It must be a real bool.

Sweeps, paths and text

cad.with_sketch("xy")
wire = cad.circle2d(cad.point2d(0, 0), 1.2)          # profile at the sketch origin
coil = cad.helix(radius=8, pitch=4, turns=5)         # the coil radius lives on the path
spring = cad.sweep("xy", region(loop=[wire]), coil)

Booleans, transforms and patterns

Booleans consume their inputs: the operands are hidden and so leave the export. Transforms and patterns keep the source and return new bodies. Coordinates, angles, factors and spacings in transforms and patterns accept variables, resolved to numbers — editing the variable later does not move the body.0.35

Components, instances and mates

Components define a reusable part once and place it many times. A component body is written flat inside a with cad.component(...) block — blocks never nest; larger structures nest by instancing other components. A component that is never instanced is transparent: it builds the top-level design, so a component file opened directly behaves like a normal editable part.

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

b1 = cad.instance("bracket")
b2 = cad.instance("bracket", translate=(50, 0, 0), mirror_plane="zx")
cad.mate_coincident(b2, "hole", b1.hole, offset=(0, 0, 5))

Appearance, quality and export

set_color, set_export, set_cell_size, hide and show accept a body ref or the body's name as a string. The string form is the only way to reach the parts of an instance (e.g. "motor_1_can") or a body whose variable was reused in a loop.

The last three are the user's controls: a script written for someone else should leave them out. Mesh export is on the Body menu — Export to 3MF…, STL…, OBJ…, GLB… and glTF… — and sketches export from File → Export Sketch as DXF… or SVG…. The manual's §8.7 lists what each format carries.

Section and projection

All three are snapshots: they update only when the whole script re-runs.

Placement helpers

Free functions, not cad. methods. They compute numbers and emit nothing; use them to place copies in a loop. Each scalar accepts a variable, resolved to its number; counts must be plain integers.0.35

A ring of points that stays linked to its source — what Modify → Pattern… writes:

step = cad.variable(60, driving=True)          # editable in the Variables panel
c = cad.point2d(0, 0)
p0 = cad.point2d(25, 0)
l0 = cad.line2d(c, p0, construction=True)      # every copy is tied to this source
for k, angle in enumerate(ring(6)):
    if k == 0:
        continue
    pk = cad.point2d(*polar(25, angle))
    lk = cad.line2d(c, pk, construction=True)
    cad.equal_lines(line1=l0, line2=lk)
    cad.angle(line1=l0, line2=lk, angle=step * k)

Component libraries

Catalog parts come from component libraries — folders of parametric part modules. A standard library ships in the app; add your own as folders under ~/Documents/FlywheelCAD/Libraries/. A library factory takes cad first and returns a component name, so it drops straight into the assembly flow — call it, then cad.instance(...) the result and mate to its exported anchors.

from lib.standard.steppers import stepper
from lib.standard.bearings import bearing

part = stepper(cad, size=17, length=40)                # a NEMA 17, 40 mm long
motor = cad.instance(part)
brg = cad.instance(bearing(cad, designation="625"))    # 5 mm bore, to fit the shaft
cad.mate_coincident(brg, "face_b", motor.shaft_tip)

Inserting through Component → Insert from Library… is copy-on-use: the module is vendored into the document’s lib/<library>/ folder (with a provenance header, shown as a read-only tab), so the design stays self-contained and a later library update never silently changes it. A few of the standard modules (every factory also accepts quality=):

The full catalogue — gears, electronics, framing, mounts and more — is on the Component library page.

Including a separate Python file

Put the helper module next to the main script — inside the bundle, next to main.py, for a .fwcad document. The document folder is on the import path, so from shapes import rectangle finds shapes.py, as in the Quick start. A helper calls FlywheelCAD() itself and gets the same shared object as the main script, so names stay unique across files.

MyProject.fwcad/
  main.py
  shapes.py
  profiles.py

Imported modules appear as read-only tabs in the script pane. Don't add __init__.py files, and don't give a module the name of a Python standard-library module or one of flywheelcad, sitecustomize, component_shape, component_export_rewrite, document_setting_rewrite or test.