Simulator/intel/radar/metrology_suite

Radar Metrology Suite: Implementation Hub 🛰️

This directory serves as the source of truth for the C-SHENRON Radar Metrology Suite. The goal of this suite is to transform the physics-based radar simulation from a "Black Box" into a transparent "Radar Lab" environment.

[!TIP] New Feature: For a detailed step-by-step guide on using these new tools, see the official Walkthrough Guide.

---

🎯 1. The Core Objective

To provide radar application engineers with 100% visibility into the signal processing chain. This is achieved by extracting and visualizing the internal energy states of the simulation before they are filtered into discrete points.

Key Deliverables:

1. Visual Heatmaps: Real-time Range-Doppler (RD) and Range-Azimuth (RA) streams in Foxglove.
2. CFAR Transparency: A visual mask of the adaptive threshold plane.
3. Metrology Persistence: Raw .npy storage of all FFT buffers for offline validation.
4. Signal Telemetry: JSON-based SNR and Noise Floor tracking.

---

🏗️ 2. Technical Architecture

The suite hooks into the ISOLATE engine at the following points:

A. Signal Generation (heatmap_gen_fast.py)

Current state: Successfully converts LiDAR points into complex ADC time-series.

• Future Goal: Implement Multi-Path interference logic.

B. Signal Processing (radar_processor.py & cfar_detector.py)

Current state: Performs 2D FFT and CA-CFAR detection.

• Implementation Status:
  • Exposes the 3D FFT Cube (Range x Doppler x Angle).
  • Extracts the Detection Gate from CA_CFAR.__call__.
  • Computes global Range-Azimuth energy maps via mean-Doppler reduction.

---

🗺️ 3. Implementation Roadmap

Phase 1: Engine Heatmap Extraction (COMPLETED)

• Modify cfar_detector.py to return the detection_gate (Threshold Baseline).
• Update radar_processor.py to capture RD and compute global RA heatmaps.
• Update model_wrapper.py to expose heatmaps and signal telemetry.

Phase 2: Signal-to-Visual Pipeline (COMPLETED)

• Implement 8-bit normalization and Viridis colormapping for radar image topics.
• Update test_shenron.py to register new /heatmaps/ image channels in MCAP.
• Add JSON telemetry packaging for SNR/Noise metrics.

Phase 3: Raw Data Persistence (COMPLETED)

• Create metrology/rd, metrology/ra, and metrology/cfar directory structure.
• Implement .npy serialization for every frame during the simulation loop.

Phase 4: Verification (COMPLETED)

• Run Iteration 18 (250-frame simulation sweep).
• Inspect raw .npy files for precision integrity.
• Verify Foxglove visual alignment.

Phase 5: Pipeline Alignment (COMPLETED)

• Integrated Multi-Radar support (awrl1432 + radarbook).
• Standardized Topic Naming (/radar/native, /radar/{type}/metrics).
• Synchronized run.bat logic for Dashboard-ready automation.

---

🧭 4. Pointers for Future Agents

• Coordinate Frame: Always remember: Index 0 = Side (Y), Index 1 = Forward (X).
• Normalization: When converting raw FFT magnitudes to images, use a log-dB scale to preserve dynamic range.
• Performance: Keep the signal.convolve2d calls optimized; we must maintain at least 1.0 FPS for UX.

---

Created by Antigravity | Project: Fox CARLA ADAS | 2026-04-08