Upload README.md with huggingface_hub

README.md

@@ -4,14 +4,17 @@ tags:
   - wifi-sensing
   - vital-signs
   - presence-detection
+  - pose-estimation
   - edge-ai
   - esp32
   - self-supervised
+  - camera-supervised
   - cognitum
   - through-wall
   - privacy-preserving
   - spiking-neural-network
   - ruvector
+  - wiflow
 language:
   - en
 library_name: onnxruntime
@@ -20,14 +23,15 @@ pipeline_tag: other
 
 # RuView — WiFi Sensing Models
 
-**Turn WiFi signals into spatial intelligence.** Detect people, measure breathing and heart rate, track movement, and monitor rooms — through walls, in the dark, with no cameras. Just radio physics.
+**Turn WiFi signals into spatial intelligence.** Detect people, measure breathing and heart rate, estimate pose, track movement, and monitor rooms — through walls, in the dark, with no cameras. Just radio physics.
 
 ## What This Does
 
-WiFi signals bounce off people. When someone breathes, their chest moves the air, which subtly changes the WiFi signal. When they walk, the changes are bigger. This model learned to read those changes from a $9 ESP32 chip.
+WiFi signals bounce off people. When someone breathes, their chest moves the air, which subtly changes the WiFi signal. When they walk, the changes are bigger. These models learned to read those changes from a $9 ESP32 chip.
 
 | What it senses | How well | Without |
 |----------------|----------|---------|
+| **Pose estimation** | **92.9% PCK@20** (17 COCO keypoints) | No camera at deployment |
 | **Is someone there?** | 100% accuracy | No camera needed |
 | **Are they moving?** | Detects typing vs walking vs standing | No wearable needed |
 | **Breathing rate** | 6-30 BPM, contactless | No chest strap |
@@ -39,22 +43,35 @@ WiFi signals bounce off people. When someone breathes, their chest moves the air
 
 ## Benchmarks
 
-Validated on real hardware (Apple M4 Pro + 2x ESP32-S3):
-
 | Metric | Result | Context |
 |--------|--------|---------|
+| **Pose PCK@20** | **92.9%** | Camera-supervised WiFlow model (v0.7.0) |
 | **Presence accuracy** | **100%** | Never misses, never false alarms |
 | **Inference speed** | **0.008 ms** | 125,000x faster than real-time |
 | **Throughput** | **164,183 emb/sec** | One laptop handles 1,600+ sensors |
-| **Contrastive learning** | **51.6% improvement** | Trained on 8 hours of overnight data |
-| **Model size** | **8 KB** (4-bit quantized) | Fits in ESP32 SRAM |
-| **Training time** | **12 minutes** | On Mac Mini M4 Pro, no GPU needed |
-| **Camera required** | **No** | Trained from 10 sensor signals |
+| **Model size (pose)** | **974 KB** | WiFlow lite, 189K params |
+| **Model size (sensing)** | **8 KB** (4-bit quantized) | Fits in ESP32 SRAM |
+| **Training time (pose)** | **19 minutes** | 5-min data collection + lite training |
+| **Training time (sensing)** | **12 minutes** | On Mac Mini M4 Pro, no GPU needed |
+| **Hardware cost** | **$9** | Single ESP32-S3 |
 
 ## Models in This Repo
 
-| File | Size | Use |
-|------|------|-----|
+### WiFlow Pose Model (v0.7.0) — NEW
+
+| File | Size | Description |
+|------|------|-------------|
+| `wiflow-v1/wiflow-v1.json` | 974 KB | **Camera-supervised pose model** — 92.9% PCK@20, 17 COCO keypoints |
+| `wiflow-v1/training-log.json` | 13 KB | Loss curves per training phase |
+| `wiflow-v1/baseline-report.json` | 1 KB | Pre-training baseline metrics |
+| `wiflow-v1/MODEL_CARD.md` | 1 KB | Model documentation |
+
+Trained on real ESP32 CSI (7,000 frames) + real webcam keypoints via MediaPipe (6,470 frames). 5-minute data collection, 19-minute training. See [ADR-079](https://github.com/ruvnet/RuView/blob/main/docs/adr/ADR-079-camera-ground-truth-training.md).
+
+### Contrastive Sensing Model (v0.6.0)
+
+| File | Size | Description |
+|------|------|-------------|
 | `model.safetensors` | 48 KB | Full contrastive encoder (128-dim embeddings) |
 | `model-q4.bin` | 8 KB | **Recommended** — 4-bit quantized, 8x compression |
 | `model-q2.bin` | 4 KB | Ultra-compact for ESP32 edge inference |
@@ -63,12 +80,11 @@ Validated on real hardware (Apple M4 Pro + 2x ESP32-S3):
 | `node-1.json` | 21 KB | LoRA adapter for room/node 1 |
 | `node-2.json` | 21 KB | LoRA adapter for room/node 2 |
 | `config.json` | 586 B | Model configuration |
-| `training-metrics.json` | 3.1 KB | Loss curves and training history |
 
 ## Quick Start
 
 ```bash
-# Download models
+# Download all models
 pip install huggingface_hub
 huggingface-cli download ruv/ruview --local-dir models/
 
@@ -81,90 +97,54 @@ python -m esptool --chip esp32s3 --port COM9 --baud 460800 \
   write_flash 0x0 bootloader.bin 0x8000 partition-table.bin \
   0xf000 ota_data_initial.bin 0x20000 esp32-csi-node.bin
 
-# Provision WiFi
-python firmware/esp32-csi-node/provision.py --port COM9 \
-  --ssid "YourWiFi" --password "secret" --target-ip YOUR_IP
-
-# See what WiFi reveals about your room
-node scripts/deep-scan.js --bind YOUR_IP --duration 10
+# Train your own pose model (5 min data + 19 min training)
+python scripts/collect-ground-truth.py --duration 300 --preview
+python scripts/record-csi-udp.py --duration 300
+node scripts/align-ground-truth.js --gt data/ground-truth/*.jsonl --csi data/recordings/*.csi.jsonl
+node scripts/train-wiflow-supervised.js --data data/paired/*.jsonl --scale lite
 ```
 
 ## Architecture
 
+### WiFlow Pose Model
 ```
-WiFi signals → ESP32-S3 ($9) → 8-dim features @ 1 Hz → Encoder → 128-dim embedding
-                                                                    ↓
-                                         ┌──────────────────────────┼──────────────────┐
-                                         ↓                          ↓                  ↓
-                                    Presence head            Activity head         Vitals head
-                                    (100% accuracy)          (still/walk/talk)     (BR, HR)
+CSI amplitude [35, 20] (ruvector-selected subcarriers)
+    |
+TCN: 2 dilated causal conv blocks (k=3, d=[1,2])
+    35 -> 32 -> 32 channels
+    |
+Flatten [640] -> FC [256] -> FC [34] -> Sigmoid
+    |
+17 COCO keypoints [x, y] in [0, 1]
 ```
 
-The encoder converts 8 WiFi Channel State Information (CSI) features into a 128-dimensional embedding:
-
-| Dim | Feature | What it captures |
-|-----|---------|-----------------|
-| 0 | Presence | How much the WiFi signal is disturbed |
-| 1 | Motion | Rate of signal change (walking > typing > still) |
-| 2 | Breathing | Chest movement modulates subcarrier phase at 6-30 BPM |
-| 3 | Heart rate | Blood pulse creates micro-Doppler at 40-120 BPM |
-| 4 | Phase variance | Signal quality — higher = more movement |
-| 5 | Person count | Independent motion clusters via min-cut graph |
-| 6 | Fall detected | Sudden phase acceleration followed by stillness |
-| 7 | RSSI | Signal strength — indicates distance from sensor |
-
-## Training Details
-
-**No camera was used.** Trained using self-supervised contrastive learning:
-
-- **Data**: 60,630 samples from 2 ESP32-S3 nodes over 8 hours
-- **Method**: Triplet loss + InfoNCE (nearby frames = similar, distant = different)
-- **Augmentation**: 10x via temporal interpolation, noise, cross-node blending
-- **Supervision**: PIR sensor, BME280, RSSI triangulation, subcarrier asymmetry
-- **Quantization**: TurboQuant 2/4/8-bit with <0.5% quality loss
-- **Adaptation**: LoRA rank-4 per room, EWC to prevent forgetting
-
-## 17 Sensing Applications
-
-Built on these embeddings ([RuView](https://github.com/ruvnet/RuView)):
-
-**Core:** Presence, person counting, RF scanning, SNN learning, CNN fingerprinting
-
-**Health:** Sleep monitoring, apnea screening, stress detection, gait analysis
-
-**Environment:** Room fingerprinting, material detection, device fingerprinting
-
-**Multi-frequency:** RF tomography, passive radar, material classification, through-wall motion
+### Contrastive Sensing Model
+```
+WiFi signals -> ESP32-S3 ($9) -> 8-dim features @ 1 Hz -> Encoder -> 128-dim embedding
+    |
+Presence head (threshold 0.3) -> person/no-person
+Activity head -> stationary/walking/typing
+Vitals extraction -> breathing BPM, heart rate BPM
+```
 
-## Hardware
+## Training Your Own Pose Model
 
-| Component | Cost | Purpose |
-|-----------|------|---------|
-| ESP32-S3 (8MB) | ~$9 | WiFi CSI sensing |
-| [Cognitum Seed](https://cognitum.one) (optional) | $131 | Persistent storage, kNN, witness chain, AI proxy |
+The camera is only needed during a one-time 5-minute training session. After that, the model runs on CSI alone — no camera at deployment.
 
-## Limitations
+1. **Collect** — Run `collect-ground-truth.py` + `record-csi-udp.py` simultaneously for 5 minutes
+2. **Align** — `align-ground-truth.js` pairs camera keypoints with CSI windows by timestamp
+3. **Train** — `train-wiflow-supervised.js` trains WiFlow with curriculum learning + bone constraints
+4. **Deploy** — Load `wiflow-v1.json` and run inference on CSI only
 
-- Room-specific (use LoRA adapters for new rooms)
-- Camera-free pose: 2.5% PCK@20 (camera labels improve significantly)
-- Health features are for screening only, not medical diagnosis
-- Breathing/HR less accurate during active movement
+See the [v0.7.0 release](https://github.com/ruvnet/RuView/releases/tag/v0.7.0) for details.
 
-## Citation
+## License
 
-```bibtex
-@software{ruview2026,
-  title={RuView: WiFi Sensing with Self-Supervised Contrastive Learning},
-  author={rUv},
-  year={2026},
-  url={https://github.com/ruvnet/RuView},
-  note={Models: https://huggingface.co/ruv/ruview}
-}
-```
+MIT — see [LICENSE](https://github.com/ruvnet/RuView/blob/main/LICENSE)
 
 ## Links
 
-- **GitHub**: https://github.com/ruvnet/RuView
-- **Cognitum Seed**: https://cognitum.one
-- **RuVector**: https://github.com/ruvnet/ruvector
-- **License**: MIT
+- [GitHub](https://github.com/ruvnet/RuView)
+- [v0.7.0 Release](https://github.com/ruvnet/RuView/releases/tag/v0.7.0)
+- [ADR-079: Camera Ground-Truth Training](https://github.com/ruvnet/RuView/blob/main/docs/adr/ADR-079-camera-ground-truth-training.md)
+- [Cognitum.one](https://cognitum.one)