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}