Merge pull request #71 from MrSuttonmann/silhouette-fallback-chain

Extend silhouette lookup with tar1090's full fallback chain

Author: MrSuttonmann

.github/workflows/ci.yml

@@ -130,6 +130,7 @@ jobs:
         # a complete page. Python interpreter is preinstalled on GitHub runners.
         env:
           TAR1090_SHAPES_DEST: ${{ github.workspace }}/app/static/tar1090_shapes.js
+          TAR1090_TYPES_DEST: ${{ github.workspace }}/app/static/icao_aircraft_types.js
         run: python3 scripts/fetch_plane_shapes.py
 
       - name: Publish backend for Playwright

.gitignore

@@ -42,6 +42,7 @@ app/aircraft_db.csv.gz
 app/airports.csv
 app/navaids.csv
 app/static/tar1090_shapes.js
+app/static/icao_aircraft_types.js
 
 # Editors / OS
 .vscode/

app/static/detail_panel.js

@@ -884,7 +884,8 @@ export function openDetailPanel(icao) {
   if (entry) {
     entry.marker.setIcon(
       planeIcon(a.track, altColor(a.altitude), true, !!a.emergency,
-        !!a.position_source && a.position_source !== 'adsb', a.type_icao),
+        !!a.position_source && a.position_source !== 'adsb',
+        a.type_icao, a.category, a.category_set),
     );
   }
   document.querySelectorAll('.ac-item').forEach(el => {
@@ -924,7 +925,8 @@ export function closeDetailPanel() {
       const a = entry.data;
       entry.marker.setIcon(
         planeIcon(a.track, altColor(a.altitude), false, !!a.emergency,
-          !!a.position_source && a.position_source !== 'adsb', a.type_icao),
+          !!a.position_source && a.position_source !== 'adsb',
+          a.type_icao, a.category, a.category_set),
       );
     }
   }

app/static/icons.js

@@ -1,25 +1,45 @@
-// Marker icon rendering. Prefers tar1090's per-type silhouette when the
-// bundle is loaded and the aircraft's ICAO type code has a match;
-// otherwise falls back to a generic triangular arrow.
+// Marker icon rendering. Prefers tar1090's per-type silhouette via the
+// four-tier fallback in `resolveSilhouette` (designator → description →
+// category); falls back to a generic triangular arrow when none match
+// or the bundles haven't loaded yet.
 //
-// tar1090_shapes.js is loaded asynchronously (it's a big static file
-// and failing to fetch it shouldn't stop the app from running). Until
-// it resolves we render the generic arrow for everyone; once it does,
-// subsequent planeIcon() calls light up.
+// tar1090_shapes.js and icao_aircraft_types.js are loaded asynchronously
+// (they're big static files and failing to fetch them shouldn't stop the
+// app from running). Until they resolve we render the generic arrow for
+// everyone; once they do, subsequent planeIcon() calls light up.
+
+import { resolveSilhouette } from './silhouette.js';
 
 let tar1090Shapes = null;
 let tar1090TypeIcons = null;
+let tar1090TypeDescIcons = null;
+let tar1090CategoryIcons = null;
+let typeDesignatorMeta = null;
 
 import('./tar1090_shapes.js').then(mod => {
   tar1090Shapes = mod.shapes;
   tar1090TypeIcons = mod.TypeDesignatorIcons;
+  tar1090TypeDescIcons = mod.TypeDescriptionIcons;
+  tar1090CategoryIcons = mod.CategoryIcons;
 }).catch(e => {
   console.warn('tar1090 shapes unavailable — using generic arrow', e);
 });
 
-function tar1090ShapeFor(typeIcao) {
-  if (!tar1090Shapes || !tar1090TypeIcons || !typeIcao) return null;
-  const entry = tar1090TypeIcons[typeIcao.toUpperCase()];
+import('./icao_aircraft_types.js').then(mod => {
+  typeDesignatorMeta = mod.TypeDesignatorMeta;
+}).catch(e => {
+  console.warn('ICAO type metadata unavailable — silhouette fallback narrowed', e);
+});
+
+function tar1090ShapeFor(typeIcao, category, categorySet) {
+  if (!tar1090Shapes) return null;
+  const entry = resolveSilhouette({
+    typeIcao, category, categorySet,
+    typeDesignatorIcons: tar1090TypeIcons,
+    typeDescriptionIcons: tar1090TypeDescIcons,
+    categoryIcons: tar1090CategoryIcons,
+    typeDesignatorMeta,
+  });
   if (!entry) return null;
   const [shapeName, scaleFactor] = entry;
   const shape = tar1090Shapes[shapeName];
@@ -86,8 +106,8 @@ function tar1090Icon(track, color, selected, emergency, relayed, shape, scaleFac
 const GENERIC_ARROW_PATH = 'M0,-10 L7,8 L0,4 L-7,8 Z';
 const GENERIC_ARROW_SIZE = 26;
 
-export function planeIcon(track, color, selected, emergency, relayed, typeIcao) {
-  const tar = tar1090ShapeFor(typeIcao);
+export function planeIcon(track, color, selected, emergency, relayed, typeIcao, category, categorySet) {
+  const tar = tar1090ShapeFor(typeIcao, category, categorySet);
   if (tar) return tar1090Icon(track, color, selected, emergency, relayed, tar.shape, tar.scaleFactor);
 
   const rot = track == null ? 0 : track;

app/static/silhouette.js

@@ -0,0 +1,58 @@
+// Pure resolver for the tar1090 silhouette fallback chain. Lives apart
+// from icons.js so it can be unit-tested without a Leaflet stub.
+//
+// `resolveSilhouette` mirrors tar1090's getBaseMarker fallback (minus the
+// halloween / ATC-style branches we don't carry). Given an aircraft's
+// type designator, ADS-B category + set letter, and the four lookup
+// tables, returns the [shapeName, scaleFactor] entry that the marker
+// renderer should use, or null when nothing matches and the caller
+// should draw the generic arrow.
+//
+// Tables (all four are optional — pass null when one isn't loaded yet):
+//   - typeDesignatorIcons: map<TYPE, [shape, scale]>            (e.g. "B738")
+//   - typeDescriptionIcons: map<DESC | DESC-WTC | KIND, [shape, scale]>
+//                                                               (e.g. "L1P", "L2J-M", "H")
+//   - categoryIcons:       map<SET+CAT, [shape, scale]>         (e.g. "A1")
+//   - typeDesignatorMeta:  map<TYPE, { desc, wtc }>             (e.g. C172 -> { desc:"L1P", wtc:"L" })
+
+export function resolveSilhouette({
+  typeIcao,
+  category,
+  categorySet,
+  typeDesignatorIcons,
+  typeDescriptionIcons,
+  categoryIcons,
+  typeDesignatorMeta,
+}) {
+  // 1. Most specific: ICAO type designator.
+  if (typeDesignatorIcons && typeIcao) {
+    const entry = typeDesignatorIcons[typeIcao.toUpperCase()];
+    if (entry) return entry;
+  }
+  // 2. ICAO type description ("L1P", "L2J", "H1T", ...) ± wake turbulence.
+  if (typeDescriptionIcons && typeDesignatorMeta && typeIcao) {
+    const meta = typeDesignatorMeta[typeIcao.toUpperCase()];
+    const desc = meta?.desc;
+    const wtc = meta?.wtc;
+    if (desc && desc.length === 3) {
+      if (wtc && wtc.length === 1) {
+        const withWtc = typeDescriptionIcons[`${desc}-${wtc}`];
+        if (withWtc) return withWtc;
+      }
+      const bare = typeDescriptionIcons[desc];
+      if (bare) return bare;
+      const basic = typeDescriptionIcons[desc.charAt(0)];
+      if (basic) return basic;
+    }
+  }
+  // 3. ADS-B emitter category. The set letter ("A"/"B"/"C") came from the
+  // BDS-08 typecode in the backend; default to "A" when the backend
+  // didn't capture it (older snapshots, peer aircraft from a pre-field
+  // build) since A is by far the most common set.
+  if (categoryIcons && category != null && category > 0) {
+    const setLetter = (categorySet || 'A').toString().toUpperCase();
+    const entry = categoryIcons[`${setLetter}${category}`];
+    if (entry) return entry;
+  }
+  return null;
+}

app/static/update_loop.js

@@ -89,10 +89,10 @@ export function update(snap) {
     // Any non-direct source — MLAT / TIS-B / ADS-R — gets the same
     // dashed amber marker. The detail panel chip distinguishes them.
     const isRelayed = a.position_source && a.position_source !== 'adsb';
-    const iconFp = `${altBand}|${isSelected ? 1 : 0}|${a.emergency ? 1 : 0}|${isRelayed ? 1 : 0}|${a.type_icao || ''}`;
+    const iconFp = `${altBand}|${isSelected ? 1 : 0}|${a.emergency ? 1 : 0}|${isRelayed ? 1 : 0}|${a.type_icao || ''}|${a.category || ''}${a.category_set || ''}`;
     let entry = state.aircraft.get(a.icao);
     if (!entry) {
-      const icon = planeIcon(a.track, color, isSelected, !!a.emergency, isRelayed, a.type_icao);
+      const icon = planeIcon(a.track, color, isSelected, !!a.emergency, isRelayed, a.type_icao, a.category, a.category_set);
       const marker = L.marker([a.lat, a.lon], { icon }).addTo(state.map);
       const trail = L.layerGroup().addTo(state.map);
       marker.on('click', () => selectAircraft(a.icao));
@@ -140,7 +140,7 @@ export function update(snap) {
       // updates, rotate the existing element in place.
       if (entry.iconFp !== iconFp) {
         entry.marker.setIcon(
-          planeIcon(a.track, color, isSelected, !!a.emergency, isRelayed, a.type_icao)
+          planeIcon(a.track, color, isSelected, !!a.emergency, isRelayed, a.type_icao, a.category, a.category_set)
         );
         entry.iconFp = iconFp;
         entry.lastTrack = a.track;

dotnet/Dockerfile

@@ -93,6 +93,7 @@ COPY app/static /out/static
 COPY scripts/fetch_plane_shapes.py /tmp/fetch_plane_shapes.py
 RUN echo "data fetch ${DATA_CACHEBUST}" \
  && TAR1090_SHAPES_DEST=/out/static/tar1090_shapes.js \
+    TAR1090_TYPES_DEST=/out/static/icao_aircraft_types.js \
     python3 /tmp/fetch_plane_shapes.py
 
 # esbuild is a standalone Go binary; we pull it straight from npm's

dotnet/src/FlightJar.Api/Hosting/RegistryWorker.cs

@@ -406,6 +406,8 @@ private RegistrySnapshot EnrichSnapshot(RegistrySnapshot snap)
             string? operatorCountry = null;
             string? countryIso = null;
             string? manufacturer = null;
+            string? typeIcao = ac.TypeIcao;
+            string? typeLong = ac.TypeLong;
 
             if (_adsbdb is not null)
             {
@@ -430,6 +432,12 @@ private RegistrySnapshot EnrichSnapshot(RegistrySnapshot snap)
                     operatorCountry = acCached.Data.OperatorCountry;
                     countryIso = acCached.Data.OperatorCountryIso;
                     manufacturer = acCached.Data.Manufacturer;
+                    // Tar1090-db is the primary source for type designator
+                    // because it's the most consistent (uppercase ICAO codes);
+                    // adsbdb fills the gap for tails it doesn't ship — recent
+                    // registrations, GA, military.
+                    typeIcao ??= acCached.Data.IcaoType;
+                    typeLong ??= acCached.Data.Type;
                 }
                 else if (!acCached.Known)
                 {
@@ -480,6 +488,8 @@ private RegistrySnapshot EnrichSnapshot(RegistrySnapshot snap)
 
             aircraft.Add(ac with
             {
+                TypeIcao = typeIcao,
+                TypeLong = typeLong,
                 Origin = origin,
                 Destination = destination,
                 OriginInfo = originInfo,

dotnet/src/FlightJar.Core/State/Aircraft.cs

@@ -12,6 +12,14 @@ public sealed class Aircraft
     public string? Callsign { get; set; }
     public int? Category { get; set; }
 
+    /// <summary>ADS-B emitter category set letter — 'A' / 'B' / 'C' / 'D',
+    /// derived from the BDS-08 typecode that delivered <see cref="Category"/>.
+    /// Pairs with the 3-bit subcategory: e.g. typecode 4 + subcategory 1
+    /// → "A1" (Light). Needed by the frontend silhouette fallback to
+    /// distinguish Set B (gliders, balloons, UAVs) and Set C (surface
+    /// vehicles) from the default Set A.</summary>
+    public char? CategorySet { get; set; }
+
     public double? Lat { get; set; }
     public double? Lon { get; set; }
     public int? AltitudeBaro { get; set; }

dotnet/src/FlightJar.Core/State/AircraftRegistry.cs

@@ -157,6 +157,19 @@ private bool IngestAdsb(DecodedMessage r, double now, long? mlatTicks)
             if (r.Category is int cat)
             {
                 ac.Category = cat;
+                // Typecode 1-4 maps to set D/C/B/A. Set A is "powered
+                // aircraft" (the vast majority of ADS-B traffic); Set B
+                // covers gliders / balloons / UAVs; Set C covers surface
+                // vehicles. The frontend uses the set letter to pick the
+                // right silhouette when no specific designator matches.
+                ac.CategorySet = tc switch
+                {
+                    4 => 'A',
+                    3 => 'B',
+                    2 => 'C',
+                    1 => 'D',
+                    _ => ac.CategorySet,
+                };
             }
         }
         else if (tc >= 5 && tc <= 8)
@@ -623,6 +636,7 @@ public RegistrySnapshot Snapshot(double? now = null)
                 Icao = ac.Icao,
                 Callsign = ac.Callsign,
                 Category = ac.Category,
+                CategorySet = ac.CategorySet?.ToString(),
                 Registration = dbInfo?.Registration,
                 TypeIcao = dbInfo?.TypeIcao,
                 TypeLong = dbInfo?.TypeLong,