inner_space/
lib.rs

1#![no_std]
2#![deny(missing_docs)]
3/*!
4Traits for vector inner products and common operations.
5
6Provides `DotProduct` trait.
7If the default dot product with scalar output is implemented for a type, the `InnerSpace` trait will be derived for it, which provides many useful helpers like `magnitude`, `normalize`, `project`, `reject`, `reflect`, `angle`, ...
8
9Use this to build libraries generic over these trait, like rendering, physics, and vector math.
10*/
11
12use num_traits::{One, real::Real};
13
14pub use vector_space::*;
15
16/// This trait defines the dot product.
17pub trait DotProduct<T = Self>: VectorSpace {
18    /// The output type of the dot product.
19    type Output;
20
21    /// The dot product.
22    fn dot(&self, other: &T) -> <Self as DotProduct<T>>::Output;
23}
24
25impl DotProduct for f32 {
26    type Output = Self;
27    fn dot(&self, other: &Self) -> Self {
28        *self * *other
29    }
30}
31impl DotProduct for f64 {
32    type Output = Self;
33    fn dot(&self, other: &Self) -> Self {
34        *self * *other
35    }
36}
37
38/// This trait adds common vector operations to a vector space if the dot product is defined.
39pub trait InnerSpace: DotProduct<Output = <Self as VectorSpace>::Scalar> {
40    /// The squared magnitude.
41    ///
42    /// This is more efficient than calculating the magnitude.
43    /// Useful if you need the squared magnitude anyway.
44    #[inline]
45    fn magnitude2(&self) -> Self::Scalar {
46        self.dot(self)
47    }
48
49    /// The magnitude of a vector.
50    #[inline]
51    fn magnitude(&self) -> Self::Scalar {
52        self.magnitude2().sqrt()
53    }
54
55    /// The normalized vector.
56    #[inline]
57    fn normalize(self) -> Self {
58        let mag = self.magnitude();
59        self / mag
60    }
61
62    /// The angle between two vectors.
63    #[inline]
64    fn angle(&self, other: &Self) -> Self::Scalar {
65        (self.dot(other) / (self.magnitude() * other.magnitude())).acos()
66    }
67
68    /// Sets the magnitude of a vector.
69    #[inline]
70    fn with_magnitude(self, magnitude: Self::Scalar) -> Self {
71        let mag = self.magnitude();
72        self * (magnitude / mag)
73    }
74
75    /// Sets the direction of a vector.
76    #[inline]
77    fn with_direction(self, dir: Self) -> Self {
78        dir * self.magnitude()
79    }
80
81    /// The value of the vector along the specified axis.
82    #[inline]
83    fn query_axis(&self, dir: Self) -> Self::Scalar {
84        self.dot(&dir.normalize())
85    }
86
87    /// Projects a vector onto an already normalized direction vector.
88    #[inline]
89    fn normalized_project(self, dir: Self) -> Self {
90        let scalar = self.dot(&dir);
91        dir * scalar
92    }
93
94    /// Projects a vector onto the specified direction vector.
95    #[inline]
96    fn project(self, dir: Self) -> Self {
97        let ratio = self.dot(&dir) / dir.magnitude2();
98        dir * ratio
99    }
100
101    /// Rejects a vector from an already normalized direction vector.
102    #[inline]
103    fn normalized_reject(self, dir: Self) -> Self {
104        let scalar = self.dot(&dir);
105        let proj = dir * scalar;
106        self - proj
107    }
108
109    /// Rejects a vector from the specified direction vector.
110    #[inline]
111    fn reject(self, dir: Self) -> Self {
112        let ratio = self.dot(&dir) / dir.magnitude2();
113        self - dir * ratio
114    }
115
116    /// Reflects a vector from an already normalized direction vector.
117    #[inline]
118    fn normalized_reflect(self, dir: Self) -> Self {
119        let scalar = self.dot(&dir);
120        let proj = dir * scalar;
121        proj * (Self::Scalar::one() + Self::Scalar::one()) - self
122    }
123
124    /// Reflects a vector from the specified direction vector.
125    #[inline]
126    fn reflect(self, dir: Self) -> Self {
127        let ratio = self.dot(&dir) / dir.magnitude2();
128        dir * ratio * (Self::Scalar::one() + Self::Scalar::one()) - self
129    }
130}
131
132impl<T: DotProduct<Output = Self::Scalar>> InnerSpace for T {}
133
134/// The distance between two points.
135pub fn distance<T: AffineSpace>(a: T, b: T) -> <T::Diff as VectorSpace>::Scalar
136where
137    T::Diff: InnerSpace,
138{
139    (b - a).magnitude()
140}
141
142/// The squared distance between two points.
143pub fn distance2<T: AffineSpace>(a: T, b: T) -> <T::Diff as VectorSpace>::Scalar
144where
145    T::Diff: InnerSpace,
146{
147    (b - a).magnitude2()
148}
149
150/// The normalized direction between two points.
151pub fn direction<T: AffineSpace>(a: T, b: T) -> T::Diff
152where
153    T::Diff: InnerSpace,
154{
155    (b - a).normalize()
156}
inner_space/lib.rs

inner_space/
lib.rs
