@motionstudies/core 0.1.0-alpha.24 → 0.1.0-alpha.26

package/air-enrichment.d.ts

@@ -0,0 +1,63 @@
+import { type AirContinent } from './air-continents.ts';
+import type { AirSearchTrack } from './air-search.ts';
+export type EndpointSide = 'origin' | 'destination';
+export type EndpointEvidence = 'observed' | 'corroborated' | 'candidate' | 'conflicting' | 'unknown';
+export interface EnrichmentAirport {
+    icao: string;
+    iata: string;
+    name: string;
+    continent: AirContinent | null;
+}
+export interface EnrichmentSource {
+    id: string;
+    kind: 'airport-reference' | 'route-reference' | 'association-audit';
+    url: string;
+    sha256: string;
+    license: string;
+}
+export interface EndpointProposal {
+    trackId: string;
+    callsign: string;
+    aircraft: string;
+    side: EndpointSide;
+    airport: string;
+    anchor: string;
+    status: 'corroborated' | 'candidate' | 'conflicting';
+    sourceIds: string[];
+    reasons: string[];
+}
+/** Sidecar metadata only. Proposed endpoints deliberately have no playback or event time. */
+export interface AirEnrichment {
+    kind: 'air-endpoint-enrichment';
+    schemaVersion: 1;
+    date: string;
+    sourceManifestSha256: string;
+    airports: EnrichmentAirport[];
+    sources: EnrichmentSource[];
+    proposals: EndpointProposal[];
+}
+export interface EndpointLabel {
+    status: EndpointEvidence;
+    airport?: EnrichmentAirport;
+    sourceIds: readonly string[];
+    reasons: readonly string[];
+}
+/** Reject wrong-day, foreign-track, duplicate, stale-anchor and observed-overwrite metadata. */
+export declare function readAirEnrichment(value: unknown, binding: {
+    date: string;
+    sourceManifestSha256: string;
+    tracks: readonly AirSearchTrack[];
+}): AirEnrichment;
+export declare function createEndpointResolver(enrichment: AirEnrichment): (track: AirSearchTrack, side: EndpointSide) => EndpointLabel;
+export declare function usableEndpoint(label: EndpointLabel, includeCandidates?: boolean): boolean;
+export declare function endpointCoverage(tracks: readonly AirSearchTrack[], resolve: ReturnType<typeof createEndpointResolver>, side: EndpointSide, includeCandidates?: boolean): {
+    observed: number;
+    corroborated: number;
+    candidate: number;
+    conflicting: number;
+    unknown: number;
+    segments: number;
+    usable: number;
+    unresolved: number;
+    continentKnown: number;
+};

package/air-enrichment.js

@@ -0,0 +1,76 @@
+import { isAirContinent } from './air-continents.js';
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const text = (v) => typeof v === 'string' && v.length > 0;
+const hash = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const side = (v) => v === 'origin' || v === 'destination';
+/** Reject wrong-day, foreign-track, duplicate, stale-anchor and observed-overwrite metadata. */
+export function readAirEnrichment(value, binding) {
+    const fail = () => { throw Error('Invalid or mismatched endpoint enrichment'); };
+    if (!object(value) || value.kind !== 'air-endpoint-enrichment' || value.schemaVersion !== 1 || value.date !== binding.date
+        || !hash(value.sourceManifestSha256) || value.sourceManifestSha256 !== binding.sourceManifestSha256
+        || !Array.isArray(value.airports) || !Array.isArray(value.sources) || !Array.isArray(value.proposals))
+        return fail();
+    const airports = new Set(), sources = new Map(), proposals = new Set();
+    for (const a of value.airports) {
+        if (!object(a) || !text(a.icao) || typeof a.iata !== 'string' || !text(a.name) || (a.continent !== null && !isAirContinent(a.continent)) || airports.has(a.icao))
+            return fail();
+        airports.add(a.icao);
+    }
+    for (const s of value.sources) {
+        if (!object(s) || !text(s.id) || sources.has(s.id) || !text(s.url) || !hash(s.sha256) || !text(s.license)
+            || !['airport-reference', 'route-reference', 'association-audit'].includes(String(s.kind)))
+            return fail();
+        // Links are either public HTTPS sources or simple sibling report files.
+        if (!/^https:\/\/[^\s]+$/.test(s.url) && !/^reports\/[a-zA-Z0-9._-]+\.json$/.test(s.url))
+            return fail();
+        sources.set(s.id, String(s.kind));
+    }
+    const tracks = new Map(binding.tracks.map(t => [t.id, t]));
+    for (const p of value.proposals) {
+        if (!object(p) || !text(p.trackId) || !side(p.side) || !text(p.airport) || !airports.has(p.airport)
+            || !['corroborated', 'candidate', 'conflicting'].includes(String(p.status)) || !Array.isArray(p.sourceIds) || !p.sourceIds.length
+            || !p.sourceIds.every(s => typeof s === 'string' && sources.has(s)) || !Array.isArray(p.reasons) || !p.reasons.every(text))
+            return fail();
+        const t = tracks.get(p.trackId), key = `${p.trackId}:${p.side}`, opposite = p.side === 'origin' ? 'destination' : 'origin';
+        if (!t || t[p.side] || t[opposite]?.icao !== p.anchor || t.callsign !== p.callsign || t.icaoAddress !== p.aircraft || proposals.has(key))
+            return fail();
+        if (!p.sourceIds.some(s => sources.get(s) === 'route-reference')
+            || (p.status !== 'candidate' && !p.sourceIds.some(s => sources.get(s) === 'association-audit'))
+            || (p.status === 'corroborated' && p.reasons.length))
+            return fail();
+        proposals.add(key);
+    }
+    return value;
+}
+export function createEndpointResolver(enrichment) {
+    const airports = new Map(enrichment.airports.map(a => [a.icao, a]));
+    const proposals = new Map(enrichment.proposals.map(p => [`${p.trackId}:${p.side}`, p]));
+    const referenceIds = enrichment.sources.filter(s => s.kind === 'airport-reference').map(s => s.id);
+    return (track, side) => {
+        const observed = track[side];
+        if (observed)
+            return { status: 'observed', airport: { icao: observed.icao, iata: observed.iata, name: observed.name,
+                    continent: isAirContinent(observed.continent) ? observed.continent : airports.get(observed.icao)?.continent ?? null }, sourceIds: referenceIds, reasons: [] };
+        const p = proposals.get(`${track.id}:${side}`);
+        if (!p)
+            return { status: 'unknown', sourceIds: [], reasons: [] };
+        return { status: p.status, airport: airports.get(p.airport), sourceIds: p.sourceIds, reasons: p.reasons };
+    };
+}
+export function usableEndpoint(label, includeCandidates = false) {
+    return label.status === 'observed' || label.status === 'corroborated' || (includeCandidates && label.status === 'candidate');
+}
+export function endpointCoverage(tracks, resolve, side, includeCandidates = false) {
+    const counts = { observed: 0, corroborated: 0, candidate: 0, conflicting: 0, unknown: 0 };
+    let usable = 0, continentKnown = 0;
+    for (const t of tracks) {
+        const label = resolve(t, side);
+        counts[label.status]++;
+        if (usableEndpoint(label, includeCandidates)) {
+            usable++;
+            if (label.airport?.continent)
+                continentKnown++;
+        }
+    }
+    return { segments: tracks.length, ...counts, usable, unresolved: tracks.length - usable, continentKnown };
+}

package/map-labels.d.ts

@@ -0,0 +1,24 @@
+/** Renderer-independent hierarchy shared by station and airport map labels. */
+export interface MapLabelPriority {
+    readonly name: string;
+    readonly rank: number;
+    readonly priority: number;
+    readonly retained: boolean;
+    readonly distance: number;
+}
+export interface MapLabelBox {
+    readonly left: number;
+    readonly right: number;
+    readonly top: number;
+    readonly bottom: number;
+}
+export interface MapLabelCandidate extends MapLabelPriority {
+    readonly box: MapLabelBox;
+}
+export declare function compareMapLabelCandidates(first: MapLabelPriority, second: MapLabelPriority): number;
+export declare function mapLabelBudget(cameraHeight: number): number;
+export declare function mapLabelRankLimit(cameraHeight: number): number;
+export declare function mapLabelBoxesOverlap(box: MapLabelBox, other: MapLabelBox, horizontalGap?: number, verticalGap?: number): boolean;
+/** Candidate boxes include the edition's full hit area. Selected candidates must
+ * already have their higher priority; all labels respect viewport and obstacles. */
+export declare function selectMapLabels<T extends MapLabelCandidate>(candidates: readonly T[], budget: number, viewport: MapLabelBox, obstacles?: readonly MapLabelBox[]): T[];

package/map-labels.js

@@ -0,0 +1,48 @@
+export function compareMapLabelCandidates(first, second) {
+    return first.priority - second.priority || Number(second.retained) - Number(first.retained)
+        || first.rank - second.rank || first.distance - second.distance || first.name.localeCompare(second.name, 'de-CH');
+}
+export function mapLabelBudget(cameraHeight) {
+    if (cameraHeight >= 30)
+        return 8;
+    if (cameraHeight >= 22)
+        return 20;
+    if (cameraHeight >= 15)
+        return 48;
+    return 96;
+}
+export function mapLabelRankLimit(cameraHeight) {
+    if (cameraHeight >= 30)
+        return 8;
+    if (cameraHeight >= 22)
+        return 20;
+    if (cameraHeight >= 15)
+        return 48;
+    if (cameraHeight >= 14)
+        return 96;
+    return Number.POSITIVE_INFINITY;
+}
+export function mapLabelBoxesOverlap(box, other, horizontalGap = 5, verticalGap = 4) {
+    return box.left < other.right + horizontalGap && box.right > other.left - horizontalGap
+        && box.top < other.bottom + verticalGap && box.bottom > other.top - verticalGap;
+}
+/** Candidate boxes include the edition's full hit area. Selected candidates must
+ * already have their higher priority; all labels respect viewport and obstacles. */
+export function selectMapLabels(candidates, budget, viewport, obstacles = []) {
+    const selected = [], occupied = [...obstacles];
+    const limit = Number.isFinite(budget) ? Math.max(0, Math.floor(budget)) : 0;
+    for (const candidate of [...candidates].sort(compareMapLabelCandidates)) {
+        if (selected.length >= limit)
+            break;
+        const box = candidate.box;
+        if (![box.left, box.right, box.top, box.bottom].every(Number.isFinite) || box.right <= box.left || box.bottom <= box.top)
+            continue;
+        if (box.left < viewport.left || box.right > viewport.right || box.top < viewport.top || box.bottom > viewport.bottom)
+            continue;
+        if (occupied.some(other => mapLabelBoxesOverlap(box, other)))
+            continue;
+        selected.push(candidate);
+        occupied.push(box);
+    }
+    return selected;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.26",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -224,6 +224,16 @@
       "types": "./render-frame.d.ts",
       "import": "./render-frame.js",
       "default": "./render-frame.js"
+    },
+    "./map-labels": {
+      "types": "./map-labels.d.ts",
+      "import": "./map-labels.js",
+      "default": "./map-labels.js"
+    },
+    "./air-enrichment": {
+      "types": "./air-enrichment.d.ts",
+      "import": "./air-enrichment.js",
+      "default": "./air-enrichment.js"
     }
   },
   "files": [