# 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.

> [!TIP]
> **New Feature:** For a detailed step-by-step guide on using these new tools, see the official [**Walkthrough Guide**](./walkthrough.md).

---

## 🎯 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.
*   **Implementation Status:** 
    -   Exposes the **3D FFT Cube** (Range x Doppler x Angle).
    -   Extracts the **Detection Gate** from `CA_CFAR.__call__`.
    -   Computes global **Range-Azimuth** energy maps via mean-Doppler reduction.

---

## 🗺️ 3. Implementation Roadmap

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

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

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

### Phase 4: Verification (COMPLETED)
- [x] Run Iteration 18 (250-frame simulation sweep).
- [x] Inspect raw `.npy` files for precision integrity.
- [x] Verify Foxglove visual alignment.

---

## 🧭 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-08*