From 7092f83b345006acae03504e51547a2268a2a439 Mon Sep 17 00:00:00 2001 From: ruv Date: Sun, 1 Mar 2026 01:39:36 -0500 Subject: [PATCH] chore: add workspace metadata and crate READMEs for publishing Add license, authors, repository, documentation, keywords, categories, and readme fields to all crate Cargo.toml files. Add crate-level README files for documentation. Co-Authored-By: claude-flow --- rust-port/wifi-densepose-rs/Cargo.toml | 20 +- rust-port/wifi-densepose-rs/crates/README.md | 297 ++++++++++++++++++ .../crates/wifi-densepose-api/Cargo.toml | 7 + .../crates/wifi-densepose-api/README.md | 71 +++++ .../crates/wifi-densepose-cli/Cargo.toml | 6 +- .../crates/wifi-densepose-cli/README.md | 95 ++++++ .../crates/wifi-densepose-config/Cargo.toml | 7 + .../crates/wifi-densepose-config/README.md | 89 ++++++ .../crates/wifi-densepose-core/README.md | 83 +++++ .../crates/wifi-densepose-db/Cargo.toml | 7 + .../crates/wifi-densepose-db/README.md | 106 +++++++ .../crates/wifi-densepose-hardware/Cargo.toml | 5 + .../crates/wifi-densepose-hardware/README.md | 82 +++++ .../crates/wifi-densepose-mat/Cargo.toml | 10 +- .../crates/wifi-densepose-mat/README.md | 114 +++++++ .../crates/wifi-densepose-nn/Cargo.toml | 1 + .../crates/wifi-densepose-nn/README.md | 89 ++++++ .../wifi-densepose-sensing-server/Cargo.toml | 8 +- .../wifi-densepose-sensing-server/README.md | 124 ++++++++ .../crates/wifi-densepose-signal/Cargo.toml | 8 +- .../crates/wifi-densepose-signal/README.md | 86 +++++ .../crates/wifi-densepose-train/Cargo.toml | 10 +- .../crates/wifi-densepose-train/README.md | 99 ++++++ .../crates/wifi-densepose-vitals/Cargo.toml | 6 + .../crates/wifi-densepose-vitals/README.md | 102 ++++++ .../crates/wifi-densepose-wasm/Cargo.toml | 7 +- .../crates/wifi-densepose-wasm/README.md | 128 ++++++++ .../crates/wifi-densepose-wifiscan/Cargo.toml | 6 + .../crates/wifi-densepose-wifiscan/README.md | 98 ++++++ 29 files changed, 1750 insertions(+), 21 deletions(-) create mode 100644 rust-port/wifi-densepose-rs/crates/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-api/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-cli/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-config/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-core/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-db/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-mat/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-nn/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-sensing-server/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-train/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-vitals/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm/README.md create mode 100644 rust-port/wifi-densepose-rs/crates/wifi-densepose-wifiscan/README.md diff --git a/rust-port/wifi-densepose-rs/Cargo.toml b/rust-port/wifi-densepose-rs/Cargo.toml index 2c0e448..00fd534 100644 --- a/rust-port/wifi-densepose-rs/Cargo.toml +++ b/rust-port/wifi-densepose-rs/Cargo.toml @@ -20,7 +20,7 @@ members = [ [workspace.package] version = "0.1.0" edition = "2021" -authors = ["WiFi-DensePose Contributors"] +authors = ["rUv ", "WiFi-DensePose Contributors"] license = "MIT OR Apache-2.0" repository = "https://github.com/ruvnet/wifi-densepose" documentation = "https://docs.rs/wifi-densepose" @@ -111,15 +111,15 @@ ruvector-attention = "2.0.4" # Internal crates -wifi-densepose-core = { path = "crates/wifi-densepose-core" } -wifi-densepose-signal = { path = "crates/wifi-densepose-signal" } -wifi-densepose-nn = { path = "crates/wifi-densepose-nn" } -wifi-densepose-api = { path = "crates/wifi-densepose-api" } -wifi-densepose-db = { path = "crates/wifi-densepose-db" } -wifi-densepose-config = { path = "crates/wifi-densepose-config" } -wifi-densepose-hardware = { path = "crates/wifi-densepose-hardware" } -wifi-densepose-wasm = { path = "crates/wifi-densepose-wasm" } -wifi-densepose-mat = { path = "crates/wifi-densepose-mat" } +wifi-densepose-core = { version = "0.1.0", path = "crates/wifi-densepose-core" } +wifi-densepose-signal = { version = "0.1.0", path = "crates/wifi-densepose-signal" } +wifi-densepose-nn = { version = "0.1.0", path = "crates/wifi-densepose-nn" } +wifi-densepose-api = { version = "0.1.0", path = "crates/wifi-densepose-api" } +wifi-densepose-db = { version = "0.1.0", path = "crates/wifi-densepose-db" } +wifi-densepose-config = { version = "0.1.0", path = "crates/wifi-densepose-config" } +wifi-densepose-hardware = { version = "0.1.0", path = "crates/wifi-densepose-hardware" } +wifi-densepose-wasm = { version = "0.1.0", path = "crates/wifi-densepose-wasm" } +wifi-densepose-mat = { version = "0.1.0", path = "crates/wifi-densepose-mat" } [profile.release] lto = true diff --git a/rust-port/wifi-densepose-rs/crates/README.md b/rust-port/wifi-densepose-rs/crates/README.md new file mode 100644 index 0000000..0bc3fa0 --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/README.md @@ -0,0 +1,297 @@ +# WiFi-DensePose Rust Crates + +[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE) +[![Rust 1.85+](https://img.shields.io/badge/rust-1.85%2B-orange.svg)](https://www.rust-lang.org/) +[![Workspace](https://img.shields.io/badge/workspace-14%20crates-green.svg)](https://github.com/ruvnet/wifi-densepose) +[![RuVector v2.0.4](https://img.shields.io/badge/ruvector-v2.0.4-purple.svg)](https://crates.io/crates/ruvector-mincut) +[![Tests](https://img.shields.io/badge/tests-542%2B-brightgreen.svg)](#testing) + +**See through walls with WiFi. No cameras. No wearables. Just radio waves.** + +A modular Rust workspace for WiFi-based human pose estimation, vital sign monitoring, and disaster response using Channel State Information (CSI). Built on [RuVector](https://crates.io/crates/ruvector-mincut) graph algorithms and the [WiFi-DensePose](https://github.com/ruvnet/wifi-densepose) research platform by [rUv](https://github.com/ruvnet). + +--- + +## Performance + +| Operation | Python v1 | Rust v2 | Speedup | +|-----------|-----------|---------|---------| +| CSI Preprocessing | ~5 ms | 5.19 us | **~1000x** | +| Phase Sanitization | ~3 ms | 3.84 us | **~780x** | +| Feature Extraction | ~8 ms | 9.03 us | **~890x** | +| Motion Detection | ~1 ms | 186 ns | **~5400x** | +| Full Pipeline | ~15 ms | 18.47 us | **~810x** | +| Vital Signs | N/A | 86 us (11,665 fps) | -- | + +## Crate Overview + +### Core Foundation + +| Crate | Description | crates.io | +|-------|-------------|-----------| +| [`wifi-densepose-core`](wifi-densepose-core/) | Types, traits, and utilities (`CsiFrame`, `PoseEstimate`, `SignalProcessor`) | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-core.svg)](https://crates.io/crates/wifi-densepose-core) | +| [`wifi-densepose-config`](wifi-densepose-config/) | Configuration management (env, TOML, YAML) | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-config.svg)](https://crates.io/crates/wifi-densepose-config) | +| [`wifi-densepose-db`](wifi-densepose-db/) | Database persistence (PostgreSQL, SQLite, Redis) | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-db.svg)](https://crates.io/crates/wifi-densepose-db) | + +### Signal Processing & Sensing + +| Crate | Description | RuVector Integration | crates.io | +|-------|-------------|---------------------|-----------| +| [`wifi-densepose-signal`](wifi-densepose-signal/) | SOTA CSI signal processing (6 algorithms from SpotFi, FarSense, Widar 3.0) | `ruvector-mincut`, `ruvector-attn-mincut`, `ruvector-attention`, `ruvector-solver` | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-signal.svg)](https://crates.io/crates/wifi-densepose-signal) | +| [`wifi-densepose-vitals`](wifi-densepose-vitals/) | Vital sign extraction: breathing (6-30 BPM) and heart rate (40-120 BPM) | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-vitals.svg)](https://crates.io/crates/wifi-densepose-vitals) | +| [`wifi-densepose-wifiscan`](wifi-densepose-wifiscan/) | Multi-BSSID WiFi scanning for Windows-enhanced sensing | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-wifiscan.svg)](https://crates.io/crates/wifi-densepose-wifiscan) | + +### Neural Network & Training + +| Crate | Description | RuVector Integration | crates.io | +|-------|-------------|---------------------|-----------| +| [`wifi-densepose-nn`](wifi-densepose-nn/) | Multi-backend inference (ONNX, PyTorch, Candle) with DensePose head (24 body parts) | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-nn.svg)](https://crates.io/crates/wifi-densepose-nn) | +| [`wifi-densepose-train`](wifi-densepose-train/) | Training pipeline with MM-Fi dataset, 114->56 subcarrier interpolation | **All 5 crates** | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-train.svg)](https://crates.io/crates/wifi-densepose-train) | + +### Disaster Response + +| Crate | Description | RuVector Integration | crates.io | +|-------|-------------|---------------------|-----------| +| [`wifi-densepose-mat`](wifi-densepose-mat/) | Mass Casualty Assessment Tool -- survivor detection, triage, multi-AP localization | `ruvector-solver`, `ruvector-temporal-tensor` | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-mat.svg)](https://crates.io/crates/wifi-densepose-mat) | + +### Hardware & Deployment + +| Crate | Description | crates.io | +|-------|-------------|-----------| +| [`wifi-densepose-hardware`](wifi-densepose-hardware/) | ESP32, Intel 5300, Atheros CSI sensor interfaces (pure Rust, no FFI) | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-hardware.svg)](https://crates.io/crates/wifi-densepose-hardware) | +| [`wifi-densepose-wasm`](wifi-densepose-wasm/) | WebAssembly bindings for browser-based disaster dashboard | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-wasm.svg)](https://crates.io/crates/wifi-densepose-wasm) | +| [`wifi-densepose-sensing-server`](wifi-densepose-sensing-server/) | Axum server: ESP32 UDP ingestion, WebSocket broadcast, sensing UI | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-sensing-server.svg)](https://crates.io/crates/wifi-densepose-sensing-server) | + +### Applications + +| Crate | Description | crates.io | +|-------|-------------|-----------| +| [`wifi-densepose-api`](wifi-densepose-api/) | REST + WebSocket API layer | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-api.svg)](https://crates.io/crates/wifi-densepose-api) | +| [`wifi-densepose-cli`](wifi-densepose-cli/) | Command-line tool for MAT disaster scanning | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-cli.svg)](https://crates.io/crates/wifi-densepose-cli) | + +--- + +## Architecture + +``` + wifi-densepose-core + (types, traits, errors) + | + +-------------------+-------------------+ + | | | + wifi-densepose-signal wifi-densepose-nn wifi-densepose-hardware + (CSI processing) (inference) (ESP32, Intel 5300) + + ruvector-mincut + ONNX Runtime | + + ruvector-attn-mincut + PyTorch (tch) wifi-densepose-vitals + + ruvector-attention + Candle (breathing, heart rate) + + ruvector-solver | + | | wifi-densepose-wifiscan + +--------+---------+ (BSSID scanning) + | + +------------+------------+ + | | + wifi-densepose-train wifi-densepose-mat + (training pipeline) (disaster response) + + ALL 5 ruvector + ruvector-solver + + ruvector-temporal-tensor + | + +-----------------+-----------------+ + | | | + wifi-densepose-api wifi-densepose-wasm wifi-densepose-cli + (REST/WS) (browser WASM) (CLI tool) + | + wifi-densepose-sensing-server + (Axum + WebSocket) +``` + +## RuVector Integration + +All [RuVector](https://github.com/ruvnet/ruvector) crates at **v2.0.4** from crates.io: + +| RuVector Crate | Used In | Purpose | +|----------------|---------|---------| +| [`ruvector-mincut`](https://crates.io/crates/ruvector-mincut) | signal, train | Dynamic min-cut for subcarrier selection & person matching | +| [`ruvector-attn-mincut`](https://crates.io/crates/ruvector-attn-mincut) | signal, train | Attention-weighted min-cut for antenna gating & spectrograms | +| [`ruvector-temporal-tensor`](https://crates.io/crates/ruvector-temporal-tensor) | train, mat | Tiered temporal compression (4-10x memory reduction) | +| [`ruvector-solver`](https://crates.io/crates/ruvector-solver) | signal, train, mat | Sparse Neumann solver for interpolation & triangulation | +| [`ruvector-attention`](https://crates.io/crates/ruvector-attention) | signal, train | Scaled dot-product attention for spatial features & BVP | + +## Signal Processing Algorithms + +Six state-of-the-art algorithms implemented in `wifi-densepose-signal`: + +| Algorithm | Paper | Year | Module | +|-----------|-------|------|--------| +| Conjugate Multiplication | SpotFi (SIGCOMM) | 2015 | `csi_ratio.rs` | +| Hampel Filter | WiGest | 2015 | `hampel.rs` | +| Fresnel Zone Model | FarSense (MobiCom) | 2019 | `fresnel.rs` | +| CSI Spectrogram | Standard STFT | 2018+ | `spectrogram.rs` | +| Subcarrier Selection | WiDance (MobiCom) | 2017 | `subcarrier_selection.rs` | +| Body Velocity Profile | Widar 3.0 (MobiSys) | 2019 | `bvp.rs` | + +## Quick Start + +### As a Library + +```rust +use wifi_densepose_core::{CsiFrame, CsiMetadata, SignalProcessor}; +use wifi_densepose_signal::{CsiProcessor, CsiProcessorConfig}; + +// Configure the CSI processor +let config = CsiProcessorConfig::default(); +let processor = CsiProcessor::new(config); + +// Process a CSI frame +let frame = CsiFrame { /* ... */ }; +let processed = processor.process(&frame)?; +``` + +### Vital Sign Monitoring + +```rust +use wifi_densepose_vitals::{ + CsiVitalPreprocessor, BreathingExtractor, HeartRateExtractor, + VitalAnomalyDetector, +}; + +let mut preprocessor = CsiVitalPreprocessor::new(56); // 56 subcarriers +let mut breathing = BreathingExtractor::new(100.0); // 100 Hz sample rate +let mut heartrate = HeartRateExtractor::new(100.0); + +// Feed CSI frames and extract vitals +for frame in csi_stream { + let residuals = preprocessor.update(&frame.amplitudes); + if let Some(bpm) = breathing.push_residuals(&residuals) { + println!("Breathing: {:.1} BPM", bpm); + } +} +``` + +### Disaster Response (MAT) + +```rust +use wifi_densepose_mat::{DisasterResponse, DisasterConfig, DisasterType}; + +let config = DisasterConfig { + disaster_type: DisasterType::Earthquake, + max_scan_zones: 16, + ..Default::default() +}; + +let mut responder = DisasterResponse::new(config); +responder.add_scan_zone(zone)?; +responder.start_continuous_scan().await?; +``` + +### Hardware (ESP32) + +```rust +use wifi_densepose_hardware::{Esp32CsiParser, CsiFrame}; + +let parser = Esp32CsiParser::new(); +let raw_bytes: &[u8] = /* UDP packet from ESP32 */; +let frame: CsiFrame = parser.parse(raw_bytes)?; +println!("RSSI: {} dBm, {} subcarriers", frame.metadata.rssi, frame.subcarriers.len()); +``` + +### Training + +```bash +# Check training crate (no GPU needed) +cargo check -p wifi-densepose-train --no-default-features + +# Run training with GPU (requires tch/libtorch) +cargo run -p wifi-densepose-train --features tch-backend --bin train -- \ + --config training.toml --dataset /path/to/mmfi + +# Verify deterministic training proof +cargo run -p wifi-densepose-train --features tch-backend --bin verify-training +``` + +## Building + +```bash +# Clone the repository +git clone https://github.com/ruvnet/wifi-densepose.git +cd wifi-densepose/rust-port/wifi-densepose-rs + +# Check workspace (no GPU dependencies) +cargo check --workspace --no-default-features + +# Run all tests +cargo test --workspace --no-default-features + +# Build release +cargo build --release --workspace +``` + +### Feature Flags + +| Crate | Feature | Description | +|-------|---------|-------------| +| `wifi-densepose-nn` | `onnx` (default) | ONNX Runtime backend | +| `wifi-densepose-nn` | `tch-backend` | PyTorch (libtorch) backend | +| `wifi-densepose-nn` | `candle-backend` | Candle (pure Rust) backend | +| `wifi-densepose-nn` | `cuda` | CUDA GPU acceleration | +| `wifi-densepose-train` | `tch-backend` | Enable GPU training modules | +| `wifi-densepose-mat` | `ruvector` (default) | RuVector graph algorithms | +| `wifi-densepose-mat` | `api` (default) | REST + WebSocket API | +| `wifi-densepose-mat` | `distributed` | Multi-node coordination | +| `wifi-densepose-mat` | `drone` | Drone-mounted scanning | +| `wifi-densepose-hardware` | `esp32` | ESP32 protocol support | +| `wifi-densepose-hardware` | `intel5300` | Intel 5300 CSI Tool | +| `wifi-densepose-hardware` | `linux-wifi` | Linux commodity WiFi | +| `wifi-densepose-wifiscan` | `wlanapi` | Windows WLAN API async scanning | +| `wifi-densepose-core` | `serde` | Serialization support | +| `wifi-densepose-core` | `async` | Async trait support | + +## Testing + +```bash +# Unit tests (all crates) +cargo test --workspace --no-default-features + +# Signal processing benchmarks +cargo bench -p wifi-densepose-signal + +# Training benchmarks +cargo bench -p wifi-densepose-train --no-default-features + +# Detection benchmarks +cargo bench -p wifi-densepose-mat +``` + +## Supported Hardware + +| Hardware | Crate Feature | CSI Subcarriers | Cost | +|----------|---------------|-----------------|------| +| ESP32-S3 Mesh (3-6 nodes) | `hardware/esp32` | 52-56 | ~$54 | +| Intel 5300 NIC | `hardware/intel5300` | 30 | ~$50 | +| Atheros AR9580 | `hardware/linux-wifi` | 56 | ~$100 | +| Any WiFi (Windows/Linux) | `wifiscan` | RSSI-only | $0 | + +## Architecture Decision Records + +Key design decisions documented in [`docs/adr/`](https://github.com/ruvnet/wifi-densepose/tree/main/docs/adr): + +| ADR | Title | Status | +|-----|-------|--------| +| [ADR-014](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-014-sota-signal-processing.md) | SOTA Signal Processing | Accepted | +| [ADR-015](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-015-public-dataset-training-strategy.md) | MM-Fi + Wi-Pose Training Datasets | Accepted | +| [ADR-016](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-016-ruvector-integration.md) | RuVector Training Pipeline | Accepted (Complete) | +| [ADR-017](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-017-ruvector-signal-mat-integration.md) | RuVector Signal + MAT Integration | Accepted | +| [ADR-021](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-021-vital-sign-detection.md) | Vital Sign Detection Pipeline | Accepted | +| [ADR-022](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-022-windows-wifi-enhanced.md) | Windows WiFi Enhanced Sensing | Accepted | +| [ADR-024](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-024-contrastive-csi-embedding.md) | Contrastive CSI Embedding Model | Accepted | + +## Related Projects + +- **[WiFi-DensePose](https://github.com/ruvnet/wifi-densepose)** -- Main repository (Python v1 + Rust v2) +- **[RuVector](https://github.com/ruvnet/ruvector)** -- Graph algorithms for neural networks (5 crates, v2.0.4) +- **[rUv](https://github.com/ruvnet)** -- Creator and maintainer + +## License + +All crates are dual-licensed under [MIT](https://opensource.org/licenses/MIT) OR [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +Copyright (c) 2024 rUv diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-api/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-api/Cargo.toml index 041134c..5010b1e 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-api/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-api/Cargo.toml @@ -3,5 +3,12 @@ name = "wifi-densepose-api" version.workspace = true edition.workspace = true description = "REST API for WiFi-DensePose" +license.workspace = true +authors = ["rUv ", "WiFi-DensePose Contributors"] +repository.workspace = true +documentation.workspace = true +keywords = ["wifi", "api", "rest", "densepose", "websocket"] +categories = ["web-programming::http-server", "science"] +readme = "README.md" [dependencies] diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-api/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-api/README.md new file mode 100644 index 0000000..b1837c2 --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-api/README.md @@ -0,0 +1,71 @@ +# wifi-densepose-api + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-api.svg)](https://crates.io/crates/wifi-densepose-api) +[![Documentation](https://docs.rs/wifi-densepose-api/badge.svg)](https://docs.rs/wifi-densepose-api) +[![License](https://img.shields.io/crates/l/wifi-densepose-api.svg)](LICENSE) + +REST and WebSocket API layer for the WiFi-DensePose pose estimation system. + +## Overview + +`wifi-densepose-api` provides the HTTP service boundary for WiFi-DensePose. Built on +[axum](https://github.com/tokio-rs/axum), it exposes REST endpoints for pose queries, CSI frame +ingestion, and model management, plus a WebSocket feed for real-time pose streaming to frontend +clients. + +> **Status:** This crate is currently a stub. The intended API surface is documented below. + +## Planned Features + +- **REST endpoints** -- CRUD for scan zones, pose queries, model configuration, and health checks. +- **WebSocket streaming** -- Real-time pose estimate broadcasts with per-client subscription filters. +- **Authentication** -- Token-based auth middleware via `tower` layers. +- **Rate limiting** -- Configurable per-route limits to protect hardware-constrained deployments. +- **OpenAPI spec** -- Auto-generated documentation via `utoipa`. +- **CORS** -- Configurable cross-origin support for browser-based dashboards. +- **Graceful shutdown** -- Clean connection draining on SIGTERM. + +## Quick Start + +```rust +// Intended usage (not yet implemented) +use wifi_densepose_api::Server; + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + let server = Server::builder() + .bind("0.0.0.0:3000") + .with_websocket("/ws/poses") + .build() + .await?; + + server.run().await +} +``` + +## Planned Endpoints + +| Method | Path | Description | +|--------|------|-------------| +| `GET` | `/api/v1/health` | Liveness and readiness probes | +| `GET` | `/api/v1/poses` | Latest pose estimates | +| `POST` | `/api/v1/csi` | Ingest raw CSI frames | +| `GET` | `/api/v1/zones` | List scan zones | +| `POST` | `/api/v1/zones` | Create a scan zone | +| `WS` | `/ws/poses` | Real-time pose stream | +| `WS` | `/ws/vitals` | Real-time vital sign stream | + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-core`](../wifi-densepose-core) | Shared types and traits | +| [`wifi-densepose-config`](../wifi-densepose-config) | Configuration loading | +| [`wifi-densepose-db`](../wifi-densepose-db) | Database persistence | +| [`wifi-densepose-nn`](../wifi-densepose-nn) | Neural network inference | +| [`wifi-densepose-signal`](../wifi-densepose-signal) | CSI signal processing | +| [`wifi-densepose-sensing-server`](../wifi-densepose-sensing-server) | Lightweight sensing UI server | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-cli/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-cli/Cargo.toml index e3dc92d..e940b5f 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-cli/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-cli/Cargo.toml @@ -6,6 +6,10 @@ description = "CLI for WiFi-DensePose" authors.workspace = true license.workspace = true repository.workspace = true +documentation = "https://docs.rs/wifi-densepose-cli" +keywords = ["wifi", "cli", "densepose", "disaster", "detection"] +categories = ["command-line-utilities", "science"] +readme = "README.md" [[bin]] name = "wifi-densepose" @@ -17,7 +21,7 @@ mat = [] [dependencies] # Internal crates -wifi-densepose-mat = { path = "../wifi-densepose-mat" } +wifi-densepose-mat = { version = "0.1.0", path = "../wifi-densepose-mat" } # CLI framework clap = { version = "4.4", features = ["derive", "env", "cargo"] } diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-cli/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-cli/README.md new file mode 100644 index 0000000..39f3737 --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-cli/README.md @@ -0,0 +1,95 @@ +# wifi-densepose-cli + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-cli.svg)](https://crates.io/crates/wifi-densepose-cli) +[![Documentation](https://docs.rs/wifi-densepose-cli/badge.svg)](https://docs.rs/wifi-densepose-cli) +[![License](https://img.shields.io/crates/l/wifi-densepose-cli.svg)](LICENSE) + +Command-line interface for WiFi-DensePose, including the Mass Casualty Assessment Tool (MAT) for +disaster response operations. + +## Overview + +`wifi-densepose-cli` ships the `wifi-densepose` binary -- a single entry point for operating the +WiFi-DensePose system from the terminal. The primary command group is `mat`, which drives the +disaster survivor detection and triage workflow powered by the `wifi-densepose-mat` crate. + +Built with [clap](https://docs.rs/clap) for argument parsing, +[tabled](https://docs.rs/tabled) + [colored](https://docs.rs/colored) for rich terminal output, and +[indicatif](https://docs.rs/indicatif) for progress bars during scans. + +## Features + +- **Survivor scanning** -- Start continuous or one-shot scans across disaster zones with configurable + sensitivity, depth, and disaster type. +- **Triage management** -- List detected survivors sorted by triage priority (Immediate / Delayed / + Minor / Deceased / Unknown) with filtering and output format options. +- **Alert handling** -- View, acknowledge, resolve, and escalate alerts generated by the detection + pipeline. +- **Zone management** -- Add, remove, pause, and resume rectangular or circular scan zones. +- **Data export** -- Export scan results to JSON or CSV for integration with external USAR systems. +- **Simulation mode** -- Run demo scans with synthetic detections (`--simulate`) for testing and + training without hardware. +- **Multiple output formats** -- Table, JSON, and compact single-line output for scripting. + +### Feature flags + +| Flag | Default | Description | +|-------|---------|-------------| +| `mat` | yes | Enable MAT disaster detection commands | + +## Quick Start + +```bash +# Install +cargo install wifi-densepose-cli + +# Run a simulated disaster scan +wifi-densepose mat scan --disaster-type earthquake --sensitivity 0.8 --simulate + +# Check system status +wifi-densepose mat status + +# List detected survivors (sorted by triage priority) +wifi-densepose mat survivors --sort-by triage + +# View pending alerts +wifi-densepose mat alerts --pending + +# Manage scan zones +wifi-densepose mat zones add --name "Building A" --bounds 0,0,100,80 +wifi-densepose mat zones list --active + +# Export results to JSON +wifi-densepose mat export --output results.json --format json + +# Show version +wifi-densepose version +``` + +## Command Reference + +```text +wifi-densepose + mat + scan Start scanning for survivors + status Show current scan status + zones Manage scan zones (list, add, remove, pause, resume) + survivors List detected survivors with triage status + alerts View and manage alerts (list, ack, resolve, escalate) + export Export scan data to JSON or CSV + version Display version information +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-mat`](../wifi-densepose-mat) | MAT disaster detection engine | +| [`wifi-densepose-core`](../wifi-densepose-core) | Shared types and traits | +| [`wifi-densepose-signal`](../wifi-densepose-signal) | CSI signal processing | +| [`wifi-densepose-hardware`](../wifi-densepose-hardware) | ESP32 hardware interfaces | +| [`wifi-densepose-wasm`](../wifi-densepose-wasm) | Browser-based MAT dashboard | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-config/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-config/Cargo.toml index e94078f..75da7e1 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-config/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-config/Cargo.toml @@ -3,5 +3,12 @@ name = "wifi-densepose-config" version.workspace = true edition.workspace = true description = "Configuration management for WiFi-DensePose" +license.workspace = true +authors = ["rUv ", "WiFi-DensePose Contributors"] +repository.workspace = true +documentation.workspace = true +keywords = ["wifi", "configuration", "densepose", "settings", "toml"] +categories = ["config", "science"] +readme = "README.md" [dependencies] diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-config/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-config/README.md new file mode 100644 index 0000000..ffcfd5c --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-config/README.md @@ -0,0 +1,89 @@ +# wifi-densepose-config + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-config.svg)](https://crates.io/crates/wifi-densepose-config) +[![Documentation](https://docs.rs/wifi-densepose-config/badge.svg)](https://docs.rs/wifi-densepose-config) +[![License](https://img.shields.io/crates/l/wifi-densepose-config.svg)](LICENSE) + +Configuration management for the WiFi-DensePose pose estimation system. + +## Overview + +`wifi-densepose-config` provides a unified configuration layer that merges values from environment +variables, TOML/YAML files, and CLI overrides into strongly-typed Rust structs. Built on the +[config](https://docs.rs/config), [dotenvy](https://docs.rs/dotenvy), and +[envy](https://docs.rs/envy) ecosystem from the workspace. + +> **Status:** This crate is currently a stub. The intended API surface is documented below. + +## Planned Features + +- **Multi-source loading** -- Merge configuration from `.env`, TOML files, YAML files, and + environment variables with well-defined precedence. +- **Typed configuration** -- Strongly-typed structs for server, signal processing, neural network, + hardware, and database settings. +- **Validation** -- Schema validation with human-readable error messages on startup. +- **Hot reload** -- Watch configuration files for changes and notify dependent services. +- **Profile support** -- Named profiles (`development`, `production`, `testing`) with per-profile + overrides. +- **Secret filtering** -- Redact sensitive values (API keys, database passwords) in logs and debug + output. + +## Quick Start + +```rust +// Intended usage (not yet implemented) +use wifi_densepose_config::AppConfig; + +fn main() -> anyhow::Result<()> { + // Loads from env, config.toml, and CLI overrides + let config = AppConfig::load()?; + + println!("Server bind: {}", config.server.bind_address); + println!("CSI sample rate: {} Hz", config.signal.sample_rate); + println!("Model path: {}", config.nn.model_path.display()); + + Ok(()) +} +``` + +## Planned Configuration Structure + +```toml +# config.toml + +[server] +bind_address = "0.0.0.0:3000" +websocket_path = "/ws/poses" + +[signal] +sample_rate = 100 +subcarrier_count = 56 +hampel_window = 5 + +[nn] +model_path = "./models/densepose.rvf" +backend = "ort" # ort | candle | tch +batch_size = 8 + +[hardware] +esp32_udp_port = 5005 +serial_baud = 921600 + +[database] +url = "sqlite://data/wifi-densepose.db" +max_connections = 5 +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-core`](../wifi-densepose-core) | Shared types and traits | +| [`wifi-densepose-api`](../wifi-densepose-api) | REST API (consumer) | +| [`wifi-densepose-db`](../wifi-densepose-db) | Database layer (consumer) | +| [`wifi-densepose-cli`](../wifi-densepose-cli) | CLI (consumer) | +| [`wifi-densepose-sensing-server`](../wifi-densepose-sensing-server) | Sensing server (consumer) | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-core/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-core/README.md new file mode 100644 index 0000000..6c2acda --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-core/README.md @@ -0,0 +1,83 @@ +# wifi-densepose-core + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-core.svg)](https://crates.io/crates/wifi-densepose-core) +[![Documentation](https://docs.rs/wifi-densepose-core/badge.svg)](https://docs.rs/wifi-densepose-core) +[![License](https://img.shields.io/crates/l/wifi-densepose-core.svg)](LICENSE) + +Core types, traits, and utilities for the WiFi-DensePose pose estimation system. + +## Overview + +`wifi-densepose-core` is the foundation crate for the WiFi-DensePose workspace. It defines the +shared data structures, error types, and trait contracts used by every other crate in the +ecosystem. The crate is `no_std`-compatible (with the `std` feature disabled) and forbids all +unsafe code. + +## Features + +- **Core data types** -- `CsiFrame`, `ProcessedSignal`, `PoseEstimate`, `PersonPose`, `Keypoint`, + `KeypointType`, `BoundingBox`, `Confidence`, `Timestamp`, and more. +- **Trait abstractions** -- `SignalProcessor`, `NeuralInference`, and `DataStore` define the + contracts for signal processing, neural network inference, and data persistence respectively. +- **Error hierarchy** -- `CoreError`, `SignalError`, `InferenceError`, and `StorageError` provide + typed error handling across subsystem boundaries. +- **`no_std` support** -- Disable the default `std` feature for embedded or WASM targets. +- **Constants** -- `MAX_KEYPOINTS` (17, COCO format), `MAX_SUBCARRIERS` (256), + `DEFAULT_CONFIDENCE_THRESHOLD` (0.5). + +### Feature flags + +| Flag | Default | Description | +|---------|---------|--------------------------------------------| +| `std` | yes | Enable standard library support | +| `serde` | no | Serialization via serde (+ ndarray serde) | +| `async` | no | Async trait definitions via `async-trait` | + +## Quick Start + +```rust +use wifi_densepose_core::{CsiFrame, Keypoint, KeypointType, Confidence}; + +// Create a keypoint with high confidence +let keypoint = Keypoint::new( + KeypointType::Nose, + 0.5, + 0.3, + Confidence::new(0.95).unwrap(), +); + +assert!(keypoint.is_visible()); +``` + +Or use the prelude for convenient bulk imports: + +```rust +use wifi_densepose_core::prelude::*; +``` + +## Architecture + +```text +wifi-densepose-core/src/ + lib.rs -- Re-exports, constants, prelude + types.rs -- CsiFrame, PoseEstimate, Keypoint, etc. + traits.rs -- SignalProcessor, NeuralInference, DataStore + error.rs -- CoreError, SignalError, InferenceError, StorageError + utils.rs -- Shared helper functions +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-signal`](../wifi-densepose-signal) | CSI signal processing algorithms | +| [`wifi-densepose-nn`](../wifi-densepose-nn) | Neural network inference backends | +| [`wifi-densepose-train`](../wifi-densepose-train) | Training pipeline with ruvector | +| [`wifi-densepose-mat`](../wifi-densepose-mat) | Disaster detection (MAT) | +| [`wifi-densepose-hardware`](../wifi-densepose-hardware) | Hardware sensor interfaces | +| [`wifi-densepose-vitals`](../wifi-densepose-vitals) | Vital sign extraction | +| [`wifi-densepose-wifiscan`](../wifi-densepose-wifiscan) | Multi-BSSID WiFi scanning | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-db/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-db/Cargo.toml index d3db37f..5edb52d 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-db/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-db/Cargo.toml @@ -3,5 +3,12 @@ name = "wifi-densepose-db" version.workspace = true edition.workspace = true description = "Database layer for WiFi-DensePose" +license.workspace = true +authors = ["rUv ", "WiFi-DensePose Contributors"] +repository.workspace = true +documentation.workspace = true +keywords = ["wifi", "database", "storage", "densepose", "persistence"] +categories = ["database", "science"] +readme = "README.md" [dependencies] diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-db/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-db/README.md new file mode 100644 index 0000000..0fc8b66 --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-db/README.md @@ -0,0 +1,106 @@ +# wifi-densepose-db + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-db.svg)](https://crates.io/crates/wifi-densepose-db) +[![Documentation](https://docs.rs/wifi-densepose-db/badge.svg)](https://docs.rs/wifi-densepose-db) +[![License](https://img.shields.io/crates/l/wifi-densepose-db.svg)](LICENSE) + +Database persistence layer for the WiFi-DensePose pose estimation system. + +## Overview + +`wifi-densepose-db` implements the `DataStore` trait defined in `wifi-densepose-core`, providing +persistent storage for CSI frames, pose estimates, scan sessions, and alert history. The intended +backends are [SQLx](https://docs.rs/sqlx) for relational storage (PostgreSQL and SQLite) and +[Redis](https://docs.rs/redis) for real-time caching and pub/sub. + +> **Status:** This crate is currently a stub. The intended API surface is documented below. + +## Planned Features + +- **Dual backend** -- PostgreSQL for production deployments, SQLite for single-node and embedded + use. Selectable at compile time via feature flags. +- **Redis caching** -- Connection-pooled Redis for low-latency pose estimate lookups, session + state, and pub/sub event distribution. +- **Migrations** -- Embedded SQL migrations managed by SQLx, applied automatically on startup. +- **Repository pattern** -- Typed repository structs (`PoseRepository`, `SessionRepository`, + `AlertRepository`) implementing the core `DataStore` trait. +- **Connection pooling** -- Configurable pool sizes via `sqlx::PgPool` / `sqlx::SqlitePool`. +- **Transaction support** -- Scoped transactions for multi-table writes (e.g., survivor detection + plus alert creation). +- **Time-series optimisation** -- Partitioned tables and retention policies for high-frequency CSI + frame storage. + +### Planned feature flags + +| Flag | Default | Description | +|------------|---------|-------------| +| `postgres` | no | Enable PostgreSQL backend | +| `sqlite` | yes | Enable SQLite backend | +| `redis` | no | Enable Redis caching layer | + +## Quick Start + +```rust +// Intended usage (not yet implemented) +use wifi_densepose_db::{Database, PoseRepository}; +use wifi_densepose_core::PoseEstimate; + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + let db = Database::connect("sqlite://data/wifi-densepose.db").await?; + db.run_migrations().await?; + + let repo = PoseRepository::new(db.pool()); + + // Store a pose estimate + repo.insert(&pose_estimate).await?; + + // Query recent poses + let recent = repo.find_recent(10).await?; + println!("Last 10 poses: {:?}", recent); + + Ok(()) +} +``` + +## Planned Schema + +```sql +-- Core tables +CREATE TABLE csi_frames ( + id UUID PRIMARY KEY, + session_id UUID NOT NULL, + timestamp TIMESTAMPTZ NOT NULL, + subcarriers BYTEA NOT NULL, + antenna_id INTEGER NOT NULL +); + +CREATE TABLE pose_estimates ( + id UUID PRIMARY KEY, + frame_id UUID REFERENCES csi_frames(id), + timestamp TIMESTAMPTZ NOT NULL, + keypoints JSONB NOT NULL, + confidence REAL NOT NULL +); + +CREATE TABLE scan_sessions ( + id UUID PRIMARY KEY, + started_at TIMESTAMPTZ NOT NULL, + ended_at TIMESTAMPTZ, + config JSONB NOT NULL +); +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-core`](../wifi-densepose-core) | `DataStore` trait definition | +| [`wifi-densepose-config`](../wifi-densepose-config) | Database connection configuration | +| [`wifi-densepose-api`](../wifi-densepose-api) | REST API (consumer) | +| [`wifi-densepose-mat`](../wifi-densepose-mat) | Disaster detection (consumer) | +| [`wifi-densepose-signal`](../wifi-densepose-signal) | CSI signal processing | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/Cargo.toml index dba25d7..b8a3672 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/Cargo.toml @@ -4,7 +4,12 @@ version.workspace = true edition.workspace = true description = "Hardware interface abstractions for WiFi CSI sensors (ESP32, Intel 5300, Atheros)" license = "MIT OR Apache-2.0" +authors = ["rUv ", "WiFi-DensePose Contributors"] repository = "https://github.com/ruvnet/wifi-densepose" +documentation = "https://docs.rs/wifi-densepose-hardware" +keywords = ["wifi", "esp32", "csi", "hardware", "sensor"] +categories = ["hardware-support", "science"] +readme = "README.md" [features] default = ["std"] diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/README.md new file mode 100644 index 0000000..682bb10 --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-hardware/README.md @@ -0,0 +1,82 @@ +# wifi-densepose-hardware + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-hardware.svg)](https://crates.io/crates/wifi-densepose-hardware) +[![Documentation](https://docs.rs/wifi-densepose-hardware/badge.svg)](https://docs.rs/wifi-densepose-hardware) +[![License](https://img.shields.io/crates/l/wifi-densepose-hardware.svg)](LICENSE) + +Hardware interface abstractions for WiFi CSI sensors (ESP32, Intel 5300, Atheros). + +## Overview + +`wifi-densepose-hardware` provides platform-agnostic parsers for WiFi CSI data from multiple +hardware sources. All parsing operates on byte buffers with no C FFI or hardware dependencies at +compile time, making the crate fully portable and deterministic -- the same bytes in always produce +the same parsed output. + +## Features + +- **ESP32 binary parser** -- Parses ADR-018 binary CSI frames streamed over UDP from ESP32 and + ESP32-S3 devices. +- **UDP aggregator** -- Receives and aggregates CSI frames from multiple ESP32 nodes (ADR-018 + Layer 2). Provided as a standalone binary. +- **Bridge** -- Converts hardware `CsiFrame` into the `CsiData` format expected by the detection + pipeline (ADR-018 Layer 3). +- **No mock data** -- Parsers either parse real bytes or return explicit `ParseError` values. + There are no synthetic fallbacks. +- **Pure byte-buffer parsing** -- No FFI to ESP-IDF or kernel modules. Safe to compile and test + on any platform. + +### Feature flags + +| Flag | Default | Description | +|-------------|---------|--------------------------------------------| +| `std` | yes | Standard library support | +| `esp32` | no | ESP32 serial CSI frame parsing | +| `intel5300` | no | Intel 5300 CSI Tool log parsing | +| `linux-wifi`| no | Linux WiFi interface for commodity sensing | + +## Quick Start + +```rust +use wifi_densepose_hardware::{CsiFrame, Esp32CsiParser, ParseError}; + +// Parse ESP32 CSI data from raw UDP bytes +let raw_bytes: &[u8] = &[/* ADR-018 binary frame */]; +match Esp32CsiParser::parse_frame(raw_bytes) { + Ok((frame, consumed)) => { + println!("Parsed {} subcarriers ({} bytes)", + frame.subcarrier_count(), consumed); + let (amplitudes, phases) = frame.to_amplitude_phase(); + // Feed into detection pipeline... + } + Err(ParseError::InsufficientData { needed, got }) => { + eprintln!("Need {} bytes, got {}", needed, got); + } + Err(e) => eprintln!("Parse error: {}", e), +} +``` + +## Architecture + +```text +wifi-densepose-hardware/src/ + lib.rs -- Re-exports: CsiFrame, Esp32CsiParser, ParseError, CsiData + csi_frame.rs -- CsiFrame, CsiMetadata, SubcarrierData, Bandwidth, AntennaConfig + esp32_parser.rs -- Esp32CsiParser (ADR-018 binary protocol) + error.rs -- ParseError + bridge.rs -- CsiData bridge to detection pipeline + aggregator/ -- UDP multi-node frame aggregator (binary) +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-core`](../wifi-densepose-core) | Foundation types (`CsiFrame` definitions) | +| [`wifi-densepose-signal`](../wifi-densepose-signal) | Consumes parsed CSI data for processing | +| [`wifi-densepose-mat`](../wifi-densepose-mat) | Uses hardware adapters for disaster detection | +| [`wifi-densepose-vitals`](../wifi-densepose-vitals) | Vital sign extraction from parsed frames | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-mat/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-mat/Cargo.toml index 2bfe093..8d3926e 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-mat/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-mat/Cargo.toml @@ -2,12 +2,14 @@ name = "wifi-densepose-mat" version = "0.1.0" edition = "2021" -authors = ["WiFi-DensePose Team"] +authors = ["rUv ", "WiFi-DensePose Contributors"] description = "Mass Casualty Assessment Tool - WiFi-based disaster survivor detection" license = "MIT OR Apache-2.0" repository = "https://github.com/ruvnet/wifi-densepose" +documentation = "https://docs.rs/wifi-densepose-mat" keywords = ["wifi", "disaster", "rescue", "detection", "vital-signs"] categories = ["science", "algorithms"] +readme = "README.md" [features] default = ["std", "api", "ruvector"] @@ -22,9 +24,9 @@ serde = ["dep:serde", "chrono/serde", "geo/use-serde"] [dependencies] # Workspace dependencies -wifi-densepose-core = { path = "../wifi-densepose-core" } -wifi-densepose-signal = { path = "../wifi-densepose-signal" } -wifi-densepose-nn = { path = "../wifi-densepose-nn" } +wifi-densepose-core = { version = "0.1.0", path = "../wifi-densepose-core" } +wifi-densepose-signal = { version = "0.1.0", path = "../wifi-densepose-signal" } +wifi-densepose-nn = { version = "0.1.0", path = "../wifi-densepose-nn" } ruvector-solver = { workspace = true, optional = true } ruvector-temporal-tensor = { workspace = true, optional = true } diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-mat/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-mat/README.md new file mode 100644 index 0000000..0b1b99d --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-mat/README.md @@ -0,0 +1,114 @@ +# wifi-densepose-mat + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-mat.svg)](https://crates.io/crates/wifi-densepose-mat) +[![Documentation](https://docs.rs/wifi-densepose-mat/badge.svg)](https://docs.rs/wifi-densepose-mat) +[![License](https://img.shields.io/crates/l/wifi-densepose-mat.svg)](LICENSE) + +Mass Casualty Assessment Tool for WiFi-based disaster survivor detection and localization. + +## Overview + +`wifi-densepose-mat` uses WiFi Channel State Information (CSI) to detect and locate survivors +trapped in rubble, debris, or collapsed structures. The crate follows Domain-Driven Design (DDD) +with event sourcing, organized into three bounded contexts -- detection, localization, and +alerting -- plus a machine learning layer for debris penetration modeling and vital signs +classification. + +Use cases include earthquake search and rescue, building collapse response, avalanche victim +location, flood rescue operations, and mine collapse detection. + +## Features + +- **Vital signs detection** -- Breathing patterns, heartbeat signatures, and movement + classification with ensemble classifier combining all three modalities. +- **Survivor localization** -- 3D position estimation through debris via triangulation, depth + estimation, and position fusion. +- **Triage classification** -- Automatic START protocol-compatible triage with priority-based + alert generation and dispatch. +- **Event sourcing** -- All state changes emitted as domain events (`DetectionEvent`, + `AlertEvent`, `ZoneEvent`) stored in a pluggable `EventStore`. +- **ML debris model** -- Debris material classification, signal attenuation prediction, and + uncertainty-aware vital signs classification. +- **REST + WebSocket API** -- `axum`-based HTTP API for real-time monitoring dashboards. +- **ruvector integration** -- `ruvector-solver` for triangulation math, `ruvector-temporal-tensor` + for compressed CSI buffering. + +### Feature flags + +| Flag | Default | Description | +|---------------|---------|----------------------------------------------------| +| `std` | yes | Standard library support | +| `api` | yes | REST + WebSocket API (enables serde for all types) | +| `ruvector` | yes | ruvector-solver and ruvector-temporal-tensor | +| `serde` | no | Serialization (also enabled by `api`) | +| `portable` | no | Low-power mode for field-deployable devices | +| `distributed` | no | Multi-node distributed scanning | +| `drone` | no | Drone-mounted scanning (implies `distributed`) | + +## Quick Start + +```rust +use wifi_densepose_mat::{ + DisasterResponse, DisasterConfig, DisasterType, + ScanZone, ZoneBounds, +}; + +#[tokio::main] +async fn main() -> anyhow::Result<()> { + let config = DisasterConfig::builder() + .disaster_type(DisasterType::Earthquake) + .sensitivity(0.8) + .build(); + + let mut response = DisasterResponse::new(config); + + // Define scan zone + let zone = ScanZone::new( + "Building A - North Wing", + ZoneBounds::rectangle(0.0, 0.0, 50.0, 30.0), + ); + response.add_zone(zone)?; + + // Start scanning + response.start_scanning().await?; + + Ok(()) +} +``` + +## Architecture + +```text +wifi-densepose-mat/src/ + lib.rs -- DisasterResponse coordinator, config builder, MatError + domain/ + survivor.rs -- Survivor aggregate root + disaster_event.rs -- DisasterEvent, DisasterType + scan_zone.rs -- ScanZone, ZoneBounds + alert.rs -- Alert, Priority + vital_signs.rs -- VitalSignsReading, BreathingPattern, HeartbeatSignature + triage.rs -- TriageStatus, TriageCalculator (START protocol) + coordinates.rs -- Coordinates3D, LocationUncertainty + events.rs -- DomainEvent, EventStore, InMemoryEventStore + detection/ -- BreathingDetector, HeartbeatDetector, MovementClassifier, EnsembleClassifier + localization/ -- Triangulator, DepthEstimator, PositionFuser + alerting/ -- AlertGenerator, AlertDispatcher, TriageService + ml/ -- DebrisPenetrationModel, VitalSignsClassifier, UncertaintyEstimate + api/ -- axum REST + WebSocket router + integration/ -- SignalAdapter, NeuralAdapter, HardwareAdapter +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-core`](../wifi-densepose-core) | Foundation types and traits | +| [`wifi-densepose-signal`](../wifi-densepose-signal) | CSI preprocessing for detection pipeline | +| [`wifi-densepose-nn`](../wifi-densepose-nn) | Neural inference for ML models | +| [`wifi-densepose-hardware`](../wifi-densepose-hardware) | Hardware sensor data ingestion | +| [`ruvector-solver`](https://crates.io/crates/ruvector-solver) | Triangulation and position math | +| [`ruvector-temporal-tensor`](https://crates.io/crates/ruvector-temporal-tensor) | Compressed CSI buffering | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-nn/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-nn/Cargo.toml index da011b8..241b08a 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-nn/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-nn/Cargo.toml @@ -9,6 +9,7 @@ documentation.workspace = true keywords = ["neural-network", "onnx", "inference", "densepose", "deep-learning"] categories = ["science", "computer-vision"] description = "Neural network inference for WiFi-DensePose pose estimation" +readme = "README.md" [features] default = ["onnx"] diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-nn/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-nn/README.md new file mode 100644 index 0000000..463125b --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-nn/README.md @@ -0,0 +1,89 @@ +# wifi-densepose-nn + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-nn.svg)](https://crates.io/crates/wifi-densepose-nn) +[![Documentation](https://docs.rs/wifi-densepose-nn/badge.svg)](https://docs.rs/wifi-densepose-nn) +[![License](https://img.shields.io/crates/l/wifi-densepose-nn.svg)](LICENSE) + +Multi-backend neural network inference for WiFi-based DensePose estimation. + +## Overview + +`wifi-densepose-nn` provides the inference engine that maps processed WiFi CSI features to +DensePose body surface predictions. It supports three backends -- ONNX Runtime (default), +PyTorch via `tch-rs`, and Candle -- so models can run on CPU, CUDA GPU, or TensorRT depending +on the deployment target. + +The crate implements two key neural components: + +- **DensePose Head** -- Predicts 24 body part segmentation masks and per-part UV coordinate + regression. +- **Modality Translator** -- Translates CSI feature embeddings into visual feature space, + bridging the domain gap between WiFi signals and image-based pose estimation. + +## Features + +- **ONNX Runtime backend** (default) -- Load and run `.onnx` models with CPU or GPU execution + providers. +- **PyTorch backend** (`tch-backend`) -- Native PyTorch inference via libtorch FFI. +- **Candle backend** (`candle-backend`) -- Pure-Rust inference with `candle-core` and + `candle-nn`. +- **CUDA acceleration** (`cuda`) -- GPU execution for supported backends. +- **TensorRT optimization** (`tensorrt`) -- INT8/FP16 optimized inference via ONNX Runtime. +- **Batched inference** -- Process multiple CSI frames in a single forward pass. +- **Model caching** -- Memory-mapped model weights via `memmap2`. + +### Feature flags + +| Flag | Default | Description | +|-------------------|---------|-------------------------------------| +| `onnx` | yes | ONNX Runtime backend | +| `tch-backend` | no | PyTorch (tch-rs) backend | +| `candle-backend` | no | Candle pure-Rust backend | +| `cuda` | no | CUDA GPU acceleration | +| `tensorrt` | no | TensorRT via ONNX Runtime | +| `all-backends` | no | Enable onnx + tch + candle together | + +## Quick Start + +```rust +use wifi_densepose_nn::{InferenceEngine, DensePoseConfig, OnnxBackend}; + +// Create inference engine with ONNX backend +let config = DensePoseConfig::default(); +let backend = OnnxBackend::from_file("model.onnx")?; +let engine = InferenceEngine::new(backend, config)?; + +// Run inference on a CSI feature tensor +let input = ndarray::Array4::zeros((1, 256, 64, 64)); +let output = engine.infer(&input)?; + +println!("Body parts: {}", output.body_parts.shape()[1]); // 24 +``` + +## Architecture + +```text +wifi-densepose-nn/src/ + lib.rs -- Re-exports, constants (NUM_BODY_PARTS=24), prelude + densepose.rs -- DensePoseHead, DensePoseConfig, DensePoseOutput + inference.rs -- Backend trait, InferenceEngine, InferenceOptions + onnx.rs -- OnnxBackend, OnnxSession (feature-gated) + tensor.rs -- Tensor, TensorShape utilities + translator.rs -- ModalityTranslator (CSI -> visual space) + error.rs -- NnError, NnResult +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-core`](../wifi-densepose-core) | Foundation types and `NeuralInference` trait | +| [`wifi-densepose-signal`](../wifi-densepose-signal) | Produces CSI features consumed by inference | +| [`wifi-densepose-train`](../wifi-densepose-train) | Trains the models this crate loads | +| [`ort`](https://crates.io/crates/ort) | ONNX Runtime Rust bindings | +| [`tch`](https://crates.io/crates/tch) | PyTorch Rust bindings | +| [`candle-core`](https://crates.io/crates/candle-core) | Hugging Face pure-Rust ML framework | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-sensing-server/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-sensing-server/Cargo.toml index 64539f9..6c07e68 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-sensing-server/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-sensing-server/Cargo.toml @@ -4,6 +4,12 @@ version.workspace = true edition.workspace = true description = "Lightweight Axum server for WiFi sensing UI with RuVector signal processing" license.workspace = true +authors = ["rUv ", "WiFi-DensePose Contributors"] +repository.workspace = true +documentation = "https://docs.rs/wifi-densepose-sensing-server" +keywords = ["wifi", "sensing", "server", "websocket", "csi"] +categories = ["web-programming::http-server", "science"] +readme = "README.md" [lib] name = "wifi_densepose_sensing_server" @@ -35,7 +41,7 @@ chrono = { version = "0.4", features = ["serde"] } clap = { workspace = true } # Multi-BSSID WiFi scanning pipeline (ADR-022 Phase 3) -wifi-densepose-wifiscan = { path = "../wifi-densepose-wifiscan" } +wifi-densepose-wifiscan = { version = "0.1.0", path = "../wifi-densepose-wifiscan" } [dev-dependencies] tempfile = "3.10" diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-sensing-server/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-sensing-server/README.md new file mode 100644 index 0000000..dd8ae39 --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-sensing-server/README.md @@ -0,0 +1,124 @@ +# wifi-densepose-sensing-server + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-sensing-server.svg)](https://crates.io/crates/wifi-densepose-sensing-server) +[![Documentation](https://docs.rs/wifi-densepose-sensing-server/badge.svg)](https://docs.rs/wifi-densepose-sensing-server) +[![License](https://img.shields.io/crates/l/wifi-densepose-sensing-server.svg)](LICENSE) + +Lightweight Axum server for real-time WiFi sensing with RuVector signal processing. + +## Overview + +`wifi-densepose-sensing-server` is the operational backend for WiFi-DensePose. It receives raw CSI +frames from ESP32 hardware over UDP, runs them through the RuVector-powered signal processing +pipeline, and broadcasts processed sensing updates to browser clients via WebSocket. A built-in +static file server hosts the sensing UI on the same port. + +The crate ships both a library (`wifi_densepose_sensing_server`) exposing the training and inference +modules, and a binary (`sensing-server`) that starts the full server stack. + +Integrates [wifi-densepose-wifiscan](../wifi-densepose-wifiscan) for multi-BSSID WiFi scanning +per ADR-022 Phase 3. + +## Features + +- **UDP CSI ingestion** -- Receives ESP32 CSI frames on port 5005 and parses them into the internal + `CsiFrame` representation. +- **Vital sign detection** -- Pure-Rust FFT-based breathing rate (0.1--0.5 Hz) and heart rate + (0.67--2.0 Hz) estimation from CSI amplitude time series (ADR-021). +- **RVF container** -- Standalone binary container format for packaging model weights, metadata, and + configuration into a single `.rvf` file with 64-byte aligned segments. +- **RVF pipeline** -- Progressive model loading with streaming segment decoding. +- **Graph Transformer** -- Cross-attention bottleneck between antenna-space CSI features and the + COCO 17-keypoint body graph, followed by GCN message passing (ADR-023 Phase 2). Pure `std`, no ML + dependencies. +- **SONA adaptation** -- LoRA + EWC++ online adaptation for environment drift without catastrophic + forgetting (ADR-023 Phase 5). +- **Contrastive CSI embeddings** -- Self-supervised SimCLR-style pretraining with InfoNCE loss, + projection head, fingerprint indexing, and cross-modal pose alignment (ADR-024). +- **Sparse inference** -- Activation profiling, sparse matrix-vector multiply, INT8/FP16 + quantization, and a full sparse inference engine for edge deployment (ADR-023 Phase 6). +- **Dataset pipeline** -- Training dataset loading and batching. +- **Multi-BSSID scanning** -- Windows `netsh` integration for BSSID discovery via + `wifi-densepose-wifiscan` (ADR-022). +- **WebSocket broadcast** -- Real-time sensing updates pushed to all connected clients at + `ws://localhost:8765/ws/sensing`. +- **Static file serving** -- Hosts the sensing UI on port 8080 with CORS headers. + +## Modules + +| Module | Description | +|--------|-------------| +| `vital_signs` | Breathing and heart rate extraction via FFT spectral analysis | +| `rvf_container` | RVF binary format builder and reader | +| `rvf_pipeline` | Progressive model loading from RVF containers | +| `graph_transformer` | Graph Transformer + GCN for CSI-to-pose estimation | +| `trainer` | Training loop orchestration | +| `dataset` | Training data loading and batching | +| `sona` | LoRA adapters and EWC++ continual learning | +| `sparse_inference` | Neuron profiling, sparse matmul, INT8/FP16 quantization | +| `embedding` | Contrastive CSI embedding model and fingerprint index | + +## Quick Start + +```bash +# Build the server +cargo build -p wifi-densepose-sensing-server + +# Run with default settings (HTTP :8080, UDP :5005, WS :8765) +cargo run -p wifi-densepose-sensing-server + +# Run with custom ports +cargo run -p wifi-densepose-sensing-server -- \ + --http-port 9000 \ + --udp-port 5005 \ + --static-dir ./ui +``` + +### Using as a library + +```rust +use wifi_densepose_sensing_server::vital_signs::VitalSignDetector; + +// Create a detector with 20 Hz sample rate +let mut detector = VitalSignDetector::new(20.0); + +// Feed CSI amplitude samples +for amplitude in csi_amplitudes.iter() { + detector.push_sample(*amplitude); +} + +// Extract vital signs +if let Some(vitals) = detector.detect() { + println!("Breathing: {:.1} BPM", vitals.breathing_rate_bpm); + println!("Heart rate: {:.0} BPM", vitals.heart_rate_bpm); +} +``` + +## Architecture + +```text +ESP32 ──UDP:5005──> [ CSI Receiver ] + | + [ Signal Pipeline ] + (vital_signs, graph_transformer, sona) + | + [ WebSocket Broadcast ] + | +Browser <──WS:8765── [ Axum Server :8080 ] ──> Static UI files +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-wifiscan`](../wifi-densepose-wifiscan) | Multi-BSSID WiFi scanning (ADR-022) | +| [`wifi-densepose-core`](../wifi-densepose-core) | Shared types and traits | +| [`wifi-densepose-signal`](../wifi-densepose-signal) | CSI signal processing algorithms | +| [`wifi-densepose-hardware`](../wifi-densepose-hardware) | ESP32 hardware interfaces | +| [`wifi-densepose-wasm`](../wifi-densepose-wasm) | Browser WASM bindings for the sensing UI | +| [`wifi-densepose-train`](../wifi-densepose-train) | Full training pipeline with ruvector | +| [`wifi-densepose-mat`](../wifi-densepose-mat) | Disaster detection module | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/Cargo.toml index 8aa7ee6..06017a5 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/Cargo.toml @@ -4,6 +4,12 @@ version.workspace = true edition.workspace = true description = "WiFi CSI signal processing for DensePose estimation" license.workspace = true +authors = ["rUv ", "WiFi-DensePose Contributors"] +repository.workspace = true +documentation = "https://docs.rs/wifi-densepose-signal" +keywords = ["wifi", "csi", "signal-processing", "densepose", "rust"] +categories = ["science", "computer-vision"] +readme = "README.md" [dependencies] # Core utilities @@ -27,7 +33,7 @@ ruvector-attention = { workspace = true } ruvector-solver = { workspace = true } # Internal -wifi-densepose-core = { path = "../wifi-densepose-core" } +wifi-densepose-core = { version = "0.1.0", path = "../wifi-densepose-core" } [dev-dependencies] criterion = { version = "0.5", features = ["html_reports"] } diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/README.md new file mode 100644 index 0000000..66b1cd2 --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/README.md @@ -0,0 +1,86 @@ +# wifi-densepose-signal + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-signal.svg)](https://crates.io/crates/wifi-densepose-signal) +[![Documentation](https://docs.rs/wifi-densepose-signal/badge.svg)](https://docs.rs/wifi-densepose-signal) +[![License](https://img.shields.io/crates/l/wifi-densepose-signal.svg)](LICENSE) + +State-of-the-art WiFi CSI signal processing for human pose estimation. + +## Overview + +`wifi-densepose-signal` implements six peer-reviewed signal processing algorithms that extract +human motion features from raw WiFi Channel State Information (CSI). Each algorithm is traced +back to its original publication and integrated with the +[ruvector](https://crates.io/crates/ruvector-mincut) family of crates for high-performance +graph and attention operations. + +## Algorithms + +| Algorithm | Module | Reference | +|-----------|--------|-----------| +| Conjugate Multiplication | `csi_ratio` | SpotFi, SIGCOMM 2015 | +| Hampel Filter | `hampel` | WiGest, 2015 | +| Fresnel Zone Model | `fresnel` | FarSense, MobiCom 2019 | +| CSI Spectrogram | `spectrogram` | Common in WiFi sensing literature since 2018 | +| Subcarrier Selection | `subcarrier_selection` | WiDance, MobiCom 2017 | +| Body Velocity Profile (BVP) | `bvp` | Widar 3.0, MobiSys 2019 | + +## Features + +- **CSI preprocessing** -- Noise removal, windowing, normalization via `CsiProcessor`. +- **Phase sanitization** -- Unwrapping, outlier removal, and smoothing via `PhaseSanitizer`. +- **Feature extraction** -- Amplitude, phase, correlation, Doppler, and PSD features. +- **Motion detection** -- Human presence detection with confidence scoring via `MotionDetector`. +- **ruvector integration** -- Graph min-cut (person matching), attention mechanisms (antenna and + spatial attention), and sparse solvers (subcarrier interpolation). + +## Quick Start + +```rust +use wifi_densepose_signal::{ + CsiProcessor, CsiProcessorConfig, + PhaseSanitizer, PhaseSanitizerConfig, + MotionDetector, +}; + +// Configure and create a CSI processor +let config = CsiProcessorConfig::builder() + .sampling_rate(1000.0) + .window_size(256) + .overlap(0.5) + .noise_threshold(-30.0) + .build(); + +let processor = CsiProcessor::new(config); +``` + +## Architecture + +```text +wifi-densepose-signal/src/ + lib.rs -- Re-exports, SignalError, prelude + bvp.rs -- Body Velocity Profile (Widar 3.0) + csi_processor.rs -- Core preprocessing pipeline + csi_ratio.rs -- Conjugate multiplication (SpotFi) + features.rs -- Amplitude/phase/Doppler/PSD feature extraction + fresnel.rs -- Fresnel zone diffraction model + hampel.rs -- Hampel outlier filter + motion.rs -- Motion and human presence detection + phase_sanitizer.rs -- Phase unwrapping and sanitization + spectrogram.rs -- Time-frequency CSI spectrograms + subcarrier_selection.rs -- Variance-based subcarrier selection +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-core`](../wifi-densepose-core) | Foundation types and traits | +| [`ruvector-mincut`](https://crates.io/crates/ruvector-mincut) | Graph min-cut for person matching | +| [`ruvector-attn-mincut`](https://crates.io/crates/ruvector-attn-mincut) | Attention-weighted min-cut | +| [`ruvector-attention`](https://crates.io/crates/ruvector-attention) | Spatial attention for CSI | +| [`ruvector-solver`](https://crates.io/crates/ruvector-solver) | Sparse interpolation solver | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-train/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-train/Cargo.toml index c6c3f40..a8e4151 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-train/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-train/Cargo.toml @@ -2,10 +2,14 @@ name = "wifi-densepose-train" version = "0.1.0" edition = "2021" -authors = ["WiFi-DensePose Contributors"] +authors = ["rUv ", "WiFi-DensePose Contributors"] license = "MIT OR Apache-2.0" description = "Training pipeline for WiFi-DensePose pose estimation" +repository = "https://github.com/ruvnet/wifi-densepose" +documentation = "https://docs.rs/wifi-densepose-train" keywords = ["wifi", "training", "pose-estimation", "deep-learning"] +categories = ["science", "computer-vision"] +readme = "README.md" [[bin]] name = "train" @@ -23,8 +27,8 @@ cuda = ["tch-backend"] [dependencies] # Internal crates -wifi-densepose-signal = { path = "../wifi-densepose-signal" } -wifi-densepose-nn = { path = "../wifi-densepose-nn" } +wifi-densepose-signal = { version = "0.1.0", path = "../wifi-densepose-signal" } +wifi-densepose-nn = { version = "0.1.0", path = "../wifi-densepose-nn" } # Core thiserror.workspace = true diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-train/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-train/README.md new file mode 100644 index 0000000..4610f7b --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-train/README.md @@ -0,0 +1,99 @@ +# wifi-densepose-train + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-train.svg)](https://crates.io/crates/wifi-densepose-train) +[![Documentation](https://docs.rs/wifi-densepose-train/badge.svg)](https://docs.rs/wifi-densepose-train) +[![License](https://img.shields.io/crates/l/wifi-densepose-train.svg)](LICENSE) + +Complete training pipeline for WiFi-DensePose, integrated with all five ruvector crates. + +## Overview + +`wifi-densepose-train` provides everything needed to train the WiFi-to-DensePose model: dataset +loading, subcarrier interpolation, loss functions, evaluation metrics, and the training loop +orchestrator. It supports both the MM-Fi dataset (NeurIPS 2023) and deterministic synthetic data +for reproducible experiments. + +Without the `tch-backend` feature the crate still provides the dataset, configuration, and +subcarrier interpolation APIs needed for data preprocessing and proof verification. + +## Features + +- **MM-Fi dataset loader** -- Reads the MM-Fi multimodal dataset (NeurIPS 2023) from disk with + memory-mapped `.npy` files. +- **Synthetic dataset** -- Deterministic, fixed-seed CSI generation for unit tests and proofs. +- **Subcarrier interpolation** -- 114 -> 56 subcarrier compression via `ruvector-solver` sparse + interpolation with variance-based selection. +- **Loss functions** (`tch-backend`) -- Pose estimation losses including MSE, OKS, and combined + multi-task loss. +- **Metrics** (`tch-backend`) -- PCKh, OKS-AP, and per-keypoint evaluation with + `ruvector-mincut`-based person matching. +- **Training orchestrator** (`tch-backend`) -- Full training loop with learning rate scheduling, + gradient clipping, checkpointing, and reproducible proofs. +- **All 5 ruvector crates** -- `ruvector-mincut`, `ruvector-attn-mincut`, + `ruvector-temporal-tensor`, `ruvector-solver`, and `ruvector-attention` integrated across + dataset loading, metrics, and model attention. + +### Feature flags + +| Flag | Default | Description | +|---------------|---------|----------------------------------------| +| `tch-backend` | no | Enable PyTorch training via `tch-rs` | +| `cuda` | no | CUDA GPU acceleration (implies `tch`) | + +### Binaries + +| Binary | Description | +|--------------------|------------------------------------------| +| `train` | Main training entry point | +| `verify-training` | Proof verification (requires `tch-backend`) | + +## Quick Start + +```rust +use wifi_densepose_train::config::TrainingConfig; +use wifi_densepose_train::dataset::{SyntheticCsiDataset, SyntheticConfig, CsiDataset}; + +// Build and validate config +let config = TrainingConfig::default(); +config.validate().expect("config is valid"); + +// Create a synthetic dataset (deterministic, fixed-seed) +let syn_cfg = SyntheticConfig::default(); +let dataset = SyntheticCsiDataset::new(200, syn_cfg); + +// Load one sample +let sample = dataset.get(0).unwrap(); +println!("amplitude shape: {:?}", sample.amplitude.shape()); +``` + +## Architecture + +```text +wifi-densepose-train/src/ + lib.rs -- Re-exports, VERSION + config.rs -- TrainingConfig, hyperparameters, validation + dataset.rs -- CsiDataset trait, MmFiDataset, SyntheticCsiDataset, DataLoader + error.rs -- TrainError, ConfigError, DatasetError, SubcarrierError + subcarrier.rs -- interpolate_subcarriers (114->56), variance-based selection + losses.rs -- (tch) MSE, OKS, multi-task loss [feature-gated] + metrics.rs -- (tch) PCKh, OKS-AP, person matching [feature-gated] + model.rs -- (tch) Model definition with attention [feature-gated] + proof.rs -- (tch) Deterministic training proofs [feature-gated] + trainer.rs -- (tch) Training loop orchestrator [feature-gated] +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-signal`](../wifi-densepose-signal) | Signal preprocessing consumed by dataset loaders | +| [`wifi-densepose-nn`](../wifi-densepose-nn) | Inference engine that loads trained models | +| [`ruvector-mincut`](https://crates.io/crates/ruvector-mincut) | Person matching in metrics | +| [`ruvector-attn-mincut`](https://crates.io/crates/ruvector-attn-mincut) | Attention-weighted graph cuts | +| [`ruvector-temporal-tensor`](https://crates.io/crates/ruvector-temporal-tensor) | Compressed CSI buffering in datasets | +| [`ruvector-solver`](https://crates.io/crates/ruvector-solver) | Sparse subcarrier interpolation | +| [`ruvector-attention`](https://crates.io/crates/ruvector-attention) | Spatial attention in model | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-vitals/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-vitals/Cargo.toml index 2db03c7..6f420bf 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-vitals/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-vitals/Cargo.toml @@ -4,6 +4,12 @@ version.workspace = true edition.workspace = true description = "ESP32 CSI-grade vital sign extraction (ADR-021): heart rate and respiratory rate from WiFi Channel State Information" license.workspace = true +authors = ["rUv ", "WiFi-DensePose Contributors"] +repository.workspace = true +documentation = "https://docs.rs/wifi-densepose-vitals" +keywords = ["wifi", "vital-signs", "breathing", "heart-rate", "csi"] +categories = ["science", "computer-vision"] +readme = "README.md" [dependencies] tracing.workspace = true diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-vitals/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-vitals/README.md new file mode 100644 index 0000000..28a9571 --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-vitals/README.md @@ -0,0 +1,102 @@ +# wifi-densepose-vitals + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-vitals.svg)](https://crates.io/crates/wifi-densepose-vitals) +[![Documentation](https://docs.rs/wifi-densepose-vitals/badge.svg)](https://docs.rs/wifi-densepose-vitals) +[![License](https://img.shields.io/crates/l/wifi-densepose-vitals.svg)](LICENSE) + +ESP32 CSI-grade vital sign extraction: heart rate and respiratory rate from WiFi Channel State +Information (ADR-021). + +## Overview + +`wifi-densepose-vitals` implements a four-stage pipeline that extracts respiratory rate and heart +rate from multi-subcarrier CSI amplitude and phase data. The crate has zero external dependencies +beyond `tracing` (and optional `serde`), uses `#[forbid(unsafe_code)]`, and is designed for +resource-constrained edge deployments alongside ESP32 hardware. + +## Pipeline Stages + +1. **Preprocessing** (`CsiVitalPreprocessor`) -- EMA-based static component suppression, + producing per-subcarrier residuals that isolate body-induced signal variation. +2. **Breathing extraction** (`BreathingExtractor`) -- Bandpass filtering at 0.1--0.5 Hz with + zero-crossing analysis for respiratory rate estimation. +3. **Heart rate extraction** (`HeartRateExtractor`) -- Bandpass filtering at 0.8--2.0 Hz with + autocorrelation peak detection and inter-subcarrier phase coherence weighting. +4. **Anomaly detection** (`VitalAnomalyDetector`) -- Z-score analysis using Welford running + statistics for real-time clinical alerts (apnea, tachycardia, bradycardia). + +Results are stored in a `VitalSignStore` with configurable retention for historical trend +analysis. + +### Feature flags + +| Flag | Default | Description | +|---------|---------|------------------------------------------| +| `serde` | yes | Serialization for vital sign types | + +## Quick Start + +```rust +use wifi_densepose_vitals::{ + CsiVitalPreprocessor, BreathingExtractor, HeartRateExtractor, + VitalAnomalyDetector, VitalSignStore, CsiFrame, + VitalReading, VitalEstimate, VitalStatus, +}; + +let mut preprocessor = CsiVitalPreprocessor::new(56, 0.05); +let mut breathing = BreathingExtractor::new(56, 100.0, 30.0); +let mut heartrate = HeartRateExtractor::new(56, 100.0, 15.0); +let mut anomaly = VitalAnomalyDetector::default_config(); +let mut store = VitalSignStore::new(3600); + +// Process a CSI frame +let frame = CsiFrame { + amplitudes: vec![1.0; 56], + phases: vec![0.0; 56], + n_subcarriers: 56, + sample_index: 0, + sample_rate_hz: 100.0, +}; + +if let Some(residuals) = preprocessor.process(&frame) { + let weights = vec![1.0 / 56.0; 56]; + let rr = breathing.extract(&residuals, &weights); + let hr = heartrate.extract(&residuals, &frame.phases); + + let reading = VitalReading { + respiratory_rate: rr.unwrap_or_else(VitalEstimate::unavailable), + heart_rate: hr.unwrap_or_else(VitalEstimate::unavailable), + subcarrier_count: frame.n_subcarriers, + signal_quality: 0.9, + timestamp_secs: 0.0, + }; + + let alerts = anomaly.check(&reading); + store.push(reading); +} +``` + +## Architecture + +```text +wifi-densepose-vitals/src/ + lib.rs -- Re-exports, module declarations + types.rs -- CsiFrame, VitalReading, VitalEstimate, VitalStatus + preprocessor.rs -- CsiVitalPreprocessor (EMA static suppression) + breathing.rs -- BreathingExtractor (0.1-0.5 Hz bandpass) + heartrate.rs -- HeartRateExtractor (0.8-2.0 Hz autocorrelation) + anomaly.rs -- VitalAnomalyDetector (Z-score, Welford stats) + store.rs -- VitalSignStore, VitalStats (historical retention) +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-hardware`](../wifi-densepose-hardware) | Provides raw CSI frames from ESP32 | +| [`wifi-densepose-mat`](../wifi-densepose-mat) | Uses vital signs for survivor triage | +| [`wifi-densepose-signal`](../wifi-densepose-signal) | Advanced signal processing algorithms | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm/Cargo.toml index ea80036..9ebadfa 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm/Cargo.toml @@ -4,7 +4,12 @@ version.workspace = true edition.workspace = true description = "WebAssembly bindings for WiFi-DensePose" license = "MIT OR Apache-2.0" +authors = ["rUv ", "WiFi-DensePose Contributors"] repository = "https://github.com/ruvnet/wifi-densepose" +documentation = "https://docs.rs/wifi-densepose-wasm" +keywords = ["wifi", "wasm", "webassembly", "densepose", "browser"] +categories = ["wasm", "web-programming"] +readme = "README.md" [lib] crate-type = ["cdylib", "rlib"] @@ -54,7 +59,7 @@ uuid = { version = "1.6", features = ["v4", "serde", "js"] } getrandom = { version = "0.2", features = ["js"] } # Optional: wifi-densepose-mat integration -wifi-densepose-mat = { path = "../wifi-densepose-mat", optional = true, features = ["serde"] } +wifi-densepose-mat = { version = "0.1.0", path = "../wifi-densepose-mat", optional = true, features = ["serde"] } [dev-dependencies] wasm-bindgen-test = "0.3" diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm/README.md new file mode 100644 index 0000000..bde62f7 --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-wasm/README.md @@ -0,0 +1,128 @@ +# wifi-densepose-wasm + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-wasm.svg)](https://crates.io/crates/wifi-densepose-wasm) +[![Documentation](https://docs.rs/wifi-densepose-wasm/badge.svg)](https://docs.rs/wifi-densepose-wasm) +[![License](https://img.shields.io/crates/l/wifi-densepose-wasm.svg)](LICENSE) + +WebAssembly bindings for running WiFi-DensePose directly in the browser. + +## Overview + +`wifi-densepose-wasm` compiles the WiFi-DensePose stack to `wasm32-unknown-unknown` and exposes a +JavaScript API via [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/). The primary export is +`MatDashboard` -- a fully client-side disaster response dashboard that manages scan zones, tracks +survivors, generates triage alerts, and renders to an HTML Canvas element. + +The crate also provides utility functions (`init`, `getVersion`, `isMatEnabled`, `getTimestamp`) and +a logging bridge that routes Rust `log` output to the browser console. + +## Features + +- **MatDashboard** -- Create disaster events, add rectangular and circular scan zones, subscribe to + survivor-detected and alert-generated callbacks, and render zone/survivor overlays on Canvas. +- **Real-time callbacks** -- Register JavaScript closures for `onSurvivorDetected` and + `onAlertGenerated` events, called from the Rust event loop. +- **Canvas rendering** -- Draw zone boundaries, survivor markers (colour-coded by triage status), + and alert indicators directly to a `CanvasRenderingContext2d`. +- **WebSocket integration** -- Connect to a sensing server for live CSI data via `web-sys` WebSocket + bindings. +- **Panic hook** -- `console_error_panic_hook` provides human-readable stack traces in the browser + console on panic. +- **Optimised WASM** -- Release profile uses `-O4` wasm-opt with mutable globals for minimal binary + size. + +### Feature flags + +| Flag | Default | Description | +|----------------------------|---------|-------------| +| `console_error_panic_hook` | yes | Better panic messages in the browser console | +| `mat` | no | Enable MAT disaster detection dashboard | + +## Quick Start + +### Build + +```bash +# Build with wasm-pack (recommended) +wasm-pack build --target web --features mat + +# Or with cargo directly +cargo build --target wasm32-unknown-unknown --features mat +``` + +### JavaScript Usage + +```javascript +import init, { + MatDashboard, + initLogging, + getVersion, + isMatEnabled, +} from './wifi_densepose_wasm.js'; + +async function main() { + await init(); + initLogging('info'); + + console.log('Version:', getVersion()); + console.log('MAT enabled:', isMatEnabled()); + + const dashboard = new MatDashboard(); + + // Create a disaster event + const eventId = dashboard.createEvent( + 'earthquake', 37.7749, -122.4194, 'Bay Area Earthquake' + ); + + // Add scan zones + dashboard.addRectangleZone('Building A', 50, 50, 200, 150); + dashboard.addCircleZone('Search Area B', 400, 200, 80); + + // Subscribe to real-time events + dashboard.onSurvivorDetected((survivor) => { + console.log('Survivor:', survivor); + }); + + dashboard.onAlertGenerated((alert) => { + console.log('Alert:', alert); + }); + + // Render to canvas + const canvas = document.getElementById('map'); + const ctx = canvas.getContext('2d'); + + function render() { + ctx.clearRect(0, 0, canvas.width, canvas.height); + dashboard.renderZones(ctx); + dashboard.renderSurvivors(ctx); + requestAnimationFrame(render); + } + render(); +} + +main(); +``` + +## Exported API + +| Export | Kind | Description | +|--------|------|-------------| +| `init()` | Function | Initialise the WASM module (called automatically via `wasm_bindgen(start)`) | +| `initLogging(level)` | Function | Set log level: `trace`, `debug`, `info`, `warn`, `error` | +| `getVersion()` | Function | Return the crate version string | +| `isMatEnabled()` | Function | Check whether the MAT feature is compiled in | +| `getTimestamp()` | Function | High-resolution timestamp via `Performance.now()` | +| `MatDashboard` | Class | Disaster response dashboard (zones, survivors, alerts, rendering) | + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-mat`](../wifi-densepose-mat) | MAT engine (linked when `mat` feature enabled) | +| [`wifi-densepose-core`](../wifi-densepose-core) | Shared types and traits | +| [`wifi-densepose-cli`](../wifi-densepose-cli) | Terminal-based MAT interface | +| [`wifi-densepose-sensing-server`](../wifi-densepose-sensing-server) | Backend sensing server for WebSocket data | + +## License + +MIT OR Apache-2.0 diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-wifiscan/Cargo.toml b/rust-port/wifi-densepose-rs/crates/wifi-densepose-wifiscan/Cargo.toml index 01bb7b6..4158655 100644 --- a/rust-port/wifi-densepose-rs/crates/wifi-densepose-wifiscan/Cargo.toml +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-wifiscan/Cargo.toml @@ -4,6 +4,12 @@ version.workspace = true edition.workspace = true description = "Multi-BSSID WiFi scanning domain layer for enhanced Windows WiFi DensePose sensing (ADR-022)" license.workspace = true +authors = ["rUv ", "WiFi-DensePose Contributors"] +repository.workspace = true +documentation = "https://docs.rs/wifi-densepose-wifiscan" +keywords = ["wifi", "bssid", "scanning", "windows", "sensing"] +categories = ["science", "computer-vision"] +readme = "README.md" [dependencies] # Logging diff --git a/rust-port/wifi-densepose-rs/crates/wifi-densepose-wifiscan/README.md b/rust-port/wifi-densepose-rs/crates/wifi-densepose-wifiscan/README.md new file mode 100644 index 0000000..fe90c6b --- /dev/null +++ b/rust-port/wifi-densepose-rs/crates/wifi-densepose-wifiscan/README.md @@ -0,0 +1,98 @@ +# wifi-densepose-wifiscan + +[![Crates.io](https://img.shields.io/crates/v/wifi-densepose-wifiscan.svg)](https://crates.io/crates/wifi-densepose-wifiscan) +[![Documentation](https://docs.rs/wifi-densepose-wifiscan/badge.svg)](https://docs.rs/wifi-densepose-wifiscan) +[![License](https://img.shields.io/crates/l/wifi-densepose-wifiscan.svg)](LICENSE) + +Multi-BSSID WiFi scanning for Windows-enhanced DensePose sensing (ADR-022). + +## Overview + +`wifi-densepose-wifiscan` implements the BSSID Acquisition bounded context for the WiFi-DensePose +system. It discovers and tracks nearby WiFi access points, parses platform-specific scan output, +and feeds multi-AP signal data into a sensing pipeline that performs motion detection, breathing +estimation, attention weighting, and fingerprint matching. + +The crate uses `#[forbid(unsafe_code)]` and is designed as a pure-Rust domain layer with +pluggable platform adapters. + +## Features + +- **BSSID registry** -- Tracks observed access points with running RSSI statistics, band/radio + type classification, and metadata. Types: `BssidId`, `BssidObservation`, `BssidRegistry`, + `BssidEntry`. +- **Netsh adapter** (Tier 1) -- Parses `netsh wlan show networks mode=bssid` output into + structured `BssidObservation` records. Zero platform dependencies. +- **WLAN API scanner** (Tier 2, `wlanapi` feature) -- Async scanning via the Windows WLAN API + with `tokio` integration. +- **Multi-AP frame** -- `MultiApFrame` aggregates observations from multiple BSSIDs into a single + timestamped frame for downstream processing. +- **Sensing pipeline** (`pipeline` feature) -- `WindowsWifiPipeline` orchestrates motion + detection, breathing estimation, attention-weighted AP selection, and location fingerprint + matching. + +### Feature flags + +| Flag | Default | Description | +|------------|---------|------------------------------------------------------| +| `serde` | yes | Serialization for domain types | +| `pipeline` | yes | WindowsWifiPipeline sensing orchestration | +| `wlanapi` | no | Tier 2 async scanning via tokio (Windows WLAN API) | + +## Quick Start + +```rust +use wifi_densepose_wifiscan::{ + NetshBssidScanner, BssidRegistry, WlanScanPort, +}; + +// Parse netsh output (works on any platform for testing) +let netsh_output = "..."; // output of `netsh wlan show networks mode=bssid` +let observations = wifi_densepose_wifiscan::parse_netsh_output(netsh_output); + +// Register observations +let mut registry = BssidRegistry::new(); +for obs in &observations { + registry.update(obs); +} + +println!("Tracking {} access points", registry.len()); +``` + +With the `pipeline` feature enabled: + +```rust +use wifi_densepose_wifiscan::WindowsWifiPipeline; + +let pipeline = WindowsWifiPipeline::new(); +// Feed MultiApFrame data into the pipeline for sensing... +``` + +## Architecture + +```text +wifi-densepose-wifiscan/src/ + lib.rs -- Re-exports, feature gates + domain/ + bssid.rs -- BssidId, BssidObservation, BandType, RadioType + registry.rs -- BssidRegistry, BssidEntry, BssidMeta, RunningStats + frame.rs -- MultiApFrame (multi-BSSID aggregated frame) + result.rs -- EnhancedSensingResult + port.rs -- WlanScanPort trait (platform abstraction) + adapter.rs -- NetshBssidScanner (Tier 1), WlanApiScanner (Tier 2) + pipeline.rs -- WindowsWifiPipeline (motion, breathing, attention, fingerprint) + error.rs -- WifiScanError +``` + +## Related Crates + +| Crate | Role | +|-------|------| +| [`wifi-densepose-signal`](../wifi-densepose-signal) | Advanced CSI signal processing | +| [`wifi-densepose-vitals`](../wifi-densepose-vitals) | Vital sign extraction from CSI | +| [`wifi-densepose-hardware`](../wifi-densepose-hardware) | ESP32 and other hardware interfaces | +| [`wifi-densepose-mat`](../wifi-densepose-mat) | Disaster detection using multi-AP data | + +## License + +MIT OR Apache-2.0