# Radar Metrology Suite: Implementation Hub 🛰️

This directory serves as the source of truth for the **C-SHENRON Radar Metrology Suite**. The goal of this suite is to transform the physics-based radar simulation from a "Black Box" into a transparent "Radar Lab" environment.

---

## 🎯 1. The Core Objective

To provide radar application engineers with 100% visibility into the signal processing chain. This is achieved by extracting and visualizing the internal energy states of the simulation before they are filtered into discrete points.

### Key Deliverables:
1.  **Visual Heatmaps:** Real-time Range-Doppler (RD) and Range-Azimuth (RA) streams in Foxglove.
2.  **CFAR Transparency:** A visual mask of the adaptive threshold plane.
3.  **Metrology Persistence:** Raw `.npy` storage of all FFT buffers for offline validation.
4.  **Signal Telemetry:** JSON-based SNR and Noise Floor tracking.

---

## 🏗️ 2. Technical Architecture

The suite hooks into the **ISOLATE** engine at the following points:

### A. Signal Generation (`heatmap_gen_fast.py`)
Current state: Successfully converts LiDAR points into complex ADC time-series.
*   **Future Goal:** Implement Multi-Path interference logic.

### B. Signal Processing (`radar_processor.py` & `cfar_detector.py`)
Current state: Performs 2D FFT and CA-CFAR detection.
*   **Modification Plan:** 
    -   Retain the **3D FFT Cube** (Range x Doppler x Angle).
    -   Extract the **Threshold Matrix** from `CA_CFAR.__call__`.
    -   Compute global **Range-Azimuth** energy maps via mean-Doppler reduction.

---

## 🗺️ 3. Active Implementation Roadmap

### Phase 1: Engine Heatmap Extraction (IN PROGRESS)
- [ ] Modify `cfar_detector.py` to return the `rd_avg_noise_power` (Threshold Baseline).
- [ ] Update `radar_processor.py` to capture RD and compute global RA heatmaps.
- [ ] Update `model_wrapper.py` to expose heatmaps and signal telemetry.

### Phase 2: Signal-to-Visual Pipeline (PENDING)
- [ ] Implement 8-bit normalization and Viridis colormapping for radar image topics.
- [ ] Update `test_shenron.py` to register new `/heatmaps/` image channels in MCAP.
- [ ] Add JSON telemetry packaging for SNR/Noise metrics.

### Phase 3: Raw Data Persistence (PENDING)
- [ ] Create `metrology/rd`, `metrology/ra`, and `metrology/cfar` directory structure.
- [ ] Implement `.npy` serialization for every frame during the simulation loop.

---

## 🧭 4. Pointers for Future Agents

*   **Coordinate Frame:** Always remember: `Index 0 = Side (Y)`, `Index 1 = Forward (X)`.
*   **Normalization:** When converting raw FFT magnitudes to images, use a log-dB scale to preserve dynamic range.
*   **Performance:** Keep the `signal.convolve2d` calls optimized; we must maintain at least 1.0 FPS for UX.

---
*Created by Antigravity | Project: Fox CARLA ADAS | 2026-04-07*