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>;