b123d-recognisers 0.1.0__py3-none-any.whl

b123d_recognisers/__init__.py

@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2024-2026 Paul Fremantle
+"""Deterministic geometry-only feature recognition for build123d solids.
+
+This Apache-2.0 package is the single recognition implementation shared by consumers. Import the
+public surface from here, not the implementation submodules.
+
+Recogniser contract (ADR 0002)
+------------------------------
+A *feature* recogniser takes one of two shapes:
+
+- **Part-based** — ``recognise_<feature>(part, *, <tuning / injected deps>) -> list[record]``
+  (``recognise_holes(part, *, cyls=None)``, ``recognise_chamfers(part, *, tol=...)``,
+  ``recognise_risers(part, *, tol=...)``). Everything after ``part`` is
+  **keyword-only** — both tuning and any injected inventory. A recogniser **never
+  re-recognises a dependency internally**; the orchestration caller owns the single inventory
+  and threads it.
+- **Derived** — ``recognise_<feature>(inventory) -> list[record]``
+  (``recognise_hole_patterns(holes)``):
+  operates purely on another recogniser's records, no ``part`` and no tuning, so the
+  single inventory arg is unambiguous and stays positional.
+
+Common to both: a **British** ``recognise_`` verb (not ``find_``/``analyse_``); a
+**deterministic ``list`` of frozen-dataclass records** (empty when absent — never
+``Optional``-singular, never a bare ``list`` of primitives); **geometry-only records** (no
+build123d types leak out; consumers adapt these values into their own domain models).
+
+The contract holds for **every** recogniser, including the two that once strained it —
+their records were simply the wrong shape (#568):
+
+- ``recognise_face_levels -> list[FaceLevel]`` (was ``list[float]``) — a level is now a
+  ``FaceLevel(z)`` record.
+- ``recognise_turned_steps -> list[TurnedStep]`` (was ``TurnedProfile | None``) — each
+  ``TurnedStep`` now carries its ``axis``, so it is a self-contained record and the old
+  ``TurnedProfile`` wrapper is no longer the return. ``TurnedProfile`` survives only as a
+  **pipeline aggregate** (``TurnedProfile.from_steps``) for consumers that want axis +
+  shoulders as a unit — it is not a recogniser return.
+
+Record class names avoid consumer-domain ``Feature`` types: for example, the public records are
+``HoleRecord`` and ``BossRecord`` rather than drawing or manufacturing IR types.
+
+``analyse_cylinders`` / ``full_cylinders`` / ``feature_diameters`` are **not** recognisers
+under this contract — they are cylinder-analysis *substrate* (a tuple of dicts / a diameter
+query), and deliberately keep their names. Likewise the **shared single-face reads**
+(``classify_bevel``/``BevelReject``, ``fillet_anchor``, ``cone_rims``,
+``floor_face_anchor``, ``step_level_zs``, #704): helpers shared with the declared
+front-end, not recognisers — they traffic in build123d/OCP objects and are exposed only where
+existing Draftwright compatibility requires them.
+
+``project_step_shoulders`` is likewise not a recogniser but its mirror image: a **pure
+projection** over :func:`recognise_risers`' records, with no ``part`` and no geometry access
+at all. It carries the ``project_`` verb rather than ``recognise_`` because the aggregate owns
+the evidence and each consumer projects. A function that cannot look at a solid cannot become a
+second recognition site.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from b123d_recognisers._features import (
+    BoltCircle,
+    BossRecord,
+    CounterBore,
+    HoleRecord,
+    HoleSpec,
+    LinearArray,
+    RectGrid,
+    analyse_cylinders,
+    feature_diameters,
+    full_cylinders,
+    recognise_bosses,
+    recognise_hole_patterns,
+    recognise_holes,
+)
+from b123d_recognisers.chamfers import (
+    BevelReject,
+    Chamfer,
+    classify_bevel,
+    recognise_chamfers,
+)
+from b123d_recognisers.countersinks import (
+    CounterSink,
+    cone_rims,
+    countersink_matches_hole,
+    recognise_countersinks,
+)
+from b123d_recognisers.fillets import Fillet, fillet_anchor, recognise_fillets
+from b123d_recognisers.flats import Flat, recognise_flats
+from b123d_recognisers.grooves import Groove, floor_face_anchor, recognise_grooves
+from b123d_recognisers.levels import (
+    FaceLevel,
+    RiserEvidence,
+    StepShoulder,
+    project_step_shoulders,
+    recognise_face_levels,
+    recognise_risers,
+    step_level_records,
+    step_level_zs,
+)
+from b123d_recognisers.pads import RaisedPad, recognise_rectangular_pads
+from b123d_recognisers.plates import Plate, has_multi_axis_plates, recognise_plates
+from b123d_recognisers.polygonal_bosses import (
+    PolygonalBoss,
+    PolygonalStock,
+    recognise_polygonal_bosses,
+    recognise_polygonal_stock,
+)
+from b123d_recognisers.profiled_bores import DoubleDBore, recognise_double_d_bores
+from b123d_recognisers.repeating_profiles import (
+    RepeatingRadialProfile,
+    recognise_repeating_radial_profiles,
+)
+from b123d_recognisers.result import RecognitionResult, build_recognition_result
+from b123d_recognisers.slots import (
+    Channel,
+    Pocket,
+    PocketArray,
+    PocketGrid,
+    Slot,
+    SlotArray,
+    SlotGrid,
+    recognise_channels,
+    recognise_pocket_patterns,
+    recognise_pockets,
+    recognise_slot_patterns,
+    recognise_slots,
+)
+from b123d_recognisers.turned import TurnedProfile, TurnedStep, recognise_turned_steps
+
+try:
+    __version__ = version("b123d-recognisers")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+# Imported after the recognition surface because census consumes that public orchestration.
+from b123d_recognisers.census import feature_census  # noqa: E402
+
+__all__ = [
+    "__version__",
+    "BoltCircle",
+    "Chamfer",
+    "Channel",
+    "Fillet",
+    "Flat",
+    "Groove",
+    "BossRecord",
+    "CounterBore",
+    "CounterSink",
+    "countersink_matches_hole",
+    "DoubleDBore",
+    "FaceLevel",
+    "HoleRecord",
+    "HoleSpec",
+    "LinearArray",
+    "Plate",
+    "Pocket",
+    "PocketArray",
+    "PocketGrid",
+    "PolygonalBoss",
+    "PolygonalStock",
+    "RaisedPad",
+    "RepeatingRadialProfile",
+    "RectGrid",
+    "Slot",
+    "SlotArray",
+    "SlotGrid",
+    "RiserEvidence",
+    "StepShoulder",
+    "TurnedProfile",
+    "TurnedStep",
+    "RecognitionResult",
+    "BevelReject",
+    "analyse_cylinders",
+    "classify_bevel",
+    "cone_rims",
+    "fillet_anchor",
+    "floor_face_anchor",
+    "has_multi_axis_plates",
+    "project_step_shoulders",
+    "recognise_face_levels",
+    "recognise_risers",
+    "step_level_records",
+    "step_level_zs",
+    "feature_diameters",
+    "feature_census",
+    "recognise_bosses",
+    "recognise_chamfers",
+    "recognise_channels",
+    "recognise_fillets",
+    "recognise_flats",
+    "recognise_grooves",
+    "recognise_countersinks",
+    "recognise_double_d_bores",
+    "recognise_hole_patterns",
+    "recognise_holes",
+    "recognise_plates",
+    "recognise_pocket_patterns",
+    "recognise_pockets",
+    "recognise_polygonal_bosses",
+    "recognise_polygonal_stock",
+    "recognise_rectangular_pads",
+    "recognise_repeating_radial_profiles",
+    "recognise_slot_patterns",
+    "recognise_slots",
+    "recognise_turned_steps",
+    "build_recognition_result",
+    "full_cylinders",
+]