# Drawings A drawing is a document of its own that draws a part or an assembly (its source, at the latest revision) on sheets: views, dimensions and annotations whose values come from the model. When the part changes, the drawing follows. On a drawing use `inspect_drawing` and `get_view`; the part tools answer only on parts. Read [Working with plans](working.md) first. ## Standard, sheets and template - A drawing follows ISO (A4 to A0 sheets, first angle projection) or ASME (ANSI A to E sheets, third angle), and shows millimeters or inches (`inspect_drawing`: `standard`, `units`). Change them with `drawing.update`, and the sheets' size and projection with `sheet.update`, in one plan. Use ASME and inches when the user works in inches. Dimension values in `inspect_drawing` stay in mm whatever the drawing shows. - Sheets are drawn on a template: the standard's own (ISO 7200 or ASME Y14.1, with zones) unless `drawing.update` names a template document of the project (`{"kind":"document","documentId":...}`); `list_projects` lists each project's templates and `create_drawing` takes a `templateId`. - Title block fields are typed per sheet with `sheet.update` `titleBlock`, by the template's field keys (title, number, material, checker, approver, ...); empty ones come from the part and the account. Revisions go in `drawing.update` `revisions` (`[{rev, description, date, by}]`, the whole list); the revision table lists them and the latest goes in the title block. - `sheet.update` also sets `scale` (`"1:2"`), `size`, `orientation`, `projection`, `generalTolerance` (`"ISO 2768-m"`) and `generalSurface`. ## Views - Orientations: `front` (looks along +Y, Z up), `back`, `top` (looks down, Y up), `bottom`, `right`, `left`, `iso`. - A view's `position` is where the part's origin lands on the sheet, in mm from the lower left. Projected views name their `parent` and stay aligned with it; the sheet's projection method decides on which side they go. - The `views.standard` helper places the standard views of the source, laid out by the projection method and scaled to fit: ```json plan:plate-drawing { "summary": "Front, top, right and iso views of the plate", "steps": [ { "label": "Views", "commands": [ { "type": "views.standard", "views": ["front", "top", "right", "iso"] } ] } ] } ``` - `view.create`, `view.update` (orientation, scale, hidden lines, tangent edges, label, breaks), `view.move` and `view.delete` change single views. - **Sections** show what is inside: `views.section` cuts a front, top or side view along a line across the part (straight, half, or in steps for an offset section), hatches the cut faces and places the section beside its parent with its letter (A-A). Use one where hidden lines would cross, or the inside matters (bores, pockets, tapped holes), and dimension inside features on the section, on the cut edges `get_view` lists for it. - **Details** (`views.detail`) show small features larger; **auxiliary views** (`views.auxiliary`) show an inclined face at its true size; **breaks** (`view.update` `breaks`) shorten a long view. Dimension on them like on any view; values stay true. ## Dimensions and annotations Annotations reference edges by the topological names `get_view` returns for that view; their values come from the model, never from you. ```json { "type": "annotation.create", "id": "$width", "annotation": { "kind": "dimension", "view": "", "type": "horizontal", "refs": [ { "kind": "edge", "name": "", "at": "start" }, { "kind": "edge", "name": "", "at": "start" } ], "offset": [0, -12] } } ``` - Dimension types: `horizontal`, `vertical`, `aligned` (one line edge gives its length, two edges the distance between them), `radius` and `diameter` (a circle seen face on), `angular`, `chamfer`, `ordinate` (from a datum along an axis), `arcLength`. `offset` places the dimension line in sheet mm from the middle of its edges; 10 to 15 mm away from the view reads well. `"text":"4x "` adds words around the value. Dimensions with the same `set` move together (baseline or chain). - **Hole callouts**: `{"kind":"holeCallout","view":,"ref":,"position":[x,y]}` writes the hole as the part makes it (count, drill, depth, counterbore, countersink, thread: `4x M4 - 6H ↧ 8`). A through hole has no depth: ISO writes only its diameter (`2x Ø5.5`), ASME adds THRU. Use one on every hole and tapped hole instead of a plain diameter. - **Tolerances** on a size: `{"type":"symmetric","value":0.1}`, `{"type":"deviation","upper":0.1,"lower":-0.05}`, `{"type":"limits",...}`, `{"type":"fit","hole":"H7"}` or `"shaft":"g6"` (ISO 286, deviations from the tables), `{"type":"basic"}` for GD&T, `{"type":"reference"}`. - **GD&T**: datums (`{"kind":"datum","letter":"A",...}` on an edge seen edge on, or on a dimension) and feature control frames (`{"kind":"featureControlFrame","characteristic":"perpendicularity","zone":{"value":0.02},"datums":[{"letter":"A"}],...}`). Form tolerances take no datum; orientation and location need one; M and L only on a dimension. Broken rules show as `GDT_INVALID`. - **Surface texture**: `{"kind":"surfaceSymbol","ref":,"process":"removal","parameters":["Ra 1.6"],...}`, and `generalSurface` on the sheet for every other surface. - Center marks, centerlines and notes: `centerMark`, `centerline`, `note`. - A dimension whose edge is gone is dangling and shows no value: reattach it with `annotation.update` (new `refs`), or delete it. ## Dimensioning a part completely Unless the user asks for less, dimension a drawing so someone can make the part from it without measuring the model: 1. The overall size in all three directions. 2. Every hole by a hole callout, and its position from the part's edges or from a datum. 3. Angles by angular dimensions, chamfers by chamfer dimensions, fillet radii. 4. Every boss, slot and step; patterns with count and spacing (`4x `). 5. A fit on every size that mates with another part (a bore for a shaft or a bearing H7, a shaft g6, or as the user says), and the general tolerances in the title block (ISO 2768-m unless asked). 6. A datum on the face or feature a fit is measured from, and a frame (perpendicularity or position) tying the fit to it; surface texture on fitted faces and a general symbol for the rest. 7. A section view where hidden lines would cross inside the part. Each size once, in the view that shows its shape best. Before you answer, check `inspect_drawing`: - `missingSizes`, `missingCallouts`, `unfittedBores`, `crowded` and `gdtProblems` must be empty. `missingSizes` lists overall and circle sizes no dimension shows yet; it cannot see positions, so check those yourself. `crowded` lists texts a line or another text runs through: move those annotations clear of the views and of each other. - No dimension may be dangling: reattach or delete one you leave behind, and say so. ## Drawings of assemblies Refs also name the component (`{"kind":"edge","name":...,"component":...}`). A parts list is `{"kind":"partsList","sheet":,"source":}` (above the title block, item 1 at the bottom), and balloons `{"kind":"balloon","view":,"component":,"position":[x,y]}` point at components. ## Drawing commands `document.rename`, `drawing.update`, `sheet.update`, `view.create`, `view.update`, `view.move`, `view.delete`, `annotation.create`, `annotation.update`, `annotation.delete`, and the helpers `views.standard`, `views.section`, `views.detail`, `views.auxiliary`. Read them with `describe_commands`.