Struct Ray

#[repr(C)]
pub struct Ray {
    pub origin: Point<f32>,
    pub dir: Vector<f32>,
}

A ray for ray-casting queries.

A ray is a half-infinite line starting at an origin point and extending infinitely in a direction. Rays are fundamental for visibility queries, shooting mechanics, and collision prediction.

Structure

• origin: The starting point of the ray
• dir: The direction vector (does NOT need to be normalized)

Direction Vector

The direction can be any non-zero vector:

• Normalized: dir with length 1.0 gives time-of-impact in world units
• Not normalized: Time-of-impact is scaled by dir.norm()

Most applications use normalized directions for intuitive results.

Use Cases

• Shooting/bullets: Check what a projectile hits
• Line of sight: Check if one object can “see” another
• Mouse picking: Select objects by clicking
• Laser beams: Simulate light or laser paths
• Proximity sensing: Detect obstacles in a direction

Example

use parry3d::query::{Ray, RayCast};
use parry3d::shape::Ball;
use nalgebra::{Point3, Vector3, Isometry3};

// Create a ray from origin pointing along +X axis
let ray = Ray::new(
    Point3::origin(),
    Vector3::new(1.0, 0.0, 0.0)  // Normalized direction
);

// Create a ball at position (5, 0, 0) with radius 1
let ball = Ball::new(1.0);
let ball_pos = Isometry3::translation(5.0, 0.0, 0.0);

// Cast the ray against the ball
if let Some(toi) = ball.cast_ray(&ball_pos, &ray, 100.0, true) {
    // Ray hits at t=4.0 (center at 5.0 minus radius 1.0)
    assert_eq!(toi, 4.0);

    // Compute the actual hit point
    let hit_point = ray.point_at(toi);
    assert_eq!(hit_point, Point3::new(4.0, 0.0, 0.0));
}

Fields

origin: Point<f32>

Starting point of the ray.

This is where the ray begins. Points along the ray are computed as origin + dir * t for t ≥ 0.

dir: Vector<f32>

Direction vector of the ray.

This vector points in the direction the ray travels. It does NOT need to be normalized, but using a normalized direction makes time-of-impact values represent actual distances.

Implementations

impl Ray

pub fn new(origin: Point<f32>, dir: Vector<f32>) -> Ray

Creates a new ray from an origin point and direction vector.

Arguments

• origin - The starting point of the ray
• dir - The direction vector (typically normalized but not required)

Example

use parry3d::query::Ray;
use nalgebra::{Point3, Vector3};

// Horizontal ray pointing along +X axis
let ray = Ray::new(
    Point3::new(0.0, 5.0, 0.0),
    Vector3::new(1.0, 0.0, 0.0)
);

// Ray starts at (0, 5, 0) and points along +X
assert_eq!(ray.origin, Point3::new(0.0, 5.0, 0.0));
assert_eq!(ray.dir, Vector3::new(1.0, 0.0, 0.0));

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

Transforms this ray by the given isometry (translation + rotation).

Both the origin and direction are transformed.

Example

use parry3d::query::Ray;
use nalgebra::{Isometry3, Point3, Vector3};

let ray = Ray::new(Point3::origin(), Vector3::x());

// Translate by (5, 0, 0)
let transform = Isometry3::translation(5.0, 0.0, 0.0);
let transformed = ray.transform_by(&transform);

assert_eq!(transformed.origin, Point3::new(5.0, 0.0, 0.0));
assert_eq!(transformed.dir, Vector3::x());

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

Transforms this ray by the inverse of the given isometry.

This is equivalent to transforming the ray to the local space of an object.

Example

use parry3d::query::Ray;
use nalgebra::{Isometry3, Point3, Vector3};

let ray = Ray::new(Point3::new(10.0, 0.0, 0.0), Vector3::x());

let transform = Isometry3::translation(5.0, 0.0, 0.0);
let local_ray = ray.inverse_transform_by(&transform);

// Origin moved back by the translation
assert_eq!(local_ray.origin, Point3::new(5.0, 0.0, 0.0));

pub fn translate_by(&self, v: Vector<f32>) -> Self

Translates this ray by the given vector.

Only the origin is moved; the direction remains unchanged.

Example

use parry3d::query::Ray;
use nalgebra::{Point3, Vector3};

let ray = Ray::new(Point3::origin(), Vector3::x());
let translated = ray.translate_by(Vector3::new(10.0, 5.0, 0.0));

assert_eq!(translated.origin, Point3::new(10.0, 5.0, 0.0));
assert_eq!(translated.dir, Vector3::x()); // Direction unchanged

pub fn point_at(&self, t: f32) -> Point<f32>

Computes a point along the ray at parameter t.

Returns origin + dir * t. For t ≥ 0, this gives points along the ray.

Arguments

• t - The parameter (typically the time-of-impact from ray casting)

Example

use parry3d::query::Ray;
use nalgebra::{Point3, Vector3};

let ray = Ray::new(
    Point3::origin(),
    Vector3::new(1.0, 0.0, 0.0)
);

// Point at t=5.0
assert_eq!(ray.point_at(5.0), Point3::new(5.0, 0.0, 0.0));

// Point at t=0.0 is the origin
assert_eq!(ray.point_at(0.0), ray.origin);

Trait Implementations

impl Clone for Ray

fn clone(&self) -> Ray

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Ray

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

Formats the value using the given formatter.

impl Copy for Ray