Browse Source

docs(intel): Finalize document organization and AI navigation roadmap

Synchronized internal links, updated iteration history (01-13), and added prioritized AI guidance for radar and scenario tasks.
1843_integration
RUSHIL AMBARISH KADU 2 months ago
parent
commit
b5360b69b8
  1. 27
      intel/internal/context.md
  2. 57
      intel/radar/Shenron_debug.md

27
intel/internal/context.md

@ -59,10 +59,14 @@ Fox/
│ └── frames.jsonl ← One JSON record per frame (metadata + scenario info) │ └── frames.jsonl ← One JSON record per frame (metadata + scenario info)
└── intel/ └── intel/
├── context.md ← This file
├── dashboard.md ← Architecture doc for the Web GUI orchestrator
├── showcase.md ← Showcase scenario deep-dive
└── braking.md ← Spawning & physics post-mortem
├── radar/ ← [CRITICAL] Physics, Material RCS, and Debug logs
│ ├── Shenron_debug.md ← The "Source of Truth" for radar calibration
│ └── Sceneset_deepdive.md ← Reflection & Electromagnetic math
├── scenarios/ ← Operational manuals for driving simulations
│ ├── dashboard.md ← Web GUI Architecture
│ └── showcase.md ← Scenario-specific post-mortems
└── internal/ ← Project-wide context and developer guides
└── context.md ← This file (Primary entry point)
``` ```
--- ---
@ -71,7 +75,7 @@ Fox/
### `dashboard.bat` & `dashboard/` — Web GUI Orchestrator ### `dashboard.bat` & `dashboard/` — Web GUI Orchestrator
A Flask-based web dashboard that provides an intuitive interface for running CARLA scenarios without the CLI. It dynamically fetches available scenarios and config params, translates user choices into `run.bat` commands as a background subprocess, and heavily streams the unbuffered Python stdout text back to the browser using Server-Sent Events (SSE). A Flask-based web dashboard that provides an intuitive interface for running CARLA scenarios without the CLI. It dynamically fetches available scenarios and config params, translates user choices into `run.bat` commands as a background subprocess, and heavily streams the unbuffered Python stdout text back to the browser using Server-Sent Events (SSE).
> **Full Architecture details:** See `intel/dashboard.md` for a complete breakdown of API routing and extension guidelines.
> **Full Architecture details:** See `intel/scenarios/dashboard.md` for a complete breakdown of API routing and extension guidelines.
--- ---
@ -334,4 +338,15 @@ class MyScenario(ScenarioBase):
--- ---
*Last updated: 2026-03-31 | Pipeline version: Scenario-Centric Deterministic Architecture*
## 🤖 AI Agent Navigation Guide
When working on this repository, prioritize documentation based on your specific task:
- **Radar Physics or Calibration:** READ `intel/radar/Shenron_debug.md` FIRST. This is the source of truth for all FMCW and material RCS milestones.
- **Scenario Creation:** READ `intel/internal/context.md` for the plugin contract and `intel/scenarios/braking.md` for spawning examples.
- **Dashboard or GUI Logic:** READ `intel/scenarios/dashboard.md` for SSE and Flask-to-Subprocess architecture.
- **Historical Context:** Check `intel/internal/old_implement.md` if the user refers to legacy "Transfuser++" patterns.
---
*Last updated: 2026-04-06 | Pipeline version: Scenario-Centric Deterministic Architecture*

57
intel/radar/Shenron_debug.md

@ -1,7 +1,6 @@
# Shenron Physics Debug Log
**Date:** 2026-04-03
**Date:** 2026-04-03 — 2026-04-06 (Calibration Update)
**Engineer:** Fox ADAS Pipeline | Antigravity AI **Engineer:** Fox ADAS Pipeline | Antigravity AI
**Objective:** Resolve physics-based discrepancies in the C-Shenron synthetic radar pipeline, align with AWRL1432BOOST hardware performance, and establish a stable, high-fidelity simulation baseline.
**Objective:** Resolve physics-based discrepancies in the C-Shenron synthetic radar pipeline, calibrate physical materials for turn-stability, and align sensor coordinate frames for zero-parallax synchronization.
--- ---
@ -60,6 +59,14 @@ CARLA (Semantic LiDAR)
--- ---
### Bug #5: Semantic Tag Mismatch (CARLA 0.9.16)
**File:** `scripts/ISOLATE/e2e_agent_sem_lidar2shenron_package/lidar.py`
**Root Cause:** The semantic lookup table was using legacy CARLA 0.9.5 tags. In CARLA 0.9.16, NPC vehicles moved to **Tag 14**, and Terrain moved to **Tag 10**.
**Effect:** All NPC cars were being deleted from the point cloud (filtered out as "unknown"), while the ground terrain was being incorrectly simulated as a high-RCS "Metal" object, creating massive false alarms.
**Fix:** Updated the `map_carla_semantic_lidar_latest` mapping to align with modern 0.9.16 standards.
---
## 📡 Hardware Profile: AWRL1432 (Iteration 07 — Current Best) ## 📡 Hardware Profile: AWRL1432 (Iteration 07 — Current Best)
The `awrl1432` profile in `ConfigureRadar.py` has been tuned to match the real-world **TI AWRL1432BOOST** professional ADAS configuration: The `awrl1432` profile in `ConfigureRadar.py` has been tuned to match the real-world **TI AWRL1432BOOST** professional ADAS configuration:
@ -76,11 +83,48 @@ The `awrl1432` profile in `ConfigureRadar.py` has been tuned to match the real-w
**Signal Processor Config** (`sim_radar_utils/config.yaml`): **Signal Processor Config** (`sim_radar_utils/config.yaml`):
- `fStrt: 77.0e9`, `fStop: 77.4e9` (matching 400MHz bandwidth) - `fStrt: 77.0e9`, `fStop: 77.4e9` (matching 400MHz bandwidth)
- `Np: 64` (matching hardware chirp count)
- `NFFT: 256` (matching N_sample) - `NFFT: 256` (matching N_sample)
--- ---
## 🚀 The Iterative Journey (Milestone History)
This log tracks the surgical evolution of the C-Shenron pipeline, from a broken legacy port to a high-fidelity ADAS testbench.
| Iteration | Challenge | Core Change | Key Result |
| :--- | :--- | :--- | :--- |
| **01** | **System Crash** | Native Port from Transfuser++ | Pipeline initialized but outputs only "black" or random point clouds. |
| **02** | **"Sparkle" Noise** | Restored Thermal Noise Floor | **Bug #2 Fixed:** CFAR detector stabilized; random ghost points removed. |
| **03** | **Low RCS Fidelity** | Fixed "Cos(Cos)" Reflection Math | **Bug #1 Fixed:** Proper Fresnel gain restored (46% energy recovery). |
| **04** | **Static Velocity** | Resolved Metadata Bit-View | **Bug #3 Fixed:** Dynamic velocities (V_radial) finally visible on NPCs. |
| **05** | **Range Stretching** | Synchronized Processor Axes | **Bug #4 Fixed:** Objects at 50m finally appear at 50m (Corrected 77GHz scaling). |
| **06** | **Latency** | Reduced Chirps (Np = 32) | Achieved ~2 FPS simulation speed for rapid prototyping. |
| **07** | **Resolution Loss** | Balanced Chirps (Np = 64) | **AWRL1432 Baseline:** 37.5cm range res with stable SNR. |
| **08** | **Incomplete Tags** | Initial 0.9.16 Tag Exploration | Identified critical mismatch in CARLA 0.9.16 semantic lookup bits. |
| **09** | **Target Vanishing** | Corrected 0.9.16 Mapping | **Bug #5 Fixed:** Target vehicles (Tag 14) are now fully detectable. |
| **10** | **Turning Drop-off** | Metal Roughness (0.0001 $\to$ 0.02) | Vehicles act as "targets" not mirrors. Stable tracks during sharp turns. |
| **11** | **Parallax Shift** | LiDAR Forward Shift (-2.0m) | Radar points spatially locked to bumper. **Lag eliminated.** |
| **11.b**| **"Bumper Clutter"**| Blackman-Harris Windowing | -92dB rejection kills ghost trails bleeding from high-SNR targets. |
| **12** | **Ground Clutter** | Aggressive Z-Filter (Z > -1.5m) | Flat road reflections removed. Identified "Lower-Half Blindness." |
| **13** | **Golden Mix** | Optimized Z-Filter (Z > -2.2m) | **30cm Clearance:** Maintains car tires while stopping road clutter. |
---
## 🚀 Physical Calibration History (Session 04-06)
Following the baseline stabilization on April 3rd, the focus shifted to high-fidelity physical realism and sensor synchronization.
| Iteration | Challenge | Core Physics Change | Critical Result |
| :--- | :--- | :--- | :--- |
| **09** | **Target Vanishing** | Corrected 0.9.16 Mapping | NPC Cars (Tag 14) now appear; Road Terrain noise suppressed. |
| **10** | **Specular Deflection**| Metal Roughness (0.0001 $\to$ 0.02) | Vehicles act as "targets" not "mirrors." Visible during sharp turns. |
| **11** | **Parallax Error** | LiDAR-to-Radar Shift (-2.0m) | **ZERO-LAG:** Radar points spatially locked to the front bumper. |
| **11.b**| **Sidelobe Leakage** | Blackman-Harris Windowing | -92dB rejection kills "ghost trails" pointing back at the ego. |
| **12** | **Ground Clutter** | Aggressive Z-Filter (Z > -1.5m) | Total removal of road noise. Blinds lower half of vehicles. |
| **13** | **Golden Mix** | Optimized Z-Filter (Z > -2.2m) | **30cm Clearance:** Maintains car tires/bottom-lip while stopping ground clutter. |
---
## 📦 Data Pipeline Fixes ## 📦 Data Pipeline Fixes
### Sensor Mount Calibration (MCAP Visualization) ### Sensor Mount Calibration (MCAP Visualization)
@ -156,6 +200,7 @@ python scripts/test_shenron.py --iter "07_high_def_sync"
1. **Turn Lag:** Shenron points appear to trail ~0.5-1 frame behind the CARLA native radar during sharp turns. Suspected cause: LiDAR data captured at `T-1` but rendered with ego pose at `T`. Requires timestamp sync investigation in `recorder.py`. 1. **Turn Lag:** Shenron points appear to trail ~0.5-1 frame behind the CARLA native radar during sharp turns. Suspected cause: LiDAR data captured at `T-1` but rendered with ego pose at `T`. Requires timestamp sync investigation in `recorder.py`.
2. **Angular FOV Validation:** Compare Shenron angular output vs. AWRL1432BOOST hardware spec (`+/- 60°`) to ensure angular clipping is not removing valid detections. 2. **Angular FOV Validation:** Compare Shenron angular output vs. AWRL1432BOOST hardware spec (`+/- 60°`) to ensure angular clipping is not removing valid detections.
3. **CFAR Threshold Tuning:** The `threshold: 20` in `config.yaml` may need adjustment after the noise floor restoration. Consider running a "Clear Road" baseline to calibrate the false alarm rate. 3. **CFAR Threshold Tuning:** The `threshold: 20` in `config.yaml` may need adjustment after the noise floor restoration. Consider running a "Clear Road" baseline to calibrate the false alarm rate.
4. **3D Energy Compression (Tree Density):** Current logic flatten 10m of vertical tree volume into a single 2D bin, making trees look 10x "louder" than cars. **Proposed Fix:** Implement a Gaussian Vertical Beam Pattern in `Sceneset.py` to dampen high-elevation points.
--- ---
@ -173,8 +218,8 @@ python scripts/test_shenron.py --iter "07_high_def_sync"
| `scripts/test_shenron.py` | Testbench — generates and packages iterations | | `scripts/test_shenron.py` | Testbench — generates and packages iterations |
| `scripts/data_to_mcap.py` | Main MCAP converter (Dashboard path) | | `scripts/data_to_mcap.py` | Main MCAP converter (Dashboard path) |
| `src/recorder.py` | Data capture — includes velocity + semantic metadata | | `src/recorder.py` | Data capture — includes velocity + semantic metadata |
| `intel/shenron_architecture_deepdive.html` | Visual HTML architecture guide |
| `intel/radar/shenron_architecture_deepdive.html` | Visual HTML architecture guide |
--- ---
*Generated by Antigravity AI | Fox CARLA ADAS Pipeline | 2026-04-03*
*Generated by Antigravity AI | Fox CARLA ADAS Pipeline | 2026-04-06 (Calibration Milestone)*
Loading…
Cancel
Save