geometry-cs 0.0.8

Coordinate system types: Cartesian, Spherical, Geographic, and angle units.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

//! Plane-angle units: [`Degree`] and [`Radian`].
//!
//! Mirrors `boost::geometry::degree` and `boost::geometry::radian` —
//! the empty tag types declared at `boost/geometry/core/cs.hpp:41-51`,
//! together with their use as the `units` typedef on the
//! `cs::{spherical,geographic,polar}<DegreeOrRadian>` templates
//! (`cs.hpp:54-79`).
//!
//! Boost.Geometry never expresses degree↔radian conversion as a method
//! on the tag; it scatters `* 0.017453292…` constants and ad-hoc helpers
//! across `util/math.hpp` and the spherical/geographic strategies. We
//! collect both directions into the [`AngleUnit`] trait so a strategy
//! can write `U::to_radians(angle)` once and have it monomorphise to
//! either `angle` (for [`Radian`]) or `angle * π/180` (for [`Degree`]).

use geometry_coords::CoordinateScalar;

/// Unit of plane angle.
///
/// Mirrors `boost::geometry::degree` / `boost::geometry::radian` from
/// `boost/geometry/core/cs.hpp:41-51` and their role as the
/// `cs_angular_units<Cs>::type` in `cs.hpp:251-281`. The conversion
/// methods are the Rust analogue of the unnamed scaling factors Boost
/// inlines inside each strategy.
///
/// # Examples
///
/// ```
/// use geometry_cs::{AngleUnit, Degree, Radian};
///
/// // 180° == π rad
/// let rad = Degree::to_radians(180.0_f64);
/// assert!((rad - core::f64::consts::PI).abs() < 1e-12);
///
/// // Round-trip through Radian is the identity.
/// assert_eq!(Radian::to_radians(1.5_f64), 1.5);
/// ```
pub trait AngleUnit {
    /// Convert a value in this unit to radians.
    ///
    /// For [`Radian`] this is the identity; for [`Degree`] it multiplies
    /// by `π / 180`.
    fn to_radians<T: CoordinateScalar + FromF64>(value: T) -> T;

    /// Convert a value in radians to this unit.
    ///
    /// For [`Radian`] this is the identity; for [`Degree`] it multiplies
    /// by `180 / π`.
    fn from_radians<T: CoordinateScalar + FromF64>(value: T) -> T;
}

/// Degrees (−180 … 180). Mirrors `boost::geometry::degree`
/// (`boost/geometry/core/cs.hpp:41`).
///
/// # Examples
///
/// ```
/// use geometry_cs::{AngleUnit, Degree};
/// assert!((Degree::to_radians(90.0_f64) - core::f64::consts::FRAC_PI_2).abs() < 1e-12);
/// ```
#[derive(Debug, Default, Clone, Copy)]
pub struct Degree;

/// Radians (−π … π). Mirrors `boost::geometry::radian`
/// (`boost/geometry/core/cs.hpp:51`).
///
/// # Examples
///
/// ```
/// use geometry_cs::{AngleUnit, Radian};
/// assert_eq!(Radian::to_radians(1.5_f64), 1.5);
/// ```
#[derive(Debug, Default, Clone, Copy)]
pub struct Radian;

impl AngleUnit for Degree {
    #[inline]
    fn to_radians<T: CoordinateScalar + FromF64>(value: T) -> T {
        value * T::from_f64(core::f64::consts::PI / 180.0)
    }

    #[inline]
    fn from_radians<T: CoordinateScalar + FromF64>(value: T) -> T {
        value * T::from_f64(180.0 / core::f64::consts::PI)
    }
}

impl AngleUnit for Radian {
    #[inline]
    fn to_radians<T: CoordinateScalar + FromF64>(value: T) -> T {
        value
    }

    #[inline]
    fn from_radians<T: CoordinateScalar + FromF64>(value: T) -> T {
        value
    }
}

/// Construct a scalar from an `f64` literal.
///
/// Lives in `geometry-cs` rather than `geometry-coords` because it is
/// only ever needed for the degree↔radian conversion factor — the rest
/// of the kernel either uses `T::ZERO` / `T::ONE` from
/// [`CoordinateScalar`] or stays in the scalar type the caller picked.
/// Keeping the bound local means strategies that never touch angle
/// units do not pay for it.
///
/// # Examples
///
/// ```
/// use geometry_cs::FromF64;
/// assert_eq!(f64::from_f64(1.5), 1.5);
/// assert_eq!(f32::from_f64(1.5), 1.5_f32);
/// ```
pub trait FromF64 {
    /// Cast an `f64` constant down to `Self`. Truncating for `f32` is
    /// fine — these are conversion-factor constants, not user data.
    fn from_f64(value: f64) -> Self;
}

impl FromF64 for f32 {
    #[inline]
    #[allow(clippy::cast_possible_truncation)]
    fn from_f64(value: f64) -> Self {
        value as f32
    }
}

impl FromF64 for f64 {
    #[inline]
    fn from_f64(value: f64) -> Self {
        value
    }
}