MartyGraphics
Kinematically verified mechanism explainers from a prompt
Gear trains, slider-crank linkages and engine cutaways, as 3D stills, loops and step-by-step videos.
Early preview · macOS 14+ and iOS 17+ · No external packages · Apache-2.0
Examples · How it works · Limits · Quick start · Contribute
What the engine checks: gear meshing (tooth phase, centre distance and tooth interference), gear ratios, joint
motion and layout. In the strict check, the labels and arrows that a view shows pass the anchor and visibility checks;
a force or flow arrow whose part is hidden in a view is dropped from that view and reported as a warning.
What it does not check: whether the words are true. It checks motion and layout, not the truth of text claims.
Image refresh (2026-11-12). The built-in 3D stills and GIF previews now use the default studio look at engine
fb604556. They are MartyGraphics renders, not Blender output or hand-made images. Source documents are unchanged.
MP4 videos keep their original captures. Commands, hashes and exceptions.
A turbofan cutaway, exploded here, from 38 lines of JSON. The solid engine builds every blade row, casing and shaft of this
schematic two-spool turbofan. The HP spool turns three times for each turn of the fan; that ratio is authored as two
input drives, not solved from gears. The example's own check confirms that both spools turn about one axis and that
every rotor keeps at least 4.52 mm from the parts that do not turn with it. The JSON was written by hand in the
documented format, not from a prompt. A teaching model, not a real engine design. The labelled cutaway and the loop
name the spool speeds with the pilots' terms N1 (LP spool) and N2 (HP spool).
Labelled cutaway · Turning loop (GIF) ·
Video (MP4) · Its JSON ·
Run it · Render receipt
Refused, then repaired: a robot-joint gearbox from a prompt
| |
|---|
| Prompt | "Show a two-stage planetary gearbox like in a robot joint." Claude Haiku 5.5, no tools, only the public docs and worked examples. |
| Try 1 | Sun 20 teeth, three planets of 18, ring 56. |
| Refused | constraint.gearMesh.phase on part ring1. Why: 20 + 56 = 76 does not divide by 3, so three equally spaced planets cannot mesh with both the sun and the ring. |
| Try 2 | Sun 24, planets 18, ring 60: (24 + 60) ÷ 3 = 28. Accepted. This is the gear set of the worked planetary example in the docs that the model saw. |
| Solved | 19 parts, 12 gear meshes, output 4/49 of the input speed (12.25:1). Two tries, 121 seconds. |
The engine sent the model only the reason and the part; the "why" line is our note. At main 287bb17,
marty-solid check still refuses try 1 with the same reason and accepts try 2. The engine rendered every frame
from the model's JSON, unedited. We picked this run after grading, from the runs that passed.
Turning loop · Exploded ·
Refused first try ·
Accepted JSON · Run receipt
How it works
- An AI model writes JSON. One assembly document: parts, joints, gear meshes, teaching steps, labels and arrows.
MartyGraphics does not include a model; the host app or a harness calls one.
- The engine checks it and refuses with an exact reason. The JSON is strictly parsed and checked (motion and
layout, not content): closed keys, bounded sizes, no code. A refusal is one stable reason token and the part, for
example
constraint.gearMesh.phase on ring1. Every reason is in the reason catalog.
- The model repairs the JSON. It reads the reason and sends a new document. The test runs on this page allowed at
most three repairs.
- The engine solves the motion and renders. It renders stills, a loop and a story video. A caption takes its
numbers from the solved values: the engine writes "at 16/23 of the input speed" from the gear mesh. In the v2
format, a typed number in a caption is refused unless the caption is marked as not checked.
The format: Solid 3D · Explainer documents · marty-solid tool
Honesty and limits
Early preview. APIs and the wire format may change. The first tagged release is v0.1.0; see the changelog.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
