More › cad

More

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-arm64 or -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, so archec in 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 with ARCHE_CAD_PYTHON=/path/to/python (or --python, or a .venv beside 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 >= 0mm means "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 cad and opens the result beside the editor, with the measures and the checks.
  • Anywhere: archec cad mechanical.arche --html box.html writes 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 .py files are tabs beside main.arche. The + above the editor makes one: type cad/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 cad loads 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 .py file.
  • When a .py file 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 mass or shape differs from the measured one. The measured one is used, and archec check warns 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 shape is 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 mass is 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 shape and mass are used, or a 0.1 m box, and a note says to run archec 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
  }
}
Diagram: A bought board
What archec draws from this code: A bought board

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 cad or a pcb; 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.py against 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, box checks 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 check gives 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:

  1. --python, then ARCHE_CAD_PYTHON.
  2. The engine carried by the extension (its cad folder, or ARCHE_CAD_WHEELHOUSE). On first use, archec makes an environment from it in ~/.arche/cad (ARCHE_CAD_HOME to change the place) with pip install --no-index.
  3. An environment made that way earlier.
  4. A .venv beside the model, then python3, 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 at is 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 .py file: 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.
  • fits compares 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.