Module math_functions

Expand description

Vectors, quaternions, transforms, and deterministic scalar math.

Core types (Vec3, Quat, Pos, Transform, Aabb, …) and the hand-rolled trig used for cross-platform determinism. Many of these are re-exported at the crate root (box3d_rust::Vec3, Pos, …).

With the double-precision feature, Pos (and related world-space scalars) widen to match BOX3D_DOUBLE_PRECISION; collision math stays f32.

Port of include/box3d/math_functions.h and src/math_functions.c. Submodules form one flat namespace via re-exports here.

SPDX-FileCopyrightText: 2025 Erin Catto SPDX-License-Identifier: MIT

Structs§

Aabb: Axis aligned bounding box.
CosSin: Cosine and sine pair. This uses a custom implementation designed for cross-platform determinism.
Mat2: A 2x2 matrix stored as columns. Ported from math_internal.h for tests and internal use (b3Matrix2).
Matrix3: A 3x3 matrix.
Plane: A plane. separation = dot(normal, point) - offset
Quat: A quaternion.
SegmentDistanceResult: The closest points between two segments or infinite lines.
Transform: A rigid transform.
Triangle: A triangle with vertex indices and edge flags. (math_internal.h: b3Triangle)
TrianglePoint: Closest point on a triangle and the feature that owns it. (math_internal.h: b3TrianglePoint)
Vec2: A 2D vector.
Vec3: A 3D vector.

Constants§

BOUNDS3_EMPTY: Empty AABB (inverted bounds). (math_internal.h: B3_BOUNDS3_EMPTY)
DEG_TO_RAD: Convenience constant to convert from degrees to radians. (B3_DEG_TO_RAD)
MAT2_ZERO: Zero 2x2 matrix. (math_internal.h literal)
MAT3_IDENTITY
MAT3_ZERO
MIN_SCALE: Minimum scale used for scaling collision meshes, etc. (B3_MIN_SCALE)
PI: https://en.wikipedia.org/wiki/Pi The C B3_PI literal (3.14159265359f) rounds to exactly this f32 value.
POS_ZERO
QUAT_IDENTITY
RAD_TO_DEG: Convenience constant to convert from radians to degrees. (B3_RAD_TO_DEG)
SQRT3: √3. (math_internal.h: B3_SQRT3)
TRANSFORM_IDENTITY
TWO_PI: 2π. (math_internal.h: B3_TWO_PI)
VEC2_ZERO
VEC3_AXIS_X
VEC3_AXIS_Y
VEC3_AXIS_Z
VEC3_ONE
VEC3_ZERO
WORLD_TRANSFORM_IDENTITY

Functions§

aabb_add_point: Add a point to an AABB. (math_internal.h: b3AABB_AddPoint)
aabb_area: Get the surface area of an axis-aligned bounding box.
aabb_center: Get the center of an axis-aligned bounding box.
aabb_contains: Does a fully contain b?
aabb_extents: Get the extents (half-widths) of an axis-aligned bounding box.
aabb_inflate: Add uniform padding to an axis-aligned bounding box.
aabb_overlaps: Do two axis-aligned boxes overlap?
aabb_transform: Transform an axis-aligned bounding box. This can create a larger box than if you recomputed the AABB of the original shape with the transform applied.
aabb_union: Get the union of two axis-aligned bounding boxes.
abs: Component-wise absolute value.
abs_float: @return the absolute value of a float.
abs_matrix3: Get the component-wise absolute value of a matrix.
add: Vector addition.
add2: 2D vector addition. (math_internal.h: b3Add2)
add_mm: Matrix addition. @return a + b
align_up8: Align x up to a multiple of 8. (math_internal.h: b3AlignUp8)
arbitrary_perp: Assume v is a unit vector. (math_internal.h: b3ArbitraryPerp)
atan2: Compute an approximate arctangent in the range [-pi, pi] This is hand coded for cross-platform determinism. The atan2f function in the standard library is not cross-platform deterministic. Accurate to around 0.0023 degrees.
blend2: Blend two vectors: s * a + t * b
blend3: Blend three vectors: s * a + t * b + u * c. (math_internal.h: b3Blend3)
box_inertia: Box inertia about the center for an AABB from min to max. (math_functions.c: b3BoxInertia)
clamp: Component-wise clamped value.
clamp_float: @return a float clamped between a lower and upper bound.
clamp_int: @return an integer clamped between a lower and upper bound.
closest_point_on_triangle: Closest point on triangle ABC to query point Q (Ericson §5.1.5). (math_functions.c: b3ClosestPointOnTriangle)
closest_point_to_aabb: Get the closest point on an axis-aligned bounding box.
compute_cos_sin: Compute the cosine and sine of an angle in radians. Implemented for cross-platform determinism.
compute_quat_between_unit_vectors: Find a quaternion that rotates one vector to another.
conjugate: Quaternion conjugate (cheap inverse).
cos: @deprecated
cross: https://en.wikipedia.org/wiki/Cross_product
cross2: 2D cross product (scalar). (math_internal.h: b3Cross2)
cylinder_inertia: Solid cylinder inertia about its center, axis along Y. (math_functions.c: b3CylinderInertia)
delta_quat_to_rotation: Pseudo angular velocity from a quaternion target. w = 2 * (target - q) * conj(q) (math_internal.h: b3DeltaQuatToRotation)
det: Compute the determinant of a 3-by-3 matrix.
distance: Distance between two points.
distance_squared: Squared distance between two points.
distance_squared2: 2D distance squared. (math_internal.h: b3DistanceSquared2)
dot: Vector dot product.
dot2: 2D dot product. (math_internal.h: b3Dot2)
dot_quat: Compute dot product of two quaternions. Useful for polarity tests.
get_axis_angle: Get the axis and angle from a quaternion. Assumes the quaternion is normalized.
get_by_index: Get a Vec3 component by index. (math_internal.h: b3GetByIndex)
get_length_and_normalize: Normalize a vector and return the length. Returns a zero vector if the input is very small.
get_quat_angle: Get the angle for a quaternion in radians
get_swing_angle: Swing angle used for cone limit
get_twist_angle: Twist angle around the z-axis, used for twist limit and revolute angle limit
integrate_rotation: Integrate rotation from angular velocity. delta_rotation is the angular displacement in radians (ω · h). q2 = q1 + 0.5 * omega * q1 (math_internal.h: b3IntegrateRotation)
intersect_ray_triangle: Intersect a ray with a triangle. Returns the hit fraction in (0, 1], or 1.0 on miss. (simd.c: b3IntersectRayTriangle, scalar path)
inv_mul_quat: Compute a relative quaternion. inv(q1) * q2
inv_mul_transforms: Creates a transform that converts a local point in frame B to a local point in frame A. This is useful for transforming points between the local spaces of two frames that are in world space.
inv_mul_world_transforms: Relative transform of frame B in frame A. The narrow phase boundary.
inv_rotate_vector: Inverse rotate a vector.
inv_transform_point: Inverse transform a point.
inv_transform_world_point: Transform a world position to a local point. One double subtraction, then float.
invert2: Invert a 2-by-2 matrix. (math_internal.h: b3Invert2)
invert_matrix: General matrix inverse.
invert_t: Invert a matrix (returns the adjugate / det without the final transpose of invert_matrix).
invert_transform: Get the inverse of a transform.
is_bounded_aabb: Is this AABB reasonably close to the origin? See B3_HUGE.
is_normalized: Is a vector normalized? In other words, does it have unit length?
is_normalized_quat: Does the supplied quaternion have unit length?
is_sane_aabb: Is this AABB valid and reasonable?
is_valid_aabb: Is this a valid bounding box? Not Nan or infinity. Upper bound greater than or equal to lower bound.
is_valid_float: Is this a valid number? Not NaN or infinity.
is_valid_matrix3: Is this a valid matrix? Not NaN or infinity.
is_valid_plane: Is this a valid plane? Normal is a unit vector. Not Nan or infinity.
is_valid_position: Is this a valid world position? Not NaN or infinity.
is_valid_quat: Is this a valid quaternion? Not NaN or infinity. Is normalized.
is_valid_transform: Is this a valid transform? Not NaN or infinity. Is normalized.
is_valid_vec3: Is this a valid vector? Not NaN or infinity.
is_valid_world_transform: Is this a valid world transform? Not NaN or infinity. Rotation is normalized.
is_within_segments: True if both closest-point fractions lie on their segments. (math_internal.h: b3IsWithinSegments)
length: Vector length.
length2: 2D length. (math_internal.h: b3Length2)
length_squared: Vector length squared.
length_squared2: 2D length squared. (math_internal.h: b3LengthSquared2)
lerp: Linearly interpolate between two vectors.
lerp_float: Interpolate a scalar.
lerp_position: World position interpolation for sweeps and sampling.
line_distance: Compute the closest points on two infinite lines.
major_axis: Major axis of a vector (same as max_element_index). (math_internal.h: b3MajorAxis)
make_aabb: Get the AABB of a point cloud.
make_diagonal_matrix: Diagonal matrix. (math_internal.h: b3MakeDiagonalMatrix)
make_matrix_from_quat: Make a matrix from a quaternion. This is useful if you need to rotate many vectors.
make_normal_from_points: Unit normal from three points. (math_internal.h: b3MakeNormalFromPoints)
make_plane_from_normal_and_point: Plane through point with given normal. (math_internal.h: b3MakePlaneFromNormalAndPoint)
make_plane_from_points: Plane through three points. (math_internal.h: b3MakePlaneFromPoints)
make_quat_from_axis_angle: Make a quaternion that is equivalent to rotating around an axis by a specified angle.
make_quat_from_matrix: Extract a quaternion from a rotation matrix.
make_world_transform: Promote a float transform to a world transform. Lossless.
max: Component-wise maximum value.
max_element_index: Index of the largest component. (math_internal.h: b3MaxElementIndex)
max_float: @return the maximum of two floats.
max_int: @return the maximum of two integers.
min: Component-wise minimum value.
min_float: @return the minimum of two floats. Matches the C ternary exactly, including NaN propagation (a < b is false for NaN).
min_int: @return the minimum of two integers.
modified_cross: Component-wise product sum used for AABB extent under rotation. (math_internal.h: b3ModifiedCross)
mul: Vector component-wise multiplication.
mul_add: a + s * b
mul_mm: Matrix multiplication. @return a * b
mul_mm2: Multiply two 2-by-2 matrices. (math_internal.h: b3MulMM2)
mul_mv: Multiply a matrix times a column vector.
mul_mv2: Multiply a 2-by-2 matrix times a 2D vector. (math_internal.h: b3MulMV2)
mul_mv2_sym: Symmetric 2×2 × vector matching b3MulMV2W (cxx=cx.x, cxy=cx.y, cyy=cy.y).
mul_mv_sym: Symmetric matrix × vector matching b3MulMVW under B3_SIMD_NONE.
mul_quat: Multiply two quaternions.
mul_sm: Multiply a matrix by a scalar, component-wise.
mul_sub: a - s * b
mul_sv: s * a
mul_sv2: 2D scalar multiply. (math_internal.h: b3MulSV2)
mul_transforms: Multiply two transforms. If the result is applied to a point p local to frame B, the transform would first convert p to a point local to frame A, then into a point in the world frame. This is useful if frame B is a child of frame A.
mul_world_transforms: Compose a world transform with a local transform.
neg: Vector negation.
negate_mat3: Negate a matrix.
negate_quat: Component-wise quaternion negation.
nlerp: Linearly interpolate and normalize between two quaternions
normalize: Normalize a vector. Returns a zero vector if the input vector is very small.
normalize_quat: Normalize a quaternion.
offset_aabb: Translate a local AABB by a world origin, rounding outward so the float box always contains the double box. Far from the origin a plain conversion could clip a shape out of its own box. In float mode the origin is float and the rounding is a no-op.
offset_pos: p + d
perp: Get a unit vector that is perpendicular to the supplied vector.
plane_separation: Signed separation of a point from a plane. (math_internal.h: b3PlaneSeparation)
point_to_segment_distance: Compute the closest point on the segment a-b to the target q.
rotate_inertia: Rotate a central inertia tensor by a quaternion. (math_internal.h: b3RotateInertia)
rotate_vector: Rotate a vector.
round_down_float
round_up_float
safe_scale: Create a safe scaling value for scaling collision. This allows negative scale, but keeps scale sufficiently far from zero.
scalar_triple_product: Scalar triple product a · (b × c). (math_internal.h: b3ScalarTripleProduct)
segment_distance: Compute the closest points on two line segments.
sign: Component-wise -1 or 1 (1 if zero).
signed_volume: Negative if p is below the triangle v1-v2-v3. (math_internal.h: b3SignedVolume)
sin: @deprecated
skew: Skew-symmetric cross-product matrix. (math_internal.h: b3Skew)
solve2: Solve A * x = b for a 2-by-2 matrix. Assumes positive semi-definite. (math_internal.h: b3Solve2)
solve3: Solve a matrix equation. @return inv(m) * a
sphere_inertia: Solid sphere inertia about its center. (math_functions.c: b3SphereInertia)
steiner: Get the inertia tensor of an offset point. https://en.wikipedia.org/wiki/Parallel_axis_theorem
sub: Vector subtraction.
sub2: 2D vector subtraction. (math_internal.h: b3Sub2)
sub_mm: Matrix subtraction. @return a - b
sub_pos: a - b, demoted to float. The primary precision boundary operation.
test_bounds_overlap: Test overlap between two AABBs given as min/max corners. (simd.h: b3TestBoundsOverlap)
test_bounds_ray_overlap: Test a ray for edge separation with an AABB (Gino, p80). (simd.h: b3TestBoundsRayOverlap)
test_bounds_triangle_overlap: Test overlap between an AABB (center + extent) and a triangle. (simd.c: b3TestBoundsTriangleOverlap)
to_pos: Convert a vector to a world position.
to_relative_transform: Shift a world transform into the frame of a base position.
to_vec3: Lossy conversion of a world position to a float vector.
transform_plane: Transform a plane by a rigid transform. (math_internal.h: b3TransformPlane)
transform_point: Transform a point.
transform_world_point: Transform a local point to a world position. Rotation in float, translation in double.
transpose: Matrix transpose.
unwind_angle: Convert any angle into the range [-pi, pi].

Type Aliases§

Pos
WorldTransform