Skip to main content

ifc_geometry/
error.rs

1//! Why interpreting a geometry entity failed.
2//!
3//! Every failure names the entity that caused it. A geometry bug in a
4//! 500k-entity file is unfindable otherwise, and "returned None" tells you
5//! nothing about which of 3,000 walls was malformed.
6
7use ifc_model::EntityId;
8use thiserror::Error;
9
10/// The result of interpreting IFC geometry.
11pub type GeometryResult<T> = Result<T, GeometryError>;
12
13/// Failures when reading or lowering IFC geometry.
14#[derive(Debug, Clone, PartialEq, Error)]
15#[non_exhaustive]
16pub enum GeometryError {
17    /// An entity referenced by an attribute is not in the model.
18    #[error("{referrer} references missing entity {missing}")]
19    MissingEntity {
20        /// The entity holding the dangling reference.
21        referrer: EntityId,
22        /// The id that does not resolve.
23        missing: EntityId,
24    },
25
26    /// An attribute slot was empty but the geometry needs it.
27    #[error("{entity} ({type_name}) has no {attribute}")]
28    MissingAttribute {
29        /// The offending entity.
30        entity: EntityId,
31        /// Its IFC type.
32        type_name: String,
33        /// Which attribute was required.
34        attribute: &'static str,
35    },
36
37    /// An attribute held a value of the wrong shape.
38    #[error("{entity} ({type_name}).{attribute}: expected {expected}, found {found}")]
39    WrongValueKind {
40        /// The offending entity.
41        entity: EntityId,
42        /// Its IFC type.
43        type_name: String,
44        /// Which attribute.
45        attribute: &'static str,
46        /// What the schema requires.
47        expected: &'static str,
48        /// What the file actually contains.
49        found: String,
50    },
51
52    /// The entity is not the type the caller assumed.
53    #[error("{entity} is {actual}, not a {expected}")]
54    WrongEntityType {
55        /// The offending entity.
56        entity: EntityId,
57        /// The type it actually has.
58        actual: String,
59        /// The type family that was required.
60        expected: &'static str,
61    },
62
63    /// A recognized IFC entity whose interpretation is not implemented.
64    ///
65    /// Distinct from [`Self::WrongEntityType`]: the file is valid and we simply
66    /// do not handle it yet. Never silently substituted with a wrong shape.
67    #[error("{type_name} ({entity}) is valid IFC but not yet interpreted: {detail}")]
68    Unsupported {
69        /// The entity in question.
70        entity: EntityId,
71        /// Its IFC type.
72        type_name: String,
73        /// What specifically is missing.
74        detail: &'static str,
75    },
76
77    /// A placement or mapped-item chain refers back to itself.
78    ///
79    /// The IFC spec pushes cycle prevention to the application layer, so real
80    /// files do contain them. Detecting beats overflowing the stack.
81    #[error("cyclic {kind} chain through {entity}")]
82    CyclicChain {
83        /// Where the cycle was detected.
84        entity: EntityId,
85        /// What kind of chain: `placement`, `mapped item`, ...
86        kind: &'static str,
87    },
88
89    /// The reader reported a unit record this resolution reads (#684): the
90    /// file defines its id more than once, or a lenient read skipped a record
91    /// with this id while another record holds it. The kept record cannot be
92    /// shown to be the one the file meant.
93    #[error("{entity} is a unit record the reader reported (diagnostic {diagnostic}), so the model's units are not shown")]
94    UnitRecordDamaged {
95        /// The reported record.
96        entity: EntityId,
97        /// Position of the first diagnostic naming it in `Model::diagnostics`.
98        diagnostic: usize,
99    },
100
101    /// The reader's diagnostics may hide a unit record (#684): a diagnostic
102    /// of an unclassified kind, a skipped record or duplicate with no id, no
103    /// `IfcProject` after a skipped record, or a skip naming a held id
104    /// elsewhere.
105    #[error("{diagnostics} reader diagnostics may hide a unit record, so the model's units are not shown")]
106    UnitsIncomplete {
107        /// How many diagnostics the model carries.
108        diagnostics: usize,
109    },
110
111    /// A chain exceeded its depth limit without closing.
112    #[error("{kind} chain through {entity} exceeded depth {limit}")]
113    ChainTooDeep {
114        /// Where the walk gave up.
115        entity: EntityId,
116        /// What kind of chain.
117        kind: &'static str,
118        /// The limit that was hit.
119        limit: usize,
120    },
121
122    /// An aggregate declared more elements than the caller's budget allows.
123    ///
124    /// IFC aggregate counts are file-controlled, so a small hostile file can
125    /// declare an enormous element count and drive a large allocation before
126    /// any geometric validation runs. This is that budget refusing, and it is
127    /// always a refusal: nothing is truncated to fit.
128    #[error("{entity} ({type_name}) declares {requested} {what}, over the limit of {limit}")]
129    AggregateTooLarge {
130        /// The offending entity.
131        entity: EntityId,
132        /// Its IFC type.
133        type_name: String,
134        /// What was being counted: `knot multiplicities`, `triangle indices`.
135        what: &'static str,
136        /// How many elements the file asked for.
137        requested: u128,
138        /// The budget that refused it.
139        limit: usize,
140    },
141
142    /// A lowered product reached the mesh or polyline compiler, which
143    /// refused it.
144    ///
145    /// Distinct from [`Self::Unsupported`]: lowering succeeded and the neutral
146    /// DAG is valid IFC meaning. What failed is *execution* -- a provider that
147    /// cannot evaluate this operation, or a budget that will not fund it. The
148    /// compiler's own reason is preserved verbatim, because it names the
149    /// missing capability precisely enough for a caller to register a provider
150    /// for it. Only reachable with the `compile` feature.
151    #[cfg(feature = "compile")]
152    #[error("{entity} could not be compiled: {reason}")]
153    CompilationRefused {
154        /// The product whose body representation was being compiled.
155        entity: EntityId,
156        /// The compiler's refusal, as reported by the provider.
157        reason: String,
158    },
159
160    /// A volume was asked of a product whose compiled body is not a solid.
161    ///
162    /// Raised by `CompiledMesh::solid_mesh` for a surface model
163    /// (`IfcShellBasedSurfaceModel`, `IfcFaceBasedSurfaceModel`) and for a
164    /// backend that does not report closure. A surface has area, not
165    /// volume; reporting the divergence sum of a closed shell the file never
166    /// declared a solid would be a plausible, wrong number.
167    #[cfg(feature = "compile")]
168    #[error("{entity} is not a solid (closure {closure:?}); it has no volume")]
169    NotASolid {
170        /// The product whose body was compiled.
171        entity: EntityId,
172        /// The closure the backend reported: `Surface` or `Unknown`.
173        closure: axiolid_mesh_compile_contract::MeshClosure,
174    },
175
176    /// A backend refused to cut one layer out of a product's Body (#455).
177    ///
178    /// Raised only for a layer split, and only when the Body itself compiles:
179    /// a refusal the Body alone would raise stays as it is. `layer` indexes
180    /// the cut's layers, so no part of the stack is dropped or merged into a
181    /// neighbour to hide it.
182    #[error("layer {layer} of {product} could not be split from its Body: {cause}")]
183    LayerNotSplit {
184        /// The layered product.
185        product: EntityId,
186        /// The first layer, as an index of the cut, the backend refused.
187        layer: usize,
188        /// Why it was refused.
189        #[source]
190        cause: Box<GeometryError>,
191    },
192
193    /// An opening that voids a host could not be subtracted from it (#44).
194    ///
195    /// Raised only when a caller asked for NET geometry. Returning the gross
196    /// body instead would make every net quantity downstream silently wrong,
197    /// so the host is refused and the opening named. `cause` says why: the
198    /// opening's body did not lower, it has no body, or the kernel refused the
199    /// subtraction.
200    #[error("opening {opening} could not be subtracted from {host}: {cause}")]
201    OpeningNotSubtracted {
202        /// The host whose net geometry was requested.
203        host: EntityId,
204        /// The voiding element that could not be removed.
205        opening: EntityId,
206        /// Why it could not be removed.
207        #[source]
208        cause: Box<GeometryError>,
209    },
210
211    /// An `IfcLinearPlacement`'s cached `CartesianPosition` disagrees with
212    /// the position its `RelativePlacement` derives (#354).
213    ///
214    /// Raised only when the caller supplied a curve evaluator and kept the
215    /// default `CachedPositionPolicy::Verify`. IFC4.3 makes the cache "an
216    /// optional fallback" for the linear expression, so a cache farther than
217    /// the model's tolerance from it is stale or wrong, and placing the
218    /// product by either would be a guess. Positions are world coordinates in
219    /// metres.
220    #[cfg(feature = "compile")]
221    #[error(
222        "{placement} (IFCLINEARPLACEMENT): the cached CartesianPosition {cached:?} is {distance} m \
223         from the position {derived:?} its RelativePlacement derives, beyond the model's \
224         tolerance of {tolerance} m"
225    )]
226    CachedPlacementMismatch {
227        /// The `IfcLinearPlacement`.
228        placement: EntityId,
229        /// The cached location, in metres.
230        cached: [f64; 3],
231        /// The derived location, in metres.
232        derived: [f64; 3],
233        /// Their distance, in metres.
234        distance: f64,
235        /// The tolerance it exceeds, in metres.
236        tolerance: f64,
237    },
238
239    /// An `IfcLinearPlacement`'s `DistanceAlong` lies on a tangent
240    /// discontinuity of its basis curve, and the caller's curve evaluator
241    /// cannot read the seam's incoming side (#409).
242    ///
243    /// IFC4.3 ADD2 8.9.3.48.3: "If DistanceAlong coincides with a point of
244    /// tangential discontinuity (within precision limits), then the tangent
245    /// of the previous segment governs." The placement is derived through
246    /// `CurveEvaluator::frame_at_on` with `SeamSide::Incoming`; an evaluator
247    /// that does not implement seam sides refuses that with
248    /// `SEAM_SIDE_UNSUPPORTED`, and the outgoing frame it could answer is
249    /// the wrong one, so the placement is refused rather than placed by it.
250    #[cfg(feature = "compile")]
251    #[error(
252        "{placement} (IFCLINEARPLACEMENT): DistanceAlong lies on a tangent discontinuity of \
253         basis curve {basis} at {distance} m, where IFC4.3 ADD2 (8.9.3.48.3) takes the tangent \
254         of the previous segment; the curve evaluator reads only the segment that starts there"
255    )]
256    SeamSideUnsupported {
257        /// The `IfcLinearPlacement`.
258        placement: EntityId,
259        /// Its basis curve.
260        basis: EntityId,
261        /// The seam's distance along the basis curve, in metres.
262        distance: f64,
263    },
264
265    /// An `IfcLinearPlacement`'s basis curve lowers to a curve relation (a
266    /// plain `IfcCompositeCurve`, an `IfcTrimmedCurve`, a composite of
267    /// segments placed at stations), and the caller's curve evaluator reads
268    /// single curves only (#418).
269    ///
270    /// The placement is derived through `CurveEvaluator::path_frame_at_on`
271    /// on the basis as a `CurvePath`; an evaluator that does not implement
272    /// curve paths refuses that with `CURVE_PATH_UNSUPPORTED`, and the
273    /// placement is refused rather than derived from one piece of the
274    /// basis.
275    #[cfg(feature = "compile")]
276    #[error(
277        "{placement} (IFCLINEARPLACEMENT): basis curve {basis} is a curve relation (pieces of \
278         curves laid end to end), and the curve evaluator evaluates single curves only"
279    )]
280    CurvePathUnsupported {
281        /// The `IfcLinearPlacement`.
282        placement: EntityId,
283        /// Its basis curve.
284        basis: EntityId,
285    },
286
287    /// A curve evaluator cannot be handed an `IfcLinearPlacement`'s basis
288    /// curve: it lowers to a curve relation holding a span whose ends its
289    /// data does not state in a form Axiolid's neutral `CurvePath` takes.
290    ///
291    /// A piece whose length is a quadrature is handed over open (#427,
292    /// axiolid/kernel#298), and a trim of an ellipse or a B-spline at an
293    /// interior parameter, a point or a forward arc length is bounded there
294    /// (#436, axiolid/kernel#304), the evaluator resolving each. What
295    /// remains has neither form: a span between distances along a relation
296    /// (a trim of it by parameters, an offset by distances along it) that
297    /// reaches a piece whose length is a quadrature other than its last, or
298    /// that reaches the last from an end that is not stated, since which
299    /// piece the span ends in is itself a quadrature; an arc-length trim of
300    /// an ellipse or a B-spline against its sense, or of a B-spline whose
301    /// parameters do not start at `0`, which is a quadrature from the
302    /// curve's start; a varying offset of such a piece; and a trim of a
303    /// relation by a Cartesian point. Only an execution provider computes
304    /// these, which this crate links none of (ADR 0004). The placement is
305    /// refused rather than derived from an estimated path. The same basis
306    /// lowers as a station, which the kernel resolves itself.
307    #[cfg(feature = "compile")]
308    #[error(
309        "{placement} (IFCLINEARPLACEMENT): basis curve {basis} holds a span whose ends lie at \
310         distances that are quadratures (a span between distances along a relation reaching a \
311         piece whose length is a quadrature, an arc-length trim of an ellipse or a B-spline \
312         against its sense); a curve path for the evaluator needs them, and only an execution \
313         provider computes them"
314    )]
315    PathPieceLengthUnstated {
316        /// The `IfcLinearPlacement`.
317        placement: EntityId,
318        /// Its basis curve.
319        basis: EntityId,
320    },
321
322    /// An `IfcLinearPlacement`'s basis curve lowers to a curve relation
323    /// holding a piece whose length is a quadrature (an offset beside a
324    /// gradient curve, a spiral, an ellipse or a B-spline, an ellipse or a
325    /// B-spline piece), handed to the evaluator as an open-ended path piece
326    /// (#427), and the caller's curve evaluator reads stated spans only.
327    ///
328    /// Such an evaluator refuses the path with `OPEN_PATH_END_UNSUPPORTED`
329    /// (axiolid/kernel#298); the placement is refused rather than derived
330    /// from a length this crate would have to estimate.
331    #[cfg(feature = "compile")]
332    #[error(
333        "{placement} (IFCLINEARPLACEMENT): basis curve {basis} holds a piece whose length is a \
334         quadrature, which the curve evaluator would have to measure itself, and it reads curve \
335         paths of stated spans only"
336    )]
337    CurvePathOpenEndUnsupported {
338        /// The `IfcLinearPlacement`.
339        placement: EntityId,
340        /// Its basis curve.
341        basis: EntityId,
342    },
343
344    /// An `IfcLinearPlacement`'s basis curve is trimmed at a point of an
345    /// ellipse or a B-spline (#436) that does not lie on the curve.
346    ///
347    /// The point reaches the evaluator as a `PathBound::Point`
348    /// (axiolid/kernel#304), which refuses it with `PATH_POINT_OFF_CURVE`
349    /// when no parameter of the curve names it within Axiolid's joint
350    /// tolerance: it is never projected onto the curve.
351    #[cfg(feature = "compile")]
352    #[error(
353        "{placement} (IFCLINEARPLACEMENT): basis curve {basis} is trimmed at a point that does \
354         not lie on its ellipse or B-spline"
355    )]
356    PathPointOffCurve {
357        /// The `IfcLinearPlacement`.
358        placement: EntityId,
359        /// Its basis curve.
360        basis: EntityId,
361    },
362
363    /// An `IfcLinearPlacement`'s basis curve is trimmed at a point of an
364    /// ellipse or a B-spline (#436) that several of its parameters name:
365    /// the curve passes through it more than once, or it is the seam of a
366    /// closed B-spline.
367    ///
368    /// The evaluator refuses the `PathBound::Point` with
369    /// `PATH_POINT_AMBIGUOUS` (axiolid/kernel#304) rather than pick one.
370    #[cfg(feature = "compile")]
371    #[error(
372        "{placement} (IFCLINEARPLACEMENT): basis curve {basis} is trimmed at a point its ellipse \
373         or B-spline passes through more than once, so the point names no one place on it"
374    )]
375    PathPointAmbiguous {
376        /// The `IfcLinearPlacement`.
377        placement: EntityId,
378        /// Its basis curve.
379        basis: EntityId,
380    },
381
382    /// An `IfcLinearPlacement`'s basis curve holds a trim of an ellipse or
383    /// a B-spline at an interior parameter or a point (#436), handed to the
384    /// evaluator as a bounded path piece, and the caller's curve evaluator
385    /// reads spans stated as distances only.
386    ///
387    /// Such an evaluator refuses the path with
388    /// `PATH_PIECE_BOUND_UNSUPPORTED` (axiolid/kernel#304); the placement
389    /// is refused rather than derived from a distance this crate would
390    /// have to estimate.
391    #[cfg(feature = "compile")]
392    #[error(
393        "{placement} (IFCLINEARPLACEMENT): basis curve {basis} is trimmed at a parameter or a \
394         point of an ellipse or a B-spline, which the curve evaluator would have to locate \
395         itself, and it reads curve paths of spans stated as distances only"
396    )]
397    CurvePathBoundUnsupported {
398        /// The `IfcLinearPlacement`.
399        placement: EntityId,
400        /// Its basis curve.
401        basis: EntityId,
402    },
403
404    /// An `IfcLinearPlacement`'s basis curve has joints after a piece whose
405    /// length is a quadrature (#427), and the caller's curve evaluator
406    /// does not certify where they lie.
407    ///
408    /// Whether `DistanceAlong` lies on such a joint within the model's
409    /// precision, where IFC4.3 ADD2 (8.9.3.48.3) takes the previous
410    /// segment, is told from `CurveEvaluator::path_joint_distances_within`
411    /// (axiolid/kernel#294, #305), the joints near it; an evaluator that
412    /// refuses it with `PATH_JOINT_DISTANCES_UNSUPPORTED` cannot tell, and
413    /// the placement is refused rather than read on an estimate.
414    #[cfg(feature = "compile")]
415    #[error(
416        "{placement} (IFCLINEARPLACEMENT): basis curve {basis} has joints after a piece whose \
417         length is a quadrature, and the curve evaluator does not certify where they lie"
418    )]
419    PathJointDistancesUnsupported {
420        /// The `IfcLinearPlacement`.
421        placement: EntityId,
422        /// Its basis curve.
423        basis: EntityId,
424    },
425
426    /// A derived `IfcLinearPlacement` on a basis with joints after a piece
427    /// whose length is a quadrature (#427): the model's precision does not
428    /// name one place along it, or the evaluator cannot certify a joint.
429    ///
430    /// The placement (or a segment of its basis placed at a station) is
431    /// read as the kernel reads the same basis's station (#423,
432    /// axiolid/kernel#294): ON the one seam whose certified distance lies
433    /// within the model's precision of `DistanceAlong`. `refusal` is
434    /// [`Ambiguous`](crate::compile::SeamWindowRefusal::Ambiguous) for two
435    /// seams within it, [`Straddled`](crate::compile::SeamWindowRefusal::Straddled)
436    /// for a seam whose certified position straddles its edge, and
437    /// [`UncertifiedLength`](crate::compile::SeamWindowRefusal::UncertifiedLength)
438    /// for a joint the evaluator cannot certify to a thousandth of it: a
439    /// piece before the window, or one reaching it, whose length it cannot
440    /// bound (#436); [`CertificationBudgetExceeded`](crate::compile::SeamWindowRefusal::CertificationBudgetExceeded)
441    /// where it can only within more panels than its budget (#443).
442    #[cfg(feature = "compile")]
443    #[error(
444        "{placement} (IFCLINEARPLACEMENT): along basis curve {basis} at {distance} m, {refusal}"
445    )]
446    PlacementSeamWindowRefused {
447        /// The `IfcLinearPlacement`.
448        placement: EntityId,
449        /// Its basis curve.
450        basis: EntityId,
451        /// The distance read, in metres: the placement's, or the station a
452        /// segment of its basis is placed at.
453        distance: f64,
454        /// What failed.
455        refusal: crate::compile::SeamWindowRefusal,
456    },
457
458    /// The kernel refused the seam-snapping window of a station lowered
459    /// on a basis whose seams lie at arc-length integrals (#423).
460    ///
461    /// Such a station carries the model's precision as a window, and the
462    /// kernel reads it on a seam within that window, from the incoming
463    /// side (IFC4.3 ADD2 8.9.3.48.3), when it resolves it
464    /// (axiolid/kernel#294). `stations` are the stations of the product's
465    /// graph lowered with a window (`ProvenanceMap::seam_windows`), each
466    /// an `IfcPointByDistanceExpression` or `IfcAxis2PlacementLinear`; the
467    /// kernel does not say which one it refused, so with several, each is
468    /// a candidate.
469    #[cfg(feature = "compile")]
470    #[error(
471        "{product}: the kernel refused the seam-snapping window of station {}: {refusal}",
472        stations.iter().map(ToString::to_string).collect::<Vec<_>>().join(", ")
473    )]
474    StationSeamWindowRefused {
475        /// The product whose graph was compiled.
476        product: EntityId,
477        /// The stations lowered with a window, ascending.
478        stations: Vec<EntityId>,
479        /// What the kernel refused.
480        refusal: crate::compile::SeamWindowRefusal,
481    },
482
483    /// The kernel refused a run whose stations carry its seam-snapping
484    /// window, lowered along a basis whose seams lie at arc-length
485    /// integrals (#429).
486    ///
487    /// Each section of such an `IfcSectionedSolidHorizontal` or
488    /// `IfcSectionedSurface` carries the model's precision as a window,
489    /// and the kernel snaps it onto a seam within it when it reads the run
490    /// (axiolid/kernel#301). `runs` are the runs of the product's graph
491    /// lowered with windows (`ProvenanceMap::seam_window_runs`), and
492    /// `stations` any single stations of the same graph lowered with one
493    /// (`ProvenanceMap::seam_windows`); the kernel does not say which it
494    /// refused, so with several, each is a candidate. Besides the window's
495    /// own refusals, `refusal` may be
496    /// [`SeamWindowRefusal::NotIncreasing`](crate::compile::SeamWindowRefusal):
497    /// two positions snapped onto one seam, or one past its neighbour; and,
498    /// for an `IfcOffsetCurveByDistances` continued to a basis end the
499    /// kernel measures (#433),
500    /// [`SeamWindowRefusal::PastBasisEnd`](crate::compile::SeamWindowRefusal):
501    /// a stated station at or past that end.
502    #[cfg(feature = "compile")]
503    #[error(
504        "{product}: the kernel refused the seam-snapping windows of run {}: {refusal}",
505        runs.iter().map(ToString::to_string).collect::<Vec<_>>().join(", ")
506    )]
507    RunSeamWindowRefused {
508        /// The product whose graph was compiled.
509        product: EntityId,
510        /// The runs lowered with windows, ascending.
511        runs: Vec<EntityId>,
512        /// The single stations lowered with a window, ascending.
513        stations: Vec<EntityId>,
514        /// What the kernel refused.
515        refusal: crate::compile::SeamWindowRefusal,
516    },
517
518    /// The two straight axes of an `IfcVirtualGridIntersection` are parallel,
519    /// so they have no intersection to place anything at (#362).
520    ///
521    /// IFC4.3 ADD2 `IfcGrid`, informal proposition: "Grid axes, which are
522    /// referenced in different lists of axes (UAxes, VAxes, WAxes) shall not
523    /// be parallel." Their offset curves are parallel too, whatever the
524    /// `OffsetDistances`.
525    #[error("{intersection} (IFCVIRTUALGRIDINTERSECTION): grid axes {} and {} are parallel", axes[0], axes[1])]
526    GridAxesParallel {
527        /// The `IfcVirtualGridIntersection`.
528        intersection: EntityId,
529        /// Its `IntersectingAxes`.
530        axes: [EntityId; 2],
531    },
532
533    /// The curved axes of an `IfcVirtualGridIntersection` meet nowhere
534    /// within their extent, or more than once (#362).
535    ///
536    /// `IfcVirtualGridIntersection.IntersectingAxes` are "two grid axes which
537    /// intersects at exactly one intersection"; picking one of two crossings,
538    /// or the nearest miss, would be a guess.
539    #[error("{intersection} (IFCVIRTUALGRIDINTERSECTION): grid axes {} and {} {detail}", axes[0], axes[1])]
540    GridAxesDoNotIntersect {
541        /// The `IfcVirtualGridIntersection`.
542        intersection: EntityId,
543        /// Its `IntersectingAxes`.
544        axes: [EntityId; 2],
545        /// Whether they miss or meet more than once.
546        detail: &'static str,
547    },
548
549    /// An `IfcGridAxis` that no `IfcGrid` lists, so it has no grid frame to
550    /// be placed in (#362).
551    ///
552    /// `IfcGridAxis` WR2: the axis is used by exactly one of `UAxes`,
553    /// `VAxes`, `WAxes` of one `IfcGrid`, whose `ObjectPlacement` positions
554    /// it ("The grid axis is positioned within the XY plane of the position
555    /// coordinate system defined by the IfcGrid").
556    #[error("grid axis {axis} belongs to no IfcGrid, so it has no placement frame")]
557    GridAxisWithoutGrid {
558        /// The `IfcGridAxis`.
559        axis: EntityId,
560    },
561
562    /// The axes one `IfcGridPlacement` names belong to different grids
563    /// (#362).
564    ///
565    /// `IfcVirtualGridIntersection`, informal proposition: both
566    /// `IntersectingAxes` "shall be two IfcGridAxis defined by the same
567    /// IfcGrid"; the same holds for the `PlacementRefDirection`
568    /// intersection. Two grids are two frames, and choosing one is a guess.
569    #[error("{intersection}: its grid axes belong to different grids, {} and {}", grids[0], grids[1])]
570    GridAxesInDifferentGrids {
571        /// The `IfcVirtualGridIntersection` (or the `IfcGridPlacement`
572        /// whose two intersections disagree).
573        intersection: EntityId,
574        /// The two grids.
575        grids: [EntityId; 2],
576    },
577
578    /// A placement's stated `PlacementRelTo` disagrees with the frame IFC4.3
579    /// ADD2 says it references (#357, #362).
580    ///
581    /// An `IfcLinearPlacement` "references the IfcObjectPlacement of the
582    /// IfcLinearPositioningElement through IfcLinearPlacement.PlacementRelTo"
583    /// (concept Product Linear Placement), and an `IfcGridPlacement`
584    /// references "the ObjectPlacement of the IfcGrid by means of
585    /// IfcObjectPlacement.PlacementRelTo". When the stated frame and the one
586    /// the basis curve's alignment (or the axes' grid) is placed in resolve
587    /// to different transforms, either answer would be a guess.
588    #[error(
589        "{placement}: PlacementRelTo {stated} resolves to a different frame than {implied}, the \
590         placement of the alignment or grid it is defined on"
591    )]
592    PlacementRelToConflict {
593        /// The `IfcLinearPlacement` or `IfcGridPlacement`.
594        placement: EntityId,
595        /// Its `PlacementRelTo`.
596        stated: EntityId,
597        /// The `ObjectPlacement` of the alignment or grid it is defined on.
598        implied: EntityId,
599    },
600
601    /// The geometry is structurally impossible.
602    ///
603    /// A degenerate direction, a zero-radius circle, a self-referencing
604    /// boolean. The file parses; the geometry does not exist.
605    #[error("{entity} ({type_name}) is geometrically invalid: {detail}")]
606    Degenerate {
607        /// The offending entity.
608        entity: EntityId,
609        /// Its IFC type.
610        type_name: String,
611        /// Why it cannot be built.
612        detail: String,
613    },
614
615    /// Units could not be resolved, so coordinates have no defined scale.
616    #[error("unit resolution failed: {0}")]
617    Units(String),
618
619    /// The model declares no length unit, so no coordinate has a scale (#585).
620    #[error("the model declares no length unit (no IfcProject, no UnitsInContext, or no LENGTHUNIT in it), so its coordinates have no scale")]
621    LengthUnitUndeclared {
622        /// The `IfcProject`, when the model has one.
623        project: Option<EntityId>,
624        /// The `IfcUnitAssignment`, when the project names one.
625        assignment: Option<EntityId>,
626    },
627
628    /// A plane angle was read, and the project declares no `PLANEANGLEUNIT`
629    /// (#585).
630    #[error("{entity} holds a plane angle, and the project declares no PLANEANGLEUNIT")]
631    AngleUnitUndeclared {
632        /// The entity whose angle has no unit.
633        entity: EntityId,
634    },
635
636    /// A declared project unit cannot be read as an exact factor (#585).
637    #[error("{unit} ({unit_type}) cannot be read: {detail}")]
638    UnitUnreadable {
639        /// The unit entity.
640        unit: EntityId,
641        /// Its `IfcUnitEnum` value, `LENGTHUNIT` or `PLANEANGLEUNIT`.
642        unit_type: &'static str,
643        /// Why it cannot be read.
644        detail: String,
645    },
646
647    /// Two candidates for one project unit (#585).
648    #[error("{first} and {second} are both the model's {kind}; IFC allows one")]
649    UnitsAmbiguous {
650        /// The first candidate.
651        first: EntityId,
652        /// The second candidate.
653        second: EntityId,
654        /// What there should be one of: `IFCPROJECT`, `LENGTHUNIT` or
655        /// `PLANEANGLEUNIT`.
656        kind: &'static str,
657    },
658
659    /// An authored value was rejected before anything was staged (ADR 0011).
660    ///
661    /// Distinct from [`Self::Degenerate`], which describes an entity that
662    /// already exists in a file. Here there is no entity yet and therefore no
663    /// id to report: the caller passed a value that could not be written.
664    #[error("cannot author {type_name}.{attribute}: {detail}")]
665    InvalidAuthoredValue {
666        /// The IFC type being authored.
667        type_name: &'static str,
668        /// The attribute whose value was rejected.
669        attribute: &'static str,
670        /// Why it cannot be written.
671        detail: String,
672    },
673
674    /// A release-aware writer could not bind one known IFC release from the
675    /// model's `FILE_SCHEMA`: it names an unrecognised release, or several.
676    ///
677    /// A model with no `FILE_SCHEMA` binds IFC4, like the other authoring
678    /// crates. Nothing is staged.
679    #[error("cannot author {type_name}: {detail}")]
680    AuthoringSchemaUnbound {
681        /// The IFC type being authored.
682        type_name: &'static str,
683        /// What the header declares instead of one known release.
684        detail: String,
685    },
686
687    /// The model's declared release does not declare the entity a
688    /// release-aware writer was asked to author. Nothing is staged.
689    #[error("{type_name} is not declared by {schema:?}")]
690    AuthoringEntityNotInSchema {
691        /// The IFC type being authored.
692        type_name: &'static str,
693        /// The bound release.
694        schema: ifc_schema::SchemaVersion,
695    },
696}
697
698mod about;
699
700#[cfg(test)]
701mod tests;