# 🪐 Walkthrough: Radar Metrology Suite (Iteration 18)

This walkthrough documents the full implementation and verification of the **Radar Metrology Suite**, a major architectural upgrade that exposes the internal signal processing states of the C-SHENRON radar engine for high-fidelity ADAS debugging.

---

## 🚀 1. Overview of Achievements

The Metrology Suite has successfully transitioned the simulation from generating "Points" to generating a complete **Signal Spectrum**. 

- **Phase 1 (Engine Extraction):** Modified the CA-CFAR and RadarProcessor to capture raw energy matrices.
- **Phase 2 (Visual Pipeline):** Implemented real-time image colormapping (Viridis/Magma/Plasma) and MCAP streaming.
- **Phase 3 (Persistence):** Established a structured hierarchy for raw `.npy` and `.jsonl` telemetry.
- **Phase 4 (Verification):** Completed a 250-frame simulation sweep (Iteration 18) proving system stability.

---

## 📡 2. Visual Diagnostic Capabilities

We have introduced three new specialized heatmaps, now available as live topics in Foxglove:

| Topic | Channel | Colormap | Purpose |
| :--- | :--- | :--- | :--- |
| `/radar/heatmaps/range_doppler` | RD Heatmap | **Viridis** | High-contrast view of targets in Velocity vs. Range space. |
| `/radar/heatmaps/range_azimuth` | RA Heatmap | **Magma** | Top-down spatial energy distribution (Bird's Eye View). |
| `/radar/heatmaps/cfar_mask` | Detection Gate| **Plasma** | Visualizes the "Detection Wall" (Noise $\times$ Threshold). |

---

## 📊 3. Deep Telemetry & Data Structure

For every frame processed, the system now persists bit-perfect data for offline engineering analysis.

### Raw Signal Dumps (`metrology/`)
Saved in `Shenron_debug/iterations/<iter_name>/<radar_type>/metrology/`:
- **`rd/*.npy`**: 256x64 Raw Power floating-point matrices.
- **`ra/*.npy`**: 256x256 Angular energy polar-coordinates.
- **`cfar/*.npy`**: The adaptive threshold baseline for that specific frame.

### Global Metrics (`metrics.jsonl`)
A frame-by-frame log of signal health, including:
- **`peak_snr_db`**: Signal-to-Noise ratio of the strongest target.
- **`avg_noise_floor`**: Estimated environment noise level.
- **`active_bins`**: Number of cells currently "breaking through" the CFAR gate.

---

## 🏁 4. Verification Results (Iteration 18)

The initial full-scale run of the suite confirmed **Optimal Signal Integrity**:
- **Peak SNR:** ~15.3 dB in peak frames (Confirmed by `metrics.jsonl`).
- **Processing Performance:** 16.63 Frames/Sec (Streaming images + PCD logic).
- **GPU Acceleration:** Confirmed active on `cuda:0:0`.

---

## 🛠️ 5. How to Use & Debug

### Launching the Metrology Suite
To run a new iteration with full metrology extraction:
```powershell
cmd /c "C:\ProgramData\miniconda3\Scripts\activate.bat carla312 && python scripts/test_shenron.py --iter <your_name>"
```

### Signal Verification Utility
Use the specialized verification tool to check a single frame's signal chain:
```powershell
cmd /c "C:\ProgramData\miniconda3\Scripts\activate.bat carla312 && python scripts/analysis/verify_metrology_logic.py"
```

---

> [!IMPORTANT]
> **Engineering Note:** The RA Heatmap uses a 1D Angle-FFT reduction across all Doppler bins. This provides a spatial "snapshot" that ignores velocity, making it ideal for checking multipath and ghosting against the ground-truth LiDAR map.

*Verified by Antigravity | Date: 2026-04-08*