diff --git a/CLAUDE.md b/CLAUDE.md index 0b3815d..520b2a8 100644 --- a/CLAUDE.md +++ b/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, -and marine radar on a boat. +at a marine traffic control station, 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 -on board simulator will all follow the following C data structure: +All targets from the network pipeline and simulator map to this C master structure: struct target_data_structure { double target_longitude; double target_latitude; - std::strong vessel_name; // will be null for no available name - std::strng registration; // will be null for no registration + std::string vessel_name; // will be null for no available name + 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 -shaders for this project (this may change later if we want to simulate new -radars that have the capability to show detailed information on each target. +Of this heavy structure, only the following lean mathematical footprint is submitted +to the graphics shaders via an OpenGL Shader Storage Buffer Object (SSBO) layout(std430): struct target_data_to_shader_structure { - double target_longitude; - double target_latitude; - float length; - float beam; - float course; - float altitude; - time_t timestamp; - }; + float target_x; // Pre-converted local Cartesian offset X (meters relative to radar) + float target_y; // Pre-converted local Cartesian offset Y (meters relative to radar) + float length; // Vessel length bounds (meters) + float beam; // Vessel beam bounds (meters) + float course; // Course over ground vector (radians relative to True North) + float altitude; // Target altitude profile (meters) + time_t timestamp; // Data aging tracking identifier +}; -The section of the project's code for handling targets coming in from the -raspberry pis as well as the simulator will be called the traffic_cop. -The traffic cop will run on a different thread than the software that directly -feeds the shaders. Mutexes shall be used to control feeding data to the software -that feeds the shaders. +The segment handling asynchronous target ingestion is called traffic_cop. +The traffic_cop runs on a dedicated background execution thread separate from the rendering loop. +Data synchronization between threads must be managed explicitly using std::mutex blocks. -This traffic cop will receive the targets and peform the following: - -1. Check to see if the target is beyond the maximum range of the radar being used; - disccarding those beyond the maximum range. -2. Check that aircraft if below 40 meters in altitude for marine type radars; - marine chain home and all ppi marine radars. If not, that target shall - be discarded. Convert the incoming target data structure to that - to be used by the shaders. -3. Assert mutex to get permission to provide an array of target information - 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. +[TRAFFIC COP OPERATIONAL TIMING PROTOCOL] +1. Processing Loop: Aggregated targets are packaged into a uniform array and dispatched + as a batch operation precisely when the PPI radar sweep line crosses 0.0 radians (True North). +2. Range Filtering: Discard any targets residing outside the active radar's designated maximum operational range. +3. Altitude Restriction: Enforce a strict <= 40-meter restriction for marine nodes (Marine Chain Home + and all PPI Marine radars). Discard any aircraft violating this ceiling. +4. Precision Alignment: Latitude and longitude coordinate conversions into local meters relative to + the radar origin must be handled on the CPU thread within traffic_cop to protect against FP32 structural precision rounding errors inside the GPU. +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. 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) - -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: +RADAR EQUATION (for all radars; note that is different for chain home) 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$). +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$. +控制方程 (Governing Equation): $$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 -that does not change, we can set that as a constant in each radar's target handling shader set. +Because each of our target scopes contains fixed design loops, these values can be pushed directly +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 - is at the top of the display and noise and distance pips and target blips will - go down. + The Chain Home A-Scope display layout is inverted. The steady, horizontal reference baseline + (the zero signal line) sits at the top of the tube display window (`y = 0.9` in viewport NDC coordinates). + 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 - base reference. The cone apearance of a target blip (ristime of a signal due - due to non perfect bursts of radio frequency pulses from the transmitters) - can be measured against the calibration pips. + This top-down structure protects the upper edge of the reference line from being distorted by noise grass, + enabling the operator to align the trace against an illuminated glass graticule with a clean visual focus. - Also note that the calibration pips, the noise floor, and the target pips - are mixed together before being sent to the deflection plates of the tube. - This is a hardware reality of any CRT A-scope: the deflection plates receive - a single voltage, so all sources must be combined into that one signal. + All source signals are combined in a single hardware mixing matrix before driving the electrostatic plates: + * **Receiver Chain:** The atmospheric background noise floor (grass) and the target echo pulses are combined + first, and are directly scaled by the operator's Receiver Sensitivity control. + * **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 - 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. */ + [SUMMING AMPLIFIER PROTOCOL] 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 - - Sine based resonance Multiplier in target handling + [METRIC RESONANCE MODEL] + Because the 12-meter carrier wavelength closely matches the physical physical dimensions (wingspan) + 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 - beam. + Because the radar antenna emits a beam with a finite horizontal beamwidth rather than an + 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 - are passed to the shaders) and any part of the beam, including the very edges; you will get - an echo. The echo will be the weakest when the edge of the beam intersects with the edge of - the target that is closest to the beam. The strength is greatest when the axis of the radio - frequency beam is center to the center of the target as it appears in the direction of the - radar. This, of course, is affected by the heading of the target (the direction the target - is movine in relation to the position of the radar; if the target is heading to the radar, the - profile as see to the radar would be the smallest). Then as the radio frequency bearm moves - past the target, the intensity of the return signal would be weaker and weaker until the beam - completely passes the target and no more energy is returned. - - 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. + The returned signal intensity distribution across this structural arc is defined by three rules: + 1. **Geometric Profile Aspect:** The cross-section $\sigma$ is computed dynamically using the target's explicit + course vector and bearing. The projected surface area facing the wavefront handles the ship's + length and beam parameters: + $$\text{Projected Width} = (|\sin(\text{aspect\_angle})| \times \text{length}) + (|\cos(\text{aspect\_angle})| \times \text{beam})$$ + $$\sigma = \text{Projected Width} \times 2.5$$ + 2. **Gaussian Power Distribution:** The returned echo energy along the arc changes smoothly according to a + Gaussian curve. The absolute edges are dimmest (where the beam's outer threshold grazes the + target perimeter) and expand exponentially to max intensity at the center axis of alignment. + 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. 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: