egml_core/error.rs
1use crate::model::base::Id;
2use crate::model::geometry::DirectPosition;
3use std::fmt;
4
5/// Errors returned by `egml-core` operations.
6#[derive(Debug, PartialEq, Clone)]
7#[non_exhaustive]
8pub enum Error {
9 /// Returned when a floating-point coordinate is not finite (NaN or ±infinity).
10 ///
11 /// `axis` names the offending component (`"x"`, `"y"`, or `"z"`); `value` is
12 /// the actual non-finite number that was supplied.
13 NonFiniteCoordinate { axis: &'static str, value: f64 },
14
15 /// Returned when a collection has fewer elements than the minimum required by
16 /// the GML geometry constraint.
17 ///
18 /// Optional fields carry progressively more context: `spec` cites the ISO
19 /// clause, `id` names the offending GML object, and `detail` gives a
20 /// human-readable description of the actual content that was supplied.
21 TooFewElements {
22 geometry: &'static str,
23 minimum: usize,
24 spec: Option<&'static str>,
25 id: Option<Id>,
26 detail: Option<String>,
27 },
28
29 /// Returned when two positions that must be distinct are identical.
30 ///
31 /// Applies to [`Triangle`](crate::model::geometry::primitives::Triangle)
32 /// vertices ([OGC 07-036 §10.5.12.5](https://docs.ogc.org/is/07-036/07-036.pdf)).
33 IdenticalPositions {
34 first: DirectPosition,
35 second: DirectPosition,
36 },
37
38 /// Returned when adjacent positions in a sequence are equal.
39 ///
40 /// `index` is the zero-based index of the first position in the duplicate
41 /// pair; `position` is its value. Applies to
42 /// [`LinearRing`](crate::model::geometry::primitives::LinearRing)
43 /// ([OGC 07-036 §10.5.8](https://docs.ogc.org/is/07-036/07-036.pdf)) and
44 /// [`LineString`](crate::model::geometry::primitives::LineString)
45 /// ([OGC 07-036 §10.4.4](https://docs.ogc.org/is/07-036/07-036.pdf)).
46 AdjacentDuplicatePositions {
47 index: usize,
48 position: DirectPosition,
49 },
50
51 /// Returned when the first and last position of a ring are equal.
52 ///
53 /// `position` is the repeated vertex. A `gml:LinearRing` is implicitly
54 /// closed and must not include an explicit closing vertex ([OGC 07-036 §10.5.8](https://docs.ogc.org/is/07-036/07-036.pdf)).
55 RepeatedClosingVertex { position: DirectPosition },
56
57 /// Returned when an [`Envelope`](crate::model::geometry::Envelope) is constructed
58 /// with a lower corner that strictly exceeds the upper corner along `axis`.
59 ///
60 /// `lower` and `upper` are the actual conflicting coordinate values.
61 /// [OGC 07-036 §10.1.4.6](https://docs.ogc.org/is/07-036/07-036.pdf) requires `lowerCorner ≤ upperCorner` in every component.
62 InvalidEnvelopeBounds {
63 axis: &'static str,
64 lower: f64,
65 upper: f64,
66 },
67
68 /// Returned when
69 /// [`Envelope::to_triangulated_surface`](crate::model::geometry::Envelope::to_triangulated_surface)
70 /// is called on an envelope that is neither a surface nor a volume.
71 ///
72 /// `non_zero_extents` is the number of axes with non-zero extent (0 or 1).
73 NotSurfaceOrVolume { non_zero_extents: u8 },
74
75 /// Returned when [`Envelope::to_polygon`](crate::model::geometry::Envelope::to_polygon)
76 /// is called on an envelope that does not have exactly two non-zero extents.
77 ///
78 /// `non_zero_extents` is the actual number of axes with non-zero extent.
79 NotASurface { non_zero_extents: u8 },
80
81 /// Returned when [`Envelope::to_solid`](crate::model::geometry::Envelope::to_solid)
82 /// is called on an envelope that does not have all three extents non-zero.
83 ///
84 /// `non_zero_extents` is the actual number of axes with non-zero extent.
85 NotAVolume { non_zero_extents: u8 },
86
87 /// Returned when the earcut polygon triangulation algorithm produces no triangles.
88 ///
89 /// `context` provides additional information about which polygon or patch
90 /// could not be decomposed.
91 TriangulationFailed { context: String },
92}
93
94impl fmt::Display for Error {
95 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
96 match self {
97 Error::NonFiniteCoordinate { axis, value } => write!(
98 f,
99 "coordinate '{axis}' has non-finite value {value}; \
100 all GML coordinate values must be real numbers (OGC 07-036 §10.1.4.1)"
101 ),
102 Error::TooFewElements {
103 geometry,
104 minimum,
105 spec,
106 id,
107 detail,
108 } => {
109 write!(f, "{geometry} requires at least {minimum} element(s)")?;
110 if let Some(s) = spec {
111 write!(f, " ({s})")?;
112 }
113 if let Some(i) = id {
114 write!(f, " [id={i}]")?;
115 }
116 if let Some(d) = detail {
117 write!(f, ": {d}")?;
118 }
119 Ok(())
120 }
121 Error::IdenticalPositions { first, second } => write!(
122 f,
123 "geometry contains two identical positions {first} and {second}; \
124 all positions must be distinct (OGC 07-036 §10.5.12.5)"
125 ),
126 Error::AdjacentDuplicatePositions { index, position } => write!(
127 f,
128 "adjacent duplicate positions at index {index} ({position}); \
129 consecutive coordinates must be distinct"
130 ),
131 Error::RepeatedClosingVertex { position } => write!(
132 f,
133 "linear ring has repeated closing vertex at {position}; \
134 gml:LinearRing is implicitly closed and must not include \
135 an explicit closing vertex (OGC 07-036 §10.5.8)"
136 ),
137 Error::InvalidEnvelopeBounds { axis, lower, upper } => write!(
138 f,
139 "envelope lower.{axis}={lower} exceeds upper.{axis}={upper}; \
140 lowerCorner must be ≤ upperCorner in every component (OGC 07-036 §10.1.4.6)"
141 ),
142 Error::NotSurfaceOrVolume { non_zero_extents } => write!(
143 f,
144 "envelope has {non_zero_extents} non-zero extent(s) and cannot be triangulated; \
145 requires a surface (2 non-zero extents) or volume (3 non-zero extents)"
146 ),
147 Error::NotASurface { non_zero_extents } => write!(
148 f,
149 "envelope has {non_zero_extents} non-zero extent(s); \
150 to_polygon requires exactly 2"
151 ),
152 Error::NotAVolume { non_zero_extents } => write!(
153 f,
154 "envelope has {non_zero_extents} non-zero extent(s); \
155 to_solid requires all 3 to be non-zero"
156 ),
157 Error::TriangulationFailed { context } => {
158 write!(f, "polygon triangulation (earcut) failed: {context}")
159 }
160 }
161 }
162}
163
164impl std::error::Error for Error {}