# Radar Exhibit — Design Document

## Hardware target
- Geekom A8 Max: AMD Ryzen 9 8945HS, Radeon 780M (Mesa/RADV), 32 GB RAM
- Ubuntu 25.10, g++ 15.2.0, C++20, OpenGL 4.3 Core

---

## Screen layout

Three fixed regions rendered with `glViewport` + `glScissor`:

| Region | Content |
|--------|---------|
| Left panel | Text description, control list (white text; red labels; pink keystrokes) |
| Right panel — upper | Radar scope |
| Right panel — lower | Status bar: range, bearing, scope ID (yellow text) |

---

## Scope sequence (cycled with keys 1 / 2)

1. Exhibit introduction (text only)
2. Chain Home A-Scope (1940s)
3. Marine A-Scope (1940s)
4. PPI — stationary marine traffic control
5. PPI — on-board boat

Each scope's control state is **independent** and **resets on re-entry**.

---

## Radar equation

$$P_r = \frac{P_t G^2 \lambda^2 \sigma}{(4\pi)^3 R^4}$$

Signal strength falls off with $1/R^4$. Each radar type has fixed hardware loop gain baked into its shader set as a constant.

---

## Controls (keyboard until physical panel is built)

| Key | Action |
|-----|--------|
| 1 / 2 | Next / previous scope |
| 3 / 4 | Intensity down / up |
| 5 / 6 | Receiver sensitivity down / up |
| q / w | STC sensitivity down / up |
| e / r | STC range down / up |
| t / y | Radiogoniometer left / right (Chain Home only) |
| u / i | Max range down / up (all except Chain Home) |
| o / p | Range cursor down / up (PPI only) |
| a / s | Bearing cursor CCW / CW (PPI only) |
| d / f | Antenna bearing CCW / CW (Marine A-Scope only) |

Notes:
- Radiogoniometer, marine antenna bearing, and PPI bearing cursor share one physical knob on the eventual panel; kept separate in software.
- Range cursor ≠ max range: max range is the radar's selected range setting; range cursor is the measurement cursor on the PPI display.

---

## Scope specifications

### Chain Home A-Scope
- Fixed range: 200 miles
- No graticule; crystal-oscillator range pips every 20 miles (operator cannot change)
- Bearing via radiogoniometer simulation: operator finds null point; bearing shown as text below scope
- Two perpendicular antenna sets (N-S, E-W); radiogoniometer angle determines which target pip goes to null

### Marine A-Scope
- Ranges: 1.5 / 3.0 / 6.0 / 12.0 miles
- Range pips: every 0.25 / 0.5 / 1.0 / 2.0 miles respectively (fixed oscillator; not affected by range setting)
- No graticule
- Bearing by rotating simulated dish/horn antenna (d/f keys)
- Pip shape: finite rise, fixed-width pulse, finite fall — curved waveform, not a vertical line

### PPI scopes (both)
- 360° sweep with phosphor persistence via FBO (semi-transparent black quad each frame; no full clear)
- Range cursor and bearing cursor overlay

#### Stationary (marine traffic control)
- Fixed observer position; targets move relative to scope center

#### On-boat
- Observer is scope center; heading-up display — world rotates as boat heading changes
- Boat position/heading supplied from GDAL/PostgreSQL data

---

## Architecture

### Class hierarchy (State pattern)

```
BaseScope          — intensity, sensitivity, STC vars, virtual render/update
├── AScope         — horizontal sweep, curved pip waveform
│   ├── ChainHomeScope   — radiogoniometer, fixed 200 mi range, 20 mi pips
│   └── MarineAScope     — antenna bearing knob, 4 range settings
└── PPIScope       — 360° sweep, FBO persistence, range/bearing cursors
    ├── StationaryPPI
    └── OnBoatPPI        — heading offset passed into shader
```

### Threading model

| Thread | Responsibility |
|--------|---------------|
| Render (main) | OpenGL loop, GLFW input, all `glDraw*` calls — never blocks |
| Simulation | Polls `target_data` (PostgreSQL) and GDAL; updates shared `std::vector<Target>` under `std::mutex` |

### FBO phosphor decay
- Render sweep into FBO each frame
- Blit FBO to screen
- Do **not** clear color buffer between frames; draw full-screen quad at very low alpha (~0.05) to decay old sweeps

### Shader notes
- GL_DEBUG_OUTPUT + `glDebugMessageCallback` enabled at startup (GPU robustness protocol)
- No NVIDIA-specific extensions; Mesa/RADV only
- $1/R^4$ attenuation computed in fragment shader; hardware loop gain is a per-scope `uniform` constant

---

## File structure

```
new-radar/
├── CMakeLists.txt
├── src/          — .cpp source files
├── include/      — .h/.hpp headers
│   ├── glad/
│   └── KHR/
├── glad/src/     — glad.c (bundled)
├── shaders/      — .vert / .frag files
├── data/         — patrol_route.json, etc.
└── map/
    ├── charts_enc/   — ENC .000 and GeoTIFF files
    └── lidar_raw/    — LIDAR zips
```

---

## Database

- PostgreSQL, database `radar`, user `radar`, password `radar`
- Table `target_data`: polled by simulation thread for live target positions