CARLA ? C-Shenron based Simualtor for Sensor data generation.

14 KiB

Raw Blame History

📜 Fox Project Chronicles: The Technical Saga

This document is the definitive record of the Fox CARLA ADAS Simulation project. It bridges high-level git history with the deep technical engineering decisions that shaped the repository. Use this as a guide to understand not just what changed, but why.

🏛️ 1. Project Manifesto: The Vision

The Fox project was born from a need for deterministic, high-fidelity ADAS validation. While standard CARLA simulations provide a starting point, they often lack the physical realism required for modern radar sensor fusion.

Our Core Pillars:

Physical Integrity: Radar data must follow the laws of physics ($1/R^4$), not just look "busy."
Deterministic Repeatability: A scenario must execute with millisecond precision every time.
Observability: Developers must have "Radar Lab" visibility into the signal processing chain.

🛰️ 2. The Shenron Iteration Log (The Long Road to Fidelity)

The "Shenron" radar engine evolved through 26 critical iterations. This table tracks its journey from a broken port to a physically consistent testbench.

Iteration	Focus	The "Why" (Decision & Rationale)	Technical Result
01-02	Stability	Initial ports from legacy code were unstable. We restored the AWGN Thermal Noise Floor because the CFAR detector needs a non-zero background variance to avoid infinite false positives.	STABLE BASELINE
03	RCS Recovery	Surfaced a critical math error in reflection logic. By removing a redundant cosine, we recovered 46% of lost signal energy, preventing vehicles from "vanishing" at slight angles.	+46% SNR
04-05	Vel. & Scale	Dynamic targets showed 0 m/s because bitfields were mismatched. We introduced `np.view(np.uint32)` for correct metadata unpacking. Fixed scaled axes to prevent "Range Stretching."	CORRECT GEOMETRY
07-09	Tag Alignment	Aligned with CARLA 0.9.16 standards. Decision: We prioritized vehicle detection (Tag 14) over generic clutter filtering to ensure ADAS targets were always visible.	0.9.16 SYNC
11-13	Z-Filtering	Decision: Implemented a floor-clipping mask (Z > -2.2m). This "Golden Mix" preserves vehicle tires/lips while completely eliminating road-surface multipath ghosts.	CLEAN METRICS
16	Target Boost	Replaced dynamic $1/N$ with a fixed `DENSITY_REF`. Rationale: Preventing distant buildings from "dimming" near targets. This preserved context-independent target power.	+234% SNR BOOST
18	Phase Lock	Switched from average Doppler to Doppler-Slice Angle FFT. Decision: Preserving complex phase is the only way to achieve sharp angular resolution and prevent "blobbing."	SHARP AZIMUTH
20-22	Symmetry	Resolved a 15° boresight tilt. Rationale: Standard FFT indexing was asymmetric; we shifted to perfect index linear spaces to ensure the 120° FOV fan was centered.	ZERO-TILT SYMMETRY
26	Milestone R4	THE BREAKTHROUGH: Replaced all artificial normalization with the $1/R^4$ Radar Range Equation. Decision: Physical correctness is the only way to build trust in ADAS validation.	PURE PHYSICS
30	Identity Fix	Proved the Isotropic Illumination root cause through LiDAR FOV clipping diagnostics.	ROOT CAUSE ID
31	Deep De-Hack	Decision: Stripped 277x legacy multipliers and tightened specular cones to 2.0°. Restoration of total physical honesty before antenna pattern fix.	PHYSICAL HONESTY

🪦 3. The Bug Graveyard: Lessons from the Abyss

These four bugs represented the most significant blockers in the project's history. Here is how they were tackled.

🐛 Bug #1: The "Cos(Cos)" Reflection Error (`Sceneset.py`)

Situation: Surfaces (especially car hoods) were appearing significantly darker than expected, regardless of material.
Investigation: Discovered that the specularpoints() method was receiving a pre-calculated cosine from the LiDAR engine, but then applying np.cos() to it again.
The "Why": A 0-degree incident angle (cos = 1.0) was being computed as cos(1.0) = 0.54.
Decision: Removed the second cosine call. This was a legacy artifact from a different coordinate system port.
Result: Immediate 46% magnitude recovery and stable tracking during turns.

🐛 Bug #2: Metadata Bit-View Packing (`src/recorder.py`)

Situation: Radar synthesis was working, but all actors showed exactly 0.0 radial velocity.
Investigation: CARLA 0.9.16 stores Actor IDs and Semantic Tags as uint32 values, but they are "packed" into a float32 bitstream to maintain a uniform array. Standard indexing read them as floats, resulting in garbage.
Decision: Use np.view(np.uint32) to reinterpret the bits without value conversion.
Result: Restored full dynamic context to the simulation, enabling velocity-aware ADAS testing.

🐛 Bug #3: The Stale Physics Race Condition (`scenarios/base.py`)

Situation: NPCs were frequently spawning at the center of the map instead of in front of the Ego vehicle.
Investigation: In Synchronous Mode, the simulator needs at least one world.tick() to settle physics. Accessing get_location() of a newly spawned Ego vehicle returned 0,0,0 because the frame hadn't processed yet.
Decision: Forced an explicit Settling Tick in the orchestrator before any scenario logic computes coordinates.
Result: 100% spawning reliability.

🐛 Bug #4: Early Dimensional Collapse (`radar_processor.py`)

Situation: Range-Azimuth plots showed targets as wide, blurry smears rather than sharp points.
Investigation: The signal processing chain was collapsing the Doppler dimension (summing magnitudes) before performing the Angle-FFT. This discarded the relative phase differences between chirps.
Decision: Re-architected the pipeline to perform Angle-FFT on individual Doppler slices, preserving coherence.
Result: Angular resolution improved by ~300%, matching hardware-spec performance.

🏔️ 4. Major Architectural Milestones

⚓ The 1/R⁴ Physical Baseline

Prior to Week 3, we used artificial scaling to keep the signal "visible." The Shift: We realized that ADAS algorithms depend on the physical contrast between a car and a building. We implemented the $1/R^4$ law:

Calculation: $P_{rec} = \frac{P_{tx} \cdot G^2 \cdot \lambda^2 \cdot \sigma}{(4\pi)^3 \cdot R^4}$
Outcome: The simulation now correctly models how energy drops over distance, allowing for realistic sensitivity-threshold testing.

🖥️ GPU Resource Control (Idle Mode)

The Shenron engine is heavy. Running it alongside a 30 FPS CARLA simulation causes thermal throttling. The Fix: We implemented "Idle Mode."

Decision: When the dashboard is not actively running a scenario or is processing a recorded dataset, we cap CARLA's fixed_delta_seconds to a crawl (near zero GPU usage).
Outcome: Frees 95% of VRAM and CUDA cores for the high-fidelity Shenron signal synthesis.

🛰️ The Metrology Breakthrough: Heatmap Synthesis

Prior to Week 3, the radar output was a "Black Box." The Sprint: We spent two days re-engineering the signal chain in heatmap_gen_fast.py and radar_processor.py.

The Problem: We were using Coherent Integration (complex averaging) across Doppler bins, which caused massive phase cancellation and "Horizontal Banding." Target vehicles were vanishing during maneuvers.
The Solution: Implemented Doppler-Slice Synthesis. We now perform Angle-FFT on each Doppler bin independently to preserve phase, followed by Incoherent Power Summation.
Result: Transitioned from spatially blurred energy fields to sharp, physically consistent RA/RD heatmaps. This unlocked the ability to see "Radar Blue" Jet-spectrum blobs that spatially align with LiDAR ground truth.

🔦 The Isotropic Illumination Breakthrough

After 30 iterations of parameter tuning, we identified the fundamental reason for vehicle detection failure at range.

The Problem: The physics engine was treating the radar as an Isotropic Point Source (equal power in all 360 degrees). Large side surfaces (road barriers, tunnel walls) at 80° were generating returns just as loud as the car at 0°, effectively "shadowing" the vehicle.
The Discovery: Diagnostic tracking using track_full_state.py proved that the peak detection angle was consistently locked to side-walls. Once we manually clipped the LiDAR FOV to ±30°, the car became the dominant detection immediately.
The "De-Hacking" Resolution: We stripped away weeks of compensatory "boosts" (gain hacks, widened reflection cones) to return to a physically honest baseline before the antenna pattern fix.

📜 5. Project Evolution (Weekly Context)

📅 Week 1: Genesis & Foundation (March 27 – March 29, 2026)

Objective: Establish the core ADAS framework and deterministic simulation logic.
Key Results:
- Initialization of the modular ScenarioBase architecture.
- Implementation of the ThreadPoolExecutor for asynchronous data capture.
- Deployment of the Showcase Suite (Deterministic coordinate control).

📅 Week 2: Dashboard & The Shenron Awakening (March 30 – April 5, 2026)

Objective: Orchestration and high-fidelity sensor integration.
Key Results:
- Deployment of the Flask Dashboard GUI.
- Surgical isolation of the Shenron Radar Simulator (ISOLATE).
- Milestone fixes for zero-velocity tracking and RCS magnitude.

📅 Week 3: Physics & Optimization (April 6 – April 12, 2026)

Objective: Physical consistency and resource control.
Key Results:
- Milestone R4: $1/R^4$ Power Law implementation.
- Symmetry Lock: Zero-tilt boresight calibration.
- Idle Mode: Synchronous GPU throttling for multi-process efficiency.

📜 6. Detailed Daily Chronology (Git Absolute)

April 15 (Today)

Task: Modular Architecture & Calibration Refinement.
Action: Transitioned Shenron to a fully modular "Knobs and Dials" architecture.
Modularity: Isolated radar hardware profiles (AWRL1432, TI-Cascade, Radarbook) in ConfigureRadar.py.
Calibration: Finalized the Antenna Gain LUT Integration (Separable Az/El patterns) in Sceneset.py.
Organization: Reorganized the intel/radar directory into structured subfolders (core, research, diagnostics, archive) to maintain documentation scalability.
Physics: Validated the pure physical $1/R^4$ power law and removed all legacy scaling multipliers.
Dashboard: Implemented a Smart Auto-Idle Toggle with clear visual feedback (Success-Green background and 'AUTO' text overlay). Redefined toggle logic to serve as a master switch that immediately pauses CARLA when enabled and disables the auto-timer when disabled.
UX Optimization: Resolved a critical 10s UI hang during simulator shutdown by reducing the backend status ping timeout from 10.0s to 5.0s and implementing immediate frontend feedback for the 'Kill' action.

April 14

Task: Physics "De-Hacking" & Root Cause Analysis.
Action: Identified the Isotropic Illumination Problem as the primary blocker for ADAS tracking.
Physics: Stripped legacy scaling multipliers (~277x) and tightened reflection cones (5.0° -> 2.0°) from Sceneset.py to restore physical realism.
Hardware Calibration: Locked AWRL1432 profile to 137.2 MHz bandwidth and 128 chirps.
UI Enhancement: Overhauled the dashboard with an Emerald-themed Telemetry HUD providing real-time SNR and point-density chips.
Metrology: Integrated track_full_state.py, track_peaks.py, and compare_metrology.py into the diagnostic loop.
Tooling: Added --frames support to test_shenron.py for faster diagnostic synthesis.

April 13

Task: Observability & UI Optimization.
Action: Established the CHRONICLES.md (Technical Saga) and memory_update.md (Agent Protocol).
Optimization: Addressed terminal log "flooding" by suppressing /api/simulator/status Werkzeug logs and reducing frontend polling from 1s to 3s.
UI Enhancement: Implemented a collapsible Configuration Parameters card.
Accessibility Fix: Performed a full theme overhaul to improve readability. Boosted panel contrast, increased label font-weight, and transformed the collapse toggle into a prominent, circular blue-accented action button.

April 10

Task: Process Efficiency & Lifecycle.
Action: Implemented Idle Mode (Synchronous Throttling) and graceful shutdown logic.

April 8-9

Task: Physics Baseline & Visualization.
Action: Locked in the 1/R⁴ Power Law and Zero-Tilt Symmetry.
Change: Removed artificial normalizations in radar_processor.py.

April 6-7

Task: Metrology Suite.
Action: Added real-time RD/RA heatmaps. Integrated Gaussian Vertical Damping (Iter 14a).

April 1-3

Task: Integration & Calibration.
Action: Merged C-SHENRON into the main pipeline. Fixed the bit-view packing bug and the cos(cos) error.

March 31

Task: Orchestration.
Action: Modernized the simulation pipeline with centralized scripts and the initial GUI.

March 27 (Initial Commit)

Task: Project Inception.
Action: Initialized the Fox CARLA ADAS repository. Implemented the asynchronous recorder and the first deterministic showcase scenarios.

Generated by Antigravity AI | Fox CARLA ADAS Simulation | 2026-04-15

14 KiB Raw Blame History