Metadata-Version: 2.5
Name: b123d-recognisers
Version: 0.3.1
Summary: Deterministic, geometry-only feature recognition for build123d solids
Project-URL: Repository, https://github.com/pzfreo/b123d-recognisers
Project-URL: Issues, https://github.com/pzfreo/b123d-recognisers/issues
Author-email: Paul Fremantle <pzfreo@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
License-File: THIRD_PARTY_NOTICES.md
Keywords: brep,build123d,cad,feature-recognition,step
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.15,>=3.10
Requires-Dist: build123d<0.12,>=0.9
Description-Content-Type: text/markdown

# b123d-recognisers

[![CI](https://github.com/pzfreo/b123d-recognisers/actions/workflows/ci.yml/badge.svg)](https://github.com/pzfreo/b123d-recognisers/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/pzfreo/b123d-recognisers/graph/badge.svg)](https://codecov.io/gh/pzfreo/b123d-recognisers)
[![PyPI](https://img.shields.io/pypi/v/b123d-recognisers.svg)](https://pypi.org/project/b123d-recognisers/)
[![Python versions](https://img.shields.io/pypi/pyversions/b123d-recognisers.svg)](https://pypi.org/project/b123d-recognisers/)
[![License](https://img.shields.io/pypi/l/b123d-recognisers.svg)](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)
[![mypy](https://img.shields.io/badge/mypy-checked-2A6DB2.svg)](https://mypy-lang.org/)

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`](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:

```python
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:

```python
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`](docs/capabilities.md) for the proven feature inventory and
[`docs/adr/0002-uniform-deterministic-recogniser-contract.md`](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:

```python
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`](docs/adr/0006-explicit-step-ladder-z-span.md) 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](https://github.com/pzfreo/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`](migration/PARITY.md).

The dependency direction is:

```text
consumer → b123d-recognisers → build123d/OCP
```

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

Contributors: see [Adding a recogniser](docs/adding-a-recogniser.md) for the AAG predicate,
candidate/evidence, registry, reconciliation, and verification path.

Maintainers: see [the release guide](docs/releasing.md) for the TestPyPI-first, OIDC-only
publication process.

## Licence

Apache License 2.0. See [`LICENSE`](LICENSE), [`NOTICE`](NOTICE), and
[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
