nom_exif/exif/
gps.rs

1use std::str::FromStr;
2
3use iso6709parse::ISO6709Coord;
4
5use crate::values::{IRational, URational};
6
7/// Parsed GPS information from the GPSInfo subIFD.
8#[derive(Debug, Clone, PartialEq, Eq)]
9pub struct GPSInfo {
10    pub latitude_ref: LatRef,
11    pub latitude: LatLng,
12    pub longitude_ref: LonRef,
13    pub longitude: LatLng,
14    pub altitude: Altitude,
15    pub speed: Option<Speed>,
16}
17
18impl Default for GPSInfo {
19    fn default() -> Self {
20        Self {
21            latitude_ref: LatRef::North,
22            latitude: LatLng::default(),
23            longitude_ref: LonRef::East,
24            longitude: LatLng::default(),
25            altitude: Altitude::Unknown,
26            speed: None,
27        }
28    }
29}
30
31/// Latitude or longitude expressed as degrees / minutes / seconds.
32#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
33pub struct LatLng {
34    pub degrees: URational,
35    pub minutes: URational,
36    pub seconds: URational,
37}
38
39/// Latitude hemisphere reference.
40#[derive(Debug, Clone, Copy, PartialEq, Eq)]
41pub enum LatRef {
42    North,
43    South,
44}
45
46impl LatRef {
47    /// Construct from the 'N' / 'S' character carried in EXIF GPSLatitudeRef.
48    pub fn from_char(c: char) -> Option<Self> {
49        match c {
50            'N' | 'n' => Some(Self::North),
51            'S' | 's' => Some(Self::South),
52            _ => None,
53        }
54    }
55
56    pub fn as_char(self) -> char {
57        match self {
58            Self::North => 'N',
59            Self::South => 'S',
60        }
61    }
62
63    /// +1.0 or -1.0 — useful when assembling decimal-degrees latitude.
64    pub fn sign(self) -> f64 {
65        match self {
66            Self::North => 1.0,
67            Self::South => -1.0,
68        }
69    }
70}
71
72/// Longitude hemisphere reference.
73#[derive(Debug, Clone, Copy, PartialEq, Eq)]
74pub enum LonRef {
75    East,
76    West,
77}
78
79impl LonRef {
80    pub fn from_char(c: char) -> Option<Self> {
81        match c {
82            'E' | 'e' => Some(Self::East),
83            'W' | 'w' => Some(Self::West),
84            _ => None,
85        }
86    }
87
88    pub fn as_char(self) -> char {
89        match self {
90            Self::East => 'E',
91            Self::West => 'W',
92        }
93    }
94
95    pub fn sign(self) -> f64 {
96        match self {
97            Self::East => 1.0,
98            Self::West => -1.0,
99        }
100    }
101}
102
103/// Altitude relative to sea level.
104///
105/// Combines EXIF's `GPSAltitudeRef` (0 = above, 1 = below) with the magnitude
106/// from `GPSAltitude` so the two cannot drift out of sync.
107#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
108pub enum Altitude {
109    /// Absent or unparseable.
110    #[default]
111    Unknown,
112    AboveSeaLevel(URational),
113    BelowSeaLevel(URational),
114}
115
116impl Altitude {
117    /// Signed altitude in meters; `None` when Unknown or denominator=0.
118    pub fn meters(&self) -> Option<f64> {
119        match self {
120            Altitude::Unknown => None,
121            Altitude::AboveSeaLevel(r) => r.to_f64(),
122            Altitude::BelowSeaLevel(r) => r.to_f64().map(|m| -m),
123        }
124    }
125
126    /// The underlying magnitude rational, regardless of sign. None for `Unknown`.
127    pub fn magnitude(&self) -> Option<URational> {
128        match self {
129            Altitude::Unknown => None,
130            Altitude::AboveSeaLevel(r) | Altitude::BelowSeaLevel(r) => Some(*r),
131        }
132    }
133}
134
135/// EXIF GPS speed reference unit (`GPSSpeedRef`).
136#[derive(Debug, Clone, Copy, PartialEq, Eq)]
137pub enum SpeedUnit {
138    KmPerHour,
139    MilesPerHour,
140    Knots,
141}
142
143impl SpeedUnit {
144    pub fn from_char(c: char) -> Option<Self> {
145        match c {
146            'K' | 'k' => Some(Self::KmPerHour),
147            'M' | 'm' => Some(Self::MilesPerHour),
148            'N' | 'n' => Some(Self::Knots),
149            _ => None,
150        }
151    }
152
153    pub fn as_char(self) -> char {
154        match self {
155            Self::KmPerHour => 'K',
156            Self::MilesPerHour => 'M',
157            Self::Knots => 'N',
158        }
159    }
160}
161
162/// EXIF GPS speed: unit + value paired so they cannot drift out of sync.
163#[derive(Debug, Clone, Copy, PartialEq, Eq)]
164pub struct Speed {
165    pub unit: SpeedUnit,
166    pub value: URational,
167}
168
169impl LatLng {
170    pub const fn new(degrees: URational, minutes: URational, seconds: URational) -> Self {
171        Self {
172            degrees,
173            minutes,
174            seconds,
175        }
176    }
177
178    /// Convert to decimal degrees. Returns `None` if any component has a zero
179    /// denominator.
180    pub fn to_decimal_degrees(&self) -> Option<f64> {
181        let d = self.degrees.to_f64()?;
182        let m = self.minutes.to_f64()?;
183        let s = self.seconds.to_f64()?;
184        Some(d + m / 60.0 + s / 3600.0)
185    }
186
187    /// Construct from decimal degrees. Rejects NaN / ±inf and values whose
188    /// magnitude exceeds 180° with `ConvertError::InvalidDecimalDegrees`.
189    pub fn try_from_decimal_degrees(degrees: f64) -> Result<Self, crate::ConvertError> {
190        if !degrees.is_finite() || degrees.abs() > 180.0 {
191            return Err(crate::ConvertError::InvalidDecimalDegrees(degrees));
192        }
193        let abs = degrees.abs();
194        let d = abs.trunc() as u32;
195        let mins_total = (abs - d as f64) * 60.0;
196        let m = mins_total.trunc() as u32;
197        let secs_hundredths = ((mins_total - m as f64) * 60.0 * 100.0).round() as u32;
198        Ok(Self::new(
199            URational::new(d, 1),
200            URational::new(m, 1),
201            URational::new(secs_hundredths, 100),
202        ))
203    }
204}
205
206impl GPSInfo {
207    /// Latitude in decimal degrees, signed by `latitude_ref` (positive = north).
208    pub fn latitude_decimal(&self) -> Option<f64> {
209        Some(self.latitude.to_decimal_degrees()? * self.latitude_ref.sign())
210    }
211
212    /// Longitude in decimal degrees, signed by `longitude_ref` (positive = east).
213    pub fn longitude_decimal(&self) -> Option<f64> {
214        Some(self.longitude.to_decimal_degrees()? * self.longitude_ref.sign())
215    }
216
217    /// Signed altitude in meters; `None` if altitude is `Unknown` or denominator=0.
218    pub fn altitude_meters(&self) -> Option<f64> {
219        self.altitude.meters()
220    }
221
222    /// Returns an ISO 6709 geographic point location string such as
223    /// `+48.8577+002.295/`.
224    pub fn to_iso6709(&self) -> String {
225        let latitude = self.latitude.to_decimal_degrees().unwrap_or(0.0);
226        let longitude = self.longitude.to_decimal_degrees().unwrap_or(0.0);
227        let altitude_meters = self.altitude.meters();
228        format!(
229            "{}{latitude:08.5}{}{longitude:09.5}{}/",
230            match self.latitude_ref {
231                LatRef::North => '+',
232                LatRef::South => '-',
233            },
234            match self.longitude_ref {
235                LonRef::East => '+',
236                LonRef::West => '-',
237            },
238            match altitude_meters {
239                None | Some(0.0) => String::new(),
240                Some(m) => format!(
241                    "{}{}CRSWGS_84",
242                    if m >= 0.0 { "+" } else { "-" },
243                    Self::format_float(m.abs())
244                ),
245            }
246        )
247    }
248
249    fn format_float(f: f64) -> String {
250        if f.fract() == 0.0 {
251            f.to_string()
252        } else {
253            format!("{f:.3}")
254        }
255    }
256}
257
258impl TryFrom<&[URational]> for LatLng {
259    type Error = crate::Error;
260    fn try_from(value: &[URational]) -> Result<Self, Self::Error> {
261        if value.len() < 3 {
262            return Err(crate::Error::Malformed {
263                kind: crate::error::MalformedKind::IfdEntry,
264                message: "need at least 3 URational components for LatLng".into(),
265            });
266        }
267        Ok(Self {
268            degrees: value[0],
269            minutes: value[1],
270            seconds: value[2],
271        })
272    }
273}
274
275impl TryFrom<&[IRational]> for LatLng {
276    type Error = crate::Error;
277    fn try_from(value: &[IRational]) -> Result<Self, Self::Error> {
278        if value.len() < 3 {
279            return Err(crate::Error::Malformed {
280                kind: crate::error::MalformedKind::IfdEntry,
281                message: "need at least 3 IRational components for LatLng".into(),
282            });
283        }
284        let map_negative = |_| crate::Error::Malformed {
285            kind: crate::error::MalformedKind::IfdEntry,
286            message: "negative LatLng component".into(),
287        };
288        Ok(Self {
289            degrees: URational::try_from(value[0]).map_err(map_negative)?,
290            minutes: URational::try_from(value[1]).map_err(map_negative)?,
291            seconds: URational::try_from(value[2]).map_err(map_negative)?,
292        })
293    }
294}
295
296impl TryFrom<&Vec<URational>> for LatLng {
297    type Error = crate::Error;
298    fn try_from(value: &Vec<URational>) -> Result<Self, Self::Error> {
299        Self::try_from(value.as_slice())
300    }
301}
302
303impl TryFrom<&Vec<IRational>> for LatLng {
304    type Error = crate::Error;
305    fn try_from(value: &Vec<IRational>) -> Result<Self, Self::Error> {
306        Self::try_from(value.as_slice())
307    }
308}
309
310impl FromStr for GPSInfo {
311    type Err = crate::ConvertError;
312    fn from_str(s: &str) -> Result<Self, Self::Err> {
313        iso6709parse::parse::<ISO6709Coord>(s)
314            .map(GPSInfo::from_iso6709_coord)
315            .map_err(|_| crate::ConvertError::InvalidIso6709(s.to_string()))
316    }
317}
318
319impl GPSInfo {
320    /// Build a `GPSInfo` from a parsed ISO 6709 coordinate. Crate-internal:
321    /// the public path is [`GPSInfo::from_str`] / `<GPSInfo as FromStr>::from_str`,
322    /// which keeps `iso6709parse::ISO6709Coord` out of the public API surface
323    /// (so an `iso6709parse` major-version bump does not force one here).
324    pub(crate) fn from_iso6709_coord(v: ISO6709Coord) -> Self {
325        let latitude_ref = if v.lat >= 0.0 {
326            LatRef::North
327        } else {
328            LatRef::South
329        };
330        let longitude_ref = if v.lon >= 0.0 {
331            LonRef::East
332        } else {
333            LonRef::West
334        };
335        let latitude = LatLng::try_from_decimal_degrees(v.lat.abs()).unwrap_or_default();
336        let longitude = LatLng::try_from_decimal_degrees(v.lon.abs()).unwrap_or_default();
337        let altitude = match v.altitude {
338            None => Altitude::Unknown,
339            Some(x) => {
340                let mag = URational::new((x.abs() * 1000.0).trunc() as u32, 1000);
341                if x >= 0.0 {
342                    Altitude::AboveSeaLevel(mag)
343                } else {
344                    Altitude::BelowSeaLevel(mag)
345                }
346            }
347        };
348        Self {
349            latitude_ref,
350            latitude,
351            longitude_ref,
352            longitude,
353            altitude,
354            speed: None,
355        }
356    }
357}
358
359#[cfg(test)]
360mod tests {
361    use super::*;
362
363    #[test]
364    fn gps_iso6709() {
365        let _ = tracing_subscriber::fmt().with_test_writer().try_init();
366
367        let palace = GPSInfo {
368            latitude_ref: LatRef::North,
369            latitude: LatLng::new(
370                URational::new(39, 1),
371                URational::new(55, 1),
372                URational::new(0, 1),
373            ),
374            longitude_ref: LonRef::East,
375            longitude: LatLng::new(
376                URational::new(116, 1),
377                URational::new(23, 1),
378                URational::new(27, 1),
379            ),
380            altitude: Altitude::AboveSeaLevel(URational::new(0, 1)),
381            speed: None,
382        };
383        assert_eq!(palace.to_iso6709(), "+39.91667+116.39083/");
384
385        let liberty = GPSInfo {
386            latitude_ref: LatRef::North,
387            latitude: LatLng::new(
388                URational::new(40, 1),
389                URational::new(41, 1),
390                URational::new(21, 1),
391            ),
392            longitude_ref: LonRef::West,
393            longitude: LatLng::new(
394                URational::new(74, 1),
395                URational::new(2, 1),
396                URational::new(40, 1),
397            ),
398            altitude: Altitude::AboveSeaLevel(URational::new(0, 1)),
399            speed: None,
400        };
401        assert_eq!(liberty.to_iso6709(), "+40.68917-074.04444/");
402
403        let above = GPSInfo {
404            latitude_ref: LatRef::North,
405            latitude: LatLng::new(
406                URational::new(40, 1),
407                URational::new(41, 1),
408                URational::new(21, 1),
409            ),
410            longitude_ref: LonRef::West,
411            longitude: LatLng::new(
412                URational::new(74, 1),
413                URational::new(2, 1),
414                URational::new(40, 1),
415            ),
416            altitude: Altitude::AboveSeaLevel(URational::new(123, 1)),
417            speed: None,
418        };
419        assert_eq!(above.to_iso6709(), "+40.68917-074.04444+123CRSWGS_84/");
420
421        let below = GPSInfo {
422            latitude_ref: LatRef::North,
423            latitude: LatLng::new(
424                URational::new(40, 1),
425                URational::new(41, 1),
426                URational::new(21, 1),
427            ),
428            longitude_ref: LonRef::West,
429            longitude: LatLng::new(
430                URational::new(74, 1),
431                URational::new(2, 1),
432                URational::new(40, 1),
433            ),
434            altitude: Altitude::BelowSeaLevel(URational::new(123, 1)),
435            speed: None,
436        };
437        assert_eq!(below.to_iso6709(), "+40.68917-074.04444-123CRSWGS_84/");
438
439        let below = GPSInfo {
440            latitude_ref: LatRef::North,
441            latitude: LatLng::new(
442                URational::new(40, 1),
443                URational::new(41, 1),
444                URational::new(21, 1),
445            ),
446            longitude_ref: LonRef::West,
447            longitude: LatLng::new(
448                URational::new(74, 1),
449                URational::new(2, 1),
450                URational::new(40, 1),
451            ),
452            altitude: Altitude::BelowSeaLevel(URational::new(100, 3)),
453            speed: None,
454        };
455        assert_eq!(below.to_iso6709(), "+40.68917-074.04444-33.333CRSWGS_84/");
456    }
457
458    #[test]
459    fn gps_iso6709_with_invalid_alt() {
460        let _ = tracing_subscriber::fmt().with_test_writer().try_init();
461
462        let iso: ISO6709Coord = iso6709parse::parse("+26.5322-078.1969+019.099/").unwrap();
463        assert_eq!(iso.lat, 26.5322);
464        assert_eq!(iso.lon, -78.1969);
465        assert_eq!(iso.altitude, None);
466
467        let iso: GPSInfo = "+26.5322-078.1969+019.099/".parse().unwrap();
468        assert_eq!(iso.latitude_ref, LatRef::North);
469        assert_eq!(
470            iso.latitude,
471            LatLng::new(
472                URational::new(26, 1),
473                URational::new(31, 1),
474                URational::new(5592, 100),
475            )
476        );
477
478        assert_eq!(iso.longitude_ref, LonRef::West);
479        assert_eq!(
480            iso.longitude,
481            LatLng::new(
482                URational::new(78, 1),
483                URational::new(11, 1),
484                URational::new(4884, 100),
485            )
486        );
487
488        assert_eq!(iso.altitude, Altitude::Unknown);
489    }
490
491    #[test]
492    fn latlng_to_decimal_degrees() {
493        let p = LatLng::new(
494            URational::new(40, 1),
495            URational::new(41, 1),
496            URational::new(21, 1),
497        );
498        let d = p.to_decimal_degrees().unwrap();
499        assert!((d - 40.689_167).abs() < 1e-5);
500    }
501
502    #[test]
503    fn latlng_to_decimal_degrees_zero_denominator() {
504        let p = LatLng::new(
505            URational::new(40, 0),
506            URational::new(41, 1),
507            URational::new(21, 1),
508        );
509        assert_eq!(p.to_decimal_degrees(), None);
510    }
511
512    #[test]
513    fn latlng_try_from_decimal_degrees_ok() {
514        let p = LatLng::try_from_decimal_degrees(43.5).unwrap();
515        let back = p.to_decimal_degrees().unwrap();
516        assert!((back - 43.5).abs() < 1e-3);
517    }
518
519    #[test]
520    fn latlng_try_from_decimal_degrees_rejects_nan_inf_oob() {
521        use crate::ConvertError;
522        assert!(matches!(
523            LatLng::try_from_decimal_degrees(f64::NAN),
524            Err(ConvertError::InvalidDecimalDegrees(_))
525        ));
526        assert!(matches!(
527            LatLng::try_from_decimal_degrees(f64::INFINITY),
528            Err(ConvertError::InvalidDecimalDegrees(_))
529        ));
530        assert!(matches!(
531            LatLng::try_from_decimal_degrees(181.0),
532            Err(ConvertError::InvalidDecimalDegrees(_))
533        ));
534    }
535
536    #[test]
537    fn lat_lon_ref_round_trip() {
538        for c in ['N', 'S', 'n', 's'] {
539            assert!(LatRef::from_char(c).is_some());
540        }
541        for c in ['E', 'W', 'e', 'w'] {
542            assert!(LonRef::from_char(c).is_some());
543        }
544        assert_eq!(LatRef::North.as_char(), 'N');
545        assert_eq!(LonRef::West.as_char(), 'W');
546        assert_eq!(LatRef::South.sign(), -1.0);
547        assert_eq!(LonRef::East.sign(), 1.0);
548        assert_eq!(LatRef::from_char('X'), None);
549    }
550
551    #[test]
552    fn altitude_meters_signed() {
553        let above = Altitude::AboveSeaLevel(URational::new(123, 1));
554        let below = Altitude::BelowSeaLevel(URational::new(123, 1));
555        assert_eq!(above.meters(), Some(123.0));
556        assert_eq!(below.meters(), Some(-123.0));
557        assert_eq!(Altitude::Unknown.meters(), None);
558        assert_eq!(Altitude::AboveSeaLevel(URational::new(1, 0)).meters(), None);
559    }
560
561    #[test]
562    fn speed_unit_round_trip() {
563        assert_eq!(SpeedUnit::from_char('K'), Some(SpeedUnit::KmPerHour));
564        assert_eq!(SpeedUnit::from_char('M'), Some(SpeedUnit::MilesPerHour));
565        assert_eq!(SpeedUnit::from_char('N'), Some(SpeedUnit::Knots));
566        assert_eq!(SpeedUnit::from_char('X'), None);
567        assert_eq!(SpeedUnit::Knots.as_char(), 'N');
568    }
569
570    #[test]
571    fn gps_info_decimal_accessors() {
572        let liberty = GPSInfo {
573            latitude_ref: LatRef::North,
574            latitude: LatLng::new(
575                URational::new(40, 1),
576                URational::new(41, 1),
577                URational::new(21, 1),
578            ),
579            longitude_ref: LonRef::West,
580            longitude: LatLng::new(
581                URational::new(74, 1),
582                URational::new(2, 1),
583                URational::new(40, 1),
584            ),
585            altitude: Altitude::AboveSeaLevel(URational::new(123, 1)),
586            speed: None,
587        };
588        let lat = liberty.latitude_decimal().unwrap();
589        let lon = liberty.longitude_decimal().unwrap();
590        assert!((lat - 40.689_167).abs() < 1e-5);
591        assert!((lon - (-74.044_444)).abs() < 1e-5);
592        assert_eq!(liberty.altitude_meters(), Some(123.0));
593    }
594
595    #[test]
596    fn gps_info_from_str_uses_convert_error() {
597        use crate::ConvertError;
598        let err = "garbage".parse::<GPSInfo>().unwrap_err();
599        assert!(matches!(err, ConvertError::InvalidIso6709(_)));
600    }
601}
nom_exif/exif/gps.rs

nom_exif/exif/
gps.rs
