parry2d/query/sat/
mod.rs

1//! Application of the Separating Axis Theorem (SAT) for collision detection.
2//!
3//! # What is the Separating Axis Theorem?
4//!
5//! The **Separating Axis Theorem (SAT)** is a fundamental geometric principle used in collision
6//! detection. It states that two convex shapes do **not** intersect if and only if there exists
7//! an axis (a line) onto which the projections of the two shapes do not overlap.
8//!
9//! In simpler terms: if you can find a direction where, when you "shine a light" from that direction
10//! and look at the shadows cast by both shapes, those shadows don't overlap, then the shapes
11//! are not colliding.
12//!
13//! # How Does SAT Work?
14//!
15//! SAT works by testing a finite set of candidate axes to find a separating axis:
16//!
17//! 1. **Select candidate axes**: For polygons/polyhedra, these are typically:
18//!    - Face normals (perpendicular to each face)
19//!    - Edge cross products (perpendicular to pairs of edges from each shape, in 3D)
20//!
21//! 2. **Project both shapes onto each axis**: Find the extent (min and max) of each shape
22//!    along the axis by computing support points (the furthest points in that direction).
23//!
24//! 3. **Check for overlap**: If the projections don't overlap on any axis, the shapes don't collide.
25//!    If all axes show overlap, the shapes are intersecting.
26//!
27//! 4. **Find minimum separation**: The axis with the smallest overlap (or largest separation)
28//!    is the "best" separating axis, useful for computing penetration depth and contact normals.
29//!
30//! # When is SAT Used?
31//!
32//! SAT is particularly effective for:
33//!
34//! - **Convex polygonal shapes**: Cuboids (boxes), triangles, convex polygons/polyhedra
35//! - **Accurate contact information**: SAT can provide exact penetration depth and contact normals
36//! - **Shallow penetrations**: Works best when shapes are just touching or slightly overlapping
37//! - **Edge-edge contacts**: In 3D, SAT naturally handles edge-edge collisions between polyhedra
38//!
39//! Parry uses SAT alongside other algorithms:
40//! - **GJK**: For general convex shapes (faster for distance queries, but less accurate for contacts)
41//! - **EPA**: For penetration depth when GJK detects overlap (but SAT is often more accurate)
42//! - **Specialized algorithms**: For specific shape pairs (sphere-sphere, etc.)
43//!
44//! # Example: Cuboid-Cuboid Collision
45//!
46//! ```rust
47//! # #[cfg(all(feature = "dim3", feature = "f32"))] {
48//! use parry3d::shape::Cuboid;
49//! use parry3d::query::sat::*;
50//! use parry3d::na::{Isometry3, Vector3};
51//!
52//! // Create two boxes
53//! let box1 = Cuboid::new(Vector3::new(1.0, 1.0, 1.0));
54//! let box2 = Cuboid::new(Vector3::new(0.5, 0.5, 0.5));
55//!
56//! // Position them close together
57//! let pos12 = Isometry3::translation(1.5, 0.0, 0.0);
58//!
59//! // Test face normals from box1
60//! let (separation, _normal) = cuboid_cuboid_find_local_separating_normal_oneway(
61//!     &box1, &box2, &pos12
62//! );
63//!
64//! if separation > 0.0 {
65//!     println!("Boxes are separated by {}", separation);
66//! } else {
67//!     println!("Boxes are overlapping by {}", -separation);
68//! }
69//! # }
70//! ```
71//!
72//! # Module Organization
73//!
74//! This module provides SAT implementations for common shape pairs:
75//!
76//! - **Cuboid-Cuboid**: Box vs box collision (2D and 3D)
77//! - **Cuboid-Triangle**: Box vs triangle (2D and 3D)
78//! - **Cuboid-Segment**: Box vs line segment (2D and 3D)
79//! - **Cuboid-SupportMap**: Box vs any convex shape
80//! - **Triangle-Segment**: Triangle vs line segment (3D only)
81//! - **SupportMap-SupportMap**: Generic convex shape vs convex shape
82//!
83//! Each module provides functions to:
84//! - Find the best separating normal (testing face normals)
85//! - Find the best separating edge (testing edge cross products, 3D only)
86//! - Compute separation distance along a given axis
87
88pub use self::sat_cuboid_cuboid::*;
89pub use self::sat_cuboid_point::*;
90pub use self::sat_cuboid_segment::*;
91pub use self::sat_cuboid_support_map::*;
92pub use self::sat_cuboid_triangle::*;
93pub use self::sat_support_map_support_map::*;
94#[cfg(feature = "dim3")]
95pub use self::sat_triangle_segment::*;
96// pub use self::sat_polygon_polygon::*;
97
98mod sat_cuboid_cuboid;
99mod sat_cuboid_point;
100mod sat_cuboid_segment;
101mod sat_cuboid_support_map;
102mod sat_cuboid_triangle;
103mod sat_support_map_support_map;
104#[cfg(feature = "dim3")]
105mod sat_triangle_segment;
106// mod sat_polygon_polygon;
parry2d/query/sat/mod.rs

parry2d/query/sat/
mod.rs
