369
docs/design.md
369
docs/design.md
@@ -1,293 +1,186 @@
|
||||
# Design record
|
||||
|
||||
Decisions that are expensive to revisit, and the evidence behind them. If you
|
||||
are adding symbols rather than changing the machinery, read
|
||||
[adding-symbols.md](adding-symbols.md) instead.
|
||||
Notes on how this binding is built and why, for anyone touching the
|
||||
machinery. Adding a new class instead? [adding-symbols.md](adding-symbols.md)
|
||||
is the practical guide.
|
||||
|
||||
## What this is
|
||||
|
||||
A hand-written [nanobind](https://github.com/wjakob/nanobind) binding of the
|
||||
OCCT surface the N3XD backend actually uses — 139 symbols across 48 `OCP.*`
|
||||
modules, per `tools/inventory.py`, not all of OCCT. It 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.
|
||||
A hand-written [nanobind](https://github.com/wjakob/nanobind) binding
|
||||
covering the subset of OCCT actually in use, not the whole kernel — run
|
||||
`tools/inventory.py` for the current count. It installs as a top-level `OCP`,
|
||||
a drop-in replacement for `cadquery-ocp-novtk`.
|
||||
|
||||
Binding *call* overhead was never the bottleneck — the CAD hotspots are inside
|
||||
the C++ kernel — so the payoff is version velocity, footprint, correctness at
|
||||
the ownership boundary, and the freedom to add APIs upstream cannot (GIL
|
||||
release, bulk array extraction).
|
||||
Binding *call* overhead was never the bottleneck — the real work happens
|
||||
inside the C++ kernel — so the payoff is version velocity, a smaller
|
||||
footprint, correctness around object ownership, and room to add APIs
|
||||
upstream doesn't offer (releasing the GIL, bulk array extraction).
|
||||
|
||||
## The handle model
|
||||
|
||||
`opencascade::handle<T>` is cast by `src/common/occt_handle.h`, modelled on
|
||||
nanobind's own `stl/shared_ptr.h`.
|
||||
|
||||
- **C++ → Python**: the wrapper is a *non-owning* nanobind instance pointing at
|
||||
the C++ object, plus one handle stored in its keep-alive list. An existing
|
||||
wrapper is reused (`is_new == false`), so identity holds while a wrapper is
|
||||
alive, and a long-lived object crossing the boundary repeatedly does not pile
|
||||
up redundant references. Transients are polymorphic, so `nb_type_put_p`
|
||||
downcasts on the dynamic type.
|
||||
- **Python → C++**: a plain handle copy, balanced when the caster dies after the
|
||||
call. Unlike `shared_ptr`, no Python reference is taken: OCCT's intrusive
|
||||
atomic refcount owns the object's memory, not the Python instance. That is
|
||||
precisely what makes releasing the GIL safe — OCCT may copy handles on its own
|
||||
worker threads without touching the interpreter.
|
||||
- **C++ → Python**: the wrapper is a *non-owning* nanobind instance pointing
|
||||
at the C++ object, plus one handle kept alive alongside it. Reusing an
|
||||
existing wrapper when one is already around keeps identity stable, so an
|
||||
object crossing the boundary repeatedly doesn't pile up references.
|
||||
- **Python → C++**: a plain handle copy, dropped when the caster goes out of
|
||||
scope. No Python reference is taken — OCCT's own atomic refcount owns the
|
||||
object, not the Python instance — which is exactly what makes releasing the
|
||||
GIL safe: OCCT can copy handles on its own threads without touching the
|
||||
interpreter.
|
||||
|
||||
**Transient constructors never use `nb::init<>`.** nanobind's normal
|
||||
constructor placement-news the object into the Python instance's storage, which
|
||||
OCCT would later `delete`. Use `ocp_new<T, Args...>()` (`occt_transient.h`),
|
||||
which heap-allocates and returns a handle. This is not hypothetical: the app
|
||||
builds a `Geom_BSplineCurve` in `sketch_builder/edges.py` and hands it to
|
||||
`BRepBuilderAPI_MakeEdge`, which keeps a handle past the call.
|
||||
constructor placement-news the object into the Python instance's storage,
|
||||
which OCCT would later try to `delete` itself. Use `ocp_new<T, Args...>()`
|
||||
(`occt_transient.h`) instead — it heap-allocates and returns a handle, which
|
||||
is what a transient needs when something keeps it alive past the call that
|
||||
created it.
|
||||
|
||||
The caster enforces the rule rather than trusting it: a transient whose
|
||||
`GetRefCount()` is zero is not handle-owned, and converting it would hand OCCT
|
||||
The caster enforces this rather than trusting callers: a transient whose
|
||||
`GetRefCount()` is zero isn't handle-owned, and converting it would hand OCCT
|
||||
the right to free a nanobind instance. `from_python` refuses instead — a
|
||||
TypeError beats heap corruption, and only a binding bug can reach it.
|
||||
`TypeError` beats heap corruption.
|
||||
|
||||
*Alternative considered*: `nb::intrusive_ptr` plus a side table mapping
|
||||
`Standard_Transient*` to `PyObject*` (OCCT objects have no self-py slot). It
|
||||
loses on the property that matters most here — nanobind's intrusive protocol
|
||||
unifies the C++ count with the PyObject refcount, so `Py_INCREF` from a
|
||||
GIL-free OCCT thread becomes a crash class. Kept as the documented fallback if
|
||||
the caster above ever proves unworkable.
|
||||
|
||||
*Verification*: `tests/test_handles.py`, run both normally and under
|
||||
`make test-asan`. It covers wrapper identity across a round trip, survival in
|
||||
both directions when one side drops its reference, refcount balance across 1000
|
||||
conversions and across 100 raising calls, null-handle ↔ `None`, and RSS growth
|
||||
across 50 000 create/destroy cycles. ASAN covers memory *safety*; the RSS
|
||||
assertion covers *growth* and is skipped under ASAN, whose quarantine retains
|
||||
freed memory (139 MB of it, which is what a naive reading would call a leak).
|
||||
Covered by `tests/test_handles.py`, run both normally and under
|
||||
`make test-asan`: wrapper identity across a round trip, refcount balance,
|
||||
null-handle ↔ `None`, and memory growth across repeated create/destroy
|
||||
cycles.
|
||||
|
||||
## Fidelity rules
|
||||
|
||||
Verified against the installed stock wheel, not assumed.
|
||||
Checked against the installed stock wheel, not assumed.
|
||||
|
||||
**`__hash__` is bound; `__eq__` is not.** Upstream binds `__hash__` (TShape ⊕
|
||||
Location) and leaves `__eq__` at Python's default identity comparison, so two
|
||||
re-extracted copies of one face hash equal but compare unequal. That pairing
|
||||
looks like a bug and is load-bearing: `cad/topology/geom_memo.py` buckets on
|
||||
`hash(face)` and disambiguates with `IsSame` *because* `==` cannot be trusted.
|
||||
Binding `__eq__` to `IsEqual` would quietly collapse entries that memo keeps
|
||||
apart. Hash *values* need not match upstream — only the semantics do.
|
||||
re-extracted copies of the same face hash equal but compare unequal. That's
|
||||
intentional upstream behaviour worth keeping as-is: code that dedupes shapes
|
||||
by hash and double-checks with `IsSame` relies on `==` *not* being
|
||||
trustworthy on its own.
|
||||
|
||||
**Sub-shapes are returned by value** (`OCP_RETURN_COPY`) from explorers,
|
||||
iterators, map lookups and history lists. A `TopoDS_Shape` is a small value
|
||||
holding a handle to its TShape, so a copy is one incref and owns what it points
|
||||
at. This makes the lifetime class that segfaulted a process-global face memo
|
||||
unrepresentable.
|
||||
holding a handle to its TShape, so a copy is cheap and owns what it points
|
||||
at — this rules out a class of lifetime bug where a cached wrapper outlives
|
||||
the structure it was explored from.
|
||||
|
||||
**Executing constructors are not bound.** `BRepAlgoAPI_*` gets a default
|
||||
constructor plus `SetArguments`/`SetTools`/`Build` — the two-argument forms run
|
||||
the algorithm immediately, which is how a latent double-execution survived in
|
||||
the app for a while.
|
||||
constructor plus `SetArguments`/`SetTools`/`Build` — the two-argument forms
|
||||
run the algorithm immediately, which invites calling `Build()` a second time
|
||||
and running the operation twice.
|
||||
|
||||
**`_s` on every static**, via `OCP_DEF_S`. The rule is blanket rather than
|
||||
clash-driven, so no static can ship without it; the app calls 176 of them.
|
||||
**`_s` on every static**, via `OCP_DEF_S`. The rule is blanket, not
|
||||
clash-driven — no static ships without it.
|
||||
|
||||
**Enums** use `nb::is_arithmetic()` + `export_values()`, reproducing pybind11's
|
||||
int comparison and module-scope members (`from OCP.TopAbs import TopAbs_FACE`).
|
||||
**Enums** use `nb::is_arithmetic()` + `.export_values()`, matching
|
||||
pybind11's int comparison and module-scope members (`from OCP.TopAbs import
|
||||
TopAbs_FACE`).
|
||||
|
||||
**Exceptions**: `Standard_Failure` derives `RuntimeError`, which is what keeps
|
||||
the backend's `except RuntimeError` sites working — it never names an OCCT
|
||||
class. About 20 concrete types are bound under `OCP.Standard` / `OCP.StdFail`
|
||||
and dispatched on the dynamic OCCT type, because cad_pool's children marshal
|
||||
failures home as `f"{type(exc).__name__}: {exc}"`, making the name observable.
|
||||
**Exceptions**: `Standard_Failure` derives `RuntimeError`, so `except
|
||||
RuntimeError` keeps working without ever naming an OCCT class. Around twenty
|
||||
concrete exception types are also bound under `OCP.Standard` / `OCP.StdFail`
|
||||
and dispatched on the OCCT dynamic type, for callers that want to match by
|
||||
name.
|
||||
|
||||
**`TopoDS` is a namespace in OCCT 7.9**, not a class. Upstream still presents it
|
||||
as a class carrying the `_s` statics, and the app calls `TopoDS.Face_s(...)`, so
|
||||
`mod_TopoDS.cpp` binds an empty carrier struct under that name.
|
||||
**`TopoDS` is a namespace in OCCT**, not a class. Upstream still presents it
|
||||
as a class carrying the `_s` statics (`TopoDS.Face_s(...)`), so
|
||||
`mod_TopoDS.cpp` binds an empty carrier struct under that name to match.
|
||||
|
||||
## GIL policy
|
||||
|
||||
Released around calls that stay inside the kernel and cannot re-enter Python:
|
||||
Released around calls that stay inside the kernel and can't re-enter Python:
|
||||
`Build`/`Perform`, meshing, `BRepCheck_Analyzer`, `RWStl`, and every
|
||||
`n3xd_ocp` bulk API. Applied from an explicit list, never blanket.
|
||||
`n3xd_ocp` bulk API. Held everywhere else — this is an explicit allow-list,
|
||||
not a blanket policy.
|
||||
|
||||
**The XSTEP readers and writers are the exception**, amending what this section
|
||||
said before Inc 3 landed. STEP and IGES read and write through the
|
||||
process-global `Interface_Static` settings table, the IGES reader is documented
|
||||
as not thread-safe, and the app already serialises every import behind a lock —
|
||||
so holding the GIL costs nothing there and removes a whole class of question.
|
||||
Upstream releases nowhere, so this also stays closer to it. `RWStl` touches no
|
||||
global state and does release.
|
||||
**STEP and IGES readers/writers are the exception.** They go through the
|
||||
process-global `Interface_Static` settings table, and IGES reading is
|
||||
documented as not thread-safe. OCCT 8.0 added a thread-safety contract for
|
||||
XSTEP, but it only covers one reader/writer per thread using the *default*
|
||||
parameter set — it says nothing about a process that mutates
|
||||
`Interface_Static` (a common way to configure units before reading). Holding
|
||||
the GIL here costs nothing if imports are already serialized on the caller's
|
||||
side, and keeps behaviour closer to upstream, which doesn't release the GIL
|
||||
for XSTEP either.
|
||||
|
||||
`BinTools` is *also* GIL-free for the kernel half, which the original plan
|
||||
assumed impossible. Rather than bridging a `streambuf` that calls back into
|
||||
Python per chunk, `occt_stream.h` slurps the file-like object first and hands
|
||||
the kernel a pure C++ stream. That is correct regardless of how BinTools seeks,
|
||||
and costs one extra copy of the payload — which `n3xd_ocp.bintools` avoids
|
||||
entirely for the pool paths that care.
|
||||
`BinTools` releases the GIL for the kernel half of (de)serialisation.
|
||||
Rather than bridging a `streambuf` that calls back into Python per chunk,
|
||||
`occt_stream.h` reads the file-like object fully first and hands the kernel a
|
||||
plain C++ stream — one extra copy of the payload, which `n3xd_ocp.bintools`
|
||||
avoids for callers that already have `bytes`.
|
||||
|
||||
**An unregistered type cannot be a default argument.** nanobind converts
|
||||
defaults to Python objects at *binding* time, so a `.def(..., "Algo"_a =
|
||||
Extrema_ExtAlgo_Grad)` for an enum this binding does not register fails the
|
||||
whole extension's import with a bare `std::bad_cast` — no file, no line. It
|
||||
happened three times while writing Inc 1 and 2. Where the trailing argument is
|
||||
one the app never overrides, the fix is to leave it off and let OCCT apply its
|
||||
own default: `GeomAPI_ProjectPointOnSurf` (Extrema algo),
|
||||
`BRepFilletAPI_MakeFillet` (`ChFi3d_FilletShape`),
|
||||
`BRepOffsetAPI_MakeThickSolid.MakeThickSolidByJoin` (mode and join type) and
|
||||
`BRepExtrema_DistShapeShape` (Extrema flags) all do. `tools/sigdiff.py` reports
|
||||
each of them, which is the point — they are the only four places the bound
|
||||
surface deliberately differs from upstream's.
|
||||
**An unregistered type can't be a default argument.** nanobind converts
|
||||
default values to Python objects at *binding* time, so giving an enum this
|
||||
binding doesn't register as a default (e.g. `"Algo"_a =
|
||||
Extrema_ExtAlgo_Grad`) fails the whole extension's import with a bare
|
||||
`std::bad_cast` and no further detail. Where the default is never overridden
|
||||
in practice, the fix is to leave the argument off and let OCCT apply its own
|
||||
default — `tools/sigdiff.py` reports every place the bound surface
|
||||
deliberately differs from upstream this way.
|
||||
|
||||
**None as an argument** is rejected before the caster for simple overloads, so
|
||||
handle parameters that legitimately accept a null handle need an explicit
|
||||
`nb::arg("x").none()`. Null *returns* map to `None` unconditionally. The app
|
||||
passes no null handles today; `inventory.py` plus the app suite are the guard.
|
||||
**`None` is rejected before the caster reaches simple overloads.** Handle
|
||||
parameters that legitimately accept a null handle need an explicit
|
||||
`nb::arg("x").none()`. Null *returns* map to `None` unconditionally.
|
||||
|
||||
## Packaging
|
||||
|
||||
**One extension** (`OCP/_OCP.abi3.so`) registering every `OCP.*` submodule via
|
||||
`PyImport_AddModule`, so `import OCP.TopoDS` works with no shim module per name
|
||||
and `cls.__module__` reads `OCP.TopoDS`. The whole surface traffics in
|
||||
`TopoDS_Shape`, `gp_*` and handles, so sharing types in-process is free here and
|
||||
would otherwise lean on nanobind's cross-extension registry; registration order
|
||||
stays an explicit sequence in `core.cpp`; and cad_pool's forkserver warms one
|
||||
dlopen. One `.cpp` per module keeps incremental compiles cheap — only the link
|
||||
is shared.
|
||||
**One extension** (`OCP/_OCP.abi3.so`) registers every `OCP.*` submodule via
|
||||
`PyImport_AddModule`, so `import OCP.TopoDS` works without a shim module per
|
||||
name. Types are shared in-process for free this way, instead of leaning on
|
||||
nanobind's cross-extension registry. One `.cpp` file per module keeps
|
||||
incremental compiles cheap — only the final link step is shared.
|
||||
|
||||
**abi3 (`cp312-abi3`)** from the first build, matching forge/assay, so the
|
||||
Python 3.13 bump (roadmap 10D) needed no rebuild — the same wheel loads on the
|
||||
3.13 the app now ships. The tag stays at `cp312`: it is a floor, and raising it
|
||||
would buy nothing. Escape hatch if a nanobind STABLE_ABI limitation ever bites:
|
||||
drop `STABLE_ABI` and `wheel.py-api`, since every deployed environment is on one
|
||||
interpreter. Stub generation works fine under abi3.
|
||||
**abi3 (`cp312-abi3`)**, so bumping the Python version doesn't require a
|
||||
rebuild — the tag stays at `cp312` as a floor, not a target. Stub generation
|
||||
works fine under abi3. If a nanobind STABLE_ABI limitation ever gets in the
|
||||
way, dropping `STABLE_ABI` and pinning to one interpreter is the escape
|
||||
hatch.
|
||||
|
||||
**Version `<occt>.N`**, asserted at configure time against the OCCT actually
|
||||
found, so `occt_version()` keeps reporting the truth for assay's goldens.
|
||||
Iteration builds carry `.devN`; the registry never allows republishing.
|
||||
**Version `<occt-version>.N`**, asserted at configure time against the OCCT
|
||||
actually found, so the version string always reflects the kernel underneath
|
||||
it. Iteration builds carry a `.devN` suffix; the registry never allows
|
||||
republishing a version.
|
||||
|
||||
**No sdist is ever published** — it could not build without the builder image,
|
||||
and offering one invites the 4-core production host to try. That is enforced by
|
||||
only ever building wheels. Note `sdist.exclude` is *not* the way to do it:
|
||||
scikit-build-core feeds it into the wheel's package-file mapping too, so
|
||||
excluding `*` silently ships a wheel containing the compiled extension and none
|
||||
of the Python package. Relatedly, file selection is git-based, so the generated
|
||||
`.pyi` stubs are gitignored *and* re-included through `sdist.include`.
|
||||
**No sdist is ever published** — it can't build without the builder image,
|
||||
and shipping one just invites someone to try. `sdist.exclude` is *not* the
|
||||
way to enforce that: scikit-build-core also feeds it into the wheel's
|
||||
package-file mapping, so excluding everything silently ships a wheel with
|
||||
the compiled extension and none of the Python package.
|
||||
|
||||
**Fork safety**: import starts no threads and creates no fork-hostile state, so
|
||||
cad_pool's forkserver keeps costing ~30 ms per job instead of a ~1.3 s spawn.
|
||||
Pinned by `tests/test_forksafety.py`.
|
||||
**Fork safety**: importing the extension starts no threads and creates no
|
||||
fork-hostile state, so forking right after import is cheap and safe. Pinned
|
||||
by `tests/test_forksafety.py`.
|
||||
|
||||
## The `n3xd_ocp` module
|
||||
|
||||
`OCP.*` stays a symbol-for-symbol drop-in so parity testing means something;
|
||||
anything additive lives in `n3xd_ocp`, shipped in the same wheel and backed by
|
||||
the same OCCT build. Only the leaf submodules are registered from C++ — creating
|
||||
the parent would put a bare module in `sys.modules` and a later `import
|
||||
n3xd_ocp` would skip the package's `__init__.py`.
|
||||
`OCP.*` stays a symbol-for-symbol drop-in so parity testing against the
|
||||
stock wheel means something; anything additive lives in `n3xd_ocp` instead,
|
||||
shipped in the same wheel and built against the same OCCT. Only the leaf
|
||||
submodules are registered from C++ — creating the parent package from C++
|
||||
would put a bare module in `sys.modules`, and a later `import n3xd_ocp`
|
||||
would then skip its `__init__.py`.
|
||||
|
||||
Shipped: `bintools` (shape ↔ `bytes`, GIL-free, byte-identical to
|
||||
`OCP.BinTools` and asserted so) and `_debug` (test-only ownership
|
||||
introspection).
|
||||
Shipped today: `bintools` (shape ↔ `bytes`, byte-identical to
|
||||
`OCP.BinTools`), `measure` (batched per-face area and centroid) and `tess`
|
||||
(triangulated meshes and edge polylines) — see their `.pyi` stubs for full
|
||||
signatures, or the [usage examples](../README.md#usage) for a quick start.
|
||||
|
||||
Designed, landing with the increment that binds their types:
|
||||
## Matching upstream, and how that's checked
|
||||
|
||||
```python
|
||||
# with Inc 1 (BRepGProp/GProp) — attacks the measured 94 % of
|
||||
# face_candidate_anchors (0.99 s of 1.05 s for 690 faces) that is
|
||||
# BRepGProp.SurfaceProperties_s called once per face from Python
|
||||
def face_surface_props(shape, *, parallel=True) -> tuple[ndarray, ndarray]
|
||||
# areas[F], centroids[F,3], ordered by TopExp.MapShapes_s(FACE) index
|
||||
`inventory.py --check` answers "does the symbol exist", not "does it behave
|
||||
the same" — and that gap is where a binding can do real damage silently.
|
||||
`tools/sigdiff.py` (`make sigdiff`) closes it by diffing every bound
|
||||
constructor and member against the stock wheel; see
|
||||
[adding-symbols.md](adding-symbols.md) for the bug it exists to catch.
|
||||
|
||||
# with Inc 2 (BRepMesh/Poly) — replaces the per-node and per-triangle Python
|
||||
# loops in cad/tessellation.py
|
||||
class FaceMesh: nodes, triangles, normals, uv, face_index
|
||||
def extract_meshes(shape, *, want_normals=True, want_uv=False,
|
||||
apply_location=True, flip_reversed=True) -> list[FaceMesh]
|
||||
Two things static analysis can't see, worth keeping in mind:
|
||||
|
||||
# with Inc 4 — opt-in experiment: OSD::SetSignal turns some native faults into
|
||||
# catchable Standard_Failure subclasses inside cad_pool children. Never called
|
||||
# at import; subprocess isolation stays regardless.
|
||||
def set_signal(arm_fpe: bool = False) -> None
|
||||
```
|
||||
|
||||
The backend adopts these after cutover, one call site at a time.
|
||||
|
||||
## Matching upstream, and how that is checked
|
||||
|
||||
`inventory.py --check` answers "does the symbol exist". It cannot answer "does
|
||||
it mean the same thing", and the gap between those two is where a binding does
|
||||
real damage. `nb::init<TopoDS_Shape, gp_Vec, bool, bool, bool>` for
|
||||
`BRepPrimAPI_MakePrism` compiled cleanly and bound OCCT's *semi-infinite*
|
||||
overload, because that one takes a `gp_Dir` and `gp_Dir` converts implicitly
|
||||
from `gp_Vec` — so the flags shifted one position along and the result was a
|
||||
valid solid of the wrong shape. The fixture digests caught it;
|
||||
`tools/sigdiff.py` (`make sigdiff`) finds the class of bug directly, by diffing
|
||||
every bound constructor and member against the stock wheel.
|
||||
|
||||
Two further limits are worth stating, because they shaped how the increments
|
||||
were gated:
|
||||
|
||||
- **Static analysis cannot see instance methods.** A method called on an object
|
||||
(`vec.Reverse()`) appears in no import, so `--check` is blind to it and
|
||||
`--methods` only guesses. Six such gaps survived to the end of Inc 4 and the
|
||||
app's suite found all six in one run — one of them, `gp_Vec.Reverse`, failing
|
||||
311 tests by itself. The suite is the only real net here.
|
||||
- **The app's suite cannot gate a single increment.** `backend/tests/
|
||||
conftest.py` imports `n3xd.main`, so every test fails at collection until the
|
||||
last module is bound. Increments are gated instead on reference values
|
||||
`tools/gen_fixtures.py` records from the stock wheel — measurements, per-face
|
||||
area and centroid in map order, mesh counts, and the `Modified`/`Generated`/
|
||||
`IsDeleted` maps compared exactly, since that is the substrate the app's
|
||||
topological naming is built on.
|
||||
|
||||
## OCCT 8.0 bump — what actually moved
|
||||
|
||||
Done at 8.0.1 (2026-08-11). Four edits across ~4 000 lines of binding, and the
|
||||
bound Python surface came out **identical** — `sigdiff` compared 7.9.3.1's dump
|
||||
against 8.0.1.1's in both directions and found no class, member or constructor
|
||||
arity changed, so the drop-in contract held without the app being touched.
|
||||
|
||||
What broke, all of it mechanical:
|
||||
|
||||
- **`NCollection_Utf8String` is gone.** `NCollection_String`
|
||||
(`NCollection_UtfString<char>`) is the same UTF-8 type and is what the font
|
||||
API takes. The Python name is unchanged, since the app imports it.
|
||||
- **`Standard_Failure` lost its `Standard_Transient` RTTI** when it moved to
|
||||
deriving `std::exception`, so `DynamicType()->Name()` no longer compiles. The
|
||||
virtual `ExceptionType()` replaced it and returns the same class names, which
|
||||
is what the exception dispatch keys on — and what `cad_pool` marshals home.
|
||||
- **The `Size()` → `size_t` migration added index overloads.** `FindKey` on the
|
||||
indexed maps now has both an `int` and a `size_t` form, so a plain member
|
||||
pointer is ambiguous; `nb::overload_cast<Standard_Integer>` picks the `int`
|
||||
one, which keeps the negative-index guard.
|
||||
- **`StdPrs` moved from TKService to TKV3d**, so `CMakeLists.txt` links both.
|
||||
|
||||
Three watchlist predictions were wrong, recorded here because the reasoning
|
||||
behind them was plausible:
|
||||
|
||||
- `StdPrs_BRepFont`/`StdPrs_BRepTextBuilder` did **not** become typedefs of
|
||||
`Font_BRepFont`/`Font_BRepTextBuilder`. The aliasing runs the other way — they
|
||||
are still the real classes and the `Font_*` names are the typedefs.
|
||||
- `GeomLProp` was **not** superseded by `GeomProp`/`BRepProp`. It became a
|
||||
template (`GeomLProp_SLProps` is now an alias for
|
||||
`GeomLProp_SLPropsBase<handle<Geom_Surface>>`) and kept the constructor and
|
||||
accessors this binding uses, so the module compiled unchanged.
|
||||
- **The byte-identity fixtures did not retire.** A different kernel was assumed
|
||||
to write different BREP bytes; 8.0.1 does not. All six fixtures round-trip to
|
||||
the same digests, and the measurement, history and mesh-count blocks match
|
||||
too, so `tests/data/` was left alone and no re-bless happened. That also means
|
||||
the app's content-addressed BREP payloads stay valid across the bump.
|
||||
|
||||
Unchanged as predicted: the handle model (`occt_handle.h` needed nothing, ASAN
|
||||
clean), the exception *table* (the removed `Raise`/`Throw`/`Instance` helpers
|
||||
were never bound), the deprecated out-parameter handle returns this binding
|
||||
still uses, and the global math wrappers it never bound.
|
||||
|
||||
## Open questions
|
||||
|
||||
- ~~**S5** — whether STEP needs `CSF_*` resource files shipped in the wheel.~~
|
||||
**Settled at Inc 3: it does not.** `tests/test_inc3_io.py` asserts that no
|
||||
`CSF_*` variable is set and then round-trips STEP and IGES, reading the
|
||||
declared units back off both — which is exactly the resource-less container
|
||||
the question was about. Both controllers initialise and the readers resolve
|
||||
millimetres. The wheel ships no `share/` tree.
|
||||
- **Byte-identity beyond 7.9.3** — the gate compares against the stock wheel, so
|
||||
it necessarily retires at the OCCT 8.0 bump (roadmap 10E), where the fixtures
|
||||
are re-blessed deliberately alongside assay's goldens. See the 8.0 watchlist
|
||||
above for what else moves.
|
||||
- **Instance methods.** A method called on an object (`vec.Reverse()`)
|
||||
appears in no import, so `--check` is blind to it; `--methods` only
|
||||
guesses, by tracing local variables back to their constructor.
|
||||
- **Whether the surface actually behaves like upstream.** Confidence that it
|
||||
does comes from reference values recorded off the stock wheel —
|
||||
measurements, per-face area and centroid, mesh counts, and the
|
||||
`Modified`/`Generated`/`IsDeleted` history maps — reproduced under this
|
||||
build and compared exactly.
|
||||
|
||||
Reference in New Issue
Block a user