CAD as code
Extension — not covered by the 1.0 stability promise (
cad; the core)
A part's shape can be written as code, beside the model, and checked like the
rest of it. The shape is a Python file that uses
build123d (OpenCascade underneath). The
model names the file, says what the part is made of, and states the limits it
must keep. archec cad builds the shape, measures it, and records what it
proves.
This page builds the enclosure of the greenhouse thermostat
(the board tutorial): a tray for the NUCLEO-F446RE, the
relay module and the BME280 breakout. The finished files are in
examples/greenhouse/: mechanical.arche and the cad/ folder.
What you need#
The CAD engine is build123d 0.13.0 with OpenCascade, about 850 MB once installed. arche-lang never downloads it.
- In VS Code, install the build of the extension for your machine
(
arche-lang-darwin-arm64.vsix,-darwin-x64,-linux-x64,-linux-arm64or-win32-x64). It carries the engine and a Python of its own. The first time you build a shape, the extension sets the engine up from the files it carries. That takes about a minute and uses no network. The engine is kept in~/.arche/cad, soarchecin any terminal finds it afterwards. - Without the extension, use a Python that has build123d:
python3 -m pip install build123d==0.13.0, then point archec at it withARCHE_CAD_PYTHON=/path/to/python(or--python, or a.venvbeside the model).
The generic arche-lang.vsix has no engine. Everything else in it works, and
Show CAD in 3D says that the platform build is needed.
To try it with nothing installed, open the Greenhouse enclosure (CAD) example of the playground. There the shapes are built in your browser: see In the playground.
1. Write the shape#
A shape file defines part: one build123d solid. Lengths are in millimetres.
# cad/enclosure.py
from build123d import Align, Axis, Box, Location, Pos, fillet
MIN = (Align.MIN, Align.MIN, Align.MIN)
WALL, FLOOR, GAP, STANDOFF = 2.0, 2.0, 3.0, 5.0
BOARD = (70.0, 82.5) # NUCLEO-64 outline
RELAY = (26.0, 50.0)
inner_x = GAP + BOARD[0] + GAP + RELAY[0] + GAP
inner_y = GAP + BOARD[1] + GAP
size = (inner_x + 2 * WALL, inner_y + 2 * WALL, FLOOR + 26.0)
shell = fillet(Box(*size, align=MIN).edges().filter_by(Axis.Z), 3.0)
part = shell - Pos(WALL, WALL, FLOOR) * Box(inner_x, inner_y, 26.0, align=MIN)
# where the other parts sit
anchors = {
"board": Location((WALL + GAP, WALL + GAP, FLOOR + STANDOFF)),
"relay": Location((WALL + GAP + BOARD[0] + GAP, WALL + GAP, FLOOR + STANDOFF)),
}
anchors is optional. Each anchor is a named place on the part where another
part can sit: Location((x, y, z)), or Location((x, y, z), (rx, ry, rz))
to turn it (degrees). The full file adds the standoffs, the USB opening and
the vents.
A file may import other .py files beside it. A change to one of them counts
as a change to the shape.
2. Name it in the model#
component Enclosure "Enclosure" {
cad "cad/enclosure.py" { material PETG }
}
cad names the file, relative to the .arche file. The block after it says
what the part is made of, which gives its mass:
| You write | Meaning |
|---|---|
material PETG |
A material from the table below. |
material RESIN |
A constant of yours whose value is a density: const RESIN = 1.18g/cm³. |
density 0.45g/cm³ |
The density itself. Use it for a printed part with infill, which is lighter than its plastic. |
material and density can also be written on their own lines in the
component, or with cad in its physical group. Without either, the mass is not known and only the size and the
volume are measured.
Densities, in g/cm³: PLA 1.24, PETG 1.27, ABS 1.04, ASA 1.07, TPU 1.21, PA12 1.01, PC 1.20, POM 1.41, PMMA 1.18, FR4 1.85, aluminium-6061 2.70, steel 7.85, stainless-304 8.00, brass 8.50, copper 8.96, titanium 4.43.
A part of a system can have a shape of its own. It replaces the shape of its definition, if that has one:
part board: NucleoF446RE { cad "cad/nucleo.py" }
3. Build and measure#
archec cad mechanical.arche
Enclosure cad/enclosure.py PETG built
size 109 × 92.5 × 28 mm (x, y, z)
volume 41.15 cm³
mass 52.26 g (1.27 g/cm³)
centre of mass (54.69, 45.93, 7.85) mm
inertia Ixx 59256 Iyy 77288 Izz 128607 g·mm² (about the centre of mass)
anchors board (5, 5, 7) relay (78, 5, 7) sensor (85, 71.5, 7)
→ build/cad/Enclosure.step, .stl, .glb
For each shape, archec cad writes three files to build/cad/:
| File | Use |
|---|---|
Enclosure.step |
Exchange with other CAD tools. |
Enclosure.stl |
Print it. |
Enclosure.glb |
Look at it in 3D. |
A shape whose file did not change is not built again: its measures are kept
in build/cad/Enclosure.json. --force builds everything again and
--only Enclosure builds one shape.
If a file fails, the error names the line of the .py file and the cad
line of the model:
✗ cad/enclosure.py:31: NameError: name 'STANDOF' is not defined
mechanical.arche:33:3 the `cad` of Enclosure
A file must give exactly one valid solid. Two separate solids are an error: fuse them, or give each part its own file.
4. State the limits#
A requirement can bound what is measured:
requirement REQ-BOX "Fits the bracket" {
text "The enclosure shall be at most 120 mm × 95 mm × 40 mm, and weigh at most 80 g."
limit Enclosure.size <= 120mm, 95mm, 40mm
limit Enclosure.mass <= 80g
}
| Limit | Bound |
|---|---|
limit Enclosure.size <= 120mm, 95mm, 40mm |
Its bounding box along x, y and z, as the file builds it. One value bounds all three. |
limit Enclosure.mass <= 80g |
Its mass. The part needs a material or a density. |
limit Enclosure.volume <= 60cm³ |
The volume of its material. |
The comparison is <=, <, >= or >. Write each bound with its unit;
archec converts between mm, cm and m, between g and kg, and between
mm³, cm³, mL and L. A bound in the wrong kind of unit (size <= 120g)
is an error. The name before the dot is a component that has a cad, or a
part of a system (Assembly.board).
archec cad checks each limit:
✓ REQ-BOX Enclosure.size 109 × 92.5 × 28 mm <= 120 × 95 × 40 mm
✓ REQ-BOX Enclosure.mass 52.26 g <= 80 g
Once a shape is built, the editor warns at a limit that is not kept, without building again.
5. Place the parts#
In a system, at puts a part at an anchor of another part:
system Assembly "Greenhouse box" {
budget mass 150g
part box: Enclosure
part board: NucleoF446RE { cad "cad/nucleo.py"; at box.board }
part relay: GpioRelay { cad "cad/relay.py"; at box.relay }
part sensor: Bme280 { cad "cad/bme280.py"; at box.sensor }
clearance box, board >= 0mm
clearance board, relay >= 2mm
}
The origin of board is put at the anchor board of box. A part with no
at stays at the origin. A part can sit on a part that sits on another.
archec cad writes the placed parts to build/cad/Assembly.glb and
Assembly.step.
clearance a, b >= 2mm checks the least distance between two placed parts:
- Parts that touch are 0 mm apart, so
>= 0mmmeans "they do not run into each other". - Parts that run into each other fail every clearance. The message gives the volume they share.
A clearance in a system is a check of archec cad. A clearance in a
requirement is also evidence for that requirement:
requirement REQ-AIR "The sensor reads the air" {
text "The BME280 shall be at least 15 mm from the relay, whose coil warms the air around it."
clearance sensor, relay >= 15mm
}
The mass budget (budget mass 150g) adds up the measured mass of each part
that has a shape and a material, in the unit of the budget. A part with no
measured mass counts with the mass written on it, if any.
6. See what it proves#
archec cad records each limit and each clearance of a requirement in
.arche/evidence/cad.jsonl. archec status reads them:
REQ-BOX Fits the bracket
satisfied by Enclosure (box)
✓ cad Enclosure.mass build123d just now 52.26 g <= 80 g
✓ cad Enclosure.size build123d just now 109 × 92.5 × 28 mm <= 120 × 95 × 40 mm
A record depends on the requirement, the component (its material included)
and the shape's files. When one of them changes, the requirement is out of
date until archec cad runs again:
! cad Enclosure.mass build123d out of date: cad/enclosure.py changed
When a limit is not kept, archec cad exits with 1, the requirement is
failing, and archec why-not says by how much:
archec why-not mechanical.arche REQ-BOX
REQ-BOX Fits the bracket — Enclosure.mass: not kept
Enclosure weighs 52.26 g (41.15 cm³ of PETG at 1.27 g/cm³); the limit is <= 45 g: 7.26 g over
mechanical.arche:23 measured from cad/enclosure.py (build/cad)
To keep it: remove material (thinner walls, pockets), take a lighter `material`, or give a printed part its own `density`.
The question can also be a measure ("Enclosure.mass") or a clearance
("clearance sensor, relay").
7. Look at it#
- In VS Code: run Arche: Show CAD in 3D. It runs
archec cadand opens the result beside the editor, with the measures and the checks. - Anywhere:
archec cad mechanical.arche --html box.htmlwrites one page that needs no network.--only Enclosure --html …shows one shape.
Drag to turn, Shift+drag or right-drag to move, and use the wheel to zoom. The red crosses are the anchors. The page shows what was built: it does not run the engine.
In the playground#
The playground builds the shapes in your browser. The engine is the same
build123d 0.13.0, on OpenCascade compiled to WebAssembly
(OCP.wasm) and run by
Pyodide. It runs the same measuring code as
archec cad, so the measures and the checks are the same.
- A model's
.pyfiles are tabs besidemain.arche. The + above the editor makes one: typecad/box.py. - The CAD tab builds the shapes and shows the 3D page. The first time, it
asks before it loads the engine: 71 MB, from arche-lang.xyz only, kept by
the browser afterwards. A model with no
cadloads nothing. A model opened from a share link asks each time: its Python is someone else's. - A limit or a clearance that is not kept is a warning in Problems. A
file that fails is an error at its line of the
.pyfile. - When a
.pyfile changes, its shape is built again; the others are kept. - The 3D tab draws the built meshes, as in section 8.
Nothing is sent to a server: the Python runs in a worker of the page.
What the playground does not do: it writes no evidence (archec status),
runs no KiCad check, and gives no STEP or STL file to download. A shape
with a textured material from threejs-materials fails there, because its
texture images (90 MB) are not served.
8. Simulate what you built#
A part with a built shape is a body for the physics. archec gen --target mujoco and the 3D view use what archec cad measured, not what the model
writes by hand:
| The body's | Comes from |
|---|---|
| shape | The triangles of build/cad/<Name>.stl, written as mujoco/meshes/<Name>.obj beside the MJCF (in metres, in the part's frame). |
| mass | The measured mass (the volume times the density of the material). |
| centre of mass, inertia | The measured ones, in an <inertial> element. |
| place | Its joint … at, as before. With no joint, where archec cad placed it (at box.board). |
archec cad mechanical.arche
archec gen mechanical.arche --target mujoco
note: box: its geometry cad/enclosure.py, 0.052263 kg, as measured; it touches as its convex hull
<body name="box">
<inertial pos="0.054692589 0.045925409 0.007847611" mass="0.052263" fullinertia="…"/>
<geom type="mesh" mesh="Enclosure"/>
</body>
A part with a cad is a body even when it has no mass and no shape, and
the 3D view never draws it as an assumed box. Three cases are said plainly:
A written
massorshapediffers from the measured one. The measured one is used, andarchec checkwarns with both values:warning arm says `mass 50g` (50 g), and its geometry weighs 5.81 g (cad/board.py, FR4): the measured mass is the one used — remove the `mass`, or correct the material [cad-mass-differs]The mass may differ by 1 %. A
shapeis compared by its size along x, y and z, and may differ by 2 % or 1 mm (cad-shape-differs).The shape has no material. Its mass is not known. A written
massis used with the mesh; with none, MuJoCo takes the density of water, and a note says so.The shape is not built yet. The written
shapeandmassare used, or a 0.1 m box, and a note says to runarchec cad.
MuJoCo makes contact with the convex hull of a mesh: a tray touches like a solid block. The mass and the inertia are exact all the same, because they are given, not computed from the mesh.
The 3D view (the playground's 3D tab, Show CAD in 3D in VS Code) draws the
same meshes. It also shows a system in which no part says a shape or a
joint, such as the greenhouse box, with each part where it was placed.
9. The board meets the box#
A board has an outline and mounting holes. The box has standoffs. fits
checks that they line up.
Say what the board is#
For a board of your own, name its KiCad file:
component Controller "Controller board" {
pcb "hw/controller.kicad_pcb"
cad "cad/board.py" { material FR4 }
}
archec reads three things from the file, and needs no KiCad for that:
| Read | From |
|---|---|
| The outline | The bounds of what is drawn on the Edge.Cuts layer (lines, arcs, rectangles, circles, polygons). |
| The mounting holes | Each footprint named MountingHole…, or with the reference H1, MH1…: the centre and the diameter of its widest drill. |
| The thickness | The board's setup. |
For a bought board, write them in the model. The store's boards do this:
component Shield "A bought board" {
physical {
outline 50mm, 40mm
hole 3.2mm at 3.5mm, 3.5mm
hole 3.2mm at 46.5mm, 3.5mm
}
}outline is the size along x and y. Each hole is a diameter, then the
centre of the hole. They go in the physical group, like cad, or on lines
of their own. A pcb wins over written lines.
The board's frame. Its origin is the lower-left corner of the outline,
seen from the component side, with x to the right and y up. KiCad's y points
down, so archec turns it over. Draw the board's cad shape in the same
frame, with the solder side at z = 0. If the shape is not the size of the
outline (by more than 0.5 mm), archec check warns with both sizes
(cad-outline-differs).
Say where the screws go#
In the box's file, mounts lists the top of each standoff, under the name of
the anchor the board sits at:
# cad/tray.py
BOARD_AT = (5.0, 5.0, 8.0)
POSTS = [(3.5, 3.5), (46.5, 3.5), (3.5, 36.5), (46.5, 36.5)] # from the board's corner
anchors = {"board": Location(BOARD_AT)}
mounts = {"board": [(BOARD_AT[0] + x, BOARD_AT[1] + y, BOARD_AT[2]) for x, y in POSTS]}
The points are in millimetres, in the frame of the box.
Check that they line up#
requirement REQ-MOUNT "The board screws onto the tray" {
text "The tray's standoffs shall be under the board's mounting holes, within 0.2 mm."
fits board, tray
}
system Unit "The unit" {
part tray: Tray
part board: Controller { at tray.board }
}
fits board, tray passes when every standoff the tray gives the board is
under one of the board's holes, within 0.2 mm. Write another tolerance after
<=: fits board, tray <= 0.5mm. The distance is measured across the board,
where the parts were placed, so a turned anchor is taken into account. A hole
with no standoff is allowed; a standoff with no hole is not.
Controller a board, from hw/controller.kicad_pcb
outline 50 × 40 mm, 1.6 mm thick
mounting holes H1 (3.5, 3.5) ⌀3.2 H2 (46.5, 3.5) ⌀3.2 H3 (3.5, 36.5) ⌀3.2 H4 (46.5, 36.5) ⌀3.2
✓ REQ-MOUNT fits board, tray 4 standoff(s) on 4 of 4 hole(s), 0 mm off at most <= 0.2 mm
Like a clearance, a fits in a system is a check of archec cad, and a
fits in a requirement is also evidence for it. The evidence depends on the
two shapes and on the board's file: move a hole in KiCad and the requirement
is out of date. When a standoff is off, archec why-not names it:
REQ-MOUNT The board screws onto the tray — fits board, tray: not kept
1 of the 4 standoff(s) tray gives board is not under a mounting hole (hw/controller.kicad_pcb),
in the board's frame: the standoff at (3.5, 3.5) is 1.5 mm from the nearest hole H1 at (5, 3.5)
— the tolerance is 0.2 mm
KiCad's own checks#
When a component names a pcb, archec cad also runs KiCad's rule checks:
| Check | Command | On |
|---|---|---|
| ERC | kicad-cli sch erc --exit-code-violations |
The .kicad_sch with the same name as the board, if there is one. |
| DRC | kicad-cli pcb drc --exit-code-violations |
The .kicad_pcb. |
KiCad also warns about its own set-up: a footprint or symbol library missing from this computer's library tables, or different from that library's copy. Those warnings depend on the computer, not the design, so archec does not count them.
Each result is recorded as evidence for the requirements the component satisfies:
✓ REQ-RULES erc Controller KiCad's electrical rules: no violation (controller.kicad_sch)
✗ REQ-RULES drc Controller KiCad's design rules: 2 violation(s) (controller.kicad_pcb)
archec does not ship KiCad and never downloads it. It looks for kicad-cli
in KICAD_CLI, then on the PATH, then where KiCad's installer puts it
(KiCad 7 or later). On macOS that is /Applications/KiCad or
~/Applications/KiCad; the second needs no administrator password (copy
KiCad.app there from KiCad's disk image). Without it the two checks are
skipped, and nothing is recorded:
- REQ-RULES drc Controller skipped: kicad-cli is not installed (KiCad 7 or later; or set KICAD_CLI)
- 2 check(s) skipped: kicad-cli is not installed (KiCad 7 or later; or set KICAD_CLI)
A skipped check does not fail archec cad, and archec status does not
count the requirement as proved by it.
What is bought can be ordered#
requirement REQ-BUY "What is bought can be ordered" {
text "Every bought part of the unit shall have a part number."
sourced Unit
}
sourced Unit passes when every bought part of the system has a part number
(product { vendor "…"; part-number "…" } on its component). A part is
bought unless:
- its component is made here: it has a
cador apcb; or - it comes with a bought part: what is on a board, or inside a part that has a part number.
Without a requirement, archec check still gives a hint at each bought part
with no part number, in a system whose parts have shapes (cad-sourcing).
archec parts and the BOM read the same part numbers.
In the greenhouse#
examples/greenhouse/mechanical.arche uses what it can show honestly:
- The store's NUCLEO-F446RE says its outline, 70 × 82.5 mm, and archec
checks
cad/nucleo.pyagainst it. - It also says the board's three mounting holes, ⌀3.25 mm, read from ST's
drill file for the MB1136 board and checked against the drawing in UM1724.
The tray's posts for the board are under them, and
fits board, boxchecks that:✓ Assembly fits board, box 3 standoff(s) on 3 of 3 hole(s). The relay's and the sensor's posts are supports, not screw positions. archec checkgives the sourcing hint for the relay, a generic module with no part number.- KiCad is not involved: the greenhouse has no board of its own.
The command#
archec cad [main.arche] [--json] [--force] [--only <Name>]… [--no-run] [--python <exe>] [--html <page.html>] [--no-record]
| Option | Effect |
|---|---|
--json |
The measures, the placements and the checks as data. |
--force |
Build every shape again. |
--only <Name> |
Build only this shape (Enclosure, Assembly.board). |
--no-run |
Check against what is measured already. Needs no engine. |
--python <exe> |
The Python to run the shapes on. |
--html <page> |
Write the 3D page. |
--no-record |
Record no evidence. |
Exit code: 0 when every shape is built and every check is kept, 1 when a file failed or a check is not kept, 2 when the model has an error or the engine is missing.
Where the engine comes from#
The platform builds of the extension are made by
node tools/cad/package.mjs <target> (see tools/cad/). The script fetches
a portable Python and the wheels of build123d and its dependencies for that
platform, and checks each against a pinned SHA-256
(tools/cad/targets.json, tools/cad/wheels-<target>.txt). None of these
files are in git. node tools/cad/lock.mjs writes the wheel lists again for
a new build123d.
archec looks for the engine in this order:
--python, thenARCHE_CAD_PYTHON.- The engine carried by the extension (its
cadfolder, orARCHE_CAD_WHEELHOUSE). On first use, archec makes an environment from it in~/.arche/cad(ARCHE_CAD_HOMEto change the place) withpip install --no-index. - An environment made that way earlier.
- A
.venvbeside the model, thenpython3, if it has build123d.
If none is found, archec says what is missing and exits with 2.
Limits: what it does not do yet#
- A measure (
Enclosure.mass) can be used in a limit and in the mass budget, not yet in a constant or an expression. - The material is the shape's: a part cannot change only the material of its definition's shape.
- A shape is one solid. A part made of several bodies needs one file per body.
- MuJoCo makes contact with the convex hull of a part's mesh, not with the mesh itself.
- A part placed by
atis a body where it was placed only when it is a part of the system itself, not a part inside another part. - The outline of a board is the bounds of its
Edge.Cuts, not its exact contour. A board's shape is still drawn in its own.pyfile: archec does not make it from the KiCad file. - A mounting hole is found by its footprint's name (
MountingHole…) or reference (H1,MH1). Other drilled holes are not counted. fitscompares positions across the board. It does not check the height of the standoffs or the diameter of the screws.- The store's other boards (NUCLEO-G474RE, NUCLEO-H743ZI2) say no mounting holes yet: they are not MB1136 boards, so the NUCLEO-F446RE's holes are not copied to them.
- The playground builds and checks the shapes, but records no evidence and gives no STEP or STL file: see In the playground.