diff --git a/intel/radar/metrology_suite/Auto_MCAP_SHENRON.md b/intel/radar/metrology_suite/Auto_MCAP_SHENRON.md index bc9c690..c3d88a3 100644 --- a/intel/radar/metrology_suite/Auto_MCAP_SHENRON.md +++ b/intel/radar/metrology_suite/Auto_MCAP_SHENRON.md @@ -13,48 +13,44 @@ Every time a simulation is triggered (e.g., via `run.bat`), the system follows a - **Output:** `data//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. +### Stage 2: Multi-Radar Synthesis (`scripts/generate_shenron.py`) +- **Objective:** Convert LiDAR point clouds into high-fidelity radar signals for multiple hardware profiles. +- **Logic:** Calls `ShenronRadarModel` concurrently for **awrl1432** and **radarbook**. - **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**. + - `awrl1432/` & `radarbook/`: Dedicated synthesis folders per radar type. + - `{r_type}/metrology/`: Nested diagnostic heatmaps (RD, RA, CFAR). + - `{r_type}/metrology/metrics.jsonl`: Automated **Telemetry** records (SNR, Noise Floor). +- **Physics Constraint:** All signals follow the pure **1/R⁴ Radar Range Equation** with hardware-specific gain offsets. ### 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//.mcap`. +- **Objective:** Package all hardware profiles and metrics into a unified Foxglove log. +- **Topic Alignment:** Follows the standardized `test_shenron` namespace: + - `/radar/native`: Raw CARLA radar. + - `/radar/awrl1432/...`: TI-style radar data and metrology. + - `/radar/radarbook/...`: Logic-style radar data and metrology. +- **Visual Enhancement:** Implements **Polar Scan Conversion** for RA maps and publishes **Telemetry** curves for live signal monitoring. --- -## 🛰️ 2. Core Metrology Algorithms +## 🛰️ 2. Core Metrology & Telemetry -The current system implements several state-of-the-art radar processing fixes to ensure simulation fidelity matches real-world hardware. +### A. Signal Quality Metrics (Telemetry) +The simulation now tracks real-time signal health using the `foxglove.Telemetry` schema. +- **Peak SNR (dB):** Tracks the separation between the strongest reflection and the noise floor. +- **Avg Noise Floor:** Monitors ambient thermal and phase noise in the RD spectrum. +- **Active Bins:** Counts detections surviving the CFAR threshold. -### A. Doppler-Slice RA Accumulation +### B. 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: +A successful automated run will produce the following nested structure: ```text data/ @@ -62,14 +58,15 @@ data/ ├── 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 + ├── awrl1432/ # TI 1432 Radar PCD & Metrology + │ └── metrology/ + │ ├── metrics.jsonl # Telemetry logs + │ ├── rd/ # RD Heatmaps + │ └── ... + ├── radarbook/ # RadarBook PCD & Metrology + │ └── metrology/ + │ └── ... + └── scenario_timestamp.mcap # Final Unified Log ``` --- @@ -78,10 +75,10 @@ data/ 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. +1. **Hardware Parity:** Compare `/radar/awrl1432` vs `/radar/radarbook`. Differences in range/velocity resolution should match the physical hardware specs. +2. **Telemetry Health:** In Foxglove, the **Telemetry** panel should show a stable SNR curve. Sudden drops suggest occlusion or sensor saturation. +3. **Target Alignment:** The "Jet Spectrum" blobs in the RA Sector plot must spatially align with the "White Points" in the 3D LiDAR point cloud. +4. **V=0 Vertical:** Static geometry in the RD heatmap must form a sharp vertical line at the 0 m/s mark, confirming clutter removal is working. --- -*Documented by Antigravity | Project: Fox CARLA ADAS | 2026-04-01* +*Documented by Antigravity | Project: Fox CARLA ADAS | 2026-04-09* diff --git a/intel/radar/metrology_suite/README.md b/intel/radar/metrology_suite/README.md index d640303..a3e3075 100644 --- a/intel/radar/metrology_suite/README.md +++ b/intel/radar/metrology_suite/README.md @@ -57,6 +57,11 @@ Current state: Performs 2D FFT and CA-CFAR detection. - [x] Inspect raw `.npy` files for precision integrity. - [x] Verify Foxglove visual alignment. +### Phase 5: Pipeline Alignment (COMPLETED) +- [X] Integrated Multi-Radar support (`awrl1432` + `radarbook`). +- [X] Standardized Topic Naming (`/radar/native`, `/radar/{type}/metrics`). +- [X] Synchronized `run.bat` logic for Dashboard-ready automation. + --- ## 🧭 4. Pointers for Future Agents diff --git a/intel/radar/metrology_suite/walkthrough.md b/intel/radar/metrology_suite/walkthrough.md index 1b480c7..eed5ac5 100644 --- a/intel/radar/metrology_suite/walkthrough.md +++ b/intel/radar/metrology_suite/walkthrough.md @@ -1,76 +1,73 @@ -# 🪐 Walkthrough: Radar Metrology Suite (Iteration 18) +# 🪐 Walkthrough: Simulation Pipeline Alignment (Iteration 19) -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. +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 Metrology Suite has successfully transitioned the simulation from generating "Points" to generating a complete **Signal Spectrum**. +The simulation pipeline now behaves as a production-grade ADAS testbench, generating multi-radar data and telemetry in a single automated pass. -- **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. +- **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. Visual Diagnostic Capabilities +## 📡 2. Unified Hardware Namespace -We have introduced three new specialized heatmaps, now available as live topics in Foxglove: +Visualization topics in Foxglove are now organized by hardware profile for easy comparison: -| Topic | Channel | Colormap | Purpose | +| Topic Namespace | Component | 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). | +| `/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 -For every frame processed, the system now persists bit-perfect data for offline engineering analysis. +The system persists data in a hardware-centric hierarchy inside each session folder. -### Raw Signal Dumps (`metrology/`) -Saved in `Shenron_debug/iterations///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. +### Raw Signal Dumps +Saved in `data///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. -### 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. +### 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 (Iteration 18) +## 🏁 4. Verification Results -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`. +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 Use & Debug +## 🛠️ 5. How to Launch -### 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 " -``` +The pipeline is now optimized for "One-Click" execution via the Dashboard or CLI: -### Signal Verification Utility -Use the specialized verification tool to check a single frame's signal chain: +### Scenario CLI ```powershell -cmd /c "C:\ProgramData\miniconda3\Scripts\activate.bat carla312 && python scripts/analysis/verify_metrology_logic.py" +./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 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. +> **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-08* +*Verified by Antigravity | Date: 2026-04-09* diff --git a/intel/radar/shenron_implementation_guide.md b/intel/radar/shenron_implementation_guide.md index 6c6cdda..f947c2d 100644 --- a/intel/radar/shenron_implementation_guide.md +++ b/intel/radar/shenron_implementation_guide.md @@ -55,20 +55,21 @@ In `src/sensors.py`, you must change the LiDAR blueprint to the **semantic** ver ``` ### Step 2: Implement the Batch Processor -Create `scripts/generate_shenron.py`. This script acts as a wrapper for the `ISOLATE` package. It iterates through your `data/` directory, looks for `lidar/` folders, and generates a corresponding `shenron_radar/` folder. +Create `scripts/generate_shenron.py`. This script acts as a wrapper for the `ISOLATE` package. It iterates through your `data/` directory, looks for `lidar/` folders, and generates corresponding hardware folders (e.g. `awrl1432/`, `radarbook/`). > [!TIP] > Use the **`heatmap_gen_fast.py`** logic within the processor to leverage CUDA/GPU acceleration for the FMCW signal generation. ### Step 3: Update the MCAP Writer -Modify `scripts/data_to_mcap.py` to recognize the new `shenron_radar/` directory. +Modify `scripts/data_to_mcap.py` to recognize the new hardware directories. **File:** [`scripts/data_to_mcap.py`](file:///d:/Work/Repo/C-Shenron/scripts/data_to_mcap.py) ```python -# Add a check for the shenron folder -shenron_path = session_dir / "shenron_radar" -if shenron_path.exists(): - # Write to Foxglove topic: "/radar/shenron" +# Loop over hardware profiles +for r_type in ['awrl1432', 'radarbook']: + shenron_path = session_dir / r_type + if shenron_path.exists(): + # Write to Foxglove topic: "/radar/{r_type}" ``` --- diff --git a/intel/radar/shenron_integration.md b/intel/radar/shenron_integration.md index a980705..acb74bb 100644 --- a/intel/radar/shenron_integration.md +++ b/intel/radar/shenron_integration.md @@ -27,27 +27,28 @@ Modify `convert_to_pcd()` to preserve the magnitude of the detected peaks. - **New**: Returns `[x, y, z, velocity, magnitude]`. ### [NEW] `ISOLATE/model_wrapper.py` -The wrapper will now handle the "Rich" data synthesis: -1. Call `Sceneset` to get the ground-truth physical power (RCS). -2. Call `HeatmapGen` to generate the noisy ADC stream. +The wrapper handles "Rich" data synthesis and telemetry: +1. Call `Sceneset` for ground-truth physical power (RCS). +2. Call `HeatmapGen` for the noisy ADC stream. 3. Call `RadarProcessor` to extract detected peaks. -4. Merge the detected peaks with the underlying RCS data to provide a complete "Semantic Radar" point cloud. +4. **Telemetry**: New `get_signal_metrics()` method exports SNR and noise floor data. --- ## Phase 3: Modular Pipeline Integration -... (Previously defined) - ---- -## Verification Plan +The automated pipeline now supports concurrent hardware simulation. -### Automated Verification -1. **API Integrity**: Run a script that initializes the `ShenronRadarModel` and passes a dummy [N, 7] array to ensure it executes and returns the correct [N, 4] shape. -2. **Batch Run**: Execute `generate_shenron.py` on an existing dataset. +### [MODIFY] `scripts/generate_shenron.py` +Loop through multiple hardware profiles: +- **AWRL1432**: Short-range, high-resolution. +- **RadarBook**: Long-range standard. -### Manual Verification -1. Compare the MCAP output with vs. without the Shenron layer to ensure topic alignment. +### [MODIFY] `scripts/data_to_mcap.py` +UnifiedTopic Management: +- `/radar/native` +- `/radar/awrl1432` +- `/radar/radarbook` --- @@ -56,9 +57,9 @@ The wrapper will now handle the "Rich" data synthesis: ### Automated Verification 1. **Pilot Run**: Record a 100-frame scenario with semantic LiDAR. 2. **Post-Process**: Run `python scripts/generate_shenron.py`. -3. **Check Output**: Verify `data//shenron_radar/` contains 100 `.npy` files. +3. **Check Output**: Verify `data//awrl1432/` and `radarbook/` contain 100 `.npy` files each. ### Manual Verification 1. Run `python scripts/data_to_mcap.py`. -2. Open the MCAP in Foxglove and verify that the `/radar/shenron` topic perfectly overlays with the `/lidar` data but shows radar-typical noise and sparsity. +2. Open the MCAP in Foxglove and verify that the `/radar/radarbook/metrics` topic shows stable telemetry curves. diff --git a/intel/scenarios/dashboard.md b/intel/scenarios/dashboard.md index 0d99803..6ec0c65 100644 --- a/intel/scenarios/dashboard.md +++ b/intel/scenarios/dashboard.md @@ -45,6 +45,8 @@ When the `/api/run` endpoint is hit: Flask builds the command array. A payload of `{"scenario": "showcase", "frames": 50}` translates to the equivalent of typing: `cmd.exe /c run.bat showcase --frames 50` + *Note: `run.bat` supports **Smart Argument Detection**. It intelligently determines if CLI flags (like `-s` or `--scenario`) are already present in the command array to prevent redundant prefixing.* + 2. **Subprocess Spawning:** Flask leverages Python's `subprocess.Popen` to spawn a detached child process running the constructed command. - `cwd=PROJECT_ROOT`: Ensures `run.bat` is executed contextually from the root workspace so relative imports inside `src/main.py` do not break.