Files
makeCAD/crates/geom/src/unit_vec3.rs
T
JIJINBEI 7ad5130cd2 refactor: geom::UnitVec3 for unit axes and normals (#2603)
* geom: UnitVec3; a face's analytic axes and normals are unit by type

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* geom: UnitVec3 adds to and subtracts from a Vec3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* kernel, doc, engine: cylinder axes and measured normals held as UnitVec3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* kernel, engine: functions that take a unit axis or direction say so by type

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* doc: a face's normal goes to Plane::from_normal as is

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* kernel, doc: main's new cylinder helpers take the face's axis as a UnitVec3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 21:16:31 -04:00

121 lines
3.2 KiB
Rust

//! A unit vector: a 3D vector of length 1.
use std::ops::{Add, Deref, Mul, Neg, Sub};
use serde::{Deserialize, Serialize};
use crate::Vec3;
/// A unit vector: length 1 up to rounding. Made only from a vector with a length
/// ([`UnitVec3::new`], [`Vec3::unit`]), so a function taking one need not normalise it or
/// handle a zero vector again. It reads as the [`Vec3`] it holds (`d.dot(v)`, `*d`), and
/// [`Vec3::dot`] and [`Vec3::cross`] take one.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(into = "Vec3", try_from = "Vec3")]
pub struct UnitVec3(Vec3);
impl UnitVec3 {
pub const X: UnitVec3 = UnitVec3(Vec3::X);
pub const Y: UnitVec3 = UnitVec3(Vec3::Y);
pub const Z: UnitVec3 = UnitVec3(Vec3::Z);
/// `v` scaled to length 1; `None` when it has no length (or is not finite).
pub fn new(v: Vec3) -> Option<UnitVec3> {
v.normalized().map(UnitVec3)
}
pub fn vec(self) -> Vec3 {
self.0
}
}
impl Vec3 {
/// This vector scaled to length 1 ([`UnitVec3::new`]).
pub fn unit(self) -> Option<UnitVec3> {
UnitVec3::new(self)
}
}
impl Deref for UnitVec3 {
type Target = Vec3;
fn deref(&self) -> &Vec3 {
&self.0
}
}
impl From<UnitVec3> for Vec3 {
fn from(d: UnitVec3) -> Vec3 {
d.0
}
}
impl TryFrom<Vec3> for UnitVec3 {
type Error = &'static str;
fn try_from(v: Vec3) -> Result<UnitVec3, Self::Error> {
UnitVec3::new(v).ok_or("a unit vector needs a finite vector with a length")
}
}
impl From<&UnitVec3> for Vec3 {
fn from(d: &UnitVec3) -> Vec3 {
d.0
}
}
impl Neg for UnitVec3 {
type Output = UnitVec3;
fn neg(self) -> UnitVec3 {
UnitVec3(-self.0)
}
}
/// `+` and `-` with a [`Vec3`] or another unit vector, giving a [`Vec3`].
macro_rules! sum_ops {
($($l:ty, $r:ty);*) => {$(
impl Add<$r> for $l {
type Output = Vec3;
fn add(self, o: $r) -> Vec3 {
Vec3::from(self) + Vec3::from(o)
}
}
impl Sub<$r> for $l {
type Output = Vec3;
fn sub(self, o: $r) -> Vec3 {
Vec3::from(self) - Vec3::from(o)
}
}
)*};
}
sum_ops!(UnitVec3, Vec3; Vec3, UnitVec3; UnitVec3, UnitVec3);
impl Mul<f64> for UnitVec3 {
type Output = Vec3;
fn mul(self, s: f64) -> Vec3 {
self.0 * s
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_unit_vector_has_length_one() {
let d = Vec3::new(0.0, 3.0, 4.0).unit().unwrap();
assert_eq!(*d, Vec3::new(0.0, 0.6, 0.8));
assert_eq!(d * 5.0, Vec3::new(0.0, 3.0, 4.0));
assert_eq!(*-d, Vec3::new(0.0, -0.6, -0.8));
assert_eq!(d.dot(Vec3::Z), 0.8);
assert_eq!(UnitVec3::Z.cross(UnitVec3::X), Vec3::Y);
assert_eq!(Vec3::X.dot(d), 0.0);
assert_eq!(Vec3::X + d, Vec3::new(1.0, 0.6, 0.8));
assert!((d - UnitVec3::Z).dist(Vec3::new(0.0, 0.6, -0.2)) < 1e-15);
}
#[test]
fn no_length_no_unit_vector() {
assert_eq!(Vec3::ZERO.unit(), None);
assert_eq!(Vec3::new(f64::NAN, 0.0, 1.0).unit(), None);
assert_eq!(Vec3::new(f64::INFINITY, 0.0, 0.0).unit(), None);
}
}