Struct Ray

Source

#[repr(C)]pub struct Ray {
    pub origin: Point3,
    pub direction: UnitVec3,
}

Expand description

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

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

Fields§

§origin: Point3

The starting point of the ray

§direction: UnitVec3

The direction of the ray (guaranteed to be a unit vector)

Implementations§

Source §

impl Ray

Source

pub fn new(origin: Point3, direction: UnitVec3) -> Self

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

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);

Source

pub fn new_with_vec3( origin: impl Into<[Real; 3]>, direction: impl Into<[Real; 3]>, ) -> Self

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

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);

Source

pub fn compute_one_over_direction(direction: UnitVec3) -> Vec3

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

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);

Source

pub fn one_over_direction(&self) -> Vec3

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

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);

Source

pub fn inverse_transform(&self, transform: &Isometry3) -> Self

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

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));