Files
gods-eye-view/src/data/trackedReadout.js
T
German Khokhlov 35e70ec280 Draw the aircraft family, Wildlife Sightings and the Cockpit through the contract
The layers that still had one Cesium and one Navara implementation, or
drew on Cesium only, now draw through engine.movers, engine.lines and
engine.camera on both engines, and application code holds the engine
instead of guessing it from a viewer.

- Aircraft family: flights, military and local ADS-B share one display
  (src/layers/aircraft/render/display.js). The Cesium and Navara
  renderers are gone. Where they differed, the display follows Cesium:
  - attach and visibility tracking, live disableDepthTestDistance
    changes, the tracked glyph's distance scale, model ids that change,
    local ADS-B markers hidden until shown and its UAT ring as a point;
  - the trail head's hidden alpha is 0.45, the contract's
    depthFailAlpha scaled by the head's 0.9.
  The tracked glyph stays over the fleet, as on Navara. The movers
  contract reports readiness per model and reads model axes as the
  glTF's own on every engine. Cesium's follow takes any native target
  through a proxy entity in the ENU frame and mirrors its readout fields.
- Wildlife Sightings draws badges and the density glow as sprite sets
  and its privacy cells as line outlines (no fill yet). It takes clicks
  from engine.input and its card anchors to the engine's canvas and
  camera, so the layer is in both engines' catalogs again and a switch
  keeps the session's layer set.
- Cockpit: cockpitHost takes the engine only. The ridden aircraft is the
  engine follow's target, hidden through its sprite; only the Cesium
  Viewer's stock double-click is still routed around.
- About forty camera, navigation, share-link, HUD, voice, detection and
  layer-lifecycle callers take the engine. isGlobeEngine and
  engineFromViewer calls outside src/globe fall from 51 to 14.

The coupling baseline drops accordingly: layer renderer lines from
5239/12331 to 4546/11106 (Cesium/Navara), `viewer` lines from 2424 to
2209, Cesium-importing files from 69 to 66.
2026-11-07 02:34:34 +04:00

344 lines
11 KiB
JavaScript

import {
clearOverlaySource,
setOverlayEntries,
setOverlaySourceVisible,
} from '../overlays/worldOverlay.js';
import { WORLD_OVERLAY_STYLE } from '../overlays/worldOverlayTokens.js';
/**
* @module trackedReadout
* @description Presentation-model bridge for the protected tracked-target
* entry in the shared world-overlay host. This module owns no canvas,
* projection, frame listener, layout, fade, or paint path.
*/
export const TRACKED_OVERLAY_SOURCE_ID = 'tracked';
export const TRACKED_OVERLAY_SOURCE_OPTIONS = Object.freeze({
cohortLimit: 1,
collisionCapacity: 0,
moving: true,
solveIntervalMs: 0,
hideInCockpit: true,
});
const TRACKED_BILLBOARD_SCALE = Object.freeze({
near: 1000,
nearValue: 3,
far: 8_000_000,
farValue: 0.5,
});
const DEFAULT_TRACKED_OVERLAY_HOST = Object.freeze({
setEntries: setOverlayEntries,
setVisible: setOverlaySourceVisible,
clearSource: clearOverlaySource,
});
// The globe engine: the followed target is engine.camera.following().
let _engine = null;
let _trackedEntityChangedRemove = null;
let _selectedContext = null;
let _contextSelectedHandler = null;
let _contextClearedHandler = null;
let _aircraftSelectedHandler = null;
let _activeEntryId = null;
let _overlayHost = DEFAULT_TRACKED_OVERLAY_HOST;
/**
* Convert the former newline/inline label text into the explicit presentation
* model used by the host.
* @param {string} text Raw source-formatted label text.
* @param {string} accent Source-owned accent color.
* @returns {{title:string,details:string[],accent:string}}
*/
export function trackedLabelModelFromText(
text,
accent = WORLD_OVERLAY_STYLE.accent,
) {
const raw = String(text || '').trim();
if (!raw) return { title: '', details: [], accent };
let lines;
if (raw.includes('\n')) {
lines = raw
.split('\n')
.map((line) => line.trim())
.filter(Boolean);
} else {
const parts = raw.split(' · ');
lines =
parts.length > 1
? [parts[0].trim(), parts.slice(1).join(' · ').trim()]
: [raw];
}
return { title: lines[0] || '', details: lines.slice(1), accent };
}
/**
* Read only the layer-owned display cache. There is deliberately no fallback
* to `entity.position.getValue()`: doing so in the host's post-render phase
* would recompute dead reckoning after the follow camera settled and jitter.
* @param {Object|null} entity Tracked or selected presentation entity.
* @returns {Object|null}
*/
export function cachedTrackedDisplayPosition(entity) {
if (!entity || typeof entity.gevDisplayPosition !== 'function') return null;
try {
return entity.gevDisplayPosition() || null;
} catch {
return null;
}
}
/**
* Anchor for the tracked CARD: the position the target is visually at.
*
* A layer that renders its tracked contact as a 3D model publishes
* `gevVisualPosition`, which returns the translation that model is actually rendering
* with. For a grounded aircraft that differs from the display position by the full
* ground-snap offset (~100 m at an inland airport), so a card anchored to the display
* position sits below the aircraft and climbs slowly as the coarse floor cell warms.
*
* Falls back to the display position, so layers without a 3D visual (and any layer
* before its model is ready) are unchanged. This deliberately does NOT repurpose
* `gevDisplayPosition`: that accessor carries the follow-camera anti-jitter contract
* and must keep returning the value the camera settled on.
* @param {Object|null} entity Tracked or selected presentation entity.
* @returns {Object|null}
*/
export function cachedTrackedVisualPosition(entity) {
if (entity && typeof entity.gevVisualPosition === 'function') {
try {
const visual = entity.gevVisualPosition();
if (visual) return visual;
} catch {
/* fall through to the display position */
}
}
return cachedTrackedDisplayPosition(entity);
}
function entryIdFor(entity) {
const explicit = String(entity?.gevTrackedId || '').trim();
if (explicit) return explicit;
const fallback = String(entity?.id || '').trim();
return fallback ? `entity:${fallback}` : null;
}
// A follow's plain-data label as the subject the readout reads (the shape a
// Cesium layer's tracked Entity has): one subject per follow handle.
const _labelSubjects = new WeakMap();
function followSubject(handle) {
if (!handle) return null;
const { label } = handle;
if (!label) return handle.native ?? null;
let subject = _labelSubjects.get(handle);
if (!subject) {
subject = {
gevTrackedId: label.id,
get gevLabelModel() {
const { model } = handle.label ?? label;
return typeof model === 'function' ? model() : model;
},
gevDisplayPosition: () => (handle.label ?? label).position(),
};
_labelSubjects.set(handle, subject);
}
return subject;
}
function trackedSubject() {
return _engine ? followSubject(_engine.camera.following()) : null;
}
function activeEntity() {
return trackedSubject() || _selectedContext?.entity || null;
}
/**
* Build the host entry from a layer-owned tracked presentation model.
* @param {Object|null} entity Tracked or selected presentation entity.
* @returns {Object|null}
*/
export function createTrackedOverlayEntry(entity) {
const model = entity?.gevLabelModel;
const id = entryIdFor(entity);
if (!id || !model || typeof entity.gevDisplayPosition !== 'function') {
return null;
}
const title = String(model.title || '').trim();
if (!title) return null;
return {
id,
position: () => cachedTrackedVisualPosition(entity),
variant: 'tracked',
tracked: true,
protected: true,
paintLane: 'tracked',
collisionGroup: 'ambient-card',
priority: Number.MAX_SAFE_INTEGER,
title,
details: Array.isArray(model.details)
? model.details.map((line) => String(line))
: [],
accent: model.accent || WORLD_OVERLAY_STYLE.accent,
cardStyle: model.cardStyle,
selected: model.selected === true,
leaderStyle: model.leaderStyle,
leaderAnimationMs: model.leaderAnimationMs,
leaderAnimationStartedAt: model.leaderAnimationStartedAt,
leaderDrawRatio: model.leaderDrawRatio,
anchorRadiusPx: Number.isFinite(Number(model.anchorRadiusPx))
? Math.max(0, Number(model.anchorRadiusPx))
: 10,
anchorRadiusScale: Object.prototype.hasOwnProperty.call(
model,
'anchorRadiusScale',
)
? model.anchorRadiusScale
: TRACKED_BILLBOARD_SCALE,
minAnchorGapPx: 16,
anchorGapPaddingPx: 10,
verticalOnly: true,
viewportMargin: 6,
edgeFade: 'keyhole',
horizonCull: true,
terrainOcclusion: false,
interactive: false,
};
}
function publishEntity(entity) {
const entry = createTrackedOverlayEntry(entity);
if (!entry) {
clearTrackedSource();
return;
}
_activeEntryId = entry.id;
_overlayHost.setEntries(
TRACKED_OVERLAY_SOURCE_ID,
[entry],
TRACKED_OVERLAY_SOURCE_OPTIONS,
);
_overlayHost.setVisible(TRACKED_OVERLAY_SOURCE_ID, true);
}
function clearTrackedSource() {
_activeEntryId = null;
_overlayHost.clearSource(TRACKED_OVERLAY_SOURCE_ID);
}
function syncActiveEntity() {
publishEntity(activeEntity());
}
/**
* Republish a layer's newly assigned `gevLabelModel` when that entity owns the
* active tracked readout. Layers call this only when presentation text changes;
* position remains the live frame-cache getter already registered with host.
* @param {Object} entity Entity whose model changed.
*/
export function refreshTrackedReadout(entity) {
// A follow handle stands for its label subject; so does a layer's tracked
// visual that names its follow handle (gevFollowHandle, an engine without
// tracked entities: the Navara aircraft renderer).
const subject =
_labelSubjects.get(entity) ??
_labelSubjects.get(entity?.gevFollowHandle) ??
entity;
if (subject && subject === activeEntity()) publishEntity(subject);
}
/** Current tracked host entry id, used to resolve its actual painted rectangle. */
export function getActiveTrackedReadoutId() {
return _activeEntryId;
}
/** Static-context layers whose click selection publishes the readout card. */
const READOUT_CONTEXT_LAYERS = new Set(['alpr-cameras', 'local-adsb']);
/**
* Initialize the model bridge and selection listeners. No render listener is
* installed; the already-initialized world-overlay host owns the frame lane.
* @param {import('../globe/contract.js').GlobeEngine} engine The readout
* follows engine.camera.following(), its label (plain data) or its Cesium
* entity.
*/
export function initTrackedReadout(engine) {
if (!engine || _engine === engine) return;
if (_engine) destroyTrackedReadout();
_engine = engine;
_overlayHost.setVisible(TRACKED_OVERLAY_SOURCE_ID, true);
_trackedEntityChangedRemove =
engine.camera.followChanged?.addEventListener?.(() => {
if (trackedSubject()) _selectedContext = null;
syncActiveEntity();
}) || null;
_contextSelectedHandler = (event) => {
const record = event.detail;
if (READOUT_CONTEXT_LAYERS.has(record?.layerId)) {
_selectedContext = record;
publishEntity(record.entity);
return;
}
if (_selectedContext) {
_selectedContext = null;
syncActiveEntity();
}
};
_contextClearedHandler = (event) => {
if (
!_selectedContext ||
event.detail?.layerId === _selectedContext.layerId
) {
_selectedContext = null;
syncActiveEntity();
}
};
_aircraftSelectedHandler = () => {
_selectedContext = null;
if (!trackedSubject()) clearTrackedSource();
};
window.addEventListener('gev:entity-selected', _contextSelectedHandler);
window.addEventListener(
'gev:entity-selection-cleared',
_contextClearedHandler,
);
window.addEventListener(
'gev:awareness-subject-selected',
_aircraftSelectedHandler,
);
syncActiveEntity();
// Boot-verification contract: the track regression harness asserts this
// exact line at init (dropped by the host migration; restored).
console.log('[TrackedReadout] Initialized');
}
/** Tear down selection listeners and clear the host source. */
export function destroyTrackedReadout() {
_trackedEntityChangedRemove?.();
_trackedEntityChangedRemove = null;
if (_contextSelectedHandler)
window.removeEventListener('gev:entity-selected', _contextSelectedHandler);
if (_contextClearedHandler)
window.removeEventListener(
'gev:entity-selection-cleared',
_contextClearedHandler,
);
if (_aircraftSelectedHandler)
window.removeEventListener(
'gev:awareness-subject-selected',
_aircraftSelectedHandler,
);
_contextSelectedHandler = null;
_contextClearedHandler = null;
_aircraftSelectedHandler = null;
_selectedContext = null;
clearTrackedSource();
_overlayHost.setVisible(TRACKED_OVERLAY_SOURCE_ID, false);
_engine = null;
}
/** Inject a host recorder for focused lifecycle tests; null restores production. */
export function _setTrackedOverlayHostForTest(host = null) {
_overlayHost = host || DEFAULT_TRACKED_OVERLAY_HOST;
}