# Processing Engine Documentation

## Overview

The Python processing engine is responsible for performing computationally intensive tasks like RF signal analysis, NeRF model training, Gaussian Splatting optimization, and motion tracking using Neural Correspondence Fields. It's designed to be executed as a separate process, typically invoked by the backend's job queue system.

## Key Scripts

*   **`python-processing.py`:**
    *   The main entry point for processing jobs.
    *   Parses command-line arguments passed by the backend (job type, dataset paths, output directory, job ID, parameters).
    *   Initializes the `RFProcessingEngine` class.
    *   Loads data using appropriate loaders based on file extensions.
    *   Orchestrates the execution of the selected job type (`rf_nerf`, `motion_tracking`, `gaussian_splat`, `statistical_analysis`).
    *   Handles progress reporting (by printing `PROGRESS: <percentage>`) and saving results (like `visualization.json`, `statistics.json`, and other output files) to the specified output directory.
    *   Selects between standard PyTorch implementations and CUDA Python accelerated versions based on availability and parameters.
*   **`nerf-rf-engine.py`:**
    *   Defines the core PyTorch-based `RFNeRFModel` (the NeRF network architecture).
    *   Defines the standard PyTorch-based `RFNeRFRenderer` for volumetric rendering.
    *   Defines the standard `RFDataProcessor` for handling RF data loading, preprocessing (like Kalman filtering), feature extraction (IQ, CSI), and grid interpolation (using SciPy).
    *   Includes a `if __name__ == "__main__":` block for benchmarking the PyTorch vs. CUDA Python implementations.
*   **`cuda_rf_processor.py`:**
    *   Contains the `CUDARFDataProcessor` class.
    *   Provides GPU-accelerated implementations of data processing tasks using CuPy for array operations and Numba (`@cuda.jit`) for custom CUDA kernels (e.g., IQ processing, Kalman filter steps, grid interpolation using inverse distance weighting).
*   **`cuda_nerf_renderer.py`:**
    *   Contains the `CUDANeRFRenderer` class.
    *   Implements GPU-accelerated NeRF rendering.
    *   Uses Numba CUDA kernels for ray generation (`_generate_rays_kernel`), point sampling (`_sample_points_kernel`), and volumetric integration (`_volumetric_render_kernel`).
    *   Interfaces with the PyTorch `RFNeRFModel` for network inference but performs rendering steps directly on the GPU.
*   **`neural-correspondence.py`:**
    *   Defines the `NeuralCorrespondenceField` model for learning motion and temporal dynamics.
    *   Includes the `MotionTracker` class for tracking points over time using the NCF.
    *   Potentially includes related models like `DOMA` (Dynamic Object Motion Analysis) if implemented.
*   **`neural-gaussian-splats.py`:**
    *   Defines the `GaussianSplatModel`.
    *   Implements the logic for fitting Gaussian Splats to input data (positions, features, colors).
    *   Provides methods for rendering Gaussian Splats (though the frontend currently handles the final rendering).

## Job Types

The engine supports several processing job types, selected via the `--job-type` argument:

*   `rf_nerf`: Trains an RF-NeRF model on the input data and generates volumetric visualization data.
*   `motion_tracking`: Uses the Neural Correspondence Field model to track points or objects over time, generating trajectory data.
*   `gaussian_splat`: Fits a Neural Gaussian Splatting model to the data, producing parameters for splat-based visualization.
*   `statistical_analysis`: Performs various statistical analyses on the input RF data (e.g., spatial density, feature correlations, clustering) and generates reports/statistics.

## CUDA Python Acceleration

*   The system automatically detects if `cuda-python`, `numba`, and `cupy` are installed.
*   If available and enabled (via job parameters or default), the engine uses the `CUDARFDataProcessor` and `CUDANeRFRenderer` for significantly faster execution of data processing and NeRF rendering tasks.
*   CuPy replaces NumPy for GPU array operations.
*   Numba `@cuda.jit` kernels provide low-level GPU acceleration for specific algorithms.
*   This allows bypassing some PyTorch overhead for certain operations, leading to performance gains.

## RF NeRF Model Architecture

The `RFNeRFModel` class (defined in `nerf-rf-engine.py`) implements a Neural Radiance Field for RF data visualization with the following key components:

* **Positional Encoding**: Transforms 3D spatial coordinates using a multi-frequency encoding scheme to help the network learn high-frequency functions
* **Network Architecture**: Utilizes a multi-layer MLP (Multi-Layer Perceptron) with skip connections
* **Input Features**: Takes both spatial coordinates and RF signal features (e.g., frequency, amplitude, phase)
* **Dual Output Heads**: Outputs both color (RGB) and density values for volumetric rendering
* **Configuration Parameters**:
  * `encoding_dim`: Controls the frequency bands used in positional encoding (default: 10)
  * `hidden_dim`: Size of hidden layers (default: 256)
  * `num_layers`: Number of hidden layers (default: 8)
  * `rf_feature_dim`: Dimensions of RF signal features (default: 6)
  * `skip_connections`: Layers with skip connections from input (default: [4])

## Data Processing Features

The `RFDataProcessor` class handles diverse RF data formats with several key capabilities:

* **Kalman Filtering**: Implements a constant velocity model for smoothing signal position data
* **IQ Data Processing**: Extracts frequency domain features from raw IQ samples with band-specific analysis
* **WiFi CSI Processing**: Processes Channel State Information matrices into feature vectors including:
  * Signal strength metrics (RSSI)
  * Channel quality indicators
  * Phase coherence measurements
  * Spatial diversity metrics
* **Grid Interpolation**: Creates regular 3D grids of RF features from sparse measurements using linear interpolation
* **Medical Imaging Support**: Converts fMRI and other medical imaging data formats to RF feature representations

## Execution Flow

1.  The backend's job queue worker picks up a job.
2.  It executes `python-processing.py` using `child_process.exec`.
3.  Command-line arguments define the job specifics.
4.  `python-processing.py` initializes `RFProcessingEngine`.
5.  `RFProcessingEngine` selects appropriate processors (standard or CUDA-accelerated).
6.  Data is loaded and preprocessed.
7.  The specific job type method (e.g., `process_rf_nerf`) is called.
8.  Models are trained/evaluated as needed.
9.  Progress is reported via stdout (`PROGRESS: ...`).
10. Results (JSON files, potentially other outputs) are saved to the designated job result directory.
11. The script exits (code 0 for success, non-zero for failure).
12. The backend detects completion/failure and updates the job status in the database.

## Performance Benchmarking

The `nerf-rf-engine.py` script includes a benchmarking utility that:

* Compares PyTorch-only vs. CUDA Python accelerated implementations
* Measures grid creation and rendering performance
* Calculates speedups when CUDA Python acceleration is available
* Validates output consistency between implementations
* Can be invoked with `python nerf-rf-engine.py --benchmark --cuda-python`

## Dependencies

*   Python 3.8+
*   PyTorch (with CUDA support recommended)
*   NumPy
*   SciPy
*   Pandas (potentially used for data loading/analysis)
*   Matplotlib (potentially used for generating static plots/reports)
*   Scikit-learn (used for clustering, KNN in analysis)
*   Pydicom (for DICOM file loading)
*   Nibabel (for NIfTI file loading)
*   (Optional but recommended for performance) CUDA Python, Numba, CuPy