@motionstudies/core 0.1.0-alpha.23 → 0.1.0-alpha.25

package/air-continents.d.ts

@@ -0,0 +1,63 @@
+/** Geographic continents from the airport reference; EU is not European Union membership. */
+export declare const AIR_CONTINENTS: {
+    readonly AF: 'Africa';
+    readonly AN: 'Antarctica';
+    readonly AS: 'Asia';
+    readonly EU: 'Europe';
+    readonly NA: 'North America';
+    readonly OC: 'Oceania';
+    readonly SA: 'South America';
+};
+export type AirContinent = keyof typeof AIR_CONTINENTS;
+export type AirContinentSource = 'ourairports' | 'override';
+export type AirContinentStatus = 'known' | 'unknown-endpoint' | 'unknown-continent';
+export interface AirContinentLabel {
+    readonly continent: AirContinent | null;
+    readonly status: AirContinentStatus;
+}
+export declare function isAirContinent(value: unknown): value is AirContinent;
+/** Older releases and unobserved endpoints remain explicitly unknown. */
+export declare function classifyAirEndpoint(endpoint?: {
+    readonly continent?: unknown;
+} | null): AirContinentLabel;
+/** Pass the canonical track index, never overlapping playback chunks. Counts are track segments, not flights. */
+export declare function summarizeAirContinents(tracks: Iterable<{
+    readonly origin?: {
+        readonly continent?: unknown;
+    };
+    readonly destination?: {
+        readonly continent?: unknown;
+    };
+}>): {
+    trackSegments: number;
+    origin: {
+        known: number;
+        unknownEndpoint: number;
+        unknownContinent: number;
+        continents: {
+            AF: number;
+            AN: number;
+            AS: number;
+            EU: number;
+            NA: number;
+            OC: number;
+            SA: number;
+        };
+        knownFraction: number | null;
+    };
+    destination: {
+        known: number;
+        unknownEndpoint: number;
+        unknownContinent: number;
+        continents: {
+            AF: number;
+            AN: number;
+            AS: number;
+            EU: number;
+            NA: number;
+            OC: number;
+            SA: number;
+        };
+        knownFraction: number | null;
+    };
+};

package/air-continents.js

@@ -0,0 +1,43 @@
+/** Geographic continents from the airport reference; EU is not European Union membership. */
+export const AIR_CONTINENTS = {
+    AF: 'Africa', AN: 'Antarctica', AS: 'Asia', EU: 'Europe',
+    NA: 'North America', OC: 'Oceania', SA: 'South America',
+};
+export function isAirContinent(value) {
+    return typeof value === 'string' && Object.hasOwn(AIR_CONTINENTS, value);
+}
+/** Older releases and unobserved endpoints remain explicitly unknown. */
+export function classifyAirEndpoint(endpoint) {
+    if (!endpoint)
+        return { continent: null, status: 'unknown-endpoint' };
+    if (!isAirContinent(endpoint.continent))
+        return { continent: null, status: 'unknown-continent' };
+    return { continent: endpoint.continent, status: 'known' };
+}
+/** Pass the canonical track index, never overlapping playback chunks. Counts are track segments, not flights. */
+export function summarizeAirContinents(tracks) {
+    const empty = () => ({
+        known: 0, unknownEndpoint: 0, unknownContinent: 0,
+        continents: { AF: 0, AN: 0, AS: 0, EU: 0, NA: 0, OC: 0, SA: 0 },
+    });
+    const counts = { origin: empty(), destination: empty() };
+    let trackSegments = 0;
+    for (const track of tracks) {
+        trackSegments++;
+        for (const side of ['origin', 'destination']) {
+            const label = classifyAirEndpoint(track[side]), count = counts[side];
+            if (label.continent) {
+                count.known++;
+                count.continents[label.continent]++;
+            }
+            else if (label.status === 'unknown-endpoint')
+                count.unknownEndpoint++;
+            else
+                count.unknownContinent++;
+        }
+    }
+    const coverage = (side) => ({
+        ...counts[side], knownFraction: trackSegments ? counts[side].known / trackSegments : null,
+    });
+    return { trackSegments, origin: coverage('origin'), destination: coverage('destination') };
+}

package/domain/air.d.ts

@@ -1,3 +1,4 @@
+import type { AirContinent, AirContinentSource } from '../air-continents.ts';
 export type AirSample = readonly [
     time: number,
     longitude: number,
@@ -13,6 +14,9 @@ export interface AirEndpoint {
     /** Study-local seconds at the observed approach/departure boundary; not a scheduled time. */
     readonly time: number;
     readonly evidence: 'observed-endpoint';
+    /** Airport geography, separate from the inferred route evidence. Absent in older releases. */
+    readonly continent?: AirContinent;
+    readonly continentSource?: AirContinentSource;
 }
 export interface AirTrack {
     readonly id: string;

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.23",
+  "version": "0.1.0-alpha.25",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -20,6 +20,11 @@
     "tag": "next"
   },
   "exports": {
+    "./air-continents": {
+      "types": "./air-continents.d.ts",
+      "import": "./air-continents.js",
+      "default": "./air-continents.js"
+    },
     "./air-search": {
       "types": "./air-search.d.ts",
       "import": "./air-search.js",
@@ -219,6 +224,11 @@
       "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"
     }
   },
   "files": [