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

Each bin is processed via a Windowed Angle FFT.
Phase Preservation: Magnitude is never taken before the FFT. Complex inputs ensure beamforming works.
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:

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":

Azimuth Variance: In the RA heatmap, energy should be non-uniform across the angle axis. Objects should appear as discrete blobs.
Target Alignment: The "Orange Blobs" in the RA Sector plot must spatially align with the "White Points" in the 3D LiDAR point cloud.
V=0 Vertical: In the RD heatmap, static geometry (ground/buildings) must form a sharp vertical line at the 0 m/s mark.
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

4.7 KiB Raw Blame History