7ad5130cd2
* 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>
121 lines
3.2 KiB
Rust
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);
|
|
}
|
|
}
|