# 🚀 Auto MCAP & SHENRON Integration Architecture

This document describes the automated pipeline for generating, processing, and visualizing high-fidelity radar data within the Fox CARLA Simulation project.

---

## 🏗️ 1. The Three-Stage Pipeline

Every time a simulation is triggered (e.g., via `run.bat`), the system follows a deterministic three-stage process:

### Stage 1: Live Simulation (`src/main.py`)
- **Objective:** Generate raw multi-modal sensor data from the CARLA simulator.
- **Output:** `data/<session>/lidar/*.npy`, `camera/*.png`, and `frames.jsonl`.
- **Key Feature:** LiDAR is saved with **Semantic Tags** and **Radial Velocity** calculations, which are essential inputs for the physics-based radar model.

### Stage 2: Shenron Synthesis (`scripts/generate_shenron.py`)
- **Objective:** Convert LiDAR point clouds into high-fidelity radar signals.
- **Logic:** Calls `ShenronRadarModel` to perform FMCW signal synthesis.
- **Improved Output:**
    - `shenron_radar/*.npy`: 3D Radar Point Cloud (x, y, z, vel, mag).
    - `metrology/rd/*.npy`: Range-Doppler Heatmaps.
    - `metrology/ra/*.npy`: Range-Azimuth Heatmaps.
    - `metrology/cfar/*.npy`: CFAR threshold masks.
    - `range_axis.npy` & `angle_axis.npy`: Physical axis definitions for visualization.
- **Physics Constraint:** As of Iteration 26, all artificial normalizations (e.g. 1/1000) have been removed. Signals follow the pure **1/R⁴ Radar Range Equation**.

### Stage 3: MCAP Conversion (`scripts/data_to_mcap.py`)
- **Objective:** Package all disparate files into a single Foxglove-compatible `.mcap` log.
- **Visual Enhancement:** Implements **Polar Scan Conversion** for the RA map, projecting the rectangular $(R, \theta)$ data onto a forward-facing BEV sector.
- **Final Output:** `data/<session>/<session>.mcap`.

---

## 🛰️ 2. Core Metrology Algorithms

The current system implements several state-of-the-art radar processing fixes to ensure simulation fidelity matches real-world hardware.

### A. Doppler-Slice RA Accumulation
To prevent angular smearing, the Range-Azimuth map is generated by looping over Doppler bins.
1. Each bin is processed via a **Windowed Angle FFT**.
2. **Phase Preservation:** Magnitude is never taken before the FFT. Complex inputs ensure beamforming works.
3. Power is summed **Incoherently** across Doppler bins *after* the FFT.

### B. Incoherent RD Integration
The Range-Doppler map uses **Incoherent Power Summation** across receiver antenna channels ($|FFT|^2$). This preserves signal energy from moving targets that would otherwise cancel out due to phase misalignment if simple averaging was used.

### C. 120° Symmetric Sector Scan-Conversion
The RA visualizer uses a **Radial Projection** to create a true Birds-Eye View (BEV) fan.
- **Symmetry-Lock:** As of Iteration 21, the FFT indices are perfectly centered to ensure the fan is symmetric around the boresight (0°).
- **Aesthetic:** Uses the **Viridis (Radar Blue)** colormap with **Global Normalization**. 
- **Physics Fidelity:** No per-range-bin normalization is allowed. Brightness must decay with distance ($M \propto 1/R^2$) to represent real-world sensor behavior.

---

## 📁 3. Data Structure Reference

A successful automated run will produce the following structure:

```text
data/
└── scenario_timestamp/
    ├── frames.jsonl          # Metadata & Synchronization
    ├── lidar/                # Semantic LiDAR [N, 7]
    ├── camera/               # Dashcam imagery
    ├── shenron_radar/        # 3D Radar Point Cloud [M, 5]
    ├── metrology/            # Diagnostic Heatmaps
    │   ├── rd/               # Range-Doppler
    │   ├── ra/               # Range-Azimuth
    │   ├── cfar/             # CFAR mask
    │   ├── range_axis.npy    # Physical Range Axis (metres)
    │   └── angle_axis.npy    # Physical Azimuth Axis (radians)
    └── scenario_timestamp.mcap # Final Foxglove Package
```

---

## 🧭 4. Interpretation Guide for AI Agents

When evaluating a session, AI agents should look for the following "Success Indicators":

1.  **Azimuth Variance:** In the RA heatmap, energy should be non-uniform across the angle axis. Objects should appear as discrete blobs.
2.  **Target Alignment:** The "Orange Blobs" in the RA Sector plot must spatially align with the "White Points" in the 3D LiDAR point cloud.
3.  **V=0 Vertical:** In the RD heatmap, static geometry (ground/buildings) must form a sharp vertical line at the 0 m/s mark.
4.  **Inverse Square Decay:** Target intensity in heatmaps should naturally decrease as range increases ($1/R^2$ in voltage, $1/R^4$ in power). Near-field objects must dominate the energy profile.

---
*Documented by Antigravity | Project: Fox CARLA ADAS | 2026-04-01*