draftwright 0.1.9__tar.gz → 0.1.10__tar.gz

{draftwright-0.1.9 → draftwright-0.1.10}/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## v0.1.10 — 2026-06-18
+
+### Added
+
+- **Constraint-based layout engine (ADR 0003).** A new `draftwright.layout`
+  module with a `Placeable` protocol and a `LayoutSolver`: a 1D Cassowary strip
+  solver (`solve_strip`, with per-pair gaps) and a 2D free-rectangle placer
+  (`place_box` / `fit_box`) that positions a box in a free part of the page
+  clear of the views, title block, and existing annotations. Hole-callout and
+  turned-diameter placement now run on the solver. The engine grows per real
+  consumer; a monolithic global 2D solve is deferred (see the ADR).
+- **Hole table + balloons (#93).** `dwg.add_table(rows)` places a generic data
+  table (gear data, BOM, revision block, …) in a free corner via `place_box`;
+  `dwg.add_hole_table(view)` builds a hole chart from the detected holes with a
+  circled balloon tag at each hole. A **too-dense plan view now auto-escalates**:
+  a part the layout cannot legibly dimension hole-by-hole is replaced by a
+  complete per-instance hole chart (`TAG | ⌀ | X | Y`, datum-relative) plus
+  balloons, instead of silently dropping callouts and location dims. The chart
+  wraps into multiple column-blocks to fit the page.
+- **External turned diameters (#77).** A turned part lying along the X axis now
+  gets ø leader-callouts for its external stepped diameters, with thread/worm
+  patches collapsed into a single boss.
+- **Pin / manual override (#89).** `dwg.pin(name)` / `dwg.unpin(name)` fix an
+  annotation's position so `repair()` — and the layout engine — never move it; a
+  deliberate (human or AI) placement wins over automatic layout.
+
+### Changed
+
+- Hole-callout and turned-diameter placement is deconflicted through the shared
+  `LayoutSolver` instead of ad-hoc per-pass logic (no output change).
+
+### Docs
+
+- The skill and generated-script header now lead with the domain API
+  (`features` / `place_dim` / `repair` / `lint_summary`) and the
+  build → critique → fix loop. ADR 0003 records the layout architecture; ADRs
+  0001/0002 remain the editing-model and lint→repair foundations.
+
 ## v0.1.9 — 2026-06-16
 
 ### Added

{draftwright-0.1.9 → draftwright-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.1.9
+Version: 0.1.10
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -680,9 +680,10 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
-Requires-Dist: build123d-drafting-helpers>=0.10.0
+Requires-Dist: build123d-drafting-helpers>=0.10.1
 Requires-Dist: build123d>=0.9.0
 Requires-Dist: kiwisolver<2,>=1.4
+Requires-Dist: numpy>=1.24
 Provides-Extra: pdf
 Requires-Dist: cairosvg>=2.7; extra == 'pdf'
 Description-Content-Type: text/markdown
@@ -720,7 +721,8 @@ draftwright my_part.step --title "Mounting Block" --number DWG-001
 - **Three orthographic views** (front, plan, side) sized and scaled automatically to the
   page
 - **Dimensions** on every principal envelope face, plus bore callouts (diameter, depth,
-  counterbore, spotface) on all holes
+  counterbore, spotface) on all holes, and ø leader-callouts for the external stepped
+  diameters of turned parts
 - **Section A–A** with ISO 128-44 solid filled cutting-plane arrows and ISO 128-50 45°
   hatching on the cut face, triggered automatically when blind or stepped holes would
   otherwise be hidden-line-only
@@ -784,17 +786,27 @@ scale, page_w, page_h, n_steps = choose_scale(80, 60, 20, page="A3")
 make_drawing(part, out="drawing", scale=2.0, page="A2")
 ```
 
-### Lint and coverage
+### Edit, critique, and self-repair
 
-```python
-from draftwright import build_drawing, lint_feature_coverage
+Edit a `Drawing` in **domain vocabulary** — the engine places annotations
+automatically, so you say *what* to dimension, not *where*:
 
+```python
 dwg = build_drawing(part)
-issues = dwg.lint()   # geometry lint + feature-coverage check
-for i in issues:
-    print(i.severity, i.message)
+
+# Inspect detected features and add a dimension in domain terms (auto-placed):
+for f in dwg.features("plan"):
+    dwg.place_dim(f.page_pos, (f.page_pos[0] + f.diameter, f.page_pos[1]),
+                  "below", "plan", dwg.draft, name="dim_pocket")
+
+crit = dwg.lint_summary()   # {"passed", "score", "by_code", "issues":[…suggestion]}
+dwg.repair()                # auto-fix mechanically-fixable lint; never worsens
 ```
 
+Each `LintIssue` carries a domain-meaningful `code` and, when computable, a
+ready-to-apply `suggestion`. See `docs/adr/` for the design (deterministic
+generation, the lint→repair loop, and the constraint-based layout engine).
+
 ## Architecture
 
 draftwright is a single module (`make_drawing.py`) on top of two Apache 2.0 libraries:

{draftwright-0.1.9 → draftwright-0.1.10}/README.md

@@ -31,7 +31,8 @@ draftwright my_part.step --title "Mounting Block" --number DWG-001
 - **Three orthographic views** (front, plan, side) sized and scaled automatically to the
   page
 - **Dimensions** on every principal envelope face, plus bore callouts (diameter, depth,
-  counterbore, spotface) on all holes
+  counterbore, spotface) on all holes, and ø leader-callouts for the external stepped
+  diameters of turned parts
 - **Section A–A** with ISO 128-44 solid filled cutting-plane arrows and ISO 128-50 45°
   hatching on the cut face, triggered automatically when blind or stepped holes would
   otherwise be hidden-line-only
@@ -95,17 +96,27 @@ scale, page_w, page_h, n_steps = choose_scale(80, 60, 20, page="A3")
 make_drawing(part, out="drawing", scale=2.0, page="A2")
 ```
 
-### Lint and coverage
+### Edit, critique, and self-repair
 
-```python
-from draftwright import build_drawing, lint_feature_coverage
+Edit a `Drawing` in **domain vocabulary** — the engine places annotations
+automatically, so you say *what* to dimension, not *where*:
 
+```python
 dwg = build_drawing(part)
-issues = dwg.lint()   # geometry lint + feature-coverage check
-for i in issues:
-    print(i.severity, i.message)
+
+# Inspect detected features and add a dimension in domain terms (auto-placed):
+for f in dwg.features("plan"):
+    dwg.place_dim(f.page_pos, (f.page_pos[0] + f.diameter, f.page_pos[1]),
+                  "below", "plan", dwg.draft, name="dim_pocket")
+
+crit = dwg.lint_summary()   # {"passed", "score", "by_code", "issues":[…suggestion]}
+dwg.repair()                # auto-fix mechanically-fixable lint; never worsens
 ```
 
+Each `LintIssue` carries a domain-meaningful `code` and, when computable, a
+ready-to-apply `suggestion`. See `docs/adr/` for the design (deterministic
+generation, the lint→repair loop, and the constraint-based layout engine).
+
 ## Architecture
 
 draftwright is a single module (`make_drawing.py`) on top of two Apache 2.0 libraries:

{draftwright-0.1.9 → draftwright-0.1.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.1.9"
+version = "0.1.10"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -12,8 +12,9 @@ authors = [{ name = "Paul Fremantle", email = "pzfreo@gmail.com" }]
 requires-python = ">=3.10"
 dependencies = [
     "build123d>=0.9.0",
-    "build123d-drafting-helpers>=0.10.0",
+    "build123d-drafting-helpers>=0.10.1",
     "kiwisolver>=1.4,<2",
+    "numpy>=1.24",
 ]
 keywords = ["build123d", "cad", "drafting", "engineering-drawing", "technical-drawing", "automation"]
 classifiers = [

draftwright-0.1.10/skills/SKILL.md

@@ -0,0 +1,273 @@
+# Automated Engineering Drawing with draftwright
+
+Use this skill when asked to create an engineering drawing automatically from a
+build123d solid or STEP file. It requires the **draftwright** package (AGPL-3.0)
+to be installed in the execution environment.
+
+> **License notice**: draftwright is AGPL-3.0. If you deploy code that uses it
+> as part of a network service you must make your application source available.
+> For Apache 2.0 annotation primitives only (`Dimension`, `Leader`, `TitleBlock`,
+> etc.), use `build123d-drafting-helpers` instead without this obligation.
+
+**There are two paths — start with the automatic one.**
+
+1. **Automatic (`make_drawing`)** — one call turns a part (or STEP file) into a
+   four-view SVG + DXF with dimensions, centrelines, and an ISO 7200 title
+   block.
+2. **Builder (`build_drawing`)** — the same pipeline, but it hands back a live
+   `Drawing` you can edit before export.
+
+Requires `draftwright >= 0.1.9` and `build123d-drafting-helpers >= 0.10.1`.
+Install: `pip install draftwright`.
+
+**Design model (worth knowing before you edit):** the engine is *deterministic*
+— no AI inside it — and you refine a drawing by **stating domain intent**
+(dimension this feature, section through here) and letting the engine **place
+everything automatically** (placement is constraint-based; you never compute page
+coordinates). When the first pass isn't perfect, you drive a **build → critique
+→ fix** loop (Step "Lint → critique → fix" below), not a hand-layout edit. The
+rationale lives in `docs/adr/`: 0001 (deterministic generation over an editable
+DSL), 0002 (the lint critique → domain-repair loop), 0003 (the constraint-based
+layout engine). Edit through the domain API; treat `Placeable`/page mechanics as
+internals.
+
+---
+
+## Step 0 — Understand the part first
+
+```
+mcp__build123d-mcp__execute  — build the part in the session
+mcp__build123d-mcp__measure  — confirm volume, bbox, face count
+mcp__build123d-mcp__render_view (save_to='/tmp/preview.png') — visual sanity check
+```
+
+Register the part under a stable name with `show(part, "part")`.
+
+---
+
+## Step 1 — Generate the drawing automatically (start here)
+
+```python
+from draftwright import make_drawing
+
+svg, dxf = make_drawing(
+    part,                       # an in-session build123d object, OR a "path/to/part.step"
+    out="drawings/bracket",     # output stem; ".svg"/".dxf" are appended
+    title="BRACKET",            # ISO 7200 document title
+    number="DWG-042",           # ISO 7200 document identifier
+    tolerance="ISO 2768-f",     # general tolerance
+    drawn_by="Your Name",
+)
+```
+
+`make_drawing` chooses the scale + ISO page size, projects front/plan/side/iso
+views, and annotates automatically — then lints and writes both SVG and DXF.
+
+Automatic annotation covers **prismatic parts in full**: every recognised hole
+gets a grouped callout ("4× ø10 THRU", counterbore/depth symbols), bolt circles
+get "EQ SP ON øD BC" callouts with a pitch-circle centreline, linear arrays get
+pitch dims, every hole gets a centre mark and baseline X/Y location dims from the
+min-X/Y datum corner, and blind/counterbored holes trigger an automatic SECTION
+A–A with ISO 128-44 solid filled arrows and ISO 128-50 45° hatching. Turned
+parts get OD/length dims, centrelines, bore leaders, and — for parts turned
+about a horizontal (X) axis — their external stepped diameters as ø
+leader-callouts.
+
+Then verify (Step 3). For most parts you are done here.
+
+---
+
+## Step 2 — Customise with the Drawing builder
+
+`build_drawing(...)` returns a live `Drawing`. **Edit it in *domain* vocabulary
+— locate things with `features()`, add dimensions with `place_dim()`, choose a
+side and view.** You give *what* and *where on the part*; the engine decides the
+*offset, stacking, and strip slot* (placement is automatic and constraint-based).
+You still pass page-point endpoints, but you get them from `features()` or
+`dwg.at(...)` — you never compute offsets or pick a strip. Hand-building a raw
+`Leader` at `dwg.at(...)` coordinates is the escape hatch, not the default.
+
+```python
+from draftwright import build_drawing
+
+dwg = build_drawing(part, out="drawings/bracket", title="BRACKET",
+                    number="DWG-042", tolerance="ISO 2768-f", drawn_by="Your Name")
+```
+
+**Inspect what the engine found and placed (read APIs):**
+
+```python
+dwg.features("plan")        # detected features in a view → [FeatureInfo(...)]
+                            #   each: .type .diameter .through .depth .count .page_pos
+dwg.annotations()           # {name: type} of every named annotation already on the sheet
+dwg.get_annotation(name)    # the named annotation object, or None
+dwg.view_bounds("front")    # (x_min, y_min, x_max, y_max) page bbox of a view, or None
+dwg.items                   # the ordered, mutable list of annotation objects
+dwg.views                   # {"front","plan","side","iso"} → (visible, hidden) compounds
+dwg.draft / dwg.scale / dwg.page_w / dwg.page_h
+```
+
+**Add a linear dimension with `place_dim`** — it allocates the offset and stacks
+clear of existing dims; you give two page-point endpoints and a side/view:
+
+```python
+# side ∈ {"above","below","left","right"}; view ∈ {"front","plan","side"}.
+p1 = dwg.at("front", 0, 0, 0)          # world → page point
+p2 = dwg.at("front", 40, 0, 0)
+dwg.place_dim(p1, p2, "above", "front", dwg.draft, name="dim_len")
+
+dwg.remove("dim_od")                    # drop an automatic annotation by name
+```
+
+**Add a diameter callout on a hole the auto-pass missed** — locate it with
+`features()` and attach a `HoleCallout` (this is what the `feature_not_dimensioned`
+lint suggestion hands you verbatim — see the loop below):
+
+```python
+from build123d_drafting import HoleCallout, Leader
+
+for f in dwg.features("plan"):          # plan→Z holes, front→Y, side→X
+    if abs(f.diameter - 4.0) < 0.2:
+        callout = HoleCallout(f.diameter, count=f.count, through=f.through,
+                              depth=f.depth, draft=dwg.draft)
+        elbow = (f.page_pos[0] + 15, f.page_pos[1] + 10, 0)
+        dwg.add(Leader((*f.page_pos, 0), elbow, "", dwg.draft, callout=callout),
+                name="hole_4")
+```
+
+**Escape hatch** — only when no domain verb fits (e.g. a free-form note at an
+exact spot). Prefer the above; this couples you to page mechanics:
+
+```python
+from build123d_drafting import Leader
+dwg.add(Leader(tip=dwg.at("front", 10, 0, 5), elbow=(8, 40, 0),
+               label="ø4 BORE", draft=dwg.draft), "ldr_bore")
+```
+
+Then re-lint and export:
+
+```python
+issues = dwg.lint()                       # list of LintIssue; [] when clean
+svg, dxf = dwg.export("drawings/bracket")
+```
+
+`make_drawing(...)` is exactly `build_drawing(...).export()`.
+
+**Add a section or auxiliary view** with `add_view()`:
+
+```python
+look = dwg.look_at
+bottom = (look[0], look[1], look[2] - dwg.dist)
+vc = dwg.add_view("bottom", part, bottom, (0, 1, 0), (260.0, 60.0))
+px, py = vc.pp(world_x, world_y, world_z)
+```
+
+---
+
+## Step 3 — Verify
+
+```
+mcp__build123d-mcp__render_drawing(svg_path='drawings/part_name.svg', save_to='/tmp/dwg.png')
+mcp__build123d-mcp__save_drawing_annotations(svg_path='drawings/part_name.svg')
+mcp__build123d-mcp__inspect_drawing(svg_path='drawings/part_name.svg')
+```
+
+---
+
+## Step 4 — Save a standalone regeneration script (default)
+
+**A — Drawing from a STEP file**:
+
+```python
+from draftwright import generate_script
+
+generate_script(
+    "path/to/part.step",
+    out="scripts/drawings/bracket",
+    title="BRACKET", number="DWG-042",
+    tolerance="ISO 2768-f", drawn_by="Your Name",
+)
+```
+
+**B — Drawing an in-session object** (hand-write the script):
+
+```python
+#!/usr/bin/env python3
+"""BRACKET — regenerates drawings/bracket.svg + .dxf in one run."""
+from draftwright import make_drawing
+from myproject.bracket import build_bracket
+
+part = build_bracket()
+make_drawing(part, out="drawings/bracket", title="BRACKET",
+             number="DWG-042", tolerance="ISO 2768-f", drawn_by="Your Name")
+```
+
+---
+
+## Scale and page control
+
+```python
+from draftwright import choose_scale
+
+SCALE, PAGE_W, PAGE_H, TB_W = choose_scale(x_size, y_size, z_size)
+make_drawing(part, out="drawing", scale=2.0, page="A2")
+```
+
+---
+
+## Lint → critique → fix (the loop to drive as an AI)
+
+draftwright is built to be *iterated*: build, read a machine-readable critique,
+apply a domain-level fix, re-build. This is the supported refinement model —
+prefer it over eyeballing the SVG and hand-placing annotations.
+
+```python
+dwg = build_drawing(part)
+
+# 1. Critique — the machine channel. JSON-friendly aggregate of lint().
+crit = dwg.lint_summary()
+#   {"passed": bool, "score": 0..1, "errors": n, "warnings": n, "infos": n,
+#    "by_code": {code: n}, "issues": [{code, severity, message, suggestion?}, ...]}
+# Gate on the severity/code COUNTS, not the scalar score.
+
+# 2. Each issue names the problem in DOMAIN terms and (when computable) carries a
+#    ready-to-apply suggestion — a domain-API call you paste in, not page maths.
+for i in dwg.lint():
+    print(i.severity, i.code, i.message)
+    if getattr(i, "suggestion", None):
+        print("  fix:", i.suggestion)   # e.g. dwg.place_dim(...) / dwg.add_view(...)
+
+# 3. Self-repair — auto-applies the mechanically-fixable issues (overlapping
+#    labels pushed apart, wrong-side dims flipped). Runs by default inside
+#    build_drawing; call again after manual edits. It never makes a sheet worse.
+dwg.repair()
+
+# Pin a deliberate placement so repair won't move it (the constraint solver will
+# honour it too as it lands — ADR 0003):
+dwg.pin(name)             # name from dwg.annotations(); dwg.unpin(name) to release
+```
+
+Codes are domain-meaningful (`feature_not_dimensioned`, `feature_count_mismatch`,
+`callout_dropped`, `location_ref_dropped`, `step_dim_dropped`, …), so a fix is
+always expressible through the domain API (`place_dim`, `features`, `add_view`),
+never the page-layout internals. Loop until `passed` (or the score plateaus).
+
+Coverage-only check, standalone:
+
+```python
+from draftwright import build_drawing, lint_feature_coverage
+issues = build_drawing(part).lint()   # geometry lint + feature-coverage check
+```
+
+---
+
+## Using this skill with build123d-mcp
+
+This skill requires `draftwright` to be in the server's import allowlist.
+The build123d-mcp server allows it by default from v0.3.51 onwards. If you see
+`ImportError: draftwright is not in the import allowlist`, pass
+`--allow-imports draftwright` to the server CLI or set
+`BUILD123D_ALLOW_IMPORTS=draftwright` in the environment.
+
+For annotation primitives (`Dimension`, `Leader`, `TitleBlock`, `lint_drawing`,
+`ViewCoordinates`, etc.) continue to import from `build123d_drafting`.