initial CMake and DESIGN
This commit is contained in:
145
DESIGN.md
145
DESIGN.md
@@ -0,0 +1,145 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user