draftwright 0.4.34__tar.gz → 0.5.0rc1__tar.gz

{draftwright-0.4.34 → draftwright-0.5.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: draftwright
-Version: 0.4.34
+Version: 0.5.0rc1
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -954,6 +954,31 @@ build_drawing(part, scale=1.0, page="A4", scale_policy="strict")
 build_drawing(part, scale=1.0, page="A4", scale_policy="permissive")
 ```
 
+### Choose an annotation planning algorithm
+
+```python
+dwg = build_drawing(part, annotation_layout="estimated-strips")  # original planning
+dwg = build_drawing(part, annotation_layout="demand-guided")    # current one-build default
+dwg = build_drawing(part, annotation_layout="compare")          # multi-build comparison
+print(dwg.annotation_scheme_decision)  # selected trial and finished-drawing evidence
+```
+
+Both planning algorithms use the same annotation placement solver. `estimated-strips`
+reserves annotation corridors from feature-based estimates; `demand-guided` uses typed
+annotation demand to choose a planning profile before rendering. The current default
+is `demand-guided`; `estimated-strips` remains an explicit compatibility choice.
+
+`compare` builds the estimated-strips layout first, then tries a bounded alternative on
+the **same sheet and scale**. It selects an alternative only when rendered annotation
+meaning and required coverage are preserved, no new required blocker appears, and
+the finished drawing has fewer layout defects or a substantially larger isometric
+view on an otherwise clean sheet. `Sheet`, `make_drawing()`, generated scripts, and the
+CLI (for example `--annotation-layout demand-guided`) accept the same names. The
+former spellings `baseline`, `candidate-preview`, and `best` remain accepted aliases.
+
+The comparison costs at least two drawing builds and may try up to three candidate
+variants for a crowded part. Export runs only for the selected drawing.
+
 ### Edit, critique, and self-repair
 
 Edit a `Drawing` in **domain vocabulary** — the engine places annotations

{draftwright-0.4.34 → draftwright-0.5.0rc1}/README.md

@@ -251,6 +251,31 @@ build_drawing(part, scale=1.0, page="A4", scale_policy="strict")
 build_drawing(part, scale=1.0, page="A4", scale_policy="permissive")
 ```
 
+### Choose an annotation planning algorithm
+
+```python
+dwg = build_drawing(part, annotation_layout="estimated-strips")  # original planning
+dwg = build_drawing(part, annotation_layout="demand-guided")    # current one-build default
+dwg = build_drawing(part, annotation_layout="compare")          # multi-build comparison
+print(dwg.annotation_scheme_decision)  # selected trial and finished-drawing evidence
+```
+
+Both planning algorithms use the same annotation placement solver. `estimated-strips`
+reserves annotation corridors from feature-based estimates; `demand-guided` uses typed
+annotation demand to choose a planning profile before rendering. The current default
+is `demand-guided`; `estimated-strips` remains an explicit compatibility choice.
+
+`compare` builds the estimated-strips layout first, then tries a bounded alternative on
+the **same sheet and scale**. It selects an alternative only when rendered annotation
+meaning and required coverage are preserved, no new required blocker appears, and
+the finished drawing has fewer layout defects or a substantially larger isometric
+view on an otherwise clean sheet. `Sheet`, `make_drawing()`, generated scripts, and the
+CLI (for example `--annotation-layout demand-guided`) accept the same names. The
+former spellings `baseline`, `candidate-preview`, and `best` remain accepted aliases.
+
+The comparison costs at least two drawing builds and may try up to three candidate
+variants for a crowded part. Export runs only for the selected drawing.
+
 ### Edit, critique, and self-repair
 
 Edit a `Drawing` in **domain vocabulary** — the engine places annotations

{draftwright-0.4.34 → draftwright-0.5.0rc1}/docs/reference/sheet.md

@@ -127,6 +127,14 @@ solve still measures the whole notes block and checks all occupied regions. If i
 page; do not remove engineering content merely to silence a diagnostic. General notes remain
 uncredited text: they do not automatically satisfy missing dimensions or unsupported features.
 
+Page selection also measures visible imported general notes before choosing a sheet. Derived
+sections and details claim their less-flexible space first; notes and tables take remaining
+regions. The late block placer prefers 6 mm of separation but retries the existing minimum
+ink clearance when necessary. An automatic section likewise prefers a wider gap from its
+parent row, and an unreserved detail prefers space around its complete footprint only when
+that keeps its requested scale. These are readability preferences, not permission to shrink,
+omit, or overlap required content.
+
 ### Dimension position and reading direction
 
 Position and reading direction are independent drawing-wide settings:
@@ -176,6 +184,41 @@ retains a non-default selection in its `Sheet(...)` constructor. A feature carry
 stronger than the drawing-wide preference. The policy affects feature leaders only—not linear
 dimensions, free notes, tables, or view placement—and never supplies coordinates.
 
+The `demand-guided` annotation layout additionally reserves a blank 6 mm gutter
+between the front/plan annotation bands and between the column and side view,
+growing toward 12 mm when the selected sheet has spare room. Its facing strips
+cannot spend that gutter. `estimated-strips` retains its established shared
+corridors; this change does not silently alter that layout's sheet selection.
+
+For separate linear hole patterns whose pitch marks have the same projected
+stations and printed value in one view, the renderer keeps one dimension rather
+than repeating the same pitch beside parallel rows. That mark retains the
+measurement identities and feature ownership of every covered pattern. Rotated
+or nonmatching rows remain separate; an unplaced pitch is still reported rather
+than silently treated as covered.
+
+### Acceptable recovered leaders
+
+A sheet-wide recovery is a last resort, not permission to send a callout around the
+page. Draftwright accepts a recovered feature leader only when:
+
+- its tip remains attached to the proved feature in its owning view;
+- its label stays on the sheet and outside projected views and settled
+  annotation text;
+- its shaft stays out of other views and does not cross settled annotation text
+  or non-crossable strokes; ordinary dimension-line crossings retain the
+  existing documented crossing policy;
+- it has at most one routing bend before the normal label shelf, never doubles
+  back, and stays local (each leg no longer than the owning view's diagonal, the
+  complete route no longer than twice that diagonal; a 30 mm floor keeps very
+  small views usable).
+
+If no candidate passes, the callout drops with a lint finding. The length and
+bend limits are Draftwright readability rules, **not** ISO- or ASME-prescribed
+numbers. They prevent a callout such as CTC04's 4×R13 from taking a long U-shaped
+detour into the next view. Ordinary feature leaders are still solved jointly;
+these additional limits govern the sheet-wide recovery path.
+
 ## Through-hole wording
 
 The optional argument to a hole handle's `through()` controls its printed indicator:
@@ -215,6 +258,21 @@ measurement should also appear beside a view. Ordinary `table(...)` text has no
 authority. See [shared drawing documents](document.md#feature-schedules) for an executable
 recipe, verified cell evidence and the document report contract.
 
+For an automatic `pmi="annotate"` drawing with multiple long imported thread/knurl
+requirements, the engine may instead place a **manufacturing requirements** table.
+The diameter or hole callout keeps its canonical size and a short `SEE MFG n` reference;
+the table carries the complete source-owned manufacturing terms. Its measured footprint
+participates in page selection, and the references are used only after the table fits.
+If it cannot be placed, full direct callouts remain. Lint reports a short reference whose
+source-matched table row is removed or altered. This does not apply to `pmi="off"` or
+replace an authored feature schedule.
+
+An imported datum-scheme sentence is omitted from the sheet only when its whole
+meaning is proven by placed, source-owned datum symbols on the matching geometry.
+The original AP242 text and the symbol source IDs remain in the model. A missing
+symbol, unmatched geometry, or extra instruction keeps the note (or produces a
+source-coverage lint error if a previously proven symbol is later removed).
+
 ## Grooves on coaxial bodies
 
 When different turned bodies share an axis line, give their steps distinct `profile_group`

{draftwright-0.4.34 → draftwright-0.5.0rc1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.4.34"
+version = "0.5.0rc1"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -184,6 +184,8 @@ dev = [
     "pytest-split>=0.8",
     "pytest-timeout>=2",
     "pytest-xdist>=3",
+    # Offline layout-cost workers need peak working-set and host RAM on Windows.
+    "psutil>=5.9",
     "ruff>=0.4",
     "tomli>=2; python_version < '3.11'",
 ]

{draftwright-0.4.34 → draftwright-0.5.0rc1}/src/draftwright/_core.py

@@ -407,7 +407,7 @@ def _table_metrics(rows, font_size, pad_around_text, block_cols=None):
     return lefts, rights, cursor, row_h * len(rows), row_h, bc
 
 
-def _build_table(rows, draft, block_cols=None):
+def _build_table(rows, draft, block_cols=None, left_align_cols=()):
     """Build a generic data-table annotation at the origin (bottom-left ``(0, 0)``).
 
     *rows* is a list of equal-length string tuples; ``rows[0]`` is the header,
@@ -443,12 +443,15 @@ def _build_table(rows, draft, block_cols=None):
             display = _font_safe_text(cell)
             if not display:
                 continue
-            cx = (lefts[ci] + rights[ci]) / 2
+            left_aligned = ci in left_align_cols
+            cx = (
+                lefts[ci] + draft.pad_around_text if left_aligned else (lefts[ci] + rights[ci]) / 2
+            )
             text = Text(
                 txt=display,
                 font_size=fs,
                 font_path=PLEX_MONO,
-                align=(Align.CENTER, Align.CENTER),
+                align=(Align.MIN if left_aligned else Align.CENTER, Align.CENTER),
                 mode=Mode.PRIVATE,
             ).locate(Location((cx, cy, 0)))
             children.extend(text.faces())
@@ -550,6 +553,37 @@ def _text_size(
     return (bb.size.X, bb.size.Y)
 
 
+_LONG_CALLOUT_LINE_MM = 48.0
+
+
+def _wrap_callout_text(
+    text: str, font_size: float, *, max_width: float = _LONG_CALLOUT_LINE_MM
+) -> str:
+    """Break a long manufacturing sentence into measured, intact words.
+
+    This is one typography policy for both compose-time width reservation and
+    rendered leaders. Short labels are unchanged. A single overlong word stays
+    intact, so the planner cannot pretend it will fit by clipping it.
+    """
+    if not text or _text_width(text, font_size) <= max_width:
+        return text
+    lines: list[str] = []
+    line = ""
+    for word in text.split():
+        candidate = f"{line} {word}" if line else word
+        if line and _text_width(candidate, font_size) > max_width:
+            lines.append(line)
+            line = word
+        else:
+            line = candidate
+        if line.endswith(";") and _text_width(line, font_size) >= max_width * 0.5:
+            lines.append(line)
+            line = ""
+    if line:
+        lines.append(line)
+    return "\n".join(lines)
+
+
 @functools.lru_cache(maxsize=32)
 def _text_line_spacing_em(
     font_size: float,
@@ -1043,9 +1077,9 @@ class DetailRequest:
                       :class:`ViewCoordinates`, mapped via ``coords.pp``) and returns the count
                       placed (0 → the detailer drops the detail without committing a view, #840).
                       Called on the SCRATCH-projected coords before the view is committed, so a
-                      zero result needs no rollback; the main view always carries the located
-                      head/block inline regardless, so a placement failure loses no coverage
-                      (lint reports the un-located interior instead).
+                      zero result needs no rollback; the main view may carry only a synthetic
+                      head/block, so the resolver must report any exact detail-owned
+                      measurements that cannot be placed.
         pad_top:      page-mm band reserved above the detail view (a horizontal
                       chain); reserved in the fit + placement.
         pads:         optional ``pads(detail_scale) -> (pad_right, pad_top)`` for a
@@ -1064,6 +1098,10 @@ class DetailRequest:
         kind:         short label for logging.
         measurement_ids/measurement_spans: exact compiler-owned requirements the detail
                       is recovering. Empty for purely geometric/authored details.
+        profile_support_points: model-space points on required visible geometry that
+                      an automatic secondary crop must retain. Turned shoulders use
+                      outer-profile edges; prismatic steps use physical face witness
+                      sites. These certify geometry, not dimension extension endpoints.
     """
 
     axis: str
@@ -1092,6 +1130,126 @@ class DetailRequest:
     source: object | None = None
     measurement_ids: tuple = ()
     measurement_spans: tuple = ()
+    profile_support_points: tuple[tuple[float, float, float], ...] = ()
+    #: Render-time refusal retained so the owner can report the real constraint,
+    #: rather than mislabelling an invalid crop as a page-fit failure.
+    failure_reason: str | None = None
+    failure_code: str | None = None
+    placed_scale: float | None = None
+    fit_evidence: dict[str, object] | None = None
+
+
+def _detail_caption(req: DetailRequest, letter: str, scale: float, bb) -> str:
+    """Identify a genuinely truncated profile independently of detail family."""
+    partial_profile = False
+    if req.cross_axis is not None and req.cross_lo is not None and req.cross_hi is not None:
+        axis = req.cross_axis.upper()
+        partial_profile = (
+            req.cross_lo > getattr(bb.min, axis) + 1e-6
+            or req.cross_hi < getattr(bb.max, axis) - 1e-6
+        )
+    qualifier = " — PARTIAL PROFILE" if partial_profile else ""
+    return f"DETAIL {letter}{qualifier} — SCALE {format_drawing_scale(scale)}"
+
+
+def y_chain_detail_scale_needed(
+    segments: tuple[tuple[float, float, float], ...],
+    label_widths: tuple[float, ...],
+    *,
+    arrow_length: float,
+    text_padding: float,
+) -> float | None:
+    """Return the minimum enlargement for an unreadable Y-turned step chain.
+
+    Segment endpoints are projected page X coordinates; their third value is the
+    approved world-space step length. ``None`` means the principal-view chain
+    already has room for every label and both inside arrows. The same pure rule
+    can be consumed by pre-sheet planning and the render pass (#1872).
+    """
+
+    if len(segments) != len(label_widths):
+        raise ValueError("Y-chain segments and label widths must correspond")
+    if not segments:
+        return None
+    centres = sorted(
+        ((pa + pb) / 2, width) for (pa, pb, _length), width in zip(segments, label_widths)
+    )
+    labels_clear = all(
+        next_centre - centre >= (width + next_width) / 2 + text_padding
+        for (centre, width), (next_centre, next_width) in zip(centres, centres[1:])
+    )
+    inside_arrows_fit = all(
+        abs(pb - pa) >= width + 2 * arrow_length + 2 * text_padding
+        for (pa, pb, _length), width in zip(segments, label_widths)
+    )
+    if labels_clear and inside_arrows_fit:
+        return None
+    return max(
+        (width + 2 * arrow_length + 2 * text_padding) / length
+        for (_pa, _pb, length), width in zip(segments, label_widths)
+        if length > 0
+    )
+
+
+def crowded_horizontal_step_runs(
+    spans: tuple[tuple[float, float], ...], scale: float, arrow_length: float
+) -> tuple[tuple[int, ...], ...]:
+    """Runs of at least two consecutive steps narrower than two page arrowheads.
+
+    The semantic pre-sheet planner and X-turned renderer must identify the same
+    head requirements; neither may invent a different crowded-step threshold.
+    """
+    short = [
+        index for index, (lo, hi) in enumerate(spans) if abs(hi - lo) * scale < 2 * arrow_length
+    ]
+    runs: list[list[int]] = []
+    for index in short:
+        if runs and index == runs[-1][-1] + 1:
+            runs[-1].append(index)
+        else:
+            runs.append([index])
+    return tuple(tuple(run) for run in runs if len(run) >= 2)
+
+
+_DETAIL_PROFILE_CONTEXT_PAGE_MM = 2.0  # Draftwright policy, not a drafting-standard minimum.
+_DETAIL_PROFILE_MIN_WORLD_MM = 0.1  # Keep the Boolean crop wider than OCC's fuzzy edge.
+
+
+def supported_secondary_crop(
+    points: tuple[tuple[float, float, float], ...],
+    axis: Literal["x", "y", "z"],
+    full_lo: float,
+    full_hi: float,
+    detail_scale: float,
+) -> tuple[float, float] | None:
+    """Smallest supported band with page context where the body extent permits.
+
+    The caller must provide every controlled physical support point. Missing or
+    invalid evidence refuses the partial crop, leaving the full profile visible.
+    The bounded page-space margin is shared by turned, prismatic, and authored
+    details; no feature-family radius or fixed world-space threshold is needed.
+    """
+    if (
+        not points
+        or not math.isfinite(full_lo)
+        or not math.isfinite(full_hi)
+        or full_lo >= full_hi
+        or not math.isfinite(detail_scale)
+        or detail_scale <= 0
+    ):
+        return None
+    index = "xyz".index(axis)
+    if any(
+        len(point) != 3 or any(not math.isfinite(value) for value in point) for point in points
+    ):
+        return None
+    stations = [point[index] for point in points]
+    if min(stations) < full_lo - 1e-6 or max(stations) > full_hi + 1e-6:
+        return None
+    context = max(_DETAIL_PROFILE_MIN_WORLD_MM, _DETAIL_PROFILE_CONTEXT_PAGE_MM / detail_scale)
+    lo = max(full_lo, min(stations) - context)
+    hi = min(full_hi, max(stations) + context)
+    return (lo, hi) if lo < hi else None
 
 
 @dataclass(frozen=True)
@@ -1371,6 +1529,9 @@ class Analysis:
     # from the effective mode so the ignored-PMI diagnostic can distinguish that default from
     # an explicit opt-out without widening the three-mode renderer contract (#623).
     pmi_defaulted: bool
+    # Planned alternate carrier for multiple long imported manufacturing terms.
+    # The renderer activates its short feature references only after this table fits.
+    manufacturing_schedule: object | None = None
     # True when this layout is a member projection of a Document's sealed acquisition.
     document_member: bool = False
     # Exact top-level annotation objects supplied by the Document acquisition. Member-authored
@@ -1441,6 +1602,9 @@ class Analysis:
     planned_iso: bool = True
     #: ``None`` lets the orientation iso auto-fit; a number is an authored exact factor.
     planned_iso_scale: float | None = None
+    #: Distinguishes a caller's exact factor from an engine-selected NTS starting factor.
+    #: Only the former is a hard constraint that settlement must never reduce.
+    planned_iso_scale_authored: bool = False
     #: Immutable ADR 2 (was 0018) authored input, retained for the resolver/diagnostics without making
     #: this low-level module depend on the view-planning leaf at runtime.
     view_constraints: object | None = None
@@ -1456,6 +1620,9 @@ class Analysis:
     RV_X: float = 0.0
     RV_Y: float = 0.0
     rv_zones: ViewZones | None = None
+    #: Planned hard page boxes for required derived views, carried from composition
+    #: to annotation placement. Empty until a supported pre-sheet demand exists.
+    derived_view_boxes: tuple[tuple[str, tuple[float, float, float, float]], ...] = ()
 
     sheet_margins: SheetMargins | None = None
     content_margins: SheetMargins | None = None
@@ -1699,7 +1866,7 @@ def _add_title_block(dwg, a: Analysis):
         dwg.items,
         tb,
         "title_block",
-        feature=dwg._build.general_tolerance_source,
+        feature=dwg.general_tolerance_source,
     )
 
 
@@ -1785,7 +1952,7 @@ def _add_default_surface_finish(dwg, a: Analysis):
     The reserved band above the title block is sheet furniture space.  A document default
     belongs there: hanging it from model geometry would falsely narrow its scope to one face.
     """
-    requirement = dwg._build.default_surface_finish_source
+    requirement = dwg.default_surface_finish_source
     if requirement is None:
         return