Openscad Design

OpenSCAD design loop

One rule sits above the rest: numbers decide, pictures confirm. A render is a low-bandwidth summary of geometry. Vision models routinely rate a broken model as fine, because a missing internal wall, a 0.02 mm gap, or a non-manifold seam looks identical to a correct part at 800x600. Never conclude "that looks right" from an image. Conclude it from measure and validate, then use the image to catch the class of error numbers miss: wrong orientation, a feature on the wrong face, a part that is inside-out.

The loop

1. State assumptions before writing code

Say these out loud in one or two lines, because they are invisible in the source and wrong in half of all first attempts:

• Units: OpenSCAD is unitless; everything here is millimetres.
• Orientation: which axis is up, and which face sits on the print bed.
• Datum: where the origin is. Corner-at-origin and centred-on-origin are both fine, but say which, and keep it consistent across parts of an assembly.
• Print process: FDM layer height and nozzle width if the user has not said, because they set minimum wall and minimum feature size.

2. Declare key dimensions as variables

Every number that the user might change, or that appears more than once, becomes a named variable at the top of the file. Derive the rest with expressions rather than retyping arithmetic. This is what makes step 6 cheap: an iteration becomes one variable edit, not a search-and-replace through solid geometry.

wall      = 2.4;   // 3 perimeters at 0.8 mm
inner_x   = 60;
inner_y   = 40;
inner_z   = 25;
clearance = 0.2;   // from reference(topic="fits")
eps       = 0.01;  // coplanar-face overlap

3. validate(mode="syntax") first

Before any render or export. OpenSCAD's exit code is not a success signal: a failed assert(), an unknown module, a missing include, and an unclosed polyhedron all exit 0 while printing to stderr. validate parses that stream. Read errors, warnings, and hints on the response. Fix everything in errors before moving on and read every warning, since "Ignoring unknown module" means a whole feature is silently absent from the geometry you are about to measure.

4. measure before you trust any picture

measure(mode="model") exports the mesh and returns exact numbers: bounding box, dimensions, volume, surface area, component count, watertightness. Compare those against the dimensions you intended. A bounding box 0.4 mm larger than expected is a clearance bug you would never see in a render.

measure also accepts an existing STL through mesh=, so you can measure a file the user already has without re-rendering it.

Modes: model for the whole thing, parts for per-solid numbers and the solid count, section for a cut plane, mass for volume-times-density estimates. The rest — probe, features, printability, orientation, anchors — are in the tool reference at the end.

5. render(grounded=true), one to three views

Only after the numbers agree. Ask for the smallest number of views that answers the open question, usually one isometric plus one orthographic view of the face in question. More images degrade the model's own counting and comparison, so a four-view contact sheet is worse than one well-chosen view, not better.

Modes: views for standard camera positions, section for a cut, parts for per-part colouring, compare for before/after.

6. Multi-part designs

• One module per part. module lid() { ... }, module body() { ... }, and a separate assembly view that translates them into place. Never one monolithic union.
• Overlap coplanar faces by epsilon. Two solids that exactly touch along a face or an edge produce a non-manifold result that CGAL drops or reports as not 2-manifold. Add eps so the parts genuinely interpenetrate, and subtract eps on through-holes so the cutter pokes out both sides.
• Get clearances from reference(topic="fits"), not from memory. Press fit, slip fit, and free fit differ by tenths of a millimetre and the right number depends on the process. Related topics: fasteners, inserts, bearings, magnets, joints, dfm, materials, conventions, cheatsheet.
• Check the solid count. measure(mode="parts") should report exactly as many components as you designed. Two when you expected one means a part is floating free; one when you expected two means they fused and will print as a single lump.
• Check manifoldness. validate(mode="geometry") returns mesh_health. Look at mesh_health.manifold: true is good, false names the defect in mesh_health.issue, and null means the check was not performed, which is not the same as passing.

6b. Assemblies: name the parts, then ask check

Once a design has more than one part, stop reasoning from pictures and give the server the parts by name. Every part is exported separately (never unioned), so identity survives and every relation is a number in the assembly frame.

check(scad_file="assembly.scad", mode="interference",
      parts=[{"name": "bracket", "code": "bracket();"},
             {"name": "motor", "code": "motor();", "place": "translate(MOTOR_POS)",
              "ghost": true, "mass_g": 34}])

• state is clear, contact, or interference. Flush contact is contact, never interference; a sliding pair (a pinion on a plate) that reports contact is the defect, so declare motion on the moving part and use contact with kind="sliding".
• mode="clearance" gives the exact minimum distance and both closest points; mode="motion" sweeps a part about an axis or along a vector and, for a full turn, adds a certificate that says whether the parts can ever touch.
• mode="alignment" is the only check that sees a 0.6 mm hole misalignment: interference and clearance both read zero there.
• rule: mass in a check file limits total mass, centre-of-mass offset from an axis or point, and inertia about an axis, composed from the exported meshes with each part's mass_g, material or density_g_cm3 (PLA if none, flagged).
• Write coordinates and limits in check files as SCAD expressions of the model's parameters (point: "[BOLT_R, 0, BASE_H]", min_mm: "GAP_MIN"), never as copied numbers: a copied number keeps passing after the parameter changes.
• Every row carries quality.fn. A distance smaller than the tessellation error bound comes back UNRESOLVED; re-run with quality="high" or an integer $fn.
• measure(mode="probe") answers "is there material at this point, and whose", ray casts ("does the scanner see the card"), and line-of-sight polylines.
• measure(mode="features") lists the holes a part cuts (axis, diameter, depth, fit name) straight from the CSG tree, and reference(topic="fits", diameter_mm=3.3) names what a hole is.
• Freeze the rules in a check file (YAML: frames, quality, parts, checks, model) and re-run check(check_file=..., mode="rules") after every edit; openscad-mcp check file.yaml does the same from a Makefile.

Purchased parts. reference(topic="parts") lists the five sourced entries: 28byj-48, nema17, lazy-susan-4in, kw11-3z (snap-action microswitch) and tcrt5000-module. model(action="create", template="part:28byj-48") writes BOSL2 modules with named anchors, a clearance mask for difference(), and a verify[] list of dimensions to confirm on your own motor. The module names come from the entry, not from the id: 28byj-48 gives part_28byj48(), part_28byj48_mask(), part_28byj48_mount_holes_mask() and part_28byj48_info(). Design the pocket from the part's named numbers, then let check prove it: the mask, not a minkowski() grow, is the pocket; hull() of two poses is wrong for an insertion sweep.

Before printing. measure(mode="printability", orientation=[180,0,0]) gives overhang patches with their unsupported reach, the wall-thickness distribution against the nozzle, islands, and a support estimate. mode="orientation" lists candidates but names no winner; you decide by which faces must look good. validate(mode="printability") turns the facts into findings with thresholds.