dearsky/wifi-densepose
1
0
Fork 0
Code Issues 20 Pull Requests 5 Actions Packages Projects Releases 1 Wiki Activity

Add WiFi DensePose implementation and results

Browse Source 
- Implemented the WiFi DensePose model in PyTorch, including CSI phase processing, modality translation, and DensePose prediction heads.
- Added a comprehensive training utility for the model, including loss functions and training steps.
- Created a CSV file to document hardware specifications, architecture details, training parameters, performance metrics, and advantages of the model.
This commit is contained in:
rUv
2025-06-07 05:23:07 +00:00
parent 8227a70c31
commit f3c77b1750
66 changed files with 19849 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1158
plans/phase1-specification/api-spec.md Normal file
View File

File diff suppressed because it is too large Load Diff

813
plans/phase1-specification/functional-spec.md Normal file
View File

@@ -0,0 +1,813 @@
# Functional Specification
## WiFi-DensePose System
### Document Information
- **Version**: 1.0
- **Date**: 2025-01-07
- **Project**: InvisPose - WiFi-Based Dense Human Pose Estimation
- **Status**: Draft
---
## 1. Introduction
### 1.1 Purpose
This document defines the functional requirements and behaviors of the WiFi-DensePose system, specifying what the system must do to meet user needs across healthcare, retail, and security domains.
### 1.2 Scope
The functional specification covers all user-facing features, system behaviors, data processing workflows, and integration capabilities required for the WiFi-based human pose estimation platform.
### 1.3 Functional Overview
The system transforms WiFi Channel State Information (CSI) into real-time human pose estimates through neural network processing, providing privacy-preserving human sensing capabilities with 87.2% accuracy.
---
## 2. Core Functional Requirements
### 2.1 CSI Data Collection and Processing
#### 2.1.1 WiFi Signal Acquisition
**Function**: Extract Channel State Information from compatible WiFi routers
- **Input**: Raw WiFi signals from 3×3 MIMO antenna arrays
- **Processing**: Real-time CSI extraction with amplitude and phase data
- **Output**: Structured CSI data streams with temporal coherence
- **Frequency**: Continuous operation at 10-30 Hz sampling rate
**Acceptance Criteria**:
- Successfully extract CSI from Atheros-based routers
- Maintain data integrity across extended operation periods
- Handle network interruptions with automatic reconnection
- Support multiple router types with unified data format
#### 2.1.2 Signal Preprocessing
**Function**: Clean and normalize raw CSI data for neural network input
- **Phase Unwrapping**: Correct phase discontinuities and wrapping artifacts
- **Temporal Filtering**: Apply moving average and linear detrending
- **Background Subtraction**: Remove static environmental components
- **Noise Reduction**: Filter systematic noise and interference
**Processing Pipeline**:
```
Raw CSI → Phase Unwrapping → Temporal Filtering →
Background Subtraction → Noise Reduction → Normalized CSI
```
**Acceptance Criteria**:
- Achieve signal-to-noise ratio improvement of 10dB minimum
- Maintain temporal coherence across processing stages
- Adapt to environmental changes automatically
- Process data streams without introducing latency >10ms
#### 2.1.3 Environmental Calibration
**Function**: Establish baseline measurements for background subtraction
- **Baseline Capture**: Record empty environment CSI patterns
- **Adaptive Calibration**: Update baselines for environmental changes
- **Multi-Environment**: Support different room configurations
- **Drift Compensation**: Correct for systematic signal drift
**Calibration Process**:
1. Capture 60-second baseline with no human presence
2. Establish statistical models for background variation
3. Monitor for environmental changes requiring recalibration
4. Update baselines automatically or on user request
### 2.2 Neural Network Inference
#### 2.2.1 Modality Translation Network
**Function**: Convert 1D CSI signals to 2D spatial representations
- **Dual-Branch Processing**: Separate amplitude and phase encoders
- **Feature Fusion**: Combine modality-specific features
- **Spatial Upsampling**: Generate 720×1280 spatial representations
- **Temporal Consistency**: Maintain coherence across frames
**Network Architecture**:
```
CSI Input (3×3×N) → Amplitude Branch → Feature Fusion →
Phase Branch → Upsampling → Spatial Features (720×1280×3)
```
**Performance Requirements**:
- Processing latency <50ms on GPU hardware
- Maintain temporal consistency across frame sequences
- Support batch processing for efficiency
- Graceful degradation on CPU-only systems
#### 2.2.2 DensePose Estimation
**Function**: Extract dense human pose from spatial features
- **Body Part Detection**: Identify 24 anatomical regions
- **UV Coordinate Mapping**: Generate dense correspondence maps
- **Keypoint Extraction**: Detect 17 major body keypoints
- **Confidence Scoring**: Provide detection confidence metrics
**Output Format**:
- Dense pose masks for 24 body parts
- UV coordinates for surface mapping
- 2D keypoint coordinates with confidence scores
- Bounding boxes for detected persons
#### 2.2.3 Multi-Person Tracking
**Function**: Track multiple individuals across frame sequences
- **Person Detection**: Identify up to 5 individuals simultaneously
- **ID Assignment**: Maintain consistent person identifiers
- **Occlusion Handling**: Track through temporary occlusions
- **Trajectory Smoothing**: Apply temporal filtering for stability
**Tracking Features**:
- Kalman filtering for position prediction
- Hungarian algorithm for ID assignment
- Confidence-based track management
- Automatic track initialization and termination
### 2.3 Real-Time Processing Pipeline
#### 2.3.1 Data Flow Management
**Function**: Orchestrate end-to-end processing pipeline
- **Buffer Management**: Handle continuous data streams
- **Queue Processing**: Manage processing queues efficiently
- **Resource Allocation**: Optimize CPU/GPU utilization
- **Error Recovery**: Handle processing failures gracefully
**Pipeline Stages**:
1. CSI Data Ingestion
2. Preprocessing and Normalization
3. Neural Network Inference
4. Post-processing and Tracking
5. Output Generation and Distribution
#### 2.3.2 Performance Optimization
**Function**: Maintain real-time performance under varying loads
- **Adaptive Processing**: Scale processing based on available resources
- **Frame Dropping**: Skip frames under high load conditions
- **Batch Optimization**: Group operations for efficiency
- **Memory Management**: Prevent memory leaks and optimize usage
**Optimization Strategies**:
- Dynamic batch size adjustment
- GPU memory pooling
- Asynchronous processing pipelines
- Intelligent frame scheduling
---
## 3. User Stories and Use Cases
### 3.1 Healthcare Domain User Stories
#### 3.1.1 Elderly Care Monitoring
**As a** healthcare provider
**I want** to monitor elderly patients for fall events and activity patterns
**So that** I can provide immediate assistance and track health trends
**Acceptance Criteria**:
- System detects falls with 95% accuracy within 2 seconds
- Activity patterns are tracked and reported daily
- Alerts are sent immediately upon fall detection
- Privacy is maintained with no video recording
**User Journey**:
1. Caregiver configures fall detection sensitivity
2. System continuously monitors patient movement
3. Fall event triggers immediate alert to caregiver
4. System provides activity summary for health assessment
// TEST: Verify fall detection accuracy meets 95% threshold
// TEST: Confirm activity tracking provides meaningful health insights
// TEST: Validate alert delivery within 2-second requirement
#### 3.1.2 Rehabilitation Progress Tracking
**As a** physical therapist
**I want** to track patient movement and exercise compliance
**So that** I can adjust treatment plans based on objective data
**Acceptance Criteria**:
- Exercise movements are accurately classified
- Progress metrics are calculated and visualized
- Compliance rates are tracked over time
- Integration with electronic health records
**User Journey**:
1. Therapist sets up exercise monitoring protocol
2. Patient performs prescribed exercises
3. System tracks movement quality and completion
4. Progress reports are generated for treatment planning
// TEST: Verify exercise classification accuracy for rehabilitation movements
// TEST: Confirm progress metrics calculation and visualization
// TEST: Validate EHR integration functionality
### 3.2 Retail Domain User Stories
#### 3.2.1 Store Layout Optimization
**As a** retail manager
**I want** to understand customer traffic patterns and zone popularity
**So that** I can optimize store layout and product placement
**Acceptance Criteria**:
- Customer paths are tracked anonymously
- Zone dwell times are measured accurately
- Heatmaps show traffic density patterns
- A/B testing capabilities for layout changes
**User Journey**:
1. Manager configures store zones and tracking areas
2. System monitors customer movement throughout day
3. Analytics dashboard shows traffic patterns and insights
4. Manager uses data to optimize store layout
// TEST: Verify anonymous customer tracking maintains privacy
// TEST: Confirm zone analytics provide actionable insights
// TEST: Validate A/B testing framework for layout optimization
#### 3.2.2 Queue Management
**As a** store operations manager
**I want** to monitor checkout queue lengths and wait times
**So that** I can optimize staffing and reduce customer wait times
**Acceptance Criteria**:
- Queue lengths are detected in real-time
- Wait times are calculated automatically
- Staff alerts when queues exceed thresholds
- Historical data for staffing optimization
**User Journey**:
1. Manager sets queue length and wait time thresholds
2. System monitors checkout areas continuously
3. Alerts are sent when thresholds are exceeded
4. Historical data guides staffing decisions
// TEST: Verify queue detection accuracy in various store layouts
// TEST: Confirm wait time calculations are precise
// TEST: Validate alert system for queue management
### 3.3 Security Domain User Stories
#### 3.3.1 Perimeter Security Monitoring
**As a** security officer
**I want** to monitor restricted areas for unauthorized access
**So that** I can respond quickly to security breaches
**Acceptance Criteria**:
- Intrusion detection works through walls and obstacles
- Real-time alerts with location information
- Integration with existing security systems
- Audit trail for all security events
**User Journey**:
1. Security officer configures restricted zones
2. System monitors areas 24/7 without line-of-sight
3. Intrusion triggers immediate alert with location
4. Officer responds based on alert information
// TEST: Verify through-wall detection capability
// TEST: Confirm real-time alert delivery with accurate location
// TEST: Validate integration with security management systems
#### 3.3.2 Building Occupancy Monitoring
**As a** facility manager
**I want** to track building occupancy for safety and compliance
**So that** I can ensure emergency evacuation procedures and capacity limits
**Acceptance Criteria**:
- Accurate person counting in all monitored areas
- Real-time occupancy dashboard
- Emergency evacuation support
- Compliance reporting for safety regulations
**User Journey**:
1. Manager configures occupancy limits for each area
2. System tracks person count continuously
3. Dashboard shows real-time occupancy status
4. Emergency mode provides evacuation support
// TEST: Verify person counting accuracy across different environments
// TEST: Confirm occupancy dashboard provides real-time updates
// TEST: Validate emergency evacuation support functionality
---
## 4. Real-Time Streaming Requirements
### 4.1 Performance Requirements
#### 4.1.1 Latency Requirements
**End-to-End Latency**: <100ms from CSI data to pose output
- CSI Processing: <20ms
- Neural Network Inference: <50ms
- Post-processing and Tracking: <20ms
- API Response Generation: <10ms
**Streaming Latency**: <50ms for WebSocket delivery
- Internal Processing: <30ms
- Network Transmission: <20ms
// TEST: Verify end-to-end latency meets <100ms requirement
// TEST: Confirm WebSocket streaming latency <50ms
// TEST: Validate latency consistency under varying loads
#### 4.1.2 Throughput Requirements
**Processing Throughput**: 10-30 FPS depending on hardware
- Minimum: 10 FPS on CPU-only systems
- Optimal: 20 FPS on GPU-accelerated systems
- Maximum: 30 FPS on high-end hardware
**Concurrent Streaming**: Support 100+ simultaneous clients
- WebSocket connections: 100 concurrent
- REST API clients: 1000 concurrent
- Streaming bandwidth: 10 Mbps per client
// TEST: Verify processing throughput meets FPS requirements
// TEST: Confirm system supports 100+ concurrent streaming clients
// TEST: Validate bandwidth utilization stays within limits
### 4.2 Data Streaming Architecture
#### 4.2.1 Multi-Protocol Support
**WebSocket Streaming**: Primary real-time protocol
- Binary and JSON message formats
- Compression for bandwidth optimization
- Automatic reconnection handling
- Client-side buffering for smooth playback
**Server-Sent Events (SSE)**: Alternative streaming protocol
- HTTP-based streaming for firewall compatibility
- Automatic retry and reconnection
- Event-based message delivery
- Browser-native support
**MQTT Streaming**: IoT ecosystem integration
- QoS levels for reliability guarantees
- Topic-based message routing
- Retained messages for state persistence
- Scalable pub/sub architecture
// TEST: Verify WebSocket streaming handles reconnections gracefully
// TEST: Confirm SSE provides reliable alternative streaming
// TEST: Validate MQTT integration with IoT ecosystems
#### 4.2.2 Adaptive Streaming
**Quality Adaptation**: Automatic quality adjustment based on network conditions
- Bandwidth detection and monitoring
- Dynamic frame rate adjustment
- Compression level optimization
- Graceful degradation strategies
**Client Capability Detection**: Optimize streaming for client capabilities
- Device performance assessment
- Network bandwidth measurement
- Display resolution adaptation
- Battery optimization for mobile clients
// TEST: Verify adaptive streaming adjusts to network conditions
// TEST: Confirm client capability detection works accurately
// TEST: Validate quality adaptation maintains user experience
### 4.3 Restream Integration Specifications
#### 4.3.1 Platform Support
**Supported Platforms**: Multi-platform simultaneous streaming
- YouTube Live: RTMP streaming with custom overlays
- Twitch: Real-time pose visualization streams
- Facebook Live: Social media integration
- Custom RTMP: Enterprise and private platforms
**Stream Configuration**: Flexible streaming parameters
- Resolution: 720p, 1080p, 4K support
- Frame Rate: 15, 30, 60 FPS options
- Bitrate: Adaptive 1-10 Mbps
- Codec: H.264, H.265 support
// TEST: Verify simultaneous streaming to multiple platforms
// TEST: Confirm stream quality meets platform requirements
// TEST: Validate custom RTMP endpoint functionality
#### 4.3.2 Visualization Pipeline
**Pose Overlay Generation**: Real-time visualization creation
- Skeleton rendering with customizable styles
- Confidence indicators and person IDs
- Background options (transparent, solid, custom)
- Multi-person color coding
**Stream Composition**: Video stream assembly
- Pose overlay compositing
- Background image/video integration
- Text overlay for metadata
- Logo and branding integration
**Performance Optimization**: Efficient video processing
- GPU-accelerated rendering
- Parallel processing pipelines
- Memory-efficient operations
- Real-time encoding optimization
// TEST: Verify pose overlay generation meets quality standards
// TEST: Confirm stream composition handles multiple elements
// TEST: Validate performance optimization maintains real-time processing
#### 4.3.3 Stream Management
**Connection Management**: Robust streaming infrastructure
- Automatic reconnection on failures
- Stream health monitoring
- Bandwidth adaptation
- Error recovery procedures
**Analytics and Monitoring**: Stream performance tracking
- Viewer count monitoring
- Stream quality metrics
- Bandwidth utilization tracking
- Error rate monitoring
**Configuration Management**: Dynamic stream control
- Real-time parameter adjustment
- Stream start/stop control
- Platform-specific optimizations
- Scheduled streaming support
// TEST: Verify stream management handles connection failures
// TEST: Confirm analytics provide meaningful insights
// TEST: Validate configuration changes apply without interruption
---
## 5. Domain-Specific Functional Requirements
### 3.1 Healthcare Monitoring
#### 3.1.1 Fall Detection
**Function**: Detect and alert on fall events for elderly care
- **Pattern Recognition**: Identify rapid position changes
- **Threshold Configuration**: Adjustable sensitivity settings
- **Alert Generation**: Immediate notification on fall detection
- **False Positive Reduction**: Filter normal activities
**Detection Algorithm**:
```
Pose Trajectory Analysis → Velocity Calculation →
Position Change Detection → Confidence Assessment → Alert Decision
```
**Alert Criteria**:
- Vertical position change >1.5m in <2 seconds
- Horizontal impact detection
- Sustained ground-level position >10 seconds
- Configurable sensitivity thresholds
#### 3.1.2 Activity Monitoring
**Function**: Track patient mobility and activity patterns
- **Activity Classification**: Identify sitting, standing, walking, lying
- **Mobility Metrics**: Calculate movement frequency and duration
- **Inactivity Detection**: Alert on prolonged inactivity periods
- **Daily Reports**: Generate activity summaries
**Monitored Activities**:
- Walking patterns and gait analysis
- Sitting/standing transitions
- Sleep position monitoring
- Exercise and rehabilitation activities
#### 3.1.3 Privacy-Preserving Analytics
**Function**: Generate health insights while protecting patient privacy
- **Anonymous Data**: No personally identifiable information
- **Aggregated Metrics**: Statistical summaries only
- **Secure Storage**: Encrypted local data storage
- **Audit Trails**: Comprehensive access logging
### 3.2 Retail Analytics
#### 3.2.1 Customer Traffic Analysis
**Function**: Monitor customer movement and behavior patterns
- **Traffic Counting**: Real-time customer count tracking
- **Zone Analytics**: Movement between store zones
- **Dwell Time**: Time spent in specific areas
- **Path Analysis**: Customer journey mapping
**Analytics Outputs**:
- Hourly/daily traffic reports
- Zone popularity heatmaps
- Average dwell time by area
- Peak traffic period identification
#### 3.2.2 Occupancy Management
**Function**: Monitor store capacity and density
- **Real-Time Counts**: Current occupancy levels
- **Capacity Alerts**: Notifications at threshold levels
- **Queue Detection**: Identify waiting areas and lines
- **Social Distancing**: Monitor spacing compliance
**Capacity Features**:
- Configurable occupancy limits
- Real-time dashboard displays
- Automated alert systems
- Historical occupancy trends
#### 3.2.3 Layout Optimization
**Function**: Provide insights for store layout improvements
- **Traffic Flow**: Identify bottlenecks and dead zones
- **Product Interaction**: Monitor engagement with displays
- **Conversion Analysis**: Path-to-purchase tracking
- **A/B Testing**: Compare layout configurations
### 3.3 Security Applications
#### 3.3.1 Intrusion Detection
**Function**: Monitor restricted areas for unauthorized access
- **Perimeter Monitoring**: Detect boundary crossings
- **Through-Wall Detection**: Monitor without line-of-sight
- **Behavioral Analysis**: Identify suspicious movement patterns
- **Real-Time Alerts**: Immediate security notifications
**Detection Capabilities**:
- Motion detection in restricted zones
- Loitering detection with configurable timeouts
- Multiple person alerts
- Integration with security systems
#### 3.3.2 Access Control Integration
**Function**: Enhance physical security systems
- **Zone-Based Monitoring**: Different security levels by area
- **Time-Based Rules**: Schedule-dependent monitoring
- **Credential Correlation**: Link with access card systems
- **Audit Logging**: Comprehensive security event logs
#### 3.3.3 Emergency Response
**Function**: Support emergency evacuation and response
- **Occupancy Tracking**: Real-time person counts by zone
- **Evacuation Monitoring**: Track movement during emergencies
- **First Responder Support**: Provide occupancy information
- **Emergency Alerts**: Automated emergency notifications
---
## 4. API and Integration Functions
### 4.1 REST API Endpoints
#### 4.1.1 Pose Data Access
**Endpoints**:
- `GET /pose/latest` - Current pose data
- `GET /pose/history` - Historical pose data
- `GET /pose/stream` - Real-time pose stream
- `POST /pose/query` - Custom pose queries
**Response Format**:
```json
{
"timestamp": "2025-01-07T04:46:32Z",
"persons": [
{
"id": 1,
"confidence": 0.87,
"keypoints": [...],
"dense_pose": {...},
"bounding_box": {...}
}
],
"metadata": {
"processing_time": 45,
"frame_id": 12345
}
}
```
#### 4.1.2 System Control
**Endpoints**:
- `POST /system/start` - Start pose estimation
- `POST /system/stop` - Stop pose estimation
- `GET /system/status` - System health status
- `POST /system/calibrate` - Trigger calibration
#### 4.1.3 Configuration Management
**Endpoints**:
- `GET /config` - Current configuration
- `PUT /config` - Update configuration
- `GET /config/templates` - Available templates
- `POST /config/validate` - Validate configuration
### 4.2 WebSocket Streaming
#### 4.2.1 Real-Time Data Streams
**Function**: Provide low-latency pose data streaming
- **Connection Management**: Handle multiple concurrent clients
- **Message Broadcasting**: Efficient data distribution
- **Automatic Reconnection**: Client reconnection handling
- **Rate Limiting**: Prevent client overload
**Stream Types**:
- Pose data streams
- System status updates
- Alert notifications
- Performance metrics
#### 4.2.2 Client Management
**Function**: Manage WebSocket client lifecycle
- **Authentication**: Secure client connections
- **Subscription Management**: Topic-based subscriptions
- **Connection Monitoring**: Health check and cleanup
- **Error Handling**: Graceful error recovery
### 4.3 External Integration
#### 4.3.1 MQTT Publishing
**Function**: Integrate with IoT ecosystems
- **Topic Structure**: Hierarchical topic organization
- **Message Formats**: JSON and binary message support
- **QoS Levels**: Configurable quality of service
- **Retained Messages**: State persistence
**MQTT Topics**:
- `wifi-densepose/pose/person/{id}` - Individual pose data
- `wifi-densepose/alerts/{type}` - Alert notifications
- `wifi-densepose/status` - System status
- `wifi-densepose/analytics/{domain}` - Domain analytics
#### 4.3.2 Webhook Integration
**Function**: Send real-time notifications to external services
- **Event Triggers**: Configurable event conditions
- **Retry Logic**: Automatic retry on failures
- **Authentication**: Support for various auth methods
- **Payload Customization**: Flexible message formats
**Webhook Events**:
- Person detection/departure
- Fall detection alerts
- System status changes
- Threshold violations
#### 4.3.3 Restream Integration
**Function**: Live streaming to multiple platforms
- **Multi-Platform**: Simultaneous streaming to multiple services
- **Video Encoding**: Real-time video generation
- **Stream Management**: Automatic reconnection and quality adaptation
- **Overlay Generation**: Pose visualization overlays
---
## 5. User Interface Functions
### 5.1 Web Dashboard
#### 5.1.1 Real-Time Visualization
**Function**: Display live pose estimation results
- **Pose Rendering**: Real-time skeleton visualization
- **Multi-Person Display**: Color-coded person tracking
- **Confidence Indicators**: Visual confidence representation
- **Background Options**: Configurable visualization backgrounds
**Visualization Features**:
- Stick figure pose representation
- Dense pose heat maps
- Keypoint confidence visualization
- Trajectory tracking displays
#### 5.1.2 System Monitoring
**Function**: Monitor system health and performance
- **Performance Metrics**: Real-time performance indicators
- **Resource Usage**: CPU, GPU, memory utilization
- **Network Status**: CSI data stream health
- **Error Reporting**: System error and warning displays
#### 5.1.3 Configuration Interface
**Function**: System configuration and control
- **Parameter Adjustment**: Real-time parameter tuning
- **Template Selection**: Domain-specific configuration templates
- **Calibration Control**: Manual calibration triggers
- **Alert Configuration**: Threshold and notification settings
### 5.2 Mobile Interface
#### 5.2.1 Responsive Design
**Function**: Mobile-optimized interface for monitoring
- **Touch Interface**: Mobile-friendly controls
- **Responsive Layout**: Adaptive screen sizing
- **Offline Capability**: Basic functionality without connectivity
- **Push Notifications**: Mobile alert delivery
#### 5.2.2 Quick Actions
**Function**: Essential controls for mobile users
- **System Start/Stop**: Basic system control
- **Alert Acknowledgment**: Quick alert responses
- **Status Overview**: System health summary
- **Emergency Controls**: Rapid emergency response
---
## 6. Data Management Functions
### 6.1 Data Storage
#### 6.1.1 Pose Data Storage
**Function**: Store pose estimation results for analysis
- **Time-Series Storage**: Efficient temporal data storage
- **Compression**: Data compression for storage efficiency
- **Indexing**: Fast query performance
- **Retention Policies**: Configurable data retention
**Storage Schema**:
```
pose_data:
- timestamp (primary key)
- person_id
- pose_keypoints
- confidence_scores
- metadata
```
#### 6.1.2 Configuration Storage
**Function**: Persist system configuration and settings
- **Version Control**: Configuration change tracking
- **Backup/Restore**: Configuration backup capabilities
- **Template Management**: Pre-configured templates
- **Validation**: Configuration integrity checking
#### 6.1.3 Analytics Storage
**Function**: Store aggregated analytics and reports
- **Domain-Specific**: Separate storage for different domains
- **Aggregation**: Pre-computed analytics for performance
- **Export Capabilities**: Data export in multiple formats
- **Privacy Compliance**: Anonymized data storage
### 6.2 Data Processing
#### 6.2.1 Batch Analytics
**Function**: Process historical data for insights
- **Trend Analysis**: Long-term pattern identification
- **Statistical Analysis**: Comprehensive statistical metrics
- **Report Generation**: Automated report creation
- **Data Mining**: Advanced pattern discovery
#### 6.2.2 Real-Time Analytics
**Function**: Generate live insights from streaming data
- **Stream Processing**: Real-time data aggregation
- **Threshold Monitoring**: Live threshold violation detection
- **Anomaly Detection**: Real-time anomaly identification
- **Alert Generation**: Immediate alert processing
---
## 7. Quality Assurance Functions
### 7.1 Testing and Validation
#### 7.1.1 Automated Testing
**Function**: Comprehensive automated test coverage
- **Unit Testing**: Component-level test coverage
- **Integration Testing**: End-to-end pipeline testing
- **Performance Testing**: Load and stress testing
- **Regression Testing**: Continuous validation
#### 7.1.2 Hardware Simulation
**Function**: Test without physical hardware
- **CSI Simulation**: Synthetic CSI data generation
- **Scenario Testing**: Predefined test scenarios
- **Environment Simulation**: Various deployment conditions
- **Validation Testing**: Algorithm validation
### 7.2 Monitoring and Diagnostics
#### 7.2.1 System Health Monitoring
**Function**: Continuous system health assessment
- **Performance Monitoring**: Real-time performance tracking
- **Resource Monitoring**: Hardware resource utilization
- **Error Detection**: Automatic error identification
- **Predictive Maintenance**: Proactive issue identification
#### 7.2.2 Diagnostic Tools
**Function**: Troubleshooting and problem resolution
- **Log Analysis**: Comprehensive log analysis tools
- **Performance Profiling**: Detailed performance analysis
- **Network Diagnostics**: CSI data stream analysis
- **Debug Interfaces**: Developer debugging tools
---
## 8. Acceptance Criteria
### 8.1 Functional Acceptance
- **Pose Detection**: Successfully detect human poses with 87.2% AP@50
- **Multi-Person**: Track up to 5 individuals simultaneously
- **Real-Time**: Maintain <100ms end-to-end latency
- **Domain Functions**: All domain-specific features operational
### 8.2 Integration Acceptance
- **API Endpoints**: All specified endpoints functional
- **WebSocket Streaming**: Real-time data streaming operational
- **External Integration**: MQTT, webhooks, and Restream functional
- **Dashboard**: Web interface fully operational
### 8.3 Performance Acceptance
- **Throughput**: Achieve 10-30 FPS processing rates
- **Reliability**: 99.5% uptime over testing period
- **Scalability**: Support 100+ concurrent API clients
- **Resource Usage**: Operate within specified hardware limits
// TEST: Validate CSI data extraction from all supported router types
// TEST: Verify neural network inference accuracy meets AP@50 targets
// TEST: Confirm multi-person tracking maintains ID consistency
// TEST: Validate real-time performance under various load conditions
// TEST: Test all API endpoints for correct functionality
// TEST: Verify WebSocket streaming handles multiple concurrent clients
// TEST: Validate domain-specific functions for healthcare, retail, security
// TEST: Confirm external integrations work with MQTT, webhooks, Restream
// TEST: Test web dashboard functionality across different browsers
// TEST: Validate data storage and retrieval operations
// TEST: Verify system monitoring and diagnostic capabilities
// TEST: Confirm automated testing framework covers all components

275
plans/phase1-specification/system-requirements.md Normal file
View File

@@ -0,0 +1,275 @@
# System Requirements Specification (SRS)
## WiFi-DensePose System
### Document Information
- **Version**: 1.0
- **Date**: 2025-01-07
- **Project**: InvisPose - WiFi-Based Dense Human Pose Estimation
- **Status**: Draft
---
## 1. Introduction
### 1.1 Purpose
This document specifies the system requirements for the WiFi-DensePose system, a revolutionary privacy-preserving human pose estimation platform that transforms commodity WiFi infrastructure into a powerful human sensing system.
### 1.2 Scope
The system enables real-time full-body tracking through walls using standard mesh routers, achieving 87.2% detection accuracy while maintaining complete privacy preservation without cameras or optical sensors.
### 1.3 Definitions and Acronyms
- **CSI**: Channel State Information - WiFi signal characteristics containing amplitude and phase data
- **DensePose**: Dense human pose estimation mapping 2D detections to 3D body models
- **MIMO**: Multiple-Input Multiple-Output antenna configuration
- **AP@50**: Average Precision at 50% Intersection over Union
- **FPS**: Frames Per Second
- **RTMP**: Real-Time Messaging Protocol
---
## 2. Overall Description
### 2.1 Product Perspective
The WiFi-DensePose system operates as a standalone platform that integrates with existing WiFi infrastructure to provide human sensing capabilities across multiple domains including healthcare, retail, and security applications.
### 2.2 Product Functions
- Real-time human pose estimation through WiFi signals
- Multi-person tracking and identification
- Cross-wall detection capabilities
- Domain-specific analytics and monitoring
- Live streaming and visualization
- API-based integration with external systems
### 2.3 User Classes
- **Healthcare Providers**: Elderly care monitoring, patient activity tracking
- **Retail Operators**: Customer analytics, occupancy monitoring
- **Security Personnel**: Intrusion detection, perimeter monitoring
- **Developers**: API integration, custom application development
- **System Administrators**: Deployment, configuration, maintenance
---
## 3. Hardware Requirements
### 3.1 WiFi Router Requirements
#### 3.1.1 Compatible Hardware
- **Primary**: Atheros-based routers (TP-Link Archer series, Netgear Nighthawk)
- **Secondary**: Intel 5300 NIC-based systems
- **Alternative**: ASUS RT-AC68U series
#### 3.1.2 Antenna Configuration
- **Minimum**: 3×3 MIMO antenna configuration
- **Spatial Diversity**: Required for CSI spatial measurements
- **Frequency Bands**: 2.4GHz and 5GHz support
#### 3.1.3 Firmware Requirements
- **Base**: OpenWRT firmware compatibility
- **Patches**: CSI extraction patches installed
- **Monitor Mode**: Capability for monitor mode operation
- **Data Streaming**: UDP data stream support
#### 3.1.4 Cost Constraints
- **Target Cost**: ~$30 per router unit
- **Total System**: Under $100 including processing hardware
- **Scalability**: 10-100x cost reduction vs. LiDAR alternatives
### 3.2 Processing Hardware Requirements
#### 3.2.1 Minimum Specifications
- **CPU**: Multi-core processor (4+ cores recommended)
- **RAM**: 8GB minimum, 16GB recommended
- **Storage**: 50GB available space
- **Network**: Gigabit Ethernet for CSI data streams
#### 3.2.2 GPU Acceleration (Optional)
- **CUDA Support**: NVIDIA GPU with CUDA capability
- **Memory**: 4GB+ GPU memory for real-time processing
- **Performance**: Sub-100ms processing latency target
#### 3.2.3 Network Infrastructure
- **Bandwidth**: Minimum 100Mbps for CSI data collection
- **Latency**: Low-latency network for real-time processing
- **Reliability**: Stable connection for continuous operation
---
## 4. Software Requirements
### 4.1 Operating System Support
- **Primary**: Linux (Ubuntu 20.04+, CentOS 8+)
- **Secondary**: Windows 10/11 with WSL2
- **Container**: Docker support for deployment
### 4.2 Runtime Dependencies
- **Python**: 3.8+ with pip package management
- **PyTorch**: GPU-accelerated deep learning framework
- **OpenCV**: Computer vision and image processing
- **FFmpeg**: Video encoding for streaming
- **FastAPI**: Web framework for API services
### 4.3 Development Dependencies
- **Testing**: pytest, unittest framework
- **Documentation**: Sphinx, markdown support
- **Linting**: flake8, black code formatting
- **Version Control**: Git integration
---
## 5. Performance Requirements
### 5.1 Accuracy Metrics
- **Primary Target**: 87.2% AP@50 under optimal conditions
- **Cross-Environment**: 51.8% AP@50 minimum performance
- **Multi-Person**: Support for up to 5 individuals simultaneously
- **Tracking Consistency**: Minimal ID switching during occlusion
### 5.2 Real-Time Performance
- **Processing Rate**: 10-30 FPS depending on hardware
- **End-to-End Latency**: Under 100ms on GPU systems
- **Startup Time**: System ready within 30 seconds
- **Memory Usage**: Stable operation without memory leaks
### 5.3 Reliability Requirements
- **Uptime**: 99.5% availability for continuous operation
- **Error Recovery**: Automatic recovery from transient failures
- **Data Integrity**: No data loss during normal operation
- **Graceful Degradation**: Reduced performance under resource constraints
### 5.4 Scalability Requirements
- **Concurrent Users**: Support 100+ API clients
- **Data Throughput**: Handle continuous CSI streams
- **Storage Growth**: Efficient data management for historical data
- **Horizontal Scaling**: Support for distributed deployments
---
## 6. Security Requirements
### 6.1 Privacy Protection
- **No Visual Data**: Complete elimination of camera-based sensing
- **Anonymous Tracking**: Pose data without identity information
- **Data Encryption**: Encrypted data transmission and storage
- **Access Control**: Role-based access to system functions
### 6.2 Network Security
- **Secure Communication**: HTTPS/WSS for all external interfaces
- **Authentication**: API key-based authentication
- **Input Validation**: Comprehensive input sanitization
- **Rate Limiting**: Protection against abuse and DoS attacks
### 6.3 Data Protection
- **Local Processing**: On-premises data processing capability
- **Data Retention**: Configurable data retention policies
- **Audit Logging**: Comprehensive system activity logging
- **Compliance**: GDPR and healthcare privacy compliance
---
## 7. Environmental Requirements
### 7.1 Physical Environment
- **Operating Temperature**: 0°C to 40°C
- **Humidity**: 10% to 90% non-condensing
- **Ventilation**: Adequate cooling for processing hardware
- **Power**: Stable power supply with UPS backup recommended
### 7.2 RF Environment
- **Interference**: Tolerance to common WiFi interference
- **Range**: Effective operation within 10-30 meter range
- **Obstacles**: Through-wall detection capability
- **Multi-Path**: Robust operation in complex RF environments
### 7.3 Installation Requirements
- **Router Placement**: Strategic positioning for coverage
- **Network Configuration**: Isolated or VLAN-based deployment
- **Calibration**: Environmental baseline establishment
- **Maintenance Access**: Physical and remote access for updates
---
## 8. Compliance and Standards
### 8.1 Regulatory Compliance
- **FCC Part 15**: WiFi equipment certification
- **IEEE 802.11**: WiFi standard compliance
- **IEEE 802.11bf**: Future WiFi sensing standard compatibility
- **Local Regulations**: Regional RF emission compliance
### 8.2 Industry Standards
- **ISO 27001**: Information security management
- **HIPAA**: Healthcare data protection (where applicable)
- **GDPR**: European data protection regulation
- **SOC 2**: Service organization control standards
---
## 9. Quality Attributes
### 9.1 Usability
- **Installation**: Automated setup and configuration
- **Interface**: Intuitive web-based dashboard
- **Documentation**: Comprehensive user and API documentation
- **Support**: Multi-language support for international deployment
### 9.2 Maintainability
- **Modular Design**: Component-based architecture
- **Logging**: Comprehensive system and error logging
- **Monitoring**: Real-time system health monitoring
- **Updates**: Rolling updates without service interruption
### 9.3 Portability
- **Cross-Platform**: Support for multiple operating systems
- **Containerization**: Docker-based deployment
- **Cloud Compatibility**: Support for cloud deployment
- **Hardware Independence**: Adaptation to different hardware configurations
---
## 10. Constraints and Assumptions
### 10.1 Technical Constraints
- **WiFi Dependency**: Requires compatible WiFi hardware
- **Processing Power**: Performance scales with available compute resources
- **Network Bandwidth**: CSI data requires significant bandwidth
- **Environmental Factors**: Performance affected by RF environment
### 10.2 Business Constraints
- **Cost Targets**: Maintain affordability for widespread adoption
- **Time to Market**: Rapid deployment capability
- **Regulatory Approval**: Compliance with local regulations
- **Intellectual Property**: Respect for existing patents and IP
### 10.3 Assumptions
- **Network Stability**: Reliable network infrastructure
- **Power Availability**: Stable power supply
- **User Training**: Basic technical competency for deployment
- **Maintenance**: Regular system maintenance and updates
---
## 11. Acceptance Criteria
### 11.1 Functional Acceptance
- **Pose Detection**: Successful human pose estimation
- **Multi-Person**: Concurrent tracking of multiple individuals
- **Real-Time**: Sub-100ms latency performance
- **API Functionality**: All specified endpoints operational
### 11.2 Performance Acceptance
- **Accuracy**: Meet specified AP@50 targets
- **Throughput**: Achieve target FPS rates
- **Reliability**: 99.5% uptime over 30-day period
- **Resource Usage**: Operate within specified hardware limits
### 11.3 Integration Acceptance
- **External APIs**: Successful integration with specified services
- **Streaming**: Functional Restream integration
- **Webhooks**: Reliable event notification delivery
- **MQTT**: Successful IoT ecosystem integration
// TEST: Verify all hardware requirements are met during system setup
// TEST: Validate performance metrics under various load conditions
// TEST: Confirm security requirements through penetration testing
// TEST: Verify compliance with regulatory standards
// TEST: Validate acceptance criteria through comprehensive testing

1377
plans/phase1-specification/technical-spec.md Normal file
View File

File diff suppressed because it is too large Load Diff

1825
plans/phase2-architecture/api-architecture.md Normal file
View File

File diff suppressed because it is too large Load Diff

1735
plans/phase2-architecture/hardware-integration.md Normal file
View File

File diff suppressed because it is too large Load Diff

1186
plans/phase2-architecture/neural-network-architecture.md Normal file
View File

File diff suppressed because it is too large Load Diff

760
plans/phase2-architecture/system-architecture.md Normal file
View File

@@ -0,0 +1,760 @@
# WiFi-DensePose System Architecture
## Document Information
- **Version**: 1.0
- **Date**: 2025-06-07
- **Project**: InvisPose - WiFi-Based Dense Human Pose Estimation
- **Status**: Draft
---
## 1. High-Level System Design
### 1.1 System Overview
WiFi-DensePose is a revolutionary privacy-preserving human pose estimation system that transforms commodity WiFi infrastructure into a powerful human sensing platform. The system processes WiFi Channel State Information (CSI) through specialized neural networks to achieve real-time human pose estimation with 87.2% accuracy without using cameras or optical sensors.
### 1.2 Architecture Diagram
```mermaid
graph TD
subgraph Hardware_Layer
A[WiFi Routers] --> B[CSI Data Extraction]
end
subgraph Core_Processing_Layer
B --> C[Signal Preprocessing]
C --> D[Neural Network Pipeline]
D --> E[Pose Estimation Engine]
E --> F[Multi-Person Tracking]
end
subgraph Service_Layer
F --> G[API Gateway]
G --> H1[REST API]
G --> H2[WebSocket Server]
G --> H3[MQTT Broker]
G --> H4[Webhook Service]
G --> H5[Restream Service]
end
subgraph Application_Layer
H1 --> I1[Web Dashboard]
H2 --> I1
H1 --> I2[Mobile App]
H2 --> I2
H3 --> I3[IoT Integration]
H4 --> I4[External Services]
H5 --> I5[Streaming Platforms]
end
subgraph Management_Layer
J[Configuration Management] --> A
J --> C
J --> D
J --> E
J --> G
K[Monitoring & Diagnostics] -.-> Hardware_Layer
K -.-> Core_Processing_Layer
K -.-> Service_Layer
end
```
### 1.3 Key System Characteristics
- **Privacy-Preserving**: No cameras or optical sensors, ensuring complete privacy
- **Real-Time Processing**: End-to-end latency under 100ms
- **Through-Wall Detection**: Ability to detect human poses through walls and obstacles
- **Multi-Person Tracking**: Support for up to 5 individuals simultaneously
- **Scalable Architecture**: Modular design supporting various deployment scenarios
- **Domain-Specific Analytics**: Specialized analytics for healthcare, retail, and security domains
---
## 2. Component Breakdown and Responsibilities
### 2.1 Hardware Interface Layer
#### 2.1.1 WiFi Router Interface
- **Responsibility**: Establish and maintain communication with WiFi routers
- **Functions**:
- Configure routers for CSI extraction
- Manage connection lifecycle
- Handle router failures and reconnections
- Support multiple router types (Atheros, Intel, ASUS)
#### 2.1.2 CSI Data Collector
- **Responsibility**: Extract and collect CSI data from WiFi routers
- **Functions**:
- Receive UDP data streams from routers
- Parse CSI packet formats
- Buffer incoming data
- Synchronize multiple data streams
- Handle packet loss and corruption
### 2.2 Core Processing Layer
#### 2.2.1 Signal Preprocessor
- **Responsibility**: Clean and normalize raw CSI data
- **Functions**:
- Phase unwrapping
- Amplitude normalization
- Temporal filtering
- Background subtraction
- Noise reduction
- Environmental calibration
#### 2.2.2 Neural Network Pipeline
- **Responsibility**: Transform CSI data into human pose estimates
- **Functions**:
- Modality translation (CSI to spatial representation)
- Feature extraction
- DensePose estimation
- Confidence scoring
- Batch processing optimization
#### 2.2.3 Pose Estimation Engine
- **Responsibility**: Orchestrate end-to-end processing pipeline
- **Functions**:
- Coordinate data flow between components
- Manage processing queues
- Optimize resource allocation
- Handle error recovery
- Maintain processing performance
#### 2.2.4 Multi-Person Tracker
- **Responsibility**: Track multiple individuals across time
- **Functions**:
- Person detection and ID assignment
- Trajectory tracking and prediction
- Occlusion handling
- Track management (creation, updating, termination)
- Temporal consistency enforcement
### 2.3 Service Layer
#### 2.3.1 API Gateway
- **Responsibility**: Provide unified access point for all services
- **Functions**:
- Request routing
- Load balancing
- Authentication and authorization
- Rate limiting
- Request/response transformation
- API versioning
#### 2.3.2 REST API Service
- **Responsibility**: Provide HTTP-based access to system functionality
- **Functions**:
- Pose data access (current and historical)
- System control (start, stop, status)
- Configuration management
- Analytics and reporting
- Domain-specific endpoints
#### 2.3.3 WebSocket Server
- **Responsibility**: Enable real-time data streaming
- **Functions**:
- Connection management
- Subscription handling
- Real-time pose data streaming
- System status updates
- Alert notifications
#### 2.3.4 External Integration Services
- **Responsibility**: Connect with external systems and platforms
- **Functions**:
- MQTT publishing for IoT integration
- Webhook delivery for event notifications
- Restream integration for live broadcasting
- Third-party API integration
### 2.4 Management Layer
#### 2.4.1 Configuration Management
- **Responsibility**: Manage system configuration and settings
- **Functions**:
- Configuration storage and retrieval
- Template management
- Validation and verification
- Dynamic configuration updates
- Environment-specific settings
#### 2.4.2 Monitoring and Diagnostics
- **Responsibility**: Monitor system health and performance
- **Functions**:
- Performance metrics collection
- Resource utilization monitoring
- Error detection and reporting
- Logging and audit trails
- Alerting and notifications
---
## 3. Data Flow Architecture
### 3.1 Primary Data Flow
```mermaid
sequenceDiagram
participant Router as WiFi Router
participant CSI as CSI Collector
participant Preproc as Signal Preprocessor
participant NN as Neural Network
participant Pose as Pose Estimator
participant Tracker as Multi-Person Tracker
participant API as API Services
participant Client as Client Applications
Router->>CSI: Raw CSI Data (UDP)
CSI->>Preproc: Structured CSI Data
Preproc->>NN: Preprocessed CSI Features
NN->>Pose: Spatial Representations
Pose->>Tracker: Raw Pose Estimates
Tracker->>API: Tracked Pose Data
API->>Client: Pose Data (REST/WebSocket)
```
### 3.2 Data Processing Stages
#### 3.2.1 CSI Data Acquisition
- **Input**: Raw WiFi signals from router antennas
- **Processing**: Packet parsing, buffering, synchronization
- **Output**: Structured CSI data (amplitude and phase)
- **Data Rate**: 10-30 Hz sampling rate
- **Data Volume**: ~100 KB/s per router
#### 3.2.2 Signal Preprocessing
- **Input**: Structured CSI data
- **Processing**: Phase unwrapping, filtering, normalization
- **Output**: Clean, normalized CSI features
- **Transformation**: Noise reduction, background removal
- **Quality Metrics**: Signal-to-noise ratio improvement
#### 3.2.3 Neural Network Inference
- **Input**: Preprocessed CSI features
- **Processing**: Deep learning inference
- **Output**: Spatial representations and pose estimates
- **Performance**: <50ms inference time on GPU
- **Accuracy**: 87.2% AP@50 under optimal conditions
#### 3.2.4 Multi-Person Tracking
- **Input**: Raw pose estimates
- **Processing**: ID assignment, trajectory prediction
- **Output**: Consistent tracked poses with IDs
- **Features**: Occlusion handling, track continuity
- **Capacity**: Up to 5 simultaneous persons
#### 3.2.5 API Distribution
- **Input**: Tracked pose data
- **Processing**: Formatting, serialization, streaming
- **Output**: REST responses, WebSocket messages, MQTT publications
- **Performance**: <10ms API response generation
- **Throughput**: Support for 100+ concurrent clients
### 3.3 Data Storage Flow
```mermaid
graph LR
A[Pose Data] --> B[Short-Term Cache]
A --> C[Time-Series Database]
C --> D[Data Aggregation]
D --> E[Analytics Storage]
E --> F[Reporting Engine]
G[Configuration Data] --> H[Config Database]
H --> I[Runtime Config]
H --> J[Config Templates]
K[System Metrics] --> L[Metrics Database]
L --> M[Monitoring Dashboard]
L --> N[Alert Engine]
```
---
## 4. Service Boundaries and Interfaces
### 4.1 Component Interface Definitions
#### 4.1.1 Hardware Interface Layer Boundaries
- **External Interfaces**:
- UDP socket interface for CSI data reception
- Router configuration interface
- **Internal Interfaces**:
- CSI data queue for preprocessor
- Router status events for monitoring
#### 4.1.2 Core Processing Layer Boundaries
- **External Interfaces**:
- Configuration API for parameter tuning
- Metrics API for performance monitoring
- **Internal Interfaces**:
- Preprocessed data queue for neural network
- Pose estimation queue for tracker
- Event bus for system status updates
#### 4.1.3 Service Layer Boundaries
- **External Interfaces**:
- REST API endpoints for clients
- WebSocket interface for real-time streaming
- MQTT topics for IoT integration
- Webhook endpoints for event notifications
- **Internal Interfaces**:
- Pose data access interface
- Authentication and authorization service
- Rate limiting and throttling service
### 4.2 API Contracts
#### 4.2.1 Internal API Contracts
- **CSI Collector → Signal Preprocessor**:
```typescript
interface CSIData {
timestamp: number;
routerId: string;
amplitude: Float32Array[][];
phase: Float32Array[][];
rssi: number;
metadata: Record<string, any>;
}
```
- **Neural Network → Pose Estimator**:
```typescript
interface SpatialRepresentation {
features: Float32Array[][][];
confidence: number;
timestamp: number;
processingTime: number;
}
```
- **Pose Estimator → Multi-Person Tracker**:
```typescript
interface PoseEstimate {
keypoints: Array<{x: number, y: number, confidence: number}>;
boundingBox: {x: number, y: number, width: number, height: number};
confidence: number;
timestamp: number;
}
```
#### 4.2.2 External API Contracts
- See API Architecture document for detailed external API contracts
### 4.3 Event-Driven Communication
```mermaid
graph TD
A[System Events] --> B{Event Bus}
B --> C[Hardware Events]
B --> D[Processing Events]
B --> E[API Events]
B --> F[Alert Events]
C --> C1[Router Connected]
C --> C2[Router Disconnected]
C --> C3[CSI Data Received]
D --> D1[Processing Started]
D --> D2[Processing Completed]
D --> D3[Error Detected]
E --> E1[Client Connected]
E --> E2[Request Received]
E --> E3[Response Sent]
F --> F1[Fall Detected]
F --> F2[Person Detected]
F --> F3[System Alert]
```
---
## 5. Deployment Architecture
### 5.1 Docker Container Architecture
```mermaid
graph TD
subgraph Docker_Host
subgraph Core_Containers
A[CSI Collector Container]
B[Neural Network Container]
C[Pose Estimation Container]
D[API Services Container]
end
subgraph Support_Containers
E[Database Container]
F[MQTT Broker Container]
G[Redis Cache Container]
H[Monitoring Container]
end
subgraph Frontend_Containers
I[Web Dashboard Container]
J[Streaming Server Container]
end
A --> B
B --> C
C --> D
D --> E
D --> F
D --> G
A --> H
B --> H
C --> H
D --> H
D --> I
D --> J
end
```
### 5.2 Container Specifications
#### 5.2.1 Core Containers
- **CSI Collector Container**:
- Base Image: Python 3.9-slim
- Resources: 1 CPU core, 1GB RAM
- Volumes: Configuration volume
- Network: Host network for UDP reception
- Restart Policy: Always
- **Neural Network Container**:
- Base Image: NVIDIA CUDA 11.6 + Python 3.9
- Resources: 2 CPU cores, 4GB RAM, 1 GPU
- Volumes: Model volume, shared data volume
- Network: Internal network
- Restart Policy: Always
- **Pose Estimation Container**:
- Base Image: Python 3.9-slim
- Resources: 2 CPU cores, 2GB RAM
- Volumes: Shared data volume
- Network: Internal network
- Restart Policy: Always
- **API Services Container**:
- Base Image: Python 3.9-slim
- Resources: 2 CPU cores, 2GB RAM
- Volumes: Configuration volume
- Network: Internal and external networks
- Ports: 8000 (REST), 8001 (WebSocket)
- Restart Policy: Always
#### 5.2.2 Support Containers
- **Database Container**:
- Base Image: TimescaleDB (PostgreSQL extension)
- Resources: 2 CPU cores, 4GB RAM
- Volumes: Persistent data volume
- Network: Internal network
- Restart Policy: Always
- **MQTT Broker Container**:
- Base Image: Eclipse Mosquitto
- Resources: 1 CPU core, 1GB RAM
- Volumes: Configuration volume
- Network: Internal and external networks
- Ports: 1883 (MQTT), 8883 (MQTT over TLS)
- Restart Policy: Always
- **Redis Cache Container**:
- Base Image: Redis Alpine
- Resources: 1 CPU core, 2GB RAM
- Volumes: Persistent data volume
- Network: Internal network
- Restart Policy: Always
- **Monitoring Container**:
- Base Image: Prometheus + Grafana
- Resources: 1 CPU core, 2GB RAM
- Volumes: Persistent data volume
- Network: Internal network
- Ports: 9090 (Prometheus), 3000 (Grafana)
- Restart Policy: Always
### 5.3 Kubernetes Deployment Architecture
```mermaid
graph TD
subgraph Kubernetes_Cluster
subgraph Core_Services
A[CSI Collector Deployment]
B[Neural Network Deployment]
C[Pose Estimation Deployment]
D[API Gateway Deployment]
end
subgraph Data_Services
E[Database StatefulSet]
F[Redis StatefulSet]
G[MQTT Broker Deployment]
end
subgraph Frontend_Services
H[Web Dashboard Deployment]
I[Streaming Server Deployment]
end
subgraph Infrastructure
J[Ingress Controller]
K[Prometheus Operator]
L[Cert Manager]
end
J --> D
J --> H
J --> I
K -.-> Core_Services
K -.-> Data_Services
K -.-> Frontend_Services
A --> B
B --> C
C --> D
D --> E
D --> F
D --> G
end
```
### 5.4 Deployment Configurations
#### 5.4.1 Development Environment
- **Deployment Method**: Docker Compose
- **Infrastructure**: Local development machine
- **Scaling**: Single instance of each container
- **Data Persistence**: Local volumes
- **Monitoring**: Basic logging and metrics
#### 5.4.2 Testing Environment
- **Deployment Method**: Kubernetes (minikube or kind)
- **Infrastructure**: Dedicated test server
- **Scaling**: Single instance with realistic data
- **Data Persistence**: Ephemeral with test datasets
- **Monitoring**: Full monitoring stack for performance testing
#### 5.4.3 Production Environment
- **Deployment Method**: Kubernetes
- **Infrastructure**: Cloud provider or on-premises cluster
- **Scaling**: Multiple instances with auto-scaling
- **Data Persistence**: Managed database services or persistent volumes
- **Monitoring**: Comprehensive monitoring, alerting, and logging
- **High Availability**: Multi-zone deployment with redundancy
#### 5.4.4 Edge Deployment
- **Deployment Method**: Docker or K3s
- **Infrastructure**: Edge devices with GPU capability
- **Scaling**: Resource-constrained single instance
- **Data Persistence**: Local storage with cloud backup
- **Monitoring**: Lightweight monitoring with cloud reporting
- **Connectivity**: Offline operation capability with sync
---
## 6. Scalability and Performance Architecture
### 6.1 Horizontal Scaling Strategy
```mermaid
graph TD
A[Load Balancer] --> B1[API Gateway Instance 1]
A --> B2[API Gateway Instance 2]
A --> B3[API Gateway Instance n]
B1 --> C1[Processing Pipeline 1]
B2 --> C2[Processing Pipeline 2]
B3 --> C3[Processing Pipeline n]
C1 --> D[Shared Database Cluster]
C2 --> D
C3 --> D
C1 --> E[Shared Cache Cluster]
C2 --> E
C3 --> E
```
### 6.2 Vertical Scaling Considerations
- **Neural Network Container**: GPU memory is the primary constraint
- **Database Container**: I/O performance and memory for time-series data
- **API Services Container**: CPU cores for concurrent request handling
- **CSI Collector Container**: Network I/O for multiple router streams
### 6.3 Performance Optimization Points
- **Batch Processing**: Neural network inference batching
- **Caching Strategy**: Multi-level caching for API responses
- **Database Indexing**: Optimized indexes for time-series queries
- **Connection Pooling**: Database and service connection reuse
- **Asynchronous Processing**: Non-blocking I/O throughout the system
- **Resource Allocation**: Right-sizing containers for workloads
---
## 7. Security Architecture
### 7.1 Authentication and Authorization
```mermaid
graph TD
A[Client Request] --> B[API Gateway]
B --> C{Authentication}
C -->|Invalid| D[Reject Request]
C -->|Valid| E{Authorization}
E -->|Unauthorized| F[Reject Request]
E -->|Authorized| G[Process Request]
subgraph Auth_Services
H[JWT Service]
I[API Key Service]
J[Role Service]
K[Permission Service]
end
C -.-> H
C -.-> I
E -.-> J
E -.-> K
```
### 7.2 Data Protection
- **In Transit**: TLS 1.3 for all external communications
- **At Rest**: Database encryption for sensitive data
- **Processing**: Memory protection and secure coding practices
- **Privacy**: Data minimization and anonymization by design
### 7.3 Network Security
- **API Gateway**: Single entry point with security controls
- **Network Segmentation**: Internal services not directly accessible
- **Firewall Rules**: Restrictive inbound/outbound rules
- **Rate Limiting**: Protection against abuse and DoS attacks
---
## 8. Monitoring and Observability Architecture
### 8.1 Metrics Collection
```mermaid
graph TD
subgraph Components
A1[CSI Collector]
A2[Neural Network]
A3[Pose Estimator]
A4[API Services]
end
subgraph Metrics_Collection
B[Prometheus]
end
subgraph Visualization
C[Grafana]
end
subgraph Alerting
D[Alert Manager]
end
A1 --> B
A2 --> B
A3 --> B
A4 --> B
B --> C
B --> D
D --> E[Notification Channels]
```
### 8.2 Logging Architecture
- **Centralized Logging**: ELK stack or similar
- **Log Levels**: ERROR, WARN, INFO, DEBUG, TRACE
- **Structured Logging**: JSON format with consistent fields
- **Correlation IDs**: Request tracing across components
- **Retention Policy**: Tiered storage with age-based policies
### 8.3 Health Checks and Probes
- **Liveness Probes**: Detect and restart failed containers
- **Readiness Probes**: Prevent traffic to initializing containers
- **Startup Probes**: Allow for longer initialization times
- **Deep Health Checks**: Verify component functionality beyond basic connectivity
---
## 9. Disaster Recovery and High Availability
### 9.1 Backup Strategy
- **Database Backups**: Regular snapshots and transaction logs
- **Configuration Backups**: Version-controlled configuration repository
- **Model Backups**: Neural network model versioning and storage
- **Restoration Testing**: Regular backup restoration validation
### 9.2 High Availability Architecture
```mermaid
graph TD
subgraph Zone_A
A1[API Gateway A]
B1[Processing Pipeline A]
C1[Database Node A]
end
subgraph Zone_B
A2[API Gateway B]
B2[Processing Pipeline B]
C2[Database Node B]
end
subgraph Zone_C
A3[API Gateway C]
B3[Processing Pipeline C]
C3[Database Node C]
end
D[Global Load Balancer] --> A1
D --> A2
D --> A3
C1 --- C2
C2 --- C3
C3 --- C1
```
### 9.3 Failure Recovery Procedures
- **Automatic Recovery**: Self-healing for common failure scenarios
- **Manual Intervention**: Documented procedures for complex failures
- **Degraded Operation**: Graceful degradation under resource constraints
- **Data Consistency**: Recovery with data integrity preservation
---
## 10. Future Extensibility
### 10.1 Extension Points
- **Plugin Architecture**: Modular design for custom extensions
- **API Versioning**: Backward compatibility with version evolution
- **Feature Flags**: Runtime toggling of experimental features
- **Configuration Templates**: Domain-specific configuration packages
### 10.2 Integration Capabilities
- **Standard Protocols**: REST, WebSocket, MQTT, Webhooks
- **Custom Adapters**: Framework for custom integration development
- **Data Export**: Standardized formats for external analysis
- **Event Streaming**: Real-time event distribution for integrations
---
## 11. Conclusion
The WiFi-DensePose system architecture provides a robust, scalable, and secure foundation for privacy-preserving human pose estimation using WiFi signals. The modular design enables deployment across various environments from edge devices to cloud infrastructure, while the well-defined interfaces ensure extensibility and integration with external systems.
Key architectural decisions prioritize:
- Real-time performance with end-to-end latency under 100ms
- Privacy preservation through camera-free sensing
- Scalability to support multiple concurrent users
- Reliability with fault tolerance and high availability
- Security by design with comprehensive protection measures
- Extensibility through modular components and standard interfaces
This architecture supports the system requirements while providing a clear roadmap for implementation and future enhancements.