# Ply3D modelling guide for AI assistants

Ply3D is a native macOS parametric CAD app (Fusion 360 style) made for 3D printing. You drive it through
MCP tools; the user sees every change live in the app, in the timeline, and can undo it (⌘Z).

## 1. Coordinate system and units
- Millimetres and degrees everywhere. Z points up; the XY plane at Z=0 is the print bed.
- Origin planes for sketches: `XY` (top, normal +Z; sketch x = world X, sketch y = world Y),
  `XZ` (front, normal −Y; sketch x = world X, sketch y = world Z),
  `YZ` (right, normal +X; sketch x = world Y, sketch y = world Z).
- `create_sketch` returns the sketch's world axes (`x_axis`, `y_axis`, `normal`). Always use them when the
  sketch is on a face or an offset plane, so 2D coordinates land where you expect.
- Extrusion distance is measured along the sketch normal. Positive = along the normal (up for XY).

## 2. The core workflow
1. `get_design` — know what exists (bodies, sketches, parameters, errors) before changing anything.
2. `set_parameter` — name the sizes that matter (`width`, `wall`, `hole_d`…). Use them in expressions:
   `"width - 2*wall"`. The user can later change one number and the whole part updates.
3. `create_sketch` with `shapes` — closed shapes become *profiles* (regions you can extrude).
4. `extrude` / `revolve` the right profiles. Operation `auto` picks cut when the tool goes into a body,
   join when it starts on a body face, new body otherwise; be explicit (`join`, `cut`) when it matters.
5. `render_view` — look at the result. Do this after every significant step; it is cheap.
6. `measure` — check size, volume, and that the body is watertight before exporting.

## 3. Sketch shapes (`create_sketch` / `add_sketch_geometry`)
Sizes accept numbers or expression strings. Shapes are fully dimensioned and anchored at their
corner/centre, so changing a parameter grows them predictably.
- `{"type":"rectangle","corner":[x,y],"width":w,"height":h}` or with `"center":[x,y]`.
- `{"type":"circle","center":[x,y],"diameter":d}` (or `"radius"`).
- `{"type":"slot","center":[x,y],"length":L,"width":w,"angle":deg}` — rounded slot; L is centre-to-centre.
- `{"type":"polygon","center":[x,y],"radius":r,"sides":n}` — r is the circumscribed radius.
- `{"type":"polyline","points":[[x,y],...],"closed":true}` — arbitrary outlines (L-shapes, brackets).
- `{"type":"arc","center":[x,y],"radius":r,"start_angle":a0,"end_angle":a1}` — counter-clockwise.
- `{"type":"line","from":[x,y],"to":[x,y]}`. Add `"construction":true` for reference geometry.
- Round or bevel sketch corners with `sketch_fillet` / `sketch_chamfer` (all corners or picked by point).
  This is THE way to round vertical edges: fillet the sketch, then extrude.

## 4. Choosing profiles
A rectangle with a circle inside gives two profiles: the plate (with a hole) and the disc.
- `"profiles": "all"` extrudes every region — a plate with a hole drawn inside would come out solid.
- `"profiles": [[x,y]]` picks the smallest region containing that sketch point. To extrude a plate with
  holes, pass a point inside the plate but outside the holes. Several points select several regions.
- `get_design` lists each sketch's profiles with `area`, `holes` and an `inside_point` you can reuse.

## 5. Building parts
- Holes and pockets: sketch on the face (`create_sketch` with `on_face`) and `extrude` with `cut`
  and a negative distance (into the material), or sketch on the base plane and cut upward.
- Bosses/ribs: sketch on the face and `extrude` with `join`.
- Through holes: cut a distance larger than the thickness; overshoot is harmless.
- Hollow boxes: `shell` with `open_face_normal` [0,0,1] for an open top. Simple shapes only.
- Repeats: `pattern` (rectangular or circular) and `mirror`; prefer them to copy-pasting geometry.
- `primitive` (box, cylinder, sphere, torus, cone) and `text` are quick; sketches are more editable.
- Edit instead of rebuilding: `update_feature` changes values of an existing operation
  (e.g. `{"distance":"height + 2","operation":"cut"}`); field names are those shown by `get_feature`.
- Limitations: there are no 3D edge fillets/chamfers (do them in the sketch before extruding), no lofts or
  sweeps. Do not promise them.

## 6. Designing for 3D printing (FDM, 0.4 mm nozzle unless the user says otherwise)
- Walls ≥ 1.2 mm (3 perimeters); load-bearing walls 2–3 mm. Minimum feature ≈ 0.8 mm.
- Clearances: 0.2 mm for sliding fits, 0.3–0.4 mm for loose fits, 0.1 mm or less for press fits.
  Holes print slightly small: add ~0.2 mm to diameters for screws/pins.
- Put a large flat face on Z=0. Avoid overhangs beyond 45°; bridges up to ~10 mm are fine.
- Bevel (sketch chamfer) bottom edges instead of rounding them; round vertical edges with sketch fillets.
- Embossed/engraved text: ≥ 0.8 mm deep or tall, ≥ 6 mm character height, bold fonts.
- Check `measure` → watertight before export; export 3MF (keeps bodies, units and colours).

## 7. Working well with the user
- Ask for the critical dimensions if they are not given; otherwise state the assumptions you made.
- Name features and bodies meaningfully; use components for parts that print separately.
- After building, summarise: parameters you created, how to tweak the design, and print orientation.
- If a tool returns an error in a feature, fix that feature (update_feature) or undo; do not stack more
  operations on top of a broken one.
- The design may be read-only when the user's license is inactive; say so instead of retrying.