# Shenron Physics-Based Radar: Debug & Troubleshooting Plan (Updated 2026-04-07)

This document tracks the resolution of data-fidelity issues in the C-SHENRON radar integration.

## ✅ 1. Resolved Blockers (Milestones)

### ⚡ A. The "Zero Velocity" Bug (Resolved)
- **Status:** Fixed in Iteration 04.
- **Solution:** Unpacked `float32` bitfields using `np.view(np.uint32)` in `src/recorder.py`. Radial velocity is now correctly projected onto the LiDAR frame before synthesis.

### 📐 B. Semantic LiDAR Column Mismatch (Resolved)
- **Status:** Fixed in Iteration 09.
- **Solution:** Updated `lidar.py` to support the 7-column CARLA 0.9.16 format. Corrected the `map_carla_semantic_lidar_latest` table for NPC vehicles (Tag 14).

### 🔄 C. Coordinate Transformation Logic (Locked)
- **Status:** Verified and Locked. 
- **Mapping:** `Side = Index 0`, `Forward = Index 1`. This convention is required for the `Sceneset` occlusion logic and must not be changed.

### 🔭 D. 3D Vertical Clumping (Resolved)
- **Status:** Fixed in Iteration 14a & 16.
- **Solution:** Implemented **Gaussian Elevation Damping** at the physics layer. Tree-top clutter is now attenuated by >90%.

---

## 🛠️ 2. Current Debugging Checklist (The Metrology Phase)

### Phase 4: Resolution Independence (Iteration 16)
- [x] **Solve the "Resolution Trap"**: Replaced dynamic $1/N$ with a fixed `DENSITY_REF`.
- [x] **Verify Context Independence**: Confirmed that buildings no longer "dim" cars (Frame 100 vs 207).
- [x] **Target Power Recovery**: Achieved **+234% SNR boost** for lead vehicles.

### Phase 5: Multi-Sensor Synchronization
- [ ] **Turn Lag Investigation**: Investigate why Shenron points trail ~0.5 frames behind native radar during sharp maneuvers. 
- [ ] **Timestamp Alignment**: Ensure ego-pose `T` matches the LiDAR capture `T` in `recorder.py`.

### Phase 6: DSP Calibration
- [ ] **CFAR Thresholding**: Re-run the False Alarm Rate (FAR) test. With the +234% signal boost, the default `threshold: 20` in `config.yaml` can be tightened to reduce noise.

---

## 🛰️ 3. Relevant Documentation
- [3D Vertical Energy Suppression](file:///d:/CARLA/CARLA_0.9.16/PythonAPI/Fox/intel/radar/3D%20vertical%20energy%20suppression.md)
- [Main Debug Log (Shenron_debug.md)](file:///d:/CARLA/CARLA_0.9.16/PythonAPI/Fox/intel/radar/Shenron_debug.md)
- [Deep Metrology Report (Iteration 17)](file:///C:/Users/rakadu1/.gemini/antigravity/brain/67913a3c-cbc2-4fba-87e3-88fbea20f043/metrology_report.md)

---
*Last Updated: 2026-04-07 | Status: Target Signal Stable*