oxiproj-core 0.1.2

//! Typed coordinate structs ported from PROJ `src/proj.h` (PJ_COORD union, replaced safely).
//!
//! PROJ represents all coordinate flavors with a single C `union` called
//! `PJ_COORD`, whose largest member is `double v[4]`. Every named member
//! (`xy`, `lp`, `lpz`, `xyzt`, …) is a *reinterpretation* of the same four
//! `double` slots. C unions rely on shared storage, which would require
//! `unsafe` in Rust.
//!
//! This module replaces that union with a single storage type [`Coord`]
//! wrapping `[f64; 4]`, plus a family of plain field structs. The accessor
//! methods on [`Coord`] (`xy`, `lp`, `xyzt`, …) read the array slots in the
//! same order PROJ's union members would have occupied them, giving the exact
//! same observable semantics with zero `unsafe`.

/// 2D Cartesian coordinate (PROJ `PJ_XY`): easting/northing or generic x/y.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Xy {
    /// First (easting / abscissa) component.
    pub x: f64,
    /// Second (northing / ordinate) component.
    pub y: f64,
}

impl Xy {
    /// Construct a new [`Xy`] from its components, in field order.
    #[must_use]
    pub const fn new(x: f64, y: f64) -> Self {
        Self { x, y }
    }
}

/// 2D geodetic coordinate (PROJ `PJ_LP`): longitude (`lam`) / latitude (`phi`).
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Lp {
    /// Longitude (lambda), in radians within PROJ's internal pipeline.
    pub lam: f64,
    /// Latitude (phi), in radians within PROJ's internal pipeline.
    pub phi: f64,
}

impl Lp {
    /// Construct a new [`Lp`] from its components, in field order.
    #[must_use]
    pub const fn new(lam: f64, phi: f64) -> Self {
        Self { lam, phi }
    }
}

/// 2D generic coordinate (PROJ `PJ_UV`): a dimensionless `(u, v)` pair.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Uv {
    /// First generic component.
    pub u: f64,
    /// Second generic component.
    pub v: f64,
}

impl Uv {
    /// Construct a new [`Uv`] from its components, in field order.
    #[must_use]
    pub const fn new(u: f64, v: f64) -> Self {
        Self { u, v }
    }
}

/// 3D Cartesian coordinate (PROJ `PJ_XYZ`): x/y plus height/`z`.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Xyz {
    /// First (easting / abscissa) component.
    pub x: f64,
    /// Second (northing / ordinate) component.
    pub y: f64,
    /// Third (vertical) component.
    pub z: f64,
}

impl Xyz {
    /// Construct a new [`Xyz`] from its components, in field order.
    #[must_use]
    pub const fn new(x: f64, y: f64, z: f64) -> Self {
        Self { x, y, z }
    }
}

/// 3D geodetic coordinate (PROJ `PJ_LPZ`): longitude/latitude plus height.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Lpz {
    /// Longitude (lambda).
    pub lam: f64,
    /// Latitude (phi).
    pub phi: f64,
    /// Ellipsoidal / vertical height.
    pub z: f64,
}

impl Lpz {
    /// Construct a new [`Lpz`] from its components, in field order.
    #[must_use]
    pub const fn new(lam: f64, phi: f64, z: f64) -> Self {
        Self { lam, phi, z }
    }
}

/// 3D generic coordinate (PROJ `PJ_UVW`): a dimensionless `(u, v, w)` triple.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Uvw {
    /// First generic component.
    pub u: f64,
    /// Second generic component.
    pub v: f64,
    /// Third generic component.
    pub w: f64,
}

impl Uvw {
    /// Construct a new [`Uvw`] from its components, in field order.
    #[must_use]
    pub const fn new(u: f64, v: f64, w: f64) -> Self {
        Self { u, v, w }
    }
}

/// 4D Cartesian space-time coordinate (PROJ `PJ_XYZT`): x/y/z plus time `t`.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Xyzt {
    /// First (easting / abscissa) component.
    pub x: f64,
    /// Second (northing / ordinate) component.
    pub y: f64,
    /// Third (vertical) component.
    pub z: f64,
    /// Time component (typically decimal years).
    pub t: f64,
}

impl Xyzt {
    /// Construct a new [`Xyzt`] from its components, in field order.
    #[must_use]
    pub const fn new(x: f64, y: f64, z: f64, t: f64) -> Self {
        Self { x, y, z, t }
    }
}

/// 4D geodetic space-time coordinate (PROJ `PJ_LPZT`).
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Lpzt {
    /// Longitude (lambda).
    pub lam: f64,
    /// Latitude (phi).
    pub phi: f64,
    /// Ellipsoidal / vertical height.
    pub z: f64,
    /// Time component (typically decimal years).
    pub t: f64,
}

impl Lpzt {
    /// Construct a new [`Lpzt`] from its components, in field order.
    #[must_use]
    pub const fn new(lam: f64, phi: f64, z: f64, t: f64) -> Self {
        Self { lam, phi, z, t }
    }
}

/// 4D generic space-time coordinate (PROJ `PJ_UVWT`).
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Uvwt {
    /// First generic component.
    pub u: f64,
    /// Second generic component.
    pub v: f64,
    /// Third generic component.
    pub w: f64,
    /// Time component.
    pub t: f64,
}

impl Uvwt {
    /// Construct a new [`Uvwt`] from its components, in field order.
    #[must_use]
    pub const fn new(u: f64, v: f64, w: f64, t: f64) -> Self {
        Self { u, v, w, t }
    }
}

/// Orientation angles (PROJ `PJ_OPK`): omega / phi / kappa.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Opk {
    /// Omega (rotation about the x-axis).
    pub o: f64,
    /// Phi (rotation about the y-axis).
    pub p: f64,
    /// Kappa (rotation about the z-axis).
    pub k: f64,
}

impl Opk {
    /// Construct a new [`Opk`] from its components, in field order.
    #[must_use]
    pub const fn new(o: f64, p: f64, k: f64) -> Self {
        Self { o, p, k }
    }
}

/// Local topocentric coordinate (PROJ `PJ_ENU`): east / north / up.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Enu {
    /// East component.
    pub e: f64,
    /// North component.
    pub n: f64,
    /// Up component.
    pub u: f64,
}

impl Enu {
    /// Construct a new [`Enu`] from its components, in field order.
    #[must_use]
    pub const fn new(e: f64, n: f64, u: f64) -> Self {
        Self { e, n, u }
    }
}

/// Geodesic solution components (PROJ `PJ_GEOD`): distance and two azimuths.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Geod {
    /// Geodesic distance `s`.
    pub s: f64,
    /// Forward azimuth `a1`.
    pub a1: f64,
    /// Reverse azimuth `a2`.
    pub a2: f64,
}

impl Geod {
    /// Construct a new [`Geod`] from its components, in field order.
    #[must_use]
    pub const fn new(s: f64, a1: f64, a2: f64) -> Self {
        Self { s, a1, a2 }
    }
}

/// Union-replacement coordinate storage, wrapping PROJ's `double v[4]`.
///
/// Where PROJ uses a C `union PJ_COORD` with overlapping members, this type
/// holds the underlying four `f64` slots and exposes typed *views* via the
/// accessor methods (`xy`, `lp`, `xyzt`, …). Each accessor reinterprets the
/// same slots in the order PROJ's union layout dictates — no `unsafe`, no
/// `transmute`, no shared mutable storage tricks.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Coord([f64; 4]);

impl Coord {
    /// Construct a coordinate from four raw slots.
    ///
    /// Mirrors PROJ's `proj_coord(x, y, z, t)`, which sets `v = [x, y, z, t]`.
    #[must_use]
    pub const fn new(a: f64, b: f64, c: f64, d: f64) -> Coord {
        Coord([a, b, c, d])
    }

    /// View slots 0,1 as a 2D Cartesian [`Xy`].
    #[must_use]
    pub fn xy(&self) -> Xy {
        Xy {
            x: self.0[0],
            y: self.0[1],
        }
    }

    /// View slots 0,1 as a 2D geodetic [`Lp`].
    #[must_use]
    pub fn lp(&self) -> Lp {
        Lp {
            lam: self.0[0],
            phi: self.0[1],
        }
    }

    /// View slots 0,1 as a 2D generic [`Uv`].
    #[must_use]
    pub fn uv(&self) -> Uv {
        Uv {
            u: self.0[0],
            v: self.0[1],
        }
    }

    /// View slots 0,1,2 as a 3D Cartesian [`Xyz`].
    #[must_use]
    pub fn xyz(&self) -> Xyz {
        Xyz {
            x: self.0[0],
            y: self.0[1],
            z: self.0[2],
        }
    }

    /// View slots 0,1,2 as a 3D geodetic [`Lpz`] (`lam`, `phi`, `z`).
    #[must_use]
    pub fn lpz(&self) -> Lpz {
        Lpz {
            lam: self.0[0],
            phi: self.0[1],
            z: self.0[2],
        }
    }

    /// View slots 0,1,2 as a 3D generic [`Uvw`].
    #[must_use]
    pub fn uvw(&self) -> Uvw {
        Uvw {
            u: self.0[0],
            v: self.0[1],
            w: self.0[2],
        }
    }

    /// View all four slots as a 4D Cartesian space-time [`Xyzt`].
    #[must_use]
    pub fn xyzt(&self) -> Xyzt {
        Xyzt {
            x: self.0[0],
            y: self.0[1],
            z: self.0[2],
            t: self.0[3],
        }
    }

    /// View all four slots as a 4D geodetic space-time [`Lpzt`].
    #[must_use]
    pub fn lpzt(&self) -> Lpzt {
        Lpzt {
            lam: self.0[0],
            phi: self.0[1],
            z: self.0[2],
            t: self.0[3],
        }
    }

    /// View all four slots as a 4D generic space-time [`Uvwt`].
    #[must_use]
    pub fn uvwt(&self) -> Uvwt {
        Uvwt {
            u: self.0[0],
            v: self.0[1],
            w: self.0[2],
            t: self.0[3],
        }
    }

    /// View slots 0,1,2 as orientation angles [`Opk`] (`o`, `p`, `k`).
    #[must_use]
    pub fn opk(&self) -> Opk {
        Opk {
            o: self.0[0],
            p: self.0[1],
            k: self.0[2],
        }
    }

    /// View slots 0,1,2 as a topocentric [`Enu`] (`e`, `n`, `u`).
    #[must_use]
    pub fn enu(&self) -> Enu {
        Enu {
            e: self.0[0],
            n: self.0[1],
            u: self.0[2],
        }
    }

    /// View slots 0,1,2 as a geodesic solution [`Geod`] (`s`, `a1`, `a2`).
    #[must_use]
    pub fn geod(&self) -> Geod {
        Geod {
            s: self.0[0],
            a1: self.0[1],
            a2: self.0[2],
        }
    }

    /// Return the four raw slots as a copy of the backing array.
    #[must_use]
    pub fn v(&self) -> [f64; 4] {
        self.0
    }

    /// Fetch slot `i` without panicking, returning `None` when out of bounds.
    ///
    /// Unlike the [`Index`](core::ops::Index) implementation, this never
    /// panics, honoring the no-panic-in-production policy.
    #[must_use]
    pub fn get(&self, i: usize) -> Option<f64> {
        self.0.get(i).copied()
    }

    /// Error sentinel mirroring PROJ's `HUGE_VAL`-filled coordinates.
    ///
    /// All four slots are set to positive infinity so that [`is_error`] returns
    /// `true`.
    ///
    /// [`is_error`]: Coord::is_error
    #[must_use]
    pub fn error() -> Coord {
        Coord([f64::INFINITY; 4])
    }

    /// Return `true` if any component is non-finite (infinity or NaN).
    ///
    /// This is how PROJ flags invalid results, where `HUGE_VAL` (infinity)
    /// marks a failed transform. NaN is treated as an error too.
    #[must_use]
    pub fn is_error(&self) -> bool {
        self.0.iter().any(|c| !c.is_finite())
    }
}

impl core::ops::Index<usize> for Coord {
    type Output = f64;

    /// Index into the backing slots.
    ///
    /// By the [`Index`](core::ops::Index) trait contract this panics on
    /// out-of-bounds access — that documented behavior is the standard array
    /// idiom and is not a no-panic-policy violation. For a non-panicking
    /// alternative use [`Coord::get`].
    fn index(&self, i: usize) -> &f64 {
        &self.0[i]
    }
}

impl From<Xy> for Coord {
    fn from(value: Xy) -> Self {
        Coord([value.x, value.y, 0.0, 0.0])
    }
}

impl From<Lp> for Coord {
    fn from(value: Lp) -> Self {
        Coord([value.lam, value.phi, 0.0, 0.0])
    }
}

impl From<Uv> for Coord {
    fn from(value: Uv) -> Self {
        Coord([value.u, value.v, 0.0, 0.0])
    }
}

impl From<Xyz> for Coord {
    fn from(value: Xyz) -> Self {
        Coord([value.x, value.y, value.z, 0.0])
    }
}

impl From<Lpz> for Coord {
    fn from(value: Lpz) -> Self {
        Coord([value.lam, value.phi, value.z, 0.0])
    }
}

impl From<Uvw> for Coord {
    fn from(value: Uvw) -> Self {
        Coord([value.u, value.v, value.w, 0.0])
    }
}

impl From<Xyzt> for Coord {
    fn from(value: Xyzt) -> Self {
        Coord([value.x, value.y, value.z, value.t])
    }
}

impl From<Lpzt> for Coord {
    fn from(value: Lpzt) -> Self {
        Coord([value.lam, value.phi, value.z, value.t])
    }
}

impl From<Uvwt> for Coord {
    fn from(value: Uvwt) -> Self {
        Coord([value.u, value.v, value.w, value.t])
    }
}

impl From<Opk> for Coord {
    fn from(value: Opk) -> Self {
        Coord([value.o, value.p, value.k, 0.0])
    }
}

impl From<Enu> for Coord {
    fn from(value: Enu) -> Self {
        Coord([value.e, value.n, value.u, 0.0])
    }
}

impl From<Geod> for Coord {
    fn from(value: Geod) -> Self {
        Coord([value.s, value.a1, value.a2, 0.0])
    }
}

/// Direction of a transform, ported from PROJ `PJ_DIRECTION`.
///
/// The discriminant values match PROJ exactly: forward = `1`, identity = `0`,
/// inverse = `-1`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[repr(i32)]
pub enum Direction {
    /// Forward transform.
    Fwd = 1,
    /// Identity (no-op) transform.
    Ident = 0,
    /// Inverse transform.
    Inv = -1,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn lp_round_trip() {
        let lp = Lp::new(0.5, 0.3);
        let c: Coord = lp.into();
        assert_eq!(c.lp(), lp);
    }

    #[test]
    fn xy_round_trip() {
        let xy = Xy::new(123.0, 456.0);
        let c: Coord = xy.into();
        assert_eq!(c.xy(), xy);
    }

    #[test]
    fn xyz_round_trip() {
        let xyz = Xyz::new(1.0, 2.0, 3.0);
        let c: Coord = xyz.into();
        assert_eq!(c.xyz(), xyz);
    }

    #[test]
    fn xyzt_round_trip() {
        let xyzt = Xyzt::new(1.0, 2.0, 3.0, 4.0);
        let c: Coord = xyzt.into();
        assert_eq!(c.xyzt(), xyzt);
    }

    #[test]
    fn lpzt_round_trip() {
        let lpzt = Lpzt::new(0.5, 0.3, 100.0, 2020.0);
        let c: Coord = lpzt.into();
        assert_eq!(c.lpzt(), lpzt);
    }

    #[test]
    fn error_sentinel_is_error() {
        assert!(Coord::error().is_error());
    }

    #[test]
    fn finite_coord_is_not_error() {
        assert!(!Coord::new(1.0, 2.0, 3.0, 4.0).is_error());
    }

    #[test]
    fn nan_component_is_error() {
        assert!(Coord::new(f64::NAN, 0.0, 0.0, 0.0).is_error());
    }

    #[test]
    fn direction_discriminants() {
        assert_eq!(Direction::Fwd as i32, 1);
        assert_eq!(Direction::Ident as i32, 0);
        assert_eq!(Direction::Inv as i32, -1);
    }

    #[test]
    fn v_returns_all_slots() {
        assert_eq!(Coord::new(1.0, 2.0, 3.0, 4.0).v(), [1.0, 2.0, 3.0, 4.0]);
    }

    #[test]
    fn get_bounds_checked() {
        assert_eq!(Coord::new(1.0, 2.0, 3.0, 4.0).get(0), Some(1.0));
        assert_eq!(Coord::new(1.0, 2.0, 3.0, 4.0).get(9), None);
    }

    #[test]
    fn index_reads_slots() {
        let c = Coord::new(10.0, 20.0, 30.0, 40.0);
        assert_eq!(c[0], 10.0);
        assert_eq!(c[3], 40.0);
    }

    #[test]
    fn other_views_share_slots() {
        let c = Coord::new(7.0, 8.0, 9.0, 0.0);
        assert_eq!(c.uv(), Uv::new(7.0, 8.0));
        assert_eq!(c.lpz(), Lpz::new(7.0, 8.0, 9.0));
        assert_eq!(c.uvw(), Uvw::new(7.0, 8.0, 9.0));
        assert_eq!(c.opk(), Opk::new(7.0, 8.0, 9.0));
        assert_eq!(c.enu(), Enu::new(7.0, 8.0, 9.0));
        assert_eq!(c.geod(), Geod::new(7.0, 8.0, 9.0));
    }

    #[test]
    fn remaining_from_conversions() {
        assert_eq!(Coord::from(Uv::new(1.0, 2.0)).v(), [1.0, 2.0, 0.0, 0.0]);
        assert_eq!(
            Coord::from(Lpz::new(1.0, 2.0, 3.0)).v(),
            [1.0, 2.0, 3.0, 0.0]
        );
        assert_eq!(
            Coord::from(Uvw::new(1.0, 2.0, 3.0)).v(),
            [1.0, 2.0, 3.0, 0.0]
        );
        assert_eq!(
            Coord::from(Uvwt::new(1.0, 2.0, 3.0, 4.0)).v(),
            [1.0, 2.0, 3.0, 4.0]
        );
        assert_eq!(
            Coord::from(Opk::new(1.0, 2.0, 3.0)).v(),
            [1.0, 2.0, 3.0, 0.0]
        );
        assert_eq!(
            Coord::from(Enu::new(1.0, 2.0, 3.0)).v(),
            [1.0, 2.0, 3.0, 0.0]
        );
        assert_eq!(
            Coord::from(Geod::new(1.0, 2.0, 3.0)).v(),
            [1.0, 2.0, 3.0, 0.0]
        );
    }
}