# n3xd-ocp

Hand-written [nanobind](https://github.com/wjakob/nanobind) bindings for the
OpenCASCADE (OCCT) geometry kernel, covering exactly the surface the N3XD CAD
backend uses — 139 symbols across 48 `OCP.*` modules, not all of OCCT.

The package installs as a top-level `OCP`, so it is a drop-in replacement for
`cadquery-ocp-novtk` and the app's 442 import sites stay untouched.

Status: **Inc 0 (spike) shipped** — build system, OCCT builder image, handle
model, and the first module surface (`gp`, `TopAbs`, `TopoDS`, `TopExp`,
`TopLoc`, `TopTools`, `BRep`, `BinTools`, `Poly`, `Standard`), published as
`7.9.3.1.dev1`. BREP serialisation is byte-identical to the stock wheel, which
is the gate that mattered: the pools and the content-addressed derive payloads
both depend on it. Coverage is 34 of the 139 symbols the app imports; the rest
lands in increments 1-4 (roadmap 10C).

Start with [docs/design.md](docs/design.md) for the decisions,
[docs/building.md](docs/building.md) to build one, and
[docs/adding-symbols.md](docs/adding-symbols.md) to extend the surface. The
phase plan lives in the app repo at `docs-private/reference/roadmap.md`
(Phase 10).

## Why

`cadquery-ocp` lags OCCT (it wraps 7.9.3; OCCT 8.0 shipped 2026-05), builds
Windows and macOS wheels we never use, and until recently forced a 638 MB VTK
dependency into the image. Binding *call* overhead is not a bottleneck — the
CAD hotspots live inside the C++ kernel — so this exists for version velocity,
footprint, and two defects that a binding we control prevents by construction:

- OCCT sub-shapes are returned **by value**, so a wrapper can never alias a
  `TShape` whose owner has died (this segfaulted a process-global face memo).
- Executing constructors (the two-argument `BRepAlgoAPI_*` forms) are **not
  bound**, so the double-execution footgun is unrepresentable.

It also releases the GIL around kernel calls and ships type stubs, neither of
which upstream does.

## Build

OCCT is compiled once into a builder image and reused; it is never built on the
production host (4 cores, and a kernel build is multi-hour). Wheels are built
here on a dev box and published to the Gitea package registry.

```bash
make image    # once, ~40 min: compiles OCCT 7.9.3 into the builder image
make dev      # inner loop: incremental compile + tests
make wheel    # compile, stubs, auditwheel, self-containment smoke test
make publish  # -> https://git.stroblme.de/api/packages/N3XD/pypi
```

Credentials go in `.secrets` (gitignored) as `UV_PUBLISH_USERNAME` /
`UV_PUBLISH_PASSWORD`. Consumers read anonymously — the package is public:

```bash
uv pip install --index-url https://git.stroblme.de/api/packages/N3XD/pypi/simple/ \
    --prerelease=allow n3xd-ocp
```

Versions are `<occt-version>.N`, enforced at configure time against the OCCT
actually found, so the kernel a wheel wraps is readable from its version alone.
The registry refuses to republish a version; iteration builds therefore carry a
`.devN` suffix and are the only ones the registry's cleanup rule collects.