Physics Engine Integration
Relevant source files
The following files were used as context for generating this wiki page:
Physics Engine Integration provides a refinement layer for human pose estimation by enforcing anatomical and temporal consistency on keypoint data. The system consumes 17-keypoint skeletal data derived from WiFi Channel State Information (CSI) and applies physical constraints to eliminate jitter and anatomically impossible movements.
This module resides within the Neural Network Layer and CSI Processing Layer of the RuView architecture. It acts as a post-processing stage after initial inference to ensure that the estimated poses adhere to human biomechanical limits and smooth trajectories over time.
Sources: plans/overview.md, plugins/ruview/skills/ruview-applications/SKILL.md
Architecture and Layering
The physics engine operates as a middle-tier service between the raw neural network output and the final application-facing API. It utilizes a modular constraint system to process skeletal frames.
The diagram shows the data flow from raw signal acquisition to the physics-refined pose output distributed to user interfaces.
Sources: plans/overview.md, plans/phase1-specification/functional-spec.md
Component Responsibilities
| Component | Responsibility | Relevant Files |
|---|---|---|
| Physics Engine | Manages the simulation loop and skeletal state updates. | engine.rs |
| Temporal Constraints | Enforces velocity and acceleration bounds to reduce jitter. | temporal.rs |
| Joint Limits | Prevents hyperextension and anatomically invalid bone angles. | joint_limit.rs |
| Pose Tracker | Maintains persistent IDs and applies Kalman filtering. | pose_tracker.rs |
Sources: v2/crates/wifi-densepose-physics/src/engine.rs, plugins/ruview/skills/ruview-applications/SKILL.md
Core Processing Logic
The integration applies two primary categories of physical refinement: skeletal validity and temporal stability.
Skeletal Validity and Joint Limits
The system identifies 24 anatomical regions and 17 major body keypoints. The joint_limit.rs module validates the angular relationship between connected bones (e.g., forearm and upper arm). If the neural network predicts a joint angle that exceeds human range of motion (ROM), the engine clamps the keypoint position to the nearest valid physical coordinate.
Sources: v2/crates/wifi-densepose-physics/src/constraints/joint_limit.rs, plans/phase1-specification/functional-spec.md:126-135
Temporal Consistency and Smoothing
To prevent "teleportation" or high-frequency jitter common in RF sensing, the temporal.rs module applies motion models.
- Velocity Capping: The engine calculates the distance traveled between frames. If the velocity exceeds a threshold (e.g., >5m/s for human movement), the engine assumes a detection error and interpolates the position.
- Kalman Filtering: The system uses Kalman filters for position prediction, which helps maintain track stability during temporary occlusions (e.g., when a person is behind a heavy obstacle).
- Trajectory Smoothing: Temporal filtering stabilizes trajectories, ensuring smooth transitions for UI rendering at 10-30 FPS.
The sequence diagram illustrates how the Physics Engine coordinates between anatomical validation and temporal smoothing before outputting a final frame.
Sources: v2/crates/wifi-densepose-physics/src/constraints/temporal.rs, plans/phase1-specification/functional-spec.md:144-155
Implementation in the Sensing Pipeline
The physics engine is integrated into the wifi-densepose-sensing-server and ruvsense modules. It maintains a persistent field model and pose tracker to handle multi-person scenarios (up to 5 individuals).
- Frame Ingestion: The engine receives raw spatial features from the upsampling branch of the neural network.
- Constraint Iteration: The engine iterates through the skeletal tree, applying
joint_limitchecks from the torso outwards to the extremities. - State Integration: The
engine.rsmodule updates the global state of the environment, integrating new measurements with predicted trajectories. - Anomaly Detection: The system flags physically impossible signal patterns as potential adversarial detections.
Sources: v2/crates/wifi-densepose-physics/src/engine.rs, plugins/ruview/skills/ruview-advanced-sensing/SKILL.md
Performance Requirements
The physics refinement layer must operate within strict latency bounds to maintain real-time performance.
- Processing Latency: Post-processing and tracking must complete in less than 20ms.
- Sampling Rate: The engine supports input rates between 10Hz and 30Hz.
- Accuracy: The goal is to maintain >85% pose estimation accuracy while reducing ID switching during occlusions.
Sources: plans/phase1-specification/functional-spec.md:218-228, plans/phase1-specification/system-requirements.md:73-82
Summary
Physics Engine Integration ensures that WiFi-based human sensing produces reliable, anatomically correct skeletal data. By combining joint limit enforcement in joint_limit.rs with temporal smoothing in temporal.rs, the system transforms noisy RF-derived keypoints into stable trajectories suitable for healthcare, retail, and security applications. This integration is critical for maintaining high Average Precision (AP@50) and low end-to-end latency in the RuView platform.