0014 — Net geometry is an explicit request; openings are exact booleans
- Status: Accepted
- Date: 2026-09-24
- Deciders: openbimrs contributors
- Supersedes: —
- Amends: ADR 0012 — adds a second compile entry point with the same backend seam
- Amended: 2026-10-04 — a Reference View opening may be taken as already applied, on explicit request (#351)
- Amended: 2026-11-03 — an opening-less Body with a boolean is lowered in its frame (#655)
Context
A product's Body representation is its gross shape. Openings are separate products (IfcOpeningElement, IfcVoidingFeature, any IfcFeatureElementSubtraction) related to their host by IfcRelVoidsElement. The file never authors the net result.
Until #44, compile_product_mesh compiled only the Body, so every wall came back solid through its doors. On the local real-model corpus the relation appears 49 to 775 times per model. No compiled mesh reflected any of them.
Both answers are legitimate. Quantity takeoff is usually gross, with openings reported separately. Clearances, net areas, window-to-floor ratios and clash tests through an opening need net. Neither can replace the other.
Decision
We will keep compile_product_mesh gross and unchanged, and add a separate net entry point:
lower::lower_product_netlowers the host Body, then each voiding opening's Body through the opening's own placement chain, and appends exactSolidOperation::Boolean { Difference }nodes. Nothing is evaluated in the bridge, per ADR 0004.compile::compile_product_mesh_netandcompile_product_mesh_net_withcompile that graph. They returnNetMesh { mesh, openings }, whereopeningslists every subtracted opening in ascending id. The_withform takes anyMeshCompiler, as ADR 0012 requires.openings_of(model, host)is a kernel-free read of the relation.- Refusal, not fallback. If any opening cannot be removed, the result is
GeometryError::OpeningNotSubtracted { host, opening, cause }. Returning the gross body would hand back geometry that claims to be net and is not. - Multi-item bodies are split into solid parts. The neutral graph accepts only solids as boolean operands, while a multi-item Body lowers to a
Collection(or anInstanceof one, for a mapped item). Both host and opening are flattened to their solid parts, with instance transforms carried onto each part. Each host part is cut on its own, since(A ∪ B) − O = (A − O) ∪ (B − O). - Order is content-defined. Openings are subtracted in ascending opening id, and an opening named by two relations is subtracted once.
Alternatives considered
| Option | Why not |
|---|---|
Make compile_product_mesh net by default | Silently changes every existing caller's volumes, and gross is the right answer for takeoff. |
A bool / options flag on the existing function | Hides a different return contract (the subtracted-opening list, a new error) behind a flag. Two named functions are clearer to callers, most of them agents. |
| Skip an opening that fails, return the rest | The mesh would claim to be net while still solid through that opening. This is the failure #44 was filed to remove. |
| Evaluate the subtraction in the bridge | Violates ADR 0004; the backend decides how booleans are computed. |
| Union all opening parts into one tool first | Adds a union the file never authored and a second failure mode for no benefit. Sequential differences give the same region. |
Consequences
Positive
- Net geometry is reachable with the same backend seam as gross.
- Every refusal names the opening at fault. On a backend refusal, the host is compiled alone first, so a host that cannot mesh even gross is blamed as the host rather than on its first opening.
- The success path compiles the net graph once.
Negative / costs
- A refusal pays a diagnostic pass: the host alone, then each chain prefix until one fails. That cost only lands on calls that already failed.
voidings_ofscans all relations per call. Netting every product of a model is O(products × relations). That is fine at the measured hundreds of relations; an index is the fix if it ever shows up in a profile.- Net quality is bounded by the backend's boolean on real exporter data. Non-manifold operands are refused by the reference kernel, and those refusals surface as
OpeningNotSubtracted. On the local corpus that is 14 of 423 hosts withaxiolid-construct0.3.1.
Follow-ups / risks to watch
IfcRelProjectsElement(additions) is the mirror case and is not handled.axiolid-construct0.3.0 wound a downward extrusion inside-out, which is how many exporters author opening bodies, so those subtractions were refused (never inverted). Fixed in 0.3.1 (axiolid/kernel#166), now the workspace floor.
Amendment (2026-10-04): Reference View openings taken as applied (#351)
IFC4 Reference View exports author an IfcOpeningElement with only a Reference representation against a host whose Body already has the hole. IFC4 ADD2 TC1 (IfcOpeningElement, entity definition) says such a representation "is not subtracted, it is provided in addition to the hole in the Body shape representation of the voided element", and the Reference View concept on the same page that it "shall not be used to subtract the opening". Refusing the host for it left 691 outcomes on 36 hosts in three real models unmeasured (axioval/engine#218).
The amended rule: lower_product_net is unchanged and still refuses. lower_product_net_with(session, product, NetOptions) with ReferenceOnlyOpenings::TakeAsApplied lists such an opening in NetLowering::taken_as_applied (opening, relation, reason) and subtracts nothing for it. Taking the exporter's word for the hole is a decision about the file a caller makes, like asking for net geometry at all, so it is explicit too. Nothing is dropped silently: every opening is either subtracted or listed. Only an opening whose every representation is Reference qualifies; one with no representation, or with any other representation beside it, is refused as before.
This is the options argument the alternatives table rejected for the gross entry point; here it selects between two readings of one return contract that both callers already handle, not between gross and net.
Amendment (2026-10-08): subtract in the host's frame (#388)
Lowering both operands in world coordinates rounded an opening flush with its wall off the wall's faces by up to an ulp of the site's survey coordinates (5.6e6 m), and the reference kernel refused the result as touching itself along the opening's edges: 28 walls in one georeferenced model (axioval/engine#303).
The amended rule: the net body is lowered in the host's frame. The host's Body is lowered without its world placement, each opening's Body by its placement relative to the host's, composed once along the IfcLocalPlacement chain the two share from their first common placement down, and the Difference nodes run there. One Instance with the host's world transform sits above gross and each subtraction's body and result, so the reported nodes stay in world coordinates. When an opening shares no such chain with its host, or its Body's context frame differs from the host's, the whole net body is lowered in world coordinates as before rather than guessed.
Amendment (2026-11-03): an opening-less Body with a boolean, in its frame (#655)
A turned wall with a flush polygonal clip has no opening, so it was lowered in world coordinates. There the clip's plane and the wall's faces are 1e-16 apart, and the kernel kept a lid over the slot (axioval/engine#373).
The amended rule: a product no opening voids is lowered in its host frame, as in #388, when an item of its Body is an IfcBooleanResult, an IfcBooleanClippingResult or an IfcCsgSolid. gross and root are one Instance of the product's world transform above the Body at identity; there is no Instance when that transform is the identity. Only BodyKind::Csg items select this path: an Instance compile adds the certified PLACEMENT_ROUNDING deviation (Exact to Within) to every placed body, which every other opening-less Body would pay for nothing. The gross entry points are unchanged; #657 covers the gross path.
Amendment (2026-11-03): per-layer parts are cut in the host's frame (#455)
A layered wall, slab or plate can be asked for one part per material layer. The planes of the stack are stated in the product's object frame, so the Body is lowered in the host's frame as in #388, split into its solid parts, and each part of layer k is cut by one exact Difference with a half space per inner side of its layer, under one Instance of the host's world transform. Cutting in world coordinates is rejected: it brings back the lost coincidences of #388.
The Body is gross by default and net on explicit request, as everywhere in this ADR. A net Body whose openings fall back to world coordinates (no shared placement chain) is refused as Unsupported; a stated plane is never moved to another frame.
Outer layers extend. Only the inner boundaries cut, so the first layer with thickness keeps everything of the Body below its upper plane and the last everything above its lower plane, and the parts add up to the Body by construction. A zero-thick layer has no part. A Body thicker than its stack therefore thickens the outer layers; a strict mode that cuts at the outer boundaries and reports the remainder is not offered yet.
ifc-geometry takes a neutral LayerCut (a unit normal and ascending distances), never an ifc-material type; the join with the material usage lives in the openbim-ifc facade (material_layer_meshes). Nothing is tessellated or evaluated in the bridge (ADR 0004): lower_product_layers builds the exact graph, and compile_product_layer_meshes_with compiles each part, naming the layer a backend refuses (LayerNotSplit) once the Body itself compiles. A part with no volume compiles to an empty mesh.
Relation to existing code
ifc-geometry/src/input/openings.rs— kernel-free relation read; slot constants asserted intests/context_slots.rs(ADR 0008 pattern).ifc-geometry/src/lower/net.rs— graph construction and body splitting.ifc-geometry/src/lower/net/frame.rs— the host's frame and each opening's placement relative to it (#388).ifc-geometry/src/lower/net/boolean_body.rs— whether a Body holds a boolean or a clip (#655).ifc-geometry/src/lower/layers.rsandsrc/compile/layers.rs— the per-layer split and its meshes (#455);openbim-ifc/src/product_geometry/layer_meshes.rsjoins them with the layer bounds.ifc-geometry/src/lower/session.rs—NodeShapeside table recorded at push.ifc-geometry/src/compile.rs— net entry points and refusal attribution.- Tests:
tests/opening_subtraction_compile.rs(analytic volumes),tests/opening_attribution.rs(backend refusals named precisely),tests/net_host_frame.rs(flush openings under georeferenced sites),tests/net_clip_frame.rs(opening-less clipped bodies, #655). tests/layer_split_compile.rs(layer volumes, polarity, extension, empty parts),openbim-ifc/tests/material_layer_meshes.rs(materials, net, releases).