Struct Aabb

#[repr(C)]
pub struct Aabb {
    pub mins: Point<f32>,
    pub maxs: Point<f32>,
}

An Axis-Aligned Bounding Box (AABB).

An AABB is the simplest bounding volume, defined by its minimum and maximum corners. It’s called “axis-aligned” because its edges are always parallel to the coordinate axes (X, Y, and Z in 3D), making it very fast to test and compute.

Structure

• mins: The point with the smallest coordinates on each axis (bottom-left-back corner)
• maxs: The point with the largest coordinates on each axis (top-right-front corner)
• Invariant: mins.x ≤ maxs.x, mins.y ≤ maxs.y (and mins.z ≤ maxs.z in 3D)

Properties

• Axis-aligned: Edges always parallel to coordinate axes
• Conservative: May be larger than the actual shape for rotated objects
• Fast: Intersection tests are very cheap (just coordinate comparisons)
• Hierarchical: Perfect for spatial data structures (BVH, quadtree, octree)

Use Cases

AABBs are fundamental to collision detection and are used for:

• Broad-phase collision detection: Quickly eliminate distant object pairs
• Spatial partitioning: Building BVHs, quadtrees, and octrees
• View frustum culling: Determining what’s visible
• Ray tracing acceleration: Quickly rejecting non-intersecting rays
• Bounding volume for any shape: Every shape can compute its AABB

Performance

AABBs are the fastest bounding volume for:

• Intersection tests: O(1) with just 6 comparisons (3D)
• Merging: O(1) with component-wise min/max
• Contains test: O(1) with coordinate comparisons

Limitations

• Rotation invariance: Must be recomputed when objects rotate
• Tightness: May waste space for rotated or complex shapes
• No orientation: Cannot represent oriented bounding boxes (OBB)

Example

use parry3d::bounding_volume::Aabb;
use nalgebra::Point3;

// Create an AABB for a unit cube centered at origin
let mins = Point3::new(-0.5, -0.5, -0.5);
let maxs = Point3::new(0.5, 0.5, 0.5);
let aabb = Aabb::new(mins, maxs);

// Check if a point is inside
let point = Point3::origin();
assert!(aabb.contains_local_point(&point));

// Get center and extents
assert_eq!(aabb.center(), Point3::origin());
assert_eq!(aabb.extents().x, 1.0); // Full width
assert_eq!(aabb.half_extents().x, 0.5); // Half width

use parry3d::bounding_volume::Aabb;
use nalgebra::Point3;

// Create from a set of points
let points = vec![
    Point3::new(1.0, 2.0, 3.0),
    Point3::new(-1.0, 4.0, 2.0),
    Point3::new(0.0, 0.0, 5.0),
];
let aabb = Aabb::from_points(points);

// The AABB encloses all points
assert_eq!(aabb.mins, Point3::new(-1.0, 0.0, 2.0));
assert_eq!(aabb.maxs, Point3::new(1.0, 4.0, 5.0));

Fields

mins: Point<f32>

The point with minimum coordinates (bottom-left-back corner).

Each component (x, y, z) should be less than or equal to the corresponding component in maxs.

maxs: Point<f32>

The point with maximum coordinates (top-right-front corner).

Each component (x, y, z) should be greater than or equal to the corresponding component in mins.

Implementations

impl Aabb

pub const EDGES_VERTEX_IDS: [(usize, usize); 12]

The vertex indices of each edge of this Aabb.

This gives, for each edge of this Aabb, the indices of its vertices when taken from the self.vertices() array. Here is how the faces are numbered, assuming a right-handed coordinate system:

   y             3 - 2
   |           7 − 6 |
   ___ x       |   | 1  (the zero is below 3 and on the left of 1,
  /            4 - 5     hidden by the 4-5-6-7 face.)
 z

pub const FACES_VERTEX_IDS: [(usize, usize, usize, usize); 6]

The vertex indices of each face of this Aabb.

This gives, for each face of this Aabb, the indices of its vertices when taken from the self.vertices() array. Here is how the faces are numbered, assuming a right-handed coordinate system:

   y             3 - 2
   |           7 − 6 |
   ___ x       |   | 1  (the zero is below 3 and on the left of 1,
  /            4 - 5     hidden by the 4-5-6-7 face.)
 z

pub fn new(mins: Point<f32>, maxs: Point<f32>) -> Aabb

Creates a new AABB from its minimum and maximum corners.

Arguments

• mins - The point with the smallest coordinates on each axis
• maxs - The point with the largest coordinates on each axis

Invariant

Each component of mins should be ≤ the corresponding component of maxs.

Example

use parry3d::bounding_volume::Aabb;
use nalgebra::Point3;

// Create a 2x2x2 cube centered at origin
let aabb = Aabb::new(
    Point3::new(-1.0, -1.0, -1.0),
    Point3::new(1.0, 1.0, 1.0)
);

assert_eq!(aabb.center(), Point3::origin());
assert_eq!(aabb.extents(), nalgebra::Vector3::new(2.0, 2.0, 2.0));

pub fn new_invalid() -> Self

Creates an invalid AABB with inverted bounds.

The resulting AABB has mins set to maximum values and maxs set to minimum values. This is useful as an initial value for AABB merging algorithms (similar to starting a min operation with infinity).

Example

use parry3d::bounding_volume::{Aabb, BoundingVolume};
use nalgebra::Point3;

let mut aabb = Aabb::new_invalid();

// Merge with actual points to build proper AABB
aabb.merge(&Aabb::new(Point3::new(1.0, 2.0, 3.0), Point3::new(1.0, 2.0, 3.0)));
aabb.merge(&Aabb::new(Point3::new(-1.0, 0.0, 2.0), Point3::new(-1.0, 0.0, 2.0)));

// Now contains the merged bounds
assert_eq!(aabb.mins, Point3::new(-1.0, 0.0, 2.0));
assert_eq!(aabb.maxs, Point3::new(1.0, 2.0, 3.0));

pub fn from_half_extents(center: Point<f32>, half_extents: Vector<f32>) -> Self

Creates a new AABB from its center and half-extents.

This is often more intuitive than specifying min and max corners.

Arguments

• center - The center point of the AABB
• half_extents - Half the dimensions along each axis

Example

use parry3d::bounding_volume::Aabb;
use nalgebra::{Point3, Vector3};

// Create a 10x6x8 box centered at (5, 0, 0)
let aabb = Aabb::from_half_extents(
    Point3::new(5.0, 0.0, 0.0),
    Vector3::new(5.0, 3.0, 4.0)
);

assert_eq!(aabb.mins, Point3::new(0.0, -3.0, -4.0));
assert_eq!(aabb.maxs, Point3::new(10.0, 3.0, 4.0));
assert_eq!(aabb.center(), Point3::new(5.0, 0.0, 0.0));

pub fn from_points_ref<'a, I>(pts: I) -> Self

where I: IntoIterator<Item = &'a Point<f32>>,

Creates a new AABB that tightly encloses a set of points (references).

Computes the minimum and maximum coordinates across all points.

Arguments

• pts - An iterator over point references

Example

use parry3d::bounding_volume::Aabb;
use nalgebra::Point3;

let points = vec![
    Point3::new(1.0, 2.0, 3.0),
    Point3::new(-1.0, 4.0, 2.0),
    Point3::new(0.0, 0.0, 5.0),
];

let aabb = Aabb::from_points_ref(&points);
assert_eq!(aabb.mins, Point3::new(-1.0, 0.0, 2.0));
assert_eq!(aabb.maxs, Point3::new(1.0, 4.0, 5.0));

pub fn from_points<I>(pts: I) -> Self

where I: IntoIterator<Item = Point<f32>>,

Creates a new AABB that tightly encloses a set of points (values).

Computes the minimum and maximum coordinates across all points.

Arguments

• pts - An iterator over point values

Example

use parry3d::bounding_volume::Aabb;
use nalgebra::Point3;

let aabb = Aabb::from_points(vec![
    Point3::new(1.0, 2.0, 3.0),
    Point3::new(-1.0, 4.0, 2.0),
    Point3::new(0.0, 0.0, 5.0),
]);

assert_eq!(aabb.mins, Point3::new(-1.0, 0.0, 2.0));
assert_eq!(aabb.maxs, Point3::new(1.0, 4.0, 5.0));

pub fn center(&self) -> Point<f32>

Returns the center point of this AABB.

The center is the midpoint between mins and maxs.

Example

use parry3d::bounding_volume::Aabb;
use nalgebra::Point3;

let aabb = Aabb::new(
    Point3::new(-2.0, -3.0, -4.0),
    Point3::new(2.0, 3.0, 4.0)
);

assert_eq!(aabb.center(), Point3::origin());

pub fn half_extents(&self) -> Vector<f32>

Returns the half-extents of this AABB.

Half-extents are half the dimensions along each axis.

Example

use parry3d::bounding_volume::Aabb;
use nalgebra::{Point3, Vector3};

let aabb = Aabb::new(
    Point3::new(-5.0, -3.0, -2.0),
    Point3::new(5.0, 3.0, 2.0)
);

let half = aabb.half_extents();
assert_eq!(half, Vector3::new(5.0, 3.0, 2.0));

// Full dimensions are 2 * half_extents
let full = aabb.extents();
assert_eq!(full, Vector3::new(10.0, 6.0, 4.0));

pub fn volume(&self) -> f32

Returns the volume of this AABB.

• 2D: Returns the area (width × height)
• 3D: Returns the volume (width × height × depth)

Example

use parry3d::bounding_volume::Aabb;
use nalgebra::Point3;

// A 2x3x4 box
let aabb = Aabb::new(
    Point3::origin(),
    Point3::new(2.0, 3.0, 4.0)
);

assert_eq!(aabb.volume(), 24.0); // 2 * 3 * 4

pub fn half_area_or_perimeter(&self) -> f32

In 3D, returns the half-area. In 2D returns the half-perimeter of the AABB.

pub fn half_area(&self) -> f32

The half area of this Aabb.

pub fn extents(&self) -> Vector<f32>

The extents of this Aabb.

pub fn take_point(&mut self, pt: Point<f32>)

Enlarges this Aabb so it also contains the point pt.

pub fn transform_by(&self, m: &Isometry<f32>) -> Self

Computes the Aabb bounding self transformed by m.

pub fn translated(self, translation: &Vector<f32>) -> Self

Computes the Aabb bounding self translated by translation.

pub fn scaled(self, scale: &Vector<f32>) -> Self

pub fn scaled_wrt_center(self, scale: &Vector<f32>) -> Self

Returns an AABB with the same center as self but with extents scaled by scale.

Parameters

• scale: the scaling factor. It can be non-uniform and/or negative. The AABB being symmetric wrt. its center, a negative scale value has the same effect as scaling by its absolute value.

pub fn bounding_sphere(&self) -> BoundingSphere

The smallest bounding sphere containing this Aabb.

pub fn contains_local_point(&self, point: &Point<f32>) -> bool

Does this AABB contains a point expressed in the same coordinate frame as self?

pub fn distance_to_origin(&self) -> f32

Computes the distance between the origin and this AABB.

pub fn intersects_moving_aabb(&self, aabb2: &Self, vel12: Vector<f32>) -> bool

Does this AABB intersects an AABB aabb2 moving at velocity vel12 relative to self?

pub fn intersection(&self, other: &Aabb) -> Option<Aabb>

Computes the intersection of this Aabb and another one.

pub fn aligned_intersections( &self, pos12: &Isometry<f32>, aabb2: &Self, ) -> Option<(Aabb, Aabb)>

Computes two AABBs for the intersection between two translated and rotated AABBs.

This method returns two AABBs: the first is expressed in the local-space of self, and the second is expressed in the local-space of aabb2.

pub fn difference(&self, rhs: &Aabb) -> ArrayVec<Self, TWO_DIM>

Returns the difference between this Aabb and rhs.

Removing another Aabb from self will result in zero, one, or up to 4 (in 2D) or 8 (in 3D) new smaller Aabbs.

pub fn difference_with_cut_sequence( &self, rhs: &Aabb, ) -> (ArrayVec<Self, TWO_DIM>, ArrayVec<(i8, f32), TWO_DIM>)

Returns the difference between this Aabb and rhs.

Removing another Aabb from self will result in zero, one, or up to 4 (in 2D) or 8 (in 3D) new smaller Aabbs.

Return

This returns a pair where the first item are the new Aabbs and the second item is the sequence of cuts applied to self to obtain the new Aabbs. Each cut is performed along one axis identified by -1, -2, -3 for -X, -Y, -Z and 1, 2, 3 for +X, +Y, +Z, and the plane’s bias.

The cuts are applied sequentially. For example, if result.1[0] contains 1, then it means that result.0[0] is equal to the piece of self lying in the negative half-space delimited by the plane with outward normal +X. Then, the other piece of self generated by this cut (i.e. the piece of self lying in the positive half-space delimited by the plane with outward normal +X) is the one that will be affected by the next cut.

The returned cut sequence will be empty if the aabbs are disjoint.

pub fn vertices(&self) -> [Point<f32>; 8]

Computes the vertices of this Aabb.

The vertices are given in the following order, in a right-handed coordinate system:

   y             3 - 2
   |           7 − 6 |
   ___ x       |   | 1  (the zero is below 3 and on the left of 1,
  /            4 - 5     hidden by the 4-5-6-7 face.)
 z

pub fn split_at_center(&self) -> [Aabb; 8]

Splits this Aabb at its center, into eight parts (as in an octree).

pub fn add_half_extents(&self, half_extents: &Vector<f32>) -> Self

Enlarges this AABB on each side by the given half_extents.

pub fn project_on_axis(&self, axis: &UnitVector<f32>) -> (f32, f32)

Projects every point of Aabb on an arbitrary axis.

pub fn intersects_spiral( &self, point: &Point<f32>, center: &Point<f32>, axis: &UnitVector<f32>, linvel: &Vector<f32>, angvel: f32, ) -> bool

impl Aabb

pub fn clip_segment(&self, pa: &Point<f32>, pb: &Point<f32>) -> Option<Segment>

Computes the intersection of a segment with this Aabb.

Returns None if there is no intersection or if pa is invalid (contains NaN).

pub fn clip_line_parameters( &self, orig: &Point<f32>, dir: &Vector<f32>, ) -> Option<(f32, f32)>

Computes the parameters of the two intersection points between a line and this Aabb.

The parameters are such that the point are given by orig + dir * parameter. Returns None if there is no intersection or if orig is invalid (contains NaN).

pub fn clip_line(&self, orig: &Point<f32>, dir: &Vector<f32>) -> Option<Segment>

Computes the intersection segment between a line and this Aabb.

Returns None if there is no intersection or if orig is invalid (contains NaN).

pub fn clip_ray_parameters(&self, ray: &Ray) -> Option<(f32, f32)>

Computes the parameters of the two intersection points between a ray and this Aabb.

The parameters are such that the point are given by ray.orig + ray.dir * parameter. Returns None if there is no intersection or if ray.orig is invalid (contains NaN).

pub fn clip_ray(&self, ray: &Ray) -> Option<Segment>

Computes the intersection segment between a ray and this Aabb.

Returns None if there is no intersection.

impl Aabb

pub fn clip_polygon(&self, points: &mut Vec<Point<f32>>)

Computes the intersections between this Aabb and the given polygon.

The results is written into points directly. The input points are assumed to form a convex polygon where all points lie on the same plane. In order to avoid internal allocations, uses self.clip_polygon_with_workspace instead.

pub fn clip_polygon_with_workspace( &self, points: &mut Vec<Point<f32>>, workspace: &mut Vec<Point<f32>>, )

Computes the intersections between this Aabb and the given polygon.

The results is written into points directly. The input points are assumed to form a convex polygon where all points lie on the same plane.

impl Aabb

pub fn canonical_split( &self, axis: usize, bias: f32, epsilon: f32, ) -> SplitResult<Self>

Splits this Aabb along the given canonical axis.

This will split the Aabb by a plane with a normal with it’s axis-th component set to 1. The splitting plane is shifted wrt. the origin by the bias (i.e. it passes through the point equal to normal * bias).

Result

Returns the result of the split. The first Aabb returned is the piece lying on the negative half-space delimited by the splitting plane. The second Aabb returned is the piece lying on the positive half-space delimited by the splitting plane.

impl Aabb

pub fn to_outline(&self) -> (Vec<Point<f32>>, Vec<[u32; 2]>)

Outlines this Aabb’s shape using polylines.

impl Aabb

pub fn to_trimesh(&self) -> (Vec<Point<f32>>, Vec<[u32; 3]>)

Discretize the boundary of this Aabb as a triangle-mesh.

Trait Implementations

impl BoundingVolume for Aabb

fn center(&self) -> Point<f32>

Returns a point inside of this bounding volume. This is ideally its center.

fn intersects(&self, other: &Aabb) -> bool

Checks if this bounding volume intersect with another one.

fn contains(&self, other: &Aabb) -> bool

Checks if this bounding volume contains another one.

fn merge(&mut self, other: &Aabb)

Merges this bounding volume with another one. The merge is done in-place.

fn merged(&self, other: &Aabb) -> Aabb

Merges this bounding volume with another one.

fn loosen(&mut self, amount: f32)

Enlarges this bounding volume.

fn loosened(&self, amount: f32) -> Aabb

Creates a new, enlarged version, of this bounding volume.

fn tighten(&mut self, amount: f32)

Tighten this bounding volume.

fn tightened(&self, amount: f32) -> Aabb

Creates a new, tightened version, of this bounding volume.

impl Clone for Aabb

fn clone(&self) -> Aabb

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Aabb

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Aabb

fn eq(&self, other: &Aabb) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PointQuery for Aabb

fn project_local_point(&self, pt: &Point<f32>, solid: bool) -> PointProjection

Projects a point on self.

fn project_local_point_and_get_feature( &self, pt: &Point<f32>, ) -> (PointProjection, FeatureId)

Projects a point on the boundary of self and returns the id of the feature the point was projected on.

fn distance_to_local_point(&self, pt: &Point<f32>, solid: bool) -> f32

Computes the minimal distance between a point and self.

fn project_local_point_with_max_dist( &self, pt: &Point<f32>, solid: bool, max_dist: f32, ) -> Option<PointProjection>

Projects a point onto the shape, with a maximum distance limit.

fn project_point_with_max_dist( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, max_dist: f32, ) -> Option<PointProjection>

Projects a point on self transformed by m, unless the projection lies further than the given max distance.

fn contains_local_point(&self, pt: &Point<f32>) -> bool

Tests if the given point is inside of self.

fn project_point( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, ) -> PointProjection

Projects a point on self transformed by m.

fn distance_to_point( &self, m: &Isometry<f32>, pt: &Point<f32>, solid: bool, ) -> f32

Computes the minimal distance between a point and self transformed by m.

fn project_point_and_get_feature( &self, m: &Isometry<f32>, pt: &Point<f32>, ) -> (PointProjection, FeatureId)

Projects a point on the boundary of self transformed by m and returns the id of the feature the point was projected on.

fn contains_point(&self, m: &Isometry<f32>, pt: &Point<f32>) -> bool

Tests if the given point is inside of self transformed by m.

impl RayCast for Aabb

fn cast_local_ray( &self, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<f32>

Computes the time of impact between this transform shape and a ray.

fn cast_local_ray_and_get_normal( &self, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<RayIntersection>

Computes the time of impact, and normal between this transformed shape and a ray.

fn intersects_local_ray(&self, ray: &Ray, max_time_of_impact: f32) -> bool

Tests whether a ray intersects this transformed shape.

fn cast_ray( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<f32>

Computes the time of impact between this transform shape and a ray.

fn cast_ray_and_get_normal( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<RayIntersection>

Computes the time of impact, and normal between this transformed shape and a ray.

fn intersects_ray( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, ) -> bool

Tests whether a ray intersects this transformed shape.

impl Copy for Aabb

impl StructuralPartialEq for Aabb