Migrations
Migrating a CAD project from cadgen 0.7 to 0.8
This is a hand-migration playbook. Work through it top to bottom with a 0.7 project open
and you will end with a working 0.8 project. An agent with the CAD skill installed is
pointed here by the skill's short references/migrations.md and can do most of this for
you: ask it to follow this guide. A project still on 0.4 first follows
Migrating 0.4 to 0.5, which ends here. This guide targets
cadgen 0.8.1 with build123d 0.13.
Read this first: there is no authoring compatibility layer
0.8 ships no backwards compatibility for authoring and runtime APIs, on purpose:
- No shims, no aliases, no deprecated keyword arguments, and no codemod.
- No teaching errors. A retired flag is an unrecognized argument, a retired name an
ImportErrororAttributeError, a retired decorator argument aTypeError. None of those errors mentions 0.7, this guide, or what the thing used to be called.
So when something fails during this migration, the error tells you what 0.8 wants, not what you did. Read it as a spec.
What a 0.7 project does under 0.8
Nothing migrates on its own, and nothing points here. What happens depends on how the project runs cadgen:
-
Its scripts run on 0.8 (the CAD plugin's
cadgencommand, or a pin moved to 0.8): the first run stops at the first 0.7 import, before any model is built:ImportError: cannot import name 'build123d' from 'cadgen' (.../site-packages/cadgen/__init__.py)With the imports fixed, the next stop is the first 0.7 decorator argument (
TypeError: step() got an unexpected keyword argument 'kinematics'), and so on down this guide's steps. -
Its docs pin 0.7 (a README or
AGENTS.mdthat saysuvx ... --from cadgen==0.7.21 python src/model.py): that command keeps building with 0.7, writes its STEP files and sidecars as before, and fails nothing. The project moves only when those commands do (Prerequisites, step 2).
The one-paragraph summary
0.8 replaces 0.7's file pipeline with one engine. A model is still a parameterless
Python function, but it is decorated @model and a run writes nothing: cadgen run model.py (or python model.py in an environment with cadgen) rebuilds the model in a warm
engine, prints its document's id and a link to its page, and every page open on it updates.
Think of the page as the open document, the script as its feature tree, and running the
script as the rebuild. Export is the download button at the navbar's right: pick a format,
the engine prepares the file, the browser saves it; cadgen export <id> part.step writes
one from the command line, and an exports.py writes a project's deliverables. Mates,
couplings, poses and JavaScript clips become build123d joints and STEP AP242's mechanism
vocabulary in the model's body (cadgen.ap242), and showcase animations become a GLB's own
channels (cadgen.gltf). Colours are sRGB hex. import build123d as bd is free until it
is used. The 0.7 store, sidecars, STEP-format commands, staleness checks and ?file= links
are gone.
Updating from 0.8.0 or 0.8.1
This section is for a project already on 0.8; it has nothing to port. An engine from
0.8.0 or 0.8.1 runs until it is stopped, so after an update it may still be running.
Update with the install command, which stops that engine when nothing is using it,
through its own installation's cadgen stop, and installs the new release in every
agent app:
curl -fsSL https://texttocad.dev/install.sh | shOn Windows, in PowerShell: irm https://www.texttocad.dev/install.ps1 | iex. A plugin
updated through its app gets the same as the new release's engine starts: it stops
every older release's engine that nothing is using. An older engine still in use (a
session still open on the older plugin, a page watching it, a build) keeps running,
and while it holds port 3245 the new engine serves on the next free port and says so
once (3245 is held by cadgen 0.8.1's engine (pid N); this installation serves on 3246 and keeps it), coming back to 3245 at a later start once it is free
(Port 3245). To stop the older
engine yourself, run its own command, then restart the agent app:
~/.local/bin/cadgen +0.8.1 stopPrerequisites
-
Update the plugin, or the pin. The plugin starts its server through
uvx --no-config --managed-python --python 3.13 --from cadgen==0.8.1 cadgen mcp, which installs and registers cadgen. Skills then run commands ascadgen +0.8.1 ...and model scripts ascadgen +0.8.1 run SCRIPT.py, through that installation's launcher. A project that pins cadgen itself moves its pin tocadgen==0.8.1. The Python floor is unchanged (3.11). cadgen no longer depends on Playwright: snapshots are drawn by OCCT, so no headless browser is downloaded. -
Run cadgen through the
cadgencommand. 0.8 installs one,~/.local/bin/cadgen, written bycadgen doctorand by the CAD app's server. It runs a registered installation, picked by the first of: a version named (cadgen +0.8.1 ...), theCADGEN_VERSIONvariable, the engine the shell's agent app holds, a running engine, and the newest installation registered.cadgen run SCRIPT.pyruns a model script with that installation's Python, so the scripts, the commands and the CAD app share one engine:0.7 (in a project's README or AGENTS.md)0.8 uvx --no-config --managed-python --python 3.13 --from cadgen==0.7.21 python src/model.pycadgen run src/model.pyuvx ... --from cadgen==0.7.21 cadgen <verb>cadgen <verb>uvx ... python -m unittest ...cadgen run -m unittest ...a version kept in step with the plugin by hand nothing (the plugin's), or cadgen +0.8.1 ...for an explicit versionIf
cadgenis not on your PATH, or says 0.8.1 is not installed, runuvx --no-config --managed-python --python 3.13 --from cadgen==0.8.1 cadgen doctoronce.A project's old venv may shadow the launcher with its own
cadgen, even when~/.local/binis on PATH. Run~/.local/bin/cadgen +0.8.1 doctorto see which executable wins, and use the full launcher path until PATH is corrected. -
Set
PYTHONPATHwhere the project's import root needs it, as forpython SCRIPT:PYTHONPATH=src cadgen run src/camera/payload.py. -
Confirm what you have.
cadgen --version # cadgen 0.8.1 cadgen doctor # the installation in use, the CAD kernel, the engine -
Stop 0.7's viewer. A 0.7 viewer still running is 0.7's own process, on its own port: stop it with 0.7's
cadgen viewer stop, or let it be. 0.8 starts its own engine on first use. -
Commit your work. This migration deletes files.
Migration checklist
Do these in order. Later steps assume earlier ones.
- 1. Rewrite imports
- 2. Convert each model to
@model, each variant a model of its own - 3. Move files out of the model: exports on request, or
exports.py - 4. Move mates to build123d joints and the mechanism's AP242 functions
- 5. Move clips to configuration sequences and animations
- 6. Move materials into the body; make colours hex
- 7. Learn the one engine: ids, pages, links and commands
- 8. Replace
read_scenerefs, checks and tools that read 0.7's files - 9. Delete 0.7 leftovers
- 10. Verify
1. Rewrite imports
# 0.7 # 0.8
from cadgen import build123d as bd import build123d as bd
from cadgen.build123d import Box from build123d import Box # loads the kernel here
from cadgen import step, read_step from cadgen import model, memo, read_step
import cadgen from cadgen.ap242 import mechanism_state, gear_pair
from cadgen.gltf import animationimport build123d as bd directly. cadgen installs a lazy importer for build123d
and OCP in its own environment: the import binds at once and the CAD kernel (about
2.5 s) loads on the first attribute anything reads, inside the engine's worker. A run the
engine finds current never loads it in your process. from build123d import Box reads
the name and loads the kernel at that line, as does a module-level bd.Color(...) or
bd.Align.CENTER default, so write build123d attribute-style. The cadgen.build123d
proxy is gone. Module-level work runs in your process on every run too: a 0.7 script that
computed its kinematics at import (KINEMATICS = kinematics() for the decorator) pays it on
every no-op; once the mates are in the body (step 4), compute them there. Measured on a
628-part arm: 1.3 s of the calling process's CPU per run at module level, 0.1 s in the body.
The root holds exactly sixteen names: model, the file decorators xbf, step,
glb, stl, threemf and dxf, memo, paint,
read_step, read_xbf, read_mesh, the operations export, snapshot and
inspect, and __version__. Two namespaces hold the standards' vocabulary:
cadgen.ap242 (mechanism_state, configuration_sequence, gear_pair,
rack_and_pinion_pair, screw_pair, posed) and cadgen.gltf (animation).
cadgen.geometry and cadgen.flatten are unchanged. Everything else 0.7 exported is gone:
| Removed (0.7) | Instead (0.8) |
|---|---|
cadgen.build123d | import build123d as bd |
revolute, slider, cylindrical, fastened, MateTarget, AssemblyHelper, target | build123d's joints in the body (step 4) |
couple | cadgen.ap242's gear_pair, rack_and_pinion_pair, screw_pair (step 4) |
srgb, srgb_to_linear, linear_to_srgb, cadgen.color | the hex itself: "#2E3742" (step 6) |
report, track | nothing: delete the calls. Progress is reported per @memo call and child model, by its function's name |
read_scene, StepScene, Occurrence, Selection | cadgen inspect and the model's own tree (step 8) |
compound_from_instances | bd.Pos(...) * part: every placement shares its shape |
label_shape, label_text | shape.label = "name" |
ensure_step_topology_artifact | nothing: the viewer reads a STEP as it is |
cadgen.kinematics, cadgen.store.*, cadgen._internal.* | nothing: private modules, gone with the store (step 8) |
A project that computes its mates as data -- a list of revolute(...) and
fastened(...) records that stages edit, re-zero and audit before the model uses them --
keeps that data: define the record yourself (a frozen dataclass with 0.7's fields name,
kind, parent, child, axis {origin, dir} and limits {value}, so
dataclasses.asdict gives the rows your code reads), import revolute and fastened from
it, and turn the final list into joints in the body (step 4).
2. Convert each model to @model, each variant a model of its own
# bracket.py (0.7)
from cadgen import build123d as bd
from cadgen import step
WIDTH = 40.0
def _bracket(width):
body = bd.Box(width, 20, 6)
return body - bd.Cylinder(4, 6)
@step(out="../STEP/bracket.step")
def bracket():
part = _bracket(WIDTH)
part.label = "bracket"
return part
if __name__ == "__main__":
bracket()# bracket.py (0.8)
import build123d as bd
from cadgen import model
def bracket_body(width, bore):
body = bd.Box(width, 20, 6)
body = body - bd.Cylinder(bore / 2, 6)
body.label = "bracket"
return body
@model
def bracket():
return bracket_body(40, 8)
@model
def bracket_wide():
return bracket_body(60, 8)
if __name__ == "__main__":
bracket()
bracket_wide()Mechanically:
-
Replace each file decorator with
@model. A model still takes no parameters and returns a build123d shape: a part, or aCompoundof labelled children. -
Keep parameters on plain helper functions. A model function takes none; its values are the arguments of the helpers it calls, as a 0.7 factory's were. The helpers need no marking: the engine keeps every kernel operation, keyed by its inputs, and replays what an edit did not reach.
-
Make each variant a named model. A configuration (a wide bracket, an M4 standoff) is a
@modelof its own that calls the helper with its values. Each has its own document, id and page. -
Keep the
__main__calls. Decoration only declares; a call builds. Each call your__main__makes prints its model's id and page. A 0.7 model with no__main__(one only other models called) builds only when one of them runs; give it one to build it alone. -
A model call returns its document, not its shape. The call returns a handle:
.id,.url(its page),.name,.shapeand.export(...). An assembly's body calls its part models and composes their shapes --plate().shapewhere 0.7 hadplate(),payload().shape.moved(loc)where 0.7 hadpayload().moved(loc)-- places them and labels the placements. A child builds in the same run and keeps its own document, id and page. A check readskit().shape; the shape comes into the calling process when it is first read. -
One declaration per function. Bare
@modelis a document with no file; the file decorators (@xbf,@step, ...) are a document with those files. Stacking@modelon a file decorator is refused: drop@model. -
A stage that was a child model only to be cached is
@memo. 0.7 projects often built a long derivation chain of cached child models (stages/a.py->stages/b.py-> the root), each writing a STEP nobody delivered. In 0.8 mark each such stage@memo(new in 0.8) and drop its__main__and its file: the engine replays it whole, keyed by its code and its arguments, and it has no document of its own. Since every kernel call is replayed anyway, a memo hit saves only Python time (0.1 to 0.4 ms per kernel call): mark a whole sub-assembly stage of a thousand kernel calls or more (measured at 1.3 to 3 s each, twice as fast on an edit), never a part and never a helper called many times. A stage a person opens on its own stays a@model. -
A stage's result is now the live tree, its sub-assemblies' placements kept. In 0.7 a child model's result came back from the store with every sub-assembly at the identity and each leaf carrying its whole placement in the child's frame. In 0.8 a
@memostage, a plain function and a child's.shaperead inside a body hand over the tree as it was built, each compound keeping its ownlocation. Code that moves leaves with.moved()(or reads a leaf's.location) expecting the 0.7 shape now works in the sub-assembly's frame: a sub-assembly turned 180 degrees moves its leaves the other way, silently, a few millimetres at a time. Where a stage's code does that, return the 0.7 shape from the stage before it:def as_leaves(node, outer=None): # every placement pushed into the leaves here = (outer or bd.Location()) * node.location if not node.children: leaf = node.located(here) leaf.label, leaf.color = node.label, node.color return leaf return bd.Compound(children=[as_leaves(c, here) for c in node.children], label=node.label, color=node.color)and compare the migrated model's placements with a 0.7 build of the same code (step 10).
A run takes no options. 0.7's --force, --json, --verbose, --profile,
--mesh-tolerance and --no-daemon are unrecognized arguments; there is nothing to
pass:
| 0.7 | 0.8 |
|---|---|
python model.py | cadgen run model.py, or python model.py in an environment with cadgen 0.8 |
python model.py --force | CADGEN_ENGINE_MEMO=0 cadgen run model.py (no memo hits) |
python model.py --json | bracket.build() from Python returns the report as data (.models[0]) |
python model.py --profile | bracket.build(profile=True) |
python model.py --no-daemon, CADGEN_DAEMON=0 | nothing: every run goes through the engine. Model.build(daemon=False) remains as a seam for tests and debugging (cold, in your process, nothing served) |
@stl(mesh_tolerance=...), --mesh-tolerance | nothing: every mesh is made at one tolerance, 0.25 % of each part's size and 28.5 degrees |
cadgen store why src/model.py (stale or current?) | run it: took ... nothing ran means the document is current; otherwise it builds, and its rebuilt: line says what changed |
A run reports a line, the delta against the build before, and the page:
built src/tom.py::tom cold in 188.89s: bodies 7 run; 9074 misses, 0 hits; body 139.98s, names 12.69s, document 0.84s
parts 628 · bounds 483.6 × 83 × 512 mm · joints 7 · sequences 3
id: 3d76a9c1-543c-514f-b08e-a21acc2a5656
view: http://127.0.0.1:3245/3d76a9c1-543c-514f-b08e-a21acc2a5656?token=...The first run in a fresh installation also says loading the CAD kernel for the first time in this environment, up to a minute. An unchanged rerun is took ... its document in memory holds the model's key, ... nothing ran, in a fraction of a second.
3. Move files out of the model: exports on request, or exports.py
In 0.7 a run wrote every file its decorators declared. In 0.8 a run writes nothing: the engine holds the model's document, and a file is written from it when you ask, with no rebuild:
cadgen run src/bracket.py # prints id: <uuid> and view: <url>
cadgen export <uuid> STEP/bracket.step STL/bracket.stl GLB/bracket.glbA project whose files are delivered after every change keeps one script that imports
its models and exports each. export takes the model function itself, builds it (a
replay when nothing changed) and writes from its document:
# src/exports.py
from pathlib import Path
from cadgen import export
from assembly import assembly
from bracket import bracket, bracket_wide
ROOT = Path(__file__).resolve().parent.parent
if __name__ == "__main__":
export(bracket, ROOT / "STEP/bracket.step", ROOT / "STL/bracket.stl")
export(bracket_wide, ROOT / "STEP/bracket_wide.step")
export(assembly, ROOT / "GLB/assembly.glb")export() prints nothing; print what it wrote if you want a record. An export takes a
document and its destinations, and nothing else. A file in another pose is a model of its
own that returns the posed assembly (step 4), and a part on its own is that part's own
model. A tool that reads a delivered file (a URDF pipeline reading STEP/robot.step) reads
the export: run exports.py before it.
The file decorators still work. @xbf, @step, @glb, @stl, @threemf and
@dxf, with out as their only argument (relative to the script), still write their
file whenever the model runs. A project can keep them while it migrates; 0.8's guidance
is @model and explicit exports. kinematics=, materials=, animation= and the mesh
tolerances are gone from every decorator.
The xbf is Save As. .xbf is cadgen's own document format: parts and placements,
names, colours, materials, element names and the mechanism, read back losslessly.
Export one only to share a model without its code, or to compose it in another project
with read_xbf; an engine restart needs none (step 7). It is not a build stage. A vendor
STEP converts to one once, and read_xbf reads it many times faster than read_step
parses the STEP:
cadgen export vendor/motor.step vendor/motor.xbf4. Move mates to build123d joints and the mechanism's AP242 functions
0.7's kinematics= dict (typed mates, couplings and poses, kept in a
<name>.step.json sidecar) is gone. An assembly's mechanism is build123d's joints on
its parts, and the functions that say more are named after the STEP AP242 entities the
document writes:
# 0.7
KINEMATICS = {
"mates": [cadgen.revolute("elbow", parent="#upper_arm", child="#forearm",
origin=(80, 0, 0), direction=(0, 0, 1), limits=(0, 150))],
"poses": {"bent": {"elbow": 60}},
}
@step(out="../STEP/arm.step", kinematics=KINEMATICS)
def arm():
...
return bd.Compound(children=[upper_arm, forearm], label="arm")# 0.8
from cadgen import model
from cadgen.ap242 import mechanism_state, posed
ELBOW = ((80, 0, 0), (0, 0, 1)) # numbers at module level; the Axis in the body
@model
def arm():
...
elbow = bd.Axis(*ELBOW)
bd.RevoluteJoint("elbow", upper_arm, axis=elbow, angular_range=(0, 150))
bd.RigidJoint("elbow", forearm, bd.Plane(origin=elbow.position, z_dir=elbow.direction).location)
upper_arm.joints["elbow"].connect_to(forearm.joints["elbow"], angle=0)
assembly = bd.Compound(children=[upper_arm, forearm], label="arm")
return mechanism_state(assembly, "bent", elbow=60)
@model
def arm_bent(): # a posed file is a model of its own
return posed(arm().shape, "bent")| 0.7 | 0.8 |
|---|---|
cadgen.revolute(name, parent=, child=, origin=, direction=, limits=) | bd.RevoluteJoint on the parent's part, a bd.RigidJoint of the same label on the child's |
cadgen.slider | bd.LinearJoint (linear_range) |
cadgen.cylindrical (.turn, .travel) | bd.CylindricalJoint, valued (angle, distance) |
cadgen.fastened | two bd.RigidJoints of one label, one on each part |
"poses": {"bent": {...}} | mechanism_state(assembly, "bent", **values) |
cadgen.couple(name, {dof: ratio}, limits=) | gear_pair (revolute joints), rack_and_pinion_pair (a revolute joint and prismatic ones) or screw_pair (one cylindrical joint's pitch); the range comes from the joints' limits |
a mate axis given as a ref ("#lever.f2") | a bd.Axis computed in the body from the live shape |
cadgen export ... --pose NAME (an 0.8 preview), snapshot --kinematics | a posed model posed(arm().shape, NAME), exported; cadgen snapshot <id> out.png --pose NAME to draw one |
The as-built state is now the value each joint stands at, so a joint whose two frames coincide as built reads 0 and keeps the parts where they were built. A coupling of one joint is that joint. The page's Position poses a document live, with a slider per coupling and per joint no coupling moves, and the mechanism states as presets. A STEP export is placements only: STEP carries no mechanism.
A nested assembly pairs its joints by label, not by connect_to. build123d's
connect_to composes a part's location within its own compound, so it can place a child
only where it sits in the same compound as its parent, as in the example above. A 0.7 mate
could name any two occurrences of the tree (#shoulder_yoke deep in one sub-assembly,
#servo in another). For those, build the assembly where it stands, author both joints
there with the mate's name as their label, and call no connect_to: the engine pairs a
moving joint with the rigid joint of the same label (the nearest in the tree), and two rigid
joints of one label fasten their parts. Two details decide whether the values read right:
- Give each joint in its part's enclosing frame. A joint constructor reads its frame in
the frame its part's
locationis in -- the compound that holds the part -- not the world. Carry a world datum in first:axis.located(holder.inverse()), whereholderis the world location of the part's enclosing compound (the product of the locations above it). - Put the child's rigid frame at the revolute joint's own frame, not at a plane made from
the world axis:
child_holder.inverse() * parent_holder * revolute.location. A plane of your own differs from the joint's by a turn about the axis, so the value as built is that turn instead of 0, and every mechanism state and motion is off by it.
def author_joints(arm, mates): # mates: step 1's records, at joint zero
nodes = {} # label -> (part, its holder's world location)
def walk(node, holder):
nodes.setdefault(node.label, (node, holder))
for child in node.children or ():
walk(child, holder * node.location)
walk(arm, bd.Location())
for m in mates:
(p, p_holder), (c, c_holder) = nodes[m.parent[1:]], nodes[m.child[1:]]
if m.kind == "revolute":
axis = bd.Axis(m.axis["origin"], m.axis["dir"]).located(p_holder.inverse())
joint = bd.RevoluteJoint(m.name, p, axis=axis, angular_range=tuple(m.limits["value"]))
bd.RigidJoint(m.name, c, c_holder.inverse() * p_holder * joint.location)
else: # fastened: at the child's own origin
frame = c_holder * c.location
bd.RigidJoint(m.name, p, p_holder.inverse() * frame)
bd.RigidJoint(m.name, c, c_holder.inverse() * frame)cadgen inspect <id> lists the joints with each one's range and its value as built (0 for
every joint when the frames are right), and the mechanism states. A 0.7 fastened mate
between occurrences the tree already nests needs no joint: a part below a jointed
sub-assembly moves with it.
5. Move clips to configuration sequences and animations
A 0.7 clip was a JavaScript module string on @step(animation=...), its update(t, m)
moving occurrences directly. 0.8 has two layers, each true to its format:
-
The mechanism's own motion (a gait, a door opening, an engine running, a robot's choreography) is a configuration sequence over its joints, kept in the document:
from cadgen.ap242 import configuration_sequence configuration_sequence(turntable, "spin", sweep={"platter": (0, 360)}, duration=4, ease="linear") configuration_sequence(arm, "cycle", [(0, "folded"), (2, "reach"), (5, "folded")]) configuration_sequence(arm, "showcase", pose_at, duration=23.4) # pose_at(t) -> {joint: value}A clip whose
update(t, m)computed its pose fromt(keys eased by hand, a breathing drift on top) takes the last form: port the pose computation to a Python function oftthat returns joint values by joint label, and the engine samples it to within 1e-3 radian. A clip that rotated occurrence ids about mate axes, and counter-rotated parts mated elsewhere, rotates nothing now: the joints say what each value carries. The page's Motion tool plays a sequence, and every GLB exported from the model carries it as a glTF animation of its name. -
A showcase (an explode, a reveal, a part spinning for show, a cover hidden) is a GLB's own animation, never written into the document:
from cadgen.gltf import animation show = animation(box, "showcase", duration=4) show.explode("feet/*", direction=(0, 0, -1), distance=20, start=0.5, end=2) show.rotation("latch", axis=(0, 0, 1), turns=2, start=1, end=3, interpolation="LINEAR") show.hide("latch", at=3)It is baked into every GLB exported from the model:
cadgen export <id> box.glb,export(box, "box.glb"), orcadgen export box.xbf box.glbfrom an xbf the model exported, which records the compiled tracks. The page and a STEP show nothing of it. The viewer's Animation section plays a GLB's animations.
Remove helper joints that existed only to slide parts apart for an explode: that is an
animation now. A clip's loop, label and description have no counterpart (a player
repeats a clip, and a sequence is called by its name), nor do .opacity and tube
deformation; .visible(false) is .hide. Snapshots never play motion: 0.7's
--animation, --time and --video are gone.
6. Move materials into the body; make colours hex
materials= on the decorator is gone. Use bd_materials, build123d's native material
library. Set a material in the body after the part's last geometric operation, then
assign any explicit colour:
# 0.7
@step(materials={"definitions": {"cast": {"name": "As-cast steel", "roughness": 0.85, "metalness": 0.2}},
"assignments": [{"targets": ["#housing"], "material": "cast"}]})
# 0.8.1, in the body
from bd_materials import metals
from cadgen import paint
cast = metals.mild_steel()
cast.pbr = cast.pbr.override(roughness=0.85, metalness=0.2)
housing.material = cast
housing.color = "#2E3742" # material assignment sets colour; apply an override after itChoose the material and its look. Catalogue factories such as metals.aluminum(),
metals.brass() and plastics.abs_() return a native FinishedMaterial (plastics is
also imported from bd_materials). Its .material holds physics; .pbr is a native
threejs_materials.PbrProperties. Edit the look with .pbr.override(...) and assign
that result back before giving the material to the shape. Its controls include
color, metalness, roughness, ior, clearcoat, clearcoat_roughness, anisotropy,
anisotropy_rotation (radians), transmission, attenuation_color,
attenuation_distance (metres), emissive, emissive_intensity, and opacity.
For custom physics, use a native family factory:
from bd_materials.core import Range
alloy = metals.custom_metal(
"Project alloy", density=2700,
modulus_of_elasticity=Range(68, 72), tensile_strength=Range(280, 320))Density is a single value in kg/m³. Mechanical properties are native ranges, with
modulus in GPa and strengths in MPa; a custom factory also accepts a number as an exact
range. shape.mass() and the physical material's mass(volume_mm3) return grams by
default; cadgen inspect reports kilograms.
Assign materials before colour overrides. Native material assignment sets the shape's
colour, including an inferred preview alpha for transmission (transmission=1 gives
alpha 0.3), even with PBR opacity=1. To keep an opaque base colour with physical
transmission, assign an opaque housing.color after its material, as above. An assembly
material is inherited by children without one; assign it before reading their materials.
paint(part, faces, colour_or_material) gives faces their own colour or native material.
Colours are sRGB, as you pick them. Shape colours and plain paints take hex strings
("#2E3742", "#38414D6B" with alpha as a byte), 0–255 integer tuples or build123d
Color. Native PBR base-colour floats are sRGB ratios; emission and attenuation floats
are linear. Hex strings avoid that distinction.
| 0.7 | 0.8.1 |
|---|---|
srgb("#2E3742") | "#2E3742" |
srgb("#38414D", 0.42) | "#38414D6B" |
A linear base colour (0.2, 0.3, 0.9) in a material definition | Set the look with material.pbr = material.pbr.override(color="#7c95f3") before assigning the material; the sRGB hex preserves the same look |
paint(shape, faces, (1, 0, 0)), paint(..., "orange") | paint(shape, faces, "#ff0000") or "#ffa500": a hex string, 0–255 integers, a build123d Color or a native FinishedMaterial |
shape.color = bd.Color(0.5, 0.5, 0.5) meant as linear | read as build123d defines it, sRGB: #808080. For the old look, give the hex of the linear value ("#bcbcbc" for 0.5) |
XBF keeps native physics and the complete resolved PBR look. The viewer and GLB retain scalar PBR controls; OCCT snapshots use their documented approximations. Native texture maps survive XBF, but the viewer, GLB export and snapshots refuse them until UV mapping is supported.
7. Learn the one engine: ids, pages, links and commands
0.7 had a build daemon, a separate viewer process with page sessions, and a store. 0.8
has one engine per installation: it runs the warm workers that build models, holds
their documents, and serves the viewer's one page. The first run, command or
cadgen viewer starts it, and no timer stops it.
Documents and their ids.
- Every document has an id, a UUID: a model's comes from its script's path and its
function's name, so it is the same every run (
bracket.idin Python, and the handle's.id). A model's identity is its namespace, the folder of its script, and its name, the function's by default.@model(name="bracket")(orname=on a file decorator) gives it an id of that folder and that name instead, the same whichever file of the folder declares it. The same name in two folders is two models; in one folder a second declaration is refused, naming bothfile:line, until the file that held the name is gone or has run again without it (cadgen run <that file>). A script moved or renamed without an edit keeps its document: its next run re-attaches the old record (history, pins, picture and saved build) to the new place. A function renamed keeps its document when it has aname=, and is a new document when it has none. A file the viewer opens has an id of its path. A document's page is/<uuid>on the engine's address, and a run prints it asview:(the handle's.url). - The commands take an id or a file.
cadgen export,cadgen snapshotandcadgen inspectread the document as the engine holds it, and never run a script: a script (x.py,x.py::fn) is refused as a source. - A document is what its last run made. The engine does not watch your script, never
compares it with the document, and never says a document is stale: there is no staleness
badge, notice or check (0.7's
cadgen store whyhas no successor). When the code changed, run it again; a run that finds nothing changed istook ... nothing ran. - The engine never reruns code. A document it holds no file of any more (its file in the
engine's cache deleted by hand, or never saved) is answered, by its page, by
cadgen inspect <id>and by the CAD app, with the command that brings it back:cadgen run <the script>. A restart or the engine's memory budget never does this: the cache keeps every document.
The store, the records and the cache. 0.7's store (content-addressed objects and an
index) is gone, and no decorator takes a store (@model(store=...), which 0.8 previews had,
is an unexpected keyword argument).
- Every document has a record in cadgen's state folder, beside your settings
(
documents/<uuid>/document.json: the script and function that build it, or the file's path; never geometry). The home lists them. - Every model's document is cached as last built (
documents/<uuid>/document.xbfin the cache folder,~/.cache/cadgenby 0.7's rule), so documents reopen after a restart, as last built, with nothing run. The cache has no size cap and nothing evicts from it; a file opened in the viewer is never cached (the file is its copy). cadgen delete <id>(or a model's script, for every document recorded of it, or a file's path), or Delete in a card's menu on the home, deletes a document: its record and its cached document. Your script and its files stay.- A model lives in a
.pyfile. Its record points at the script. - A notebook hands its shape over. In a notebook cell or a REPL, build the shape and
call
model(shape, name="bracket"): the engine holds, caches and serves a document of it, exports it like any other, and returns the same handle (.shapeis your shape). Joints, mechanism states and sequences on the shape go with it; a GLB's animations are passed asanimations=[...]. Its id comes from the notebook's working folder and the name. Nothing builds it again: run the cell again.
Port 3245 and the day link.
- One port, kept. The engine serves on 3245 (or the port
CADGEN_ENGINE_PORTor--portnames). When another program holds 3245, the engine takes the next free port, says so once (3245 is held by <name> (pid N); this installation serves on 3246 and keeps it) and keeps that port, so links stay stable; once 3245 is free at a start it moves back (back on the default port 3245: links made on 3246 no longer work). Another 0.8 release's engine that nothing uses is stopped for 3245; one still in use is rolled past. A 0.7 CAD Viewer still on 3245 is named in that line too: 0.7'scadgen viewer stopfrees it. A port you name is never moved: held, the engine refuses to start and names the holder. - A printed link is good for a day. Every page URL the engine prints or opens -- a run's
view:line,cadgen viewer's output, the CAD app's Open in browser -- carries?token=<expiry>.<signature>, valid for 24 hours. A browser that opens it is signed in with a cookie good for 30 days from its last use, on any port, acrosscadgen stop, a crash and a reboot; an open page that lost its engine reconnects on its own when the engine comes back. A link past its day, in a browser that is not signed in, shows "This CAD Viewer page needs its link": run the model again, orcadgen viewer <id>, and open the fresh link.cadgen server --rotate-token, run with the engine stopped, retires every link and session handed out before it. - No page sessions.
/s/<session>/...,?file=and?doc=links open the home.
The commands.
| 0.7 | 0.8 |
|---|---|
python model.py | cadgen run model.py: builds the models its __main__ calls |
cadgen daemon status | cadgen status: the engine's workers, the documents it holds, its port and its cache |
cadgen daemon | cadgen server: runs the engine in this process |
| (none) | cadgen stop: stops the engine, and any older one left running |
cadgen viewer --detach, --new, cadgen viewer stop, cadgen viewer list | cadgen viewer [FILE or ID ...]: ensures the engine, registers each file, prints each page (--json: one line with each document's url), exits |
<viewer url>?file=<path> | /<uuid>, printed by the run or by cadgen viewer FILE |
cadgen step build IN OUT, cadgen stl|3mf|glb build | cadgen export SRC DST [DST ...], SRC an id, an .xbf, a .step, or a mesh (to the other mesh kinds) |
cadgen step compile | nothing: the viewer and snapshots read a STEP as it is |
cadgen step snapshot, cadgen stl|3mf|glb snapshot | cadgen snapshot SRC OUT.png, for every kind |
snapshot --kinematics | --pose |
snapshot --focus, --hide | --display '{"isolated": [...]}', --display '{"hidden": [...]}' |
snapshot --mode list | the model's tree: [part.label for part in assembly().shape.leaves] |
cadgen store why|where|forget|gc|info | no store to manage: cadgen inspect <id> prints what a document holds and what it was built from, cadgen delete <id> deletes it, and a run says whether anything changed |
cadgen telemetry status|on|off | the same |
| (none) | cadgen doctor [--prune]: sets cadgen up, reports it, and clears what nothing needs (0.7's store among it) |
--no-daemon is gone from every command, and cadgen build and cadgen.build(), which
0.8 previews had, are gone too: the only way to build is a decorated function called
from Python, in a script. A shape made elsewhere -- a notebook cell, a REPL -- is handed
over with model(shape, name=...).
The home and the page.
- The home is the library alone.
/lists, under Recent, every model built and every file opened, as tiles or a table, pinned first, then by last activity, with a type filter (All, Models, Files), a search, and Open (the desktop's file chooser). A tile says its last activity with a verb: "Edited 2m ago" when the document changed after a page last opened it, "Viewed 16m ago" when a page opened it after the change. The table's columns are Name, Updated (when it last changed) and Created (when its record was first made: a model's first run, a file's first open). No model is shown with the script that built it. A card's menu holds Open, a file's Copy path and Reveal, Pin, and Delete, which asks first. 0.7's Recents are not read, and a launch's folder is no longer listed: the home starts empty after the upgrade and fills as you run models and open files. A model page's Files menu lists the folder the explorer was last in, else your home folder, never the script's. - Exports are downloads. The viewer's Export (the download button at the navbar's
right) is a browser download: pick a format, a "Preparing..." toast shows while the engine
writes the file, and the browser saves it where it saves downloads. There is no export
dialog, destination or jobs panel. An exported file, from the viewer,
cadgen exportor a file decorator, is a detached copy: its page follows the file on disk, never the model, and nothing reruns it.
The CAD app (MCP) shows a model by its id or a file by its path (cad_show; every CAD
tool names the model in source, where cad_show and cad_open took path in 0.7). How it
looks depends on the host:
- Claude Desktop and other MCP Apps hosts draw a card per
cad_show: the whole viewer at card size under its navbar (the logo and app menu, Back and Forward, the name menu, then Full size where the host offers it and Open in browser last; no Export, as the host has no downloads). A newer card retires the older ones. - The Codex app shows CAD in its sidebar (the home) and in a CAD tab beside each thread, both under the same navbar, and Open with CAD for a model file, which shows that file alone, with no navbar.
- Text hosts (Claude Code in a terminal,
codex exec) draw nothing:cad_showopens the model's page in your browser, from the agent's own environment, and answers with its link (or says it is already open there, or that no browser can be opened from there).
An agent writes files with cad_export, draws with cad_snapshot and asks with
cad_inspect, on every host.
8. Replace read_scene refs, checks and tools that read 0.7's files
References are the engine's grammar, for models and STEP files alike. A 0.7 ref,
/work/STEP/assembly.step#o1.2.f7, named an occurrence by its position and a face by its
number in one saved revision, and read_scene(path).resolve(ref) resolved it; the viewer
had a grammar of its own for STEP pages. Both are gone. A 0.8 ref names the document (a
model's id, or a file's absolute path), #, the occurrence by the labels on its way from the
root, then the element by the code that made it, or by its number:
b48e875e-f53d-5535-ada3-a2a300690f6f#kit/hand/finger.2/f:finger.body.3;M:finger.relief
/work/STEP/assembly.step#assembly/bracket/face 7hand/finger.2 is the second component labelled finger in hand; a label with spaces is
written as it is. Element names come from the function and the variable that made each
feature, so moving code renames nothing and a dimension edit keeps every name; a STEP that
0.8 exported carries them too. The viewer copies refs in this form (Quick Edit's
References:). Resolve one with cadgen inspect:
cadgen inspect <uuid> "hand/finger.2/face 7"
cadgen inspect STEP/assembly.step "assembly/bracket/face 7"It answers what the ref names, with the kernel's facts and made_by, the function, file
and line of the code that made the element. An old ref resolves to nothing and is refused
with the nearest names (has no part or assembly o1.2.f7; nearest: ...): select again in
the viewer, or take the names cadgen inspect prints. Code of your own that addresses
occurrences by tree position (o1.2.15) for its own purposes may keep doing so; cadgen no
longer reads them.
A check calls the model and measures what it returns. Copy the project helpers
world_parts and find_part from
Opening geometry
into the check first. They accumulate each parent's placement before measuring and
refuse a missing or ambiguous leaf label:
# 0.7 # 0.8
from cadgen import read_scene from cadgen.geometry import closest_points
scene = read_scene("STEP/kit.step")
... from kit import kit
tree = kit().shape
plate, post = find_part(tree, "plate"), find_part(tree, "post")
print(closest_points(plate, post).distance)cadgen.geometry (closest_points, overlap_volume, mass_properties, the topology
checks) is unchanged. In 0.8 previews, select(...) resolved refs in Python; it is gone
too, for cadgen inspect and build123d's selectors in the body, and
snapshot_job(packet, source) is cadgen.snapshot(source, job=packet).
A tool that read 0.7's files reads the model. Project tooling built on 0.7 -- a URDF
exporter, a mass report, a collision checker -- often read the STEP's <name>.step.json
sidecar (its kinematics block, childId occurrence ids) or reached into cadgen's private
modules (cadgen.store.trees.capture_tree, cadgen.store.objects.read_object,
cadgen._internal.doors.document_tree). The sidecar is never written and the modules are
gone. Read instead:
- the geometry from the model,
robot().shape, or from an exported STEP withread_step. Both keep a tree of.childrenand parent-relative.locationvalues;.leavesalone does not apply ancestors' placements. Useworld_partsabove for measurements in world coordinates; - the mechanism from your own data (step 1's records), or from
cadgen inspect <id> --json, whose summary lists the joints, their ranges, the states and the sequences.
Three things differ from what 0.7's store handed such a tool. read_step gives the STEP's root
assembly wrapped in a compound of the same name: tree-position ids (o1.2.15) count from the
assembly inside it. A part's .color is the sRGB a person picks (#A7ACB0 reads 0.655, where
0.7's store gave the linear 0.386), so a glTF writer converts it to linear. And no per-face
colour is read back: a vendor board's painted faces take the part's colour. Equal parts share
one shape (node.wrapped.TShape()); a digest of the part's own BRep at its origin keys them.
9. Delete 0.7 leftovers
-
Sidecars:
<name>.step.jsonand.params.jsfiles beside your STEP files are read by nothing. Delete them once each model is ported. -
Old exports: STEP, STL, 3MF and GLB files 0.7 runs wrote stay where they were and nothing rewrites them, the STEP files of stages that are
@memonow among them. Export them again from the ported models, or delete them. -
The project's 0.7 notes: commands and rules in its README or
AGENTS.mdthat nameuvx ... cadgen==0.7.x,--force,cadgen store why,cadgen step snapshot,cadgen viewer --detach,?file=links orfrom cadgen import build123d. -
The 0.7 store. cadgen 0.7 kept a cache store that can hold gigabytes (
objects/andindex/in its cache folder), and a few state files of its own (its sidebar views, its snapshot browser's lock, its viewer's log, its Recents log). 0.8 keeps its own document cache in the same folder, underdocuments/, and never reads or writes 0.7's. Whether a 0.7 is still installed cannot be told (0.7 never registered itself), so they retire themselves:cadgen doctorsays they are there, with their size and when they were last written, andcadgen doctor --pruneremoves them once nothing has written them for 7 days -- a 0.7 in use writes its store at every build:removed cadgen 0.7's store and 2 state files (92.0 MB), last written 2026-10-14Once no 0.7 is left in any agent app (no 0.7 plugin anywhere),
cadgen doctor --prune --all-versionsremoves them at once, however recently written. 0.8 loses nothing either way.Platform 0.7's store is in macOS, Linux ~/.cache/cadgen, or$XDG_CACHE_HOME/cadgenwhenXDG_CACHE_HOMEis setWindows %LOCALAPPDATA%\cadgenanywhere the folder CADGEN_CACHE_DIRnamed, if you set it for 0.7Your settings, telemetry answer and recent files live in cadgen's state folder and stay.
-
Quick Edit's preference: Quick Edit is always available; a
features.quickEdit: falseleft in settings does nothing.
10. Verify
- Run each root script:
cadgen run src/assembly.pyexits 0 and prints an id and a page for every model it calls. A second run takes the documents (took ... nothing ran). - Run
cadgen inspect <id>on each mechanism: its joints, each at 0 as built, its states and its sequences. - Open each page and compare it with the 0.7 model: parts, colours, materials and the tree. For a mechanism, try Position's sliders and presets, and play each motion.
- Run your checks and tests: they call the models now.
- Export what you deliver and compare it with the 0.7 files you kept, by snapshot
(
cadgen snapshot STEP/old.step a.pngbesidecadgen snapshot <uuid> b.png) and by measurement:cadgen inspecton both files gives their part counts and bounds, andcadgen inspect STEP/old.step <part>besidecadgen inspect <uuid> <part>each part's world bounds. Equal overall bounds do not prove equal placements: compare the parts of every sub-assembly a stage moved (step 2, item 8). Keep the 0.7 STEP until they agree.
Telemetry
Your answer carries over in the same settings, cadgen telemetry status|on|off works as
before, and DO_NOT_TRACK=1 or CADGEN_TELEMETRY=0 turns it off for a process. New in
0.8: the viewer also counts which of its tools and settings are used, each as a name from a
fixed list (Select, Measure, Explode, Clip, the display modes, Preview, playback, Export, the
home's search and filters, and the like), with how many times each was used and, for a tool
that stays on, how many whole seconds it was on -- never what you typed, a value you chose
(other than a choice that is itself a name on the list, such as a display mode), or a file's
or a part's name. The CAD app's cad_telemetry tool is gone: you answer in the CAD app's
menu, the viewer's, or with cadgen telemetry.
What lands where
| Thing | 0.7 | 0.8 |
|---|---|---|
| A model | @step(out=...) (or a mesh decorator) on a parameterless function | @model on a parameterless function; parameters on plain helpers |
| A cached stage | a child model writing its own STEP | @memo on the stage function, no file |
| A run | uvx ... cadgen==0.7.x python model.py, writing every declared file | cadgen run model.py, writing nothing; it updates the document and its pages |
| A file | written by every run, or by cadgen <format> build | written on request by cadgen export, or by exports.py |
| The model's document | a STEP plus a <name>.step.json sidecar | held by the engine at /<uuid>; an .xbf when saved as one |
| Kinematics | kinematics= mates, couplings, poses, in the sidecar | build123d joints and cadgen.ap242, in the document |
| Animation | a JavaScript clip module in the sidecar | configuration_sequence (the document) or animation() (a GLB) |
| Materials | materials= definitions and assignments | part.material = ... in the body |
| Colours | linear floats, srgb(...) | sRGB hex or 0-255 integers |
| Refs | #o1.2.f7 | <id or path>#path/to/part/f:function.feature.n |
| Stale or current | cadgen store why | a run: took ... nothing ran, or rebuilt: <what changed> |
| The cache | the store in ~/.cache/cadgen | the warm worker's memory, and each model's document as last built in ~/.cache/cadgen/documents, kept until deleted, with the engine's bytecode under pycache/ |
| The viewer | its own process, ?file= links, page sessions | the engine's one page, /<uuid>, on port 3245, links good for a day |
Troubleshooting a half-migrated project
- A run prints nothing and exits 0. The script's
__main__calls no model, or the model is still undecorated. Decoration only declares; add the calls. (A script that only callsexport()prints a line per file it wrote.) - The project still writes STEP files and sidecars. Its commands still run 0.7
(
uvx ... cadgen==0.7.x): Prerequisites, step 2. ModuleNotFoundErrorfor one of the project's own packages.PYTHONPATHdoes not name the import root (Prerequisites, step 3).TypeErrornamingkinematics,materialsoranimation. A decorator still carries a 0.7 argument. Move it into the body (steps 4 to 6).ImportError: cannot import name 'build123d' from 'cadgen'. Step 1:import build123d as bd.ImportErrororAttributeErrorforrevolute,fastened,couple,srgb,report,track, or acadgen.storeorcadgen._internalmodule. Step 1's table; step 8 for tools.AttributeError: 'Document' object has no attribute 'moved'(or another shape method): a child model's call used as a shape. Composechild().shape(step 2).- The model builds, but some parts sit a few millimetres from where 0.7 put them, with the same overall bounds. A stage moves leaves inside a sub-assembly that keeps its own placement in 0.8: hand it the 0.7 shape (step 2, item 8).
- A joint's value as built is not 0, or every state looks turned. The child's rigid frame is not the revolute joint's own frame (step 4).
- A build fails naming a pair the built tree contradicts. A part moved after its
connect_to, orconnect_toacross compounds: author the joints where the parts stand and pair them by label (step 4). - Colours look washed out or too dark. A colour meant as linear floats is now read as sRGB: give the hex of what you see (step 6).
- A link opens the home instead of the model. It is a 0.7 or pre-release link
(
?file=,/s/...). Run the model and use the page it prints. - A page says it needs its link. Its link is more than a day old, and this browser has
not been signed in within 30 days: run the model again, or
cadgen viewer <id>. - A page or
cadgen inspectsays the document is not saved. Its file in the engine's cache is gone (deleted by hand), or was never written (the cache folder could not be written). Run the command it prints. - The viewer shows an old mechanism or none. A sidecar is read by nothing: the mechanism must be in the model's body (step 4).
Code written against an 0.8 preview
Projects written against a 0.8 pre-release may use names the release renamed or removed, and the engine such a project ran holds records and documents made under the pre-release's identities and build closures.
key="x" is now name="x". key= is an unexpected keyword argument. A name belongs to
the folder of its script: the same name in two folders is two models, and in one folder a
second declaration of it is refused, naming both file:line, until the file that held it
is gone or has run again without it (cadgen run <that file>). Moving a name to another
file of its folder keeps its document.
Saved XBF documents remain usable. cadgen 0.8.1 writes xbf/9 and reads both
xbf/8 and xbf/9. Opening an xbf/8 file or cached snapshot automatically converts its
material metadata in memory, so viewing, inspection, snapshots, imports and exports need
no model source or execution. Source and cache bytes, the cache record and revision, and
the original build closure and toolchain provenance remain unchanged. A separate migration
record describes the conversion. Reading an upgraded document again is idempotent.
To save the upgraded document, choose a different XBF path:
cadgen export saved-v8.xbf upgraded-v9.xbfThe complete upgraded XCAF document is saved atomically; exporting over the source path is refused. Exporting a cached document by id to XBF also saves its upgraded form. The viewer's original-file XBF download still returns the original bytes; use the command above to save an upgrade. Ordinary current-format XBF-to-XBF translation remains refused. Unsupported formats or failed conversions preserve the original bytes and cache record and report a clear error.
When you explicitly run a model's source, its original build key is compared with the current one and the model builds normally when they differ. Saved-document access does not imply build-cache reuse. See the persisted-document policy.
The independent startup identity pass still gives each JSON record its namespace and
name, and a model's record the fingerprint of its script. A record that a key= named
moves, with its saved document, to the id its folder and name give. This changes identity,
not the saved document's format. A record that cannot be read or moved stays as it is,
is never deleted, and is counted by cadgen status.
Rename key= to name= in the scripts. The models keep their ids. The other names the
release renamed or removed:
| Before | Now |
|---|---|
from cadgen.engine import model, memo, ... | from cadgen import model, memo, ... |
configuration(assembly, name, **values) | cadgen.ap242.mechanism_state(assembly, name, **values) |
motion(assembly, name, ...) | cadgen.ap242.configuration_sequence(assembly, name, ...), the same arguments |
couple(...) of revolute joints | gear_pair(assembly, name, **joints) |
couple(...) of a revolute joint and prismatic ones | rack_and_pinion_pair(assembly, name, **joints) |
couple(assembly, name, joint=(turn, travel)) of one cylindrical joint | screw_pair(assembly, name, joint=360 * travel / turn): its pitch; the value is now the turn in degrees |
from cadgen import mechanism_state, configuration_sequence, gear_pair, ... | from cadgen.ap242 import ... |
from cadgen import animation | from cadgen.gltf import animation |
cadgen build SOURCE, cadgen.build(code_or_shape, ...), cad_build | none: a decorated function called from Python, in a .py file; a shape made elsewhere is handed over, model(shape, name=...) |
@xbf + @glb stacked so a GLB bakes its animations | @model; cadgen export <id> model.glb or export(x, "model.glb") bakes them |
a model call returning its shape (base = plate() used as a shape) | the call returns the document's handle: compose plate().shape |
@model(store="copy"), store="pointer", store="memory" | none: no store argument. A model lives in a .py file; a cell's shape is handed over, model(shape, name="plate") |
@model(id="<uuid>") | none: an id is derived (the script and the function), or name="plate" names one within its script's folder |
@model stacked with @xbf, @step or another file decorator | one or the other; the stack is refused |
Model.export(...), Model.snapshot(...), Model.document on the decorated function | the handle a call returns: arm().export(...), arm().snapshot(...), or export(arm(), ...) |
cadgen export DOC OUT --pose NAME, export(..., pose=) | a model returning posed(assembly, NAME), exported |
cadgen export DOC OUT --part OWNER, export(..., part=) | the part's own @model, exported |
cadgen export ... --no-daemon, cadgen snapshot ... --no-daemon | the same command without the flag |
select(source, ref, kind=None) | cadgen inspect DOC REF (cadgen.inspect(DOC, REF)) |
cadgen.engine.api.snapshot_job(packet, source) | cadgen.snapshot(source, job=packet) |
cadgen.serve(doc), cadgen.status(), cadgen.stop(), cadgen.daemon() | the commands cadgen serve DOC, cadgen status, cadgen stop, cadgen server |
a stale badge, a stale notice on export, snapshot or inspect | none: a document is what its last run made; run it again |
GET /__cad/browser (a card's lookup of a browser page) | none; a card's Open in browser is POST /__cad/browser/open, the app's alone |
a page at /?doc=..., /?file=..., /s/<session>/... | /<id>; an old link opens the home |
XBF/model.xbf written by every run as the model's cache | no file: the engine caches the document; export an xbf only as Save As |
Migration complete when
- Every model is
@modelon a parameterless function, its values on plain helpers, and each variant a named model; cached stages are@memo. -
import build123d as bdeverywhere; nofrom cadgen import build123d, no private cadgen module. - The project's own docs run
cadgen runandcadgen, withPYTHONPATHwhere it needs one. - No
kinematics=,materials=oranimation=anywhere; mechanisms use build123d joints andcadgen.ap242, showcasescadgen.gltf. - Every colour is hex or 0-255 integers.
- Deliverables come from
cadgen exportor anexports.py. - No
.step.jsonor.params.jsfile remains, and no tool reads one. - Every root script runs clean and prints a page for each model; each page has been opened and reviewed.
-
cadgen doctornames no 0.7 store, or says when--pruneremoves it.