Skip to main content

math/
plane.rs

1use maths_rs::{cross, dot, length, normalize, Vec3f};
2
3use crate::sphere::Sphere;
4
5/// The `Plane` struct provides a plane for 3D distance and half-space tests.
6///
7/// The plane uses the equation `N.x*x + N.y*y + N.z*z + D = 0`. The `normal`
8/// field stores `N`, and `distance` stores `D`. Use a unit normal when results
9/// must use world-space distance units.
10#[derive(Clone, Copy, Debug)]
11pub struct Plane {
12	pub normal: Vec3f,
13	pub distance: f32,
14}
15
16impl Plane {
17	/// Creates a plane from a normal vector and the equation constant `D`.
18	pub fn new(normal: Vec3f, distance: f32) -> Self {
19		let length = length(normal);
20		let normal = normal / length; // Normalize the normal vector
21		let distance = distance / length; // Adjust distance accordingly
22		Self { normal, distance }
23	}
24
25	/// Creates a plane through three noncollinear points.
26	///
27	/// The returned plane has a unit normal and contains each input point.
28	pub fn from_points(p1: Vec3f, p2: Vec3f, p3: Vec3f) -> Self {
29		let v1 = p2 - p1;
30		let v2 = p3 - p1;
31		let normal = normalize(cross(v1, v2));
32		let distance = -dot(normal, p1);
33		Self { normal, distance }
34	}
35
36	/// Returns the signed distance from a point to this plane.
37	///
38	/// A positive value is on the normal side, a negative value is on the opposite
39	/// side, and zero is on the plane. The result uses world-space distance units
40	/// when the plane has a unit normal.
41	pub fn signed_distance_to_point(&self, point: Vec3f) -> f32 {
42		dot(self.normal, point) + self.distance
43	}
44
45	/// Returns whether any part of a sphere is in this plane's positive half-space.
46	pub fn is_sphere_in_half_space(&self, sphere: &Sphere) -> bool {
47		let dist_to_center = self.signed_distance_to_point(sphere.center);
48		dist_to_center >= -sphere.radius
49	}
50}
51
52#[cfg(test)]
53mod tests {
54	use super::*;
55	use crate::{assert_float_eq, assert_vec3f_near};
56
57	#[test]
58	fn test_plane_new_and_signed_distance() {
59		let normal = normalize(Vec3f::new(1.0, 2.0, -2.0)); // Normal vector (1/3, 2/3, -2/3)
60		let distance_d = -5.0;
61		let plane = Plane::new(normal, distance_d);
62
63		// Point on the plane: P such that N.P + D = 0 => N.P = -D.
64		// A simple choice for P is -D * N (if N is unit vector)
65		let point_on_plane = normal * (-distance_d);
66		assert_float_eq!(
67			plane.signed_distance_to_point(point_on_plane),
68			0.0,
69			"Point on plane should have zero distance"
70		);
71
72		let point_positive_side = point_on_plane + normal * 3.0; // 3 units along normal
73		assert_float_eq!(
74			plane.signed_distance_to_point(point_positive_side),
75			3.0,
76			"Point on positive side distance check"
77		);
78
79		let point_negative_side = point_on_plane - normal * 4.0; // 4 units against normal
80		assert_float_eq!(
81			plane.signed_distance_to_point(point_negative_side),
82			-4.0,
83			"Point on negative side distance check"
84		);
85	}
86
87	#[test]
88	fn test_from_points_origin_xy_plane() {
89		let p1 = Vec3f::new(0.0, 0.0, 0.0);
90		let p2 = Vec3f::new(2.0, 0.0, 0.0);
91		let p3 = Vec3f::new(0.0, 3.0, 0.0);
92		let plane = Plane::from_points(p1, p2, p3);
93
94		// v1 = p2-p1 = (2,0,0), v2 = p3-p1 = (0,3,0)
95		// cross(v1,v2) = (0,0,6). normalize -> (0,0,1)
96		let expected_normal = Vec3f::new(0.0, 0.0, 1.0);
97		// distance = -dot(normal, p1) = -dot((0,0,1), (0,0,0)) = 0
98		let expected_distance_d = 0.0;
99
100		assert_vec3f_near!(plane.normal, expected_normal, "Normal for XY plane");
101		assert_float_eq!(plane.distance, expected_distance_d, "Distance D for XY plane");
102
103		assert_float_eq!(plane.signed_distance_to_point(p1), 0.0, "p1 on XY plane");
104		assert_float_eq!(plane.signed_distance_to_point(p2), 0.0, "p2 on XY plane");
105		assert_float_eq!(plane.signed_distance_to_point(p3), 0.0, "p3 on XY plane");
106
107		let test_point_on_plane = Vec3f::new(5.0, -5.0, 0.0);
108		assert_float_eq!(
109			plane.signed_distance_to_point(test_point_on_plane),
110			0.0,
111			"Another point on XY plane"
112		);
113		let test_point_off_plane_pos = Vec3f::new(0.0, 0.0, 1.0);
114		assert_float_eq!(
115			plane.signed_distance_to_point(test_point_off_plane_pos),
116			1.0,
117			"Point on positive side of XY plane"
118		);
119		let test_point_off_plane_neg = Vec3f::new(0.0, 0.0, -2.0);
120		assert_float_eq!(
121			plane.signed_distance_to_point(test_point_off_plane_neg),
122			-2.0,
123			"Point on negative side of XY plane"
124		);
125	}
126
127	#[test]
128	fn test_from_points_offset_plane_x_equals_constant() {
129		// Plane x = -2
130		let p1 = Vec3f::new(-2.0, 0.0, 0.0);
131		let p2 = Vec3f::new(-2.0, 1.0, 0.0); // p2-p1 = (0,1,0)
132		let p3 = Vec3f::new(-2.0, 0.0, 1.0); // p3-p1 = (0,0,1)
133		let plane = Plane::from_points(p1, p2, p3);
134
135		// cross((0,1,0), (0,0,1)) = (1,0,0). normalize -> (1,0,0)
136		let expected_normal = Vec3f::new(1.0, 0.0, 0.0);
137		// distance = -dot((1,0,0), (-2,0,0)) = -(-2) = 2.0
138		let expected_distance_d = 2.0;
139
140		assert_vec3f_near!(plane.normal, expected_normal, "Normal for x=-2 plane");
141		assert_float_eq!(plane.distance, expected_distance_d, "Distance D for x=-2 plane");
142
143		assert_float_eq!(plane.signed_distance_to_point(p1), 0.0, "p1 on x=-2 plane");
144		assert_float_eq!(plane.signed_distance_to_point(p2), 0.0, "p2 on x=-2 plane");
145		assert_float_eq!(plane.signed_distance_to_point(p3), 0.0, "p3 on x=-2 plane");
146
147		let test_point_on_plane = Vec3f::new(-2.0, 5.0, 5.0);
148		assert_float_eq!(
149			plane.signed_distance_to_point(test_point_on_plane),
150			0.0,
151			"Another point on x=-2 plane"
152		);
153		// N.P + D = (1,0,0).(-1,0,0) + 2 = -1 + 2 = 1
154		let test_point_off_plane_pos = Vec3f::new(-1.0, 0.0, 0.0);
155		assert_float_eq!(
156			plane.signed_distance_to_point(test_point_off_plane_pos),
157			1.0,
158			"Point on positive side of x=-2 plane (x=-1)"
159		);
160		// N.P + D = (1,0,0).(-3,0,0) + 2 = -3 + 2 = -1
161		let test_point_off_plane_neg = Vec3f::new(-3.0, 0.0, 0.0);
162		assert_float_eq!(
163			plane.signed_distance_to_point(test_point_off_plane_neg),
164			-1.0,
165			"Point on negative side of x=-2 plane (x=-3)"
166		);
167	}
168
169	#[test]
170	fn test_from_points_general_case_properties() {
171		let p1 = Vec3f::new(1.0, 2.0, 3.0);
172		let p2 = Vec3f::new(4.0, -1.0, 5.0);
173		let p3 = Vec3f::new(-2.0, 4.0, -3.0); // Ensure non-collinear
174		let plane = Plane::from_points(p1, p2, p3);
175
176		// Check if the normal is a unit vector
177		assert_float_eq!(dot(plane.normal, plane.normal), 1.0, "Normal vector should be unit length");
178
179		// Check if all three defining points lie on the generated plane
180		assert_float_eq!(plane.signed_distance_to_point(p1), 0.0, "p1 should be on the generated plane");
181		assert_float_eq!(plane.signed_distance_to_point(p2), 0.0, "p2 should be on the generated plane");
182		assert_float_eq!(plane.signed_distance_to_point(p3), 0.0, "p3 should be on the generated plane");
183	}
184
185	#[test]
186	fn test_from_points_winding_order() {
187		let p1 = Vec3f::new(1.0, 0.0, 0.0);
188		let p2 = Vec3f::new(0.0, 1.0, 0.0);
189		let p3 = Vec3f::new(0.0, 0.0, 1.0);
190
191		let plane1 = Plane::from_points(p1, p2, p3); // (p2-p1) x (p3-p1)
192		let plane2 = Plane::from_points(p1, p3, p2); // (p3-p1) x (p2-p1)
193
194		// Normals should be opposite
195		assert_vec3f_near!(plane1.normal, plane2.normal * -1.0, "Normals should be opposite");
196		// Distances D should be opposite (since D = -N.p1)
197		assert_float_eq!(plane1.distance, -plane2.distance, "Distances D should be opposite");
198
199		// Both planes must still contain all three points (distance = 0)
200		for p_idx in [p1, p2, p3].iter().enumerate() {
201			assert_float_eq!(
202				plane1.signed_distance_to_point(*p_idx.1),
203				0.0,
204				"Point p{} on plane1",
205				p_idx.0 + 1
206			);
207			assert_float_eq!(
208				plane2.signed_distance_to_point(*p_idx.1),
209				0.0,
210				"Point p{} on plane2",
211				p_idx.0 + 1
212			);
213		}
214
215		// For any other point, signed distances should be opposite
216		let test_point = Vec3f::new(5.0, 5.0, 5.0);
217		let dist1 = plane1.signed_distance_to_point(test_point);
218		let dist2 = plane2.signed_distance_to_point(test_point);
219		assert_float_eq!(
220			dist1,
221			-dist2,
222			"Signed distances to a test point should be opposite for reversed winding"
223		);
224	}
225}