# 🪐 Walkthrough: Simulation Pipeline Alignment (Iteration 19)

This walkthrough documents the full implementation of the **Simulation Pipeline Alignment**, which synchronizes the automated `run.bat` workflow with the high-fidelity diagnostic standards of the radar metrology suite.

---

## 🚀 1. Overview of Achievements

The simulation pipeline now behaves as a production-grade ADAS testbench, generating multi-radar data and telemetry in a single automated pass.

- **Multi-Radar Support:** Concurrent synthesis of `awrl1432` and `radarbook` hardware profiles.
- **Protocol Alignment:** Topics and folder structures now match the `test_shenron` testbench identically.
- **Telemetry Integration:** Automatic extraction of SNR, Noise Floor, and Detection Bins.
- **Seamless MCAP:** Single-pass packaging of all raw point clouds, metrology heatmaps, and telemetry curves.

---

## 📡 2. Unified Hardware Namespace

Visualization topics in Foxglove are now organized by hardware profile for easy comparison:

| Topic Namespace | Component | Colormap | Purpose |
| :--- | :--- | :--- | :--- |
| `/radar/native` | RAW CARLA | -- | Baseline physics points. |
| `/radar/{type}` | Shenron PCD | -- | High-fidelity rich point cloud. |
| `/radar/{type}/metrics` | Telemetry | Plot | SNR and Noise monitoring. |
| `/radar/{type}/heatmaps/ra`| RA Heatmap | **Jet** | Top-down spatial energy (BEV). |
| `/radar/{type}/heatmaps/rd`| RD Heatmap | **Viridis** | Range-Doppler spectrum analysis. |

---

## 📊 3. Deep Telemetry & Data Structure

The system persists data in a hardware-centric hierarchy inside each session folder.

### Raw Signal Dumps
Saved in `data/<session>/<radar_type>/metrology/`:
- **`rd/*.npy`**: Log-scaled power matrices.
- **`ra/*.npy`**: Polar-to-Cartesian scan-converted BEV maps.
- **`metrics.jsonl`**: Standardized telemetry records for Foxglove Telemetry panels.

### Performance Indicators
- **Real-time Streaming:** `PYTHONUNBUFFERED` logging enables instant SSE console feedback in the Dashboard.
- **GPU Acceleration:** Multi-radar synthesis is distributed across available CUDA cores.

---

## 🏁 4. Verification Results

Recent full-scale runs confirm **Protocol Parity**:
- **Topic Integrity:** MCAP files are now 1:1 compatible with testbench dashboards.
- **Metric Accuracy:** SNR extraction is verified against the RD spectrum across all active hardware profiles.

---

## 🛠️ 5. How to Launch

The pipeline is now optimized for "One-Click" execution via the Dashboard or CLI:

### Scenario CLI
```powershell
./run.bat braking --frames 200
```

### Dashboard GUI
Simply launch `dashboard.bat` and select your scenario. The post-processing (Shenron + MCAP) will trigger automatically upon completion.

---

> [!IMPORTANT]
> **Engineering Note:** The RA Heatmap has transitioned to the **Jet (Radar Spectrum)** colormap and includes a safety clip to prevent numerical overflow in the log-conversion stage.

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