updated-radar/CLAUDE.md

This is a project for a museum to demonstrate a simulation of a 1940's to 1960's
vintage radar, including the Chain Home radar from early World War 2, marine radar,

The project will be implemented on a Geekom A8 Max
32 GB RAM
AMD Ryzen 9 8945HS w/ Radeon 780M Graphics
We need to render to the Radeon 780M Graphics GPU

Tech Stack: We are using C++20, OpenGL 4.3 Core, GLFW, GLAD, FreeType, GDAL (libgdal-dev)
Compiler: is g++ (Ubuntu 15.2.0-4ubuntu4) 15.2.0

FreeType is the text type we use
GDAL is used for reading the LIDAR/ENC chart files
GLFW (graphics library framework) open-source, multi-platform library used to manage windows
GLAD (Multi-Language GL/GLES/WGL/GLX Loader-Generator) Loads the pointers to 
   OpenGL functions (like glDrawArrays or glCompileShader)

PostgreSQL is installed. Database: radar. User: radar. Password: radar.
User has full privileges on database radar. Table is target_data.

Operating system details:

Distributor ID: Ubuntu
Description:    Ubuntu 25.10
Release:        25.10
Codename:       questing

Use cmake for building.

[DIRECTIVE: GPU ROBUSTNESS PROTOCOL]

Debug Callback: Enable GL_DEBUG_OUTPUT and glDebugMessageCallback 
to capture driver-level warnings and errors in real-time.

I will be using SSH from Windows to write code and check with claude.
You may compile the code during an SSH session.
Please do not try to run the code during SSH session.
I will run the code while physically using the Geekom.

Please add MIT license header to each file
Please add Author: Mark Allyn to each file

Use snake_case for variables and PascalCase for classes
use #pragma once
Use // for single line comments
use /* */ for multiple block comments spanning multiple lines
avoid using auto

Summary of project:

This is a museum exhibit displaying and providing some interaction
of vintage 1940's, 1950's, and 1960's radars. A key objective is to
provide interaction with and viewing of radars from that era.



There will be three main areas of the screen. On the right hand side will be the radar
scope.

On the left hand side of the screen will be a text description of the scope as well 
as the controls of the scope and keyboard keys for each control. This text will be
white while the control labels will be red and the keystrokes will be in pink.
At some point, pending a decision with the museum, we may purchase components to mount the controls on a panel. Until that is done, the controls will be on the keyboard.

Below the scope will be a text status window. This text will be yellow

Scopes in the right panel

1. Introduction of Exhibit (Explanation of the project on the left hand text panel.
2. A-scope for Chain Home Radar in the 1940's (first radar and could be tricky)
3. A-scope for marine radar in the 1940's (Before PPI radar); was a bit tedious to operate
4. PPI scope for marine traffic control (uses beam sweeping in all 360 degrees of
   rotation); Easier to use than a scope
5. PPI scope on board a boat. Shows how movement of a boat affects the radar display

Please note that these scopes will not appear all at once. The selection of which scope
the visitor sees is done by pressing a forward control and a reverse control to go around
the loop of scopes. The first display when the system is turned on or booted up is the 
Introduction of the exhibit.

Please note that the first iteration of the project will have only minimal controls.
This is a suggestion I got after meeting with the museum staff. Perhaps later we may
add more controls.

Also, please note that the state of the controls of each scope is independent of any
other scope. Furthermore, the controls will reset when a scope is exited and then re-entered.

Controls to affect the behavior of the scopes; (these first implemented using keyboard
strokes; later when and if physical controls are completed, the keyboard controls will be removed)
These controls will affect the state variables and the uniform variables of the shaders.

There will be three abstracts for scopes:

1. A Scope - sweep on horizontal axis. A pulse will appear for a return. The distance from
   the left hand side to the pulse is the range. The height of the pulse is the strength
   of the return signal. The bearing is determined by manual control.

   The basic controls for both A Scopes include:
      Intensity (the overall brightness of the entire display).

      Sensitivity (the strength of the signal amplification of the
      receiver). This has nothing to do with the brightness of the
      pulses. This only affects the height of the pulse and the height
      of any noise floor.

      STC sensitivity; sensitivity for close in targets

      STC sensitivity range; how far shall the STC sensitivity have effect

   Chain Home A Scope

   Because the receiving antennas are very large (about 100 feet), the
   operator cannot physically move them. 
       
   Therefore, the bearing is determined through a process called radio direction
   finding (RDF) using a specialized instrument known as a Radiogoniometer.

   The receiver towers (which were separate from the transmitter towers) 
   featured two sets of dipole antennas mounted at right angles to one 
   another—essentially one oriented North-South and the other East-West.

   The signals from these two perpendicular antennas were fed into a Radiogoniometer
   located in the receiver hut. Inside the device there are two fixed coils (field coils)
   that were mounted at right angles matching the orientation of the outdoor antennas.
   A third coil, the search coil, is mounted on a rotating shaft inside the two 
   field coils. The operator would physically turn a knob to rotate the search coil.

   The relative strength of the signal in each antenna depended on the angle of the
   incoming wave. For example, a target directly to the North would produce a maximum
   signal in the North-South antenna and zero in the East-West antenna. 

   The operator would look for a null point (a signal or pip weaker than the noise floor).
   At that point, the operator would read the bearing from a calibrated scale attached
   to the radiogoniometer knob.

   We can simulate the radiogoniometer knob that would affect the null point depending
   on the bearing of a target. The museum visitor could experience seeing different
   null points for each target. Since we do not have a physical calibrated knob, we
   can put the bearing as a text indicator below the A Scope.

   The range is 200 miles.

   There is no graticule. Photos only show crystal oscillator generated 'pips' for
   every 20 miles. 


   Marine A Scope

   Utilization of A scope marine was limited to military use prior to PPI scope
   invention. An example is British Type 271 radar, introduced in 1941.

   Marine radar frequencies allowed the use of much smaller antennas;
   dishes or horns. Those antennas would be mounted on the shaft of a servo motor. The
   servo motor would be driven by another servo that is attached to the bearing control
   knob on the radar console. The bearing is on a calibrated dial on the bearing control
   knob.

   We can simulate the bearing knob that would affect the simulated pointing of the
   dish antenna. The museum visitor could experience seeing different
   pips appear as they rotate the antenna toward them. Likewise the pips would disappear
   as the antenna is rotated away.

   The range is indicated at how far the pip is from the left hand side of the scope which
   is the location of the radar transmitter. If the target goes further away, 
   the pip will move to the right. If the target comes close to you, the pip will 
   move left.

   This pip has a finite rise time as the transmitter starts.
   The width is set by the modulator stage in the transmitter.
   Following the width, the pip has a finite fall time as the transmitter stops. This
   creates a curved waveform; not just a line.

   A photograph for this display show no graticule at all. Only range pips formed by an oscillator.

   1. 1.5 miles; marker pips every 0.25 miles
   2. 3.0 miles; marker pips every 0.5 miles
   3. 6.0 miles; marker pips every 1.0 miles
   4. 12.0 miles; marker pips every 2.0 miles

   Range can be selected with two keyboard keys or two buttons on the panel, and is
   indicated in the text status panel below the scope.

2. PPI Scope - still being worked



==================================

RADAR EQUATION

Lets start here by mentioning the radar equation that sets the perceived strength of any
radar echoes, no matter what kind of radar.

Summary of radar equation:

The fundamental radar equation describes how much power returns to a radar system 
after bouncing off a distant target. Physically, it follows a "round-trip" journey
of energy: the radar transmits a signal that spreads out as a sphere (losing strength 
by the square of the distance, $R^2$), hits a target that reflects a portion of that 
energy (the Radar Cross Section, $\sigma$), and that reflection then spreads out 
again as a second sphere on its way back (losing another factor of $R^2$). Mathematically, 
this results in the received power being inversely proportional to the fourth 
power of the distance ($1/R^4$), meaning that if a target moves twice as far away, 
the returning signal becomes 16 times weaker. To calculate the final received power 
($P_r$), you multiply the transmitted power ($P_t$) by the antenna's ability to 
focus that energy (Gain, $G$) and its physical size (Aperture, $A$), then factor 
in the target's reflectivity ($\sigma$) and the wavelength of the signal ($\lambda$), 
all while dividing by the spreading losses $(4\pi)^3 R^4$.  
$$P_r = \frac{P_t G^2 \lambda^2 \sigma}{(4\pi)^3 R^4}$$


Since we had four distinct radar types, and each one has it's own hardware loop gain 
that does not change, we can set that as a constant in each radar's target handling shader set.


======================================