KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #cli #open-source #ai #claude-code #codex #developer-tools #react #windows #deepseek-harness #ai-agent

draftwright

★ 47 Open GitHub ↗

Automated technical-drawing generation for build123d and STEP files

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![CI](https://github.com/pzfreo/draftwright/actions/workflows/ci.yml/badge.svg)](https://github.com/pzfreo/draftwright/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/pzfreo/draftwright/branch/main/graph/badge.svg)](https://codecov.io/gh/pzfreo/draftwright)
[![PyPI](https://img.shields.io/pypi/v/draftwright.svg)](https://pypi.org/project/draftwright/)
[![Python](https://img.shields.io/pypi/pyversions/draftwright.svg)](https://pypi.org/project/draftwright/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://raw.githubusercontent.com/pzfreo/draftwright/main/LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

**[API reference](https://pzfreo.github.io/draftwright/)** ·
**[Examples and source](https://github.com/pzfreo/draftwright#readme)**

Automated technical-drawing generation for [build123d](https://github.com/gumyr/build123d).
Point it at a solid (or a STEP file) and get a fully-annotated multi-view engineering
drawing — orthographic views, dimensions, section A–A, ISO hatching, title block — ready
to export as PDF, SVG, and DXF.

![Example engineering drawing generated by draftwright](https://raw.githubusercontent.com/pzfreo/draftwright/main/docs/images/example.png)

*A mounting plate, generated automatically: three dimensioned orthographic views, a
counterbored bore callout (`⌀18 THRU ⊔ ⌀30 ↓14`), a `4× ⌀8 THRU` hole-pattern callout,
Section A–A with ISO hatching, an isometric, and an ISO 7200 title block — every
annotation placed by the engine.*

## Quick start

```
pip install draftwright
```

### Command line

Point it at a STEP file — that's the whole workflow:

```
draftwright my_part.step --title "Mounting Plate" --number DWG-001
# writes my_part.pdf (the default)
```

Choose formats, scale, and page; or emit an editable drawing script:

```
draftwright my_part.step --format pdf,dxf     # also: svg, all
draftwright my_part.step --scale 2 --page A3  # override the auto scale / page
draftwright my_part.step --script             # write an editable declarative Sheet script
```

`draftwright --help` lists every flag; `--version` prints the version.

### Python

One call turns a build123d solid (or a STEP file) into a drawing. This is the exact
part in the image above:

```python
from build123d import Box, Cylinder, Pos
from draftwright import make_drawing

part = (
    Box(100, 70, 24)
    - Pos(0, 0, 0) * Cylinder(9, 40)     # central bore, counterbored below
    - Pos(0, 0, 8) * Cylinder(15, 20)    # counterbore → triggers Section A–A
    - Pos(-38, 24, 0) * Cylinder(4, 40)  # 4× corner holes (recognised as a pattern)
    - Pos(38, 24, 0) * Cylinder(4, 40)
    - Pos(-38, -24, 0) * Cylinder(4, 40)
    - Pos(38, -24, 0) * Cylinder(4, 40)
)
make_drawing(part, out="my_part", title="Mounting Plate", number="DWG-001")
# writes my_part.svg and my_part.dxf   (or from a STEP file: make_drawing(step_file="p.step", out="my_part"))
```

For inspection and editing, get a composable `Drawing`:

```python
from draftwright import build_drawing

dwg = build_drawing(part, title="Mounting Plate")
issues = dwg.lint()                       # list[LintIssue] — coverage, page bounds, ISO
paths = dwg.export("my_part", formats=("svg", "dxf"))   # {"svg": ..., "dxf": ...}
```

`export()` with no `formats=` returns the old `(svg, dxf)` tuple; that shape is deprecated
and removed in 0.5.0 (see [docs/deprecations.md](docs/deprecations.md)).

### Declarative drawings — reference features, declare intent

Instead of relying on detection, **reference the build123d objects you built** and declare
only the drawing intent — geometry supplies the sizes (⌀ read off the object), you supply
tolerances, fits, datums, GD&T, and surface finish. The fluent `Sheet` skips detection and
dimensions exactly what you declare (ADR 0011):

```python
from build123d import Box, Cylinder, Pos
from draftwright import Sheet

plate = Box(120, 80, 20)
bore = Pos(0, 0, 0) * Cylinder(4, 20)

sheet = Sheet(plate - bore, title="Plate", number="DWG-002")
env = sheet.envelope()
sheet.datum("A", plate.faces().sort_by()[-1])             # datum A on the top face
hole = sheet.hole(bore).finish("1.6").note("M3x0.5 TAP")  # ⌀8 bore, Ra 1.6, tapped
sheet.control(hole).position(0.1, to="A", diameter=True)  # ⌀0.1 position wrt A

sheet.authored_dimensions()                               # THIS is the complete set
sheet.dimension(env, "width.length")                      # (ADR 0016: a build says where
sheet.dimension(env, "height.length")                     #  its dimensions come from, and
sheet.dimension(hole, "bore.diameter")                    #  omitting one means suppress it)

sheet.export("plate")                                     # writes plate.pdf
```

Every aspect the geometry can't carry is a declared verb: `.tolerance(±)` / `.fit("H7")`
(ISO 286), `.finish("Ra")` (ISO 1302), `sheet.datum(letter, ref)` (ISO 5459), and
`sheet.control(ref)` with all 14 ISO 1101 characteristics
(`.position`/`.flatness`/`.perpendicularity`/`.circular_runout`/…), plus `.thread("M3x0.5")`
(a tap/thread spec folded onto the hole callout), `.knurl("0.8")`, and `sheet.note(text, ref)`
/ `.note(text)` for any other free-text shop callout (`DEBURR`, chip-relief). A feature verb returns
a chainable handle (`sheet.hole(bore)`) that the aspect and `control(...)` verbs decorate;
targets are placed automatically — the view and strip are derived from the referenced
feature or face, with `view=`/`side=` overrides.

### From a part to an object-referenced script

`draftwright part.step --script` writes an editable `Sheet` script. When you built the part
yourself (rather than importing a STEP), pass your **live source** as a `module:attr` (or
`file.py:attr`) object spec, and the script binds `part` back to your real object:

```bash
draftwright mymodule:thumbwheel --script
```

The emitted values are *detected* off the geometry — honest, and a good starting point. Since
you have the objects, swap each numbered line for a reference so the object stays the single
source of truth (ADR 0011 — the size is read off the object, no numbers restated):

```python
# generated (detected):
sheet.step(diameter=8, length=25, at=(0, 0, 12), axis="z")

# edited to reference your objects:
features = mymodule.thumbwheel_features()
part = features.part
sheet.step(features.journal)
sheet.hole(features.m3_bore).thread("M3x0.5").finish("1.6")   # tapped + Ra on the same hole
```

An object-sourced script carries an inline tip pointing at exactly this edit; a STEP-sourced
script keeps the detected numbers (there's no object to reference).

Every generated script ends by naming the drawing it built, so you can critique or inspect it
before (or instead of) exporting — one build, not two:

```python
drawing = sheet.build()

for issue in drawing.lint():                  # ISO/coverage critique of THIS drawing
    print(issue.severity, issue.code, issue.message)

drawing.export("part", formats=("pdf",))
```

`sheet.export(...)` remains the one-liner for handwritten scripts that just want the file.

See [`docs/multi-feature-object-reference-workflow.md`](docs/multi-feature-object-reference-workflow.md)
for a complete, runnable walkthrough of this pattern on a multi-feature turned part —
including the backward-compatible refactor, external threads (no `.thread()` on a step —
use `.note(...)`), and why an object-sourced script should point at the cheap geometry
variant of your source.

## What it produces

- **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, 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
- **Title block** (ISO 7200) with part name, drawing number, scale, tolerance, and date
- **Lint** — `Drawing.lint()` checks annotation coverage, page bounds, and ISO compliance
  and returns structured `LintIssue` objects

All output is real build123d geometry, so PDF, SVG, and DXF all come from the same
source and dimensions are live on the DXF layer.

Requires Python ≥ 3.10 and build123d ≥ 0.9.0. Annotation primitives are provided by
[`build123d-drafting-helpers`](https://github.com/pzfreo/build123d-drafting-helpers),
installed automatically as a dependency.

## Going further

### Scale and page control

```python
from draftwright import choose_scale

# Auto-select the best ISO/ASME standard scale for an A3 sheet
scale, page_w, page_h, n_steps = choose_scale(80, 60, 20, page="A3")

# Override
make_drawing(part, out="drawing", scale=2.0, page="A2")
```

### Edit, critique, and self-repair

Edit a `Drawing` in **domain vocabulary** — the engine places annotations
automatically, so you say *what* to dimension, not *where*:

```python
dwg = build_drawing(part)

# Inspect detected features and add a pinned dimension in domain terms:
env = next(f for f in dwg.model().features if f.kind == "envelope")
dwg.dimension(env, "length", role="width", side="below", pin=True)

crit = dwg.lint_summary()
# Legacy diagnostic severity heuristic (not overall drawing quality):
assert crit["diagnostic_score"] == crit["score"]
# Independently observable components; no composite quality score is invented:
completeness = crit["quality"]["completeness"]
# Named for its denominator: the requirements Draftwright recognized AND can audit.
# 1.0 does NOT mean the drawing is complete — it means every requirement recognition did
# identify was placed, however much of the part it missed. What was never recognized never
# became a requirement. (Recognized nothing auditable at all? available is False, not 1.0.)
audited = completeness["audited_score"]
assert completeness["scope"] == "audited_recognized_requirements"
completeness["excludes"]                     # what the denominator cannot see
completeness["unrecognised_geometry_reports"]  # a floor on that gap, never a measure
legibility = crit["quality"]["legibility"]
# Raw pair findings remain available and keep the original count semantics.
legibility["warnings"], legibility["by_code"], crit["issues"]
# The legibility scalar uses primary issues: one affected annotation/failure mechanism even
# when several pairwise comparisons found it. These fields make that denominator explicit.
legibility["primary_issues"], legibility["primary_by_code"], legibility["affected_pairs"]
assert legibility["score_inventory"] == "primary_issues"
restraint = crit["quality"]["restraint"]  # unavailable until provenance is complete
dwg.repair()                # auto-fix mechanically-fixable lint; never worsens
```

Completeness is strict about authored omissions: removing a dimension from a complete authored
set records a `suppressed` requirement and lowers the audited score. The evidence distinguishes
that choice from a placement failure, but cannot certify that the omission is
engineering-correct; plain deletion is not an accepted-waiver mechanism.

**`audited_score` is not a completion gate.** It answers "of the requirements we recognised and
can audit, how many were placed?" — so a part can score 1.0 with whole features missing from the
drawing, if recognition never identified them. Gate on issue codes and severities, and read
`excludes` and `unrecognised_geometry_reports` for what the denominator cannot account for.

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 collect-then-solve placement).

## Architecture

draftwright is structured as a **part-drawing compiler** (ADR 0015): recognised
or declared features converge on a `PartModel` IR, then planner-fed and
sanctioned model-routed render intents feed shared placement, projection, and
export. Coverage lint independently compares recognised geometry with the
placed drawing, so an upstream omission cannot hide from verification. It
builds on two libraries:

```
draftwright
    └── build123d-drafting-helpers  — Dimension, Leader, HoleCallout, …
    └── build123d                   — CAD kernel
```

It owns feature recognition (`recognition/`) and linting (`linting/`); annotation
primitives (`Dimension`, `Leader`, etc.) live in `build123d-drafting-helpers` and can
be used independently. The compiler is largely converged in production — turned
dims/lengths, centre marks, envelope, slots, holes (callouts/locations/grouping),
the section A–A trigger, the prismatic step-ladder + rotational furniture, and PMI/GD&T
are all on the IR. See
[`docs/target-architecture.md`](docs/target-architecture.md) and
[`docs/layout-algorithm-primer.md`](docs/layout-algorithm-primer.md) for a short walkthrough, plus
[`docs/adr/`](docs/adr/). The engine handles view layout (strip/zone model), scale
selection, annotation placement, and section rendering.

The codebase has been entirely written by LLM (Claude Code) under detailed guidance from a person.

draftwright

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README