Module physics3d
Expand description
Unified Analytical SDF + B-Rep 3D Physics & ODE Response Engine (physics3d).
Provides etalon-sim’s Tier-1 (HotZeroHeap) 3D rigid-body, SDF, joint, fracture,
continuum-coupling, and RK4 ODE response physics engine:
sdf_collider: Exact analytical SDF evaluation (Sphere,RoundedBox,Capsule,Torus,SmoothUnionPair) with tetrahedron gradient normals $\nabla\text{sdf}(\mathbf{x})$.broadphase_bvh,query_ray, &query_sweep: Dynamic fat-AABB BVH (BroadphaseBvh),cast_ray(sphere-tracing + Möller–Trumbore),cast_sphere,cast_capsule, andoverlap_aabb.shapes,gjk_epa, &manifold: PGA [Motor] support mappings, zero-heap GJK/EPA narrowphase, and persistent 4-pointContactManifold3Dwith warm-starting.fracture_csg: Principled tensile stress-cleavage dynamic fracture (evaluate_and_fracture_body) conserving linear and angular momentum.xpbd_solver,joints, &ragdoll: 64 Hz deterministic XPBD rigid-body solver, 6-DOF PGA [Motor] joints (BallMotorJoint,RevoluteMotorJoint,FixedMotorJoint,SpringSuspensionJoint), andArticulatedRagdoll.continuum_bridge: Two-way force coupling with geomechanics, hydrodynamics, and botanical FSPM metamers.response_ode: Zero-heap 4D RK4 driven spring (step_spring) and thermal relaxation (step_thermal) ODE kernels.
Modules§
- broadphase_
bvh - Zero-Heap Dynamic Broadphase BVH with Fat-AABB Hysteresis (
broadphase_bvh.rs). - continuum_
bridge - Two-Way Rigid-Body ↔ Continuum Physics Coupling (
continuum_bridge.rs). - fracture_
csg - Principled Stress-Cleavage Dynamic Fracture (
fracture_csg.rs). - gjk_epa
- Zero-Heap GJK / EPA & Analytical SDF Narrowphase (
gjk_epa.rs). - joints
- 6-DOF PGA
MotorJoint Constraints (joints.rs). - manifold
- Persistent 4-Point Contact Manifold with Warm-Starting (
manifold.rs). - query
- Backwards-compatible
querymodule alias re-exporting both ray and swept shape queries. - query_
ray - 3D Spatial Raycasting (
query_ray.rs). - query_
sweep - 3D Swept Shape-Casting & Volume Overlap Queries (
query_sweep.rs). - ragdoll
- Articulated Ragdoll Controller (
ragdoll.rs). - response_
ode - Zero-Heap 4D RK4 Driven Spring & Thermal ODE Response Kernel (
response_ode.rs). - sdf_
collider - Analytical SDF Collider & Tetrahedron Gradient Normal Evaluator (
sdf_collider.rs). - shapes
- 3D Collider Shapes, Support Mappings, AABBs & Inertia Tensors (
shapes.rs). - xpbd_
solver - 64 Hz Deterministic XPBD Rigid-Body Solver (
xpbd_solver.rs).
Structs§
- Aabb3D
- 3D Axis-Aligned Bounding Box (
[min_x, min_y, min_z]..[max_x, max_y, max_z]). - Articulated
Ragdoll - Zero-heap articulated ragdoll controller for up to
MAX_LIMBSbones. - Ball
Motor Joint - Spherical ball-and-socket joint locking two local anchor points in world space.
- Botanical
Impact Outcome - Telemetry returned by rigid-body ↔ botanical metamer impact coupling.
- Broadphase
Bvh - Zero-heap dynamic broadphase BVH with fat-AABB hysteresis.
- BvhLeaf
Entry - Leaf entry in
BroadphaseBvh. - Contact
Manifold3D - Persistent 4-point 3D contact manifold between
body_aandbody_b. - Contact
Point3D - A single contact point inside a
ContactManifold3D. - Driven
Spring - Stiffness and damping per unit mass:
stiffness * (target - position) - damping * velocity. - Fixed
Motor Joint - Rigid weld joint preserving a fixed relative PGA
Motoroffset frombody_atobody_b. - Fracture
Outcome3D - Result of splitting a
RigidBody3Dalong a principal tensile stress cleavage plane. - Hydro
Coupling Outcome - Telemetry returned by two-way hydrodynamic coupling.
- Narrowphase
Contact - Result of a narrowphase contact query between two 3D colliders.
- ODEState4D
- 4-state ODE snapshot.
- Ragdoll
Limb Binding - Bone-to-rigid-body mapping entry inside an
ArticulatedRagdoll. - RayHit3D
- Hit result returned by
cast_ray. - Revolute
Motor Joint - 1-DOF revolute hinge joint with angular limits and optional motor drive.
- Rigid
Body3D - 3D rigid body with PGA
Motorpose and physical properties (HotZeroHeap). - Rk4Integrator4D
- Zero-heap 4th-order Runge–Kutta ODE integrator with fixed
[f64; 4]state. - Shape
Cast Hit3D - Hit result returned by
cast_sphereandcast_capsule. - Soil
Coupling Outcome - Telemetry returned by two-way soil-rigid-body coupling.
- Spring
State - 1D spring position and velocity state.
- Spring
Suspension Joint - Compliant linear suspension strut connecting
body_a(chassis) andbody_b(wheel/bogie). - Support
Vertex - Minkowski difference support vertex $v = S_A(\mathbf{d}) - S_B(-\mathbf{d})$.
- Thermal
Targets - Two-channel driven thermal reservoir targets and relaxation rates ($s^{-1}$).
Enums§
- Collider
Shape3D - Unified 3D collider shape supporting analytical primitives, convex hulls, and analytical SDFs.
- Motor
Joint3D - Unified 6-DOF PGA
Motorjoint enum. - Ragdoll
Mode - Operational mode of an
ArticulatedRagdoll. - Response
OdeError - Error type returned by
Rk4Integrator4D,step_spring, andstep_thermal. - Rigid
Body Type3D - Kinematic / dynamic simulation class of a 3D rigid body.
- SdfPrimitive
- Analytical SDF primitive shapes evaluated in $O(1)$ local coordinates.
Constants§
- MAX_
CONVEX_ HULL_ POINTS - Maximum number of vertices in an inline zero-heap
ConvexHullcollider. - MAX_
MANIFOLD_ CONTACTS - Alias for
MAX_MANIFOLD_POINTS. - MAX_
MANIFOLD_ POINTS - Maximum number of persistent contact points in a single 3D manifold.
- PERSISTENT_
CONTACT_ THRESHOLD_ SQ - Distance squared threshold ($m^2$) for matching a new contact point to a cached warm-start point.
Traits§
- ODEFunction4D
- 4-state ODE derivative trait for
Rk4Integrator4D.
Functions§
- cast_
capsule - Casts a vertical 3D capsule (
radius,half_height) alongdirup tomax_distby sweeping 3 axial proxy spheres (bottom hemisphere, center, top hemisphere). - cast_
ray - Casts a 3D ray through a
BroadphaseBvhand collider slice, returning the closestRayHit3D. - cast_
sphere - Casts a sphere of
radiusalongdirup tomax_distby inflating target primitives byradius. - compute_
narrowphase_ contact - Evaluates narrowphase contact between two 3D colliders (
HotZeroHeap). - couple_
rigid_ body_ with_ botanical_ stem - Couples a 3D rigid-body impact against
metamer_idxin aMetamerPlantGraph. - couple_
rigid_ body_ with_ hydro - Applies two-way 3D Archimedes buoyancy, wave-normal righting torque, and quadratic fluid drag
between a
RigidBody3Dand a [SimdGerstnerSpectrum] wavefield. - couple_
rigid_ body_ with_ soil - Applies two-way geotechnical force coupling between a
RigidBody3D(wheel, foot, boulder, or chassis) and aSoilMechanicsProfile. - evaluate_
and_ fracture_ body - Evaluates whether an impact impulse
impact_impulse_nsovercontact_area_m2fracturesbody, and if $\sigma = J / A \ge \text{tensile_strength}$, partitions the collider along the cleavage plane usingevaluate_stress_cleavage_partition. - evaluate_
smooth_ minimum_ sdf - Polynomial smooth-minimum blending (SDF implicit fillet) between two distances $d_1$ and $d_2$: $smin(d_1, d_2, r) = \min(d_1, d_2) - \frac{h^2}{4r}$ where $h = \max(r - |d_1 - d_2|, 0)$.
- evaluate_
stress_ cleavage_ partition - Evaluate structural fracture criterion under principal tensile stress $\sigma_1$.
Returns
Some(true/false)if $\sigma_1 \ge \sigma_{\text{crit}}$ indicating the cleavage partition half-space sign, orNoneif below threshold. - gjk_
intersect - Zero-heap GJK intersection test on a fixed 4-vertex stack simplex.
- overlap_
aabb - Convenience wrapper returning all collider IDs overlapping
query_aabb. - ray_
sdf_ local - Sphere-tracing raycast against an analytical
SdfPrimitivein local space. - ray_
sphere_ local - Analytical ray-sphere intersection in local space (sphere centered at origin).
- ray_
triangle_ moller_ trumbore - Möller–Trumbore ray-triangle intersection test (
HotZeroHeap). - raycast_
collider - Raycast against a single
ColliderShape3Dtransformed bymotor. - solve_
motor_ joint_ xpbd - Solves a single
MotorJoint3Dconstraint overbodiesfor substepdt. - step_
spring - Steps a
DrivenSpringoverdt(0.0..=0.05s), substepped at $\le 1/240$ s viaRk4Integrator4D. - step_
thermal - Steps two thermal channels toward
targetsoverdt(0.0..=0.05s) viaRk4Integrator4D. - step_
xpbd_ world - Steps a slice of
RigidBody3Dbodies, contact manifolds, andMotorJoint3Dconstraints by one fixed timestepdt(typically $1/64 = 0.015625\text{ s}$) usingsubstepsXPBD iterations.
Type Aliases§
- Response
OdeResult - Result alias for ODE response kernels.