Guide

Python Script Backend

How the app records UI work as Python, executes it, and rebuilds the model.

In FlywheelCAD, the script is not a secondary export. It is the persistent model text. The right-hand editor shows that text directly, and rerunning it reconstructs the design.

Source of Truth

Each document stores plain script text. When a document is opened, FlywheelCAD connects the document text to the command logger and, once the runtime graph is ready, replays the script to rebuild geometry.

Document text

The saved file contains Python source, not a hidden binary model representation. Saving prefers the current logger snapshot so the on-disk file matches the editor.

Command logger

UI actions append new lines into a script buffer. The buffer ensures the standard preamble exists and inserts the active cad.with_sketch(...) line when the sketch context changes.

Script editor

The right panel is a real editable text editor. It is not read-only output. You can change code there and rerun it directly.

Live sync

If the command logger changes while the editor is still in sync, the panel refreshes to show the latest generated script instead of drifting behind the model.

What the UI Writes

A typical UI session quickly becomes ordinary Python lines. The structure is intentionally simple: import, FlyWheelCAD(), sketch context, geometry creation, then constraints or body operations.

from flywheelcad import *
cad = FlyWheelCAD()

cad.with_sketch("xy")
p1 = cad.point2d(-60, -12.5)
p2 = cad.point2d(-20, -12.5)
l1 = cad.line2d(p1, p2)
cad.horizontal(l1)
cad.length(l1, 40)

# additional UI-created lines and a hole circle would follow here
# before the region is turned into a body with cad.extrude(...)

The same model can then be edited by hand. You can rename variables, insert helper imports, restructure code into functions, or replace repeated UI-authored geometry with loops.

Edit and Rerun Cycle

1. Edit text	Change the generated script directly in the right-hand editor. Indentation is kept as raw text so ordinary Python formatting still matters.
2. Execute	Press the run button in the command panel. The editor first loads your current text into the command logger, then execution starts without discarding that text buffer.
3. Python stage	FlywheelCAD runs the script through a Python subprocess using the bundled `flywheelcad.py` module. The script emits CAD commands to stdout.
4. Parse and validate	The emitted commands are parsed and validated before geometry changes are applied. This prevents half-applied scripts from mutating the model when syntax or reference errors are present.
5. Replay model	Existing geometry is cleared, origin points and standard planes are recreated, then commands are executed sequentially to rebuild the full design state.
6. Rebuild scene	After execution, FlywheelCAD synchronizes 2D and 3D state, generates missing meshes, then rebuilds the 3D scene so the visual result matches the script.

Imports and Local Helper Files

The document folder is used as the execution working directory. That is what makes ordinary sibling imports work: helper files next to the main script can be imported directly.

Project/
  gearbox.py
  CADgears.py
  helpers.py

from flywheelcad import *
from CADgears import gear_outline
from helpers import keyed_slot

cad = FlyWheelCAD()
gear = gear_outline(center_x=0, center_y=0, tooth_count=24, module=5.0, plane_name="xy")
gear_body = cad.extrude("xy", gear["region_ring"], 24, quality="high")

Important: repeated calls to FlyWheelCAD() return the same singleton instance, so helper modules share the same variable-name counter and the same origin references.

Examples of Script Refinement

Start in the UI

Rough in lines, circles, and regions interactively. Let the logger create a direct, explicit first draft of the script.

Promote shared values

Replace hard-coded dimensions with cad.variable(...) bindings so lengths, radii, and offsets become easier to reuse and rename.

Move generators into helpers

Once geometry becomes patterned or algorithmic, move it into a separate module like CADgears.py or CADpolygons.py and import it from the main file.

Rerun until stable

The best endpoint is a script you can rerun from a clean document and get the same model back every time.