# RARDCFAR_guide.md

## C-Shenron Radar Metrology Debugging & Correction Guide

---

# 1. System Architecture (Your Implementation)

## Signal Chain

```text
LiDAR → Physics Engine → Raw ADC → Range FFT → Doppler FFT → Angle FFT → CFAR → Point Cloud
```

---

## Your Actual Implementation (Code Verified)

### Range FFT

```python
fft(data * rangeWin * velWin, axis=0)
```

### Doppler FFT

```python
fftshift(fft(rangeProfile, axis=1), axis=1)
```

### RD Heatmap

```python
avgDopplerProfile = np.mean(dopplerProfile, axis=2)
rd_heatmap = |avgDopplerProfile|^2
```

### RA Heatmap

```python
ra_heatmap_raw = np.mean(dopplerProfile, axis=1)
ra_heatmap = |FFT(ra_heatmap_raw)|^2
```

---

# 2. Current Observations (From Your Output)

## ✅ Correct

* Range axis correct
* RD vertical column at V=0
* CFAR pipeline working
* FFT chain structurally valid

---

## ❌ Issues

| Component | Issue                                      |
| --------- | ------------------------------------------ |
| RD        | No Doppler spread                          |
| RA        | Horizontal banding + no angular separation |
| CFAR      | Over-detecting static clutter              |
| RA        | Phase cancellation artifacts               |

---

# 3. ROOT CAUSE ANALYSIS (CODE LEVEL)

---

# ❌ ISSUE 1 — RA Banding (CRITICAL)

## Problem Line:

```python
ra_heatmap_raw = np.mean(dopplerProfile, axis=1)
```

---

## Why This is WRONG

You are doing:

> **Coherent integration across Doppler (complex mean)**

This causes:

### 🔴 Phase cancellation

For moving targets:

[
\sum e^{j\phi_k} ≈ 0
]

→ Signal disappears

---

## Result:

* Horizontal banding
* Missing targets
* Weak angular structure

---

## ✅ FIX (MANDATORY)

Replace with:

```python
ra_heatmap_raw = np.sum(np.abs(dopplerProfile), axis=1)
```

---

## Why This Works

* Preserves energy
* Removes phase sensitivity
* Matches real radar power integration

---

# ❌ ISSUE 2 — Missing Window on Angle FFT

## Current:

```python
fft(pointSel, axis=1)
```

---

## Problem:

* No spatial window → sidelobes
* Poor angular resolution
* Leakage → smearing

---

## ✅ FIX

Apply Hann window:

```python
window = np.hanning(N_antennas)
pointSel_windowed = pointSel * window
```

---

Then:

```python
fft(pointSel_windowed, axis=1)
```

---

# ❌ ISSUE 3 — Doppler Collapse

## Problem Location:

```python
avgDopplerProfile = np.mean(dopplerProfile, axis=2)
```

---

## Why This is WRONG

* Averaging complex signals across antennas
* Phase misalignment → cancellation

---

## Result:

* Everything collapses to V=0
* No velocity separation

---

## ✅ FIX

Use power summation:

```python
rd_heatmap = np.sum(np.abs(dopplerProfile)**2, axis=2)
```

---

## Why:

* Preserves Doppler energy
* Matches real radar processing

---

# ❌ ISSUE 4 — CFAR Too Permissive

## Config:

```yaml
threshold: 20
win_param: [9, 9, 3, 3]
```

---

## Problem:

* Large window → over-smoothing
* Static clutter dominates noise estimate

---

## Symptoms:

* Entire vertical column detected
* Poor selectivity

---

## ✅ FIX

### Adjust:

```yaml
win_param: [6, 6, 2, 2]
threshold: 25–35
```

---

## Optional Upgrade:

Switch to:

* OS-CFAR (better robustness)
* Or adaptive threshold per range band

---

# ❌ ISSUE 5 — Velocity Axis Compression

## Code:

```python
velAxis = ...
```

---

## Problem:

* Likely too wide range
* Real velocities compressed near zero

---

## ✅ FIX

Limit:

```python
vel_min = -20 m/s
vel_max = +20 m/s
```

---

# ❌ ISSUE 6 — RA Formation Order

## Current Flow:

```text
Doppler → mean → angle FFT
```

---

## Correct Flow:

```text
Doppler → magnitude → sum → angle FFT
```

---

# 4. CORRECTED PIPELINE

---

## RD Generation

```python
rd_heatmap = np.sum(np.abs(dopplerProfile)**2, axis=2)
```

---

## RA Generation

```python
ra_heatmap_raw = np.sum(np.abs(dopplerProfile), axis=1)

window = np.hanning(N_ant)
ra_heatmap_raw *= window

ra_heatmap = np.abs(fftshift(fft(ra_heatmap_raw, axis=1)))**2
```

---

## Angle Estimation

```python
aoaProfile = fft(pointSel * window, axis=1)
```

---

# 5. VALIDATION CHECKLIST

---

## RD

* [ ] Static → vertical line
* [ ] Moving → offset blobs
* [ ] No collapse to center

---

## RA

* [ ] Left/right separation
* [ ] Matches LiDAR geometry
* [ ] No horizontal banding

---

## CFAR

* [ ] Sparse detections
* [ ] Peaks only
* [ ] No full-column activation

---

# 6. KEY INSIGHT (IMPORTANT)

---

## Your Current System

> FFT pipeline is correct
> BUT **integration strategy is wrong**

---

## Core Problem

You are doing:

> **Coherent integration where incoherent is required**

---

## Radar Rule

| Stage | Integration Type |
| ----- | ---------------- |
| FFT   | Coherent         |
| Power | Incoherent       |

---

# 7. Shenron vs Your System

| Component   | Shenron      | Your Current       |
| ----------- | ------------ | ------------------ |
| Integration | Incoherent   | ❌ Coherent         |
| RA          | Energy field | ❌ Phase-sensitive  |
| RD          | Power-based  | ⚠️ Mixed           |
| CFAR        | Tuned        | ⚠️ Over-permissive |

---

# 8. Expected Outcome After Fix

---

## RD

* Clear moving targets
* Velocity separation visible

---

## RA

* Clean blobs
* Angular localization restored

---

## CFAR

* Sparse detections
* True target extraction

---

# 9. Next Steps

---

## Immediate

1. Fix RD power calculation
2. Fix RA incoherent integration
3. Add Hann window

---

## Then

4. Tune CFAR
5. Validate against LiDAR

---

## Optional (Advanced)

* Add antenna array geometry
* Add beam pattern
* Add noise model

---

# 10. Offer

If you want:

👉 I can rewrite your `RadarProcessor` into a **correct, production-grade version**
👉 Or debug further edge cases (multipath, clutter, velocity aliasing)

---

# FINAL TAKEAWAY

> Your system is **architecturally correct**
> But **one fundamental mistake (coherent averaging)** is breaking RA and RD fidelity.

Fix that → your system will jump to near **Shenron-quality radar output**.

---

**End of Document**