Skip to main content

Module physics3d

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, and overlap_aabb.
  • shapes, gjk_epa, & manifold: PGA [Motor] support mappings, zero-heap GJK/EPA narrowphase, and persistent 4-point ContactManifold3D with 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), and ArticulatedRagdoll.
  • 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 [Motor] Joint Constraints (joints.rs).
manifold
Persistent 4-Point Contact Manifold with Warm-Starting (manifold.rs).
query
Backwards-compatible query module 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]).
ArticulatedRagdoll
Zero-heap articulated ragdoll controller for up to MAX_LIMBS bones.
BallMotorJoint
Spherical ball-and-socket joint locking two local anchor points in world space.
BotanicalImpactOutcome
Telemetry returned by rigid-body ↔ botanical metamer impact coupling.
BroadphaseBvh
Zero-heap dynamic broadphase BVH with fat-AABB hysteresis.
BvhLeafEntry
Leaf entry in BroadphaseBvh.
ContactManifold3D
Persistent 4-point 3D contact manifold between body_a and body_b.
ContactPoint3D
A single contact point inside a ContactManifold3D.
DrivenSpring
Stiffness and damping per unit mass: stiffness * (target - position) - damping * velocity.
FixedMotorJoint
Rigid weld joint preserving a fixed relative PGA [Motor] offset from body_a to body_b.
FractureOutcome3D
Result of splitting a RigidBody3D along a principal tensile stress cleavage plane.
HydroCouplingOutcome
Telemetry returned by two-way hydrodynamic coupling.
NarrowphaseContact
Result of a narrowphase contact query between two 3D colliders.
ODEState4D
4-state ODE snapshot.
RagdollLimbBinding
Bone-to-rigid-body mapping entry inside an ArticulatedRagdoll.
RayHit3D
Hit result returned by cast_ray.
RevoluteMotorJoint
1-DOF revolute hinge joint with angular limits and optional motor drive.
RigidBody3D
3D rigid body with PGA [Motor] pose and physical properties (HotZeroHeap).
Rk4Integrator4D
Zero-heap 4th-order Runge–Kutta ODE integrator with fixed [f64; 4] state.
ShapeCastHit3D
Hit result returned by cast_sphere and cast_capsule.
SoilCouplingOutcome
Telemetry returned by two-way soil-rigid-body coupling.
SpringState
1D spring position and velocity state.
SpringSuspensionJoint
Compliant linear suspension strut connecting body_a (chassis) and body_b (wheel/bogie).
SupportVertex
Minkowski difference support vertex $v = S_A(\mathbf{d}) - S_B(-\mathbf{d})$.
ThermalTargets
Two-channel driven thermal reservoir targets and relaxation rates ($s^{-1}$).

Enums§

ColliderShape3D
Unified 3D collider shape supporting analytical primitives, convex hulls, and analytical SDFs.
MotorJoint3D
Unified 6-DOF PGA [Motor] joint enum.
RagdollMode
Operational mode of an ArticulatedRagdoll.
ResponseOdeError
Error type returned by Rk4Integrator4D, step_spring, and step_thermal.
RigidBodyType3D
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 ConvexHull collider.
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) along dir up to max_dist by sweeping 3 axial proxy spheres (bottom hemisphere, center, top hemisphere).
cast_ray
Casts a 3D ray through a BroadphaseBvh and collider slice, returning the closest RayHit3D.
cast_sphere
Casts a sphere of radius along dir up to max_dist by inflating target primitives by radius.
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_idx in a MetamerPlantGraph.
couple_rigid_body_with_hydro
Applies two-way 3D Archimedes buoyancy, wave-normal righting torque, and quadratic fluid drag between a RigidBody3D and a SimdGerstnerSpectrum wavefield.
couple_rigid_body_with_soil
Applies two-way geotechnical force coupling between a RigidBody3D (wheel, foot, boulder, or chassis) and a SoilMechanicsProfile.
evaluate_and_fracture_body
Evaluates whether an impact impulse impact_impulse_ns over contact_area_m2 fractures body, and if $\sigma = J / A \ge \text{tensile_strength}$, partitions the collider along the cleavage plane using evaluate_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, or None if 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 SdfPrimitive in 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 ColliderShape3D transformed by motor.
solve_motor_joint_xpbd
Solves a single MotorJoint3D constraint over bodies for substep dt.
step_spring
Steps a DrivenSpring over dt (0.0..=0.05 s), substepped at $\le 1/240$ s via Rk4Integrator4D.
step_thermal
Steps two thermal channels toward targets over dt (0.0..=0.05 s) via Rk4Integrator4D.
step_xpbd_world
Steps a slice of RigidBody3D bodies, contact manifolds, and MotorJoint3D constraints by one fixed timestep dt (typically $1/64 = 0.015625\text{ s}$) using substeps XPBD iterations.

Type Aliases§

ResponseOdeResult
Result alias for ODE response kernels.