Skip to main content

ifc_georef/
error.rs

1//! Structured failures while resolving an IFC coordinate operation.
2
3use ifc_model::EntityId;
4
5/// Why a project-to-map operation could not be resolved losslessly.
6#[non_exhaustive]
7#[derive(Debug, Clone, PartialEq)]
8pub enum GeorefError {
9    /// An entity referenced another that the model does not contain.
10    MissingEntity {
11        /// The entity holding the dangling reference.
12        referrer: EntityId,
13        /// The id that resolved to nothing.
14        missing: EntityId,
15    },
16    /// An entity was not the IFC type the referencing slot requires.
17    WrongType {
18        /// The entity that was read.
19        entity: EntityId,
20        /// The IFC type the slot requires.
21        expected: &'static str,
22        /// The IFC type actually declared.
23        actual: String,
24    },
25    /// A mandatory attribute was absent, so the value cannot be inferred.
26    MissingAttribute {
27        /// The entity that was read.
28        entity: EntityId,
29        /// Zero-based slot index of the absent attribute.
30        index: usize,
31        /// Schema name of the attribute.
32        name: &'static str,
33    },
34    /// A value supplied to an authoring helper was not acceptable.
35    ///
36    /// Distinct from [`GeorefError::InvalidAttribute`], which names an
37    /// entity already in the model: at authoring time there is no id
38    /// yet, so the entity is named by type.
39    AuthoringInvalid {
40        /// The entity being authored.
41        entity: &'static str,
42        /// The attribute at fault.
43        attribute: &'static str,
44        /// What was supplied.
45        value: String,
46    },
47    /// An attribute was present but held the wrong kind of value.
48    InvalidAttribute {
49        /// The entity that was read.
50        entity: EntityId,
51        /// Zero-based slot index of the offending attribute.
52        index: usize,
53        /// Schema name of the attribute.
54        name: &'static str,
55    },
56    /// The coordinate operation is a subtype this crate does not resolve.
57    ///
58    /// Refused rather than approximated: a non-projected operation would
59    /// silently produce wrong map coordinates.
60    UnsupportedOperation {
61        /// The coordinate operation entity.
62        entity: EntityId,
63        /// The IFC type actually declared.
64        actual: String,
65    },
66    /// A rigid operation's coordinates are the other `SameCoordinateType`
67    /// branch than the entry point reads: plane angles given to the
68    /// project-to-map resolver, which only lowers length offsets, or
69    /// lengths given to the geographic-offset reader.
70    CoordinateMeasureMismatch {
71        /// The `IfcRigidOperation` entity.
72        entity: EntityId,
73        /// The measure type this entry point reads.
74        expected: &'static str,
75        /// The measure type both coordinates carry.
76        actual: &'static str,
77    },
78    /// The map x axis is zero-length or non-finite, so no rotation exists.
79    DegenerateAxis {
80        /// The map conversion entity.
81        entity: EntityId,
82    },
83    /// The map scale is zero, negative, or non-finite.
84    InvalidScale {
85        /// The map conversion entity.
86        entity: EntityId,
87        /// The rejected scale.
88        value: f64,
89    },
90    /// The map unit is not a length unit this crate can reduce to metres.
91    InvalidUnit {
92        /// The unit entity.
93        entity: EntityId,
94        /// Which expectation failed.
95        detail: &'static str,
96    },
97    /// A unit conversion chain revisited an entity or ran deeper than 16.
98    ///
99    /// Both guards exist: a repeated id catches a true loop, the depth cap
100    /// catches an unbounded chain of distinct units.
101    UnitCycle {
102        /// The unit entity where the walk was abandoned.
103        entity: EntityId,
104    },
105    /// The reader reported a unit record this resolution reads (#686): the
106    /// file defines its id more than once, or a lenient read skipped a record
107    /// with this id while another record holds it. The kept record cannot be
108    /// shown to be the one the file meant.
109    UnitRecordDamaged {
110        /// The reported record.
111        entity: EntityId,
112        /// Position of the first diagnostic naming it in `Model::diagnostics`.
113        diagnostic: usize,
114    },
115    /// The reader reported a record georeferencing reads other than a unit
116    /// (#690): the CRS, the coordinate operation, its source, or an IFC2X3
117    /// property set or property. The file defines its id more than once, or
118    /// a lenient read skipped a record with this id while another record
119    /// holds it. The kept record cannot be shown to be the one the file
120    /// meant.
121    RecordDamaged {
122        /// The reported record.
123        entity: EntityId,
124        /// Position of the first diagnostic naming it in `Model::diagnostics`.
125        diagnostic: usize,
126    },
127    /// The reader's diagnostics may hide a record georeferencing reads (#686,
128    /// #690): a diagnostic
129    /// of an unclassified kind, a skipped record or duplicate with no id, or
130    /// a skip naming a held id elsewhere.
131    RecordsIncomplete {
132        /// How many diagnostics the model carries.
133        diagnostics: usize,
134    },
135    /// The model header declares no `FILE_SCHEMA` token.
136    MissingSchema,
137    /// The header declares more than one schema, so the profile is ambiguous.
138    ///
139    /// Refused rather than picking one: the choice changes which coordinate
140    /// operations are legal.
141    AmbiguousSchema {
142        /// Every schema token found in the header.
143        tokens: Vec<String>,
144    },
145    /// The declared schema has no projected georeferencing profile here.
146    ///
147    /// IFC2X3 declares no georeferencing entities at all; other tokens may be
148    /// unrecognised.
149    UnsupportedSchema {
150        /// The rejected schema token.
151        token: String,
152    },
153    /// Chaining onto a project frame requires that frame to be supplied.
154    MissingProjectFrame,
155    /// The supplied project frame is not an invertible rigid transform.
156    DegenerateProjectFrame,
157    /// A direction was zero-length or non-finite, so it cannot be normalised.
158    NonFiniteDirection {
159        /// The direction entity.
160        entity: EntityId,
161    },
162    /// An entity breaks a WHERE rule or an inverse cardinality its declared
163    /// release states, such as IFC4X3 `IfcCoordinateReferenceSystem.NameOrWKT`.
164    RuleViolation {
165        /// The entity that breaks the rule.
166        entity: EntityId,
167        /// The rule's schema label, such as `NameOrWKT`.
168        rule: &'static str,
169    },
170    /// An `IfcCompoundPlaneAngleMeasure` breaks a WHERE rule of its type in
171    /// the declared release (such as IFC4 `ConsistentSign` or IFC2X3 `WR1`),
172    /// or the WGS84 range its attribute definition states.
173    InvalidCompoundAngle {
174        /// The entity holding the angle.
175        entity: EntityId,
176        /// Zero-based slot index of the angle attribute.
177        index: usize,
178        /// Schema name of the attribute, such as `RefLatitude`.
179        name: &'static str,
180        /// The rule's schema label, or the stated range that is broken.
181        rule: &'static str,
182    },
183    /// A caller-supplied number is non-finite or outside its documented
184    /// domain, such as a negative comparison tolerance.
185    InvalidParameter {
186        /// The parameter's name.
187        name: &'static str,
188        /// The rejected value.
189        value: f64,
190    },
191    /// IFC2X3 property-set georeferencing: an object carries one of
192    /// `ePSet_MapConversion` and `ePSet_ProjectedCRS` but not the other, so
193    /// it states a conversion without a CRS or a CRS without a conversion.
194    ///
195    /// Refused rather than completed from another object: a pair is never
196    /// joined across hosts.
197    IncompletePropertySets {
198        /// The `IfcProject` or `IfcSite` the present set is attached to.
199        host: EntityId,
200        /// The property set that is missing.
201        missing: &'static str,
202    },
203    /// IFC2X3 property-set georeferencing: an object carries more than one
204    /// property set of the same georeferencing name, so which one applies
205    /// is ambiguous.
206    AmbiguousPropertySets {
207        /// The `IfcProject` or `IfcSite`.
208        host: EntityId,
209        /// The repeated property-set name.
210        name: &'static str,
211        /// Every property set of that name on the host, ascending.
212        sets: Vec<EntityId>,
213    },
214    /// IFC2X3 property-set georeferencing: a property the conversion
215    /// requires is absent, or present with no `NominalValue`.
216    MissingProperty {
217        /// The `IfcPropertySet`.
218        property_set: EntityId,
219        /// The property name, such as `Eastings`.
220        name: &'static str,
221    },
222    /// IFC2X3 property-set georeferencing: a property is present but is not
223    /// an `IfcPropertySingleValue` holding the value its definition states,
224    /// such as an `Eastings` that is not a finite `IfcLengthMeasure`.
225    InvalidProperty {
226        /// The `IfcPropertySet`.
227        property_set: EntityId,
228        /// The property entity.
229        property: EntityId,
230        /// The property name.
231        name: &'static str,
232        /// What the property must hold.
233        expected: &'static str,
234    },
235}
236
237impl std::fmt::Display for GeorefError {
238    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
239        match self {
240            Self::MissingEntity { referrer, missing } => {
241                write!(f, "{referrer} references missing {missing}")
242            }
243            Self::WrongType {
244                entity,
245                expected,
246                actual,
247            } => write!(f, "{entity} is {actual}, expected {expected}"),
248            Self::MissingAttribute {
249                entity,
250                index,
251                name,
252            } => write!(f, "{entity} is missing {name} at slot {index}"),
253            Self::InvalidAttribute {
254                entity,
255                index,
256                name,
257            } => write!(f, "{entity} has invalid {name} at slot {index}"),
258            Self::AuthoringInvalid {
259                entity,
260                attribute,
261                value,
262            } => write!(f, "{entity}.{attribute}: {value}"),
263            Self::UnsupportedOperation { entity, actual } => {
264                write!(f, "{entity} uses unsupported coordinate operation {actual}")
265            }
266            Self::CoordinateMeasureMismatch {
267                entity,
268                expected,
269                actual,
270            } => write!(
271                f,
272                "{entity} has {actual} coordinates, this reader requires {expected}"
273            ),
274            Self::DegenerateAxis { entity } => {
275                write!(f, "{entity} has a zero-length or non-finite map x axis")
276            }
277            Self::InvalidScale { entity, value } => {
278                write!(f, "{entity} has invalid map scale {value}")
279            }
280            Self::InvalidUnit { entity, detail } => {
281                write!(f, "{entity} has unsupported or invalid map unit: {detail}")
282            }
283            Self::UnitCycle { entity } => {
284                write!(f, "unit conversion chain at {entity} is cyclic or too deep")
285            }
286            Self::UnitRecordDamaged { entity, diagnostic } => write!(
287                f,
288                "{entity} is a unit record the reader reported (diagnostic {diagnostic}), so the map unit is not shown"
289            ),
290            Self::RecordDamaged { entity, diagnostic } => write!(
291                f,
292                "{entity} is a record the reader reported (diagnostic {diagnostic}), so the georeferencing is not shown"
293            ),
294            Self::RecordsIncomplete { diagnostics } => write!(
295                f,
296                "{diagnostics} reader diagnostics may hide a record georeferencing reads, so it is not shown"
297            ),
298            Self::MissingSchema => {
299                write!(f, "model header declares no FILE_SCHEMA token")
300            }
301            Self::AmbiguousSchema { tokens } => {
302                write!(f, "model header declares multiple schemas: {tokens:?}")
303            }
304            Self::UnsupportedSchema { token } => {
305                write!(
306                    f,
307                    "schema {token} does not declare IFC georeferencing entities \
308                     or its coordinate-operation profile is not projected here"
309                )
310            }
311            Self::MissingProjectFrame => {
312                write!(
313                    f,
314                    "chaining a project-to-map operation onto a project frame \
315                     requires that frame to be supplied explicitly"
316                )
317            }
318            Self::DegenerateProjectFrame => {
319                write!(
320                    f,
321                    "supplied project frame is not an invertible rigid transform \
322                     (zero or non-finite determinant)"
323                )
324            }
325            Self::NonFiniteDirection { entity } => {
326                write!(f, "{entity} has a non-finite or zero-length direction")
327            }
328            Self::RuleViolation { entity, rule } => {
329                write!(f, "{entity} violates {rule}")
330            }
331            Self::InvalidCompoundAngle {
332                entity,
333                index,
334                name,
335                rule,
336            } => write!(f, "{entity} {name} at slot {index} violates {rule}"),
337            Self::InvalidParameter { name, value } => {
338                write!(f, "parameter {name} has invalid value {value}")
339            }
340            Self::IncompletePropertySets { host, missing } => {
341                write!(
342                    f,
343                    "{host} carries one georeferencing property set but not {missing}"
344                )
345            }
346            Self::AmbiguousPropertySets { host, name, sets } => {
347                write!(
348                    f,
349                    "{host} carries {} property sets named {name}: {sets:?}",
350                    sets.len()
351                )
352            }
353            Self::MissingProperty { property_set, name } => {
354                write!(
355                    f,
356                    "{property_set} has no value for required property {name}"
357                )
358            }
359            Self::InvalidProperty {
360                property_set,
361                property,
362                name,
363                expected,
364            } => write!(
365                f,
366                "{property_set} property {name} ({property}) must be {expected}"
367            ),
368        }
369    }
370}
371
372impl std::error::Error for GeorefError {}
373
374/// Result of a georeferencing read, carrying [`GeorefError`] on failure.
375pub type GeorefResult<T> = Result<T, GeorefError>;