add target info edits

CLAUDE.md

@@ -1,7 +1,6 @@
 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
-at a marine traffic control station,
+at a marine traffic control station, and marine radar on a boat.
-and marine radar on a boat.
 
 The project will be implemented on a Geekom A8 Max
 32 GB RAM
@@ -106,7 +105,7 @@ affect all scopes.
 
 ====================================================================================
 
-TARGET DETAILS
+TARGET DETAILS & TARGET PIPELINE
 
 Targets for this project will come from two sources:
 
@@ -117,16 +116,15 @@ Targets for this project will come from two sources:
 
 Please note that the components for the AIS and ADS-B target
 handling are not yet available, thereby the programming for that
-souce will not be defined at this point.
+source will not be defined at this point.
 
-Please note that all targets, both from the AIS, ADS-b, and and the 
+All targets from the network pipeline and simulator map to this C master structure:
-on board simulator will all follow the following C data structure:
 
 struct target_data_structure {
    double target_longitude;
    double target_latitude;
-   std::strong vessel_name; // will be null for no available name
+   std::string vessel_name; // will be null for no available name
-   std::strng registration; // will be null for no registration
+   std::string registration; // will be null for no registration
    float length; // in meters
    float beam; // in meters
    int vessel_type; // AIS type code or aircraft type
@@ -136,43 +134,34 @@ struct target_data_structure {
    time_t timestamp; // time of last fix; used to age out stale targets
    float altitude; // meters, but 0 for boats
    TargetType type; // type of target; vessel or aircraft
-   };
+};
 
-Of this structure, only the following structure needs to be submitted to the
+Of this heavy structure, only the following lean mathematical footprint is submitted
-shaders for this project (this may change later if we want to simulate new
+to the graphics shaders via an OpenGL Shader Storage Buffer Object (SSBO) layout(std430):
-radars that have the capability to show detailed information on each target.
 
 struct target_data_to_shader_structure {
-  double target_longitude;
+  float target_x;     // Pre-converted local Cartesian offset X (meters relative to radar)
-  double target_latitude;
+  float target_y;     // Pre-converted local Cartesian offset Y (meters relative to radar)
-  float length;
+  float length;       // Vessel length bounds (meters)
-  float beam;
+  float beam;         // Vessel beam bounds (meters)
-  float course;
+  float course;       // Course over ground vector (radians relative to True North)
-  float altitude;
+  float altitude;     // Target altitude profile (meters)
-  time_t timestamp;
+  time_t timestamp;   // Data aging tracking identifier
-  };
+};
 
-The section of the project's code for handling targets coming in from the
+The segment handling asynchronous target ingestion is called traffic_cop.
-raspberry pis as well as the simulator will be called the traffic_cop. 
+The traffic_cop runs on a dedicated background execution thread separate from the rendering loop. 
-The traffic cop will run on a different thread than the software that directly
+Data synchronization between threads must be managed explicitly using std::mutex blocks.
-feeds the shaders. Mutexes shall be used to control feeding data to the software
-that feeds the shaders.
 
-This traffic cop will receive the targets and peform the following:
+[TRAFFIC COP OPERATIONAL TIMING PROTOCOL]
-
+1. Processing Loop: Aggregated targets are packaged into a uniform array and dispatched 
-1. Check to see if the target is beyond the maximum range of the radar being used;
+   as a batch operation precisely when the PPI radar sweep line crosses 0.0 radians (True North).
-   disccarding those beyond the maximum range.
+2. Range Filtering: Discard any targets residing outside the active radar's designated maximum operational range.
-2. Check that aircraft if below 40 meters in altitude for marine type radars;
+3. Altitude Restriction: Enforce a strict <= 40-meter restriction for marine nodes (Marine Chain Home 
-   marine chain home and all ppi marine radars. If not, that target shall
+   and all PPI Marine radars). Discard any aircraft violating this ceiling.
-   be discarded. Convert the incoming target data structure to that 
+4. Precision Alignment: Latitude and longitude coordinate conversions into local meters relative to 
-   to be used by the shaders.
+   the radar origin must be handled on the CPU thread within traffic_cop to protect against FP32 structural precision rounding errors inside the GPU.
-3. Assert mutex to get permission to provide an array of target information
+5. Critical Section: Assert a std::mutex to gain safe writing access to the double-buffered array driving the SSBO, copy the structural contents, and clear the mutex immediately.
-   for the shaders.
-4. Copy the array into the target data structure for the shaders.
-5. Clear the mutex.
-
-Note suggestion that target data be given as a batch once every sweep of the
-beam through the 0 degree (top) of the scope.
 
 Note that the construction of the simulator will be discussed later in this document.
 
@@ -203,7 +192,7 @@ These are knobs on the panel once that is built. Keyboard keys until then
 4. STC Range - range to which sensitivity to closer targets is effective
    keyboard e for lower; r for higher
 5. Radiogoniometer knob for Chain Home; keyboard t for left turn; y for right turn.
-6. Maximum Range for all scopes except for chain  home, which is fixed. This control
+6. Maximum Range for all scopes except for chain home, which is fixed. This control
    will not operate for Chain Home. These maximum
    range selections will be defined for each scope; If you try to go beyond the stated
    maximum ranges, the control will have no effect; note that the default maximum range would
@@ -219,38 +208,34 @@ However, when I make the control panel, those will be combined as one physical k
 labels, chain home radiogon, marine a scope antenna rotation, and ppi scope bearing to save on 
 hardware; the same physical control can be used for multiple scopes.
 
-Note that the range cursor is different from the maximum range. Maximum range  is the maximum
+Note that the range cursor is different from the maximum range. Maximum range is the maximum
 radar range setting and range cursor is the range portion of the ppi cursor.
 
 =========================================================================
-RADAR EQUATION (for all radars; note that is different for chain  home)
+RADAR EQUATION (for all radars; note that is different for chain home)
-
-Lets start here by mentioning the radar equation that sets the perceived strength of any
-radar echoes, no matter what kind of radar (a scope and ppi scopes)
-
-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
+Physically, it follows a "round-trip" journey of energy: the radar transmits a signal 
-of energy: the radar transmits a signal that spreads out as a sphere (losing strength 
+that spreads out as a sphere (losing strength by the square of the distance, $R^2$), 
-by the square of the distance, $R^2$), hits a target that reflects a portion of that 
+hits a target that reflects a portion of that energy (the Radar Cross Section, $\sigma$), 
-energy (the Radar Cross Section, $\sigma$), and that reflection then spreads out 
+and that reflection then spreads out again as a second sphere on its way back (losing 
-again as a second sphere on its way back (losing another factor of $R^2$). 
+another factor of $R^2$). 
 
-Mathematically, this results in the received power being inversely proportional to the fourth 
+控制方程 (Governing Equation):
-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}$$
 
+Where:
+  P_r = Received Echo Power (Watts)
+  P_t = Peak Transmitter Power (Watts)
+  G   = Antenna Gain (Linear)
+  λ   = Wavelength of transmitted carrier wave (Meters)
+  σ   = Radar Cross Section (RCS, Meters squared)
+  R   = Target Range from station origin (Meters)
 
-Since we had four distinct radar types, and each one has it's own hardware loop gain 
+Because each of our target scopes contains fixed design loops, these values can be pushed directly
-that does not change, we can set that as a constant in each radar's target handling shader set.
+as hardware uniform parameters matching specific hardware loop gains that do not change.
 
 ========================================================
 
@@ -324,7 +309,7 @@ Individual scope informations
 
       STC sensitivity range; how far shall the STC sensitivity have effect. 
 
-    Please  note that the phosphor (chemical that glows when hit by
+    Please note that the phosphor (chemical that glows when hit by
     electrons in the tube) is green, similar to an oscilloscope. The Hex
     for green is #39FF14; there is a short persistance of the phosphor after being
     struck by the electron beam. That persistance is about 25 milliseconds and its color
@@ -341,46 +326,33 @@ Individual scope informations
 
    ==========================================================
 
-   Downward PIP and mixing calibration pips with target pips and noise grass
+   [INVERTED DISPLAY & ADDITIVE VIDEO SIGNAL SUMMATION]
 
-   Very important. The Chain Home A Scope is upside down. That is, the baseline
+   The Chain Home A-Scope display layout is inverted. The steady, horizontal reference baseline 
-   is at the top of the display and noise and distance pips and target blips will
+   (the zero signal line) sits at the top of the tube display window (`y = 0.9` in viewport NDC coordinates). 
-   go down. 
+   All video activity—receiver noise floor grass, fixed calibration markers, and target echo pulses—deflects 
+   vertically **downward** into the dark lower quadrants of the screen.
 
-   This is done so that the operator can look at the top of the scope for the
+   This top-down structure protects the upper edge of the reference line from being distorted by noise grass, 
-   base reference. The cone apearance of a target blip (ristime of a signal due
+   enabling the operator to align the trace against an illuminated glass graticule with a clean visual focus.
-   due to non perfect bursts of radio frequency pulses from the transmitters)
-   can be measured against the calibration pips.
 
-   Also note that the calibration pips, the noise floor, and the target pips
+   All source signals are combined in a single hardware mixing matrix before driving the electrostatic plates:
-   are mixed together before being sent to the deflection plates of the tube.
+   * **Receiver Chain:** The atmospheric background noise floor (grass) and the target echo pulses are combined 
-   This is a hardware reality of any CRT A-scope: the deflection plates receive
+     first, and are directly scaled by the operator's Receiver Sensitivity control.
-   a single voltage, so all sources must be combined into that one signal.
+   * **Calibration Chain:** The crystal-controlled 20-mile reference pips are injected into the video chain 
+     AFTER the primary receiver gain stage. As a result, modifications to the Sensitivity control do not scale 
+     the vertical height of calibration pips.
 
-   That means that the three sources are summed together before you see them
+   [SUMMING AMPLIFIER PROTOCOL]
-   on the scope. Remember that zero signal is the reference line at the top.
-
-   Importantly, the calibration pips are generated by a crystal oscillator and
-   injected into the video chain AFTER the receiver gain stage. This means
-   turning the Sensitivity control up or down does NOT change the height of the
-   calibration pips — only the noise floor and target echoes are scaled by the
-   receiver gain. This is true for both Chain Home and the Marine A-scope.
-
-   For example, if one of the calibration pips is exactly the same distance as
-   a target blip, that would look like it is extending the target blip. This was
-   a known operational hazard; operators were trained to account for it.
-
-   For your reference, the work inside the shader may be something like:
-
-   /* Simulated Summing Amplifier Logic.
-      Cal pips are outside the sensitivity multiply because they are injected
-      after the receiver gain stage in the real hardware. */
    float receiver_signal = (noise_floor + target_echoes) * sensitivity;
    float total_deflection = receiver_signal + calibration_pips;
    
-   // Apply to your downward-hanging baseline
+   // Map values downwards from structural baseline ceiling
    float final_y = baseline_y - total_deflection;
 
+   If an operational target echo shares an identical range slot with a 20-mile calibration pip, their respective 
+   voltages additively sum, dynamically pushing the peak tip further toward the bottom layout limit.
+
    ==========================================================================
 
    Because the receiving antennas are very large (about 100 feet), the
@@ -422,12 +394,14 @@ Individual scope informations
    Wavelength 12 Meters
    Antenna Gain 5 dB
    Pulse Width 20 microseconds
-   Beam Width 150  degrees (floodlight)
+   Beam Width 150 degrees (floodlight)
    PRF 25 HZ
 
-   Airplane acts as a half wave dipole
+   [METRIC RESONANCE MODEL]
-
+   Because the 12-meter carrier wavelength closely matches the physical physical dimensions (wingspan) 
-   Sine based resonance Multiplier in target handling
+   of historical combat aircraft (e.g., 10-12 meters), the target functions as a resonant half-wave dipole. 
+   When a target's physical length falls within the Rayleigh/Mie resonant band (40% to 60% of the carrier wavelength), 
+   the backscattering intensity receives an explicit 1.5x structural cross-section multiplier.
 
    // Pseudocode for Shader/Logic
    float resonance = (targetLength >= wavelength * 0.4 && targetLength <= wavelength * 0.6) ? 1.5 : 1.0;
@@ -509,7 +483,7 @@ Individual scope informations
 
    SYSTEM_TEMPERATURE ($T_s$): Usually 290K; used to calculate the noise floor
    NOISE_FIGURE ($F$): A value in dB that determines how much "grass" your 
-     specific receiver adds to the signal.
+     specific receiver adds to the signal (20 dB typical for early centimetric systems).
    BOLTZMANN_CONSTANT ($k$): $1.38 \times 10^{-23}$, essential for the thermal 
      noise part of your simulation.
 
@@ -581,25 +555,24 @@ Individual scope informations
 
    =========================================================================
 
-   Important Nuance For PPI Scope.
+   [PPI BEAM-WIDTH & TARGET SPATIAL ARC DISPERSION]
 
-   The radio frequency beam from the antenna has a finite width. It's not just a pencil thin
+   Because the radar antenna emits a beam with a finite horizontal beamwidth rather than an 
-   beam.
+   infinitely narrow beam, targets intersect the energy wave continuously as the antenna rotates 
+   across their angular boundaries. This spatial geometric interaction distorts a standalone point target 
+   into a concentric circumferential **arc** drawn perpendicular to the radar's origin vector.
 
-   So what that means is the if there is any intersection between the target (whose dimentions
+   The returned signal intensity distribution across this structural arc is defined by three rules:
-   are passed to the shaders) and any part of the beam, including the very edges; you will get
+   1. **Geometric Profile Aspect:** The cross-section $\sigma$ is computed dynamically using the target's explicit 
-   an echo. The echo will be the weakest when the edge of the beam intersects with the edge of
+      course vector and bearing. The projected surface area facing the wavefront handles the ship's 
-   the target that is closest to the beam. The strength is greatest when the axis of the radio
+      length and beam parameters:
-   frequency beam is center to the center of the target as it appears in the direction of the
+      $$\text{Projected Width} = (|\sin(\text{aspect\_angle})| \times \text{length}) + (|\cos(\text{aspect\_angle})| \times \text{beam})$$
-   radar. This, of course, is affected by the heading of the target (the direction the target
+      $$\sigma = \text{Projected Width} \times 2.5$$
-   is movine in relation to the position of the radar; if the target is heading to the radar, the
+   2. **Gaussian Power Distribution:** The returned echo energy along the arc changes smoothly according to a 
-   profile as see to the radar would be the smallest). Then as the radio frequency bearm moves
+      Gaussian curve. The absolute edges are dimmest (where the beam's outer threshold grazes the 
-   past the target, the intensity of the return signal would be weaker and weaker until the beam
+      target perimeter) and expand exponentially to max intensity at the center axis of alignment.
-   completely passes the target and no more energy is returned. 
+   3. **Sweep Intersect Envelope:** Energy returns climb from the noise floor, achieve peak voltage 
-
+      at perfect cross-coincidence, and fade back down into the receiver noise as the sweep line passes the target.
-   So, the target would appear as a curved line that is perpendicular to the angle of the radio
-   frequency beam. The ends of the line would be the dimmest in intensity (weaker) and the center
-   of the target would be the brightest.
 
    Graticules - These are plastic overlays over the face of the scope. They are
    for the purposes of showing the bearing. They are calibrated in degrees; short line (1/8 inch)
@@ -610,10 +583,6 @@ Individual scope informations
 
    =======================================================================
 
-   
-
-
-
 ==================================
 
 settings.h file suggestions: