Make the fleet models, their handover and the vessel sprites a public entry point

This commit is contained in:
Sameh Khamis committed 2026-11-18 13:12:13 -08:00
1 parent 2a0a3a9b99
commit e19c84bae4
10 files changed
+480 -28

No files matched your search

+6
View File
@@ -0,0 +1,6 @@
- The fleet model set and its loader, the aircraft and vessel model
resolvers, the icon-to-model handover distances, model lighting and part
posing, and the vessel hull sprites are part of the package's public entry
points as `gods-eye-view/fleet`, with declarations, so contacts can be drawn
exactly as the Flights and Vessels layers draw them (Sameh Khamis,
@samehkhamis, #XXXX).
+6 -1
View File
@@ -28,7 +28,12 @@ own `.d.ts`:
- `gods-eye-view/render/recession`: how a set that recedes shrinks and
fades its items toward the limb;
- `gods-eye-view/render/windStreamlines`: the wind field's streamlines;
- `gods-eye-view/geo/screenCluster`: screen-space clustering.
- `gods-eye-view/geo/screenCluster`: screen-space clustering;
- `gods-eye-view/fleet`: fleet contacts as the Flights and Vessels layers
draw them: the fleet model set and its loader, which model and size an
aircraft or a vessel takes, the distances a contact's icon hands over to
its model at, how a model is lit, tinted and posed, and the vessel hull
sprites.
`src/render/neutralExports.test.mjs` checks that each is declared, that its
names match what it exports, that it type-checks under strict TypeScript and
+1
View File
@@ -350,6 +350,7 @@
"./render/weather": "./src/render/weather.js",
"./weather/effects": "./src/weatherEffectsMath.js",
"./geo/screenCluster": "./src/geo/screenCluster.js",
"./fleet": "./src/fleet/index.js",
"./layers/wildlife-sightings": "./src/layers/wildlifeSightings/index.js",
"./layers/wildlife-sightings/source": "./src/layers/wildlifeSightings/source.js"
}
+29
View File
@@ -1890,6 +1890,7 @@
"src/data/vesselTypes.js",
"src/data/fleetTrailAnchors.js",
"src/data/fleetModelInstances.js",
"src/data/fleetModelDraw.js",
"src/data/modelPartDrivers.js",
"src/data/headingDegrees.js",
"src/i18n/marker.js",
@@ -2041,6 +2042,7 @@
"src/data/vesselTypes.js",
"src/data/fleetTrailAnchors.js",
"src/data/fleetModelInstances.js",
"src/data/fleetModelDraw.js",
"src/data/modelPartDrivers.js",
"src/data/headingDegrees.js",
"src/i18n/marker.js",
@@ -2224,6 +2226,7 @@
"src/data/aircraftClass.js",
"src/i18n/marker.js",
"src/data/fleetModelInstances.js",
"src/data/fleetModelDraw.js",
"src/data/modelPartDrivers.js",
"src/data/aircraftModelLighting.js",
"src/data/modelEligibility.js",
@@ -4120,6 +4123,7 @@
"src/render/modelParts.js",
"src/data/fleetTrailAnchors.js",
"src/data/fleetModelInstances.js",
"src/data/fleetModelDraw.js",
"src/app/layers/fleetModels.js",
"src/sources/adsbFields.js",
"src/data/headingDegrees.js",
@@ -5521,6 +5525,7 @@
"src/data/fleetModels.js",
"src/data/fleetTrailAnchors.js",
"src/data/fleetModelInstances.js",
"src/data/fleetModelDraw.js",
"src/app/layers/fleetModels.js",
"src/data/feedState.js",
"src/loadingFeedback.js",
@@ -7262,6 +7267,7 @@
"src/data/aircraftClass.js",
"src/i18n/marker.js",
"src/data/fleetModelInstances.js",
"src/data/fleetModelDraw.js",
"src/data/modelPartDrivers.js",
"src/data/modelEligibility.js",
"src/data/fleetTrailAnchors.js",
@@ -7415,6 +7421,7 @@
"src/render/modelParts.js",
"src/data/vesselTypes.js",
"src/data/fleetModelInstances.js",
"src/data/fleetModelDraw.js",
"src/data/modelPartDrivers.js",
"src/data/aircraftClass.js",
"src/data/aircraftModelLighting.js",
@@ -8192,6 +8199,28 @@
],
"external": []
},
"fleet": {
"exports": ["./fleet"],
"modules": [
"src/fleet/index.js",
"src/data/fleetModels.js",
"src/data/aircraftClass.js",
"src/i18n/marker.js",
"src/render/modelParts.js",
"src/data/fleetTrailAnchors.js",
"src/data/vesselTypes.js",
"src/layers/flights/modelSpec.js",
"src/layers/flights/policy.js",
"src/data/aircraftEmergency.js",
"src/render/color.js",
"src/data/aircraftModelLighting.js",
"src/data/modelPartDrivers.js",
"src/data/modelEligibility.js",
"src/data/fleetModelDraw.js",
"src/data/vesselSprites.js"
],
"external": []
},
"sky": {
"exports": ["./sky"],
"modules": [
+33
View File
@@ -0,0 +1,33 @@
/**
* How a fleet model's draw item is turned, stretched and coloured
* (`fleetModelInstances.js`): pure, no renderer, so it can be read without
* the draw port.
*/
/** Every fleet GLB is nose -X: opposite the draw contract's heading 0. */
export const FLEET_HEADING_OFFSET_DEG = 180;
/**
* A colour as the draw contract takes it: a CSS string or `[r, g, b, a]`
* as given, `{red, green, blue, alpha}` as an array; null for none.
*/
export function fleetColor(color) {
if (color === undefined || color === null) return null;
if (typeof color === 'string' || Array.isArray(color)) return color;
if (typeof color.red === 'number')
return [color.red, color.green, color.blue, color.alpha ?? 1];
return null;
}
/**
* The per-axis stretch a fleet spec draws with on top of its length scale,
* along the model's glTF axes (`x` its length, `y` its height, `z` its
* beam), or undefined when it keeps its proportions.
* @param {object} spec `fleetModelSpec`.
* @returns {[number, number, number]|undefined}
*/
export function fleetAxisScale(spec) {
const [length, beam, height] = spec?.scaleXYZ ?? [];
if (!(length > 0) || (beam === length && height === length)) return;
return [1, height / length, beam / length];
}
+10 -27
View File
@@ -1,4 +1,9 @@
import { selectModelEligible } from './modelEligibility.js';
import {
FLEET_HEADING_OFFSET_DEG,
fleetAxisScale,
fleetColor,
} from './fleetModelDraw.js';
import { AIRCRAFT_ENVIRONMENT_MAP_OPTIONS } from './aircraftModelLighting.js';
import { fleetModelSet, fleetPartTable } from './fleetModels.js';
import { findCamera, findDraw } from '../render/rendererOf.js';
@@ -17,8 +22,11 @@ import {
* and Rail layers share.
*/
/** Every fleet GLB is nose -X: opposite the draw contract's heading 0. */
export const FLEET_HEADING_OFFSET_DEG = 180;
export {
FLEET_HEADING_OFFSET_DEG,
fleetAxisScale,
fleetColor,
} from './fleetModelDraw.js';
/** How long (ms) a model whose load failed waits before it loads again. */
const RETRY_MS = 5000;
@@ -26,31 +34,6 @@ const RETRY_MS = 5000;
/** A white tint: what a model under the NVG/FLIR styles draws with. */
const WHITE = Object.freeze([1, 1, 1, 1]);
/**
* A colour as the draw contract takes it: a CSS string or `[r, g, b, a]`
* as given, `{red, green, blue, alpha}` as an array; null for none.
*/
export function fleetColor(color) {
if (color === undefined || color === null) return null;
if (typeof color === 'string' || Array.isArray(color)) return color;
if (typeof color.red === 'number')
return [color.red, color.green, color.blue, color.alpha ?? 1];
return null;
}
/**
* The per-axis stretch a fleet spec draws with on top of its length scale,
* along the model's glTF axes (`x` its length, `y` its height, `z` its
* beam), or undefined when it keeps its proportions.
* @param {object} spec `fleetModelSpec`.
* @returns {[number, number, number]|undefined}
*/
export function fleetAxisScale(spec) {
const [length, beam, height] = spec?.scaleXYZ ?? [];
if (!(length > 0) || (beam === length && height === length)) return;
return [1, height / length, beam / length];
}
/**
* Whether `point` is inside the eye's view cone (`pose`), a metre's slack.
* @param {object} pose The camera port's pose.
+289
View File
@@ -0,0 +1,289 @@
/**
* Fleet contacts as the Flights and Vessels layers draw them (`index.js`):
* the fleet model set and its loader, model and size resolution, the
* icon-to-model handover distances, model lighting and tint, part-state
* drivers and vessel hull sprites.
*/
import type { Color, ModelPartState } from '../render/contract/index';
import type { PartTable } from '../render/modelParts';
/** A colour as `[r, g, b, a]`, 0..1. */
export type FleetRgba = readonly [number, number, number, number];
/** The loaded fleet model set (`loadFleetModelSet`). */
export interface FleetModelSet {
/** `catalog.json`: each model's file, bounds, length, beam, clearance and icon class. */
readonly catalog: Record<string, FleetCatalogModel>;
/** `types.json`: which model draws which type, and the fallbacks. */
readonly types: FleetTypes;
/** Each model's GLB bytes by name; a model whose GLB did not load is absent. */
readonly bytes: ReadonlyMap<string, Uint8Array>;
readonly loadMs: number;
readonly totalBytes: number;
}
/** One model of `catalog.json`. */
export interface FleetCatalogModel {
readonly file: string;
readonly category: string;
readonly icon?: string;
readonly length: number;
readonly beam?: number;
readonly clearance: number;
readonly min: readonly [number, number, number];
readonly max: readonly [number, number, number];
readonly [key: string]: unknown;
}
/** `types.json`, as the resolvers read it. */
export interface FleetTypes {
readonly [key: string]: unknown;
}
/** A model and the length (metres) it is drawn at; null draws it as built. */
export interface FleetModelChoice {
model: string;
length: number | null;
}
/** The drawing of a fleet model at a size (`fleetModelSpec`). */
export interface FleetModelSpec {
readonly model: string;
readonly url: string;
readonly category: string;
readonly icon?: string;
/** Metres along the body, as drawn. */
readonly length: number;
/** The uniform scale along the model's length. */
readonly scale: number;
/** The length, beam and height scales. */
readonly scaleXYZ: readonly [number, number, number];
/** How far the model reaches below its origin at this scale. */
readonly clearanceM: number;
/** How far the model's origin stands above the route it follows. */
readonly elevationM: number;
/** Whether its meshes carry the `_TINT` attribute a route colour paints. */
readonly tinted: boolean;
readonly nativeRadiusM: number;
readonly visualCenterNative: readonly [number, number, number];
readonly trailAnchorNative: readonly [number, number, number];
/** Its identity: model and scales. */
readonly key: string;
/** An aid to navigation's: it has no heading to turn to. */
readonly fixed?: boolean;
}
/** An aircraft's model spec as the aircraft layers draw it. */
export interface AircraftLayerModelSpec extends Omit<
FleetModelSpec,
'model' | 'url'
> {
/** Null before the set has loaded. */
readonly model: string | null;
readonly url: string | null;
/** How far a grounded aircraft's origin stands above the ground. */
readonly bellyM: number;
}
/** What picks an aircraft's model. */
export interface FleetAircraft {
typeCode?: string | null;
type?: string | null;
category?: string | number | null;
callsign?: string | null;
}
/** What picks a vessel's model. */
export interface FleetVessel {
type?: string | number | null;
mmsi?: string | number | null;
virtual?: boolean;
length?: number | null;
beam?: number | null;
name?: string | null;
}
/** What picks a transit or rail vehicle's model. */
export interface FleetTransitVehicle {
railCategory?: string;
railMode?: string;
routeType?: number | string;
mode?: string;
}
/** The icon-to-model rules every fleet layer follows. */
export interface FleetModelPolicy {
/** No model above this camera height. */
readonly altitudeCeilingM: number;
/** Models drawn in the nearby mode, and in the all mode. */
readonly cap: number;
readonly capAll: number;
/** A contact this near gets a model; one that has one keeps it this near. */
readonly addM: number;
readonly keepM: number;
/** How often eligibility is worked out again. */
readonly intervalMs: number;
}
/** How an aircraft model's colour meets its mesh (`ModelItem.colorBlend`). */
export interface AircraftModelBlend {
mode: 'highlight' | 'mix';
amount?: number;
}
/** What an aircraft's part state is driven by. */
export interface FleetAircraftMotion {
onGround?: boolean;
heightAboveGroundM?: number | null;
altitudeM?: number | null;
verticalRateMps?: number | null;
speedMps?: number | null;
}
/** Where the model set is served, relative to the application base. */
export const FLEET_MODEL_BASE: string;
export function resolveAircraft(
types: FleetTypes,
type?: string | null,
category?: string | null,
callsign?: string | null,
): FleetModelChoice;
export function resolveVessel(
types: FleetTypes,
shipType?: number | null,
length?: number | null,
beam?: number | null,
name?: string | null,
): FleetModelChoice;
export function resolveTransit(
types: FleetTypes,
vehicle?: FleetTransitVehicle,
): FleetModelChoice;
export function fleetModelSpec(
set: Pick<FleetModelSet, 'catalog' | 'types'>,
name: string,
length: number | null,
options?: { beam?: number },
): FleetModelSpec;
export function aircraftModelSpec(
set: Pick<FleetModelSet, 'catalog' | 'types'>,
aircraft?: FleetAircraft,
): FleetModelSpec;
/** Null for a virtual aid to navigation: nothing physical stands there. */
export function vesselModelSpec(
set: Pick<FleetModelSet, 'catalog' | 'types'>,
vessel?: FleetVessel,
): FleetModelSpec | null;
export function transitModelSpec(
set: Pick<FleetModelSet, 'catalog' | 'types'>,
vehicle: FleetTransitVehicle,
): FleetModelSpec;
/** Model `name`'s part table, read once from its GLB; null for none. */
export function fleetPartTable(
set: Pick<FleetModelSet, 'bytes'> | null | undefined,
name: string | null | undefined,
): PartTable | null;
/** The set once loaded, else null. */
export function fleetModelSet(): FleetModelSet | null;
/** The load started, or null when none has. */
export function fleetModelSetLoading(): Promise<FleetModelSet> | null;
/** Fetches the set's JSON and every GLB once, up front. */
export function loadFleetModelSet(options?: {
resolveAsset?: (url: string) => string;
fetchImpl?: typeof fetch;
now?: () => number;
}): Promise<FleetModelSet>;
export const UNLOADED_AIRCRAFT_MODEL_SPEC: AircraftLayerModelSpec;
export function aircraftLayerModelSpec(
aircraft: FleetAircraft | null | undefined,
set?: FleetModelSet | null,
): AircraftLayerModelSpec;
export function aircraftModelSpecCacheKey(
aircraft: FleetAircraft | null | undefined,
set?: FleetModelSet | null,
): string;
export const EMERGENCY_TINT: FleetRgba;
export const FLEET_MODEL_POLICY: FleetModelPolicy;
/** The handover: a contact within this many metres of the eye is drawn as its model. */
export const MODEL_ADD_M: number;
export const MODEL_KEEP_M: number;
export const MODEL_ALT_CEIL_M: number;
export const MODEL_HEADING_OFFSET_DEG: number;
export const MODEL_MAX: number;
export const MODEL_MAX_ALL: number;
export const MODEL_WHITE: FleetRgba;
export const AIRCRAFT_ENVIRONMENT_MAP_OPTIONS: { readonly enabled: boolean };
export const AIRCRAFT_MODEL_TINT_MIX: number;
export function aircraftModelBlend(
irBoost: boolean,
tint?: ArrayLike<number> | null,
): AircraftModelBlend;
export function aircraftPartState(
table: PartTable | null | undefined,
aircraft: FleetAircraftMotion,
): ModelPartState | undefined;
/** An airport vehicle (class `vehicle`) rolls as a road vehicle; any other contact flies. */
export function aircraftLayerPartState(
table: PartTable | null | undefined,
contact: FleetAircraftMotion & { klass?: string | null },
): ModelPartState | undefined;
export function vesselPartState(
table: PartTable | null | undefined,
vessel: { speedMps?: number | null },
): ModelPartState | undefined;
export function groundVehiclePartState(
table: PartTable | null | undefined,
vehicle: { speedMps?: number | null; atStop?: boolean },
): ModelPartState | undefined;
/**
* Which contacts may hold a model: `[id, distanceSq, onScreen]` inside the
* keep radius, nearest first, on-screen first under the cap.
*/
export function selectModelEligible(
candidates: ReadonlyArray<readonly [string, number, boolean]>,
options: {
cap: number;
addDistSq: number;
isModeled: (id: string) => boolean;
},
): Set<string>;
/** Every fleet model is nose -X: opposite the draw contract's heading 0. */
export const FLEET_HEADING_OFFSET_DEG: number;
/** The per-axis stretch a spec draws with on top of its length scale, if any. */
export function fleetAxisScale(
spec: Pick<FleetModelSpec, 'scaleXYZ'> | null | undefined,
): [number, number, number] | undefined;
/** A colour as the draw contract takes it; null for none. */
export function fleetColor(
color:
| Color
| { red: number; green: number; blue: number; alpha?: number }
| null
| undefined,
): Color | null;
export const VESSEL_SPRITE_PX: number;
/** The white hull sprite of a vessel kind, bow up, as an SVG data URI. */
export function vesselSprite(kind: string): string;
/** The buoy sprite of an aid to navigation, as an SVG data URI. */
export function aidSprite(): string;
export const VESSEL_KINDS: readonly string[];
export const VESSEL_KIND_STYLES: Readonly<
Record<string, { readonly css: string; readonly accent: string }>
>;
export function isAidToNavigation(vessel?: {
type?: string | number | null;
mmsi?: string | number | null;
virtual?: boolean;
}): boolean;
export function normalizeVesselType(
type: string | number | null | undefined,
): string;
export function vesselKind(type: string | number | null | undefined): string;
+69
View File
@@ -0,0 +1,69 @@
/**
* Fleet contacts as the Flights and Vessels layers draw them: the procedural
* fleet model set and its loader, which model and size an aircraft or a
* vessel draws with, the icon-to-model handover distances, how a model is
* lit, tinted and turned, the moving parts it is posed with, and the vessel
* hull sprites. Every name here is the layers' own; nothing is redefined.
*
* Portable: no engine, DOM or layer state.
*/
export {
FLEET_MODEL_BASE,
aircraftModelSpec,
fleetModelSet,
fleetModelSetLoading,
fleetModelSpec,
fleetPartTable,
loadFleetModelSet,
resolveAircraft,
resolveTransit,
resolveVessel,
transitModelSpec,
vesselModelSpec,
} from '../data/fleetModels.js';
export {
UNLOADED_AIRCRAFT_MODEL_SPEC,
aircraftLayerModelSpec,
aircraftModelSpecCacheKey,
} from '../layers/flights/modelSpec.js';
export {
EMERGENCY_TINT,
FLEET_MODEL_POLICY,
MODEL_ADD_M,
MODEL_ALT_CEIL_M,
MODEL_HEADING_OFFSET_DEG,
MODEL_KEEP_M,
MODEL_MAX,
MODEL_MAX_ALL,
MODEL_WHITE,
} from '../layers/flights/policy.js';
export {
AIRCRAFT_ENVIRONMENT_MAP_OPTIONS,
AIRCRAFT_MODEL_TINT_MIX,
aircraftModelBlend,
} from '../data/aircraftModelLighting.js';
export {
aircraftLayerPartState,
aircraftPartState,
groundVehiclePartState,
vesselPartState,
} from '../data/modelPartDrivers.js';
export { selectModelEligible } from '../data/modelEligibility.js';
export {
FLEET_HEADING_OFFSET_DEG,
fleetAxisScale,
fleetColor,
} from '../data/fleetModelDraw.js';
export {
VESSEL_SPRITE_PX,
aidSprite,
vesselSprite,
} from '../data/vesselSprites.js';
export {
VESSEL_KINDS,
VESSEL_KIND_STYLES,
isAidToNavigation,
normalizeVesselType,
vesselKind,
} from '../data/vesselTypes.js';
+36
View File
@@ -0,0 +1,36 @@
import assert from 'node:assert/strict';
import test from 'node:test';
import * as fleet from './index.js';
import * as fleetModels from '../data/fleetModels.js';
import * as policy from '../layers/flights/policy.js';
import * as partDrivers from '../data/modelPartDrivers.js';
import * as vesselSprites from '../data/vesselSprites.js';
test('hands out the layers’ own functions and constants, not copies', () => {
assert.equal(fleet.loadFleetModelSet, fleetModels.loadFleetModelSet);
assert.equal(fleet.fleetModelSet, fleetModels.fleetModelSet);
assert.equal(fleet.resolveAircraft, fleetModels.resolveAircraft);
assert.equal(fleet.resolveVessel, fleetModels.resolveVessel);
assert.equal(fleet.FLEET_MODEL_POLICY, policy.FLEET_MODEL_POLICY);
assert.equal(fleet.MODEL_WHITE, policy.MODEL_WHITE);
assert.equal(fleet.vesselPartState, partDrivers.vesselPartState);
assert.equal(fleet.vesselSprite, vesselSprites.vesselSprite);
});
test('the handover is the aircraft layers’ distances, the policy every fleet layer takes', () => {
assert.equal(fleet.FLEET_MODEL_POLICY.addM, fleet.MODEL_ADD_M);
assert.equal(fleet.FLEET_MODEL_POLICY.keepM, fleet.MODEL_KEEP_M);
assert.equal(
fleet.FLEET_MODEL_POLICY.altitudeCeilingM,
fleet.MODEL_ALT_CEIL_M,
);
assert.ok(fleet.MODEL_KEEP_M > fleet.MODEL_ADD_M);
});
test('a vessel kind’s hull sprite is an SVG data URI, the same each time', () => {
const hull = fleet.vesselSprite(fleet.vesselKind('70'));
assert.match(hull, /^data:image\/svg\+xml;base64,/);
assert.equal(fleet.vesselSprite('cargo'), hull);
assert.notEqual(fleet.aidSprite(), hull);
});
+1
View File
@@ -34,6 +34,7 @@ const NEUTRAL = [
'./render/weather',
'./weather/effects',
'./geo/screenCluster',
'./fleet',
];
const fileOf = (key) => path.join(ROOT, PKG.exports[key]);