From 478d9647acf487bc0cdae4bdfc85a45c5ac563d2 Mon Sep 17 00:00:00 2001 From: ruv Date: Sun, 1 Mar 2026 00:24:57 -0500 Subject: [PATCH] docs: Improve README sections with rich detail, emoji features, and collapsed groups - Add emoji key features table above ToC in plain language - Expand WiFi-Mat section: START triage table, deployment modes, safety guarantees, performance targets - Expand SOTA Signal Processing: math formulas, why-it-matters explanations, processing pipeline order - Expand RVF Container: ASCII structure diagram, 20+ segment types, size examples - Expand Training: 8-phase pipeline table with line counts, best-epoch snapshotting, three-tier strategy table - Collapse Architecture, Testing, Changelog, and Release History sections - Fix date in Meta section (March 2025) - All 22 anchor links and 27 file links verified Co-Authored-By: claude-flow --- README.md | 162 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 120 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 99700c6..cacf9bf 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,22 @@ docker run -p 3000:3000 ruvnet/wifi-densepose:latest --- +## πŸš€ Key Features + +| | Feature | What It Means | +|---|---------|---------------| +| πŸ”’ | **Privacy-First** | Tracks human pose using only WiFi signals β€” no cameras, no video, no images stored | +| ⚑ | **Real-Time** | Analyzes WiFi signals in under 100 microseconds per frame β€” fast enough for live monitoring | +| πŸ’“ | **Vital Signs** | Detects breathing rate (6-30 breaths/min) and heart rate (40-120 bpm) without any wearable | +| πŸ‘₯ | **Multi-Person** | Simultaneously tracks up to 10 people, each with independent pose and vitals | +| 🧱 | **Through-Wall** | WiFi passes through walls, furniture, and debris β€” works where cameras cannot | +| πŸš‘ | **Disaster Response** | Detects trapped survivors through rubble and classifies injury severity (START triage) | +| 🐳 | **One-Command Setup** | `docker pull ruvnet/wifi-densepose:latest` β€” live sensing in 30 seconds, no toolchain needed | +| πŸ“¦ | **Portable Models** | Trained models package into a single `.rvf` file β€” runs on edge, cloud, or browser (WASM) | +| πŸ¦€ | **810x Faster** | Complete Rust rewrite: 54,000 frames/sec pipeline, 132 MB Docker image, 542+ tests | + +--- + ## πŸ“‹ Table of Contents
@@ -122,20 +138,6 @@ WiFi DensePose is MIT-licensed open source, developed by [ruvnet](https://github --- -## πŸš€ Key Features - -| Feature | Description | -|---------|-------------| -| **Privacy-First** | No cameras β€” uses WiFi signals for pose detection | -| **Real-Time** | Sub-100Β΅s/frame (Rust), 11,665 fps vital sign benchmark | -| **Vital Signs** | Contactless breathing (6-30 BPM) and heart rate (40-120 BPM) | -| **Multi-Person** | Simultaneous tracking of up to 10 individuals | -| **Docker Ready** | `docker pull ruvnet/wifi-densepose:latest` (132 MB) | -| **RVF Portable Models** | Single-file `.rvf` containers with progressive loading | -| **542+ Tests** | Comprehensive Rust test suite, zero mocks | - ---- - ## πŸ“‘ Signal Processing & Sensing
@@ -249,12 +251,26 @@ See [ADR-022](docs/adr/ADR-022-windows-wifi-enhanced-fidelity-ruvector.md) and [
🚨 WiFi-Mat: Disaster Response β€” Search & rescue, START triage, 3D localization -| Feature | Description | -|---------|-------------| -| **Vital Signs** | Breathing (4-60 BPM), heartbeat via micro-Doppler | -| **3D Localization** | Position estimation through debris up to 5m | -| **START Triage** | Automatic Immediate/Delayed/Minor/Deceased classification | -| **Real-time Alerts** | Priority-based notifications with escalation | +WiFi signals penetrate non-metallic debris (concrete, wood, drywall) where cameras and thermal sensors cannot reach. The WiFi-Mat module (`wifi-densepose-mat`, 139 tests) uses CSI analysis to detect survivors trapped under rubble, classify their condition using the START triage protocol, and estimate their 3D position β€” giving rescue teams actionable intelligence within seconds of deployment. + +| Capability | How It Works | Performance Target | +|------------|-------------|-------------------| +| **Breathing Detection** | Bandpass 0.07-1.0 Hz + Fresnel zone modeling detects chest displacement of 5-10mm at 5 GHz | 4-60 BPM, <500ms latency | +| **Heartbeat Detection** | Micro-Doppler shift extraction from fine-grained CSI phase variation | Via ruvector-temporal-tensor | +| **3D Localization** | Multi-AP triangulation + CSI fingerprint matching + depth estimation through rubble layers | 3-5m penetration | +| **START Triage** | Ensemble classifier votes on breathing + movement + vital stability β†’ P1-P4 priority | <1% false negative | +| **Zone Scanning** | 16+ concurrent scan zones with periodic re-scan and audit logging | Full disaster site | + +**Triage classification (START protocol compatible):** + +| Status | Color | Detection Criteria | Priority | +|--------|-------|-------------------|----------| +| Immediate | Red | Breathing detected, no movement | P1 | +| Delayed | Yellow | Movement + breathing, stable vitals | P2 | +| Minor | Green | Strong movement, responsive patterns | P3 | +| Deceased | Black | No vitals for >30 min continuous scan | P4 | + +**Deployment modes:** portable (single TX/RX handheld), distributed (multiple APs around collapse site), drone-mounted (UAV scanning), vehicle-mounted (mobile command post). ```rust use wifi_densepose_mat::{DisasterResponse, DisasterConfig, DisasterType, ScanZone, ZoneBounds}; @@ -271,6 +287,8 @@ response.add_zone(ScanZone::new("North Wing", ZoneBounds::rectangle(0.0, 0.0, 30 response.start_scanning().await?; ``` +**Safety guarantees:** fail-safe defaults (assume life present on ambiguous signals), redundant multi-algorithm voting, complete audit trail, offline-capable (no network required). + - [WiFi-Mat User Guide](docs/wifi-mat-user-guide.md) | [ADR-001](docs/adr/ADR-001-wifi-mat-disaster-detection.md) | [Domain Model](docs/ddd/wifi-mat-domain-model.md)
@@ -278,14 +296,20 @@ response.start_scanning().await?;
πŸ”¬ SOTA Signal Processing (ADR-014) β€” 6 research-grade algorithms -| Algorithm | Purpose | Reference | -|-----------|---------|-----------| -| **Conjugate Multiplication** | Cancels CFO/SFO from raw CSI phase | SpotFi (SIGCOMM 2015) | -| **Hampel Filter** | Robust outlier removal using median/MAD | Hampel (1974) | -| **Fresnel Zone Model** | Physics-based breathing detection | FarSense (MobiCom 2019) | -| **CSI Spectrogram** | STFT time-frequency matrices | Standard since 2018 | -| **Subcarrier Selection** | Variance-ratio top-K ranking | WiDance (MobiCom 2017) | -| **Body Velocity Profile** | Domain-independent velocity x time | Widar 3.0 (MobiSys 2019) | +The signal processing layer bridges the gap between raw commodity WiFi hardware output and research-grade sensing accuracy. Each algorithm addresses a specific limitation of naive CSI processing β€” from hardware-induced phase corruption to environment-dependent multipath interference. All six are implemented in `wifi-densepose-signal/src/` with deterministic tests and no mock data. + +| Algorithm | What It Does | Why It Matters | Math | Source | +|-----------|-------------|----------------|------|--------| +| **Conjugate Multiplication** | Multiplies CSI antenna pairs: `H₁[k] Γ— conj(Hβ‚‚[k])` | Cancels CFO, SFO, and packet detection delay that corrupt raw phase β€” preserves only environment-caused phase differences | `CSI_ratio[k] = H₁[k] * conj(Hβ‚‚[k])` | [SpotFi](https://dl.acm.org/doi/10.1145/2789168.2790124) (SIGCOMM 2015) | +| **Hampel Filter** | Replaces outliers using running median Β± scaled MAD | Z-score uses mean/std which are corrupted by the very outliers it detects (masking effect). Hampel uses median/MAD, resisting up to 50% contamination | `ΟƒΜ‚ = 1.4826 Γ— MAD` | Standard DSP; WiGest (2015) | +| **Fresnel Zone Model** | Models signal variation from chest displacement crossing Fresnel zone boundaries | Zero-crossing counting fails in multipath-rich environments. Fresnel predicts *where* breathing should appear based on TX-RX-body geometry | `ΔΦ = 2Ο€ Γ— 2Ξ”d / Ξ»`, `A = \|sin(ΔΦ/2)\|` | [FarSense](https://dl.acm.org/doi/10.1145/3300061.3345431) (MobiCom 2019) | +| **CSI Spectrogram** | Sliding-window FFT (STFT) per subcarrier β†’ 2D time-frequency matrix | Breathing = 0.2-0.4 Hz band, walking = 1-2 Hz, static = noise. 2D structure enables CNN spatial pattern recognition that 1D features miss | `S[t,f] = \|Ξ£β‚™ x[n] w[n-t] e^{-j2Ο€fn}\|Β²` | Standard since 2018 | +| **Subcarrier Selection** | Ranks subcarriers by motion sensitivity (variance ratio) and selects top-K | Not all subcarriers respond to motion β€” some sit in multipath nulls. Selecting the 10-20 most sensitive improves SNR by 6-10 dB | `sensitivity[k] = var_motion / var_static` | [WiDance](https://dl.acm.org/doi/10.1145/3117811.3117826) (MobiCom 2017) | +| **Body Velocity Profile** | Extracts velocity distribution from Doppler shifts across subcarriers | BVP is domain-independent β€” same velocity profile regardless of room layout, furniture, or AP placement. Basis for cross-environment recognition | `BVP[v,t] = Ξ£β‚– \|STFTβ‚–[v,t]\|` | [Widar 3.0](https://dl.acm.org/doi/10.1145/3328916) (MobiSys 2019) | + +**Processing pipeline order:** Raw CSI β†’ Conjugate multiplication (phase cleaning) β†’ Hampel filter (outlier removal) β†’ Subcarrier selection (top-K) β†’ CSI spectrogram (time-frequency) β†’ Fresnel model (breathing) + BVP (activity) + +See [ADR-014](docs/adr/ADR-014-sota-signal-processing.md) for full mathematical derivations.
@@ -296,13 +320,40 @@ response.start_scanning().await?;
πŸ“¦ RVF Model Container β€” Single-file deployment with progressive loading +The RuVector Format (RVF) packages an entire trained model β€” weights, HNSW indexes, quantization codebooks, SONA adaptation deltas, and WASM inference runtime β€” into a single self-contained binary file. No external dependencies are needed at deployment time. + +**Container structure:** + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ RVF Container (.rvf) β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” 64-byte header per segment β”‚ +β”‚ β”‚ Manifest β”‚ Magic: 0x52564653 ("RVFS") β”‚ +β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ Type + content hash + compression β”‚ +β”‚ β”‚ Weights β”‚ Model parameters (f32/f16/u8) β”‚ +β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ +β”‚ β”‚ HNSW Index β”‚ Vector search index β”‚ +β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ +β”‚ β”‚ Quant β”‚ Quantization codebooks β”‚ +β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ +β”‚ β”‚ SONA Profile β”‚ LoRA deltas + EWC++ Fisher matrix β”‚ +β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ +β”‚ β”‚ Witness β”‚ Ed25519 training proof β”‚ +β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ +β”‚ β”‚ Vitals Configβ”‚ Breathing/HR filter parameters β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + | Property | Detail | |----------|--------| -| **Format** | Segment-based binary (magic `0x52564653`) with 64-byte headers | -| **Progressive Loading** | Layer A <5ms, Layer B 100ms-1s, Layer C full graph | -| **Signing** | Ed25519 training proofs for verifiable provenance | -| **Quantization** | f32/f16/u8 via `rvf-quant` with SIMD distance | -| **CLI** | `--export-rvf`, `--save-rvf`, `--load-rvf`, `--model` | +| **Format** | Segment-based binary, 20+ segment types, CRC32 integrity per segment | +| **Progressive Loading** | **Layer A** (<5ms): manifest + entry points β†’ **Layer B** (100ms-1s): hot weights + adjacency β†’ **Layer C** (seconds): full graph | +| **Signing** | Ed25519 training proofs for verifiable provenance β€” chain of custody from training data to deployed model | +| **Quantization** | Per-segment temperature-tiered: f32 (full), f16 (half), u8 (int8), binary β€” with SIMD-accelerated distance computation | +| **CLI** | `--export-rvf` (generate), `--load-rvf` (config), `--save-rvf` (persist), `--model` (inference), `--progressive` (3-layer load) | +| **Size** | Typical: 13 KB (sensing-only) to 50+ MB (full DensePose) | ```bash # Export model package @@ -310,6 +361,9 @@ response.start_scanning().await?; # Load and run with progressive loading ./target/release/sensing-server --model wifi-densepose-v1.rvf --progressive + +# Export via Docker +docker run --rm -v $(pwd):/out ruvnet/wifi-densepose:latest --export-rvf /out/model.rvf ``` See [ADR-023](docs/adr/ADR-023-trained-densepose-model-ruvector-pipeline.md). @@ -319,21 +373,45 @@ See [ADR-023](docs/adr/ADR-023-trained-densepose-model-ruvector-pipeline.md).
🧬 Training & Fine-Tuning β€” MM-Fi/Wi-Pose pre-training, SONA adaptation -Three-tier data strategy: +The training pipeline implements 8 phases in pure Rust (7,832 lines, zero external ML dependencies). It trains a graph transformer with cross-attention to map CSI feature matrices to 17 COCO body keypoints and DensePose UV coordinates β€” following the approach from the CMU "DensePose From WiFi" paper (arXiv:2301.00250). -1. **Pre-train** on public datasets (MM-Fi, Wi-Pose) for cross-environment generalization -2. **Fine-tune** with ESP32 data + camera pseudo-labels for environment-specific multipath -3. **SONA adaptation** via micro-LoRA + EWC++ for continuous on-device learning +**Three-tier data strategy:** + +| Tier | Method | Purpose | +|------|--------|---------| +| **1. Pre-train** | MM-Fi + Wi-Pose public datasets | Cross-environment generalization (multi-subject, multi-room) | +| **2. Fine-tune** | ESP32 CSI + camera pseudo-labels | Environment-specific multipath adaptation | +| **3. SONA adapt** | Micro-LoRA (rank-4) + EWC++ | Continuous on-device learning without catastrophic forgetting | + +**Training pipeline components:** + +| Phase | Module | What It Does | +|-------|--------|-------------| +| 1 | `dataset.rs` (850 lines) | MM-Fi `.npy` + Wi-Pose `.mat` loaders, subcarrier resampling (114β†’56, 30β†’56), windowing, normalization | +| 2 | `graph_transformer.rs` (855 lines) | COCO BodyGraph (17 kp, 16 edges), AntennaGraph, multi-head CrossAttention, GCN message passing | +| 3 | `trainer.rs` (881 lines) | 6-term composite loss (MSE, cross-entropy, UV regression, temporal consistency, bone length, symmetry), SGD+momentum, cosine+warmup scheduler, PCK/OKS metrics | +| 4 | `sona.rs` (639 lines) | LoRA adapters (AΓ—B delta), EWC++ Fisher regularization, EnvironmentDetector (3-sigma drift detection) | +| 5 | `sparse_inference.rs` (753 lines) | NeuronProfiler hot/cold partitioning, SparseLinear (skip cold rows), INT8/FP16 quantization with <0.01 MSE | +| 6 | `rvf_pipeline.rs` (1,027 lines) | Progressive 3-layer loader, HNSW index, OverlayGraph, `RvfModelBuilder` | +| 7 | `rvf_container.rs` (914 lines) | Binary container format, 6+ segment types, CRC32 integrity | +| 8 | `main.rs` integration | `--train`, `--model`, `--progressive` CLI flags, REST endpoints | + +**Best-epoch snapshotting**: the trainer saves the best validation loss weights and restores them before checkpoint/export β€” prevents exporting overfit final-epoch parameters. ```bash -# Pre-train +# Pre-train on MM-Fi dataset ./target/release/sensing-server --train --dataset data/ --dataset-type mmfi --epochs 100 -# Or via Docker +# Train and export to RVF in one step +./target/release/sensing-server --train --dataset data/ --epochs 100 --save-rvf model.rvf + +# Via Docker (no toolchain needed) docker run --rm -v $(pwd)/data:/data ruvnet/wifi-densepose:latest \ --train --dataset /data --epochs 100 --export-rvf /data/model.rvf ``` +See [ADR-023](docs/adr/ADR-023-trained-densepose-model-ruvector-pipeline.md). +
@@ -361,7 +439,7 @@ See `vendor/ruvector/` for full source. ## πŸ—οΈ System Architecture -
+
End-to-end data flow β€” From CSI capture to REST/WebSocket API ``` @@ -674,7 +752,7 @@ wifi-densepose tasks list # List background tasks ## πŸ§ͺ Testing -
+
542+ tests across 7 suites β€” zero mocks, hardware-free simulation ```bash @@ -804,7 +882,7 @@ pre-commit install ## πŸ“„ Changelog -
+
Release history ### v2.3.0 β€” 2026-03-01