Merge origin/main into the renderer-contract branch: the procedural fleet models drawn through the renderer's model sets

Aircraft, military, local ADS-B, vessel, transit and rail models come from
the fleet model set, loaded up front and drawn life size through the draw
port's models sets; no layer touches the viewer or Cesium outside
src/render/cesium/. The models capability gains glTF bytes (gltf), a
per-axis stretch (axisScale), a colour for tinted parts (maskColor) and a
cut below the origin (clip: 'belowOrigin'), with conformance checks.

Main's rail layer and Data Library are ported to the ports; the CCTV
footprint probe keeps the globe-terrain clamp through the query port.
This commit is contained in:
Sameh Khamis committed 2026-11-13 14:14:42 -08:00
commit e3865f462f
533 files changed
+55738 -2518

No files matched your search

+5
View File
@@ -7,6 +7,7 @@ import { createRendering } from './rendering.js';
import { createSelection } from './selection.js';
import { createTracking } from './tracking.js';
import { createCards } from './cards.js';
import { createPhotos } from './photos.js';
import { createTesting } from './testing.js';
import { createEvidence } from './evidence.js';
import { createQueries } from './queries.js';
@@ -24,6 +25,7 @@ export function createVesselLayer({ source, services, options = {} } = {}) {
parts.selection = createSelection(context);
parts.tracking = createTracking(context);
parts.cards = createCards(context);
parts.photos = createPhotos(context);
parts.testing = createTesting(context);
parts.evidence = createEvidence(context);
parts.queries = createQueries(context);
@@ -90,6 +92,9 @@ export function createVesselLayer({ source, services, options = {} } = {}) {
buildVesselCard: parts.cards.buildVesselCard,
buildSelectedVesselCard: parts.cards.buildSelectedVesselCard,
cardScreenSeparated: parts.cards.cardScreenSeparated,
/** The vessel's Open Vessel Photos photo, once its lookup answered. */
getVesselPhoto: (id) =>
parts.photos.vesselPhoto(vesselState.state.records.byId.get(id)),
});
Object.defineProperty(layer, 'testing', { value: parts.testing });
return layer;
+2
View File
@@ -213,6 +213,8 @@ export function createIngestion({
imo: record.imo,
type: record.type,
destination: record.destination,
length: record.lengthM ?? null,
beam: record.beamM ?? null,
speed: record.speedMps == null ? null : record.speedMps / 0.514444,
course: record.courseDeg,
heading: record.headingDeg,
+1
View File
@@ -242,6 +242,7 @@ export function createLifecycle({
if (state.preRenderRemover) {
state.preRenderRemover();
}
components.rendering.destroyModels();
resetState();
},
};
+56
View File
@@ -0,0 +1,56 @@
import { MMSI, parseOpenVesselPhoto } from '../../data/openVesselPhoto.js';
/** A failed lookup is asked again after this long; a miss is final. */
const PHOTO_RETRY_MS = 5 * 60 * 1000;
/** Lookups remembered per session, oldest dropped first. */
const PHOTO_CACHE_LIMIT = 500;
/**
* The selected vessel's photo, looked up once per MMSI when it is selected.
* The answer is read with `parseOpenVesselPhoto` whatever shape the source
* returns, so only a checked photo is ever kept. A source without
* `getEnrichment` has no photos.
*/
export function createPhotos({ vesselState }) {
/** MMSI → photo, `null` for a final miss, or `{failedAtMs}`/`{pending}`. */
const answers = new Map();
function remember(mmsi, answer) {
answers.delete(mmsi);
answers.set(mmsi, answer);
if (answers.size > PHOTO_CACHE_LIMIT)
answers.delete(answers.keys().next().value);
}
/** Ask for the record's photo unless it is known, asked or cooling down. */
function requestVesselPhoto(record, now = Date.now()) {
const mmsi = String(record?.mmsi || '');
const source = vesselState._source;
if (!MMSI.test(mmsi) || typeof source?.getEnrichment !== 'function') return;
const known = answers.get(mmsi);
if (known !== undefined) {
if (known?.pending || known === null || known.found) return;
if (now - known.failedAtMs < PHOTO_RETRY_MS) return;
}
remember(mmsi, { pending: true });
Promise.resolve()
.then(() => source.getEnrichment({ kind: 'photo', id: mmsi }))
.then(
(answer) => {
const photo = parseOpenVesselPhoto(answer);
remember(mmsi, photo.found ? photo : null);
},
() => remember(mmsi, { failedAtMs: Date.now() }),
);
}
/** The vessel's checked photo, or null. */
function vesselPhoto(record) {
const answer = answers.get(String(record?.mmsi || ''));
if (!answer?.found) return null;
const { src, width, height, photographer, licence, link } = answer;
return { src, width, height, photographer, licence, link };
}
return { requestVesselPhoto, vesselPhoto };
}
+87
View File
@@ -0,0 +1,87 @@
// src/layers/vessels/photos.test.mjs — a selected vessel's photo is asked for
// once per MMSI; a miss is final and a failure is retried only after a pause.
import test from 'node:test';
import assert from 'node:assert/strict';
import { createPhotos } from './photos.js';
const ANSWER = Object.freeze({
mmsi: '366999709',
photos: [
{
urls: {
mmsi: 'https://openvesselphotos.org/v1/mmsi/366999709/photos/1.jpg',
},
credit: 'Gordon Leggett',
licenceName: 'CC BY 4.0',
width: 1600,
height: 1200,
},
],
});
const settle = () => new Promise((resolve) => setImmediate(resolve));
function fixture(answer) {
const asked = [];
const source = {
getSnapshot() {},
async getEnrichment(query) {
asked.push(query);
return answer(query);
},
};
const photos = createPhotos({ vesselState: { _source: source } });
return { photos, asked };
}
test('a selected vessel is asked once and shows its checked photo', async () => {
const { photos, asked } = fixture(() => ANSWER);
const record = { id: 'v1', mmsi: '366999709' };
photos.requestVesselPhoto(record);
photos.requestVesselPhoto(record);
await settle();
photos.requestVesselPhoto(record);
assert.deepEqual(asked, [{ kind: 'photo', id: '366999709' }]);
assert.deepEqual(photos.vesselPhoto(record), {
src: 'https://openvesselphotos.org/v1/mmsi/366999709/photos/1.jpg?size=800',
width: 800,
height: 600,
photographer: 'Gordon Leggett',
licence: 'CC BY 4.0',
link: 'https://openvesselphotos.org/vessels/mmsi/366999709',
});
});
test('a vessel without a valid MMSI, or a source without lookups, is never asked', async () => {
const { photos, asked } = fixture(() => ANSWER);
photos.requestVesselPhoto({ id: 'v1', mmsi: '' });
photos.requestVesselPhoto({ id: 'v2', mmsi: '12345' });
await settle();
assert.equal(asked.length, 0);
const bare = createPhotos({ vesselState: { _source: { getSnapshot() {} } } });
bare.requestVesselPhoto({ id: 'v3', mmsi: '366999709' });
assert.equal(bare.vesselPhoto({ mmsi: '366999709' }), null);
});
test('a miss is final; a failure is asked again only after the pause', async () => {
let fail = true;
const { photos, asked } = fixture(({ id }) => {
if (id === '111111111') return { mmsi: id, photos: [] };
if (fail) throw new Error('down');
return ANSWER;
});
const missing = { mmsi: '111111111' };
const flaky = { mmsi: '366999709' };
photos.requestVesselPhoto(missing);
photos.requestVesselPhoto(flaky, 0);
await settle();
photos.requestVesselPhoto(missing);
photos.requestVesselPhoto(flaky, Date.now() + 1000);
assert.equal(asked.length, 2);
fail = false;
photos.requestVesselPhoto(flaky, Date.now() + 10 * 60 * 1000);
await settle();
assert.equal(asked.length, 3);
assert.equal(photos.vesselPhoto(missing), null);
assert.equal(photos.vesselPhoto(flaky).photographer, 'Gordon Leggett');
});
+1
View File
@@ -654,6 +654,7 @@ export function createQueries({
if ((idx - start) % stride !== 0) continue;
const record = records[idx];
const visual = components.rendering.getVisual(record);
// Horizon visibility: a vessel drawn as its model still counts.
if (!visual.visible) continue;
const position = visual.position;
if (!position) continue;
+10
View File
@@ -25,6 +25,9 @@ export function normalizeVessel(row) {
imo: String(row.imo || ''),
type: String(row.type || ''),
destination: String(row.destination || ''),
// Hull length and beam (metres), null when unreported.
length: positiveNumber(row.length),
beam: positiveNumber(row.beam),
speed: finiteNumber(row.speed),
course: finiteNumber(row.course),
heading: finiteNumber(row.heading),
@@ -46,6 +49,11 @@ function stampFix(record, receivedAtMs, feedLatestEpoch) {
record.fixFeedEpoch = feedLatestEpoch;
}
function positiveNumber(value) {
const number = finiteNumber(value);
return number !== null && number > 0 ? number : null;
}
function finiteNumber(value) {
if (value === null || value === undefined || value === '') return null;
const number = Number(value);
@@ -146,6 +154,8 @@ export class VesselRecords {
record.imo = next.imo;
record.type = next.type;
record.destination = next.destination;
record.length = next.length;
record.beam = next.beam;
record.speed = next.speed;
record.course = next.course;
record.heading = next.heading;
+151 -4
View File
@@ -8,7 +8,7 @@ import {
} from '../../data/vesselLabels.js';
import { fromDegrees } from '../../geo/ellipsoid.js';
import { horizonFrom, liftedForHorizon } from '../../geo/horizon.js';
import { distance } from '../../geo/vector.js';
import { distance, distanceSquared } from '../../geo/vector.js';
import {
canvasOf,
drawOf,
@@ -29,6 +29,12 @@ import {
followsClock,
} from './policy.js';
import { vesselPositionAt } from './motion.js';
import {
fleetModelSet,
loadFleetModelSet,
vesselModelSpec,
} from '../../data/fleetModels.js';
import { createFleetModelLayer } from '../../data/fleetModelInstances.js';
/** How often vessels move on as the world clock plays (wall ms). */
const FOLLOW_POSITION_MS = 250;
@@ -38,6 +44,9 @@ const SHIP_ICON_PX = 32;
let instances = 0;
/** How often the vessels near enough for a model are gathered again (wall ms). */
const MODEL_CANDIDATES_MS = 500;
export function createRendering({
vesselState,
services,
@@ -71,6 +80,8 @@ export function createRendering({
visualRecords.set(record, visual);
}
visual.position = anchorPosition(record);
// A ship model's origin is its waterline: the sea surface, unlifted.
visual.waterline = anchorPosition(record, 0);
return visual;
}
@@ -79,16 +90,18 @@ export function createRendering({
* (the geoid, once its grid has loaded). Following the world clock, a
* vessel is drawn where it was at the time.
* @param {Object} record - Vessel record with a finite lat/lon.
* @param {number} [liftM] Height above the sea surface (the icon's lift by
* default; 0 for a ship model's waterline).
* @returns {{x: number, y: number, z: number}} ECEF metres: icon items,
* focus and the layer's queries take it as it is.
*/
function anchorPosition(record) {
function anchorPosition(record, liftM = VESSEL_LIFT_M) {
const { lat, lon } = followsClock(vesselState)
? vesselPositionAt(record, vesselState.worldNow())
: record;
const heightM = components.queries.vesselDatumHeightM(
components.tracking.currentGeoidN(lat, lon),
VESSEL_LIFT_M,
liftM,
);
return fromDegrees(lon, lat, heightM);
}
@@ -142,6 +155,7 @@ export function createRendering({
* at the geoid would clip behind local tide/mesh noise).
*/
function ensureCollections(viewer) {
ensureModels(viewer);
if (!viewer || state.icons) return;
const set = drawOf(viewer).icons({
id: `ais-vessels:${++instances}`,
@@ -193,7 +207,8 @@ export function createRendering({
const courseDeg = vesselCourseDeg(record);
return {
id: visual.iconId,
show: !isCockpitSubject(record),
// Hidden while the bridge camera rides it, or its model draws it.
show: !isCockpitSubject(record) && !visual.modelOwnsVisual,
pos: visual.position,
image: shipIcon(record, selected),
size: [SHIP_ICON_PX, SHIP_ICON_PX],
@@ -302,6 +317,128 @@ export function createRendering({
return icon;
}
// Under the DISPLAY rail's 3D toggle, vessels near the camera are drawn as
// the project's procedural fleet models at their reported length and beam,
// on the aircraft layers' icon-to-model rules (services.fleet). The fleet
// set loads once, up front, when the layer starts.
let fleetModels = null;
/** Items drawn last frame, and the map the next frame's are gathered into. */
let modelItems = new Map();
let spareItems = new Map();
let modelCandidatesAtMs = -Infinity;
function ensureModels(viewer) {
const fleet = services.fleet;
if (!viewer || fleetModels || !fleet?.policy) return;
loadFleetModelSet({ resolveAsset: fleet.resolveAsset }).catch(() => {
/* models stay off; vessels keep their icons */
});
fleetModels = createFleetModelLayer({
viewer,
display: fleet.display,
policy: fleet.policy,
resolveAsset: fleet.resolveAsset,
// A hull below the waterline would show through a plain globe.
waterline: true,
});
}
/** The model item for `record`, its spec rebuilt only when its type or size changes. */
function modelItem(record, set) {
let item = modelItems.get(record.id);
if (!item || item.record !== record)
item = {
record,
pickId: getVisual(record).meta,
tint: null,
modelOwnsVisual: false,
};
const specKey = `${record.type}|${record.length}|${record.beam}|${record.name}`;
if (item.specKey !== specKey) {
item.specKey = specKey;
item.spec = vesselModelSpec(set, record);
}
item.position = getVisual(record).waterline;
item.headingDeg = vesselCourseDeg(record);
item.show = record.id !== state.cockpitSubjectId;
return item;
}
/** Gather the vessels within the models' keep radius of the camera into `into`. */
function gatherModelItems(set, into) {
const eye = state.viewer
? findCamera(state.viewer)?.pose()?.position
: null;
if (!eye) return;
const policy = services.fleet.policy;
const keepM =
services.fleet.display?.()?.models3dMode === 'all'
? policy.keepAllM
: policy.keepM;
const limitSq = keepM * keepM * 1.44;
for (const record of state.records.all) {
const waterline = getVisual(record).waterline;
if (!waterline) continue;
if (distanceSquared(eye, waterline) > limitSq) continue;
into.set(record.id, modelItem(record, set));
}
}
/** Give a vessel's chevron back when its model no longer draws it. */
function handBackVisual(record) {
const visual = getVisual(record);
if (!visual.modelOwnsVisual) return;
visual.modelOwnsVisual = false;
syncRecordIcon(record);
}
function updateModels() {
if (!fleetModels) return;
if (!fleetModels.active()) {
if (modelItems.size) {
modelItems.clear();
fleetModels.frame(modelItems, performance.now());
for (const record of state.records.all) handBackVisual(record);
}
return;
}
const set = fleetModelSet();
const now = performance.now();
const next = spareItems;
next.clear();
if (now - modelCandidatesAtMs >= MODEL_CANDIDATES_MS) {
modelCandidatesAtMs = now;
gatherModelItems(set, next);
} else {
for (const [id, item] of modelItems)
if (state.records.byId.get(id) === item.record)
next.set(id, modelItem(item.record, set));
}
for (const [id, item] of modelItems)
if (next.get(id) !== item) handBackVisual(item.record);
spareItems = modelItems;
modelItems = next;
fleetModels.frame(modelItems, now);
for (const item of modelItems.values()) {
const visual = getVisual(item.record);
if (item.modelOwnsVisual) {
if (!visual.modelOwnsVisual) {
visual.modelOwnsVisual = true;
syncRecordIcon(item.record);
}
} else handBackVisual(item.record);
}
if (fleetModels.settling) governorRequestRender('ais-vessels-models');
}
function destroyModels() {
fleetModels?.destroy();
fleetModels = null;
modelItems = new Map();
spareItems = new Map();
modelCandidatesAtMs = -Infinity;
}
// Vessels move only when a poll lands, so the layer does not hold the
// continuous render loop. Its passes run in preRender, which idle mode fires
// only for rendered frames: a forced pass (new data, selection) requests its
@@ -316,6 +453,7 @@ export function createRendering({
findFrame(viewer)?.on('preRender', () => {
if (followsClock(vesselState)) followClockPositions();
updateVisibility();
if (state.feed.enabled) updateModels();
}) ?? null;
}
@@ -670,6 +808,13 @@ export function createRendering({
function setVisible(show) {
if (state.icons) state.icons.show = show;
fleetModels?.setVisible(show);
if (!show && fleetModels) {
fleetModels.clear();
for (const item of modelItems.values())
getVisual(item.record).modelOwnsVisual = false;
modelItems.clear();
}
vesselState._vesselOverlayHost.setVisible(VESSEL_OVERLAY_SOURCE_ID, show);
}
return {
@@ -699,5 +844,7 @@ export function createRendering({
labelPriority,
hasUsefulName,
setVisible,
updateModels,
destroyModels,
};
}
+1
View File
@@ -165,6 +165,7 @@ export function createSelection({
// click, not up to VISIBILITY_UPDATE_MS later.
components.rendering.updateVisibility(true);
components.cards.updateSelectedVesselHud(record);
components.photos.requestVesselPhoto(record);
if (registerSelectedContext(record)) {
selectEntityContext(record);
}