rust-port/wifi-densepose-rs/docs/ddd/ubiquitous-language.md
This glossary defines the domain terminology used throughout the WiFi-DensePose system. All team members (developers, domain experts, stakeholders) should use these terms consistently in code, documentation, and conversation.
The system that uses WiFi signals to perform non-invasive human pose estimation. Unlike camera-based systems, it operates through walls and in darkness, providing privacy-preserving body tracking.
The detailed information about how a WiFi signal propagates between transmitter and receiver. CSI captures amplitude and phase changes across multiple subcarriers and antennas, encoding environmental information including human presence and movement.
A computer vision technique that maps all pixels of a detected human body to a 3D surface representation. In our context, we translate WiFi signals into DensePose-compatible outputs.
The process of determining the position and orientation of a human body, typically by identifying anatomical landmarks (keypoints) and body segments.
The magnitude (strength) of the CSI measurement for a specific subcarrier and antenna pair. Amplitude variations indicate physical changes in the environment, particularly human movement.
Units: Linear scale or decibels (dB)
Example Usage:
let amplitude = csi_frame.amplitude(); // Matrix of amplitude values
The timing offset of the WiFi signal, measured in radians. Phase is highly sensitive to distance changes and is crucial for detecting subtle movements like breathing.
Units: Radians (-pi to pi)
Note: Raw phase requires sanitization (unwrapping, noise removal) before use.
An individual frequency component within an OFDM (Orthogonal Frequency-Division Multiplexing) WiFi signal. Each subcarrier provides an independent measurement of the channel state.
Typical Values:
A physical receiver element on the WiFi device. Multiple antennas enable MIMO (Multiple-Input Multiple-Output) and provide spatial diversity in CSI measurements.
Typical Configurations: 1x1, 2x2, 3x3, 4x4
A quality metric measuring the strength of the desired signal relative to background noise. Higher SNR indicates cleaner, more reliable CSI data.
Units: Decibels (dB)
Quality Thresholds:
The ambient electromagnetic interference level in the environment. The noise floor limits the minimum detectable signal.
Units: dBm (decibels relative to milliwatt)
A frequency change caused by moving objects. The Doppler effect in CSI reveals motion velocity and direction.
Formula: fd = (2 * v * f) / c
Where v is velocity, f is carrier frequency, c is speed of light.
The distribution of signal power across frequencies. PSD analysis reveals periodic motions like walking or breathing.
Units: dB/Hz
The process of computing meaningful statistics and transformations from raw CSI data. Features include amplitude mean/variance, phase differences, correlations, and frequency-domain characteristics.
Initial signal conditioning including:
The core innovation of WiFi-DensePose: converting radio frequency (RF) features into visual-like feature representations that can be processed by pose estimation models.
Also Known As: Cross-modal learning, RF-to-vision translation
Binary classification determining whether one or more humans are present in the sensing area. This is typically the first stage of the pose estimation pipeline.
The estimated number of individuals in the detection zone. Accurate counting is challenging with WiFi sensing due to signal superposition.
A named anatomical landmark on the human body. WiFi-DensePose uses the COCO keypoint format with 17 points:
| Index | Name | Description |
|---|---|---|
| 0 | Nose | Tip of nose |
| 1 | Left Eye | Center of left eye |
| 2 | Right Eye | Center of right eye |
| 3 | Left Ear | Left ear |
| 4 | Right Ear | Right ear |
| 5 | Left Shoulder | Left shoulder joint |
| 6 | Right Shoulder | Right shoulder joint |
| 7 | Left Elbow | Left elbow joint |
| 8 | Right Elbow | Right elbow joint |
| 9 | Left Wrist | Left wrist |
| 10 | Right Wrist | Right wrist |
| 11 | Left Hip | Left hip joint |
| 12 | Right Hip | Right hip joint |
| 13 | Left Knee | Left knee joint |
| 14 | Right Knee | Right knee joint |
| 15 | Left Ankle | Left ankle |
| 16 | Right Ankle | Right ankle |
A segmented region of the human body. DensePose defines 24 body parts:
| ID | Part | ID | Part |
|---|---|---|---|
| 1 | Torso | 13 | Left Lower Leg |
| 2 | Right Hand | 14 | Right Lower Leg |
| 3 | Left Hand | 15 | Left Foot |
| 4 | Right Foot | 16 | Right Foot |
| 5 | Left Foot | 17 | Right Upper Arm Back |
| 6 | Right Upper Arm Front | 18 | Left Upper Arm Back |
| 7 | Left Upper Arm Front | 19 | Right Lower Arm Back |
| 8 | Right Lower Arm Front | 20 | Left Lower Arm Back |
| 9 | Left Lower Arm Front | 21 | Right Upper Leg Back |
| 10 | Right Upper Leg Front | 22 | Left Upper Leg Back |
| 11 | Left Upper Leg Front | 23 | Right Lower Leg Back |
| 12 | Right Lower Leg Front | 24 | Left Lower Leg Back |
A 2D parameterization of the body surface. U and V are continuous coordinates (0-1) that map any point on the body to a canonical 3D mesh.
Purpose: Enable consistent body surface representation regardless of pose.
A rectangular region in the detection space that encloses a detected person.
Format: (x, y, width, height) in normalized coordinates [0, 1]
A probability value [0, 1] indicating the model's certainty in a detection or classification. Higher values indicate greater confidence.
Thresholds:
A high-level classification of what a person is doing:
| Activity | Description |
|---|---|
| Standing | Upright, stationary |
| Sitting | Seated position |
| Walking | Ambulatory movement |
| Running | Fast ambulatory movement |
| Lying | Horizontal position |
| Falling | Rapid transition to ground |
| Unknown | Unclassified activity |
Identification of a fall event, typically characterized by:
Critical Use Case: Elderly care, healthcare facilities
Recognition of significant movement in the sensing area. Motion is detected through:
A client connection for real-time data streaming. A session has a lifecycle: connecting, active, paused, reconnecting, completed, failed.
The category of data being streamed:
| Type | Data Content |
|---|---|
| Pose | Pose estimation results |
| CSI | Raw or processed CSI data |
| Alerts | Critical events (falls, motion) |
| Status | System health and metrics |
A logical or physical area for filtering and organizing detections. Zones enable:
A client's expressed interest in receiving specific data. Subscriptions include:
Sending data to all clients matching subscription criteria.
A periodic ping message to verify connection liveness. Clients that fail to respond to heartbeats are disconnected.
Flow control mechanism when a client cannot process messages fast enough. Options include:
The time delay between event occurrence and client receipt. Measured in milliseconds.
Target: < 100ms for real-time applications
A physical WiFi hardware unit capable of CSI extraction. Supported types:
| Type | Description |
|---|---|
| ESP32 | Low-cost microcontroller with WiFi |
| Atheros Router | Router with modified firmware |
| Intel NIC | Intel 5300/5500 network cards |
| Nexmon | Broadcom chips with Nexmon firmware |
| PicoScenes | Research-grade CSI platform |
Media Access Control address - a unique hardware identifier for network interfaces.
Format: XX:XX:XX:XX:XX:XX (hexadecimal)
Software running on the WiFi device that enables CSI extraction.
The process of tuning a device for optimal CSI quality:
Periodic verification that a device is functioning correctly. Checks include:
An interface for persisting and retrieving aggregate roots. Each aggregate type has its own repository.
Pattern: Repository pattern from Domain-Driven Design
An object with a distinct identity that persists over time. Entities are equal if their identifiers match.
Examples: Device, Session, CsiFrame
An object defined by its attributes rather than identity. Value objects are immutable and equal if all attributes match.
Examples: Frequency, Confidence, MacAddress
A cluster of entities and value objects treated as a single unit. One entity is the aggregate root; all access goes through it.
A persistence mechanism that stores domain events as the source of truth. Supports event sourcing and audit trails.
A logical boundary within which a particular domain model is defined and applicable. Each bounded context has its own ubiquitous language.
WiFi-DensePose Contexts:
A record of something significant that happened in the domain. Events are immutable and named in past tense.
Examples: CsiFrameReceived, PoseEstimated, FallDetected
A request to perform an action that may change system state.
Examples: ProcessCsiFrame, EstimatePose, ConnectDevice
A request for information that does not change state.
Examples: GetCurrentPose, GetDeviceStatus, GetSessionHistory
A unique identifier that links related events across the system, enabling end-to-end tracing.
The rate of data processing, typically measured in:
The duration to complete a processing step. Measured in milliseconds.
How closely estimates match ground truth. For pose estimation:
The proportion of positive detections that are correct.
Formula: TP / (TP + FP)
The proportion of actual positives that are detected.
Formula: TP / (TP + FN)
Harmonic mean of precision and recall.
Formula: 2 * (Precision * Recall) / (Precision + Recall)
| Acronym | Expansion |
|---|---|
| API | Application Programming Interface |
| CQRS | Command Query Responsibility Segregation |
| CSI | Channel State Information |
| dB | Decibel |
| dBm | Decibel-milliwatt |
| DDD | Domain-Driven Design |
| FPS | Frames Per Second |
| Hz | Hertz (cycles per second) |
| IoU | Intersection over Union |
| MAC | Media Access Control |
| MIMO | Multiple-Input Multiple-Output |
| OFDM | Orthogonal Frequency-Division Multiplexing |
| OKS | Object Keypoint Similarity |
| PSD | Power Spectral Density |
| RF | Radio Frequency |
| RSSI | Received Signal Strength Indicator |
| SNR | Signal-to-Noise Ratio |
| UUID | Universally Unique Identifier |
| UV | Texture mapping coordinates |
| VO | Value Object |
| WiFi | Wireless Fidelity (IEEE 802.11) |
| WS | WebSocket |
Use exact terms from this glossary:
// Good: Uses ubiquitous language
pub struct CsiFrame { ... }
pub fn detect_human_presence(&self) -> HumanPresenceResult { ... }
pub fn estimate_pose(&self) -> PoseEstimate { ... }
// Bad: Non-standard terminology
pub struct WifiData { ... } // Should be CsiFrame
pub fn find_people(&self) { ... } // Should be detect_human_presence
pub fn get_body_position(&self) { ... } // Should be estimate_pose
Always use defined terms; avoid synonyms that could cause confusion.
When discussing the system, use these terms consistently to ensure clear communication between technical and domain experts.
This glossary is a living document. To propose changes: