Intel update after shenron complete integration. into main pipeline.

1 month ago · 548a8af313
6 changed files with 102 additions and 99 deletions
--- 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/<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.
 ### 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/<session>/<session>.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*
--- 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
--- 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/<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.
 ### 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.
 ### 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 <your_name>"
 ```
 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*
--- 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}"
 ```
 ---
--- 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/<session>/shenron_radar/` contains 100 `.npy` files.
 3. **Check Output**: Verify `data/<session>/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.
--- 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.