diff --git a/additions b/additions index 6f3a2c0..1cef301 100644 --- a/additions +++ b/additions @@ -1,112 +1,228 @@ -I would like to have this project use the radar equation to determine -brightness and possible blooming on targets. +================================================================== +ADDITION: BOAT RADAR — BELLINGHAM POLICE PATROL BOAT +================================================================== -I want the radar equation to be implemented within the shaders. +I want to add a radar scope showing the view from a marine radar +mounted on a Bellingham Police Department patrol boat. The boat +is on a continuous back-and-forth patrol of the working waterfront. -I want a postgres database (I did install postgresql and set up a database named radar with -a postgresql user named radar with password radar with full priveleges to database radar. +PATROL ROUTE: + Police boats do patrol inside Squalicum Marina (theft, vandalism, + welfare checks) and inside Whatcom Waterway (commercial port + security). They do not rely on seeing over the breakwater -- + the concrete breakwater shadows the inner basin. -DATABASE Schema: + Speed varies by zone: + Open waterfront: 10 knots + Whatcom Waterway: 3-5 knots (narrow, industrial) + Inside marina: 3-4 knots (displacement speed, no wake) -1. Type of target (Enumeration AIS, ADS-B, Local (simulator) -2. ID a. MMSI for marine; b. ICAO 32 bit aircraft address; for simulator we can use the same MMSI - and aircraft address -3. width (32 bits) in meters (float data type) -4. length (32 bits) in meters (float data type) -5. Height above water (32 bits) in meters (float data type) -6. Material (Enumeration fiberglass, wood, aluminum, steel -7. boolean: need update for size and material, does not need update for size and material -8. ISO 8601 timestamp for last used -9. ISO 8601 timestamp for last updated -10. Track / position history (to be used if I want newer track prediction radars + Proposed full route (continuous, reversing at each end): + Whatcom Waterway entrance + -> slow to 4 knots, transit Whatcom Waterway + -> exit to bay, accelerate to 10 knots + -> Squalicum Marina outer breakwater entrance + -> slow to 3-4 knots, tour inner marina basin + -> exit marina, accelerate to 10 knots + -> west along waterfront + -> Boulevard Park + -> Taylor Dock + -> Community Boating Center + -> reverse and repeat -For performance, we can keep id, width, length, and height, and material -inside the shaders as fixed data; but have location, heading, and altitude (aircraft) + INSIDE MARINA -- RADAR CLUTTER NOTE: + At 2-3 m antenna height inside a marina full of sailboat masts, + the radar picture will be heavily cluttered with mast returns, + appearing as a dense ring around the boat. This is realistic and + is a good exhibit teaching moment -- visitors can use the sea/wave + clutter filter (already designed) to try to suppress it. The boat + radar's wide beamwidth (4-6 deg) makes the clutter worse than the + big coastal radar would show. -The items that are updated per data coming in from the raspberry pis and the simulator -are orientation / RCS (based on heading), location (in longitude and latitude) and ID ; Suggestion -vertex objects or SSBO +PATROL SPEED: + Approximately 10 knots. -Suggest that CPU compute the RCS based on heading and dimensions and altitude (aircraft) -In doing this, keep this work outside of any mutex lock of any shared data + 10 knots is reasonable -- typical working-waterfront patrol speed + is 8-12 knots, fast enough to respond quickly but slow enough to + observe traffic and avoid wake damage near the docks. -Maybe, if I simulate a modern system, I may want a field to describe the target (passenger, cargo, -oil, fishing; and maybe specifics for the targets. I know that the coast guard has a lot of -contextual data on targets that are from external sources. For now, let's not worry about this. +WHAT THIS MEANS FOR THE DISPLAY: + Unlike all the other radars in this exhibit, the radar origin is + not fixed. It moves with the boat along the patrol route. The + radar antenna is on the boat, so the PPI scope center tracks the + boat's position. -PROPOSAL: + The boat also changes heading as it follows the shoreline, which + means the bearing offset (already implemented as the k/j keys on + the marine PPI) will be continuously updated by the simulator as + the boat turns -- the operator does not manually drive the boat. -Since ADS-b and AIS may not have material and size data, I would like to propose -That the initial running of the system upon detecting a target that has no size -determination, we use a default size, say, 20 feet long 20 feet wide and fiberglass -for boats; 50 feet long 10 feet wide fusalage for planes; and set the need update parameter -to need update. + The boat's heading at any point along the route determines the + antenna offset so that True North stays at the top of the scope. -Add an option (command line option) for system. Command line options would be 'database' -which would open a graphical panel suitable for updating the postgres database. -At the beginning of the life of this project, almost all targets seen except for those -from the simulator will need database updating; as life of the system gets older there would -be fewer targets that need operation. For this option; none of the main radar screens -will be available. So we do not have to to have the opengl and shader stuff. Use a regular -desktop based application non opengl shader database updating application. This would be ended with quit -and then the main radar application can be started. +SIMULATOR ARCHITECTURE: + The patrol boat position is the radar PLATFORM, not a target. + It should be managed by the existing Simulator (Thread 4) as a + special PatrolPlatform object alongside the target list -- NOT a + separate simulator thread, and NOT built into the scope/rendering + code (Thread 1). -END OF PROPOSAL + The TrafficCop (Thread 2) already polls the Simulator each sweep. + It will also retrieve the current platform lat/lon and heading at + the same poll and write them to SharedRenderState under Mutex A. + Thread 1 reads platform position and heading to set the PPI scope + center point and bearing offset before rendering each frame. -Marine radar equation stuff: + The patrol route is a sequence of lat/lon waypoints with speed + per segment. The Simulator interpolates position between waypoints + using elapsed time and the segment speed. -For this purpose, the marine radar will use the X Band (9225 MHZ) and 30 KW power for -maritime traffic system radar (our a-scope marine and PPI scope marine) +DECISIONS: + 1. SCOPE CLASS: New BoatPPIScope, a subclass of PPIScope directly + (not a subclass of MarinePPIScope). Same controls as MarinePPIScope. + Moving origin is specific to this class. -For Marine, horizontal beam width is 0.5 degrees; vertical beam width is 20 degrees. -For Marine, the antenna size is 15 feet in length. -For Marine, the antenna height is 50 feet off surface + 2. WAYPOINTS: JSON data file, e.g. data/patrol_route.json. + Loaded at startup by the Simulator. Each entry has lat/lon and + speed for that segment. settings.h stays as tunable constants only. -Air traffic radar equation stuff: - -For this purpose, the air traffic control radar at BLI frequency 3 ghz or S Band; -power 25 KW + 3. LEFT PANEL: Both -- a plain text zone description (e.g. + "Currently: Open waterfront, heading west") AND a numeric + lat/lon readout below it. Visitor-friendly text plus precise data. -For Air Traffic Control, the beam width is 1.4 degrees for horizontal and 5 degrees for vertical -For Air Traffic Control, the antenna size is 20 feet wide -For Air Traffic Control, the antenna is on a tower 50 feet high from the runway. It is not -mounted on the control tower. + 4. SIMULATED SMALL TARGETS: Both scripted and random. + - Scripted: a paddleboarder drifts slowly across the ferry lane + on a fixed loop (dramatic, repeatable, good for exhibit) + - Random: additional kayakers/small boats wander within a defined + zone near the ferry terminal and harbor mouth + - These small targets also appear on the fixed MARINE PPI scope + (same Bellingham Bay coverage area, same target pipeline) -Chain Home radar equation stuff: + 5. SCOPE ORDER: Boat PPI goes immediately after Marine PPI. + New sequence: Intro -> Marine A -> Chain Home A -> Marine PPI + -> Boat PPI -> ATC PPI -> PAR -> (back to Intro) -For Chain Home, this will be a bit different: (this is AMES type 1) + 6. MARINA AND WHATCOM WATERWAY: Deferred. The patrol route for v1 + stays in open water only. The boat does NOT enter Squalicum Marina + or Whatcom Waterway in the first implementation. Those can be + added in a later version once the shoreline geometry problem + is solved (see LIDAR/CHART NOTE below). -Frequency is 30 MHZ -Power is 500 KW -Pulse width is 20 US +LIDAR AND SHORELINE GEOMETRY NOTE: -TRANSMIT GAIN (Gt) -Note that the transmit beam is not a beam, but a floodlight. -Pulse repetition frequency is 25 Hz or 12.5 Hz as selected by operator -Use Transmit G from beam width (floodlight) something like -G = 30000/100 degrees * 40 degrees -about 8.7 dBi (linear value of 7.5) + The marina, breakwater, Whatcom Waterway, and Georgia Pacific site + all require accurate geometry to simulate correctly -- both as radar + return sources and as shadow-casters. -Note that this is Bistatic; we need both Gt and Gr + TWO DATA SOURCES: -RECEIVE GAIN (Gr) is about 4 to 10 (6–10 dBi) + 1. NOAA Electronic Navigational Chart 18424 (Bellingham Bay) + Free vector download from charts.noaa.gov (ENC format). + Already clean vector polygons: breakwater, piers, channel edges, + ferry terminal, dock outlines. Best starting point -- no point + cloud processing required. -System loss due to transmission line about 8 DB + 2. Washington State LIDAR Portal (lidarportal.dnr.wa.gov) + Free LIDAR point cloud downloads for Whatcom County. + 0.5-1 meter horizontal resolution. Captures individual pilings, + building edges, breakwater detail, Georgia Pacific site remnants. + Use this when finer detail is needed (inside marina, Whatcom + Waterway structures). Requires offline processing to extract + obstruction polygons before use in the simulation. -Target RCS larger RCS due to resonant scattering (I need help; please lookup + GEORGIA PACIFIC SITE: + Most of the old GP pulp mill has been demolished. The area is + now the Bellingham Waterfront District (partially built). LIDAR + or ENC data will show whatever was on-site at survey time. For + the exhibit this is acceptable -- it is a patrol scenario, + not a live chart. -Precision Approach Radar Equation Stuff: + HOW GEOMETRY FEEDS INTO THE SIMULATION: + Shoreline and obstruction data is processed ONCE offline into + a set of vector polygons representing hard radar-reflective + features. These are loaded at Thread 1 startup as a static VBO. + Read-only after load -- no mutex required (already noted in + the design). The radar sweep computes returns from these + polygons the same way it handles vessel targets. -Peak power is about 100 kw -Very high antenna gain -X Band (3 cm for wavelength) Operation allow higher antenna gain -PAR must reliably detect small aircraft -High pulse repetition rate -Sweep about 20 degrees horizontal and 10 degrees vertical -Short pulse width for range resolution -Beamwidth is determined by wavelength/antenna size with antenna size of about 5 meters. + RADAR SHADOW ZONES: + The breakwater does not just produce a return -- it shadows + everything behind it. To simulate this correctly, the sweep + must raycast from the current radar position, find the first + intersection with each obstruction polygon, and mark everything + beyond that intersection as shadowed (no return). This is a + per-sweep raycast operation, implementable CPU-side each sweep + or in a compute shader. Shadow simulation is required even for + the v1 open-water-only route, because the breakwater shadow + is clearly visible from outside. -GENERAL NOTE FOR EQUATION STUFF + V1 GEOMETRY SCOPE (open water only -- marina deferred): + Only these features are needed for the first version: + - Outer shoreline of Bellingham Bay (simple polygon) + - Squalicum Harbor breakwater (solid obstruction, shadow-caster) + - Ferry terminal structure + - Taylor Dock pier outline (weak return -- wood, but pilings show) + - Boulevard Park shoreline + NOAA ENC 18424 provides all of these in vector form. + Internal marina dock fingers and Whatcom Waterway structures + are deferred until the boat patrol route enters those areas. -We will need these key variables to be able to be changed via the settings.h file -and DESIGN.md and CLAUDE.md + 4. The radar hardware spec for the boat radar is DIFFERENT from + the fixed coastal marine radar. Typical police/patrol boat radar: + + Frequency: 9.3 - 9.5 GHz (X-band, same band, slightly + different frequency -- treat as same for exhibit) + Peak power: 2 kW to 4 kW (NOT the 30 kW of the fixed + coastal radar -- this is a small-vessel unit) + Antenna type: Radome (enclosed dome, ~60 cm diameter) -- + more rugged and lower wind resistance than + an open array, typical for patrol boats + Horizontal beamwidth: 4 to 6 degrees (vs 0.5 deg for the big + coastal radar -- targets will appear as + noticeably fatter blips; good exhibit contrast) + Antenna height: 2 to 3 meters above waterline (radar arch + or short mast on a 25-35 foot patrol vessel) + + RADAR HORIZON at 2.5 m antenna height: + horizon = 2.23 x sqrt(2.5) = approx 3.5 nautical miles + (~4 statute miles) to a sea-level target. + Compare: fixed coastal radar at 15 m sees ~8.6 nautical miles. + + MAX RANGE DECISION: 2 miles maximum. + The patrol boat's job is close-in situational awareness, not + long-range surveillance (the fixed coastal radar handles that). + 2 miles puts the entire inner harbor on screen at once. + + RANGE STEPS: 0.5 / 1 / 2 miles. + Tighter steps than the fixed marine scopes (2/4/6) because the + officer needs a close-in zoom for marina and waterway work: + 0.5 mi -- tight quarters, marina basin, Whatcom Waterway + 1.0 mi -- inner harbor, near-shore patrol + 2.0 mi -- full harbor picture, ferry lane monitoring + + SMALL TARGET DETECTION NOTE (important for exhibit realism): + A paddleboard or kayak is a marginal radar target at any range. + Very small RCS, almost no freeboard. At 2-4 kW with 4-6 degree + beamwidth, a paddleboarder may show as a faint intermittent blip + or may wash into the noise floor entirely -- especially in chop. + A kayak carrying a small aluminum radar reflector shows much + better. This is realistic and worth simulating: the exhibit + shows visitors that radar does not see everything, and that + small non-metallic targets are genuinely hard to detect. + + FERRY LANE SCENARIO: + The Bellingham terminal serves the Alaska Marine Highway System + (state ferries up to 400 feet). A paddleboarder or kayaker + drifting into the departure lane is a real hazard the patrol + officer watches for. Simulated small targets (paddleboards, + kayaks) near the ferry lane would make a compelling exhibit + moment -- visitor tries to spot them on the radar before the + ferry moves. + + 5. Should the left panel description explain that this is a moving + platform, and show the current boat position (lat/lon or a + simple text description of where on the route the boat is)? + + 6. I do not care about the size or material of the police boat + itself since it is the platform the radar is mounted on, not + a target. diff --git a/additions-comments b/additions-comments index 3aad156..e69de29 100644 --- a/additions-comments +++ b/additions-comments @@ -1,127 +0,0 @@ - 1. Radar Equation in Shaders - - Good idea overall, but the phrase "keep a copy of the data in the shaders" needs clarification. Shaders are stateless - per-invocation — they don't store data between frames. What you actually want is: - - - A CPU-side target array (mirroring the DB subset of known targets) that gets uploaded to the GPU each frame via a - Shader Storage Buffer Object (SSBO) or uniform array. - - The shader reads per-target RCS + range, computes P_r from the radar equation, and maps it to brightness/amplitude. - - Blooming cannot be done in a single render pass. It requires a post-processing pass — render targets to an FBO at full - brightness, then apply a Gaussian blur/threshold to bright spots and blend back. This is a separate shader pair and - should be in the file layout. - - The radar equation belongs naturally in the phosphor.frag shader or a dedicated radar_equation.glsl include file - shared across scopes. - - --- - 2. PostgreSQL Database Schema — Issues to Address - - 24-bit field widths (width, length, height) don't map to standard SQL types. PostgreSQL has SMALLINT (16-bit), INTEGER - (32-bit), and BIGINT (64-bit). You'll want INTEGER or SMALLINT. Define units explicitly — feet or meters — and - document it in the schema, or you'll regret it later. - - The "need update" enumeration is really just a boolean. Consider BOOLEAN need_update DEFAULT TRUE rather than an enum - with two values. Simpler, and PostgreSQL handles it natively. - - The schema is missing a few things worth adding now: - - A timestamp for when the record was last seen (for staleness tracking) - - A timestamp for when the record was last updated by an operator - - Units annotation (feet vs meters) on dimensional fields - - Missing from the schema: any position/track history. That's probably intentional for v1, but worth noting — the DB - only stores identity and physical characteristics, not track data. Track data lives in TargetBuffer (Thread 2/4), - which is correct for real-time use. - - --- - 3. Default Sizes for Unknown Targets - - The proposal to default unknown AIS/ADS-B targets to a standard size with need_update = TRUE is practical and - well-conceived. Two observations: - - - For aircraft, "50 feet long, 10 feet wide" covers a narrow-body airliner but not small GA aircraft (Cessna 172 = - ~27ft long, ~36ft wingspan). A GA default would be more realistic for BLI traffic. Consider two aircraft defaults: GA - and commercial. - - For boats, fiberglass is a good default for pleasure craft. However, if targets are coming from AIS, they are - legally required commercial/commercial-sized vessels, which are more likely steel. You may want separate defaults for - AIS-sourced vs simulator-sourced marine targets. - - --- - 4. Command Line Database Panel - - This is architecturally sound — separating the museum exhibit mode from the operator database management mode via a - command line flag keeps the exhibit clean. A few things to think through: - - - The DB panel will need a UI toolkit. GLFW is minimal — it gives you an OpenGL window and keyboard/mouse but no - widgets. Consider using Dear ImGui for the DB panel; it's header-only, integrates directly with GLFW/OpenGL, and would - give you form fields, dropdowns, and tables without a heavy dependency. - - The additions file mentions DESIGN.md as a place to document settings alongside settings.h. That file doesn't exist - in the current layout in CLAUDE.md — it should be added to the file list. - - --- - 5. Radar Parameters — Technical Notes - - Marine (X Band, 9225 MHz, 30 kW): Parameters are solid for a coastal surveillance radar. Horizontal beam of 0.5° is - tight and realistic for a 15-foot slotted waveguide antenna at that frequency. The 50-foot antenna height is important - for the radar horizon calculation — with a 50-foot antenna and a target at sea level, the radar horizon is roughly 9 - miles, which fits your 6-mile max range well. - - ATC (S Band, 3 GHz, 25 kW): Correct band for terminal area surveillance (ASR-type). The 1.4° horizontal beamwidth from - a 20-foot antenna at S band is consistent. One note: real ASR radars (like ASR-9 at airports like BLI) typically run - 1.2–1.4 MW peak power, not 25 kW. 25 kW is closer to a gap-filler or small terminal radar. For a museum exhibit this - is fine — just be aware if the radar equation simulation produces unexpectedly short realistic ranges at those power - levels. - - Chain Home (30 MHz, 500 kW, bistatic): Historically accurate. Your Gt formula (G = 30000 / (beamwidth_az × - beamwidth_el) ≈ 7.5 linear) is a standard approximation and appropriate here. The note about resonant scattering is - correct and important: at 30 MHz (λ = 10 meters), aircraft with wingspans of 10–30 meters are in the Mie/resonant - region, not the optical region. RCS can be 2–5× the physical cross section. This is why Chain Home could detect - aircraft that would have been invisible to shorter-wavelength systems. This is a great museum talking point and should - be in the explainer text. For settings.h, you'll want a CHAIN_HOME_RCS_RESONANCE_FACTOR constant. - - PAR (X Band, ~3 cm, 100 kW, 5-meter antenna): At 10 GHz and 5 meters, beamwidth = λ/D ≈ 0.03/5 = 0.006 radians ≈ - 0.34°. That's extremely tight — correct for a precision approach system. The 20° horizontal × 10° vertical scan - coverage is accurate for PAR. The very high gain implied by the 5-meter aperture is what makes PAR work at short range - with high resolution. The simulation of blooming at close range (< 2 miles) will be visually dramatic with 100 kW - into a high-gain antenna. - - --- - 6. DESIGN.md Reference - - The additions file mentions DESIGN.md in the last line. That file does not currently exist in the project layout in - CLAUDE.md. When you're ready to integrate these additions, add DESIGN.md to the root-level file list. - - --- - Summary of Things That Need Resolution Before Coding - - ┌────────────────────────────────────┬───────────────────────────────────────────────────────────┐ - │ Issue │ Action Needed │ - ├────────────────────────────────────┼───────────────────────────────────────────────────────────┤ - │ "Copy in shaders" language │ Clarify as CPU-side SSBO/uniform array │ - ├────────────────────────────────────┼───────────────────────────────────────────────────────────┤ - │ Bloom post-processing │ Add to shader file layout (separate FBO pass) │ - ├────────────────────────────────────┼───────────────────────────────────────────────────────────┤ - │ 24-bit DB field types │ Replace with SQL-standard INTEGER/SMALLINT │ - ├────────────────────────────────────┼───────────────────────────────────────────────────────────┤ - │ DB units (feet vs meters) │ Pick one, document it │ - ├────────────────────────────────────┼───────────────────────────────────────────────────────────┤ - │ need_update as enum │ Simplify to BOOLEAN │ - ├────────────────────────────────────┼───────────────────────────────────────────────────────────┤ - │ GA vs commercial aircraft defaults │ Decide on one or two aircraft defaults │ - ├────────────────────────────────────┼───────────────────────────────────────────────────────────┤ - │ Dear ImGui for DB panel │ Evaluate vs rolling your own with GLFW │ - ├────────────────────────────────────┼───────────────────────────────────────────────────────────┤ - │ DESIGN.md │ Add to file layout in CLAUDE.md │ - ├────────────────────────────────────┼───────────────────────────────────────────────────────────┤ - │ Chain Home RCS resonance factor │ Add to settings.h constant list │ - ├────────────────────────────────────┼───────────────────────────────────────────────────────────┤ - │ ATC power level realism │ Decide if historically accurate power matters for display │ - └────────────────────────────────────┴───────────────────────────────────────────────────────────┘ - -✻ Sautéed for 1m 11s - -──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── -❯ 000 -──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── - -