Module math 

Core math types and operations for the OxiPhysics engine.

All other OxiPhysics crates should import math types from oxiphysics_core::math rather than depending on nalgebra directly.

Structs

Aabb

Axis-aligned bounding box in 3-D.

Dual

A dual number a + b * ε where ε² = 0.

Frustum

A view frustum defined by 6 planes (near, far, left, right, top, bottom).

Plane

A plane defined by a normal and signed distance from origin.

Ray

A ray defined by an origin and direction.

Unit

A wrapper that ensures the underlying algebraic entity has a unit norm.

Functions

barycentric_coords

Barycentric coordinates of point p with respect to triangle (a, b, c).

bezier_arc_length

Arc length of a cubic Bézier curve approximated with n segments.

bezier_cubic

Cubic Bézier curve.

bspline_basis3

B-spline basis functions for a clamped uniform cubic B-spline (degree 3).

build_orthonormal_basis

Build an orthonormal basis (tangent, bitangent, normal) given a surface normal n (must be unit length).

cartesian_to_cylindrical

Convert Cartesian coordinates to cylindrical (rho, phi, z).

cartesian_to_spherical

Convert Cartesian coordinates (x, y, z) to spherical (r, theta, phi).

catmull_rom

Catmull-Rom spline interpolation.

closest_point_on_line

Closest point on line (origin + t * dir) to point p. dir should be a unit vector.

closest_point_on_segment

Closest point on segment a–b to point p.

cross_matrix

Build the skew-symmetric (cross-product) matrix for v.

cross_product_matrix

Cross product matrix [a]× such that [a]× * b = a × b.

cylindrical_to_cartesian

Convert cylindrical coordinates (rho, phi, z) to Cartesian.

cylindrical_to_vec3

Convert cylindrical (rho, phi, z) to a Cartesian Vec3.

double_cross_matrix

Double cross product a × (a × b) expressed as a matrix times b: the matrix is -[a]ײ = a*aᵀ - (a·a)*I.

dual_differentiate

Compute the derivative of f at x using dual numbers.

gram_schmidt

Gram-Schmidt orthogonalization of three linearly-independent vectors.

gram_schmidt_vectors

Gram-Schmidt orthonormalization of up to n vectors stored in vecs.

hermite_interpolate

Hermite spline interpolation between two points p0 and p1 with tangents m0 and m1. Parameter t runs from 0 (at p0) to 1 (at p1).

look_at

Create a look-at view matrix (right-handed).

mat3_adjugate

Adjugate (classical adjoint) of a 3×3 matrix: adj(M) = det(M) * M^{-1}.

mat3_adjugate_na

Adjugate of a nalgebra Mat3 (transpose of the cofactor matrix).

mat3_arr_inverse

Inverse of a 3×3 matrix. Returns None if singular (|det| < 1e-14).

mat3_cayley_hamilton

Verify the Cayley-Hamilton theorem for a 3×3 matrix M.

mat3_cofactor

Cofactor matrix of a 3×3 matrix.

mat3_compose_rotations

Compose two rotation matrices: r_total = r2 * r1 (first apply r1, then r2).

mat3_det

Determinant of a 3×3 matrix.

mat3_determinant

Compute the determinant of a 3x3 matrix.

mat3_eigenvalues_symmetric

Compute real eigenvalues of a symmetric 3x3 matrix.

mat3_exp_skew

Matrix exponential of a skew-symmetric matrix (rotation matrix).

mat3_frobenius_norm

Compute the Frobenius norm of a 3x3 matrix.

mat3_from_axis_angle

Build a rotation matrix from an axis (unit vector) and angle (radians).

mat3_from_cols

Build a 3×3 matrix from three column vectors.

mat3_from_euler_zyx

Build a rotation matrix from ZYX Euler angles (roll, pitch, yaw) in radians.

mat3_gram_schmidt

Modified Gram-Schmidt applied to the columns of a Mat3.

mat3_inverse

Compute the inverse of a 3x3 matrix.

mat3_log_rotation

Matrix logarithm of a rotation matrix R.

mat3_mul_mat3

Multiply two 3×3 matrices: a * b.

mat3_mul_vec3

Multiply a 3×3 matrix by a 3-vector: m * v.

mat3_outer_product

Outer product of two 3-vectors: a ⊗ b (a 3×3 matrix).

mat3_rotation_angle

Extract the rotation angle from a 3×3 rotation matrix.

mat3_rotation_axis

Extract the rotation axis (unit vector) from a 3×3 rotation matrix.

mat3_rotation_from_to

Build a rotation matrix that takes unit vector from to unit vector to.

mat3_slerp

Interpolate between two rotation matrices using matrix slerp.

mat3_to_euler_zyx

Extract ZYX Euler angles (yaw, pitch, roll) from a rotation matrix.

mat3_trace

Compute the trace of a 3x3 matrix.

mat3_transpose

Transpose a 3×3 matrix stored as [[f64;3\];3] (row-major).

mat3_weighted_mean

Compute the average of multiple rotation matrices using the iterative geodesic mean (Moakher 2002). weights must be non-negative and sum to 1.

orthographic

Create an orthographic projection matrix (right-handed).

perspective

Create a perspective projection matrix (right-handed, depth [0, 1]).

plane_from_point_normal

Create a plane [nx, ny, nz, d] from a point p and unit normal n.

plane_plane_intersection

Compute the intersection line of two planes.

plane_signed_dist

Signed distance from point to the plane [nx, ny, nz, d].

point_in_triangle

Test whether point p lies inside triangle (a, b, c).

point_to_line_distance

Distance from point p to the line defined by origin and unit dir.

point_to_segment_distance

Distance from point p to segment a–b.

polar_decomposition

Compute the polar decomposition of a 3×3 matrix M = R * S where R is orthogonal (rotation) and S is symmetric positive semi-definite.

quat_arr_conjugate

Convert a unit quaternion [x,y,z,w] to its conjugate.

quat_arr_dot

Dot product of two quaternions (as 4-vectors).

quat_arr_exp

Quaternion exponential for a pure quaternion v = [x, y, z, 0].

quat_arr_from_axis_angle

Create a unit quaternion [x, y, z, w] from an axis-angle pair.

quat_arr_log

Quaternion logarithm for a unit quaternion q = [x, y, z, w].

quat_arr_normalize

Normalize a quaternion [x,y,z,w] to unit length.

quat_arr_pow

Power of a unit quaternion: q^t = exp(t * log(q)).

quat_arr_rotate_vec3

Rotate a 3-vector by a unit quaternion q = [x,y,z,w] using the sandwich product q * v * q^*.

quat_arr_slerp

Spherical linear interpolation between two unit quaternions (format: [x,y,z,w]).

quat_arr_squad_control

Double-geodesic (SQUAD) interpolation at midpoint between two key frames.

quat_blend

Linear blending of two quaternions followed by renormalization (NLerp).

quat_double_cover_fix

Ensure double-cover consistency: negate q if its w < 0 so that the canonical representative always has w ≥ 0.

quat_exp

Quaternion exponential of a pure quaternion v (w component ignored).

quat_from_axis_angle

Create a quaternion from an axis-angle representation.

quat_from_euler

Create a quaternion from Euler angles (roll, pitch, yaw) in radians.

quat_from_two_vectors

Build a unit quaternion that rotates from onto to.

quat_geodesic_distance

Geodesic (angular) distance between two unit quaternions.

quat_integrate_rk4

Runge–Kutta 4th-order integration of a quaternion ODE.

quat_log

Quaternion logarithm of a UnitQuaternion.

quat_multiply

Multiply two quaternions p * q (Hamilton product). Format: [x, y, z, w].

quat_nlerp

Normalized linear interpolation (nlerp) between two unit quaternions.

quat_slerp

Spherical linear interpolation between two quaternions.

quat_squad

SQUAD (Spherical Quadrangle interpolation) for smooth quaternion paths.

quat_squad_control

Build the inner control quaternion s_i needed for SQUAD interpolation.

quat_squad_na

Spherical cubic interpolation (SQUAD) between two UnitQuaternions.

quat_to_axis_angle

Convert a unit quaternion [x, y, z, w] to (axis, angle).

quat_to_euler

Convert a quaternion to Euler angles (roll, pitch, yaw) in radians.

quat_to_mat3

Convert a unit quaternion [x, y, z, w] to a 3×3 rotation matrix (row-major).

reflect_direction

Compute the reflection of direction d about unit normal n.

rodrigues_rotate

Rodrigues rotation: rotate vector v around unit axis by angle radians.

sample_hemisphere_cosine

Cosine-weighted sample on the unit hemisphere (z ≥ 0).

sample_hemisphere_uniform

Uniformly sample a direction on the unit hemisphere (z ≥ 0) given two uniform random numbers u1, u2 ∈ [0, 1).

sample_unit_disk_concentric

Uniformly sample a point on the surface of a unit disk.

sh_project_l1

Project a radiance function sampled at n uniformly-spread directions onto the 4 L0+L1 SH coefficients [c00, c1m1, c10, c11].

sh_y00

Evaluate real spherical harmonic Y_0^0 (degree 0, order 0).

sh_y1m1

Evaluate real spherical harmonic Y_1^{-1} (degree 1, order -1).

sh_y10

Evaluate real spherical harmonic Y_1^0 (degree 1, order 0).

sh_y11

Evaluate real spherical harmonic Y_1^1 (degree 1, order 1).

skew_symmetric

Build a skew-symmetric matrix from a vector (for cross product as matrix multiply).

spherical_to_cartesian

Convert spherical coordinates (r, theta, phi) to Cartesian (x, y, z).

spherical_to_vec3

Convert spherical (r, theta, phi) to a Cartesian Vec3.

spin_matrix

Spin matrix for angular velocity omega: the time-derivative of a rotation matrix R satisfies Ṙ = omega_hat * R where omega_hat = skew(omega).

symmetric_eigen3

Compute eigenvalues and eigenvectors of a real symmetric 3×3 matrix using the Jacobi iteration method.

three_plane_intersection

Compute the intersection point of three planes.

vec4

Create a Vec4 from components.

vec3_abs

Absolute value of each component of v.

vec3_angle_between

Angle in radians between two non-zero vectors a and b.

vec3_clamp

Component-wise clamp of v to [lo, hi].

vec3_cross

Cross product of two 3-vectors: a × b.

vec3_decompose

Decompose a Vec3 into components parallel and perpendicular to axis (which must be a unit vector).

vec3_lerp

Linear interpolation between two 3-vectors: a + t*(b-a).

vec3_max

Component-wise maximum of two Vec3 values.

vec3_min

Component-wise minimum of two Vec3 values.

vec3_outer_product

Outer product of two Vec3 vectors: a ⊗ b as a nalgebra Mat3.

vec3_project

Project vector a onto onto. Returns the zero vector if onto is zero.

vec3_project_onto

Project v onto the unit direction onto_unit.

vec3_project_onto_plane

Project a Vec3 onto a plane defined by its unit normal n.

vec3_project_onto_unit

Project vector v onto unit direction onto_unit.

vec3_reflect

Reflect vector v about unit normal n: v - 2*(v·n)*n.

vec3_reflect_about

Reflect v about the unit normal n: v - 2*(v·n)*n.

vec3_reflect_about_normal

Reflect vector v about unit normal n: v - 2*(v·n)*n.

vec3_refract

Refract v about the unit normal n with relative index of refraction eta.

vec3_refract_ratio

Refract vector v (unit incident) through a surface with unit normal n.

vec3_reject

Reject (orthogonal complement) of v with respect to unit direction u: reject(v, u) = v - project(v, u).

vec3_reject_from

Reject v from the unit direction onto_unit (perpendicular component).

vec3_rotate_by_angle

Rotate vector v around unit axis by angle radians (Rodrigues’ formula).

vec3_rotate_by_quat

Rotate v by quaternion q.

vec3_scalar_triple

Scalar triple product a · (b × c).

vec3_signed_angle

Signed angle (in radians) from a to b measured about axis.

vec3_to_cylindrical

Convert a Cartesian 3-vector to cylindrical coordinates (rho, phi, z).

vec3_to_spherical

Convert a Cartesian Vec3 to spherical coordinates (r, theta, phi).

vec3_triple_product

Scalar triple product: a · (b × c).

vec3_vector_triple

Vector triple product a × (b × c) = b*(a·c) - c*(a·b).

vec4_direction

Homogeneous direction (w=0).

vec4_point

Homogeneous point (w=1).

vec4_to_vec3

Project a Vec4 back to Vec3 by dividing by w.

Type Aliases

Mat3

3x3 matrix type alias.

Mat4

4x4 matrix type alias.

Matrix3

A stack-allocated, column-major, 3x3 square matrix.

Matrix4

A stack-allocated, column-major, 4x4 square matrix.

Point3

A statically sized 3-dimensional column point.

Quat

Quaternion type alias.

Real

Scalar type used throughout the engine (f64 by default).

UnitQuaternion

A unit quaternions. May be used to represent a rotation.

Vec3

3D vector type alias.

Vec4

4D vector type alias.

Vector3

A stack-allocated, 3-dimensional column vector.

Vector4

A stack-allocated, 4-dimensional column vector.