From 70f317a90b68270aa9e931774db7e62ed8797795 Mon Sep 17 00:00:00 2001
From: Mark Allyn <allyn@well.com>
Date: Sun, 17 May 2026 20:31:28 -0700
Subject: [PATCH] add target information

---
 CLAUDE.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 9526fdc..0b3815d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -101,6 +101,83 @@ the visitor sees is done by pressing a forward control and a reverse control to
 the loop of scopes. The first display when the system is turned on or booted up is the 
 Introduction of the exhibit.
 
+Before going, we must point out the target information handling which will
+affect all scopes.
+
+====================================================================================
+
+TARGET DETAILS
+
+Targets for this project will come from two sources:
+
+1. Raspberry pis communicating with an AIS receiver for boats and
+   an ADS-b receiver for aircraft
+2. An on-board simulator that will simulate targets using an internal
+   table of target information in the postgresql database.
+
+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.
+
+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:
+
+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
+   float length; // in meters
+   float beam; // in meters
+   int vessel_type; // AIS type code or aircraft type
+   uint32_t mmsi; // AIS unique identifier; ICAO hex address for aircraft
+   float course; // course over ground, degrees, based on true north
+   float speed; // speed over ground, knots
+   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.
+
+struct target_data_to_shader_structure {
+  double target_longitude;
+  double target_latitude;
+  float length;
+  float beam;
+  float course;
+  float altitude;
+  time_t timestamp;
+  };
+
+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.
+
+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.
+
+Note that the construction of the simulator will be discussed later in this document.
+
+=============================================================================
+
 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.