Skip to main content

trackball/
plane.rs

1use crate::{Rigid, float};
2use glam::{Quat, Vec3};
3
4/// Plane encoding position with signed bias along unit normal.
5///
6/// Realizes plane equation `a*x+b*y+c*z+d=0` with unit normal `[x, y, z]` and signed bias `d`.
7#[derive(Debug, Clone, Copy, PartialEq)]
8#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
9#[cfg_attr(
10    feature = "rkyv-08",
11    derive(rkyv_08::Archive, rkyv_08::Serialize, rkyv_08::Deserialize),
12    rkyv(crate = rkyv_08)
13)]
14#[repr(C)]
15pub struct Plane {
16    /// Plane unit normal.
17    pub normal: Vec3,
18    /// Signed bias along unit normal.
19    pub bias: f32,
20}
21
22impl Plane {
23    /// Plane from unit `normal` and signed `distance` from the origin.
24    ///
25    /// ```
26    /// use trackball::{Plane, glam::Vec3};
27    ///
28    /// // Plane intersecting y-axis at `5.0`.
29    /// let plane = Plane::new(Vec3::Y, 5.0);
30    ///
31    /// // Origin projected onto plane where plane intersects y-axis.
32    /// let point = plane.project_point(Vec3::ZERO);
33    /// assert_eq!(point, Vec3::new(0.0, 5.0, 0.0));
34    ///
35    /// // Bias is negated distance.
36    /// assert_eq!(plane.distance(), 5.0);
37    /// assert_eq!(plane.bias, -5.0);
38    ///
39    /// // Plane intersecting y-axis at `-5.0`.
40    /// let plane = Plane::new(Vec3::Y, -5.0);
41    ///
42    /// // Origin projected onto plane where plane intersects y-axis.
43    /// let point = plane.project_point(Vec3::ZERO);
44    /// assert_eq!(point, Vec3::new(0.0, -5.0, 0.0));
45    ///
46    /// // Bias is negated distance.
47    /// assert_eq!(plane.distance(), -5.0);
48    /// assert_eq!(plane.bias, 5.0);
49    /// ```
50    #[must_use]
51    pub const fn new(normal: Vec3, distance: f32) -> Self {
52        Self {
53            normal,
54            bias: -distance,
55        }
56    }
57    /// Plane from unit normal with point in plane.
58    #[must_use]
59    pub fn with_point(normal: Vec3, point: Vec3) -> Self {
60        Self::new(normal, normal.dot(point))
61    }
62    /// Signed orthogonal distance from the origin.
63    #[must_use]
64    pub const fn distance(&self) -> f32 {
65        -self.bias
66    }
67    /// Signed orthogonal distance from `point`.
68    #[must_use]
69    pub fn distance_from(&self, point: Vec3) -> f32 {
70        self.distance() - self.normal.dot(point)
71    }
72    /// Projects point onto plane.
73    #[must_use]
74    pub fn project_point(&self, point: Vec3) -> Vec3 {
75        point - self.normal * (self.normal.dot(point) + self.bias)
76    }
77    /// Projects axis onto plane regardless of bias.
78    #[must_use]
79    pub fn project_axis(&self, axis: Vec3) -> Vec3 {
80        self.project_vector(axis).normalize()
81    }
82    /// Projects vector onto plane regardless of bias.
83    #[must_use]
84    pub fn project_vector(&self, vector: Vec3) -> Vec3 {
85        vector - self.normal * self.normal.dot(vector)
86    }
87    /// Signed angle from `a` to `b` where both vectors are in the plane.
88    ///
89    /// Unlike `Vec3::angle_between()`, small and nearly opposite angles are precise.
90    #[must_use]
91    pub fn angle_between(&self, a: Vec3, b: Vec3) -> f32 {
92        float::atan2(self.normal.dot(a.cross(b)), a.dot(b))
93    }
94    /// Rotates plane.
95    #[must_use]
96    pub fn rotate_by(self, rot: Quat) -> Self {
97        Self {
98            normal: rot * self.normal,
99            bias: self.bias,
100        }
101    }
102    /// Translates plane.
103    #[must_use]
104    pub fn translate_by(self, vec: Vec3) -> Self {
105        Self {
106            normal: self.normal,
107            bias: self.bias - self.normal.dot(vec),
108        }
109    }
110    /// Transforms plane by direct isometry, i.e., rotation followed by translation.
111    ///
112    /// ```
113    /// use core::f32::consts::FRAC_PI_2;
114    /// use trackball::{
115    ///     Plane, Rigid,
116    ///     glam::{Quat, Vec3},
117    /// };
118    ///
119    /// // Plane intersecting y-axis at `5.0`.
120    /// let plane = Plane::new(Vec3::Y, 5.0).transform_by(Rigid::from_rotation_translation(
121    ///     // Rotation by 90 degrees before translation.
122    ///     Quat::from_rotation_z(FRAC_PI_2),
123    ///     // Translation after rotation.
124    ///     Vec3::new(-5.0, 0.0, 0.0),
125    /// ));
126    /// // Plane intersecting x-axis at `-10.0`.
127    /// assert!(plane.abs_diff_eq(Plane::new(-Vec3::X, 10.0), 1e-6));
128    /// ```
129    #[must_use]
130    pub fn transform_by(self, rigid: Rigid) -> Self {
131        self.rotate_by(rigid.rotation)
132            .translate_by(rigid.translation)
133    }
134    /// Whether all components are approximately equal within absolute difference `max_abs_diff`.
135    #[must_use]
136    pub fn abs_diff_eq(&self, other: Self, max_abs_diff: f32) -> bool {
137        self.normal.abs_diff_eq(other.normal, max_abs_diff)
138            && (self.bias - other.bias).abs() <= max_abs_diff
139    }
140}