phys_geom/

aabb2.rs

// Copyright (C) 2020-2025 phys-geom authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use std::ops::{Add, AddAssign, Sub, SubAssign};

use crate::math::{Point2, Real, Vec2};

/// 2D Axis-Aligned Bounding Box (AABB) implementation.
///
/// This module provides functionality for working with axis-aligned bounding boxes in 2D space.
/// AABBs are fundamental for spatial partitioning, collision detection, and various geometric
/// algorithms. The implementation supports both f32 and f64 precision through feature flags.
///
/// # Examples
///
/// ```
/// use phys_geom::{Aabb2, math::Point2};
///
/// // Create an AABB from two points
/// let aabb = Aabb2::new(Point2::new(0.0, 0.0), Point2::new(10.0, 5.0));
///
/// // Get the center and size
/// let center = aabb.center();
/// let size = aabb.size();
///
/// // Check if two AABBs overlap
/// let other = Aabb2::new(Point2::new(5.0, 2.0), Point2::new(15.0, 8.0));
/// let overlaps = aabb.overlap_test(&other);
/// ```
/// 2D Axis-Aligned Bounding Box.
///
/// An AABB represents a rectangular region in 2D space defined by its minimum and maximum
/// coordinates. The box is axis-aligned, meaning its edges are parallel to the coordinate axes.
///
/// # Representation
///
/// The AABB is stored using two `Point2` values:
/// - `min`: The bottom-left corner of the box
/// - `max`: The top-right corner of the box
///
/// # Invariants
///
/// For a valid AABB, `min.x <= max.x` and `min.y <= max.y` must hold true.
/// The `new_unchecked` method enforces this with debug assertions.
#[derive(Copy, Clone, Default, Debug)]
#[repr(C)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Aabb2 {
    min: Point2,
    max: Point2,
}

impl Aabb2 {
    /// Zero-sized AABB located at the origin.
    ///
    /// Both min and max points are at (0, 0), representing a degenerate box with zero area.
    pub const ZERO: Aabb2 = Self {
        min: Point2::new(0.0, 0.0),
        max: Point2::new(0.0, 0.0),
    };

    /// Creates a new AABB from two points.
    ///
    /// The AABB will be the smallest axis-aligned rectangle that contains both points.
    /// This method automatically determines which point should be the min and max corners.
    ///
    /// # Arguments
    ///
    /// * `p1` - First point
    /// * `p2` - Second point
    ///
    /// # Returns
    ///
    /// A new AABB that contains both input points.
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::Point2};
    ///
    /// let p1 = Point2::new(5.0, 10.0);
    /// let p2 = Point2::new(1.0, 3.0);
    /// let aabb = Aabb2::new(p1, p2);
    ///
    /// assert_eq!(aabb.min(), Point2::new(1.0, 3.0));
    /// assert_eq!(aabb.max(), Point2::new(5.0, 10.0));
    /// ```
    #[inline]
    #[must_use]
    pub fn new(p1: Point2, p2: Point2) -> Aabb2 {
        Aabb2 {
            min: Point2::new(Real::min(p1.x, p2.x), Real::min(p1.y, p2.y)),
            max: Point2::new(Real::max(p1.x, p2.x), Real::max(p1.y, p2.y)),
        }
    }

    /// Creates a new AABB from explicit min and max points.
    ///
    /// Unlike the `new` method, this function assumes the caller has already determined
    /// which point is the minimum and which is the maximum. This is more efficient when
    /// you already know the min/max relationship.
    ///
    /// # Safety
    ///
    /// The caller must ensure that `min.x <= max.x` and `min.y <= max.y`.
    /// Debug assertions will catch violations in debug builds.
    ///
    /// # Arguments
    ///
    /// * `min` - The minimum corner (bottom-left) of the AABB
    /// * `max` - The maximum corner (top-right) of the AABB
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::Point2};
    ///
    /// let min = Point2::new(0.0, 0.0);
    /// let max = Point2::new(10.0, 5.0);
    /// let aabb = Aabb2::new_unchecked(min, max);
    /// ```
    #[inline]
    #[must_use]
    pub fn new_unchecked(min: Point2, max: Point2) -> Self {
        debug_assert!(min.x <= max.x, "min > max, min = {min},max = {max}");
        debug_assert!(min.y <= max.y, "min > max, min = {min},max = {max}");
        Self { min, max }
    }

    /// Creates an AABB from an array of 4 floating-point values.
    ///
    /// The array elements should be in the order: [min_x, min_y, max_x, max_y].
    /// This method is useful for interoperability with other systems that
    /// represent AABBs as flat arrays.
    ///
    /// # Arguments
    ///
    /// * `values` - Array of 4 values: [min_x, min_y, max_x, max_y]
    ///
    /// # Returns
    ///
    /// A new AABB created from the array values.
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::Point2};
    ///
    /// let values = [0.0, 0.0, 10.0, 5.0];
    /// let aabb = Aabb2::from_array_unchecked(values);
    ///
    /// assert_eq!(aabb.min(), Point2::new(0.0, 0.0));
    /// assert_eq!(aabb.max(), Point2::new(10.0, 5.0));
    /// ```
    #[inline]
    #[must_use]
    pub fn from_array_unchecked(values: [Real; 4]) -> Self {
        Aabb2 {
            min: Point2::new(values[0], values[1]),
            max: Point2::new(values[2], values[3]),
        }
    }

    /// Returns the minimum corner of the AABB.
    ///
    /// This is the bottom-left corner of the bounding box, containing the smallest
    /// x and y coordinates within the AABB.
    ///
    /// # Returns
    ///
    /// The minimum point of the AABB.
    #[inline]
    #[must_use]
    pub fn min(&self) -> Point2 {
        self.min
    }

    /// Returns the maximum corner of the AABB.
    ///
    /// This is the top-right corner of the bounding box, containing the largest
    /// x and y coordinates within the AABB.
    ///
    /// # Returns
    ///
    /// The maximum point of the AABB.
    #[inline]
    #[must_use]
    pub fn max(&self) -> Point2 {
        self.max
    }

    /// Expands the AABB to include the specified point.
    ///
    /// If the point is already inside the AABB, this method has no effect.
    /// Otherwise, the AABB is expanded to include the point.
    ///
    /// # Arguments
    ///
    /// * `p` - The point to include in the AABB
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::Point2};
    ///
    /// let mut aabb = Aabb2::new(Point2::new(0.0, 0.0), Point2::new(5.0, 5.0));
    /// aabb.grow(Point2::new(10.0, -2.0));
    ///
    /// assert_eq!(aabb.min(), Point2::new(0.0, -2.0));
    /// assert_eq!(aabb.max(), Point2::new(10.0, 5.0));
    /// ```
    #[inline]
    pub fn grow(&mut self, p: Point2) {
        self.min = self.min.inf(&p);
        self.max = self.max.sup(&p);
    }

    /// Returns the four corner points of the AABB.
    ///
    /// The corners are returned in counter-clockwise order starting from the minimum corner:
    /// 1. Bottom-left (min.x, min.y)
    /// 2. Top-left (min.x, max.y)
    /// 3. Top-right (max.x, max.y)
    /// 4. Bottom-right (max.x, min.y)
    ///
    /// # Returns
    ///
    /// Array of 4 points representing the corners of the AABB.
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::Point2};
    ///
    /// let aabb = Aabb2::new(Point2::new(0.0, 0.0), Point2::new(10.0, 5.0));
    /// let corners = aabb.corners();
    ///
    /// assert_eq!(corners[0], Point2::new(0.0, 0.0));  // bottom-left
    /// assert_eq!(corners[1], Point2::new(0.0, 5.0));  // top-left
    /// assert_eq!(corners[2], Point2::new(10.0, 5.0)); // top-right
    /// assert_eq!(corners[3], Point2::new(10.0, 0.0)); // bottom-right
    /// ```
    #[inline]
    #[must_use]
    pub fn corners(&self) -> [Point2; 4] {
        let min = self.min;
        let max = self.max;
        [
            min,
            Point2::new(min.x, max.y),
            max,
            Point2::new(max.x, min.y),
        ]
    }

    /// Expands the AABB by adding a margin on all sides.
    ///
    /// The margin is added to both sides of the AABB, effectively increasing its
    /// size by 2 * margin in each dimension. This is useful for creating buffer zones
    /// around bounding boxes.
    ///
    /// # Arguments
    ///
    /// * `margin` - The margin to add on all sides (must be non-negative)
    ///
    /// # Returns
    ///
    /// A new AABB expanded by the specified margin.
    ///
    /// # Panics
    ///
    /// In debug builds, this method panics if margin components are negative.
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::{Point2, Vec2}};
    ///
    /// let aabb = Aabb2::new(Point2::new(0.0, 0.0), Point2::new(10.0, 5.0));
    /// let expanded = aabb.with_margin(Vec2::new(1.0, 0.5));
    ///
    /// assert_eq!(expanded.min(), Point2::new(-1.0, -0.5));
    /// assert_eq!(expanded.max(), Point2::new(11.0, 5.5));
    /// ```
    #[inline]
    #[must_use]
    pub fn with_margin(&self, margin: Vec2) -> Self {
        debug_assert!(margin.x >= 0.0 && margin.y >= 0.0);
        let min = self.min - margin;
        let max = self.max + margin;
        Self::new_unchecked(min, max)
    }

    /// Returns the center point of the AABB.
    ///
    /// The center is calculated as the midpoint between the min and max corners.
    /// This method automatically adapts to the current floating-point precision (f32 or f64).
    ///
    /// # Returns
    ///
    /// The center point of the AABB.
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::Point2};
    ///
    /// let aabb = Aabb2::new(Point2::new(0.0, 0.0), Point2::new(10.0, 5.0));
    /// let center = aabb.center();
    ///
    /// assert_eq!(center, Point2::new(5.0, 2.5));
    /// ```
    #[inline]
    #[must_use]
    pub fn center(&self) -> Point2 {
        const HALF: Real = 0.5;
        Point2::from((self.min.coords + self.max.coords) * HALF)
    }

    /// Returns the size (dimensions) of the AABB.
    ///
    /// The size is calculated as max - min, giving the width and height of the AABB.
    /// Note that this method returns zero for degenerate AABBs where min equals max.
    ///
    /// # Returns
    ///
    /// A vector representing the width (x) and height (y) of the AABB.
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::{Point2, Vec2}};
    ///
    /// let aabb = Aabb2::new(Point2::new(0.0, 0.0), Point2::new(10.0, 5.0));
    /// let size = aabb.size();
    ///
    /// assert_eq!(size, Vec2::new(10.0, 5.0));
    /// ```
    #[inline]
    #[must_use]
    pub fn size(&self) -> Vec2 {
        self.max - self.min
    }

    /// Tests if this AABB overlaps with another AABB.
    ///
    /// Two AABBs overlap if they share any common area. This method performs
    /// a separating axis test along both the x and y axes.
    ///
    /// # Arguments
    ///
    /// * `rhs` - The other AABB to test against
    ///
    /// # Returns
    ///
    /// `true` if the AABBs overlap, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::Point2};
    ///
    /// let aabb1 = Aabb2::new(Point2::new(0.0, 0.0), Point2::new(5.0, 5.0));
    /// let aabb2 = Aabb2::new(Point2::new(3.0, 3.0), Point2::new(8.0, 8.0));
    /// let aabb3 = Aabb2::new(Point2::new(10.0, 10.0), Point2::new(15.0, 15.0));
    ///
    /// assert!(aabb1.overlap_test(&aabb2));  // overlapping
    /// assert!(!aabb1.overlap_test(&aabb3)); // not overlapping
    /// ```
    #[inline]
    #[must_use]
    pub fn overlap_test(&self, rhs: &Aabb2) -> bool {
        Self::overlap_test_1d(self.min[0], self.max[0], rhs.min[0], rhs.max[0])
            && Self::overlap_test_1d(self.min[1], self.max[1], rhs.min[1], rhs.max[1])
    }

    /// Tests overlap between two 1D intervals.
    ///
    /// This is a helper method that checks if two intervals [min0, max0] and [min1, max1]
    /// overlap on a single axis. Two intervals overlap if the start of one is less than
    /// the end of the other, and vice versa.
    ///
    /// # Arguments
    ///
    /// * `min0` - Start of first interval
    /// * `max0` - End of first interval
    /// * `min1` - Start of second interval
    /// * `max1` - End of second interval
    ///
    /// # Returns
    ///
    /// `true` if the intervals overlap, `false` otherwise.
    #[inline]
    fn overlap_test_1d(min0: Real, max0: Real, min1: Real, max1: Real) -> bool {
        max0 > min1 && min0 < max1
    }
}

impl Add<Vec2> for Aabb2 {
    type Output = Aabb2;

    /// Translates the AABB by adding a vector.
    ///
    /// This operation moves the entire AABB by the specified vector,
    /// preserving its size and shape.
    ///
    /// # Arguments
    ///
    /// * `rhs` - The translation vector
    ///
    /// # Returns
    ///
    /// A new AABB translated by the vector.
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::{Point2, Vec2}};
    ///
    /// let aabb = Aabb2::new(Point2::new(0.0, 0.0), Point2::new(5.0, 5.0));
    /// let translated = aabb + Vec2::new(10.0, 5.0);
    ///
    /// assert_eq!(translated.min(), Point2::new(10.0, 5.0));
    /// assert_eq!(translated.max(), Point2::new(15.0, 10.0));
    /// ```
    #[inline]
    fn add(self, rhs: Vec2) -> Self::Output {
        let min = self.min + rhs;
        let max = self.max + rhs;
        Aabb2::new_unchecked(min, max)
    }
}

impl Sub<Vec2> for Aabb2 {
    type Output = Aabb2;

    /// Translates the AABB by subtracting a vector.
    ///
    /// This operation moves the entire AABB by the negative of the specified vector,
    /// preserving its size and shape.
    ///
    /// # Arguments
    ///
    /// * `rhs` - The translation vector to subtract
    ///
    /// # Returns
    ///
    /// A new AABB translated by the negative vector.
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::{Point2, Vec2}};
    ///
    /// let aabb = Aabb2::new(Point2::new(10.0, 5.0), Point2::new(15.0, 10.0));
    /// let translated = aabb - Vec2::new(10.0, 5.0);
    ///
    /// assert_eq!(translated.min(), Point2::new(0.0, 0.0));
    /// assert_eq!(translated.max(), Point2::new(5.0, 5.0));
    /// ```
    #[inline]
    fn sub(self, rhs: Vec2) -> Self::Output {
        let min = self.min - rhs;
        let max = self.max - rhs;
        Aabb2::new_unchecked(min, max)
    }
}

impl AddAssign<Vec2> for Aabb2 {
    /// Translates the AABB in-place by adding a vector.
    ///
    /// This operation moves the entire AABB by the specified vector,
    /// modifying the original AABB.
    ///
    /// # Arguments
    ///
    /// * `rhs` - The translation vector
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::{Point2, Vec2}};
    ///
    /// let mut aabb = Aabb2::new(Point2::new(0.0, 0.0), Point2::new(5.0, 5.0));
    /// aabb += Vec2::new(10.0, 5.0);
    ///
    /// assert_eq!(aabb.min(), Point2::new(10.0, 5.0));
    /// assert_eq!(aabb.max(), Point2::new(15.0, 10.0));
    /// ```
    #[inline]
    fn add_assign(&mut self, rhs: Vec2) {
        self.min += rhs;
        self.max += rhs;
    }
}

impl SubAssign<Vec2> for Aabb2 {
    /// Translates the AABB in-place by subtracting a vector.
    ///
    /// This operation moves the entire AABB by the negative of the specified vector,
    /// modifying the original AABB.
    ///
    /// # Arguments
    ///
    /// * `rhs` - The translation vector to subtract
    ///
    /// # Examples
    ///
    /// ```
    /// use phys_geom::{Aabb2, math::{Point2, Vec2}};
    ///
    /// let mut aabb = Aabb2::new(Point2::new(10.0, 5.0), Point2::new(15.0, 10.0));
    /// aabb -= Vec2::new(10.0, 5.0);
    ///
    /// assert_eq!(aabb.min(), Point2::new(0.0, 0.0));
    /// assert_eq!(aabb.max(), Point2::new(5.0, 5.0));
    /// ```
    #[inline]
    fn sub_assign(&mut self, rhs: Vec2) {
        self.min -= rhs;
        self.max -= rhs;
    }
}

#[cfg(test)]
mod tests {
    use approx::assert_relative_eq;

    use super::*;

    #[test]
    fn test_aabb_grow() {
        let mut aabb = Aabb2::new(Point2::new(0.0, 0.0), Point2::new(1.0, 1.0));
        aabb.grow(Point2::new(-1.0, 2.0));
        assert_relative_eq!(aabb.min(), Point2::new(-1.0, 0.0));
        assert_relative_eq!(aabb.max(), Point2::new(1.0, 2.0));
    }

    #[test]
    fn test_aabb_corners() {
        let aabb = Aabb2::new(Point2::new(-1.0, -2.0), Point2::new(1.0, 2.0));
        let corners = aabb.corners();
        assert_relative_eq!(corners[0], Point2::new(-1.0, -2.0));
        assert_relative_eq!(corners[1], Point2::new(-1.0, 2.0));
        assert_relative_eq!(corners[2], Point2::new(1.0, 2.0));
        assert_relative_eq!(corners[3], Point2::new(1.0, -2.0));
    }
}