@aeroswarm/live-server 0.1.1 → 0.1.2

package/README.md

@@ -75,6 +75,64 @@ wss.on("connection", (ws, req) => {
 });
 ```
 
+## Several sensors, one aircraft (fusion)
+
+Radar, MLAT and ADS-B often see the same aircraft. Each feed makes its own
+track id, and `TrackState` replaces a track whenever another id arrives for the
+same `icao24`, so two feeds knock each other out on every update. Put the fuser
+between the feeds and `state.ingest`:
+
+```ts
+import { createTrackFuser } from "@aeroswarm/live-server";
+
+const fuser = createTrackFuser();            // or createTrackFuser({ spatial: true, ... })
+
+trackSource.start((ev) => {
+  if (ev.kind !== "track") return;
+  const fused = fuser.ingest(ev.event as FusedTrackEvent);   // null = nothing new to show
+  if (fused) { persist(fused); state.ingest(fused); }
+});
+state.on("removed", ({ trackId }) => fuser.forget(trackId));
+setInterval(() => fuser.sweep(), 30_000);    // forget sensors that went silent
+```
+
+What you get: one canonical `trackId` per aircraft, `sources` listing every
+contributing sensor (`lifecycle: "merged"`), and the position of the preferred
+sensor. A sensor that lets go of the track (`lifecycle: "dropped"`) does not
+remove the aircraft while another sensor still sees it. With one sensor the
+output is the same as without the fuser, with a stable track id.
+
+**Matching.** By Mode-S address (`icao24`). Targets without one (surface
+vehicles, SSR-only radar) get a synthetic id from sensor + track number
+(`r50-176-42`), which means nothing to another sensor; they are only joined when
+`spatial` is on, by distance and time. A candidate that is ambiguous (more than
+one), or that carries a different Mode-S address, is never merged.
+
+**Which sensor's position is shown.** The first match in the priority list for
+the current state, where "on the ground" means some fresh report says
+`onGround`. Entries are a protocol (`asterix-cat010`) or a feed's source id.
+The default prefers MLAT in both lists, then ADS-B, the system track and radar.
+A sensor silent for `maxSourceAgeMs` stops competing.
+
+| Option | Default | |
+|---|---|---|
+| `surfacePriority` | MLAT (CAT010/011/020), CAT021, CAT062, CAT048 | best first |
+| `airbornePriority` | MLAT (CAT020/010/011), CAT021, CAT062, CAT048 | best first |
+| `maxSourceAgeMs` | `5000` | silent sensor stops competing |
+| `forgetAfterMs` | `600000` | sensor forgotten after this long silent |
+| `spatial` | `false` | also match tracks that share no Mode-S address |
+| `matchRadiusM` | `150` | spatial matching: distance |
+| `matchMaxSkewMs` | `3000` | spatial matching: time difference |
+| `disagreeM` | `300` | sensors further apart are counted as disagreeing |
+| `now` | `Date.now` | clock, for tests |
+
+`fuser.stats()` returns `{ aircraft, merged, spatialMatches, ambiguous,
+disagreements }`. `confidence.sourceAgreement` on a merged track falls from 1 to
+0 as its sensors drift apart.
+
+Fusion applies to what the host feeds it: events that arrive some other way
+(HTTP, Kafka) are not fused unless the host passes them through `ingest` too.
+
 ## Protocol
 
 JSON envelopes `{ type, seq, serverTime, payload }`, `seq` strictly increasing across the server.

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { CurrentTrack, FusedTrackEvent, FlightPlan, FlightPlanEvent } from '@aeroswarm/core/types';
+import { FusedTrackEvent as FusedTrackEvent$1 } from '@aeroswarm/core';
 
 /** Minimal socket surface. Satisfied by Bun's `ServerWebSocket` and the `ws` library. */
 interface LiveSocket {
@@ -189,6 +190,70 @@ declare class MovementDetector {
 }
 declare function createMovementDetector(): MovementDetector;
 
+/**
+ * Several sensors (radar, MLAT, ...) often see the same aircraft. Each feed
+ * produces its own track id, so without this layer they replace one another
+ * on every update. The fuser keeps ONE canonical track per aircraft and picks
+ * which sensor's position to show.
+ *
+ *   feed events ──► fuser.ingest ──► one event per aircraft ──► storage, live picture
+ *
+ * Matching: by Mode-S address when both have one. Tracks without it (surface
+ * vehicles, SSR-only radar: ids like "r50-176-42") only match across sensors
+ * when `spatial` is on, by position and time.
+ */
+interface FusionOptions {
+    /** Preferred sources while the aircraft is on the ground, best first. Each entry is a protocol ("asterix-cat010") or a source id. */
+    surfacePriority: string[];
+    /** Same, for an aircraft in the air. */
+    airbornePriority: string[];
+    /** A sensor silent for longer than this stops competing for the position. */
+    maxSourceAgeMs: number;
+    /** A sensor's contribution is forgotten after this long without an update. */
+    forgetAfterMs: number;
+    /** Also match tracks that share no Mode-S address, by distance and time. */
+    spatial: boolean;
+    matchRadiusM: number;
+    matchMaxSkewMs: number;
+    /** Two sensors further apart than this are reported as disagreeing. */
+    disagreeM: number;
+    now?: () => number;
+}
+/** MLAT first (CAT010 surface, CAT020 wide-area), then ADS-B, the system track, radar. */
+declare const DEFAULT_SURFACE_PRIORITY: readonly string[];
+/** MLAT is preferred in the air too. Put "asterix-cat062"/"asterix-cat048" first to prefer radar. */
+declare const DEFAULT_AIRBORNE_PRIORITY: readonly string[];
+/** Every option, with the defaults a host gets when it passes none. */
+declare function defaultFusionOptions(): FusionOptions;
+interface FusionStats {
+    /** Canonical tracks held. */
+    aircraft: number;
+    /** Of those, how many are fed by more than one sensor right now. */
+    merged: number;
+    /** Tracks joined by position because they shared no id. */
+    spatialMatches: number;
+    /** New tracks with several possible partners, left unmerged. */
+    ambiguous: number;
+    /** Emitted updates where the sensors were further apart than `disagreeM`. */
+    disagreements: number;
+}
+interface TrackFuser {
+    /** The event to store and show, or null when it adds nothing new. */
+    ingest(event: FusedTrackEvent$1): FusedTrackEvent$1 | null;
+    /** Forget a canonical track, e.g. when the live picture removed it. */
+    forget(trackId: string): void;
+    /** Drop sensors that went silent and tracks with none left. */
+    sweep(): void;
+    stats(): FusionStats;
+}
+/** Ids the ingest package builds from sensor + track number when there is no Mode-S address. */
+declare const isSyntheticId: (icao24: string) => boolean;
+/**
+ * Options not given (or `undefined`) take their defaults, so a host passes only
+ * what it wants to change: `createTrackFuser({ spatial: true })`.
+ */
+declare function createTrackFuser(options?: Partial<FusionOptions>): TrackFuser;
+
 /** Result of `authenticate`. `airportId` pins the connection to that airport
  *  (a sensor token); leave it undefined for viewer tokens that may request any. */
 interface LiveAuth {
@@ -233,4 +298,4 @@ interface LiveServer {
 }
 declare function createLiveServer(opts: LiveServerOptions): LiveServer;
 
-export { type Bbox, type FlightPlanFilter, FlightPlanStore, type FlightPlanStoreOptions, type LiveAuth, type LiveMessage, type LiveOpenContext, type LiveServer, type LiveServerOptions, type LiveServerStats, type LiveSocket, type Logger, MovementDetector, type MovementEvent, type MovementSample, type MovementType, type RemoveReason, type RemovedListener, type TrackFilter, type TrackListener, TrackState, type TrackStateOptions, type UpdateInfo, createFlightPlanStore, createLiveServer, createMovementDetector, createTrackState };
+export { type Bbox, DEFAULT_AIRBORNE_PRIORITY, DEFAULT_SURFACE_PRIORITY, type FlightPlanFilter, FlightPlanStore, type FlightPlanStoreOptions, type FusionOptions, type FusionStats, type LiveAuth, type LiveMessage, type LiveOpenContext, type LiveServer, type LiveServerOptions, type LiveServerStats, type LiveSocket, type Logger, MovementDetector, type MovementEvent, type MovementSample, type MovementType, type RemoveReason, type RemovedListener, type TrackFilter, type TrackFuser, type TrackListener, TrackState, type TrackStateOptions, type UpdateInfo, createFlightPlanStore, createLiveServer, createMovementDetector, createTrackFuser, createTrackState, defaultFusionOptions, isSyntheticId };

package/dist/index.js

@@ -567,6 +567,245 @@ function createMovementDetector() {
   return new MovementDetector();
 }
 
+// src/fusion.ts
+var DEFAULT_SURFACE_PRIORITY = [
+  "asterix-cat010",
+  "asterix-cat011",
+  "asterix-cat020",
+  "asterix-cat021",
+  "asterix-cat062",
+  "asterix-cat048"
+];
+var DEFAULT_AIRBORNE_PRIORITY = [
+  "asterix-cat020",
+  "asterix-cat010",
+  "asterix-cat011",
+  "asterix-cat021",
+  "asterix-cat062",
+  "asterix-cat048"
+];
+function defaultFusionOptions() {
+  return {
+    surfacePriority: [...DEFAULT_SURFACE_PRIORITY],
+    airbornePriority: [...DEFAULT_AIRBORNE_PRIORITY],
+    maxSourceAgeMs: 5e3,
+    forgetAfterMs: 6e5,
+    spatial: false,
+    matchRadiusM: 150,
+    matchMaxSkewMs: 3e3,
+    disagreeM: 300
+  };
+}
+var SYNTHETIC_ID = /^[rtv]\d+-\d+-\d+$/;
+var EARTH_M = 6371e3;
+var isSyntheticId = (icao24) => SYNTHETIC_ID.test(icao24);
+function distanceM(a, b) {
+  const rad = Math.PI / 180;
+  const dLat = (b.lat - a.lat) * rad;
+  const dLon = (b.lon - a.lon) * rad;
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(a.lat * rad) * Math.cos(b.lat * rad) * Math.sin(dLon / 2) ** 2;
+  return 2 * EARTH_M * Math.asin(Math.min(1, Math.sqrt(h)));
+}
+var sourceOf = (event) => event.sources[0];
+var keyFor = (event) => {
+  const icao24 = event.identity.icao24;
+  return isSyntheticId(icao24) ? `s:${sourceOf(event)}:${icao24}` : `m:${icao24}`;
+};
+function rank(list, event) {
+  const idx = list.findIndex(
+    (s) => s === event.protocol || s === sourceOf(event)
+  );
+  return idx < 0 ? list.length : idx;
+}
+function pickPrimary(fresh, list) {
+  const sorted = [...fresh].sort(
+    (a, b) => rank(list, a.event) - rank(list, b.event) || b.at - a.at
+  );
+  return sorted[0] ?? null;
+}
+function mergeIdentity(primary, others) {
+  const out = { ...primary.event.identity };
+  for (const other of others) {
+    const id = other.event.identity;
+    out.callsign ??= id.callsign;
+    out.squawk ??= id.squawk;
+    out.targetType ??= id.targetType;
+    out.vehicleFleet ??= id.vehicleFleet;
+    if (isSyntheticId(out.icao24) && !isSyntheticId(id.icao24)) {
+      out.icao24 = id.icao24;
+    }
+  }
+  return out;
+}
+function maxSpreadM(primary, others) {
+  const base = primary.event.position;
+  if (!base) return 0;
+  let max = 0;
+  for (const other of others) {
+    const pos = other.event.position;
+    if (pos) max = Math.max(max, distanceM(base, pos));
+  }
+  return max;
+}
+var Fuser = class {
+  opts;
+  now;
+  byKey = /* @__PURE__ */ new Map();
+  byId = /* @__PURE__ */ new Map();
+  spatialMatches = 0;
+  ambiguous = 0;
+  disagreements = 0;
+  constructor(opts) {
+    this.opts = opts;
+    this.now = opts.now ?? (() => Date.now());
+  }
+  ingest(event) {
+    const now = this.now();
+    const src = sourceOf(event);
+    const key = keyFor(event);
+    const known = this.byKey.get(key);
+    if (event.lifecycle === "dropped") return this.drop(known, event, src, now);
+    const entry = known ?? this.matchSpatially(event, src, now) ?? this.create(event);
+    this.link(entry, key, event);
+    entry.contributions.set(src, { event, sourceId: src, at: now });
+    return this.output(entry, src, now, false);
+  }
+  forget(trackId) {
+    const entry = this.byId.get(trackId);
+    if (entry) this.remove(entry);
+  }
+  sweep() {
+    const now = this.now();
+    for (const entry of [...this.byId.values()]) {
+      for (const [src, c] of entry.contributions) {
+        if (now - c.at > this.opts.forgetAfterMs)
+          entry.contributions.delete(src);
+      }
+      if (entry.contributions.size === 0) this.remove(entry);
+    }
+  }
+  stats() {
+    const now = this.now();
+    let merged = 0;
+    for (const entry of this.byId.values()) {
+      if (this.fresh(entry, now).length > 1) merged++;
+    }
+    return {
+      aircraft: this.byId.size,
+      merged,
+      spatialMatches: this.spatialMatches,
+      ambiguous: this.ambiguous,
+      disagreements: this.disagreements
+    };
+  }
+  fresh(entry, now) {
+    return [...entry.contributions.values()].filter(
+      (c) => now - c.at <= this.opts.maxSourceAgeMs
+    );
+  }
+  create(event) {
+    const entry = {
+      id: event.trackId,
+      keys: /* @__PURE__ */ new Set(),
+      contributions: /* @__PURE__ */ new Map(),
+      realIcao24: null,
+      lastPrimary: "",
+      lastSources: ""
+    };
+    this.byId.set(entry.id, entry);
+    return entry;
+  }
+  link(entry, key, event) {
+    entry.keys.add(key);
+    this.byKey.set(key, entry);
+    if (!isSyntheticId(event.identity.icao24)) {
+      entry.realIcao24 = event.identity.icao24;
+    }
+  }
+  remove(entry) {
+    for (const key of entry.keys) this.byKey.delete(key);
+    this.byId.delete(entry.id);
+  }
+  drop(entry, event, src, now) {
+    if (!entry) return event;
+    entry.contributions.delete(src);
+    if (entry.contributions.size > 0) return this.output(entry, src, now, true);
+    this.remove(entry);
+    return { ...event, trackId: entry.id };
+  }
+  /** The partner for a track nobody else shares an id with, or null. */
+  matchSpatially(event, src, now) {
+    const pos = event.position;
+    if (!this.opts.spatial || !pos) return null;
+    const hasMode = !isSyntheticId(event.identity.icao24);
+    const found = [];
+    for (const entry of this.byId.values()) {
+      if (entry.contributions.has(src) || hasMode && entry.realIcao24)
+        continue;
+      if (this.isNear(entry, pos, now)) found.push(entry);
+    }
+    if (found.length > 1) this.ambiguous++;
+    if (found.length !== 1) return null;
+    this.spatialMatches++;
+    return found[0] ?? null;
+  }
+  isNear(entry, pos, now) {
+    for (const c of entry.contributions.values()) {
+      const other = c.event.position;
+      if (!other || now - c.at > this.opts.matchMaxSkewMs) continue;
+      if (distanceM(pos, other) <= this.opts.matchRadiusM) return true;
+    }
+    return false;
+  }
+  /**
+   * The event for the aircraft as it stands now. Null when `src` is not the
+   * sensor being shown and nothing else changed, so a lower-priority sensor
+   * does not make the picture jump.
+   */
+  output(entry, src, now, force) {
+    const fresh = this.fresh(entry, now);
+    const onGround = fresh.some((c) => c.event.position?.onGround === true);
+    const list = onGround ? this.opts.surfacePriority : this.opts.airbornePriority;
+    const primary = pickPrimary(fresh, list);
+    if (!primary) return null;
+    const sources = fresh.map((c) => c.sourceId).sort().join(",");
+    const changed = force || primary.sourceId === src || primary.sourceId !== entry.lastPrimary || sources !== entry.lastSources;
+    entry.lastPrimary = primary.sourceId;
+    entry.lastSources = sources;
+    return changed ? this.build(entry, primary, fresh) : null;
+  }
+  build(entry, primary, fresh) {
+    const others = fresh.filter((c) => c !== primary).sort((a, b) => b.at - a.at);
+    const { event } = primary;
+    const out = {
+      ...event,
+      trackId: entry.id,
+      sources: [primary.sourceId, ...others.map((c) => c.sourceId)],
+      identity: mergeIdentity(primary, others),
+      lifecycle: others.length > 0 ? "merged" : event.lifecycle
+    };
+    const velocity = event.velocity ?? others.find((c) => c.event.velocity)?.event.velocity;
+    if (velocity) out.velocity = velocity;
+    if (others.length > 0) this.scoreAgreement(out, primary, others);
+    return out;
+  }
+  scoreAgreement(out, primary, others) {
+    const spread = maxSpreadM(primary, others);
+    if (spread > this.opts.disagreeM) this.disagreements++;
+    out.confidence = {
+      ...out.confidence,
+      sourceAgreement: Math.max(0, 1 - spread / this.opts.disagreeM)
+    };
+  }
+};
+function createTrackFuser(options = {}) {
+  const base = defaultFusionOptions();
+  const given = Object.fromEntries(
+    Object.entries(options).filter(([, v]) => v !== void 0)
+  );
+  return new Fuser({ ...base, ...given });
+}
+
 // ../core/dist/chunk-ZYX6U3ZK.js
 import { z } from "zod";
 var positionSchema = z.object({
@@ -919,11 +1158,16 @@ function createLiveServer(opts) {
   };
 }
 export {
+  DEFAULT_AIRBORNE_PRIORITY,
+  DEFAULT_SURFACE_PRIORITY,
   FlightPlanStore,
   MovementDetector,
   TrackState,
   createFlightPlanStore,
   createLiveServer,
   createMovementDetector,
-  createTrackState
+  createTrackFuser,
+  createTrackState,
+  defaultFusionOptions,
+  isSyntheticId
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeroswarm/live-server",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",