feat(shenron): Fix CARLA 0.9.16 semantic alignment and restore test-suite

This includes the [NEW] intel/possible_issue_resolution.md file

intel/possible_issue_resolution.md

@@ -0,0 +1,56 @@
+# Shenron Radar Physics: Issue Analysis & Resolution Plan
+
+This document details the root causes behind the three radar anomalies observed during Iteration 08, leveraging the radar physics models and signal processing math in the pipeline.
+
+---
+
+## Issue 1: High False Velocities (>25 m/s) on Static Buildings
+
+**Observation:** Static buildings exhibit radial velocities $> 25\text{ m/s}$ (moving away) when the ego vehicle turns or drives fast, particularly on far-off structures.
+
+**Physics Root Cause: Doppler Aliasing (Nyquist Wrap-Around)**
+FMCW radars measure radial velocity by measuring the phase shift between consecutive chirps. There is a fundamental physics hardware limit called the **Maximum Unambiguous Velocity ($V_{max}$)**. 
+
+If an object approaches faster than $V_{max}$, the phase shift exceeds $180^\circ$ and "wraps around," making a fast-approaching object look like it's fast-receding (aliasing).
+
+*   **The Math:** $V_{max} = \frac{\lambda}{4 \cdot T_{rep}}$
+*   **AWRL1432 Profile:** Frequency = 77 GHz ($\lambda \approx 3.89\text{ mm}$), Chirp Repetition ($T_{rep}$) = $36.4\mu s$.
+*   $V_{max} = \frac{3.89\text{ mm}}{4 \times 36.4\mu s} \approx \mathbf{26.75\text{ m/s}}$ (approx. 96 km/h).
+
+**Why it happens during turns/driving:** If your Ego vehicle is driving straight at 100 km/h (27.7 m/s), a static building dead ahead is approaching you at -27.7 m/s. Because this exceeds the -26.75 m/s limit of the AWRL1432 profile, the FFT wraps it around to the positive side of the spectrum, outputting roughly **+25.8 m/s** (moving away). 
+*   **Resolution Plan:** This perfectly matches real-world 77GHz hardware limitations! To fix it, we must either increase the pulse repetition frequency (lower `chirp_rep` in `ConfigureRadar.py`), or implement a multi-Doppler ambiguity resolution algorithm in the processor.
+
+---
+
+## Issue 2: NPC Vehicle "Disappearing" During Turns
+
+**Observation:** The NPC vehicle vanished from the `awrl1432` radar when making a turn or presenting non-flat angles, but a background tree remained visible. The older `radarbook` radar did not lose the NPC.
+
+**Physics Root Cause: Specular Deflection vs. Diffuse Wavelength Penalty**
+In `lidar.py`, we assigned cars the "Metal" material type, which has an extremely low roughness score (`0.0001`). This makes vehicles act like **perfect mirrors**.
+
+1. **Straight Lines:** When the NPC is driving straight ahead, its rear bumper is perfectly perpendicular to your radar. The radar beam bounces directly back (Specular Reflection), creating a massive "flash" of energy.
+2. **Turning:** When the NPC turns, its body angle changes. Like pointing a flashlight at a mirror tilted 45 degrees, the radar beam bounces off the car and scatters into the simulated sky or road. 
+3. **Why did `radarbook` see it, but `awrl1432` failed?** 
+   When specular reflection fails, radar relies on "Diffuse Scattering" (rough edges like tires and door handles that scatter energy everywhere). The Radar Equation states that return power scales with the **square of the wavelength ($\lambda^2$)**.
+   *   `radarbook` (24 GHz) $\lambda = 12.5\text{ mm}$
+   *   `awrl1432` (77 GHz) $\lambda = 3.89\text{ mm}$
+   *   $(12.5 / 3.89)^2 \approx \mathbf{10.3\times}$ **More Power.**
+   Because 77GHz wavelengths are so small, diffuse scattering is incredibly weak. The diffuse return of the turning car fell below the CFAR threshold for the `awrl1432`, but stayed above the threshold for the `radarbook`.
+*   **Resolution Plan:** We need to increase the `roughness` coefficient for the "Metal" material in `lidar.py`. Real cars are shiny, but their complex geometry (grilles, mirrors, rims) scatters a lot of energy. A slightly higher roughness will ensure they return energy continuously, even at high deflection angles.
+
+---
+
+## Issue 3: "Ghost Points" Following the NPC Direction
+
+**Observation:** Ghost points appear very close to the ego vehicle. They do not move relative to the ego, but they continuously point in the exact same azimuthal direction as the bright NPC vehicle.
+
+**Signal Processing Root Cause: Range Spectral Leakage (FFT Sidelobes)**
+This is not a reflection from the road—this is a math artifact of the Fast Fourier Transform (FFT) inside the Signal Processor.
+
+1. When the NPC vehicle is straight ahead, the specular "flash" is so incredibly loud (SNR > 60-80 dB) that its signal overwhelms the FFT.
+2. An FFT assumes infinite periodic signals. When we window a finite ADC sample (256 samples), a perfect peak "leaks" energy into adjacent bins. These are called **Sidelobes**.
+3. If the NPC is at 30 meters, its sidelobes will spread down into the 5m, 10m, and 15m range bins. Because these ghost peaks are literally pieces of the NPC's signal, they mathematically have the exact same Angle-of-Arrival (AoA), causing them to "point" at the NPC.
+*   **Resolution Plan:** 
+    1. **Short-Range Blanking:** All real-world ADAS radars mute the first 2-3 meters of data to ignore DC leakage, bumper reflections, and extreme sidelobes. We can implement a hard cutoff in `radar_processor.py` (e.g., `range > 2.0m`).
+    2. **Stronger Windowing:** The processor currently uses a `Hann` window. Changing it to a `Blackman-Harris` window will suppress sidelobes by -92dB, completely eliminating these ghost points at the cost of slightly thicker range bins.

intel/shenron_architecture_deepdive.html

@@ -57,6 +57,7 @@
             font-weight: 800;
             background: linear-gradient(90deg, var(--accent), #aff5b4);
             -webkit-background-clip: text;
+            background-clip: text;
             -webkit-text-fill-color: transparent;
             margin-bottom: 10px;
         }

scripts/ISOLATE/e2e_agent_sem_lidar2shenron_package/lidar.py

@@ -29,21 +29,26 @@ def map_carla_semantic_lidar_latest(carla_sem_lidar_data):
     tags = carla_sem_lidar_data[:, tag_col_idx].astype(np.float32).view(np.uint32)
     
     # CARLA 0.9.16 -> Legacy team_code mapping (used by new_map_material)
-    # 0.9.16: 0:none, 1:building, 2:fence, 4:pedestrian, 10:vehicle, 11:wall, 12:traffic_sign, 13:sky, 14:ground, 15:bridge, 16:rail, 17:guardrail, 18:traffic_light, 19:static, 20:dynamic, 21:water, 22:terrain
-    # Legacy: 13:car, 11:pedestrian, 4:fence, 5:pole, 7:traffic_sign, 2:building, 3:wall, 1:sidewalk, 8:vegetation
+    # 0.9.16: 0:none, 1:roads, 2:sidewalk, 3:building, 4:wall, 5:fence, 6:pole, 7:traffic_light, 8:traffic_sign, 9:vegetation, 10:terrain, 11:sky, 12:pedestrian, 13:rider, 14:car, 15:truck, 16:bicycle, 17:motorcycle
     
-    # We create a 256-long lookup table for all possible tags
     mapping = np.zeros(256, dtype=int)
-    mapping[1] = 2   # Building
-    mapping[2] = 4   # Fence
-    mapping[4] = 11  # Pedestrian
-    mapping[5] = 5   # Pole
-    mapping[8] = 1   # Sidewalk
-    mapping[9] = 8   # Vegetation
-    mapping[10] = 13 # Vehicle
-    mapping[11] = 3  # Wall
-    mapping[12] = 7  # Traffic Sign
-    mapping[18] = 6  # Traffic Light
+    mapping[1] = 1   # Road -> Sidewalk/Concrete
+    mapping[2] = 1   # Sidewalk -> Concrete
+    mapping[3] = 2   # Building -> Concrete
+    mapping[4] = 3   # Wall -> Concrete
+    mapping[5] = 4   # Fence -> Metal
+    mapping[6] = 5   # Pole -> Metal
+    mapping[7] = 6   # Traffic Light -> Metal
+    mapping[8] = 7   # Traffic Sign -> Metal
+    mapping[9] = 8   # Vegetation -> Wood
+    mapping[10] = 9  # Terrain -> Earth
+    mapping[12] = 11 # Pedestrian -> Human
+    mapping[13] = 12 # Rider -> Human
+    mapping[14] = 13 # Car -> Metal
+    mapping[15] = 14 # Truck -> Metal
+    mapping[16] = 18 # Bicycle -> Metal
+    mapping[17] = 17 # Motorcycle -> Metal
+    mapping[22] = 9  # Terrain (Alternative) -> Earth
     
     legacy_tags = mapping[tags % 256] # bitwise safety
     

scripts/test_shenron.py

@@ -81,7 +81,7 @@ def run_testbench(iter_name):
         return
         
     iter_dir.mkdir(parents=True, exist_ok=True)
-    radar_types = ['awrl1432']
+    radar_types = ['awrl1432', 'radarbook', 'ti_cascade']
     
     print(f"\n======================================")
     print(f"SHENRON TESTBENCH ITERATION: {iter_name}")