# 🚩 Benchmark: 3D Energy Compression & Environmental Clutter (Tree Density)

**Metadata:**
- **Status:** Research & Mitigation Planning (Iteration 14)
- **Domain:** Physics-Based Radar Simulation / ADAS Fidelity
- **Goal:** Resolve signal intensity imbalance between thin targets (Vehicles) and voluminous targets (Trees/Buildings).

---

## 🔍 1. Problem Statement: The "Super-Reflector" Tree

In Iteration 13, we identified a significant intensity discrepancy in the Foxglove 3D panel. While NPC vehicles (primary ADAS targets) produced stable but moderate point clouds, environmental objects like **Trees** and **Distant Buildings** generated extremely dense, high-SNR reflections that overwhelmed the CFAR detector.

### Observed Discrepancies:
- **Visual Clumping:** Trees appeared as solid "walls" of radar points, whereas in real-world 77GHz hardware, trees should appear as sparse, flickering points due to low-RCS foliage.
- **Dynamic Range Mismatch:** The "Magnitude" attribute for a tree (voluminous) was an order of magnitude higher than a sedan (thin metallic surface), violating expected ADAS SNR profiles.

---

## 🧮 2. Root Cause Analysis

The issue is a side-effect of how the Shenron pipeline compresses a 3D LiDAR scene into a 2D Radar heatmap. 

### A. The "Shrinking" Math (`heatmap_gen_fast.py`)
The physics engine iterates through all 100k+ LiDAR points and **sums their complex phases** into the ADC signal cube based strictly on **Range (rho)** and **Azimuth (theta)**.

### B. The Vertical Summation Problem (`Sceneset.py`)
In the current implementation (Line 412):
```python
P_incident = np.power(rho,2) * ... * (1/np.power(rho,tx_dist_loss_exponent)) * K_sq 
```
- **Infinite Vertical Gain:** The radar currently has **no vertical beamwidth** ($G(\phi)$). It "sees" every point from the ground to the sky with equal gain.
- **Energy Integration:** A tree consists of thousands of points spread vertically. When the 3D scene is flattened, the radar treats those 1,000 vertical points as a single, super-powered reflection. 
- **Result:** The 2D energy bin for a tree is the **sum of all its vertical slices**, making it look artificially "loud" compared to a 1.5m tall car.

---

## 🛠️ 3. Proposed Mitigation Strategies

### Phase A: Vertical Antenna Gain (Boresight Weighting)
Implement a **Gaussian Vertical Beam Pattern** in the `P_incident` calculation to model the directive nature of ADAS antenna arrays.
- **Math:** Introduce a damping factor $G_{elev} = \exp\left(-2.77 \cdot \left(\frac{\phi}{\beta}\right)^2\right)$, where $\phi$ is the elevation angle and $\beta$ is the vertical beamwidth.
- **The "2.77" Constant:** This constant ensures that when the elevation ($\phi$) reaches exactly half the beamwidth ($\beta/2$), the power is attenuated by exactly **3dB (50%)**. This aligns the simulation with standard hardware datasheets.
- **Impact:** Points at the top of a tree or skyscraper are "blinded" by the antenna pattern, ensuring their vertical energy isn't integrated into the horizontal detection bin.

### Phase B: Density-Based Normalization (The "Resolution Trap")
**[RESOLVED in Iteration 26]**
Solve the physical inconsistency where increasing LiDAR resolution increases Radar intensity.
- **The Initial Attempt (Iter 14):** Tried dynamic $1/N$ normalization; caused background-dependency.
- **The Second Attempt (Iter 16):** Used fixed `DENSITY_REF = 1000`. Stop-gap measure.
- **The Final Fix (Iter 26):** **Pure Physical R^-4 Alignment.** By removing all artificial normalizations and following free-space physics, the signal levels naturally balance. Large distant buildings are dimmed by distance, and near-field cars remain dominant. 
- **Impact:** Simulation is now 100% true-to-life; "Resolution Trap" eliminated.

---

## 🧭 4. Implementation Steps (Iteration 14)

1. **Hardware Profile Update:** Define `self.vertical_beamwidth` in `ConfigureRadar.py`.
2. **Physics Engine Implementation:** Add the Gaussian vertical damping logic and $1/N$ normalization to `shenron/Sceneset.py`.
3. **DSP Calibration:** Fine-tune the `threshold` and `guard cells` in `sim_radar_utils/config.yaml` to match the new dynamic range.

---

## 📚 Annex: Technical Reference

### Key Files to Reference
| File | Role | Change Required |
| :--- | :--- | :--- |
| **`ConfigureRadar.py`** | Hardware Profiles | Define `vertical_beamwidth` for `awrl1432` and `radarbook`. |
| **`shenron/Sceneset.py`** | Physics Engine | Implement Gaussian $G_{elev}$ and density normalization. |
| **`sim_radar_utils/config.yaml`** | DSP Config | Adjust `threshold` and `guard cells` after vertical energy is balanced. |

### Knowledge Base
- **Calibration History:** [Shenron_debug.md](file:///d:/CARLA/CARLA_0.9.16/PythonAPI/Fox/intel/radar/Shenron_debug.md) (Iterations 01-13).
- **Architecture Guide:** [context.md](file:///d:/CARLA/CARLA_0.9.16/PythonAPI/Fox/intel/internal/context.md) (AI navigation rules).

---

*Generated by Antigravity AI | 2026-04-07 | Knowledge Transfer Benchmark V2.*