draftwright 0.4.0__tar.gz → 0.4.1__tar.gz

{draftwright-0.4.0 → draftwright-0.4.1}/CHANGELOG.md

@@ -2,6 +2,97 @@
 
 ## Unreleased
 
+## v0.4.1 — 2026-08-07
+
+**The recognition trust release.** Automatic drawings now fail closed on unsupported inner
+profiles, prove semantic coverage for flats, slots and patterns, and retain the measurement
+identity needed to explain placed, suppressed, dropped and missing definitions. Several real
+STEP case studies also move from clean-looking but incomplete output to complete drawings or
+actionable lint.
+
+### Discouraged (supported)
+
+- **`Sheet.auto_dimensions()` and `Sheet.add_dimension()` now emit
+  `SoftDeprecationWarning`** (#1043). They remain supported with no removal planned; the
+  warning steers declared scripts toward `authored_dimensions()` plus explicit
+  `dimension(feature, parameter_id)` lines, where omission can mean suppression. Automatic
+  `build_drawing(part)` and the `Sheet.from_part(part)` on-ramp remain silent. See
+  `docs/deprecations.md` for filtering and migration guidance.
+
+### Added
+
+- **Finished drawings expose why measurements were omitted and, on covered placement paths,
+  what an annotation measures** (#996/#1002). `Drawing.suppressions()` returns the compiler's
+  omission ledger, `Drawing.measurement_keys(name)` exposes recorded measurement provenance, and
+  `draftwright.audit.diff_builds(before, after)` reports losses, substitutions and candidate
+  suppression explanations. The differential is deliberately a triage aid, not a proof where
+  renderer identity remains incomplete.
+
+- **Physical-completeness lint now follows semantic correspondence for flats, lone slots and
+  slot patterns** (#1018). Coverage is joined through recognition, IR and compiler identities
+  rather than inferred from label text or page geometry, and distinguishes authored
+  suppression, placement drops, missing definitions and unverifiable provenance.
+
+- **Full-span floored open channels are recognised and dimensioned as first-class features**
+  (#917). Automatic and declared drawings state the independent overall extent, one wall and
+  channel width, suppress the derived opposite wall, and report any missing member of that
+  defining chain.
+
+### Fixed
+
+- **Square and near-square parts retain both independent planar extents** (#997). A plain
+  square plate could previously lose both plan dimensions, while parts up to five percent off
+  square could lose one and be silently represented as square. The unsafe suppression rule is
+  removed; explicit square notation remains tracked separately in #918.
+
+- **Machined flats retain their physical stock identity from recognition through placement
+  and completeness lint** (#1013/#1015/#1034/#1036). Flats on separate parallel, coaxial or
+  slanted stock no longer collapse into one definition or borrow an opposite face from another
+  stock region. Independent callouts receive clear-margin candidates, while double-D faces on
+  one stock still form one A/F requirement.
+
+- **Dense callout and step-detail cases keep their complete defining set** (#915). Hole
+  callout batches are reconciled as a queue, detail views fit their actual aspect, step levels
+  retain the supporting-face correspondence needed for truthful crops, and a detail redraws
+  only rungs omitted from its parent view.
+
+- **Pocket leaders start on the physical opening rim** (#916), removing the spurious inner
+  silhouette crossing while preserving the solved label corridor and approved dimensions on
+  X-, Y- and Z-depth pockets.
+
+- **Wedge-mounted raised pads survive recognition** (#909). Lower ledges that touch only in
+  plan no longer make the recogniser discard a valid upper pad; true staircase tiers remain
+  excluded.
+
+- **Annotation-dense detail placement no longer stalls the build** (#1065). Detail views
+  avoid every decomposed annotation shaft, witness, label and item footprint; CTC-02
+  supplies 571 such boxes. The free-rectangle search previously treated that set as tiny
+  and admitted roughly 34 billion candidate rectangles, exhausting the slow tier's
+  ten-minute test budget before export. A compressed-coordinate sweep preserves the same
+  deterministic winning rectangle while completing the real search in seconds.
+
+- **Through double-D bores are recognised and called out as first-class hole profiles**
+  (#1061). Automatic and declared builds preserve the parent-circle diameter, A/F size,
+  orientation and depth, and render one compound `DOUBLE-D ... A/F` bore callout. Physical
+  critique now accepts that supported inner profile while retaining a separate warning for
+  13 evenly spaced common-circle arcs on the unresolved outer boundary; it does not infer a
+  repeating full profile or a gear standard.
+
+- **Unsupported internal profiles no longer pass physical-completeness lint silently**
+  (#1058). Inner loops on principal boundary faces are checked against the current
+  circular-hole, rectangular-opening, true-obround, and proven through-double-D vocabulary.
+  Profiles outside it now produce
+  `unrecognised_defining_geometry` and reduce the lint score instead of allowing an
+  envelope-only drawing to score 1.0.
+
+### Changed
+
+- **Crowded prismatic step dimensions recover into an enlarged detail view by default**
+  (#909). The automatic `build_drawing` / `make_drawing` / CLI paths and generated
+  `Sheet` scripts now preserve the omitted dimensions instead of returning
+  `step_dim_dropped` unless the caller remembered `detail_view=True`. Pass
+  `detail_view=False` to retain the parent-view-only behavior and its lint warning.
+
 ## v0.4.0 — 2026-08-02
 
 **The compat-exit release.** Every surface whose documented removal target was 0.4.0 is gone,

{draftwright-0.4.0 → draftwright-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.4.0
+Version: 0.4.1
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -771,9 +771,12 @@ from draftwright import build_drawing
 
 dwg = build_drawing(part, title="Mounting Plate")
 issues = dwg.lint()                       # list[LintIssue] — coverage, page bounds, ISO
-svg_path, dxf_path = dwg.export("my_part")
+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
@@ -789,10 +792,16 @@ plate = Box(120, 80, 20)
 bore = Pos(0, 0, 0) * Cylinder(4, 20)
 
 sheet = Sheet(plate - bore, title="Plate", number="DWG-002")
-sheet.envelope()
+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
 ```
 

{draftwright-0.4.0 → draftwright-0.4.1}/README.md

@@ -75,9 +75,12 @@ from draftwright import build_drawing
 
 dwg = build_drawing(part, title="Mounting Plate")
 issues = dwg.lint()                       # list[LintIssue] — coverage, page bounds, ISO
-svg_path, dxf_path = dwg.export("my_part")
+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
@@ -93,10 +96,16 @@ plate = Box(120, 80, 20)
 bore = Pos(0, 0, 0) * Cylinder(4, 20)
 
 sheet = Sheet(plate - bore, title="Plate", number="DWG-002")
-sheet.envelope()
+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
 ```
 

{draftwright-0.4.0 → draftwright-0.4.1}/docs/adr/README.md

@@ -33,6 +33,7 @@ architecture** table; open retired or superseded records only for design history
 | [0014](0014-collect-then-solve-annotation-placement.md) | Collect-then-solve annotation placement (as built) | Collect, select, assign, and deterministically solve annotations per corridor before rendering. | Accepted; supersedes 0009 | `test_carve_free_position_callers.py`, `test_strip_layout.py`, `test_layout_property.py`, `test_import_boundaries.py` |
 | [0015](0015-part-drawing-compiler-as-built.md) | The part-drawing compiler, as built | Use one detected-or-declared feature IR and planner-fed dimension groups as the compiler waist. | Accepted; supersedes 0008 | `test_part_model.py`, `test_detect_once.py`, `test_import_boundaries.py` |
 | [0016](0016-declared-dimensioning-intent.md) | Declared dimensioning intent: capture what to measure, let the engine place it | Declare which measurements matter as scale-independent intent routed through the planner and corridor solve; never hardcode dimension geometry. | Accepted; epic #867 complete; phase 6 landed (#940) | `test_compiled_plan_boundary.py`, `test_label_provenance.py`, `test_sheet_emit.py`, `test_add_dimension.py` |
+| [0017](0017-recognition-inventory-correspondence-and-measurement-provenance.md) | One recognition result per run; correspondence is evidence-gated | Produce one explicit recognition result owned by `BuildState`; require vertical-slice evidence before generalising correspondence, identity, requirements, outcomes, or reconciliation. | Accepted; ownership phase landed, extensions gated by #1018 | `test_recognition_manifest.py`, `test_recognition_result.py`, `test_declared_recognition_gate.py` |
 
 ## Historical records
 
@@ -49,5 +50,6 @@ architecture** table; open retired or superseded records only for design history
 - Layout and placement: 0004 → 0014 → 0012.
 - Declared intent and the editable surface: 0001 → 0011 → 0012 → 0016.
 - Quality and correction: 0002, with provenance from 0010.
+- Recognition correspondence and completeness: 0007 → 0013 → 0015 → 0017.
 
 Tracking issue: #745.

{draftwright-0.4.0 → draftwright-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.4.0"
+version = "0.4.1"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -80,6 +80,18 @@ markers = [
     "slow: heavy end-to-end CTC fixture builds (deselected by default)",
     "smoke: curated build-light subset for a fast local check (~30 s)",
 ]
+# `SoftDeprecationWarning` marks a surface that is discouraged but SUPPORTED and not going
+# away (#1043). The suite exercises `Sheet.auto_dimensions()` in ~170 places, deliberately —
+# it is still a supported path and its behaviour must keep being tested. Migrating those to
+# authored dimensions would be churn that tests less, so the category is silenced here rather
+# than at ~170 call sites.
+#
+# This does NOT weaken the guard: `tests/test_soft_deprecation.py` asserts the warning with
+# `pytest.warns`, which fires regardless of this filter. Real `DeprecationWarning`s are
+# untouched and still carry removal dates (`tests/test_deprecation_dates.py`).
+filterwarnings = [
+    "ignore::draftwright.SoftDeprecationWarning",
+]
 # Coverage is a CI concern (it adds ~13% locally and instruments every line); the
 # CI workflow passes the --cov flags explicitly. Keep the local default lean.
 addopts = "--tb=short -m 'not slow'"
@@ -87,6 +99,9 @@ addopts = "--tb=short -m 'not slow'"
 [tool.coverage.run]
 source = ["src/draftwright"]
 omit = ["src/draftwright/__init__.py"]
+# Keep XML paths anchored at the repository root so local diff coverage and Codecov
+# measure the same changed source lines rather than relying on runner-specific paths.
+relative_files = true
 # Branch coverage makes the regression gate sensitive to untested decision paths,
 # which matter more than raw statement execution in the recognition/layout code.
 branch = true
@@ -94,8 +109,8 @@ branch = true
 [tool.coverage.report]
 # Baseline measured on the full fast tier on Linux/Python 3.13 (#825):
 # 92.05% combined line+branch coverage (93.90% statements, 86.89% branches).
-# Keep two points of cross-platform/kernel headroom; ratchet upward only after the
-# lowest CI matrix result has stayed above the proposed floor.
+# Keep two points of headroom; ratchet upward only after the canonical coverage job
+# has stayed above the proposed floor.
 fail_under = 90
 precision = 1
 exclude_lines = [

{draftwright-0.4.0 → draftwright-0.4.1}/src/draftwright/__init__.py

@@ -32,6 +32,11 @@ _LAZY = {
     "PmiRecord": "draftwright.pmi",
     "extract_pmi": "draftwright.pmi",
     "choose_scale": "draftwright.compose",
+    # A warning category users are told to filter must be importable without reaching into a
+    # private module (#1043 review) — and without paying for the CAD kernel. It lives in the
+    # dependency-free `_warnings` leaf for that second reason: defined in `_core` it cost ~6 s
+    # to reach, and the pytest filterwarnings entry naming it paid that on every invocation.
+    "SoftDeprecationWarning": "draftwright._warnings",
 }
 
 
@@ -68,6 +73,7 @@ _sys.modules[__name__].__class__ = _DraftwrightModule
 
 
 if TYPE_CHECKING:  # static analysers / IDEs — no runtime import, no kernel cost
+    from draftwright._warnings import SoftDeprecationWarning
     from draftwright.builder import build_drawing, make_drawing
     from draftwright.compose import choose_scale
     from draftwright.drawing import Drawing, FeatureInfo
@@ -85,6 +91,7 @@ def __dir__():
 
 __all__ = [
     "Drawing",
+    "SoftDeprecationWarning",
     "FeatureInfo",
     "PmiRecord",
     "Sheet",

{draftwright-0.4.0 → draftwright-0.4.1}/src/draftwright/_core.py

@@ -17,7 +17,7 @@ import functools
 import logging
 import math
 import re
-from bisect import bisect_right
+from bisect import bisect_left, bisect_right
 from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
@@ -26,7 +26,7 @@ from typing import TYPE_CHECKING, Literal
 
 if TYPE_CHECKING:
     from draftwright.compose import StripDepths
-    from draftwright.recognition import TurnedProfile
+    from draftwright.recognition import RecognitionResult, TurnedProfile
 
 from build123d import Align, BoundBox, Compound, Edge, Location, Mode, Shape, Text, Vector
 from build123d_drafting.helpers import (
@@ -49,18 +49,21 @@ from draftwright.layout import _greedy_strip_1d, _solve_strip_1d
 _log = logging.getLogger(__name__)
 
 
-def place_annotation(registry, items, obj, name=None, view=None, feature=None):
+def place_annotation(registry, items, obj, name=None, view=None, feature=None, measurement=None):
     """The annotation-placement primitive (#817): register *obj* under *name* — replacing any
     prior object of that name (dropped from the render list *items*) so a name maps to one
     object — append it to *items*, and record its owning *view* + source *feature* in *registry*.
     Shared by :meth:`Drawing._add` and :meth:`PlacementContext.place` so the render passes place
-    annotations without reaching into the ``Drawing``. Returns *obj*."""
+    annotations without reaching into the ``Drawing``. Returns *obj*.
+
+    *measurement* is the `DimensionId` *obj* draws, where the caller holds one (#1002) —
+    one axis finer than *feature*, since a feature has several measurements."""
     displaced = registry.named(name) if name is not None else None
     if displaced is not None:
         items.remove(displaced)
     annotate(obj, name)
     items.append(obj)
-    registry.add(obj, name, view, feature)
+    registry.add(obj, name, view, feature, measurement)
     return obj
 
 
@@ -536,58 +539,184 @@ def _legible_locations(positions, scale):
     return kept, n_too_close
 
 
-def _largest_empty_rect(drawable, obstacles, *, warn: bool = True):
+class _FreeRunIndex:
+    """Range-covered Y coordinates with the longest remaining free run.
+
+    Coordinate points are represented as zero-length cells between the ordinary
+    intervals.  That lets a degenerate obstacle split a gap exactly as the open
+    AABB overlap predicate does, without assigning the point any physical width.
+    """
+
+    def __init__(self, coordinates):
+        self.coordinates = coordinates
+        lengths = []
+        for i, value in enumerate(coordinates):
+            lengths.append(0.0)
+            if i + 1 < len(coordinates):
+                lengths.append(coordinates[i + 1] - value)
+        self._lengths = lengths
+        self._n = len(lengths)
+        size = 4 * self._n
+        self._cover = [0] * size
+        self._total = [0.0] * size
+        self._prefix = [0.0] * size
+        self._suffix = [0.0] * size
+        self._longest = [0.0] * size
+        self._all_free = [True] * size
+        self._build(1, 0, self._n)
+
+    def _build(self, node, lo, hi):
+        if hi - lo == 1:
+            length = self._lengths[lo]
+            self._total[node] = length
+            self._prefix[node] = length
+            self._suffix[node] = length
+            self._longest[node] = length
+            return
+        mid = (lo + hi) // 2
+        self._build(node * 2, lo, mid)
+        self._build(node * 2 + 1, mid, hi)
+        self._pull(node)
+
+    def _pull(self, node):
+        if self._cover[node]:
+            self._all_free[node] = False
+            self._prefix[node] = self._suffix[node] = self._longest[node] = 0.0
+            return
+        left, right = node * 2, node * 2 + 1
+        self._total[node] = self._total[left] + self._total[right]
+        self._all_free[node] = self._all_free[left] and self._all_free[right]
+        self._prefix[node] = self._prefix[left]
+        if self._all_free[left]:
+            self._prefix[node] += self._prefix[right]
+        self._suffix[node] = self._suffix[right]
+        if self._all_free[right]:
+            self._suffix[node] += self._suffix[left]
+        self._longest[node] = max(
+            self._longest[left],
+            self._suffix[left] + self._prefix[right],
+            self._longest[right],
+        )
+
+    @property
+    def longest(self):
+        return self._longest[1]
+
+    def block(self, lo, hi):
+        """Add one obstacle interval in coordinate space."""
+        first = bisect_left(self.coordinates, lo)
+        last = bisect_left(self.coordinates, hi)
+        if lo == hi:
+            unit_lo, unit_hi = 2 * first, 2 * first + 1
+        else:
+            # Block the open span but not its endpoints: touching an obstacle is
+            # permitted by the placement AABB predicate.
+            unit_lo, unit_hi = 2 * first + 1, 2 * last
+        self._block(1, 0, self._n, unit_lo, unit_hi)
+
+    def _block(self, node, lo, hi, block_lo, block_hi):
+        if block_lo <= lo and hi <= block_hi:
+            self._cover[node] += 1
+            self._pull(node)
+            return
+        mid = (lo + hi) // 2
+        if block_lo < mid:
+            self._block(node * 2, lo, mid, block_lo, block_hi)
+        if mid < block_hi:
+            self._block(node * 2 + 1, mid, hi, block_lo, block_hi)
+        self._pull(node)
+
+    def first_run(self, minimum):
+        """Lowest-Y free run at least *minimum* long."""
+        return self._first_run(1, 0, self._n, self.coordinates[0], minimum)
+
+    def _first_run(self, node, lo, hi, origin, minimum):
+        if hi - lo == 1:
+            return origin
+        left, right = node * 2, node * 2 + 1
+        mid = (lo + hi) // 2
+        if self._longest[left] >= minimum:
+            return self._first_run(left, lo, mid, origin, minimum)
+        if self._suffix[left] + self._prefix[right] >= minimum:
+            return origin + self._total[left] - self._suffix[left]
+        return self._first_run(
+            right,
+            mid,
+            hi,
+            origin + self._total[left],
+            minimum,
+        )
+
+
+def _largest_empty_rect(drawable, obstacles, *, target_size=None, warn: bool = True):
     """Largest axis-aligned empty rectangle in *drawable* avoiding *obstacles*.
 
     *drawable* and each obstacle are ``(x0, y0, x1, y1)`` page-mm boxes.  Returns
     the empty sub-rectangle of *drawable* (overlapping no obstacle) that maximises
-    the side of the largest square it can hold — i.e. ``min(width, height)`` — so
-    the (near-square) iso view can be scaled up as far as possible.
-
-    The obstacle set is tiny (front/plan/side views + title block), so a
-    gap-based search over candidate edges is both exact enough and cheap: every
-    maximal empty rectangle has edges drawn from the drawable bounds and the
-    obstacle bounds, so enumerating those cut lines finds the optimum.
+    the uniform scale of *target_size*. The default ``(1, 1)`` maximises the side
+    of the largest square it can hold, preserving the iso-view policy. A caller
+    placing a wide or tall fixed-aspect footprint can supply its minimum
+    ``(width, height)`` instead.
+
+    Every maximal empty rectangle has edges drawn from the drawable bounds and
+    the obstacle bounds.  Sweep candidate X strips while adding their blocking Y
+    intervals to a compressed-coordinate free-run index.  This is equivalent to
+    enumerating every pair of Y edges, without the quartic blow-up when a detail
+    view includes hundreds of decomposed annotation segments (#1065).
     """
+    target_w, target_h = target_size or (1.0, 1.0)
+    if not (math.isfinite(target_w) and target_w > 0 and math.isfinite(target_h) and target_h > 0):
+        raise ValueError("target_size must contain finite positive dimensions")
+
     dx0, dy0, dx1, dy1 = drawable
     xs = sorted({dx0, dx1, *(c for o in obstacles for c in (o[0], o[2]) if dx0 < c < dx1)})
     ys = sorted({dy0, dy1, *(c for o in obstacles for c in (o[1], o[3]) if dy0 < c < dy1)})
 
-    # The score is min(width, height), so any candidate whose width OR height is
-    # ``<= best_score`` cannot beat the best found so far. Because ``xs``/``ys`` are
-    # sorted and ``best_score`` only grows, we skip those candidates outright rather
-    # than enumerate-then-reject them: ``break`` the outer loop once even its widest
-    # candidate is too small, and ``bisect`` the inner loop's start past every pair
-    # narrower than ``best_score``. This is an exact prune — skipped candidates could
-    # never satisfy ``score > best_score`` — so the result (and its tie-breaking) is
-    # identical to the naive quadruple loop, but the detail-view caller (which passes
-    # every placed-annotation footprint, not just the handful of views) no longer
-    # triggers an O(N⁴) blow-up (#661).
+    events = []
+    for ox0, oy0, ox1, oy1 in obstacles:
+        block_lo = max(dy0, oy0)
+        block_hi = min(dy1, oy1)
+        if block_hi < dy0 or block_lo > dy1:
+            continue
+        events.append((ox0, ox1, block_lo, block_hi))
+    events.sort(key=lambda event: event[0])
+
+    # The score is min(width / target_w, height / target_h), so any candidate whose
+    # width or height cannot exceed the corresponding scaled target cannot beat the
+    # best found so far. This is the same exact prune as the square-default path,
+    # normalized by the requested footprint.
     best = None
     best_score = 0.0
-    nx, ny = len(xs), len(ys)
+    nx = len(xs)
     for i in range(nx - 1):
         rx0 = xs[i]
-        if xs[-1] - rx0 <= best_score:
+        if xs[-1] - rx0 <= best_score * target_w:
             break  # widest strip from here on can't beat best (rx0 only grows)
-        for j in range(bisect_right(xs, rx0 + best_score), nx):
+        free_y = _FreeRunIndex(ys)
+        event_index = 0
+        for j in range(bisect_right(xs, rx0 + best_score * target_w), nx):
             rx1 = xs[j]
             width = rx1 - rx0
-            # only obstacles overlapping the x-strip [rx0, rx1] can block it
-            strip = [(o[1], o[3]) for o in obstacles if o[0] < rx1 and rx0 < o[2]]
-            for k in range(ny - 1):
-                ry0 = ys[k]
-                if ys[-1] - ry0 <= best_score:
-                    break  # tallest gap from here can't beat best (ry0 only grows)
-                for m in range(bisect_right(ys, ry0 + best_score), ny):
-                    ry1 = ys[m]
-                    if any(ry0 < oy1 and oy0 < ry1 for (oy0, oy1) in strip):
-                        continue
-                    height = ry1 - ry0
-                    score = width if width < height else height
-                    if score > best_score:
-                        best_score = score
-                        best = (rx0, ry0, rx1, ry1)
+            while event_index < len(events) and events[event_index][0] < rx1:
+                _, ox1, block_lo, block_hi = events[event_index]
+                if rx0 < ox1:
+                    free_y.block(block_lo, block_hi)
+                event_index += 1
+
+            height = free_y.longest
+            score = min(width / target_w, height / target_h)
+            if score <= best_score:
+                continue
+
+            # If width caps the score, select the first global Y edge that makes
+            # the target fit.  Otherwise select the end of the first tallest gap.
+            # These are the same deterministic winners as the exhaustive search.
+            needed_height = min(width * target_h / target_w, height)
+            ry0 = free_y.first_run(needed_height)
+            edge = bisect_left(ys, ry0 + needed_height)
+            ry1 = ys[min(edge, len(ys) - 1)]
+            best_score = score
+            best = (rx0, ry0, rx1, ry1)
     if best is None:
         # No empty rectangle exists (obstacles cover the drawable area). This
         # is unreachable in practice — choose_scale always leaves a gap — but
@@ -819,6 +948,12 @@ class Analysis:
     """
 
     part: Shape
+    #: The ADR 0017 aggregate, or ``None`` on a DECLARED build — which recognises nothing
+    #: (ADR 0011 / #1022).  ``None`` means "not detected", never "detected and empty": a
+    #: consumer needing an inventory on that path must go through the lazy
+    #: ``Drawing._recognition()``, which builds one on demand rather than reading an absence
+    #: as an answer.
+    recognition: RecognitionResult | None
     bb: BoundBox
     x_size: float
     y_size: float
@@ -836,7 +971,7 @@ class Analysis:
     pads: list  # geometry-derived rectangular-pad coverage inventory (#885)
     z_diams: list[float]
     cross_diams: list[float]
-    cyls: tuple[list, list]
+    cyls: tuple[tuple, tuple]
     prof: TurnedProfile | None  # turned step profile (recognise_turned_steps), detected once
     od_diam: float | None
     is_rotational: bool

{draftwright-0.4.0 → draftwright-0.4.1}/src/draftwright/_geometry.py

@@ -12,6 +12,7 @@ drawing grab-bag (ADR 0008; #584 WP2). This module imports nothing from
 from __future__ import annotations
 
 import logging
+import math
 from dataclasses import dataclass
 
 from build123d import Compound
@@ -108,6 +109,102 @@ def _axis_letter_of(axis) -> str:
     return max(zip("xyz", axis, strict=True), key=lambda t: abs(t[1]))[0]
 
 
+def _axis_direction_components(axis: str, direction=None):
+    """Validate a direction and return ``(raw, norm, dominant_index)``."""
+    if axis not in "xyz" or len(axis) != 1:
+        raise ValueError("axis must be 'x', 'y', or 'z'")
+    if direction is None:
+        direction = tuple(1.0 if letter == axis else 0.0 for letter in "xyz")
+    try:
+        raw = tuple(float(component) for component in direction)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("axis_direction must be a 3-vector") from exc
+    if len(raw) != 3:
+        raise ValueError("axis_direction must be a 3-vector")
+    if not all(math.isfinite(component) for component in raw):
+        raise ValueError("axis_direction must contain only finite values")
+    norm = math.hypot(*raw)
+    if norm <= 1e-12:
+        raise ValueError("axis_direction must be non-zero")
+    idx = "xyz".index(axis)
+    if abs(raw[idx]) + norm * 1e-9 < max(abs(component) for component in raw):
+        raise ValueError(f"axis_direction's dominant component must match axis={axis!r}")
+    return raw, norm, idx
+
+
+def _normalised_axis_direction(axis: str, direction=None) -> tuple[float, float, float]:
+    """Full-precision unit direction used for geometric projection."""
+    raw, norm, idx = _axis_direction_components(axis, direction)
+    sign = -1.0 if raw[idx] < 0 else 1.0
+    return (
+        sign * raw[0] / norm,
+        sign * raw[1] / norm,
+        sign * raw[2] / norm,
+    )
+
+
+def _canonical_axis_direction(axis: str, direction=None) -> tuple[float, float, float]:
+    """Return a stable unit direction whose named dominant component is positive.
+
+    ``axis`` remains the orthographic routing hint used by the IR. ``direction`` is the
+    actual geometric axis needed to distinguish slanted stock lines; omitting it means the
+    corresponding principal axis. Six decimal places preserve direction while keeping
+    recognition/declaration identities stable across round trips.
+    """
+    raw, norm, idx = _axis_direction_components(axis, direction)
+    sign = -1.0 if raw[idx] < 0 else 1.0
+    # A previously canonical six-decimal vector is close enough to unit length that
+    # normalising it again can move the last digit. Preserve it to make emit -> declare
+    # idempotent; arbitrary vectors are still normalised on first entry.
+    unit = (
+        tuple(sign * component for component in raw)
+        if abs(norm - 1.0) <= 2e-6
+        else _normalised_axis_direction(axis, raw)
+    )
+    rounded = tuple(0.0 if abs(component) < 0.5e-6 else round(component, 6) for component in unit)
+    return (rounded[0], rounded[1], rounded[2])
+
+
+def _canonical_axis_span(axis: str, direction, span) -> tuple[float, float]:
+    """Express an axial extent along the canonical positive direction."""
+    raw, _norm, idx = _axis_direction_components(axis, direction)
+    lo, hi = (float(value) for value in span)
+    if raw[idx] < 0:
+        lo, hi = -hi, -lo
+    return (round(lo, 3), round(hi, 3))
+
+
+def _axis_line_coordinates(axis: str, point, direction=None) -> tuple[float, float]:
+    """Canonical in-plane coordinates of a 3-D axis line.
+
+    The perpendicular foot from the origin makes the result invariant to which point on the
+    line a geometry kernel reports. The named dominant coordinate is omitted; together with
+    the direction it is recoverable from the foot's perpendicularity, so two numbers retain
+    the aligned-stock representation while remaining sufficient for slanted stock.
+    """
+    px, py, pz = (float(component) for component in point)
+    # Use the unrounded unit vector here. Rounding before projection amplifies angular error
+    # into millimetres when the reported axis point is tens of metres from the origin.
+    vector = _normalised_axis_direction(axis, direction)
+    along = px * vector[0] + py * vector[1] + pz * vector[2]
+    foot = tuple(component - along * delta for component, delta in zip((px, py, pz), vector))
+    keep = [i for i, letter in enumerate("xyz") if letter != axis]
+    coordinates = tuple(round(foot[i], 3) for i in keep)
+    return (
+        0.0 if coordinates[0] == 0 else coordinates[0],
+        0.0 if coordinates[1] == 0 else coordinates[1],
+    )
+
+
+def _axis_direction_is_aligned(axis: str, direction, *, tol: float = 1e-3) -> bool:
+    """Whether a canonical direction follows the principal axis named by ``axis``."""
+    vector = _canonical_axis_direction(axis, direction)
+    idx = "xyz".index(axis)
+    return abs(vector[idx] - 1.0) <= tol and all(
+        abs(vector[j]) <= tol for j in range(3) if j != idx
+    )
+
+
 def _fmt(v: float) -> str:
     """Format a float as integer string if whole, otherwise 1 dp. The one number
     formatter the IR (:mod:`draftwright.model.ir`) and the drawing layers