brekkylab/ailoy/shared

CAD

A model is a Python script that builds solids with CadQuery, a parametric CAD library on the OpenCascade kernel. render.py runs the script, checks what it built, exports it and draws it, so that you can look at what you made and fix it before you hand it over.

The loop

1. Write the model as model.py in a folder under /artifacts named for what it is, such as

/artifacts/gear-bearing/model.py. The script is part of what you deliver: keep the dimensions as named parameters at its top.

1. Run it from this directory:

``sh python3 render.py /artifacts/gear-bearing/model.py --out /artifacts/gear-bearing ``

1. Read the report it prints, then look at views.png with your read tool. Say to yourself

what should be there and check that it is: every feature, the right way round, the right size.

1. Fix and run again until the report is clean and the pictures show what was asked for.

Most models need a few rounds. --no-export skips the files while you iterate.

Do not describe a model you have not looked at. The report catches what is invalid or overlapping; only the pictures show that a hole is on the wrong face.

The script

It runs as CQ-editor runs one: cq is already imported, and each part is handed over with show_object.

width, depth, height, wall = 60.0, 40.0, 25.0, 2.0
box = cq.Workplane("XY").box(width, depth, height).faces(">Z").shell(-wall)
lid = cq.Workplane("XY").box(width, depth, wall).translate((0, 0, height / 2 + wall / 2 + 0.4))
show_object(box, "box", {"color": "#4c78a8"})
show_object(lid, "lid", {"color": "#f58518"})

• show_object(obj, name, options) adds a part. obj is a Workplane, a Shape, an

cq.Assembly or a list of them. options["color"] is a CSS color name, #rrggbb, a tuple of 0–1 or 0–255 values, or a cq.Color. Parts that name no color get one of a palette.

• A script that calls show_object for nothing is taken for its result variable.
• Units are millimetres and Z is up. For a print, Z is off the bed: put the face it prints on

at z = 0.

• Parts that are separate things — the planets of a gear set, a lid and its box — are

separate show_object calls. The report checks each pair of them for overlap, and each is its own STL.

render.py

python3 render.py MODEL.py --out DIR [--no-export] [--size PX]
                  [--explode F] [--section AXIS[=V]] [--turntable [--frames N]]

It writes into DIR:

• views.png — iso, front (from −Y), right (from +X) and top on one sheet, with the model's

size in each; and iso.png, front.png, right.png, top.png alone.

• model.step — every part, named and colored, as one STEP assembly, for other CAD tools.
• model.glb — the same as colored meshes, for a viewer or a web page.
• parts/NAME.stl — each part on its own, for a slicer.
• exploded.png with --explode F — each part moved away from the middle of the model, F

times as far. Parts on the model's centre do not move, so for a stack of concentric parts make an exploded copy in a script of its own, with translate.

• section.png with --section z=5 — every part cut by the plane z = 5 and seen from the

side that was taken away, the cut faces lighter. Without =V it cuts through the middle. This is how to see inside: walls, bores, clearances between parts.

• turntable.gif with --turntable — the model turning once, 36 frames by default. The

report is the same without it, so make it last, for the user.

The report on stdout is one JSON object:

• parts — for each: valid (OpenCascade's own check), solids (how many), bbox (min,

max, size), volume in mm³, area in mm², color, triangles and watertight (whether its mesh is closed).

• bbox — of the whole model.
• interferences — every pair of parts whose solids share more than 0.001 mm³, with how

much. Parts that only touch share none. --interference V changes the threshold.

• files, and seconds for each step.

A script that fails comes back as {"error": ..., "traceback": ...} with exit code 1.

What the report should say before you hand a model over:

• every part valid, with the number of solids it should have: one, for a part to print;
• every part watertight, or a slicer may not take it;
• interferences empty, unless two parts are meant to be one — then union them;
• bbox sizes that match what was asked for.

CadQuery

A Workplane is a chain: a plane, 2D shapes on it, then operations that turn them into solids and change them.

• Sketching. rect, circle, polygon(n, d), slot2D, ellipse, and

polyline(points).close() or spline(points) for outlines of your own. pushPoints, rarray(xs, ys, nx, ny) and polarArray(r, 0, 360, n) place copies of what follows.

• Solids. extrude(h) (both=True for both ways), revolve(deg, (x0, y0, 0), (x1, y1, 0)),

twistExtrude(h, deg) for helical and herringbone teeth, loft() between stacked sketches, sweep(path) along a wire, with cq.Wire.makeHelix(pitch, height, r) for springs and threads. box, cylinder, sphere directly.

• Selecting. faces(">Z") is the top face, faces("<Z") the bottom, edges("|Z") the

vertical edges, faces(">Z").workplane() a new plane on the top face to sketch on.

• Features. hole(d), cboreHole, cskHole, shell(-t) to hollow (the selected faces

are left open), fillet(r) and chamfer(d) on selected edges.

• Booleans. union, cut, intersect. Moving: translate((x, y, z)),

rotate((0, 0, 0), (0, 0, 1), deg), mirror("XY", (0, 0, z)).

Where it goes wrong:

• polyline with two points the same in a row fails with BRep_API: command not done. So

does a profile that crosses itself. Drop repeated points before you close it.

• A fillet too big for the edges it is on fails with StdFail_NotDone, or makes an invalid

solid. Fillet last, select edges narrowly, and try a smaller radius.

• A boolean between faces that lie exactly on each other can come back invalid. Let the

cutter stick out past the face it cuts, by 0.01 mm or more.

• Hundreds of small unions or cuts in a loop are slow. Draw the repeated feature in 2D

and extrude it once, or place copies with pushPoints or polarArray.

• twistExtrude twists about the workplane's origin: centre the profile on it.

Gears

For spur gears with module m, pressure angle α (20°) and z teeth: the pitch radius is m·z/2, the base radius m·z/2·cos α, the tip m further out, the root 1.25·m further in. A tooth's flank is the involute of the base circle, at angle inv(φ) = tan φ − φ for the radius r_b / cos φ. Two external gears mesh at centre distance m·(z1 + z2)/2. A ring gear is a disc with an external gear of its tooth count cut out of it, and then a circle of radius m·z/2 − m cut out too: without that the ring's teeth are as long as the gear's gaps were deep, and run into the roots of the planets.

A planetary set has z_ring = z_sun + 2·z_planet, and n planets spaced evenly only fit when (z_sun + z_ring) / n is a whole number. Each planet then has to be turned so that its teeth fall into the sun's gaps and the ring's: check it with the report's interferences and a --section through the teeth, not by eye.

Parts that turn against each other need a clearance. For a print that comes off the bed assembled, 0.3–0.5 mm between the flanks — make each tooth thinner at the pitch circle by half of it, so two teeth in mesh leave all of it — and the same between any faces that slide. Teeth in mesh with no clearance show as a small overlap in interferences, a fraction of a mm³ per pair; a tooth in the wrong place shows as hundreds.

Printing

• Put the largest flat face on z = 0, and keep overhangs under 45° from vertical, or they

need supports.

• Walls 1.2 mm or thicker, and holes that take a screw 0.2–0.3 mm bigger than the screw.
• One solid per part: a part that is two solids is two parts, or a part the union missed.

Delivering

In /artifacts/NAME leave the script, model.step, the STLs, model.glb and the pictures that show it best. In your reply, say what the model is, its main dimensions, what the report said, and which files are there.