phys_geom/

shape.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.

//! Geometric shape implementations for 3D physics simulations.
//!
//! This module provides a collection of primitive geometric shapes commonly used in physics
//! engines, along with their basic properties and operations. All shapes are designed to be
//! FFI-safe through the `#[repr(C)]` attribute and support optional serialization via the `serde`
//! feature.
//!
//! ## Available Shapes
//!
//! - [`Sphere`] - A perfect sphere defined by its radius
//! - [`Capsule`] - A capsule with cylindrical body and hemispherical caps
//! - [`Cuboid`] - A rectangular box (also known as a box or rectangular prism)
//! - [`Cylinder`] - A cylinder with circular cross-section
//! - [`InfinitePlane`] - An infinite plane (primarily for geometric computations)
//! - [`Tetrahedron`] - A tetrahedron defined by four vertices
//!
//! ## Common Properties
//!
//! All shapes share these characteristics:
//! - **FFI-safe**: All shapes use `#[repr(C)]` for C compatibility
//! - **Serializable**: Support `serde` serialization when the feature is enabled
//! - **Validated**: Construction validates parameters (e.g., positive dimensions)
//! - **Copy-friendly**: All shapes implement `Copy` and `Clone`
//!
//! ## Usage Examples
//!
//! ```rust
//! use phys_geom::shape::{Sphere, Capsule, Cuboid, Cylinder};
//!
//! // Create a sphere
//! let sphere = Sphere::new(1.0);
//! assert_eq!(sphere.radius(), 1.0);
//!
//! // Create a capsule with cylindrical half-height 2.0 and radius 0.5
//! let capsule = Capsule::new(2.0, 0.5);
//! assert_eq!(capsule.height(), 4.0); // cylinder height (excluding caps)
//!
//! // Create a cuboid (box) with dimensions 2x3x1
//! let cuboid = Cuboid::new([2.0, 3.0, 1.0]);
//! assert_eq!(cuboid.length(), [2.0, 3.0, 1.0]);
//!
//! // Create a cylinder
//! let cylinder = Cylinder::new(1.5, 0.8); // half-height=1.5, radius=0.8
//! assert_eq!(cylinder.height(), 3.0);
//! ```

use crate::math::*;

/// A sphere shape centered at the origin.
///
/// The sphere is defined by its radius and is commonly used for simple collision detection
/// and physics calculations. The sphere is centered at the origin (0, 0, 0).
///
/// # Examples
///
/// ```rust
/// use phys_geom::shape::Sphere;
///
/// // Create a sphere with radius 1.0
/// let sphere = Sphere::new(1.0);
/// assert_eq!(sphere.radius(), 1.0);
///
/// // Use the predefined unit sphere
/// let unit_sphere = Sphere::UNIT;
/// assert_eq!(unit_sphere.radius(), 0.5);
/// ```
///
/// # Panics
///
/// - [`Sphere::new()`] panics if the radius is not positive
/// - [`Sphere::set_radius()`] panics if the new radius is not positive
#[repr(C)]
#[derive(Debug, Copy, Clone, Default, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Sphere {
    radius: Real,
}

impl Sphere {
    /// A unit sphere with radius 0.5.
    ///
    /// This is useful as a reference size for normalized shapes.
    pub const UNIT: Sphere = Sphere { radius: 0.5 };

    /// Creates a new sphere with the given radius.
    ///
    /// # Arguments
    ///
    /// * `radius` - The radius of the sphere (must be positive)
    ///
    /// # Returns
    ///
    /// A new `Sphere` instance with the specified radius.
    ///
    /// # Panics
    ///
    /// Panics if `radius` is not positive.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Sphere;
    ///
    /// let sphere = Sphere::new(2.5);
    /// assert_eq!(sphere.radius(), 2.5);
    /// ```
    #[inline]
    #[must_use]
    pub fn new(radius: Real) -> Sphere {
        assert!(radius > 0.0);
        Sphere { radius }
    }

    /// Returns the radius of the sphere.
    ///
    /// # Returns
    ///
    /// The radius as a `Real` (f32 or f64 depending on features).
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Sphere;
    ///
    /// let sphere = Sphere::new(3.0);
    /// assert_eq!(sphere.radius(), 3.0);
    /// ```
    #[inline]
    pub const fn radius(&self) -> Real {
        self.radius
    }

    /// Sets the radius of the sphere.
    ///
    /// # Arguments
    ///
    /// * `value` - The new radius (must be positive)
    ///
    /// # Panics
    ///
    /// Panics if `value` is not positive.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Sphere;
    ///
    /// let mut sphere = Sphere::new(1.0);
    /// sphere.set_radius(2.0);
    /// assert_eq!(sphere.radius(), 2.0);
    /// ```
    #[inline]
    pub fn set_radius(&mut self, value: Real) {
        *self = Self::new(value);
    }
}

/// A capsule shape centered at the origin, aligned along the Y-axis.
///
/// A capsule consists of a cylinder with hemispherical caps at both ends.
/// It's commonly used in physics engines for character controllers because
/// it provides good collision detection while being easy to rotate.
///
/// The capsule is centered at the origin (0, 0, 0) and extends along the Y-axis.
///
/// # Examples
///
/// ```rust
/// use phys_geom::shape::Capsule;
///
/// // Create a capsule with half-height 2.0 and radius 0.5
/// let capsule = Capsule::new(2.0, 0.5);
/// assert_eq!(capsule.half_height(), 2.0);
/// assert_eq!(capsule.radius(), 0.5);
/// assert_eq!(capsule.height(), 4.0); // total height
/// ```
///
/// # Dimensions
///
/// - `half_height`: Height of the cylindrical portion (excluding caps)
/// - `radius`: Radius of both the cylinder and the hemispherical caps
/// - Total height = `2 * half_height + 2 * radius`
#[repr(C)]
#[derive(Debug, Copy, Clone, Default, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Capsule {
    half_height: Real,
    radius: Real,
}

impl Capsule {
    /// Creates a new capsule with the given dimensions.
    ///
    /// # Arguments
    ///
    /// * `half_height` - Half the height of the cylindrical portion (must be non-negative)
    /// * `radius` - The radius of the capsule (must be positive)
    ///
    /// # Returns
    ///
    /// A new `Capsule` instance.
    ///
    /// # Panics
    ///
    /// Panics if:
    /// - `half_height` is negative
    /// - `radius` is not positive
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Capsule;
    ///
    /// // Create a capsule with cylindrical portion 3 units tall and 0.5 unit radius
    /// let capsule = Capsule::new(1.5, 0.5);
    /// assert_eq!(capsule.height(), 3.0);
    /// ```
    #[must_use]
    pub fn new(half_height: Real, radius: Real) -> Self {
        assert!(half_height >= 0.0);
        assert!(radius > 0.0);
        Self {
            half_height,
            radius,
        }
    }

    /// Returns the height of the cylindrical portion of the capsule.
    ///
    /// This is the height of just the cylindrical part, excluding the hemispherical caps.
    /// Height = 2 * half_height
    ///
    /// # Returns
    ///
    /// The height of the cylindrical portion as a `Real`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Capsule;
    ///
    /// let capsule = Capsule::new(2.0, 0.5);
    /// assert_eq!(capsule.height(), 4.0); // cylinder height = 2 * half_height
    /// ```
    #[inline]
    pub fn height(&self) -> Real {
        self.half_height + self.half_height
    }

    /// Returns the half height of the cylindrical portion.
    ///
    /// This is the height of the cylindrical part excluding the hemispherical caps.
    ///
    /// # Returns
    ///
    /// The half height as a `Real`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Capsule;
    ///
    /// let capsule = Capsule::new(2.0, 0.5);
    /// assert_eq!(capsule.half_height(), 2.0);
    /// ```
    #[inline]
    pub fn half_height(&self) -> Real {
        self.half_height
    }

    /// Returns the radius of the capsule.
    ///
    /// This is the radius of both the cylindrical body and the hemispherical caps.
    ///
    /// # Returns
    ///
    /// The radius as a `Real`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Capsule;
    ///
    /// let capsule = Capsule::new(2.0, 0.5);
    /// assert_eq!(capsule.radius(), 0.5);
    /// ```
    #[inline]
    pub fn radius(&self) -> Real {
        self.radius
    }
}

/// A cuboid (rectangular box) shape centered at the origin.
///
/// A cuboid is a three-dimensional rectangular box with six rectangular faces.
/// It's one of the most commonly used shapes in physics engines for representing
/// boxes, containers, and general rectangular objects.
///
/// The cuboid is centered at the origin (0, 0, 0) with its edges aligned to the coordinate axes.
///
/// # Examples
///
/// ```rust
/// use phys_geom::shape::Cuboid;
///
/// // Create a cuboid with dimensions 2x3x1
/// let cuboid = Cuboid::new([2.0, 3.0, 1.0]);
/// assert_eq!(cuboid.length(), [2.0, 3.0, 1.0]);
/// assert_eq!(cuboid.half_length(), [1.0, 1.5, 0.5]);
///
/// // Create a unit cube
/// let unit_cube = Cuboid::UNIT;
/// assert_eq!(unit_cube.length(), [1.0, 1.0, 1.0]);
/// ```
///
/// # Dimensions
///
/// - `half_length`: Half-lengths along each axis (x, y, z)
/// - Total dimensions: `[x, y, z] = [2 * half_length[0], 2 * half_length[1], 2 * half_length[2]]`
///
/// # Construction
///
/// The cuboid can be constructed from:
/// - An array of three lengths: `Cuboid::new([x, y, z])`
/// - Individual components: `Cuboid::new_xyz(x, y, z)`
#[repr(C)]
#[derive(Debug, Copy, Clone, Default, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Cuboid {
    half_length: [Real; 3],
}

impl Cuboid {
    /// A unit cube with side length 1.0.
    ///
    /// This is useful as a reference size for normalized shapes.
    /// The cube extends from -0.5 to +0.5 along each axis.
    pub const UNIT: Cuboid = Cuboid {
        half_length: [0.5, 0.5, 0.5],
    };

    /// Creates a new cuboid with the given dimensions.
    ///
    /// # Arguments
    ///
    /// * `length` - The dimensions of the cuboid as a 3-element array [x, y, z]
    ///
    /// # Returns
    ///
    /// A new `Cuboid` instance.
    ///
    /// # Panics
    ///
    /// Panics if any component of length is not positive.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Cuboid;
    ///
    /// // Create from array
    /// let cuboid1 = Cuboid::new([2.0, 3.0, 1.0]);
    ///
    /// // Create from tuple (via Into trait)
    /// let cuboid2 = Cuboid::new((2.0, 3.0, 1.0));
    ///
    /// assert_eq!(cuboid1.length(), cuboid2.length());
    /// ```
    #[inline]
    #[must_use]
    pub fn new(length: impl Into<[Real; 3]>) -> Cuboid {
        let length = length.into();
        assert!(length[0] > 0.0);
        assert!(length[1] > 0.0);
        assert!(length[2] > 0.0);

        const HALF: Real = 0.5;
        Cuboid {
            half_length: [length[0] * HALF, length[1] * HALF, length[2] * HALF],
        }
    }

    /// Creates a new cuboid with individual x, y, z dimensions.
    ///
    /// This is a convenience method equivalent to `Cuboid::new([x, y, z])`.
    ///
    /// # Arguments
    ///
    /// * `x` - Length along the X-axis
    /// * `y` - Length along the Y-axis
    /// * `z` - Length along the Z-axis
    ///
    /// # Returns
    ///
    /// A new `Cuboid` instance.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Cuboid;
    ///
    /// let cuboid = Cuboid::new_xyz(2.0, 3.0, 1.0);
    /// assert_eq!(cuboid.length(), [2.0, 3.0, 1.0]);
    /// ```
    #[inline]
    pub fn new_xyz(x: Real, y: Real, z: Real) -> Cuboid {
        Self::new([x, y, z])
    }

    /// Returns the full dimensions of the cuboid.
    ///
    /// Returns an array [x, y, z] representing the total length along each axis.
    ///
    /// # Returns
    ///
    /// An array of three `Real` values [x, y, z].
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Cuboid;
    ///
    /// let cuboid = Cuboid::new([2.0, 3.0, 1.0]);
    /// assert_eq!(cuboid.length(), [2.0, 3.0, 1.0]);
    /// ```
    #[inline]
    pub fn length(&self) -> [Real; 3] {
        const DOUBLE: Real = 2.0;
        [
            self.half_length[0] * DOUBLE,
            self.half_length[1] * DOUBLE,
            self.half_length[2] * DOUBLE,
        ]
    }

    /// Returns the half-lengths of the cuboid.
    ///
    /// Returns an array [x/2, y/2, z/2] representing the distance from the center
    /// to each face along the respective axes.
    ///
    /// # Returns
    ///
    /// An array of three `Real` values [x/2, y/2, z/2].
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Cuboid;
    ///
    /// let cuboid = Cuboid::new([2.0, 3.0, 1.0]);
    /// assert_eq!(cuboid.half_length(), [1.0, 1.5, 0.5]);
    /// ```
    #[inline]
    pub fn half_length(&self) -> [Real; 3] {
        self.half_length
    }

    /// Sets the dimensions of the cuboid.
    ///
    /// # Arguments
    ///
    /// * `length` - The new dimensions as a 3-element array [x, y, z]
    ///
    /// # Panics
    ///
    /// Panics if any component of length is not positive.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Cuboid;
    ///
    /// let mut cuboid = Cuboid::new([1.0, 1.0, 1.0]);
    /// cuboid.set_length([2.0, 3.0, 1.0]);
    /// assert_eq!(cuboid.length(), [2.0, 3.0, 1.0]);
    /// ```
    #[inline]
    pub fn set_length(&mut self, length: impl Into<[Real; 3]>) {
        *self = Self::new(length);
    }
}

/// A cylinder shape centered at the origin, aligned along the Y-axis.
///
/// A cylinder is a three-dimensional shape with a circular cross-section.
/// It's commonly used in physics engines for representing pillars, pipes,
/// wheels, and other cylindrical objects.
///
/// The cylinder is centered at the origin (0, 0, 0) with its axis
/// aligned to the Y-axis. It extends from -half_height to +half_height
/// along the Y-axis.
///
/// # Examples
///
/// ```rust
/// use phys_geom::shape::Cylinder;
///
/// // Create a cylinder with height 3.0 and radius 0.8
/// let cylinder = Cylinder::new(1.5, 0.8);
/// assert_eq!(cylinder.height(), 3.0);
/// assert_eq!(cylinder.radius(), 0.8);
/// ```
///
/// # Dimensions
///
/// - `half_height`: Half the height of the cylinder
/// - `radius`: Radius of the circular cross-section
/// - Total height = `2 * half_height`
#[repr(C)]
#[derive(Debug, Clone, Default, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Cylinder {
    half_height: Real,
    radius: Real,
}

impl Cylinder {
    /// Creates a new cylinder with the given dimensions.
    ///
    /// # Arguments
    ///
    /// * `half_height` - Half the height of the cylinder (must be positive)
    /// * `radius` - The radius of the cylinder (must be positive)
    ///
    /// # Returns
    ///
    /// A new `Cylinder` instance.
    ///
    /// # Panics
    ///
    /// Panics if `half_height` or `radius` is not positive.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Cylinder;
    ///
    /// // Create a cylinder with total height 4.0 and radius 1.0
    /// let cylinder = Cylinder::new(2.0, 1.0);
    /// assert_eq!(cylinder.height(), 4.0);
    /// assert_eq!(cylinder.radius(), 1.0);
    /// ```
    #[inline]
    #[must_use]
    pub fn new(half_height: Real, radius: Real) -> Self {
        assert!(radius > 0.0);
        assert!(half_height > 0.0);
        Self {
            half_height,
            radius,
        }
    }

    /// Returns the total height of the cylinder.
    ///
    /// # Returns
    ///
    /// The total height as a `Real`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Cylinder;
    ///
    /// let cylinder = Cylinder::new(1.5, 0.8);
    /// assert_eq!(cylinder.height(), 3.0);
    /// ```
    #[inline]
    pub fn height(&self) -> Real {
        self.half_height * 2.0
    }

    /// Returns the half height of the cylinder.
    ///
    /// This is the distance from the center to either end of the cylinder.
    ///
    /// # Returns
    ///
    /// The half height as a `Real`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Cylinder;
    ///
    /// let cylinder = Cylinder::new(1.5, 0.8);
    /// assert_eq!(cylinder.half_height(), 1.5);
    /// ```
    #[inline]
    pub fn half_height(&self) -> Real {
        self.half_height
    }

    /// Returns the radius of the cylinder.
    ///
    /// # Returns
    ///
    /// The radius as a `Real`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Cylinder;
    ///
    /// let cylinder = Cylinder::new(1.5, 0.8);
    /// assert_eq!(cylinder.radius(), 0.8);
    /// ```
    #[inline]
    pub fn radius(&self) -> Real {
        self.radius
    }
}

/// An infinite plane in 3D space.
///
/// An infinite plane represents a flat surface that extends infinitely in all directions.
/// This is primarily used for geometric computations and as a conceptual shape in
/// physics simulations (e.g., ground planes, collision surfaces).
///
/// Note: This is a marker struct for type system purposes. The actual plane definition
/// would typically be handled separately with a normal vector and distance from origin.
///
/// # FFI Safety
///
/// The struct includes padding to ensure FFI safety, as empty structs are not
/// FFI-safe in Rust (see [Rust issue #17679]).
///
/// # Examples
///
/// ```rust
/// use phys_geom::shape::InfinitePlane;
///
/// // Create an infinite plane
/// let plane = InfinitePlane::default();
/// ```
#[repr(C)]
#[derive(Default, Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct InfinitePlane {
    // empty struct is not FFI-safe, https://github.com/rust-lang/rust/issues/17679
    _padding: i32,
}

/// A triangle defined by three vertices in 3D space.
///
/// A triangle is the simplest polygon in 3D space, consisting of three vertices
/// connected by three edges. It's a fundamental building block in computer graphics,
/// computational geometry, and physics simulations.
///
/// The triangle is defined by three vertices A, B, and C. The orientation and
/// properties are computed based on the relative positions of these vertices.
///
/// # Examples
///
/// ```rust
/// use phys_geom::shape::Triangle;
/// use phys_geom::math::Point3;
///
/// // Create a triangle
/// let triangle = Triangle::new(
///     Point3::new(0.0, 0.0, 0.0),
///     Point3::new(1.0, 0.0, 0.0),
///     Point3::new(0.0, 1.0, 0.0),
/// );
/// ```
///
/// # Mathematical Properties
///
/// - Area = 0.5 * |(B-A) × (C-A)|
/// - Normal = normalize((B-A) × (C-A))
/// - Center = (A + B + C) / 3
#[repr(C)]
#[derive(Debug, Clone, Copy, Default, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Triangle {
    /// First vertex of the triangle
    pub a: Point3,
    /// Second vertex of the triangle
    pub b: Point3,
    /// Third vertex of the triangle
    pub c: Point3,
}

impl Triangle {
    /// Creates a new triangle from three vertices.
    ///
    /// # Arguments
    ///
    /// * `a` - First vertex
    /// * `b` - Second vertex
    /// * `c` - Third vertex
    ///
    /// # Returns
    ///
    /// A new `Triangle` instance.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Triangle;
    /// use phys_geom::math::Point3;
    ///
    /// let triangle = Triangle::new(
    ///     Point3::new(0.0, 0.0, 0.0),
    ///     Point3::new(1.0, 0.0, 0.0),
    ///     Point3::new(0.0, 1.0, 0.0),
    /// );
    /// ```
    #[inline]
    #[must_use]
    pub fn new(a: impl Into<[Real; 3]>, b: impl Into<[Real; 3]>, c: impl Into<[Real; 3]>) -> Self {
        Self {
            a: Point3::from(a.into()),
            b: Point3::from(b.into()),
            c: Point3::from(c.into()),
        }
    }

    /// Computes the geometric center (centroid) of the triangle.
    ///
    /// The centroid is calculated as the average of all three vertices:
    /// C = (A + B + C) / 3
    ///
    /// # Returns
    ///
    /// The centroid coordinates as a `Point3`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Triangle;
    /// use phys_geom::math::Point3;
    ///
    /// let triangle = Triangle::new(
    ///     Point3::new(0.0, 0.0, 0.0),
    ///     Point3::new(2.0, 0.0, 0.0),
    ///     Point3::new(0.0, 2.0, 0.0),
    /// );
    ///
    /// let center = triangle.center();
    /// assert_eq!(center, Point3::new(2.0/3.0, 2.0/3.0, 0.0));
    /// ```
    #[inline]
    pub fn center(&self) -> Point3 {
        let a: Vec3 = self.a.coords;
        let b: Vec3 = self.b.coords;
        let c: Vec3 = self.c.coords;
        Point3::from((a + b + c) / 3.0)
    }

    /// Computes the normal vector of the triangle.
    ///
    /// The normal is calculated using the cross product of two edges:
    /// N = normalize((B-A) × (C-A))
    ///
    /// The direction follows the right-hand rule based on the vertex order (A, B, C).
    ///
    /// # Returns
    ///
    /// The unit normal vector as a `UnitVec3`.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Triangle;
    /// use phys_geom::math::{Point3, UnitVec3};
    ///
    /// let triangle = Triangle::new(
    ///     Point3::new(0.0, 0.0, 0.0),
    ///     Point3::new(1.0, 0.0, 0.0),
    ///     Point3::new(0.0, 1.0, 0.0),
    /// );
    ///
    /// let normal = triangle.normal();
    /// // Triangle lies in the XY plane, normal points in +Z direction
    /// assert!(normal.z > 0.9); // Close to 1.0 for unit vector
    /// ```
    #[inline]
    pub fn normal(&self) -> UnitVec3 {
        let edge1 = self.b - self.a;
        let edge2 = self.c - self.a;
        UnitVec3::new_normalize(edge1.cross(&edge2))
    }

    /// Computes the area of the triangle.
    ///
    /// The area is calculated using half the magnitude of the cross product:
    /// Area = 0.5 * |(B-A) × (C-A)|
    ///
    /// # Returns
    ///
    /// The area as a `Real` value.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Triangle;
    /// use phys_geom::math::Point3;
    ///
    /// let triangle = Triangle::new(
    ///     Point3::new(0.0, 0.0, 0.0),
    ///     Point3::new(2.0, 0.0, 0.0),
    ///     Point3::new(0.0, 2.0, 0.0),
    /// );
    ///
    /// let area = triangle.area();
    /// assert_eq!(area, 2.0); // Right triangle with legs of length 2
    /// ```
    #[inline]
    pub fn area(&self) -> Real {
        let edge1 = self.b - self.a;
        let edge2 = self.c - self.a;
        edge1.cross(&edge2).magnitude() / 2.0
    }

    /// Checks if the triangle is degenerate (has zero area).
    ///
    /// A triangle is degenerate if all three vertices are collinear, which means
    /// the cross product of two edges has zero (or near-zero) magnitude.
    ///
    /// # Returns
    ///
    /// `true` if the triangle is degenerate, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Triangle;
    /// use phys_geom::math::Point3;
    ///
    /// // Non-degenerate triangle
    /// let triangle1 = Triangle::new(
    ///     Point3::new(0.0, 0.0, 0.0),
    ///     Point3::new(1.0, 0.0, 0.0),
    ///     Point3::new(0.0, 1.0, 0.0),
    /// );
    /// assert!(!triangle1.is_degenerate());
    ///
    /// // Degenerate triangle (all points on a line)
    /// let triangle2 = Triangle::new(
    ///     Point3::new(0.0, 0.0, 0.0),
    ///     Point3::new(1.0, 0.0, 0.0),
    ///     Point3::new(2.0, 0.0, 0.0),
    /// );
    /// assert!(triangle2.is_degenerate());
    /// ```
    #[inline]
    pub fn is_degenerate(&self) -> bool {
        self.area() <= Real::EPSILON
    }
}

use crate::{Aabb3, ComputeAabb3};

impl ComputeAabb3 for Triangle {
    #[inline]
    fn compute_aabb(&self) -> Aabb3 {
        let p1 = self.a.coords.inf(&self.b.coords).inf(&self.c.coords);
        let p2 = self.a.coords.sup(&self.b.coords).sup(&self.c.coords);
        Aabb3::new(Point3::from(p1), Point3::from(p2))
    }
}

/// A tetrahedron defined by four vertices in 3D space.
///
/// A tetrahedron is a polyhedron with four triangular faces, six edges, and four vertices.
/// It's the simplest type of polyhedron and is commonly used in computational geometry,
/// finite element analysis, and physics simulations.
///
/// The tetrahedron is defined by four vertices A, B, C, and D. The volume and other
/// properties are computed based on the relative positions of these vertices.
///
/// # Examples
///
/// ```rust
/// use phys_geom::shape::Tetrahedron;
///
/// // Create a regular tetrahedron
/// let tetrahedron = Tetrahedron {
///     a: [1.0, 1.0, 1.0],
///     b: [1.0, -1.0, -1.0],
///     c: [-1.0, 1.0, -1.0],
///     d: [-1.0, -1.0, 1.0],
/// };
///
/// // Compute its signed volume
/// let volume = tetrahedron.signed_volume();
/// let center = tetrahedron.center();
/// ```
///
/// # Volume Sign Convention
///
/// The signed volume follows the right-hand rule:
/// - Positive volume: Vertex D is on the side pointed by the normal of triangle ABC
/// - Negative volume: Vertex D is on the opposite side
/// - Zero volume: All vertices are coplanar
///
/// # Mathematical Properties
///
/// - Volume = (1/6) * |(B-A) · ((C-A) × (D-A))|
/// - Center = (A + B + C + D) / 4
pub struct Tetrahedron {
    /// First vertex of the tetrahedron
    pub a: [Real; 3],
    /// Second vertex of the tetrahedron
    pub b: [Real; 3],
    /// Third vertex of the tetrahedron
    pub c: [Real; 3],
    /// Fourth vertex of the tetrahedron
    pub d: [Real; 3],
}

impl Tetrahedron {
    /// Computes the signed volume of this tetrahedron.
    ///
    /// The signed volume is calculated using the scalar triple product:
    /// V = (1/6) * ((B-A) · ((C-A) × (D-A)))
    ///
    /// # Returns
    ///
    /// The signed volume as a `Real` value.
    ///
    /// # Volume Sign Convention
    ///
    /// - **Positive**: Vertex D is on the half-space pointed by the normal of the oriented triangle
    ///   (A, B, C)
    /// - **Negative**: Vertex D is on the opposite side
    /// - **Zero**: All four vertices are coplanar
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Tetrahedron;
    ///
    /// let tetrahedron = Tetrahedron {
    ///     a: [0.0, 0.0, 0.0],
    ///     b: [1.0, 0.0, 0.0],
    ///     c: [0.0, 1.0, 0.0],
    ///     d: [0.0, 0.0, 1.0],
    /// };
    ///
    /// let volume = tetrahedron.signed_volume();
    /// assert!(volume > 0.0);
    /// ```
    #[inline]
    pub fn signed_volume(&self) -> Real {
        let a: Vec3 = self.a.into();
        let b: Vec3 = self.b.into();
        let c: Vec3 = self.c.into();
        let d: Vec3 = self.d.into();
        let v1 = b - a;
        let v2 = c - a;
        let v3 = d - a;
        v1.dot(&v2.cross(&v3)) / 6.0
    }

    /// Computes the centroid (geometric center) of the tetrahedron.
    ///
    /// The centroid is calculated as the average of all four vertices:
    /// C = (A + B + C + D) / 4
    ///
    /// # Returns
    ///
    /// The centroid coordinates as a 3-element array [x, y, z].
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::shape::Tetrahedron;
    ///
    /// let tetrahedron = Tetrahedron {
    ///     a: [0.0, 0.0, 0.0],
    ///     b: [2.0, 0.0, 0.0],
    ///     c: [0.0, 2.0, 0.0],
    ///     d: [0.0, 0.0, 2.0],
    /// };
    ///
    /// let center = tetrahedron.center();
    /// assert_eq!(center, [0.5, 0.5, 0.5]);
    /// ```
    #[inline]
    pub fn center(&self) -> [Real; 3] {
        let a: Vec3 = self.a.into();
        let b: Vec3 = self.b.into();
        let c: Vec3 = self.c.into();
        let d: Vec3 = self.d.into();
        let center = (a + b + c + d) / 4.0;
        center.into()
    }
}

#[cfg(test)]
mod tests {

    use super::*;
    use crate::ComputeAabb3;

    #[test]
    fn test_sphere() {
        let mut sphere = Sphere::new(1.0);
        assert_eq!(sphere.radius(), 1.0);

        sphere.set_radius(2.0);
        assert_eq!(sphere.radius(), 2.0);
    }

    #[test]
    fn test_capsule() {
        let capsule = Capsule::new(1.0, 1.0);
        assert_eq!(capsule.half_height(), 1.0);
        assert_eq!(capsule.radius(), 1.0);
    }

    #[test]
    fn test_cuboid() {
        let cuboid = Cuboid::new([1.0, 1.0, 1.0]);
        assert_eq!(cuboid.length(), [1.0, 1.0, 1.0]);
        assert_eq!(cuboid.half_length(), [0.5, 0.5, 0.5]);
    }

    #[test]
    fn test_cylinder() {
        let cylinder = Cylinder::new(1.0, 1.0);
        assert_eq!(cylinder.height(), 2.0);
        assert_eq!(cylinder.half_height(), 1.0);
        assert_eq!(cylinder.radius(), 1.0);
    }

    #[test]
    fn test_triangle() {
        let triangle = Triangle::new([0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]);

        assert_eq!(triangle.a, Point3::new(0.0, 0.0, 0.0));
        assert_eq!(triangle.b, Point3::new(1.0, 0.0, 0.0));
        assert_eq!(triangle.c, Point3::new(0.0, 1.0, 0.0));
    }

    #[test]
    fn test_triangle_center() {
        let triangle = Triangle::new(
            Point3::new(0.0, 0.0, 0.0),
            Point3::new(2.0, 0.0, 0.0),
            Point3::new(0.0, 2.0, 0.0),
        );

        let center = triangle.center();
        assert_eq!(center, Point3::new(2.0 / 3.0, 2.0 / 3.0, 0.0));
    }

    #[test]
    fn test_triangle_normal() {
        let triangle = Triangle::new(
            Point3::new(0.0, 0.0, 0.0),
            Point3::new(1.0, 0.0, 0.0),
            Point3::new(0.0, 1.0, 0.0),
        );

        let normal = triangle.normal();
        // Triangle lies in the XY plane, normal should point in +Z direction
        assert!(normal.z > 0.9);
        assert!(normal.x.abs() < 0.1);
        assert!(normal.y.abs() < 0.1);
    }

    #[test]
    fn test_triangle_area() {
        let triangle = Triangle::new(
            Point3::new(0.0, 0.0, 0.0),
            Point3::new(2.0, 0.0, 0.0),
            Point3::new(0.0, 2.0, 0.0),
        );

        let area = triangle.area();
        assert_eq!(area, 2.0); // Right triangle with legs of length 2
    }

    #[test]
    fn test_triangle_degenerate() {
        // Non-degenerate triangle
        let triangle1 = Triangle::new(
            Point3::new(0.0, 0.0, 0.0),
            Point3::new(1.0, 0.0, 0.0),
            Point3::new(0.0, 1.0, 0.0),
        );
        assert!(!triangle1.is_degenerate());

        // Degenerate triangle (all points on a line)
        let triangle2 = Triangle::new(
            Point3::new(0.0, 0.0, 0.0),
            Point3::new(1.0, 0.0, 0.0),
            Point3::new(2.0, 0.0, 0.0),
        );
        assert!(triangle2.is_degenerate());
    }

    #[test]
    fn test_triangle_equality() {
        let triangle1 = Triangle::new(
            Point3::new(0.0, 0.0, 0.0),
            Point3::new(1.0, 0.0, 0.0),
            Point3::new(0.0, 1.0, 0.0),
        );

        let triangle2 = Triangle::new(
            Point3::new(0.0, 0.0, 0.0),
            Point3::new(1.0, 0.0, 0.0),
            Point3::new(0.0, 1.0, 0.0),
        );

        let triangle3 = Triangle::new(
            Point3::new(0.0, 0.0, 0.0),
            Point3::new(1.0, 0.0, 0.0),
            Point3::new(0.0, 2.0, 0.0),
        );

        assert_eq!(triangle1, triangle2);
        assert_ne!(triangle1, triangle3);
    }

    #[test]
    fn test_triangle_aabb() {
        let triangle = Triangle::new(
            Point3::new(0.0, 0.0, 0.0),
            Point3::new(1.0, 2.0, 1.0),
            Point3::new(0.0, 1.0, 0.0),
        );

        let aabb = triangle.compute_aabb();
        assert_eq!(aabb.min(), Point3::new(0.0, 0.0, 0.0));
        assert_eq!(aabb.max(), Point3::new(1.0, 2.0, 1.0));
    }
}