phys_geom/

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

//! Ray casting utilities for 3D geometry operations.
//!
//! This module provides functionality for working with rays in 3D space, which are
//! fundamental for various geometric operations including:
//! - Ray casting for collision detection
//! - Intersection testing with geometric shapes
//! - Picking operations in graphics applications
//! - Line-of-sight calculations
//!
//! # Overview
//!
//! A ray is defined by an origin point and a direction vector. The ray extends
//! infinitely from the origin in the specified direction.
//!
//! # Usage Examples
//!
//! ```rust
//! use phys_geom::{Ray, math::Point3, math::Vec3};
//!
//! // Create a ray from origin in the positive X direction
//! let origin = Point3::new(0.0, 0.0, 0.0);
//! let direction = Vec3::x_axis();
//! let ray = Ray::new(origin, direction);
//!
//! // Create a ray from a vector direction (automatically normalized)
//! let ray2 = Ray::new_with_vec3(origin, Vec3::new(1.0, 1.0, 0.0));
//! ```
//!
//! # Ray Transformations
//!
//! Rays can be transformed using isometries (rigid body transformations):
//!
//! ```rust
//! use phys_geom::{Ray, math::Point3, math::Vec3, math::Isometry3};
//!
//! let origin = Point3::new(1.0, 0.0, 0.0);
//! let direction = Vec3::x_axis();
//! let ray = Ray::new(origin, direction);
//! let isometry = Isometry3::translation(1.0, 0.0, 0.0);
//! let transformed_ray = ray.inverse_transform(&isometry);
//! ```
//!
//! # Performance Considerations
//!
//! - Ray creation is cheap and involves minimal computation
//! - Direction vectors are stored as unit vectors for efficiency
//! - The `one_over_direction` method pre-computes values for efficient AABB intersection
//! - Transform operations require inverse transformation calculations

use crate::math::{Isometry3, Point3, UnitVec3, Vec3};
use crate::Real;

/// A ray composed of an origin point and a unit direction vector.
///
/// A ray represents a half-line that starts at the origin point and extends infinitely
/// in the direction specified by the unit vector. Rays are fundamental for ray casting,
/// intersection testing, and various geometric algorithms.
///
/// # Mathematical Representation
///
/// A ray can be parametrically represented as:
/// `R(t) = origin + t * direction` where `t >= 0`
///
/// # Examples
///
/// ```rust
/// use phys_geom::{Ray, math::Point3, math::Vec3};
///
/// // Create a ray from the origin along the X-axis
/// let origin = Point3::new(0.0, 0.0, 0.0);
/// let direction = Vec3::x_axis();
/// let ray = Ray::new(origin, direction);
///
/// // Create a ray using automatic normalization
/// let ray2 = Ray::new_with_vec3(origin, Vec3::new(2.0, 0.0, 0.0));
/// ```
///
/// # Memory Layout
///
/// The struct uses `#[repr(C)]` for FFI compatibility and stores the origin as a Point3
/// and direction as a UnitVec3 (guaranteed to be normalized).
///
/// # Common Use Cases
///
/// - **Collision Detection**: Testing intersections with geometric shapes
/// - **Picking**: Selecting objects in 3D scenes
/// - **Visibility Testing**: Determining line-of-sight
/// - **Rendering**: Ray tracing and casting algorithms
#[repr(C)]
#[derive(Clone, Copy, Debug)]
pub struct Ray {
    /// The starting point of the ray
    pub origin: Point3,
    /// The direction of the ray (guaranteed to be a unit vector)
    pub direction: UnitVec3,
}

impl Ray {
    /// Creates a new ray with the specified origin and direction.
    ///
    /// # Arguments
    ///
    /// * `origin` - The starting point of the ray
    /// * `direction` - The direction of the ray (must be a unit vector)
    ///
    /// # Returns
    ///
    /// A new `Ray` instance.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::{Ray, math::Point3, math::Vec3, math::UnitVec3};
    ///
    /// let origin = Point3::new(1.0, 2.0, 3.0);
    /// let direction = UnitVec3::new_normalize(Vec3::new(1.0, 0.0, 0.0));
    /// let ray = Ray::new(origin, direction);
    /// ```
    #[inline]
    #[must_use]
    pub fn new(origin: Point3, direction: UnitVec3) -> Self {
        Self { origin, direction }
    }

    /// Creates a new ray, automatically normalizing the direction vector.
    ///
    /// This is a convenience method that creates a ray from any non-zero direction
    /// vector by automatically normalizing it to unit length.
    ///
    /// # Arguments
    ///
    /// * `origin` - The starting point of the ray
    /// * `direction` - The direction vector (will be normalized)
    ///
    /// # Returns
    ///
    /// A new `Ray` instance with normalized direction.
    ///
    /// # Panics
    ///
    /// Will panic if `direction` is zero or infinite length.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::{Ray, math::Point3, math::Vec3, math::UnitVec3};
    ///
    /// let origin = Point3::new(0.0, 0.0, 0.0);
    /// let direction = Vec3::new(3.0, 4.0, 0.0); // Not normalized
    /// let ray = Ray::new_with_vec3(origin, direction);
    ///
    /// // Direction is automatically normalized to unit length
    /// let dir_array = ray.direction.as_ref();
    /// let dir_length = (dir_array[0].powi(2) + dir_array[1].powi(2) + dir_array[2].powi(2)).sqrt();
    /// assert!((dir_length - 1.0).abs() < 1e-6);
    /// ```
    #[inline]
    #[must_use]
    pub fn new_with_vec3(origin: impl Into<[Real; 3]>, direction: impl Into<[Real; 3]>) -> Self {
        Self {
            origin: origin.into().into(),
            direction: UnitVec3::new_normalize(direction.into().into()),
        }
    }

    /// Computes the reciprocal of direction components for efficient Ray-AABB intersection testing.
    ///
    /// This method computes optimized values used in slab-based ray-AABB intersection algorithms.
    /// The result incorporates sign information and avoids division by zero by using a small
    /// epsilon.
    ///
    /// # Mathematical Details
    ///
    /// For each component of the direction vector, computes:
    /// `result[i] = sign(direction[i]) / max(|direction[i]|, ε)`
    /// where ε = 1e-15 to prevent division by zero.
    ///
    /// # Arguments
    ///
    /// * `direction` - The unit direction vector to process
    ///
    /// # Returns
    ///
    /// A Vec3 containing the optimized reciprocal values. Note that this is **not** a unit vector.
    ///
    ///
    /// # See Also
    ///
    /// - [`Self::one_over_direction`] - Instance method that uses this computation
    /// - [`crate::Aabb3::raycast`] - Method that uses these values for intersection testing
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::{Ray, math::Vec3, math::UnitVec3};
    ///
    /// let direction = UnitVec3::new_normalize(Vec3::new(1.0, 2.0, 3.0));
    /// let one_over = Ray::compute_one_over_direction(direction);
    ///
    /// // The result preserves sign information
    /// assert!(one_over.x > 0.0);
    /// assert!(one_over.y > 0.0);
    /// assert!(one_over.z > 0.0);
    /// ```
    #[inline]
    #[must_use]
    pub fn compute_one_over_direction(direction: UnitVec3) -> Vec3 {
        let one = Vec3::new(
            if direction.x < 0.0 { -1.0 } else { 1.0 },
            if direction.y < 0.0 { -1.0 } else { 1.0 },
            if direction.z < 0.0 { -1.0 } else { 1.0 },
        );
        let v = direction
            .into_inner()
            .abs()
            .sup(&Vec3::new(1e-15, 1e-15, 1e-15));
        one.component_div(&v)
    }

    /// Computes the reciprocal of this ray's direction for Ray-AABB intersection testing.
    ///
    /// This is a convenience method that calls [`Self::compute_one_over_direction`] with
    /// this ray's direction vector. The result is optimized for slab-based AABB intersection
    /// algorithms.
    ///
    /// # Returns
    ///
    /// A Vec3 containing optimized reciprocal values for this ray's direction.
    /// Note that this is **not** a unit vector.
    ///
    /// # Performance Note
    ///
    /// Call this method once per ray and reuse the result for multiple AABB intersection
    /// tests to maximize performance.
    ///
    /// # See Also
    ///
    /// - [`Self::compute_one_over_direction`] - Static method with detailed explanation
    /// - [`crate::Aabb3::raycast`] - Method that uses these values
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::{Ray, math::Point3, math::Vec3};
    ///
    /// let direction = Vec3::x_axis();
    /// let ray = Ray::new(Point3::origin(), direction);
    /// let one_over = ray.one_over_direction();
    ///
    /// // Can be used for efficient AABB testing
    /// // let intersects = aabb.raycast_by_one_over_direction(ray.origin, one_over, max_distance);
    /// ```
    #[inline]
    #[must_use]
    pub fn one_over_direction(&self) -> Vec3 {
        Self::compute_one_over_direction(self.direction)
    }

    /// Applies the inverse of the given transformation to this ray.
    ///
    /// This method transforms the ray by the inverse of the specified isometry,
    /// which is useful for transforming rays from world space to object space.
    ///
    /// # Arguments
    ///
    /// * `transform` - The isometry to invert and apply to the ray
    ///
    /// # Returns
    ///
    /// A new `Ray` instance representing the transformed ray.
    ///
    /// # Mathematical Details
    ///
    /// The transformation applies:
    /// - Origin: `origin' = transform⁻¹ * origin`
    /// - Direction: `direction' = transform⁻¹ * direction` (rotation only)
    ///
    /// Note that the direction is only affected by the rotational component of the
    /// transform, as directions are invariant under translation.
    ///
    /// # Use Cases
    ///
    /// - **Object-space ray casting**: Transform world-space rays to object space
    /// - **Hierarchical collision testing**: Transform rays through scene graphs
    /// - **Inverse transformations**: Computing original rays from transformed ones
    ///
    /// # Examples
    ///
    /// ```rust
    /// use phys_geom::{Ray, math::Point3, math::Vec3, math::Isometry3};
    ///
    /// let ray = Ray::new(Point3::new(1.0, 0.0, 0.0), Vec3::x_axis());
    /// let transform = Isometry3::translation(1.0, 0.0, 0.0);
    ///
    /// let transformed_ray = ray.inverse_transform(&transform);
    ///
    /// // The ray origin is now at (0.0, 0.0, 0.0) in the new coordinate system
    /// assert_eq!(transformed_ray.origin, Point3::new(0.0, 0.0, 0.0));
    /// ```
    #[inline]
    #[must_use]
    pub fn inverse_transform(&self, transform: &Isometry3) -> Self {
        Self {
            origin: transform.inverse_transform_point(&self.origin),
            direction: transform.rotation.inverse() * self.direction,
        }
    }
}