feat: Complete Rust port of WiFi-DensePose with modular crates

Major changes:
- Organized Python v1 implementation into v1/ subdirectory
- Created Rust workspace with 9 modular crates:
  - wifi-densepose-core: Core types, traits, errors
  - wifi-densepose-signal: CSI processing, phase sanitization, FFT
  - wifi-densepose-nn: Neural network inference (ONNX/Candle/tch)
  - wifi-densepose-api: Axum-based REST/WebSocket API
  - wifi-densepose-db: SQLx database layer
  - wifi-densepose-config: Configuration management
  - wifi-densepose-hardware: Hardware abstraction
  - wifi-densepose-wasm: WebAssembly bindings
  - wifi-densepose-cli: Command-line interface

Documentation:
- ADR-001: Workspace structure
- ADR-002: Signal processing library selection
- ADR-003: Neural network inference strategy
- DDD domain model with bounded contexts

Testing:
- 69 tests passing across all crates
- Signal processing: 45 tests
- Neural networks: 21 tests
- Core: 3 doc tests

Performance targets:
- 10x faster CSI processing (~0.5ms vs ~5ms)
- 5x lower memory usage (~100MB vs ~500MB)
- WASM support for browser deployment
This commit is contained in:
Claude
2026-01-13 03:11:16 +00:00
parent 5101504b72
commit 6ed69a3d48
427 changed files with 90993 additions and 0 deletions

View File

@@ -0,0 +1,56 @@
# ADR-001: Rust Workspace Structure
## Status
Accepted
## Context
We need to port the WiFi-DensePose Python application to Rust for improved performance, memory safety, and cross-platform deployment including WASM. The architecture must be modular, maintainable, and support multiple deployment targets.
## Decision
We will use a Cargo workspace with 9 modular crates:
```
wifi-densepose-rs/
├── Cargo.toml # Workspace root
├── crates/
│ ├── wifi-densepose-core/ # Core types, traits, errors
│ ├── wifi-densepose-signal/ # Signal processing (CSI, phase, FFT)
│ ├── wifi-densepose-nn/ # Neural networks (DensePose, translation)
│ ├── wifi-densepose-api/ # REST/WebSocket API (Axum)
│ ├── wifi-densepose-db/ # Database layer (SQLx)
│ ├── wifi-densepose-config/ # Configuration management
│ ├── wifi-densepose-hardware/ # Hardware abstraction
│ ├── wifi-densepose-wasm/ # WASM bindings
│ └── wifi-densepose-cli/ # CLI application
```
### Crate Responsibilities
1. **wifi-densepose-core**: Foundation types, traits, and error handling shared across all crates
2. **wifi-densepose-signal**: CSI data processing, phase sanitization, FFT, feature extraction
3. **wifi-densepose-nn**: Neural network inference using ONNX Runtime, Candle, or tch-rs
4. **wifi-densepose-api**: HTTP/WebSocket server using Axum
5. **wifi-densepose-db**: Database operations with SQLx
6. **wifi-densepose-config**: Configuration loading and validation
7. **wifi-densepose-hardware**: Router and hardware interfaces
8. **wifi-densepose-wasm**: WebAssembly bindings for browser deployment
9. **wifi-densepose-cli**: Command-line interface
## Consequences
### Positive
- Clear separation of concerns
- Independent crate versioning
- Parallel compilation
- Selective feature inclusion
- Easier testing and maintenance
- WASM target isolation
### Negative
- More complex dependency management
- Initial setup overhead
- Cross-crate refactoring complexity
## References
- [Cargo Workspaces](https://doc.rust-lang.org/cargo/reference/workspaces.html)
- [ruvector crate structure](https://github.com/ruvnet/ruvector)

View File

@@ -0,0 +1,40 @@
# ADR-002: Signal Processing Library Selection
## Status
Accepted
## Context
CSI signal processing requires FFT operations, complex number handling, and matrix operations. We need to select appropriate Rust libraries that provide Python/NumPy equivalent functionality.
## Decision
We will use the following libraries:
| Library | Purpose | Python Equivalent |
|---------|---------|-------------------|
| `ndarray` | N-dimensional arrays | NumPy |
| `rustfft` | FFT operations | numpy.fft |
| `num-complex` | Complex numbers | complex |
| `num-traits` | Numeric traits | - |
### Key Implementations
1. **Phase Sanitization**: Multiple unwrapping methods (Standard, Custom, Itoh, Quality-Guided)
2. **CSI Processing**: Amplitude/phase extraction, temporal smoothing, Hamming windowing
3. **Feature Extraction**: Doppler, PSD, amplitude, phase, correlation features
4. **Motion Detection**: Variance-based with adaptive thresholds
## Consequences
### Positive
- Pure Rust implementation (no FFI overhead)
- WASM compatible (rustfft is pure Rust)
- NumPy-like API with ndarray
- High performance with SIMD optimizations
### Negative
- ndarray-linalg requires BLAS backend for advanced operations
- Learning curve for ndarray patterns
## References
- [ndarray documentation](https://docs.rs/ndarray)
- [rustfft documentation](https://docs.rs/rustfft)

View File

@@ -0,0 +1,57 @@
# ADR-003: Neural Network Inference Strategy
## Status
Accepted
## Context
The WiFi-DensePose system requires neural network inference for:
1. Modality translation (CSI → visual features)
2. DensePose estimation (body part segmentation + UV mapping)
We need to select an inference strategy that supports pre-trained models and multiple backends.
## Decision
We will implement a multi-backend inference engine:
### Primary Backend: ONNX Runtime (`ort` crate)
- Load pre-trained PyTorch models exported to ONNX
- GPU acceleration via CUDA/TensorRT
- Cross-platform support
### Alternative Backends (Feature-gated)
- `tch-rs`: PyTorch C++ bindings
- `candle`: Pure Rust ML framework
### Architecture
```rust
pub trait Backend: Send + Sync {
fn load_model(&mut self, path: &Path) -> NnResult<()>;
fn run(&self, inputs: HashMap<String, Tensor>) -> NnResult<HashMap<String, Tensor>>;
fn input_specs(&self) -> Vec<TensorSpec>;
fn output_specs(&self) -> Vec<TensorSpec>;
}
```
### Feature Flags
```toml
[features]
default = ["onnx"]
onnx = ["ort"]
tch-backend = ["tch"]
candle-backend = ["candle-core", "candle-nn"]
cuda = ["ort/cuda"]
tensorrt = ["ort/tensorrt"]
```
## Consequences
### Positive
- Use existing trained models (no retraining)
- Multiple backend options for different deployments
- GPU acceleration when available
- Feature flags minimize binary size
### Negative
- ONNX model conversion required
- ort crate pulls in C++ dependencies
- tch requires libtorch installation