llms.txt
Compare with other sites' llms.txt files →# RapidCAM
> RapidCAM (https://rapidcam.app) is a parametric 2D CAD +
> CAM application for CNC mills, rotary (4th-axis) machines, and lasers. Its
> project format, `.rcam`, is plain JSON with a published JSON Schema, and is
> explicitly designed so that automated tools — including LLMs — can author
> valid design files.
**Can you only fetch a single URL?** Some AI tools cannot follow links found
in a fetched page. Fetch [the single-file bundle](https://rcamhub.com/llms-full.txt)
instead — this index plus the full format guide, the JSON Schema, and the AI
integration guide, inlined as one plain-text document.
## File format (.rcam)
- [Format guide](https://rcamhub.com/docs/rcam-format-v3.md): the human- and
AI-readable authoring guide — point-key vocabulary, constraint semantics,
CAM operations, and gotchas the schema can't express
- [JSON Schema, draft 2020-12](https://rcamhub.com/schema/rcam-v3.schema.json):
the machine-readable contract (this URL is also the schema's `$id`)
- [Examples index](https://rcamhub.com/examples/index.json): bundled golden
example projects, each validated against the schema on every commit; fetch
any listed file at `https://rcamhub.com/examples/<name>`
- [AI integration guide](https://rcamhub.com/docs/ai-integration.md): every
way an AI can work with RapidCAM — the in-app assistant loop, this index,
the headless CLI, and the MCP server — plus authoring tips
- [Version control guide](https://rcamhub.com/docs/version-control.md): keeping
`.rcam` files in git — why saving an unchanged design is byte-identical, and
the merge driver that reconciles two edits by shape instead of by line
([rcam-merge.mjs](https://rcamhub.com/rcam-merge.mjs), one
dependency-free file run by `node`). Relevant when generating files that will
be merged: mint ids the way the format guide describes, not with a counter.
## Parametric features (generators)
- `features[]` in `.rcam`: geometry produced by a built-in generator (box,
box-joint, spur gear, ...) that stays re-editable — `{id, generatorId,
params, paramExprs?, groupId, offset}`.
- `paramExprs` (optional) holds an expression per param, evaluated against
document `variables` and the built-in keywords (`stock`, `stock_width`,
`origin_x`, `pi`, `counter`, …; a user variable of the same name overrides a
built-in); `params` holds the
last resolved values as cache/fallback for params with no expression, or
whose expression fails to evaluate.
- Features regenerate automatically when a variable they reference changes
(and are self-healed on file open if `params` doesn't match what the
expressions currently resolve to).
- Entity ids stay stable across a regeneration, so CAM operations,
constraints, and dimensions that reference generated geometry survive a
parameter edit.
- `keyIds` (optional) maps generator-assigned stable keys (e.g. "front-wall")
to entity ids; keyed entities keep their ids by key rather than by emit
position, so references survive output reordering and partial deletes.
## Groups & blocks (including nesting)
- `groups[]` in `.rcam`: `{id, name, entityIds}`. Adding `"rigid": true` plus
`origin` and `angle` makes it a **block** — one rigid body with 3 degrees of
freedom, whose members keep ordinary world coordinates.
- **An entity id may appear in at most one group's `entityIds`.** This is the
rule most often broken by generated files: a block inside a block is NOT
written by listing the inner block's entities in the outer block as well.
- **Nest with `parentGroupId`**, which names the containing block. It is a
parent pointer, so a block has one parent at most, and following it must
terminate — a group may not be its own ancestor.
- A nested block is frozen relative to its parent: the whole tree solves as one
rigid body, and only the outermost block carries the 3 transform variables.
- `blockDefinitions[]` (`{id, name, entities, children?}`) are shared
definitions; a group with a `definitionId` is a linked instance of one.
`children[]` are `{definitionId, origin, angle, scale?}` references to other
definitions — a definition contains block REFERENCES, never a second copy of
the child's geometry — and the reference graph must be acyclic.
- `group.scale` is ABSOLUTE (the instance relative to its definition);
`children[].scale` is RELATIVE to the parent definition.
- None of these rules is expressible in JSON Schema, so a file that breaks them
still validates. The importer reports them as `blocks` errors, and the app
repairs them on open rather than refusing the file.
## Parametric CAM operations
- `operations[]` may carry `paramExprs` too — an expression per **numeric op
field**, keyed by field name: `{"depth": "-stock", "feedrate": "baseFeed*1.2"}`.
Every numeric field takes one (pinned by `test/everyNumericOpFieldBinds.test.ts`).
A key that is not a numeric op field is **ignored silently** rather than
rejected, so a typo costs you the binding without costing you the file.
Evaluated against `variables` and the built-in keywords before every solve, then clamped to
the field's valid range.
- Always also emit the plain numeric field (`depth`, `feedrate`, ...): it is the
last resolved value and the fallback when a field has no expression or its
expression fails. A file never needs an expression evaluated to load.
- Bare numbers in an op expression are **millimetres** regardless of
`displayUnit`. Note the exception elsewhere: a VARIABLE whose expression is a
lone length (`"0.5"`, no arithmetic) is read in the document's display unit.
Operation expressions never are.
- Nested fields take either key spelling: `"tabCount"`/`"tabs.count"`,
`"leadInLen"`/`"leadIn.length"`, `"perforateGapWidth"`/`"perforate.gapWidth"`.
Ignored while `tabs`/`leadIn`/`leadOut`/`perforate` is absent.
- `"depth": "-stock"` is the common case — a profile that always cuts through
whatever the stock currently is.
## Laser jobs from layers
- A **layer** may carry a `laser` recipe — `{kind?, feedrate, laserPower,
laserPasses, kerfWidth?, side?, airAssist?}` — so a design describes how each
colour is cut: cut on black, score on red, engrave on blue.
- `feedrate`/`laserPower`/`laserPasses` are **live**: any operation whose
`entityIds` all sit on that layer takes them at toolpath time, so re-tuning a
layer re-tunes everything on it. An operation spanning several layers keeps
its own settings, and `"laserOverride": true` opts one out entirely.
- `kind` (`"cut"|"score"|"engrave"|"fill"`) is read when operations are BUILT,
not applied live — a cut, an engrave and a fill emit different geometry, so
retyping an existing operation at export would not match its preview. A layer
with a recipe but no `kind` tunes the operations that cut it without being a
job of its own.
- Emitting layers with kinds and NO `operations` is a valid, compact way to
describe a laser job: the user presses **Toolpaths from Layers** and gets one
operation per layer, in layer order, named after the layer.
- Hidden layers (`"visible": false`) and workholding layers (`"fixture": true`)
are never cut when a job is built FROM LAYERS. An operation that names
workholding geometry explicitly still cuts it — pre-flight warns
(`machined-fixture`) rather than dropping the cut silently.
- A clamp's height above the stock top comes from the layer's `fixtureHeight`,
or from the shape's own `fixtureHeight` when clamps of different heights share
a layer. Unset at both levels means full-height: it blocks every pass.
- Kerf direction is automatic unless you set `side`: a contour enclosed by
another on the same layer is treated as a hole and compensated inward while
the outline goes outward, so both finish at the drawn size.
## Authoring tips for LLMs
- All lengths are millimetres. Angles are radians (CCW) everywhere except the
two dimension types listed next, which are in degrees. Neither depends on the
file's `displayUnit`. The world frame is Y-up.
- `angle-x` — a line's direction from +X, signed — has a `value` in **DEGREES**.
- `arc-sweep` — an arc's included angle, 0–360 — has a `value` in **DEGREES**.
- Those two back a property field, and a dimension's `expr` lands in `value`
with no unit applied, so they store the unit you type. Emitting
`{"type": "angle-x", "value": 0.785}` meaning 45° gives a line at 0.785° —
plausible-looking and wrong. Write `45`.
- You do not need exact coordinates: emit rough positions plus constraints and
dimensions, and RapidCAM's parametric solver snaps the geometry exact.
- A **rounded, coved or chamfered rectangle is still a `rectangle`** — give it
`cornerRadii` (one radius per corner, `bl` `br` `tr` `tl`) and a treatment per
corner (`"round"` | `"inverted"` | `"chamfer"`): `cornerType` for one treatment
on every corner, or `cornerTypes` (four, same order) to mix a chamfer with a
fillet on one rectangle. Do not tessellate one into a
polyline: as a rectangle it keeps its `W`/`H` fields, its corner point keys,
and an editable radius, and the arcs reach the toolpath as true arcs. The
radius is also the scalar DOF `cr`, so a `bindings[]` entry can drive it from
a formula (`{"scalarKey": "cr", "expr": "stock * 2"}`), all four corners at once.
- A **rounded, coved or chamfered `polyline` is still a `polyline`** — the same
two fields, but `cornerRadii` is an object keyed by **vertex id**, not an
array: `{"cornerRadii": {"1": 6, "2": 6}, "cornerType": "round"}` shapes the
vertices whose `vertexIds` entries are `"1"` and `"2"`. To mix treatments, use
`cornerTypes` keyed the same way — `{"1": "chamfer", "2": "round"}`. Do not tessellate an
arc into extra vertices — as corner data it stays editable, reaches the
toolpath as a true arc, and leaves every `v<id>` constraint alone. An open
polyline's first and last vertices cannot be shaped. **The number means the
fillet RADIUS for `"round"`/`"inverted"` but the bevel SETBACK for
`"chamfer"`**; those are the same figure only at a 90° corner, which is why a
`rectangle` gets away with one meaning.
- An embedded image carrying **`zRangeMM`** is a HEIGHT MAP from an imported STL,
not a picture: byte 255 is the model's top surface (no cut), byte 0 its base
(full depth), and `zRangeMM` is the carve depth in mm at true scale. Preserve
the field when editing such a file — dropping it turns the model back into a
photograph, and the white-threshold default alone then flattens the top 4% of
its height range. For the same reason, do not set `reliefGamma` on a relief
operation that reads one; a tone curve on a height map is a geometry error.
A model with near-vertical walls also takes `"reliefSteepPass": true` on
the finish op: anything steeper than 45° is then cut by constant-Z contours
rather than by the raster, which cannot hold a cusp on a wall. It has no
settings of its own — the contour spacing is derived from the stepover.
- A relief rasters the whole image by default. To stop it air-cutting over the
background, set `reliefWhiteThreshold` (0..1, default 0.96) so dots at/above
that greyscale are background and skipped — and/or `reliefBoundaryIds` to a
list of closed-loop entity ids (with `reliefBoundaryOffset` mm to expand it)
so only the inside of those loops is carved. Both apply to the rough and the
finish pass; the threshold is ignored on an STL heightfield.
- Declare `"version": 3` and validate your output against the schema before
presenting it to a user.
- Opening a file in RapidCAM reports schema, solver, and CAM lint problems;
iterate on that feedback rather than aiming for a perfect first attempt.
- Agents on the user's machine with a RapidCAM checkout can run those same
checks headlessly (CLI: `npm run cli -- validate|post|render|open|decode`)
or as MCP tools (`npm run mcp`), including `open` — which delivers a
validated design straight into the user's browser via a share-link URL —
and `decode`, which turns a copied share link back into .rcam JSON. See
the AI integration guide above.