cadcore_math/
vec3.rs

1//! 3-D vector (`Vec3`).
2
3use std::fmt;
4use std::ops::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Neg, Sub, SubAssign};
5
6use crate::EPS;
7
8/// A free 3-D vector with f64 components.
9///
10/// Distinct from [`crate::Point3`]: a `Vec3` represents a *direction + magnitude*,
11/// while a `Point3` represents a *location*.  The two types are deliberately
12/// separated so the compiler catches confusion between them.
13#[derive(Clone, Copy, PartialEq)]
14#[repr(C)]
15pub struct Vec3 {
16    /// X component.
17    pub x: f64,
18    /// Y component.
19    pub y: f64,
20    /// Z component.
21    pub z: f64,
22}
23
24impl Vec3 {
25    /// Zero vector.
26    pub const ZERO: Self = Self { x: 0.0, y: 0.0, z: 0.0 };
27    /// Unit vector along +X.
28    pub const X: Self = Self { x: 1.0, y: 0.0, z: 0.0 };
29    /// Unit vector along +Y.
30    pub const Y: Self = Self { x: 0.0, y: 1.0, z: 0.0 };
31    /// Unit vector along +Z.
32    pub const Z: Self = Self { x: 0.0, y: 0.0, z: 1.0 };
33
34    /// Construct from components.
35    #[inline] pub const fn new(x: f64, y: f64, z: f64) -> Self { Self { x, y, z } }
36
37    /// Squared Euclidean length.
38    #[inline] pub fn length_sq(self) -> f64 { self.dot(self) }
39
40    /// Euclidean length.
41    #[inline] pub fn length(self) -> f64 { self.length_sq().sqrt() }
42
43    /// Dot product.
44    #[inline]
45    pub fn dot(self, rhs: Self) -> f64 {
46        self.x * rhs.x + self.y * rhs.y + self.z * rhs.z
47    }
48
49    /// Cross product: `self × rhs`.
50    #[inline]
51    pub fn cross(self, rhs: Self) -> Self {
52        Self {
53            x: self.y * rhs.z - self.z * rhs.y,
54            y: self.z * rhs.x - self.x * rhs.z,
55            z: self.x * rhs.y - self.y * rhs.x,
56        }
57    }
58
59    /// Return the normalised version of this vector, or `None` if near-zero.
60    #[inline]
61    pub fn try_normalize(self) -> Option<Self> {
62        let len = self.length();
63        if len < EPS { None } else { Some(self / len) }
64    }
65
66    /// Normalise without a safety check (panics on zero in debug builds).
67    #[inline]
68    pub fn normalize(self) -> Self {
69        self.try_normalize().expect("Vec3::normalize called on zero vector")
70    }
71
72    /// Component-wise absolute value.
73    #[inline]
74    pub fn abs(self) -> Self { Self::new(self.x.abs(), self.y.abs(), self.z.abs()) }
75
76    /// Reflect `self` about a unit normal `n`.
77    #[inline]
78    pub fn reflect(self, n: Self) -> Self { self - n * (2.0 * self.dot(n)) }
79
80    /// Return a vector perpendicular to `self` (arbitrary, consistent).
81    pub fn any_perp(self) -> Self {
82        // Choose the axis with the smallest absolute component to maximise
83        // numerical stability of the cross product.
84        if self.x.abs() <= self.y.abs() && self.x.abs() <= self.z.abs() {
85            self.cross(Self::X)
86        } else if self.y.abs() <= self.z.abs() {
87            self.cross(Self::Y)
88        } else {
89            self.cross(Self::Z)
90        }
91    }
92
93    /// Linearly interpolate: `(1-t)*self + t*rhs`.
94    #[inline]
95    pub fn lerp(self, rhs: Self, t: f64) -> Self { self + (rhs - self) * t }
96}
97
98// ── Arithmetic operators ─────────────────────────────────────────────────────
99
100impl Add for Vec3 {
101    type Output = Self;
102    #[inline] fn add(self, r: Self) -> Self { Self::new(self.x+r.x, self.y+r.y, self.z+r.z) }
103}
104impl Sub for Vec3 {
105    type Output = Self;
106    #[inline] fn sub(self, r: Self) -> Self { Self::new(self.x-r.x, self.y-r.y, self.z-r.z) }
107}
108impl Neg for Vec3 {
109    type Output = Self;
110    #[inline] fn neg(self) -> Self { Self::new(-self.x, -self.y, -self.z) }
111}
112impl Mul<f64> for Vec3 {
113    type Output = Self;
114    #[inline] fn mul(self, s: f64) -> Self { Self::new(self.x*s, self.y*s, self.z*s) }
115}
116impl Mul<Vec3> for f64 {
117    type Output = Vec3;
118    #[inline] fn mul(self, v: Vec3) -> Vec3 { v * self }
119}
120impl Div<f64> for Vec3 {
121    type Output = Self;
122    #[inline] fn div(self, s: f64) -> Self { self * (1.0 / s) }
123}
124
125impl AddAssign for Vec3 { #[inline] fn add_assign(&mut self, r: Self) { *self = *self + r; } }
126impl SubAssign for Vec3 { #[inline] fn sub_assign(&mut self, r: Self) { *self = *self - r; } }
127impl MulAssign<f64> for Vec3 { #[inline] fn mul_assign(&mut self, s: f64) { *self = *self * s; } }
128impl DivAssign<f64> for Vec3 { #[inline] fn div_assign(&mut self, s: f64) { *self = *self / s; } }
129
130impl fmt::Debug for Vec3 {
131    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
132        write!(f, "Vec3({:.6}, {:.6}, {:.6})", self.x, self.y, self.z)
133    }
134}
135impl fmt::Display for Vec3 {
136    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
137        write!(f, "({:.4}, {:.4}, {:.4})", self.x, self.y, self.z)
138    }
139}
140
141#[cfg(test)]
142mod tests {
143    use super::*;
144
145    #[test]
146    fn cross_product() {
147        let x = Vec3::X;
148        let y = Vec3::Y;
149        let z = x.cross(y);
150        assert!((z - Vec3::Z).length() < 1e-12);
151    }
152
153    #[test]
154    fn normalize_unit_length() {
155        let v = Vec3::new(3.0, 4.0, 0.0).normalize();
156        assert!((v.length() - 1.0).abs() < 1e-12);
157    }
158
159    #[test]
160    fn reflect() {
161        let v = Vec3::new(1.0, -1.0, 0.0);
162        let n = Vec3::Y;
163        let r = v.reflect(n);
164        assert!((r - Vec3::new(1.0, 1.0, 0.0)).length() < 1e-12);
165    }
166}
cadcore_math/vec3.rs

cadcore_math/
vec3.rs
