VEX IQ · 2nd generation
Say where the parts go. IQDraw draws the rest.
A build is a short Python file: a part name and a hole coordinate per line. IQDraw draws the isometric step-by-step diagrams and wraps them in a printable booklet — the shape of a real VEX build guide. Offline, no CAD, no web service.
Spec and drawing, side by side
The lines that drew it
The step drawings are
rendered when the site is deployed. Run
./docs/build.sh to see them locally.
Every part has an address
This is the part to get right; everything else follows from it. One grid unit is one VEX IQ hole — 12.7 mm. Every structural part is a whole number of pitches, which is the only reason a plain integer grid can describe real builds.
Placed by hole centre
A pin and its hole share an address
A beam_1x8 at (0,0,0) has holes at
(0,0,0) through (7,0,0). A pin at
(3,0,0) goes through that beam's fourth hole. No offset
arithmetic.
0-based
Hole 2 is the third one a student counts
Write step notes in whichever convention you teach, but keep the numbers in the spec 0-based.
+z is up
The camera looks down the diagonal
Fixed on (+1,+1,+1), always looking down at the model,
so the underside of a build is never drawn.
| Part | Thickness | A part at z occupies |
|---|---|---|
| beam | 0.50 | z-0.25 … z+0.25 |
| plate | 0.25 | z-0.125 … z+0.125 |
| gear | 0.50 | z-0.25 … z+0.25 |
pin_1x1 | 1.00, centred | z-0.5 … z+0.5 |
A build is a list of steps
Each step() is one instruction and the parts it adds.
Because the spec is a Python file, "a pin in every hole along this beam"
is one line rather than eight.
The CLI renders the first Build it finds at
module level. That is the whole starting point — iqdraw --new
my-build.py writes something very close to it.
Arrows answer “which hole?”
Use arrow whenever the step is which hole
rather than which part. “A shaft through holes 0, 2 and 6” asks
a student to count along twenty identical holes; three arrows answer it
at a glance.
When one flat list stops working
Absolute coordinates are fine for six steps and stop working around
fifteen. An arm three holes forward carries that offset by hand on every
line, and the far side of a symmetric robot is the near side with every
y negated, typed twice. An assembly is a module
written at its own origin; place() drops it in. Sections
divide the booklet so a reader never has to hold their own place in
thirty undivided steps.
There is no rotation that turns a left side into a right side — a reflection is the only thing that does it. Assemblies nest, and transforms compose all the way down, mirrors included, so mirroring a claw that already contains a mirrored finger gives back a correctly handed pair.
Four things it will not let you get wrong quietly
Every render runs the checks first and prints what it finds.
--strict makes them fatal, --check-only runs
them without drawing.
| Check | Fires when |
|---|---|
duplicate | the same part is placed twice at the same coordinates |
overlap | two beams or plates occupy the same space |
gear mesh | a gear pair is close to meshing but not actually meshing |
stranded | a part touches nothing else in the build |
Every rule only fires on something a correct build cannot do, and that is the whole design. A checker that reports a working build gets switched off, and then it catches nothing. It is why the overlap rule looks at beams and plates only: pins through beams and shafts through gears are meant to interpenetrate.
What the reader gets
One self-contained HTML file — no fonts, scripts or images to fetch, so it opens on a school laptop with no internet and prints straight from the browser.
- The shape of the job on the cover. How many steps, how many parts, and the one line saying how a builder knows they have finished — all before any of the build itself.
- “Step 3 of 6” on every step, in words rather than only as a badge, so progress never has to be held in your head.
- A box to tick per step, which works on screen and survives printing.
- A parts callout on every step, listing only what that step needs, with counts — and everything a section needs listed where the section starts, so parts can be fetched once rather than one at a time.
- A described drawing. Every diagram carries an
aria-labelnaming what the step added, because the picture holds the half of the instruction the words leave out — which hole, which way round. - Dark theme on screen, light theme on paper, with text contrast at WCAG AA or better in both. Distinctions never rest on hue alone: already-built parts are separated from new ones by lightness, which survives a black-and-white printer.
Install it
Python 3.9 or newer. The renderer is standard-library-only; the desktop app adds CustomTkinter.
Command line
iqdraw my-build.py
--svg-dir also writes one SVG per step,
--png rasterises them, --no-hero drops the
cover drawing, and --new writes a starter build without
overwriting anything.
Desktop
IQDraw Studio
Prefer buttons to terminal commands? iqdraw-gui opens a
desktop app with bundled examples, recent projects, step and inventory
review, and HTML/SVG/PNG output through the same tested path as the
CLI.
Build specs are Python programs, so only open files you trust. Studio inspects a spec in a short-lived helper process to keep its state out of the GUI, but that is not a security sandbox.
Four worked builds
Rendered from the specs in the repository every time this site is deployed, so they are whatever the current code actually draws. Open one and print it.
5 steps · 12 parts
Pinned Frame
The base every other build starts from, and the worked example of how the vertical stack lines up.
Open the booklet →
6 steps · 15 parts
Gear Train
A 12T / 36T / 60T train. Turning the crank turns all three gears, with no free play.
Open the booklet →
10 steps · 25 parts
Drive Base
Two side frames, joined by cross beams, brain on top. The worked example of assemblies and sections.
Open the booklet →
19 steps · 44 parts
Grabber Arm
Nineteen steps in eight sections, a shared chassis, and a claw made of two mirrored fingers.
Open the booklet →
The larger booklets are several megabytes — every step redraws the model so far. They are built to open and print on a school laptop, but give the grabber arm a moment on a slow connection.