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

1. 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.
2. 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.
3. 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.
4. 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.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗