From e19c84bae47fa568cd160f80c9c911b42d6af772 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Wed, 18 Nov 2026 13:12:13 -0800 Subject: [PATCH] Make the fleet models, their handover and the vessel sprites a public entry point --- changelog.d/XXXX-fleet-entry.md | 6 + docs/RENDERER-CONTRACT.md | 7 +- package.json | 1 + scripts/package-boundaries.json | 29 +++ src/data/fleetModelDraw.js | 33 ++++ src/data/fleetModelInstances.js | 37 +--- src/fleet/index.d.ts | 289 +++++++++++++++++++++++++++++ src/fleet/index.js | 69 +++++++ src/fleet/index.test.mjs | 36 ++++ src/render/neutralExports.test.mjs | 1 + 10 files changed, 480 insertions(+), 28 deletions(-) create mode 100644 changelog.d/XXXX-fleet-entry.md create mode 100644 src/data/fleetModelDraw.js create mode 100644 src/fleet/index.d.ts create mode 100644 src/fleet/index.js create mode 100644 src/fleet/index.test.mjs diff --git a/changelog.d/XXXX-fleet-entry.md b/changelog.d/XXXX-fleet-entry.md new file mode 100644 index 0000000000..78d09ddf22 --- /dev/null +++ b/changelog.d/XXXX-fleet-entry.md @@ -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). diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index b216b7236e..76d547cb09 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -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 diff --git a/package.json b/package.json index f4eb8082fd..9fff58ddfe 100644 --- a/package.json +++ b/package.json @@ -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" } diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index e095bae1d2..a09757f481 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -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": [ diff --git a/src/data/fleetModelDraw.js b/src/data/fleetModelDraw.js new file mode 100644 index 0000000000..9495345232 --- /dev/null +++ b/src/data/fleetModelDraw.js @@ -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]; +} diff --git a/src/data/fleetModelInstances.js b/src/data/fleetModelInstances.js index 39989a1b73..59086f1c64 100644 --- a/src/data/fleetModelInstances.js +++ b/src/data/fleetModelInstances.js @@ -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. diff --git a/src/fleet/index.d.ts b/src/fleet/index.d.ts new file mode 100644 index 0000000000..a0b0f3989a --- /dev/null +++ b/src/fleet/index.d.ts @@ -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; + /** `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; + 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, + name: string, + length: number | null, + options?: { beam?: number }, +): FleetModelSpec; +export function aircraftModelSpec( + set: Pick, + aircraft?: FleetAircraft, +): FleetModelSpec; +/** Null for a virtual aid to navigation: nothing physical stands there. */ +export function vesselModelSpec( + set: Pick, + vessel?: FleetVessel, +): FleetModelSpec | null; +export function transitModelSpec( + set: Pick, + vehicle: FleetTransitVehicle, +): FleetModelSpec; +/** Model `name`'s part table, read once from its GLB; null for none. */ +export function fleetPartTable( + set: Pick | 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 | 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; + +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 | 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, + options: { + cap: number; + addDistSq: number; + isModeled: (id: string) => boolean; + }, +): Set; + +/** 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 | 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 +>; +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; diff --git a/src/fleet/index.js b/src/fleet/index.js new file mode 100644 index 0000000000..b54b18c7b6 --- /dev/null +++ b/src/fleet/index.js @@ -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'; diff --git a/src/fleet/index.test.mjs b/src/fleet/index.test.mjs new file mode 100644 index 0000000000..319c4053fb --- /dev/null +++ b/src/fleet/index.test.mjs @@ -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); +}); diff --git a/src/render/neutralExports.test.mjs b/src/render/neutralExports.test.mjs index 17057a35ec..8120d09202 100644 --- a/src/render/neutralExports.test.mjs +++ b/src/render/neutralExports.test.mjs @@ -34,6 +34,7 @@ const NEUTRAL = [ './render/weather', './weather/effects', './geo/screenCluster', + './fleet', ]; const fileOf = (key) => path.join(ROOT, PKG.exports[key]);