Module skeletal
Expand description
Zero-Heap Skeletal Animation, ABSM, Blend Spaces, Motor IK & Dual-Quaternion Skinning (skeletal).
Unifies:
pga_f64:f64PGA $\mathcal{G}_{3,0,1}$MotorandMotorBivector(log,exp,sclerp) with bidirectional conversion tocrate::spatial_math::pga::Motor(f32).pose,skin,gpu_skin,gpu_morph,ik_motor: caller-buffered pose sampling, 4-influence CPU/GPU dual-quaternion skinning, ontogenetic morph targets, and analytical/FABRIK IK.blend_space_1d,blend_space_2d(re-exported underblend_space): 1D & 2D Bowyer–Watson Delaunay blend spaces.absm_types,absm_machine,root_motion(re-exported underabsm): multi-layer bone-masked Animation Blending State Machine with timeline signals and ontogenetic posture modulation.transform_hierarchy,clip_state_machine(also accessible underinertial_skeleton):Transform3D,ZeroHeapSkeleton,AnimationStateMachine, and direct dual-quaternion GPU palette export.
Modules§
- absm
- Submodule namespace preserving
skeletal::absm::*import paths. - absm_
machine - Zero-Heap Multi-Layer Animation Blending State Machine Evaluator (
absm_machine.rs). - absm_
types - Zero-Heap Animation Blending State Machine Types (
absm_types.rs). - activity
- Bounded visual activity timeline, independent of campaign time and rendering.
- authoring
- Bounded skin influence authoring and seam remapping into caller buffers.
- blend_
space - Submodule namespace preserving
skeletal::blend_space::*import paths. - blend_
space_ 1d - Zero-Heap 1D Animation Blend Space (
blend_space_1d.rs). - blend_
space_ 2d - Zero-Heap 2D Delaunay Animation Blend Space (
blend_space_2d.rs). - clip_
state_ machine - Zero-Heap Clip State Machine, Layer Blending & Sim Blend Space (
clip_state_machine.rs). - cosserat_
rod - Regime II & V: Geometrically Exact Discrete Cosserat Rod Solver (
cosserat_rod.rs). - dca_
multibody - Regime I: Articulated Multibody Endoskeleton Solver (
dca_multibody.rs). - exoskeletal_
cuticle - Regime III: Inverted Cuticular Exoskeleton Solver (
exoskeletal_cuticle.rs). - gpu_
morph - GPU Morph Target (Blend Shape) & Ontogenetic Deformation Bridge (
gpu_morph.rs). - gpu_
skin - Hardware GPU PGA
MotorDual-Quaternion Skinning Palette & Vertex Shader Bridge. - ik_
motor - Zero-Heap Analytical Two-Bone Motor IK & Constrained Motor FABRIK (
ik_motor.rs). - inertial_
skeleton - Submodule namespace grouping
transform_hierarchyandclip_state_machine. - mobility_
risk_ eval - BIO-WP-10: Coupled Mobility, Effort Reserve, Gait Stability & Bone Fracture Risk Evaluator.
- pga_f64
- 3D Projective Geometric Algebra (PGA $\mathcal{G}_{3,0,1}$) / Dual Quaternion Motor Algebra (
f64). - player
- Cold resident allocation and allocation-free visual playback lifecycle.
- pose
- root_
motion - Loop-Safe Root Motion Extraction & Ontogenetic Posture Modulation (
root_motion.rs). - skin
- time_
policy - Per-invocation sampling policy; the authored clip’s loop declaration and legacy natural-advance behavior are never mutated by an inspection seek.
- transform_
hierarchy - Zero-Heap Skeletal Transform Hierarchy & Dual-Quaternion Bridge (
transform_hierarchy.rs). - vbd_
soft_ tissue - Regime IV: Volumetric Soft Tissue, Fascia & Hydrostatic Skeleton Solver (
vbd_soft_tissue.rs).
Structs§
- Absm
Layer - Single animation layer within an
AbsmMachine. - Absm
Machine - Multi-layer zero-heap Animation Blending State Machine (
AbsmMachine). - Absm
State Node - A state node inside an
super::absm_machine::AbsmLayer. - Absm
Transition - Directed transition edge between two states in an
super::absm_machine::AbsmLayer. - Animation
Clip - Fixed-capacity skeletal animation clip (
HotZeroHeap). - Animation
Event - Discrete event marker embedded in an
AnimationCliptimeline. - Animation
Signal - Timeline event emitted when an animation playhead crosses a normalized trigger timestamp.
- Animation
State Machine - Zero-heap animation state machine controller.
- Apodeme
Actuator - Internal apodeme muscle fiber bundle attached inside the cuticular shell.
- Bicondylar
Hinge - Dual-pin dicondylic arthrodial hinge between parent and child sclerite shells.
- Blend
Point1D - A single sample point inside a
BlendSpace1D. - Blend
Point2D - A 2D parameter sample point inside a
BlendSpace2D. - Blend
Sample2D - Result of sampling a
BlendSpace2Dat a 2D parameter coordinate. - Blend
Space1D - Fixed-capacity 1D animation blend space (
MAX_POINTSdefault8). - Blend
Space2D - Fixed-capacity 2D Delaunay animation blend space (
MAX_POINTS = 16,MAX_TRIS = 32). - Blend
Triangle - A Delaunay triangle indexing 3 points in
BlendSpace2D::points. - Body
Densitometry Inertia - Tissue densitometry and geometry parameters used to derive BMD-scaled 6x6 spatial inertia.
- Body
FitSpec - Neutral body-fit specification applied in bind/CCF space before orbit-frame normalisation.
- Bone
Fracture Load Evaluation - Computed bone yield capacity and Structural Factor of Risk $\Phi_b$.
- Bone
Fracture Load Input - Input parameters for structural bone fracture load evaluation.
- Bone
Layer Mask - 128-bit bone mask (1 bit per joint up to
MAX_JOINTS = 128). - Bone
Mask64 - 64-bit bone mask (1 bit per bone in
ZeroHeapSkeleton). - Bone
Track - Fixed-capacity keyframe track for a single bone (
HotZeroHeap). - Clip
- Clip
Record - Metadata record describing an animation clip span in caller-owned track/key tables.
- Cosserat
Element - Material-frame segment state connecting node
ito nodei + 1. - Cosserat
Element Gpu - GPU-aligned 64-byte Cosserat element buffer matching
COSSERAT_ROD_WGSL. - Cosserat
Environment - Environmental forcing parameters for Cosserat rods (gravity, fluid/wind, light direction).
- Cosserat
Node - Centerline node state for a discrete Cosserat rod.
- Coupled
Mobility Fracture Summary - Coupled whole-body summary combining mobility reserve, dynamic balance, and fracture risk.
- Cuticle
Sclerite - Exterior load-bearing cuticular sclerite shell.
- DcaAssembly
Node Gpu - GPU-aligned 128-byte binary-tree DCA assembly node matching
DCA_MULTIBODY_WGSL. - DcaBody
Gpu - GPU-aligned 64-byte per-body state record matching
DCA_MULTIBODY_WGSL. - DcaBody
Node - Rigid-body articulated node for Regime I ABA/DCA dynamics.
- Eont
Posture Config - Ontogenetic and metabolic posture/cadence modulator (
EONT1compatible). - ExoHinge
Gpu - GPU-aligned 64-byte dicondylic hinge + hemolymph state matching
EXOSKELETAL_CUTICLE_WGSL. - Gait
Stability Evaluation - Computed Hof $\text{XCoM}$ and Margin of Stability evaluation.
- Gait
Stability Input - Input parameters for Hof’s dynamic gait / posture Margin of Stability evaluation.
- GpuInstance
Morph Weights - 48-byte per-instance morph weight uniform/storage record uploaded to the GPU.
- GpuJoint
Motor Pair - 64-byte GPU storage record per joint storing both current-frame and previous-frame
skinning PGA
Motors ($M_{\text{skin}, j} = M_{\text{world}, j} \circ M_{\text{inv_bind}, j}$). - GpuMorph
Delta - 32-byte GPU storage record holding a single morph target’s per-vertex position and normal delta.
- GpuSkinned
Vertex - 24-byte static vertex skinning attribute (
JOINTS_0+WEIGHTS_0) uploaded once per mesh. - Hemolymph
Hydraulics - Internal hemolymph / coelomic hydraulic chamber driving joint extension.
- Joint
- Joint
Mobility Evaluation - Computed joint effort reserve and capacity evaluation.
- Joint
Mobility Input - Input parameters for a single joint actuator mobility/effort evaluation.
- Key
- Keyframe3D
- Single keyframe sample for a
BoneTrack. - Loop
Closure Constraint - Closed kinematic loop constraint (ribcage, radius-ulna, pelvic ring).
- Motor
- A 3D PGA Motor (even multivector / unit dual quaternion) in
f64precision. Real part $R = (r_w, r_x, r_y, r_z)$, Dual part $D = (d_w, d_x, d_y, d_z)$. - Motor
Bivector - Lie algebra $\mathfrak{se}(3)$ screw bivector (rotation axis/angle + translation along screw axis).
- Ontogenetic
State Header - Domain-neutral 40-byte ontogenetic and metabolic state header (
EONT1layout). - Playback
Receipt - Root
Motion Delta - Frame-to-frame root motion displacement extracted from the skeleton’s root joint.
- Root
Motion Extractor - Extracts continuous root motion from the root bone (eliminating loop-wrap teleport spikes)
and locks horizontal
(x, z)drift on the visual skeleton. - Signal
Queue - Fixed-capacity FIFO ring buffer for
AnimationSignalevents (HotZeroHeap). - Signal
Trigger - Authored signal trigger attached to an animation state.
- SimAnimation
Signal - Fixed-capacity animation signal event and ring buffer.
- SimBlend
Point2D - 2D blend space sample point for
Transform3Dposes. - SimBlend
Space2D - Zero-heap 2D triangle blend space for
Transform3Dskeletal poses. - SimRoot
Motion Delta - Root motion displacement extracted from bone 0.
- SimRoot
Motion Extractor - Loop-safe root motion extractor for
Transform3Dskeletons. - SimSignal
Queue - Skeletal
Counts - Validated element counts and encoded payload size for skeletal admission budgeting.
- Skeletal
Player - Buffers are allocated once on validated scene admission, never on advance. Geometry stays in the authored bind frame; output can receive a uniform orbit transform without altering the rig or losing attachment alignment.
- Skeletal
RigDescriptor - Direct borrowed rig descriptor implementing
SkeletalSectionSource. - Skin
Weight - Track
- Transform3D
- 3D affine transform representation (
rotationstored as[x, y, z, w]). - TwoBone
IkResult - Output receipt for
solve_two_bone_motor_ik_zero_heap. - VbdTet
Element - Constitutive hyperelastic + active Hill muscle + dermal strain-hardening parameters per tet.
- VbdVertex
- Vertex state for graph-colored Vertex Block Descent soft-tissue simulation.
- VbdVertex
Gpu - GPU-aligned 32-byte VBD vertex record matching
VBD_SOFT_TISSUE_WGSL. - Zero
Heap Skeleton - Fixed-capacity skeletal rig (
MAX_BONES = 64).
Enums§
- Absm
Parameter - Typed parameter value driving ABSM transitions and blend spaces.
- Absm
State Source - Motion generator source for a state inside an
super::absm_machine::AbsmLayer. - Anatomic
Bone Site - Anatomic site selecting Morgan, Bayraktar & Keaveny (2003) / Carter & Hayes (1977) power laws.
- Biological
SexBasis - Biological substrate sex basis for age-trajectory and neuromuscular reference scaling.
- Fracture
Callus Stage - Mechanobiological fracture healing stage (Claes & Heigele 1999).
- Joint
Constraint - Angular constraint applied to a joint during
solve_constrained_fabrik_motor_ik_zero_heap. - Layer
Blend Mode - How an ABSM layer combines its output pose with lower layers.
- Layer
Blend Op - Multi-layer skeletal blend mode.
- Leaf
Condition - Atomic predicate for transition evaluation (stack-resident,
Copy). - Player
Error - Pose
Time Policy - Skeletal
Error - Transition
Condition - Zero-heap transition firing condition supporting single predicates and
And/Orcombinators. - Transition
Mode - Animation state machine transition blend mode.
Constants§
- COSSERAT_
ROD_ WGSL - DCA_
MULTIBODY_ WGSL - EXOSKELETAL_
CUTICLE_ WGSL - MAX_
ABSM_ PARAMS - Maximum parameter slots in an
super::absm_machine::AbsmMachine. - MAX_
BONES - Maximum bones supported per skeleton instance (fits in GPU uniform blocks).
- MAX_
COSSERAT_ NODES - MAX_
DCA_ BODIES - MAX_
DCA_ LOOPS - MAX_
EXO_ APODEMES - MAX_
EXO_ SCLERITES - MAX_
GPU_ MORPH_ TARGETS - Maximum morph targets evaluated simultaneously per instance on the GPU.
- MAX_
GPU_ RIG_ JOINTS - Maximum joints supported per GPU skeletal rig palette (
128joints =8 KiBper instance). - MAX_
GPU_ SKELETON_ INSTANCES - Maximum concurrent skeletal instances resident in a single GPU storage buffer.
- MAX_
IK_ CHAIN - Maximum joints in a single constrained FABRIK chain (
HotZeroHeapstack bound). - MAX_
JOINTS - MAX_
KEYS - MAX_
SIGNALS_ PER_ STATE - Maximum signal triggers per animation state.
- MAX_
VBD_ COLORS - MAX_
VBD_ TETS - MAX_
VBD_ VERTICES - MAX_
VERTICES - VBD_
SOFT_ TISSUE_ WGSL
Traits§
- Body
FitSource - Conversion trait allowing host body-fit descriptors (e.g.
AnatomyBodyFit) to configureSkeletalPlayer::set_body_fitwithout reverse crate dependencies. - Skeletal
Section Source - Zero-copy section source abstraction so
SkeletalPlayercan be constructed from.10dSkeletalSectionpayloads or direct in-memory slice descriptors without introducing reverse crate dependencies.
Functions§
- blend_
skeleton_ layer_ zero_ heap - Blends
layer_poseintobase_poseusingmask,op, andweightin[0.0, 1.0](HotZeroHeap). - clip_
view - Build a runtime
Clipview after loading the section into caller-owned arrays. - compose_
palette_ into - Iterative parent-before-child composition and inverse bind application.
globalsdoubles as reusable attachment transforms for tools and clothing. - compute_
darboux_ vector - Computes material Darboux bending/twist vector $\boldsymbol{\Omega}$ between adjacent frames.
- compute_
ontogenetic_ morph_ weights_ from_ header_ zero_ heap - Convenience wrapper extracting
stage,damage_permill, andhydration_permilldirectly from anOntogeneticStateHeader(EntityOntologyMiniHeader). - compute_
ontogenetic_ morph_ weights_ zero_ heap - Computes
GpuInstanceMorphWeightswith zero heap allocations (HotZeroHeap), combining explicit pose/facial blend-shape weights with ontogenetic/metabolic state (damage_permill,hydration_permill, andstageontogenetic factor). - evaluate_
bone_ fracture_ load - Evaluates Structural Factor of Risk $\Phi_b = F_{\text{applied}} / F_{\text{yield}}$ from volumetric BMD, BV/TV, fabric tensor $\mathbf{M}{\text{fabric}}$, mineralization $\mu{\text{min}}$, and 4-stage fracture callus state.
- evaluate_
coupled_ mobility_ and_ fracture_ risk - Evaluates coupled joint mobility effort ($\text{RER}_j$), Hof dynamic stability ($\text{MoS}$),
and bone Structural Factor of Risk ($\Phi_b$) into caller-supplied slices (
HotZeroHeap). - evaluate_
gait_ stability - Evaluates Hof’s Extrapolated Center of Mass ($\text{XCoM}$) and signed Margin of Stability ($\text{MoS}$).
- evaluate_
joint_ mobility - Evaluates $\text{RER}j = |\tau{j,\text{req}}| / \tau_{j,\max}$ for a single joint.
- evaluate_
morph_ deltas_ zero_ heap - Evaluates linear blend-shape morph deltas into caller-supplied vertex position and normal
buffers with zero heap allocations (
HotZeroHeap). - evaluate_
skinning_ motor_ palette_ zero_ heap - Evaluates the GPU skinning
Motorpalette in a single zero-heap pass (HotZeroHeap). - gpu_
shader_ skin_ vertex_ reference - Deterministic software reference implementation of the WGSL vertex shader PGA
Motordual-quaternion skinning kernel (HotZeroHeap). - hemisphere_
align_ motor - Aligns
candidateto the same $S^3$ double-cover hemisphere asreference. - hydrostatic_
cavity_ axial_ force - Computes internal hydrostatic cavity axial thrust $F_{\text{cav}} = P_{\text{cav}} \pi r^2$.
- ontogenetic_
stage_ growth_ factor - Maps a
DevelopmentalStagediscriminant (0..=4) to a normalized ontogenetic growth factor in[0.0, 1.0]. - resolve_
loop_ closures_ zero_ heap - Resolves closed kinematic loop residuals (e.g. ribcage, radius-ulna) via compliant
constraint projection over world body
Motorposes (HotZeroHeap), returning max residual (m). - sample_
blend_ space_ 1d_ zero_ heap - Evaluates a
BlendSpace1Datparamand blends the corresponding clipMotorposes intoout_poseusingMotor::sclerp(HotZeroHeap). - sample_
blend_ space_ 2d_ zero_ heap - Samples a
BlendSpace2Datqueryand blends the 3 enclosing triangle clip poses per joint using barycentricMotor::sclerpwith zero heap allocation (HotZeroHeap). - sample_
pose_ 2d_ zero_ heap - Samples a
SimBlendSpace2Datqueryand blends the 3 enclosing clipTransform3Dposes (HotZeroHeap). - sample_
pose_ into - Samples a local pose, optionally transitioning from a caller-owned pose.
blendis target influence[0, 1]. Missing tracks retain the rig rest pose. Validation finishes before modifying any output. Time is visual, not a game day. - sideways_
fall_ trochanteric_ impact_ force_ n - Estimates sideways-fall trochanteric impact force (N) attenuated by trochanteric soft-tissue padding $h_{\text{troch}}$ and protective stepping reflex attenuation (Robinovitch / Bouxsein).
- skin_
vertices_ gpu_ reference_ into - Batch helper that skins a slice of vertices via
gpu_shader_skin_vertex_referenceinto caller-supplied output slices (HotZeroHeap). - skin_
vertices_ into - Four-influence linear blend skinning of immutable bind geometry. Positions and normals share the same palette. UVs, tangents and material topology are unchanged; tangent reconstruction remains the renderer’s job. No partial writes on malformed influences or inadequate output buffers.
- solve_
aba_ zero_ heap - Solves forward dynamics in $O(N)$ using Featherstone’s Articulated-Body Algorithm (
HotZeroHeap). - solve_
constrained_ fabrik_ motor_ ik_ zero_ heap - Solves multi-joint Constrained Forward-And-Backward Reaching Inverse Kinematics (FABRIK)
directly on a chain of up to
MAX_IK_CHAIN = 16PGAMotors with zero heap allocations (HotZeroHeap). - solve_
dca_ parallel_ chain_ zero_ heap - Solves forward dynamics for a serial chain in $O(\log N)$ balanced binary-tree passes
via Featherstone’s Divide-and-Conquer Articulated-Body Algorithm (
HotZeroHeap). - solve_
two_ bone_ motor_ ik_ zero_ heap - Analytically solves two-bone inverse kinematics (e.g., hip–knee–ankle or shoulder–elbow–wrist)
directly on PGA
Motors using the Law of Cosines and a pole-vector bend plane (HotZeroHeap). - step_
cosserat_ rod_ zero_ heap - Advances a discrete Cosserat rod by
dtseconds with zero heap allocations (HotZeroHeap). - step_
exoskeletal_ cuticle_ zero_ heap - Advances Regime III cuticular sclerite hinges under apodeme torques, hydraulic hemolymph
extension pressure, and coelomic volume conservation (
HotZeroHeap). - step_
vbd_ soft_ tissue_ zero_ heap - Advances Regime IV soft tissue using graph-colored Vertex Block Descent (
HotZeroHeap), returning the mean volume determinant $\det(\mathbf{F})$ across elements. - valid_
motor - Returns
truewhenmis a finite, unit-norm, Plücker-orthogonal PGAMotor. - validate_
joints - Validates topological parent ordering and motor invariants for
joints.
Type Aliases§
- Entity
Ontology Mini Header - Backwards-compatible alias for
OntogeneticStateHeader. - Spatial
Mat6 - 6x6 spatial matrix in row-major
[row][col]layout. - Spatial
Vec6 - 6D spatial motion or force vector
[ang_0, ang_1, ang_2, lin_0, lin_1, lin_2].