diff --git a/docs/user-guide.md b/docs/user-guide.md index 4e30a62..1dff5ad 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -79,7 +79,7 @@ cd wifi-densepose/rust-port/wifi-densepose-rs # Build cargo build --release -# Verify (runs 542+ tests) +# Verify (runs 700+ tests) cargo test --workspace ``` @@ -452,15 +452,17 @@ docker run --rm \ --train --dataset /data --epochs 100 --export-rvf /output/model.rvf ``` -The pipeline runs 8 phases: +The pipeline runs 10 phases: 1. Dataset loading (MM-Fi `.npy` or Wi-Pose `.mat`) -2. Subcarrier resampling (114->56 or 30->56) -3. Graph transformer construction (17 COCO keypoints, 16 bone edges) -4. Cross-attention training (CSI features -> body pose) -5. Composite loss optimization (MSE + CE + UV + temporal + bone + symmetry) -6. SONA adaptation (micro-LoRA + EWC++) -7. Sparse inference optimization (hot/cold neuron partitioning) -8. RVF model packaging +2. Hardware normalization (Intel 5300 / Atheros / ESP32 -> canonical 56 subcarriers) +3. Subcarrier resampling (114->56 or 30->56 via Catmull-Rom interpolation) +4. Graph transformer construction (17 COCO keypoints, 16 bone edges) +5. Cross-attention training (CSI features -> body pose) +6. **Domain-adversarial training** (MERIDIAN: gradient reversal + virtual domain augmentation) +7. Composite loss optimization (MSE + CE + UV + temporal + bone + symmetry) +8. SONA adaptation (micro-LoRA + EWC++) +9. Sparse inference optimization (hot/cold neuron partitioning) +10. RVF model packaging ### Step 3: Use the Trained Model @@ -470,6 +472,27 @@ The pipeline runs 8 phases: Progressive loading enables instant startup (Layer A loads in <5ms with basic inference), with full model loading in the background. +### Cross-Environment Adaptation (MERIDIAN) + +Models trained in one room typically lose 40-70% accuracy in a new room due to different WiFi multipath patterns. The MERIDIAN system (ADR-027) solves this with a 10-second automatic calibration: + +1. **Deploy** the trained model in a new room +2. **Collect** ~200 unlabeled CSI frames (10 seconds at 20 Hz) +3. The system automatically generates environment-specific LoRA weights via contrastive test-time training +4. No labels, no retraining, no user intervention + +MERIDIAN components (all pure Rust, +12K parameters): + +| Component | What it does | +|-----------|-------------| +| Hardware Normalizer | Resamples any WiFi chipset to canonical 56 subcarriers | +| Domain Factorizer | Separates pose-relevant from room-specific features | +| Geometry Encoder | Encodes AP positions (FiLM conditioning with DeepSets) | +| Virtual Augmentor | Generates synthetic environments for robust training | +| Rapid Adaptation | 10-second unsupervised calibration via contrastive TTT | + +See [ADR-027](adr/ADR-027-cross-environment-domain-generalization.md) for the full design. + --- ## RVF Model Containers @@ -630,7 +653,7 @@ No. Run `docker run -p 3000:3000 ruvnet/wifi-densepose:latest` and open `http:// No. Consumer WiFi exposes only RSSI (one number per access point), not CSI (56+ complex subcarrier values per frame). RSSI supports coarse presence and motion detection. Full pose estimation requires CSI-capable hardware like an ESP32-S3 ($8) or a research NIC. **Q: How accurate is the pose estimation?** -Accuracy depends on hardware and environment. With a 3-node ESP32 mesh in a single room, the system tracks 17 COCO keypoints. The core algorithm follows the CMU "DensePose From WiFi" paper ([arXiv:2301.00250](https://arxiv.org/abs/2301.00250)). See the paper for quantitative evaluations. +Accuracy depends on hardware and environment. With a 3-node ESP32 mesh in a single room, the system tracks 17 COCO keypoints. The core algorithm follows the CMU "DensePose From WiFi" paper ([arXiv:2301.00250](https://arxiv.org/abs/2301.00250)). The MERIDIAN domain generalization system (ADR-027) reduces cross-environment accuracy loss from 40-70% to under 15% via 10-second automatic calibration. **Q: Does it work through walls?** Yes. WiFi signals penetrate non-metallic materials (drywall, wood, concrete up to ~30cm). Metal walls/doors significantly attenuate the signal. The effective through-wall range is approximately 5 meters. @@ -648,7 +671,7 @@ The Rust implementation (v2) is 810x faster than Python (v1) for the full CSI pi ## Further Reading -- [Architecture Decision Records](../docs/adr/) - 24 ADRs covering all design decisions +- [Architecture Decision Records](../docs/adr/) - 27 ADRs covering all design decisions - [WiFi-Mat Disaster Response Guide](wifi-mat-user-guide.md) - Search & rescue module - [Build Guide](build-guide.md) - Detailed build instructions - [RuVector](https://github.com/ruvnet/ruvector) - Signal intelligence crate ecosystem