Skip to main content

ifc_geometry/lower/
dispatch.rs

1//! Total representation-item dispatch.
2//!
3//! # Why totality matters here
4//!
5//! `GeometryNode` is `#[non_exhaustive]` and the crate contract says an
6//! unknown family must become a typed `Unsupported` result, never a panic and
7//! never a silently substituted shape. This dispatcher is the single place
8//! that decides which IFC representation items are implemented, so coverage is
9//! auditable from one table instead of scattered across families.
10//!
11//! # Coverage is per release
12//!
13//! [`IMPLEMENTED`], [`PLANNED`] and [`PARTIAL`] together classify every
14//! concrete representation item of IFC4 ADD2 TC1 and IFC4X3 ADD2 that is a
15//! root item rather than nested input; `tests/schema_coverage.rs` and
16//! `tests/lower_dispatch_corpus.rs` derive both inventories from the schemas
17//! and fail on an unclassified family.
18//!
19//! # Subtypes
20//!
21//! Dispatch matches exact type names, because most subtypes change meaning
22//! (`IfcGradientCurve` is an `IfcCompositeCurve` whose segments are heights
23//! over a horizontal base curve). A subtype the supertype's lowering handles
24//! exactly is routed through [`SPECIALISATIONS`], which names the attributes
25//! it adds and why ignoring or checking them is exact.
26
27use axiolid_model::NodeId;
28use ifc_model::EntityId;
29
30use crate::error::GeometryResult;
31use crate::lower::bbox::lower_bounding_box_node;
32use crate::lower::boolean::lower_boolean_result_node;
33use crate::lower::brep::{lower_face_surface_node, lower_faceted_brep_node};
34use crate::lower::collection::lower_collection_node;
35use crate::lower::csg::{
36    lower_csg_primitive_node, lower_csg_solid_node, lower_surface_curve_swept_area_solid_node,
37    lower_swept_disk_node,
38};
39use crate::lower::curve::lower_curve_node;
40use crate::lower::halfspace::lower_half_space_node;
41use crate::lower::mapped::lower_mapped_item_node;
42use crate::lower::point::{lower_point_on_curve_node, lower_point_on_surface_node};
43use crate::lower::sectioned::{
44    lower_sectioned_solid_horizontal_node, lower_sectioned_surface_node,
45};
46use crate::lower::session::LoweringSession;
47use crate::lower::station::{lower_axis2_placement_linear_node, lower_point_by_distance_node};
48use crate::lower::surface::lower_surface_node;
49use crate::lower::swept::{
50    lower_directrix_derived_reference_sweep_node, lower_extruded_area_solid_node,
51    lower_fixed_reference_sweep_node, lower_revolved_area_solid_node, lower_sectioned_spine_node,
52    lower_tapered_extrusion_node, lower_tapered_revolution_node,
53};
54use crate::lower::tessellated::{lower_polygonal_face_set_node, lower_triangulated_face_set_node};
55use crate::select::is_a;
56use crate::transform::Transform;
57
58/// Families this crate lowers today, paired with what is still missing.
59///
60/// Kept as data so the census test can assert on it rather than re-deriving
61/// the list by scraping source text.
62pub const IMPLEMENTED: &[&str] = &[
63    "IFCEXTRUDEDAREASOLID",
64    "IFCREVOLVEDAREASOLID",
65    "IFCBOOLEANRESULT",
66    "IFCBOOLEANCLIPPINGRESULT",
67    "IFCMAPPEDITEM",
68    "IFCFACETEDBREP",
69    "IFCFACETEDBREPWITHVOIDS",
70    "IFCADVANCEDBREP",
71    "IFCADVANCEDBREPWITHVOIDS",
72    "IFCHALFSPACESOLID",
73    "IFCBOXEDHALFSPACE",
74    "IFCPOLYGONALBOUNDEDHALFSPACE",
75    "IFCTRIANGULATEDFACESET",
76    // IFC4X3: routed through SPECIALISATIONS; voids and holes are refused.
77    "IFCTRIANGULATEDIRREGULARNETWORK",
78    "IFCPOLYGONALFACESET",
79    "IFCCSGSOLID",
80    "IFCSWEPTDISKSOLID",
81    "IFCSWEPTDISKSOLIDPOLYGONAL",
82    "IFCSURFACECURVESWEPTAREASOLID",
83    "IFCBLOCK",
84    "IFCSPHERE",
85    "IFCRIGHTCIRCULARCYLINDER",
86    "IFCRIGHTCIRCULARCONE",
87    "IFCRECTANGULARPYRAMID",
88    "IFCBOUNDINGBOX",
89    "IFCEXTRUDEDAREASOLIDTAPERED",
90    "IFCREVOLVEDAREASOLIDTAPERED",
91    "IFCFIXEDREFERENCESWEPTAREASOLID",
92    // IFC4X3: tangent-only directrix; a tangent-plane directrix is refused.
93    "IFCDIRECTRIXDERIVEDREFERENCESWEPTAREASOLID",
94    "IFCSECTIONEDSPINE",
95    "IFCSHELLBASEDSURFACEMODEL",
96    "IFCFACEBASEDSURFACEMODEL",
97    // A face surface is a legal item and a member of IfcSurfaceOrFaceSurface
98    // (connection surfaces); it lowers as a single-face open BRep.
99    "IFCFACESURFACE",
100    "IFCADVANCEDFACE",
101    "IFCGEOMETRICSET",
102    "IFCGEOMETRICCURVESET",
103    // Bare curves/surfaces are valid representation items in Curve2D,
104    // Curve3D, SurfaceModel, and plan representations.
105    "IFCLINE",
106    "IFCCIRCLE",
107    "IFCELLIPSE",
108    "IFCPOLYLINE",
109    "IFCINDEXEDPOLYCURVE",
110    "IFCCOMPOSITECURVE",
111    "IFCCOMPOSITECURVEONSURFACE",
112    "IFCBOUNDARYCURVE",
113    "IFCOUTERBOUNDARYCURVE",
114    "IFCTRIMMEDCURVE",
115    "IFCOFFSETCURVE2D",
116    "IFCOFFSETCURVE3D",
117    "IFCPCURVE",
118    "IFCSURFACECURVE",
119    "IFCINTERSECTIONCURVE",
120    "IFCSEAMCURVE",
121    "IFCBSPLINECURVEWITHKNOTS",
122    "IFCRATIONALBSPLINECURVEWITHKNOTS",
123    "IFCPLANE",
124    "IFCCYLINDRICALSURFACE",
125    "IFCSPHERICALSURFACE",
126    "IFCTOROIDALSURFACE",
127    "IFCSURFACEOFLINEAREXTRUSION",
128    "IFCSURFACEOFREVOLUTION",
129    "IFCRECTANGULARTRIMMEDSURFACE",
130    "IFCCURVEBOUNDEDPLANE",
131    "IFCCURVEBOUNDEDSURFACE",
132    "IFCBSPLINESURFACEWITHKNOTS",
133    "IFCRATIONALBSPLINESURFACEWITHKNOTS",
134    "IFCPOINTONCURVE",
135    "IFCPOINTONSURFACE",
136    // IFC4X3 alignment geometry (#243): placed segments and centrelines.
137    "IFCCURVESEGMENT",
138    "IFCGRADIENTCURVE",
139    // IFC4X3 stations (#307): exact onto Axiolid's station relations
140    // (ADR 0082); `lower::station` and `lower::sectioned`.
141    "IFCPOINTBYDISTANCEEXPRESSION",
142    "IFCAXIS2PLACEMENTLINEAR",
143    "IFCOFFSETCURVEBYDISTANCES",
144    "IFCSECTIONEDSOLIDHORIZONTAL",
145    "IFCSECTIONEDSURFACE",
146];
147
148/// Recognized representation items that are not lowered yet.
149///
150/// Each entry names the concrete reason so a caller building a viewer can
151/// report progress instead of a bare failure. Adding a family here is how a
152/// stub is declared; implementing it means moving the name to [`IMPLEMENTED`].
153/// The dispatcher reports the reason in its typed `Unsupported` refusal.
154///
155/// Every entry is an IFC4X3 ADD2 family: every IFC4 ADD2 TC1 root item is
156/// lowered. Each reason is the runtime refusal text, which
157/// `tests/lower_dispatch_corpus.rs` keeps equal.
158///
159/// The IFC4X3 spirals and `IfcPolynomialCurve` are unbounded on their own;
160/// they lower exactly as the `ParentCurve` of an `IfcCurveSegment`, which is
161/// where IFC4.3 uses them.
162pub const PLANNED: &[(&str, &str)] = &[
163    // Alignment curves (IfcGeometryResource, IFC4X3); `lower::curve`.
164    ("IFCCLOTHOID", "an IfcSpiral is unbounded (-inf < u < inf) and the neutral intrinsic curve needs a \
165         finite arc length; it lowers exactly as the ParentCurve of an IfcCurveSegment"),
166    ("IFCSECONDORDERPOLYNOMIALSPIRAL", "an IfcSpiral is unbounded (-inf < u < inf) and the neutral intrinsic curve needs a \
167         finite arc length; it lowers exactly as the ParentCurve of an IfcCurveSegment"),
168    ("IFCTHIRDORDERPOLYNOMIALSPIRAL", "an IfcSpiral is unbounded (-inf < u < inf) and the neutral intrinsic curve needs a \
169         finite arc length; it lowers exactly as the ParentCurve of an IfcCurveSegment"),
170    ("IFCSEVENTHORDERPOLYNOMIALSPIRAL", "an IfcSpiral is unbounded (-inf < u < inf) and the neutral intrinsic curve needs a \
171         finite arc length; it lowers exactly as the ParentCurve of an IfcCurveSegment"),
172    ("IFCCOSINESPIRAL", "an IfcCosineSpiral or IfcSineSpiral law depends on the length L of the IfcCurveSegment \
173         using it; it lowers exactly only as the ParentCurve of an IfcCurveSegment"),
174    ("IFCSINESPIRAL", "an IfcCosineSpiral or IfcSineSpiral law depends on the length L of the IfcCurveSegment \
175         using it; it lowers exactly only as the ParentCurve of an IfcCurveSegment"),
176    ("IFCPOLYNOMIALCURVE", "an IfcPolynomialCurve is unbounded (-inf < u < inf) and the neutral vocabulary has no \
177         unbounded polynomial curve; it lowers exactly as the ParentCurve of an IfcCurveSegment"),
178    ("IFCSEGMENTEDREFERENCECURVE", "IfcSegmentedReferenceCurve segments are curves in the (distance along, deviating elevation) \
179         space of its base curve, and no normative rule maps a segment's ParentCurve and placement \
180         Axis to a cant law and pivot: implementations differ in the coefficient scaling (cant \
181         kappa*L or kappa*L^2) and the cross slope (sine or tangent of cant over rail head \
182         distance); the business cant layout lowers to a banked curve through ifc-alignment (#311)"),
183];
184
185/// A subtype the supertype's lowering handles exactly.
186///
187/// Routing a subtype to its supertype's lowerer is exact only when every
188/// attribute and rule the subtype adds either leaves the shape unchanged or
189/// is checked by that lowerer. `tests/schema_coverage.rs` asserts each row
190/// against the IFC4X3 schema: the subtype relation, the added attributes,
191/// and that both names are in [`IMPLEMENTED`].
192#[derive(Debug, Clone, Copy, PartialEq, Eq)]
193pub struct Specialisation {
194    /// The subtype as a STEP type name.
195    pub subtype: &'static str,
196    /// The supertype whose lowering it is routed to.
197    pub supertype: &'static str,
198    /// The explicit attributes the subtype declares, in schema order.
199    pub added_attributes: &'static [&'static str],
200    /// Why the supertype's lowering is exact for it.
201    pub rationale: &'static str,
202}
203
204/// Subtypes routed to their supertype's lowering.
205pub const SPECIALISATIONS: &[Specialisation] = &[Specialisation {
206    subtype: "IFCTRIANGULATEDIRREGULARNETWORK",
207    supertype: "IFCTRIANGULATEDFACESET",
208    added_attributes: &["Flags"],
209    rationale: "the face-set slots are unchanged; the lowerer checks Flags \
210                and refuses voids, holes and undocumented codes, so only \
211                breakline codes, which leave the triangles unchanged, lower",
212}];
213
214/// A variant within a family that is admitted or refused independently.
215///
216/// [`IMPLEMENTED`] and [`PLANNED`] classify at *family* granularity, which is
217/// too coarse for families whose support depends on how the instance is
218/// authored. `IFCPCURVE` is implemented, but only for some reference-curve
219/// forms; a flat "implemented" claim hides the refusals inside it.
220#[derive(Debug, Clone, Copy, PartialEq, Eq)]
221pub struct Variant {
222    /// The concrete family this variant belongs to; always in [`IMPLEMENTED`].
223    pub family: &'static str,
224    /// The distinguishing condition, as a caller would recognize it.
225    pub variant: &'static str,
226    /// Whether this specific variant lowers or is a typed refusal.
227    pub support: Support,
228    /// Why it is admitted or refused. Refusals name the missing contract.
229    pub rationale: &'static str,
230}
231
232/// Whether a [`Variant`] lowers exactly or reports a typed refusal.
233#[derive(Debug, Clone, Copy, PartialEq, Eq)]
234#[non_exhaustive]
235pub enum Support {
236    /// Lowers exactly, with no approximation.
237    Admitted,
238    /// Reports a typed [`crate::GeometryError::Unsupported`] naming the entity.
239    Refused,
240}
241
242/// Variant-level dispositions for partially supported families.
243///
244/// Every family named here must appear in [`IMPLEMENTED`] and must declare at
245/// least one `Admitted` and one `Refused` variant -- a family with no refusals
246/// is not partial and belongs in `IMPLEMENTED` alone. Enforced by
247/// `tests/lower_dispatch_corpus.rs`.
248pub const PARTIAL: &[Variant] = &[
249    Variant {
250        family: "IFCPCURVE",
251        variant: "reference curve is an IfcPolyline",
252        support: Support::Admitted,
253        rationale: "an ordered 2D point sequence needs no evaluation",
254    },
255    Variant {
256        family: "IFCPCURVE",
257        variant: "reference curve is an IfcIndexedPolyCurve with no explicit \
258                  Segments, or only IfcLineIndex segments",
259        support: Support::Admitted,
260        rationale: "reads identically to a plain ordered point sequence",
261    },
262    Variant {
263        family: "IFCPCURVE",
264        variant: "reference curve is an IfcLine, IfcCircle or IfcEllipse \
265                  positioned by an IfcAxis2Placement2D",
266        support: Support::Admitted,
267        rationale: "defining values are read verbatim in the surface's own \
268                    (u, v) domain with no unit conversion",
269    },
270    Variant {
271        family: "IFCPCURVE",
272        variant: "reference conic positioned by an IfcAxis2Placement3D",
273        support: Support::Refused,
274        rationale: "a 3D placement's axis has no meaning in a 2D parameter \
275                    domain; admitting it would require inventing a projection",
276    },
277    Variant {
278        family: "IFCPCURVE",
279        variant: "reference curve is an IfcIndexedPolyCurve with an explicit \
280                  IfcArcIndex segment",
281        support: Support::Admitted,
282        rationale: "a three-point arc composes exactly from a parameter-space \
283                    circumcentre into Circle2 plus a Cartesian trim, mirroring \
284                    the 3D path with no approximation",
285    },
286    Variant {
287        family: "IFCPCURVE",
288        variant: "reference curve is an explicit-knot IfcBSplineCurveWithKnots \
289                  or IfcRationalBSplineCurveWithKnots",
290        support: Support::Admitted,
291        rationale: "every field is dimensionless or a curve parameter; knots \
292                    already pass through the 3D path unscaled, and control \
293                    points are read as raw (u, v) pairs",
294    },
295    Variant {
296        family: "IFCPCURVE",
297        variant: "reference curve is a trimmed or composite curve",
298        support: Support::Admitted,
299        rationale: "trim parameters and segments stay in the surface (u, v) \
300                    domain, unscaled, so no dimensional contract is needed",
301    },
302    Variant {
303        family: "IFCPCURVE",
304        variant: "reference curve is a convention-only IfcBSplineCurve",
305        support: Support::Refused,
306        rationale: "a base spline carries no authored knot vector to preserve",
307    },
308    Variant {
309        family: "IFCDIRECTRIXDERIVEDREFERENCESWEPTAREASOLID",
310        variant: "directrix defines only a tangent (no IfcCurveSegment, \
311                  segment-built or surface curve reachable)",
312        support: Support::Admitted,
313        rationale: "IFC4.3 gives it exactly the behaviour of \
314                    IfcFixedReferenceSweptAreaSolid in this case, so it lowers \
315                    to the same FixedReferenceSweep",
316    },
317    Variant {
318        family: "IFCDIRECTRIXDERIVEDREFERENCESWEPTAREASOLID",
319        variant: "directrix defines a tangent plane",
320        support: Support::Refused,
321        rationale: "kernel: the directrix defines a tangent plane (it is built from \
322                    IfcCurveSegment placements or lies on a surface), so the derived \
323                    reference adds that plane's rotation to FixedReference; the neutral \
324                    FixedReferenceSweep carries only a constant reference direction",
325    },
326    Variant {
327        family: "IFCTRIANGULATEDIRREGULARNETWORK",
328        variant: "every Flags value is a breakline code, 0 to 7",
329        support: Support::Admitted,
330        rationale: "a breakline marks an edge the triangulation already has, \
331                    so the triangle surface is the supertype's; the flags \
332                    are not carried into the mesh",
333    },
334    Variant {
335        family: "IFCTRIANGULATEDIRREGULARNETWORK",
336        variant: "a Flags value is -1 (hole) or -2 (void)",
337        support: Support::Refused,
338        rationale: "the triangle is excluded from the surface, and a hole may \
339                    fall back on another surface; the neutral mesh has no \
340                    face-exclusion or fall-back channel",
341    },
342    Variant {
343        family: "IFCTRIANGULATEDIRREGULARNETWORK",
344        variant: "a Flags value is outside -2 to 7",
345        support: Support::Refused,
346        rationale: "the documentation defines no meaning for it",
347    },
348    Variant {
349        family: "IFCSURFACECURVE",
350        variant: "MasterRepresentation is Curve3D, PCurveS1, or PCurveS2 with \
351                  the named side present",
352        support: Support::Admitted,
353        rationale: "each side pairs a surface with its own p-curve, so the \
354                    neutral MasterRepresentation names S1 and S2 exactly",
355    },
356    Variant {
357        family: "IFCCURVESEGMENT",
358        variant: "ParentCurve is an IfcLine, IfcCircle or 2D IfcPolyline, \
359                  measured by IfcLengthMeasure",
360        support: Support::Admitted,
361        rationale: "a line, arc or polyline cut by arc length and placed rigidly \
362                    is elementary: a polyline or an angle-trimmed circle",
363    },
364    Variant {
365        family: "IFCCURVESEGMENT",
366        variant: "ParentCurve is an IfcSpiral subtype, measured by \
367                  IfcLengthMeasure",
368        support: Support::Admitted,
369        rationale: "the spiral's curvature law, rebased to the segment in closed \
370                    form, on a planar intrinsic curve; nothing is integrated",
371    },
372    Variant {
373        family: "IFCCURVESEGMENT",
374        variant: "SegmentLength is zero (the closing segment of a layout)",
375        support: Support::Admitted,
376        rationale: "its placement exactly: a planar intrinsic curve of length zero",
377    },
378    Variant {
379        family: "IFCCURVESEGMENT",
380        variant: "ParentCurve is a 2D IfcPolynomialCurve with a degree-one \
381                  coordinate, cut forwards from SegmentStart 0",
382        support: Support::Admitted,
383        rationale: "its Bezier over a closed-form parameter bound, placed \
384                    rigidly and trimmed at TrimSelector::ArcLength: the kernel \
385                    inverts the arc length, nothing is integrated here",
386    },
387    Variant {
388        family: "IFCCURVESEGMENT",
389        variant: "ParentCurve is an IfcPolynomialCurve cut from a non-zero \
390                  SegmentStart, walked backwards, 3D, or with no degree-one \
391                  coordinate",
392        support: Support::Refused,
393        rationale: "the placed start point inverts a non-elementary arc-length \
394                    integral, a 3D polynomial has no plane for the placement, \
395                    and without a degree-one coordinate the trim has no \
396                    closed-form parameter bound",
397    },
398    Variant {
399        family: "IFCCURVESEGMENT",
400        variant: "SegmentStart or SegmentLength is an IfcParameterValue",
401        support: Support::Refused,
402        rationale: "SegmentStart/SegmentLength given as IfcParameterValue: IFC4.3 ADD2 defines no parametric \
403         space for IfcCurveSegment parents yet (informal proposition 1 requires IfcLengthMeasure)",
404    },
405    Variant {
406        family: "IFCCURVESEGMENT",
407        variant: "Placement is an IfcAxis2PlacementLinear, the segment met on its \
408                  own or in a plain IfcCompositeCurve",
409        support: Support::Admitted,
410        rationale: "an InstanceAtStation: the parent's piece in local coordinates \
411                    placed in the frame of the OrientedCurveStation the placement \
412                    lowers to, local X, Y, Z on the station's tangent, left and up \
413                    as 8.9.3.4 reads them; the kernel resolves the station",
414    },
415    Variant {
416        family: "IFCCURVESEGMENT",
417        variant: "Placement is an IfcAxis2PlacementLinear in an IfcGradientCurve",
418        support: Support::Refused,
419        rationale: "an IfcAxis2PlacementLinear placement stands at a station along a basis curve, which only a \
420     kernel resolves; a segment of an IfcGradientCurve is read as a plan or profile piece and \
421     needs a resolved placement",
422    },
423    Variant {
424        family: "IFCGRADIENTCURVE",
425        variant: "horizontal IfcCurveSegments over lines, arcs, spirals and \
426                  2D IfcPolynomialCurves; vertical IfcCurveSegments over \
427                  IfcLine, IfcCircle, an IfcSpiral subtype, or a degree-2 \
428                  IfcPolynomialCurve that keeps its start tangent",
429        support: Support::Admitted,
430        rationale: "one plan parameterised by arc length (an intrinsic curve, \
431                    or an arc-length chain with a polynomial piece) plus a \
432                    piecewise elevation law of polynomial, circular and \
433                    intrinsic pieces: Curve3::Elevated, exact",
434    },
435    Variant {
436        family: "IFCGRADIENTCURVE",
437        variant: "a vertical parabola or spiral with no following segment, \
438                  closing segment or EndPoint",
439        support: Support::Refused,
440        rationale: "its plan extent inverts a non-elementary arc-length \
441                    integral, and nothing states it",
442    },
443    Variant {
444        family: "IFCGRADIENTCURVE",
445        variant: "a heading kink, a closed-form position gap, or a profile \
446                  that does not span the base curve",
447        support: Support::Refused,
448        rationale: "one plan curve and one elevation law cannot carry a kink or \
449                    a gap, and an elevation law must cover the whole plan",
450    },
451    Variant {
452        family: "IFCGRADIENTCURVE",
453        variant: "placed by a frame that tilts, scales or mirrors the vertical",
454        support: Support::Refused,
455        rationale: "a plan plus a height is carried only by frames that keep \
456                    the vertical axis",
457    },
458    Variant {
459        family: "IFCPOINTBYDISTANCEEXPRESSION",
460        variant: "DistanceAlong is an IfcLengthMeasure on the basis curve, on or \
461                  off its tangent discontinuities",
462        support: Support::Admitted,
463        rationale: "a CurveStation: distance (plan distance on a gradient curve, arc \
464                    length otherwise) and the lateral (left), vertical and \
465                    longitudinal offsets, in the same frame IFC4.3 ADD2 8.9.3.48 \
466                    states; within precision of a seam, at the seam reading \
467                    SeamSide::Incoming, since the previous segment's tangent \
468                    governs (8.9.3.48.3)",
469    },
470    Variant {
471        family: "IFCPOINTBYDISTANCEEXPRESSION",
472        variant: "DistanceAlong is an IfcParameterValue",
473        support: Support::Refused,
474        rationale: "IFC4.3 ADD2 gives most basis curves no parameterisation a \
475                    distance can be read from, and a neutral station is a distance",
476    },
477    Variant {
478        family: "IFCPOINTBYDISTANCEEXPRESSION",
479        variant: "DistanceAlong on a composite, trimmed or surface curve, or on \
480                  segments placed at stations, whose pieces' lengths are stated \
481                  by their data",
482        support: Support::Admitted,
483        rationale: "a station along the curve relation, measured end to end \
484                    through its pieces (axiolid/kernel#285); every joint is a \
485                    seam, and within precision of one the station stands on it \
486                    reading SeamSide::Incoming, the previous segment \
487                    (8.9.3.48.3)",
488    },
489    Variant {
490        family: "IFCPOINTBYDISTANCEEXPRESSION",
491        variant: "DistanceAlong on a basis whose tangent discontinuities lie at \
492                  arc-length integrals: an offset whose length is a quadrature \
493                  (beside a gradient curve, a spiral, a B-spline or an ellipse, \
494                  or a variable offset of a circle), a relation with an ellipse \
495                  or a B-spline piece, a B-spline with a corner knot",
496        support: Support::Admitted,
497        rationale: "an OrientedCurveStation at its own distance reading \
498                    SeamSide::Incoming, with the model's precision as its \
499                    seam-snapping window (axiolid/kernel#294, #423): the kernel \
500                    reads it on a seam within the window, from the previous \
501                    segment (8.9.3.48.3), at its own certified distance, and \
502                    refuses two seams in the window, a seam on its edge and a \
503                    length it cannot certify by name",
504    },
505    Variant {
506        family: "IFCPOINTBYDISTANCEEXPRESSION",
507        variant: "DistanceAlong on an IfcOffsetCurve2D/3D or an \
508                  IfcOffsetCurveByDistances of lines, polylines or circles (a \
509                  constant offset of a circle in its plane)",
510        support: Support::Admitted,
511        rationale: "a station along the offset relation, in the offset's own \
512                    length (axiolid/kernel#289); every seam of the basis and \
513                    every OffsetValues station is a joint, and within precision \
514                    of one the station stands on it reading \
515                    SeamSide::Incoming, the previous segment (8.9.3.48.3); IFC's \
516                    positive Distance (anticlockwise normal) is Axiolid's left",
517    },
518    Variant {
519        family: "IFCPOINTBYDISTANCEEXPRESSION",
520        variant: "DistanceAlong on an offset of an offset, a trim of an offset, \
521                  an offset through a circle's centre, or an offset across a \
522                  corner of its basis",
523        support: Support::Refused,
524        rationale: "kernel: Axiolid measures a station along an offset of atomic \
525                    pieces whose sides meet, in its own length",
526    },
527    Variant {
528        family: "IFCPOINTBYDISTANCEEXPRESSION",
529        variant: "DistanceAlong on a relation joining gradient curves with other \
530                  pieces",
531        support: Support::Refused,
532        rationale: "kernel: no one distance runs through pieces measured in plan \
533                    distance and in arc length",
534    },
535    Variant {
536        family: "IFCAXIS2PLACEMENTLINEAR",
537        variant: "Axis and RefDirection absent, or 3D and not parallel",
538        support: Support::Admitted,
539        rationale: "an OrientedCurveStation: the ratios are components in the \
540                    curve's (tangent, left, up) frame, Axis exact and RefDirection \
541                    orthogonalised against it, as 8.9.3.4 states",
542    },
543    Variant {
544        family: "IFCAXIS2PLACEMENTLINEAR",
545        variant: "Location is refused as an IfcPointByDistanceExpression",
546        support: Support::Refused,
547        rationale: "the placement is its station; see IFCPOINTBYDISTANCEEXPRESSION",
548    },
549    Variant {
550        family: "IFCOFFSETCURVEBYDISTANCES",
551        variant: "OffsetValues along its own BasisCurve, spanning it or on a basis \
552                  with a stated length, across its tangent discontinuities too",
553        support: Support::Admitted,
554        rationale: "OffsetByStations, linear between the offsets; a span short of the \
555                    ends is carried on unchanged to them by added stations, as \
556                    8.9.3.42.3 states; mitred at a seam like the sweeps on the \
557                    same stations (8.8.3.35.1)",
558    },
559    Variant {
560        family: "IFCOFFSETCURVEBYDISTANCES",
561        variant: "OffsetValues short of the ends of a bounded basis whose length \
562                  lies at an arc-length integral (an offset beside a gradient \
563                  curve, a spiral, a B-spline or an ellipse, a relation with an \
564                  ellipse or a B-spline piece, a B-spline or an ellipse)",
565        support: Support::Admitted,
566        rationale: "OffsetsAtStations continued by stations at the basis's start \
567                    and end, whose distances the kernel measures \
568                    (RunStation::at_basis_start / at_basis_end, \
569                    axiolid/kernel#303, #433), as 8.9.3.42.3 states; stations \
570                    carry the kernel's seam-snapping window where the seams are \
571                    quadratures (#429); a stated station at or past the end the \
572                    kernel measures is refused by it by name",
573    },
574    Variant {
575        family: "IFCOFFSETCURVEBYDISTANCES",
576        variant: "offsets short of an unbounded end, a non-zero \
577                  OffsetLongitudinal, a member on another basis, or a run \
578                  across a seam where the basis turns back on itself",
579        support: Support::Refused,
580        rationale: "an unbounded line has no end to continue the offsets to and \
581                    the neutral offset curve stops at its last station, IFC \
582                    states no law for a longitudinal offset along a curve, and a \
583                    mitre has no plane at a reversal",
584    },
585    Variant {
586        family: "IFCSECTIONEDSOLIDHORIZONTAL",
587        variant: "area sections at positions along the Directrix, across its \
588                  tangent discontinuities too",
589        support: Support::Admitted,
590        rationale: "SectionsAtStations in the curve's frame, matched by ring and \
591                    index; RefDirection is the profile normal and Axis profile Y \
592                    (IFC4.x-IF#147, IFC4.x-development#1010); a seam is mitred at \
593                    half angle (8.8.3.35.1)",
594    },
595    Variant {
596        family: "IFCSECTIONEDSOLIDHORIZONTAL",
597        variant: "area sections along a Directrix whose seams lie at arc-length \
598                  integrals (an offset beside a gradient curve, a spiral, a \
599                  B-spline or an ellipse, or a B-spline corner knot)",
600        support: Support::Admitted,
601        rationale: "each section carries the model's precision as the kernel's \
602                    seam-snapping window, reading SeamSide::Incoming \
603                    (axiolid/kernel#301, #429): the kernel snaps it onto a seam \
604                    within the window and mitres there at half angle \
605                    (8.8.3.35.1), and refuses two seams in a window, a seam on \
606                    its edge, a length it cannot certify and positions no longer \
607                    increasing once snapped by name",
608    },
609    Variant {
610        family: "IFCSECTIONEDSOLIDHORIZONTAL",
611        variant: "positions off the Directrix, or spanning a seam where it turns \
612                  back on itself",
613        support: Support::Refused,
614        rationale: "a station measures along its own basis, and \"very sharp \
615                    edges may result in nearly impossible miter\" (8.8.3.35.1)",
616    },
617    Variant {
618        family: "IFCSECTIONEDSURFACE",
619        variant: "open sections tagged throughout or not at all, with one tag set",
620        support: Support::Admitted,
621        rationale: "OpenSectionsAtStations joined by tag, forwards or reversed; \
622                    profile X to the left as IfcOpenCrossProfileDef states \
623                    (8.15.3.15.1, #344)",
624    },
625    Variant {
626        family: "IFCSECTIONEDSURFACE",
627        variant: "open sections along a Directrix whose seams lie at arc-length \
628                  integrals",
629        support: Support::Admitted,
630        rationale: "as IFCSECTIONEDSOLIDHORIZONTAL: each section carries the \
631                    kernel's seam-snapping window and the incoming side \
632                    (axiolid/kernel#301, #429), mitred at half angle where it \
633                    snaps (8.8.3.37.1)",
634    },
635    Variant {
636        family: "IFCSECTIONEDSURFACE",
637        variant: "mixed tagging or branching breaklines (sections with different \
638                  Tags)",
639        support: Support::Refused,
640        rationale: "the neutral surface joins one tag set through every section",
641    },
642    Variant {
643        family: "IFCSURFACECURVE",
644        variant: "MasterRepresentation is PCurveS2 with only one associated \
645                  p-curve",
646        support: Support::Refused,
647        rationale: "the master names a parametric side the curve does not \
648                    have; the schema calls this inconsistent, so it is \
649                    refused rather than resolved to the remaining p-curve",
650    },
651];
652
653/// Lower any representation item into the caller's session.
654///
655/// Returns the node for implemented families and a typed
656/// [`crate::GeometryError::Unsupported`] naming the source entity otherwise.
657pub fn lower_representation_item(
658    session: &mut LoweringSession<'_>,
659    id: EntityId,
660    frame: Transform,
661) -> GeometryResult<NodeId> {
662    let type_name = session.type_name(id)?;
663    // IFC4X3 sectioned surface, routed before the inheritance test so the
664    // named refusal holds whether or not the subtype table knows the type.
665    if type_name == "IFCSECTIONEDSURFACE" {
666        return lower_sectioned_surface_node(session, id, frame);
667    }
668    // An exact specialisation lowers through its supertype's arm. The
669    // refusal below still names the entity's own type.
670    let routed = SPECIALISATIONS
671        .iter()
672        .find(|row| row.subtype == type_name)
673        .map_or(type_name.as_str(), |row| row.supertype);
674    // Shape representations may legitimately contain bare curve and surface
675    // items (Curve2D/Curve3D/SurfaceModel). Route by generated IFC inheritance
676    // before the concrete solid table so plan and surface selections lower
677    // through the same total entry point as body geometry.
678    if is_a(&type_name, "IFCCURVE") {
679        return lower_curve_node(session, id, frame);
680    }
681    if is_a(&type_name, "IFCSURFACE") {
682        return lower_surface_node(session, id, frame);
683    }
684    match routed {
685        "IFCEXTRUDEDAREASOLID" => lower_extruded_area_solid_node(session, id, frame),
686        "IFCREVOLVEDAREASOLID" => lower_revolved_area_solid_node(session, id, frame),
687        "IFCBOOLEANRESULT" | "IFCBOOLEANCLIPPINGRESULT" => {
688            lower_boolean_result_node(session, id, frame)
689        }
690        "IFCHALFSPACESOLID" | "IFCBOXEDHALFSPACE" | "IFCPOLYGONALBOUNDEDHALFSPACE" => {
691            lower_half_space_node(session, id, frame)
692        }
693        "IFCMAPPEDITEM" => lower_mapped_item_node(session, id, frame),
694        // `IfcCurveSegment` is an IfcSegment, not an IfcCurve, so the
695        // inheritance test above does not route it; the curve module lowers
696        // it. The IFC4X3 curves themselves route by inheritance (#293).
697        "IFCCURVESEGMENT" => lower_curve_node(session, id, frame),
698        "IFCPOINTONCURVE" => lower_point_on_curve_node(session, id, frame),
699        "IFCPOINTONSURFACE" => lower_point_on_surface_node(session, id, frame),
700        "IFCFACETEDBREP"
701        | "IFCFACETEDBREPWITHVOIDS"
702        | "IFCADVANCEDBREP"
703        | "IFCADVANCEDBREPWITHVOIDS" => lower_faceted_brep_node(session, id, frame),
704        "IFCFACESURFACE" | "IFCADVANCEDFACE" => lower_face_surface_node(session, id, frame),
705        "IFCTRIANGULATEDFACESET" => lower_triangulated_face_set_node(session, id, frame),
706        "IFCPOLYGONALFACESET" => lower_polygonal_face_set_node(session, id, frame),
707        "IFCCSGSOLID" => lower_csg_solid_node(session, id, frame),
708        "IFCSWEPTDISKSOLID" | "IFCSWEPTDISKSOLIDPOLYGONAL" => {
709            lower_swept_disk_node(session, id, frame)
710        }
711        "IFCSURFACECURVESWEPTAREASOLID" => {
712            lower_surface_curve_swept_area_solid_node(session, id, frame)
713        }
714        "IFCBOUNDINGBOX" => lower_bounding_box_node(session, id, frame),
715        "IFCEXTRUDEDAREASOLIDTAPERED" => lower_tapered_extrusion_node(session, id, frame),
716        "IFCREVOLVEDAREASOLIDTAPERED" => lower_tapered_revolution_node(session, id, frame),
717        "IFCFIXEDREFERENCESWEPTAREASOLID" => lower_fixed_reference_sweep_node(session, id, frame),
718        "IFCDIRECTRIXDERIVEDREFERENCESWEPTAREASOLID" => {
719            lower_directrix_derived_reference_sweep_node(session, id, frame)
720        }
721        "IFCSECTIONEDSOLIDHORIZONTAL" => lower_sectioned_solid_horizontal_node(session, id, frame),
722        "IFCPOINTBYDISTANCEEXPRESSION" => lower_point_by_distance_node(session, id, frame),
723        "IFCAXIS2PLACEMENTLINEAR" => lower_axis2_placement_linear_node(session, id, frame),
724        "IFCSECTIONEDSPINE" => lower_sectioned_spine_node(session, id, frame),
725        "IFCSHELLBASEDSURFACEMODEL"
726        | "IFCFACEBASEDSURFACEMODEL"
727        | "IFCGEOMETRICSET"
728        | "IFCGEOMETRICCURVESET" => lower_collection_node(session, id, frame),
729        "IFCBLOCK"
730        | "IFCSPHERE"
731        | "IFCRIGHTCIRCULARCYLINDER"
732        | "IFCRIGHTCIRCULARCONE"
733        | "IFCRECTANGULARPYRAMID" => lower_csg_primitive_node(session, id, frame),
734        _ => Err(session.unsupported(id, &type_name, detail_for(&type_name))),
735    }
736}
737
738/// The documented reason a recognized family is not lowered yet.
739fn detail_for(type_name: &str) -> &'static str {
740    planned_detail(type_name).unwrap_or("representation item family is not lowered yet")
741}
742
743/// The documented [`PLANNED`] reason for a family, if it has one.
744///
745/// Shared with the curve lowerer: once the subtype table routes
746/// an IFC4X3 curve there by inheritance (#293), the ledger's reason must
747/// still be the one reported.
748pub(crate) fn planned_detail(type_name: &str) -> Option<&'static str> {
749    PLANNED
750        .iter()
751        .find(|(name, _)| *name == type_name)
752        .map(|(_, detail)| *detail)
753}
754
755#[cfg(test)]
756mod tests;