0012 — Geometry backends are swappable, whole or per area
- Status: Accepted
- Date: 2026-09-21
- Deciders: openbimrs contributors
- Supersedes: —
- Amends: ADR 0004 — compilation stays opt-in; this decides whose kernel runs
Context
ADR 0004 established that this crate is a bridge, not a kernel: it lowers IFC into a neutral DAG and calls someone else's compiler. A 2026-09-14 amendment admitted mesh compilation behind an opt-in compile feature.
That amendment left one thing undecided, and the implementation chose badly. compile_product_mesh constructed a concrete pair inline:
let compiler = ReferenceMeshCompiler::new(BoolmeshBoolean);The upstream contracts are traits — MeshCompiler, MeshBoolean, Tessellator, CurveEvaluator, MeshPlaneSection, ExactCompiler — so the architecture was swappable while our single call site was not. A consumer who wanted CGAL, OCCT, or a GPU tessellator had to fork compile.rs. That also made honest benchmarking impossible: comparing two backends on the same file is exactly the measurement a bridge should make easy.
Geometry kernels are not interchangeable in practice. One is fast at mesh booleans, another is trusted for exact B-rep, a third is the only one licensed for a given deployment. Forcing a single choice for all areas is the wrong shape.
Decision
Backend selection is a parameter, never a constant.
Every compilation entry point is generic over the upstream contract, and the backend is borrowed so one instance serves a whole run:
rustpub fn compile_product_mesh_with<B: MeshCompiler>( backend: &B, model: &Model, product: EntityId, tolerance: Tolerance, ) -> GeometryResult<Option<TriMesh>>Two granularities are supported, because kernels differ by area.Whole-kernel: implement
MeshCompilerover your own engine; none of the reference execution path is linked. Per-area: keep the reference traversal and replace one capability, e.g.ReferenceMeshCompiler::new(MyBoolean).The seam and the engine are separate features.
compilebrings the contracts a caller implements against.compile-reference-backendadds the reference engine and the convenience wrappers. A bring-your-own-kernel build enablescompilealone and links no backend at all.A default still exists and is named.
default_backend()returns the reference pair rather than hiding it inside a function body, so a caller can log it beside a benchmark or compare against it explicitly.compile_product_meshdelegates tocompile_product_mesh_with, so the convenience path and the explicit path cannot drift.
Consequences
Backend choice stays application policy, which is what ADR 0004 required: the file never determines it, and two backends given the same model must agree on what the file means. Choosing between them is a question of speed, robustness, or licence.
A kernel author needs no changes here — they implement a published upstream trait. Benchmarking two kernels over one corpus is now a loop, not a fork.
The cost is one extra feature name and a generic parameter on three functions. Callers who want the old behaviour enable compile-reference-backend and call compile_product_mesh exactly as before.
tests/backend_seam_linkage.rs inspects the resolved dependency graph and fails if the engine leaks into the compile feature, if the contracts go missing from it, or if either reaches a default build. tests/backend_swap.rs defines a kernel outside this crate and asserts the mesh a caller receives is the one their own code produced.
Amendment (2026-10-09): the comparison is committed (#31)
"Benchmarking two kernels over one corpus is now a loop" was a claim with no loop behind it. The backend_compare example of ifc-geometry (crates/ifc-geometry/examples/backend_compare/) is that loop, written as a consumer would write it. The decision above is unchanged; this records how it is exercised.
- Backends are values. Each one is a
Contestantin a list, and one traversal runs them all throughcompile_product_mesh_with. The onlycfgis where the list is built: the reference backend joins it undercompile-reference-backend. - The second backend is real and foreign.
polygon-extruderis defined in the example and names only the published contracts. It compiles a straight-edged subset itself (collections and instances, triangle and polygon meshes, faceted B-reps, extrusions of polygonal profiles with holes, blocks) and refuses everything else withGeomError::UnsupportedInput. It builds and runs undercompilealone. No second engine is a dependency, so no licence surface is added. - Agreement is checked, not assumed. Where both backends mesh a product, signed volume, area and every bounding-box coordinate must agree within a stated relative tolerance. Each metric outside it is listed with fixture, product and both values. A refusal by one backend is listed as a coverage difference and the run goes on.
- Numbers carry their method. The output states the iteration count, that the first pass is reported separately, what is timed, the machine, the profile and the load. It also states that the times are not a cross-kernel performance claim, because backends that mesh different products do different work.
- The gate runs it. It runs in quick mode under
compilealone and beside the reference, where--strictfails on any divergence.
The harness is shaped for the other contracts. A MeshBoolean, MeshPlaneSection, Tessellator, CurveEvaluator or ExactCompiler comparison adds an area, an artifact and a measure, and keeps the traversal, timing and report. None is implemented yet.