b123d-recognisers

Recover useful engineering features from imported STEP and boundary-representation (B-Rep) geometry.

A STEP file normally gives a CAD application faces, edges, and solids, but not the design intent that produced them. b123d-recognisers analyses that topology and returns deterministic semantic records for features such as holes and counterbores, bosses, slots, pockets, pads, fillets, chamfers, grooves, hole and pocket patterns, and turned steps. The records contain ordinary, JSON-serialisable geometry values rather than build123d or OCP objects.

Recognition classifies faces by analytic surface type, so imported geometry must arrive with its planes, cylinders and cones intact. STEP carries them, and every pinned fixture is proven to survive an export and re-import unchanged. Geometry delivered entirely as B-splines is outside the proven domain; see docs/capabilities.md.

That makes the library a useful foundation for systems which inspect, classify, annotate, compare, or modify imported CAD. For example, a STEP editor can recognise a hole, present its diameter and axis as editable intent, and use those values to drive its own topology-editing operation. The recognisers recover evidence; the consuming CAD system decides what that evidence means and how an edit should be performed.

The package is Apache-2.0 licensed and independent of any drawing or editing application. It uses build123d/OCP internally as its B-Rep kernel, but its purpose is recovering meaning from geometry whose construction history is not available.

Recognise an imported model

Import a STEP file with build123d, then run the shared recognition orchestration to obtain one consistent feature inventory:

from build123d import import_step
from b123d_recognisers import build_recognition_result

part = import_step("gearbox-housing.step")
result = build_recognition_result(part)

for hole in result.holes:
    print(hole.location, hole.axis, hole.diameter, hole.depth, hole.bottom)

build_recognition_result() shares intermediate geometric analysis across recognisers and is the usual entry point for a CAD application. Its frozen result can be inspected directly or projected to JSON-compatible dictionaries for storage, indexing, comparison, or an editing pipeline.

Individual recognisers are also public when an application needs a narrower answer. Reusable evidence can be injected explicitly so it is not rediscovered:

from b123d_recognisers import analyse_cylinders, recognise_hole_patterns, recognise_holes

cylinders = analyse_cylinders(part)
holes = recognise_holes(part, cyls=cylinders)
patterns = recognise_hole_patterns(holes)

Every recognise_* function returns a deterministic list of frozen dataclass records. Records provide to_dict() projections containing only JSON-serialisable geometry values. The installed package also exposes a versioned capability manifest so larger CAD systems can validate which recognisers and record schemas they consume. See docs/capabilities.md for the proven feature inventory and docs/adr/0002-uniform-deterministic-recogniser-contract.md for the complete contract.

Project an aggregate step ladder

The aggregate owns the one geometry-only rule that chooses between Z-turned shoulders and already filtered prismatic levels. Pass only the Z envelope it needs; no build123d object crosses this projection boundary:

z_min = part.bounding_box().min.Z
z_max = part.bounding_box().max.Z
step_zs = result.step_ladder_for_z_span(z_min, z_max)

The default boundary_margin=0.6 is measured in model length units (normally millimetres) and strictly excludes turned end faces at both ends. It can be overridden explicitly. The former result.step_ladder(bound_box) call remains as a deprecated 0.2.x compatibility shim and will be removed no earlier than 1.0.0. See ADR 0006 for the caller inventory and boundary decision.

Scope

Feature recognition is deliberately separate from feature editing. This package reports geometric facts; it does not mutate the source model, guess manufacturing intent, or prescribe a downstream CAD representation. That boundary lets an editor, drawing engine, CAM tool, model checker, or search/indexing service adopt the same recognition layer while retaining its own policy.

b123d-recognisers began as the recognition layer of Draftwright, but the runtime package does not import Draftwright and is designed for standalone use.

Migrated behavior

The initial 0.1 release series preserves the recognition behavior of Draftwright commit 3fe20b0f71a71deced06b310943dd44cc66e355e. The migration includes every public recogniser, shared cylinder/level substrates, the aggregate result, and feature_census. There are no feature policy changes; one previously platform-dependent numerical axis tie is normalized to the pinned baseline result. The checked-in semantic corpus records and continuously verifies the compatibility boundary; see migration/PARITY.md.

The dependency direction is:

consumer → b123d-recognisers → build123d/OCP

The runtime package does not import Draftwright and does not return build123d or OCP objects in public feature records.

Maintainers: see the release guide for the TestPyPI-first, OIDC-only publication process.

Licence

Apache License 2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.