WiFi DensePose Python v1 vs Rust v2 Implementation: Key Differences Explained

The Rust v2 implementation transforms the Python v1 prototype into a production-grade system by replacing dynamic typing with compile-time safety, exception-based errors with Result types, and monolithic classes with modular structs and builder patterns.

The ruvnet/wifi-densepose repository contains two distinct implementations of a CSI (Channel State Information) processing pipeline for human pose estimation. While both versions perform preprocessing, feature extraction, and human-presence detection, the Python v1 and Rust v2 implementation differ fundamentally in architecture, type safety, and error handling. This guide breaks down the technical distinctions using actual source paths and code patterns from the repository.

Language Paradigm and Type Safety

The most immediate difference lies in the programming models. Python v1 uses a dynamically-typed, object-oriented approach centered on a single CSIProcessor class in v1/src/core/csi_processor.py. This class encapsulates all state, including configuration dictionaries and CSI history, with methods mutating internal state directly.

Rust v2, located in rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/src/csi_processor.rs, adopts a statically-typed, functional style. The logic splits between CsiProcessor and CsiPreprocessor structs. Type safety is enforced at compile time; for example, configuration parameters that might be missing or mistyped in Python become mandatory fields on CsiProcessorConfig, preventing runtime AttributeError or KeyError exceptions.

Error Handling: Exceptions vs Result Types

Error handling represents a architectural shift from implicit failure to explicit propagation.

Python v1 relies on a custom CSIProcessingError exception subclass. Methods raise this exception when encountering invalid configuration or malformed data:

# v1/src/core/csi_processor.py

if config["sampling_rate"] <= 0:
    raise CSIProcessingError("sampling_rate must be positive")

Unhandled exceptions bubble up to the caller, potentially crashing the async event loop if not caught.

Rust v2 replaces exceptions with the Result type. The CsiProcessorError enum, defined using the thiserror crate, implements std::error::Error. Every public operation returns Result<T, CsiProcessorError>, forcing callers to acknowledge failures:

// rust-port/wifi-densepose-rs/crates/wifi-densepose-signal/src/csi_processor.rs
pub fn preprocess(&mut self, data: &CsiData) -> Result<ProcessedCsi, CsiProcessorError> {
    if data.amplitude.is_empty() {
        return Err(CsiProcessorError::InvalidData("empty amplitude".into()));
    }
    // ...
}

This approach eliminates runtime panics for expected error conditions and makes failure modes visible in the function signature.

Configuration Management: Dicts vs Builder Pattern

Configuration handling evolves from runtime validation to compile-time construction.

In Python v1, configuration is a plain dict passed to the CSIProcessor constructor. Validation occurs inside _validate_config, which checks for required keys and value ranges at runtime:

config = {
    "sampling_rate": 1000,
    "window_size": 256,
    "overlap": 0.5,
    # Missing keys raise ValueError only when process_csi_data is called

}
processor = CSIProcessor(config, logger)

The Rust v2 implementation introduces CsiProcessorConfig, a serde-serializable struct with typed fields. A CsiProcessorConfigBuilder provides a fluent interface for construction, ensuring all mandatory fields are set before the object is created:

let config = CsiProcessorConfig::builder()
    .sampling_rate(1000.0)
    .window_size(256)
    .overlap(0.5)
    .noise_threshold(-30.0)
    .human_detection_threshold(0.8)
    .smoothing_factor(0.9)
    .max_history_size(500)
    .enable_preprocessing(true)
    .enable_feature_extraction(true)
    .enable_human_detection(true)
    .build()?; // Returns Err if validation fails

This pattern prevents invalid configurations from reaching the processing pipeline and provides clear error messages at the point of construction.

Architecture and Separation of Concerns

The Rust v2 implementation demonstrates stricter separation of concerns through modular design.

Python v1 consolidates preprocessing, feature extraction, and detection logic within the single CSIProcessor class. Private methods like _remove_noise, _apply_windowing, and _normalize_amplitude mutate internal state and access shared history buffers directly.

Rust v2 extracts preprocessing into a dedicated CsiPreprocessor struct, making the pipeline composition explicit and testable in isolation. The CsiProcessor orchestrates the flow while CsiPreprocessor handles the three-step transformation (noise removal, windowing, normalization). This modularity allows developers to swap or extend preprocessing steps without modifying the core processor logic.

Data Structures and Metadata Handling

Type safety extends to metadata representation.

In Python v1, metadata flows as arbitrary Dict[str, Any]. The code merges dictionaries at runtime: metadata={**csi_data.metadata, **local_metadata}. This flexibility risks runtime errors if keys are misspelled or types mismatch.

Rust v2 defines a CsiMetadata struct with explicit boolean flags (noise_filtered, windowed, normalized) and a HashMap<String, String> for custom entries. This structure enforces that metadata fields exist and carry the correct type, while still accommodating extensibility through the custom map.

History management shows similar discipline: Python uses collections.deque while Rust uses std::collections::VecDeque<CsiData>, with the Rust version enforcing that history entries conform to the CsiData struct layout.

Testing Strategy and Code Organization

Testing philosophy shifts from external verification to internal co-location.

Python v1 places unit and integration tests in separate directories: v1/tests/unit/*.py and v1/tests/integration/*.py. While this keeps the source tree clean, it risks drift between test mocks and actual implementation details.

Rust v2 embeds tests directly within the source files using #[cfg(test)] modules. Unit tests reside immediately below the implementation they verify, using the same imports and types. This ensures tests compile against the exact code they test and encourages maintenance of tests alongside feature changes. The Rust tests utilize ndarray for array assertions, mirroring the production code's data structures.

Dependencies and Performance Characteristics

The dependency stacks reflect each language's ecosystem.

Python v1 relies on numpy for numerical operations, scipy for signal processing, and asyncio for asynchronous event loops. These provide rapid development and rich scientific computing capabilities but incur runtime overhead and GIL constraints.

Rust v2 uses ndarray for n-dimensional arrays, num_complex for complex number support, chrono for timestamps, serde for serialization, and thiserror for ergonomic error definitions. These choices provide zero-cost abstractions, thread safety without GIL, and compile-time verification of data shapes.

The Rust implementation currently operates synchronously, though its type system allows async integration later. Python v1 declares process_csi_data as async, enabling immediate integration into async event loops at the cost of requiring await at every call site.

Summary

• Type Safety: Python v1 uses dynamic dictionaries and runtime validation; Rust v2 enforces configuration and metadata through statically-typed structs and builders.
• Error Handling: Python raises CSIProcessingError exceptions; Rust returns Result types with the CsiProcessorError enum, eliminating uncaught runtime failures.
• Architecture: Python bundles preprocessing and detection in a single CSIProcessor class; Rust separates concerns with CsiPreprocessor and CsiProcessor structs.
• Testing: Python keeps tests in external v1/tests/ directories; Rust co-locates #[cfg(test)] modules with source code for tighter integration.
• Dependencies: Python relies on numpy, scipy, and asyncio; Rust uses ndarray, serde, and thiserror for zero-cost abstractions without GIL constraints.

Frequently Asked Questions

What is the main architectural difference between the Python v1 and Rust v2 implementation?

The Python v1 implementation uses a monolithic CSIProcessor class that encapsulates preprocessing, feature extraction, and detection logic with private methods like _remove_noise and _apply_windowing. The Rust v2 implementation splits these responsibilities into distinct structs: CsiPreprocessor handles the three-step signal conditioning pipeline, while CsiProcessor orchestrates the workflow and maintains state. This separation makes the Rust version more modular and allows developers to test or replace individual pipeline stages without modifying the core processor.

How does error handling differ between the Python and Rust versions?

Python v1 uses exception-based error handling through a custom CSIProcessingError class. Methods raise this exception when encountering invalid configuration or malformed CSI data, and callers must wrap calls in try-except blocks to prevent crashes. Rust v2 eliminates exceptions entirely in favor of the Result<T, E> type. Every fallible operation returns a Result, with errors represented by the CsiProcessorError enum that implements std::error::Error. This forces callers to explicitly handle failures at compile time, preventing runtime panics and making error paths visible in function signatures.

Why did the Rust implementation adopt a builder pattern for configuration?

The Rust v2 implementation uses CsiProcessorConfigBuilder to construct CsiProcessorConfig structs because it provides compile-time guarantees that all required fields are set and valid before the processor is instantiated. Unlike Python v1, which accepts a plain dictionary and validates it at runtime inside _validate_config, the Rust builder pattern ensures that missing parameters or type mismatches trigger compiler errors rather than runtime ValueError exceptions. This approach also produces immutable configuration objects that can be safely shared across threads without risk of mutation.

Can the Rust v2 implementation handle asynchronous processing like Python v1?

Currently, the Rust v2 implementation operates synchronously, whereas Python v1 declares process_csi_data as an async function that can be awaited within an asyncio event loop. The synchronous Rust design simplifies the initial port and eliminates the complexity of async runtime management for signal processing tasks that are typically CPU-bound. However, because Rust uses zero-cost abstractions and the CsiProcessor methods do not hold references across await points, the codebase can be extended with async wrappers using crates like tokio without altering the core synchronous pipeline logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}