Struct Torus 

pub struct Torus {
    pub major_radius: Real,
    pub minor_radius: Real,
}

A torus defined by major radius R (center to tube center) and minor radius r (tube radius).

The torus lies in the XZ plane (Y is the axis of symmetry).

Fields

major_radius: Real

Major radius: distance from the center of the torus to the center of the tube.

minor_radius: Real

Minor radius: radius of the tube.

Implementations

impl Torus

pub fn new(major_radius: Real, minor_radius: Real) -> Self

Create a new torus with the given major and minor radii.

pub fn volume(&self) -> Real

Volume = 2π²Rr²

pub fn surface_area(&self) -> Real

Surface area = 4π²Rr

pub fn bounding_box_extents(&self) -> Vec3

Approximate bounding box half-extents: outer radius = R+r, height = r.

Returns half-extents as [R+r, r, R+r] (torus in XZ plane, Y is up).

pub fn inertia_tensor_array(&self, mass: Real) -> [[f64; 3]; 3]

Inertia tensor for a solid torus of given mass.

Axis of symmetry is Y. Standard formulas: I_y = m*(R² + (3/4)r²) (but commonly written as m(3R²+4r²)/4 – equivalent) I_xz = m*((5/8)r² + R²/2) (= m(5r²+4R²)/8)

pub fn ray_cast_array( &self, origin: [f64; 3], direction: [f64; 3], max_toi: f64, ) -> Option<(f64, [f64; 3])>

Cast a ray against the torus using an iterative quartic solver approach.

The torus implicit equation (centered at origin, axis = Y): (x²+y²+z² + R²−r²)² − 4R²(x²+z²) = 0

Substituting P+t*D gives a quartic in t which is solved by Ferrari’s method. Returns Some((t, normal)) or None.

pub fn closest_point(&self, p: [f64; 3]) -> [f64; 3]

Closest point on the torus surface to point p.

Projects p onto the nearest point on the ring circle (in XZ), then moves from that circle point toward p (or outward if p is inside tube) by the minor radius.

pub fn contains_point(&self, p: [f64; 3]) -> bool

Returns true if point p is inside (or on the surface of) the torus tube.

pub fn sample_surface(&self, u: f64, v: f64) -> [f64; 3]

Parametric surface sample: u ∈ [0,2π), v ∈ [0,2π).

Returns a point (x,y,z) on the torus surface. x = (R + rcos(v)) * cos(u) y = r * sin(v) z = (R + rcos(v)) * sin(u)

pub fn sdf(&self, p: [f64; 3]) -> f64

Torus SDF (signed distance to torus surface).

Negative inside the tube, positive outside.

pub fn ray_torus_analytic( &self, origin: [f64; 3], direction: [f64; 3], max_toi: f64, ) -> Option<(f64, [f64; 3])>

Torus-ray analytic intersection (same as ray_cast_array but explicit name).

pub fn support_array(&self, direction: [f64; 3]) -> [f64; 3]

Torus support function (plain array).

pub fn surface_parameters(&self, p: [f64; 3]) -> (f64, f64)

Surface parameterization: returns the (u, v) angles for the point on the torus surface closest to p.

u is the angle around the major circle (XZ plane), v is the angle around the tube (in the plane through the Y axis and the ring point).

pub fn random_surface_points(&self, n: usize, seed: u64) -> Vec<[f64; 3]>

Generate n random points uniformly distributed on the torus surface.

Uses a deterministic xorshift64 PRNG seeded with seed. Sampling: uniform in u and v, weighted by area element (R + r cos v).

pub fn inertia_raw(&self, mass: f64) -> [[f64; 3]; 3]

Approximate solid torus inertia tensor from inertia_tensor_array.

pub fn outer_radius(&self) -> f64

Outer radius of the torus (major + minor).

pub fn inner_radius(&self) -> f64

Inner radius of the torus (major - minor, clamped to 0).

pub fn uv_map(&self, p: [f64; 3]) -> [f64; 2]

UV mapping for the torus surface.

Maps a surface point p to texture coordinates (u, v) in [0, 1)². u corresponds to the major (longitudinal) angle and v to the minor (latitudinal) angle, both normalised to the range [0, 1).

pub fn geodesic_distance_flat(&self, a: [f64; 3], b: [f64; 3]) -> f64

Approximate geodesic distance between two surface points a and b via the flat-torus metric.

The flat-torus metric: d = sqrt((R Δθ)² + (r Δφ)²) where Δθ and Δφ are the wrapped angular differences on the major and minor circles.

pub fn area_element_factor(&self, v: f64) -> f64

Area element at angle v on the tube: (R + r cos v) r dv du.

Returns the area-weighted factor R + r*cos(v) for the given tube angle v.

pub fn surface_area_numeric(&self, n_steps: usize) -> f64

Approximate surface area by numerical integration (cross-check of closed form).

Uses n_steps Gauss-Legendre-like sampling along each angular dimension.

pub fn tube_cross_section(&self, u: f64, n: usize) -> Vec<[f64; 3]>

Tube cross-section: return a list of n points on the tube circle at angle u.

The circle lies in the plane through the ring point at angle u and the Y axis.

pub fn torus_knot_path(&self, p: i32, q: i32, n_pts: usize) -> Vec<[f64; 3]>

Generate a torus knot path with winding numbers (p, q).

A (p, q)-torus knot winds around the major circle p times while winding around the tube q times. Returns n_pts sampled points.

pub fn winding_number_major(&self, curve: &[[f64; 3]]) -> i32

Winding number of a closed curve projected onto the torus major circle.

Counts how many times the sequence of (u, _) angles (extracted from the points via surface_parameters) winds around the major circle.

Returns an integer winding count (positive = counter-clockwise).

pub fn tangent_u(&self, u: f64, v: f64) -> [f64; 3]

Parametric tangent vector on the torus surface in the u direction.

dP/du at (u, v): partial derivative with respect to the major angle.

pub fn tangent_v(&self, u: f64, v: f64) -> [f64; 3]

Parametric tangent vector on the torus surface in the v direction.

dP/dv at (u, v): partial derivative with respect to the tube angle.

pub fn normal_from_tangents(&self, u: f64, v: f64) -> [f64; 3]

Surface normal via cross product of tangents dP/du × dP/dv.

Should agree with torus_normal up to sign conventions.

pub fn ray_intersection_count( &self, origin: [f64; 3], direction: [f64; 3], max_toi: f64, ) -> usize

Test whether a ray intersects the torus and return the hit count.

A finite ray with origin o, direction d, and parameter max_toi can intersect the torus at 0, 2, or 4 points. This counts all positive-t intersections within [0, max_toi].

pub fn intersects_aabb(&self, aabb_min: [f64; 3], aabb_max: [f64; 3]) -> bool

Approximate torus-AABB overlap test via SDF.

Returns true if the AABB [min, max] overlaps the torus. Uses the 8 corners of the AABB as sample points.

pub fn aspect_ratio(&self) -> f64

Aspect ratio of the torus: major_radius / minor_radius.

Returns the ratio R/r. A value close to 1 means the torus is nearly self-intersecting; large values mean a thin tube.

pub fn major_circle_points(&self, n: usize) -> Vec<[f64; 3]>

Generate n equidistant points along the major circle (the ring itself).

Points lie on the spine of the torus (on the ring circle in the XZ plane, at y = 0).

Trait Implementations

impl Clone for Torus

fn clone(&self) -> Torus

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Torus

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

Formats the value using the given formatter.

impl Shape for Torus

fn bounding_box(&self) -> Aabb

Compute the axis-aligned bounding box of this shape (in local space).

fn support_point(&self, direction: &Vec3) -> Vec3

Compute the support point in the given direction (for GJK).

fn volume(&self) -> Real

Compute the volume of this shape.

fn center_of_mass(&self) -> Vec3

Compute the center of mass in local space.

fn inertia_tensor(&self, mass: Real) -> Mat3

Compute the inertia tensor for the given mass.

fn mass_properties(&self, density: Real) -> MassProperties

Compute full mass properties for a given density.

fn ray_cast( &self, ray_origin: &Vec3, ray_direction: &Vec3, max_toi: Real, ) -> Option<RayHit>

Cast a ray against this shape (in local space). Returns the first intersection within max_toi.