/** * @module trailRenderer * @description Shared track-history renderer (PRD WS-F F4; rebuilt round 6, * 2026-07-06; drawn through the renderer's draw port since 2026-11). * * One trail = one line set on the viewer's draw port: the history line and, * for layers that draw one, the live head from the last history point to * the moving contact. Two owner directives from the field shape it: * - "the line must ALWAYS be visible": where the trail passes behind or * below scene geometry it draws dimmed (the line's depth-fail colour) * instead of vanishing. * - "show actual tracks, don't style them too much": the whole history * renders at one readable alpha (dimmer where it is hidden). * * The history changes at poll cadence (~15-60 s) plus once on backfill; the * head may change every frame. Either is rebuilt alone, under the same pick * id, without rebuilding the other. */ import { cssColor } from '../render/color.js'; import { findDraw } from '../render/rendererOf.js'; import { registerPickOwner } from './pickRegistry.js'; // Trail lines are pickable (a click on one must not fall through to the // ground under it). A trail hugs its aircraft, so an unclaimed pick would // read as "empty space" in every layer's click handler and deselect the very // plane being tracked. Claiming the 'gev-trail:' id namespace makes // isOwnedByOtherLayer() true for every layer — clicking a trail is a no-op // everywhere. Registered once at module load; the predicate is pure. registerPickOwner('trails', (pickedId) => String(pickedId).startsWith('gev-trail:'), ); /** @type {number} Uniquifier for trail set and line ids. */ let _trailSeq = 0; /** @constant {number} Alpha where the trail passes the depth test. */ const TRAIL_ALPHA = 0.85; /** @constant {number} Alpha where the trail is behind/below scene geometry — * visible (owner: never vanish) but readable as occluded. */ const TRAIL_OCCLUDED_ALPHA = 0.4; /** @constant {number} Alpha of the live head, and where it is hidden. */ const HEAD_ALPHA = 0.9; const HEAD_OCCLUDED_ALPHA = 0.45; /** @constant {number} Squared distance (m^2) below which consecutive points are merged. */ const MIN_SEGMENT_DISTANCE_SQ = 0.01; /** `css` (any CSS colour) at `alpha`, as a renderer colour. */ function colorAt(css, alpha) { const [r, g, b] = cssColor(css) ?? [1, 1, 1]; return [r, g, b, alpha]; } const distanceSq = (a, b) => (a.x - b.x) ** 2 + (a.y - b.y) ** 2 + (a.z - b.z) ** 2; /** * Consecutive near-duplicates dropped (zero-length segments add nothing), * as plain ECEF; empty when fewer than 2 distinct positions remain. * @param {Array<{x: number, y: number, z: number}|null|undefined>} given */ function trailPositions(given) { const positions = []; for (const position of Array.isArray(given) ? given : []) { if (!position) continue; const last = positions[positions.length - 1]; if (last && distanceSq(last, position) < MIN_SEGMENT_DISTANCE_SQ) continue; positions.push({ x: position.x, y: position.y, z: position.z }); } return positions.length >= 2 ? positions : []; } /** * Create an always-visible polyline trail bound to a viewer. * @param {object} viewer - Viewer whose renderer draws the trail. * @param {object} options - Trail options. * @param {string} options.color - CSS colour of the trail. * @param {number} [options.width=2.5] - Line width in pixels. * @returns {{setPositions: function(Array<{x: number, y: number, z: number}>): void, setHead: function(Array<{x: number, y: number, z: number}>|null): void, setVisible: function(boolean): void, clear: function(): void, destroy: function(): void}} * Trail handle: setPositions replaces the history, setHead the live head * (null or fewer than 2 positions: none), setVisible temporarily hides * both without discarding them, clear empties both, and destroy removes * the trail permanently. */ export function createTrail(viewer, { color, width = 2.5 }) { const seq = ++_trailSeq; const bodyId = `gev-trail:${seq}`; const headId = `gev-trail:${seq}:head`; let destroyed = false; let visible = true; /** @type {import('../render/contract/draw').DrawSet|null} */ let set = null; /** Each line as last drawn and its positions' key, by id, to skip a redraw that changes nothing. */ const drawn = new Map(); /** The head given while the trail is hidden, drawn once it shows. */ let pendingHead = null; function ensureSet() { if (set || destroyed || !viewer || viewer.isDestroyed?.()) return set; set = findDraw(viewer)?.lines({ id: `trail:${seq}`, show: visible }) ?? null; return set; } /** * Draw one of the trail's lines, or with no positions hide it. A hidden * line stays in the set, so the other is never rebuilt for it. */ function draw(id, positions, alpha, occludedAlpha, mode = 'geodesic') { if (destroyed || !viewer || viewer.isDestroyed?.()) return; const lines = ensureSet(); if (!lines) return; const key = positions.map(({ x, y, z }) => `${x},${y},${z}`).join(';'); const was = drawn.get(id); if ((was?.key ?? '') === key) return; if (!positions.length) { const hidden = { ...was.item, show: false }; drawn.set(id, { key, item: hidden }); lines.upsert([hidden]); return; } const item = { id, positions, widthPx: width, mode, style: { kind: 'solid', color: colorAt(color, alpha) }, // The owner-locked rule (round 6): a segment below the photoreal // mesh renders dimmed — it must never disappear into the ground. depthFailColor: colorAt(color, occludedAlpha), }; drawn.set(id, { key, item }); lines.upsert([item]); } /** * Replace the live head: the segment from the last drawn history point * to where the contact is drawn now. It may change every frame: while * the trail is hidden it is only kept, and drawn once the trail shows. * @param {Array<{x: number, y: number, z: number}>|null} cartesians */ function setHead(cartesians) { if (!visible) { pendingHead = cartesians ?? []; return; } pendingHead = null; // One poll interval long at most: straight is the geodesic to the // pixel, and a frame's rebuild stays two positions. draw( headId, trailPositions(cartesians), HEAD_ALPHA, HEAD_OCCLUDED_ALPHA, '3d', ); } return { /** * Replace the trail geometry with a chronological position list * (oldest first). Fewer than 2 distinct positions clears the trail. * @param {Array<{x: number, y: number, z: number}>} cartesians * ECEF positions, oldest -> newest. */ setPositions(cartesians) { // Round 8 (owner: UAL1104's Pacific trail "cutting through the // globe"): straight 3D chords between sparse trans-oceanic // waypoints tunnel through the planet; a geodesic line follows the // curved surface (heights interpolated) instead. draw( bodyId, trailPositions(cartesians), TRAIL_ALPHA, TRAIL_OCCLUDED_ALPHA, ); }, setHead, /** Temporarily hide/show the trail without discarding accumulated history. */ setVisible(nextVisible) { visible = nextVisible !== false; if (set) set.show = visible; if (visible && pendingHead) setHead(pendingHead); }, /** Empty the trail, keeping its set (cheap re-arm). */ clear() { pendingHead = null; if (!destroyed && set && !viewer?.isDestroyed?.() && drawn.size) { drawn.clear(); set.clear(); } }, /** Remove the trail permanently (layer disable/teardown). */ destroy() { destroyed = true; try { set?.dispose(); } catch { /* torn down */ } set = null; drawn.clear(); }, }; }