The MechPilot file format

A drawing is one JSON text file, name.mechpilot.json. It is yours: open, documented, versioned, and written in a stable order so it diffs well in Git (product rule 3). Nothing is rounded on save or load: numbers are IEEE doubles written by JSON.stringify, which round-trips every value exactly (product rule 1).

Reference implementation: shared/doc/types.ts (shapes), shared/doc/file.ts (serialize, parse, validate, migrations). Tests: tests/file-format.test.ts.

Top level (format 1)

{
  "format": "mechpilot",
  "version": 1,
  "unit": "mm",
  "name": "Mounting bracket",
  "description": "optional",
  "standard": "iso",
  "projection": "first",
  "layerOrder": ["0", "hidden", "centre"],
  "activeLayer": "0",
  "layers": { "0": { "id": "0", "name": "0", "color": "auto", "lineType": "01.2", "lineWidth": 0.5, "visible": true, "locked": false } },
  "entityOrder": ["e1", "e2"],
  "entities": { "e1": { "id": "e1", "type": "line", "layer": "0", "a": { "x": 0, "y": 0 }, "b": { "x": 120, "y": 0 } } }
}

Ids are short strings, unique within the file. Keys inside a layer or an entity are written with id, type and layer first and the rest alphabetically.

Layers

Entities (format 2)

Angles are radians, counter-clockwise, y up.

Format 1 (M0) had line, circle and arc only; a format-1 file is upgraded to format 2 unchanged.

Annotations (format 3)

Annotations are drawn from the document's dimStyle (paper mm: textHeight, arrowSize, extensionOvershoot, extensionGap, textGap, decimals, annotationScale, arrowhead). The measured value is computed from the geometry when the drawing is shown, never stored, so a dimension can never disagree with what it measures.

Sheets (format 3)

sheetOrder / sheets: each sheet has name, size (A0 to A4), orientation, titleBlock (ISO 7200 field id → text) and views: windows onto the model placed on the paper, each with scale (ratio: 0.5 for 1:2), center (model point at the centre of the viewport), position, width, height (paper mm) and label (draw "SCALE 1:2" under it). A format-2 file gets the default dimension style and no sheets.

Sketch constraints (format 4)

constraintOrder / constraints: each constraint has an id and a kind, and refers to entities by id and to their points by a PointRef { "entity": "e1", "point": "a" } (a/b of a line, center of a circle or arc, start/end of an arc, or a vertex index of a polyline). Values are mm, angles radians.

A dimension with driving set (a number: mm, or degrees for angular) also constrains the geometry it measures. The solver (planegcs in a worker) moves the entities; the solved geometry is what the file stores, so a file opens exactly as it was saved even without solving. Deleting an entity deletes the constraints that refer to it (undo brings both back).

Parts (format 5)

partOrder / parts: a part has name, an optional material (id from library/materials) and features, an ordered list built one after the other by OpenCascade (through replicad) in a worker. Each feature has id, name, kind and optionally suppressed.

Edge selectors: { kind: "all" }, { kind: "parallelTo", axis }, { kind: "inPlane", plane, offset }, { kind: "ofLength", length }, { kind: "inBox", min, max }. Face selectors: { kind: "normal", direction: "Z+" } or { kind: "inPlane", plane, offset }. The built solid is never stored: a file rebuilds from its features, so it stays small and diffable; meshes and mass properties are computed when the part is shown.

Each addition bumps version and ships a migration.

Migrations

shared/doc/file.ts keeps one function per version step. Opening a file of version n runs the steps n → n+1 → … → current, then validates. A file that fails validation is refused with the field that is wrong, never silently repaired.

Source of this page on GitHub