refactor(flights): Cesium rendering behind a renderer interface

Task 10a. The flights logic no longer imports Cesium: every Cesium object it
built moved one for one into the shared aircraft renderer
(src/layers/aircraft/render/cesium.js; contract in render/contract.js), with
the flights' parameters in src/layers/flights/render/cesium.js, registered
for 'cesium' in the renderer registry and created at init(viewer, {engine}).

- Fleet: BillboardCollection + sprite-order slot; sprites stay Billboard
  handles (field vocabulary documented for the Navara renderer).
- Models: fleet/tracked/preload glTF loads (asynchronous:false, MIX tint, IR
  boost as `unlit` → the UNLIT CustomShader), the model collection, setPose
  (same HPR frame with airplane.glb's 180° offset).
- Tracked: the ENU billboard Entity with its position/colour/rotation
  callbacks, viewFrom, followed through viewer.trackedEntity + the one exact
  tracked frame (kept as is; engine.camera.follow on Cesium would also end
  the follow on any camera command, a behaviour change).
- Trail: the entity trail (data/trailRenderer, unchanged: its Primitive
  predecessor failed below the mesh) and the live head segment.
- View: camera/scene reads, frame number, frustum and horizon tests,
  projection, render requests, frame events, evidence render-loop hold.
- Clicks and Escape go through the engine's selection dispatcher (the
  ScreenSpaceEventHandler and keydown listener are gone); the cross-layer
  untrack watches the renderer's follow.
- Colours are engine-neutral Rgba (src/layers/shared/color.js), bit-equal to
  the Cesium.Color constants they replace; NearFarScalar → nearFarScale.
- Cesium math in the logic → src/geo.
- check-import-directions: cesium only in render/cesium*.js and three/Navara
  only in render/navara*.js for flights, aircraft and shared; a layer's
  Navara renderer only through navaraMode's import().

Source-text tests updated with the moved code, same meaning:
- readLayerSource reads a layer's render/*.js and, for the aircraft layers,
  aircraft/render/*.js (GLB-load, tracked-entity, CallbackProperty checks).
- modelScale.test: _normalBillboardScaleByDistance reads nearFarScale(...).
- spriteOrder.test: flights' enable calls fleet.restoreOrderOnEnable(); the
  renderer wires it to restoreSpriteOrderOnEnable('flights', viewer).
- trackingClickGesture.test: the flights gesture rules are the dispatcher's
  (selection gesture before select, click classifier before the empty-space
  clear); flights answers the empty click with a user-origin clear.
- militaryAwareness.test: flights' hasContact guard reads fleet.visible().
- ownership.test: the services fixture names selection and renderer.

New tests: color, the Cesium aircraft renderer (contract, collections, pose,
loads, frustum/horizon, tracked entity, follow, trail head, adopted
collections), the flights logic over a plain-data renderer and a fake engine
(fleet, click-select, no-op on the tracked visual, empty-click release), the
boundary rule.

W1 replay vs 7c7422e2: counts, known objects, screen points (0 px), tracking
poses (0 m), requests and shots (same sha256) identical. Main chunk
2,890,982 B (+6.2 KB, +0.21 %: the renderer indirection).
This commit is contained in:
German Khokhlov committed 2026-10-17 01:04:25 +04:00
1 parent 8e702f0c3b
commit 7f13ef4a87
33 files changed
+1974 -748

No files matched your search

+159
View File
@@ -0,0 +1,159 @@
// The aircraft renderer: what the aircraft layers' logic (flights now,
// military and local ADS-B after it) asks of an engine to draw a fleet of
// aircraft, its 3D models, the tracked aircraft, its trail, and to follow it.
// render/cesium.js implements it over Cesium (the objects the layers used
// to build themselves, one for one); render/navara.js implements it on the
// Navara engine over engine.movers / engine.lines / engine.camera.follow.
// Nothing here imports an engine.
//
// The logic holds HANDLES and writes plain fields on them; the field names
// are Cesium's (the extraction is a pure move), and an engine other than
// Cesium implements them as setters:
//
// SpriteHandle (fleet.add) — one aircraft glyph:
// position (Cartesian3), show, rotation (screen angle, rad),
// scale, width, height (CSS px), color ({red, green, blue, alpha} with
// withAlpha(); an Rgba of src/layers/shared/color.js or what the engine
// stored), image (canvas or URL), scaleByDistance ({near, nearValue,
// far, farValue}), id. Reads return what was last written (color and
// scaleByDistance as the engine's own copy). The logic may keep its own
// bookkeeping fields on a handle (prefixed _gev).
// ModelHandle (models.load*) — one glTF instance:
// show, ready (read-only), scale, computedScale (read-only: scale after
// minimumPixelSize), color, id, modelMatrix (16 numbers, column-major,
// written by models.setPose and read for anchors), sceneGraph? (Cesium).
// TrackedHandle (tracked.create) — the selected aircraft's glyph and the
// follow target: viewFrom (ENU offset, read), and the annotation fields
// the shell reads: gevSelectionOrigin, gevTrackedId, gevLabelModel,
// gevDisplayPosition(), gevVisualPosition().
// Trail (trails.create): setPositions(Cartesian3[]), setVisible(bool),
// clear(), destroy(). TrailHead (trails.createHead): show (bool).
//
// The view: what the logic reads of the camera and the frame. `camera` is
// camera-shaped (positionWC, positionCartographic, directionWC, upWC,
// rightWC, heading, pitch, roll, frustum.fovy) and `scene` scene-shaped
// ({ camera, canvas.clientHeight, frameState.frameNumber }) for the shared
// helpers that take them (iconOrientation, focusDeemphasis); on Navara
// they are adapters over engine.camera.pose(), with the engine registered
// for the scene (engineFromViewer) so projections go through its projector.
/**
* @typedef {object} AircraftView
* @property {object} camera
* @property {object} scene
* @property {() => number} frameNumber One value per rendered frame.
* @property {() => number} viewportHeightPx
* @property {() => ((position: object) => boolean)} frustumTester For this
* frame: is a point (1 m sphere) inside or on the view frustum.
* @property {() => { isPointVisible(position: object): boolean }} horizon
* For this frame: the ellipsoid horizon test.
* @property {(position: object, result?: object) => ({x: number, y: number} | undefined)} worldToWindow
* @property {() => void} requestRender
* @property {(event: 'preRender'|'preUpdate'|'moveEnd', listener: Function) => () => void} on
* @property {object} surfaceOwner What groundSnap/meshFloor sample through
* (a viewer registered with its engine, or the engine).
* @property {object} surfaceScene What sampleMeshFloorCells takes.
* @property {() => void} holdFrames Evidence capture: stop the engine's own
* frame loop (QA only).
* @property {() => void} closeFrameLatch Evidence capture, one task later:
* let manual renders start without waiting for the loop's next frame.
* @property {() => void} releaseFrames
*/
/**
* @typedef {object} AircraftRenderer
* @property {'cesium'|'navara'} kind
* @property {object|null} engine The globe engine (null in unit tests that
* drive a bare viewer).
* @property {AircraftView} view
* @property {object} fleet attach(), detach(), attached(), visible(),
* setVisible(bool), add(spec) → SpriteHandle, remove(sprite),
* restoreOrder(), restoreOrderOnEnable().
* @property {object} models live(), setVisible(bool), loadFleet(spec),
* loadTracked(spec), preload(url) → Promise<ModelHandle>, add(model),
* remove(model), destroy(model), setPose(model, position, headingDeg).
* spec: { url, minimumPixelSize, scale, color, blendAmount, unlit, id }.
* @property {object} tracked create(spec) → TrackedHandle, remove(handle),
* isLive(handle), setImage(handle, image), setViewFrom(handle, enu),
* billboardSize(handle) → { width, height, scale, scaleByDistance } | null.
* spec: { image, width, height, scale, scaleByDistance,
* disableDepthTestDistance, position(), color() → colour, rotation() }.
* @property {object} follow start(handle) → stop, refocus(handle) → stop,
* release(), isFollowing(handle), current(), onChanged(listener) → remove.
* @property {object} trails create({ color, width }) → Trail,
* createHead({ id, show, positions() → Cartesian3[], color, width }) →
* TrailHead, removeHead(head).
* @property {(objects: { sprites: Iterable, models: Iterable }) => object[]} surfaceExclusions
* What a vertical surface probe must not hit: the layer's own drawings.
* @property {() => void} destroy
*/
/** The members every aircraft renderer has (shape checks, tests). */
export const AIRCRAFT_RENDERER_SHAPE = Object.freeze({
view: [
'frameNumber',
'viewportHeightPx',
'frustumTester',
'horizon',
'worldToWindow',
'requestRender',
'on',
'holdFrames',
'closeFrameLatch',
'releaseFrames',
],
fleet: [
'attach',
'detach',
'attached',
'visible',
'setVisible',
'add',
'remove',
'restoreOrder',
'restoreOrderOnEnable',
],
models: [
'live',
'setVisible',
'loadFleet',
'loadTracked',
'preload',
'add',
'remove',
'destroy',
'setPose',
],
tracked: [
'create',
'remove',
'isLive',
'setImage',
'setViewFrom',
'billboardSize',
],
follow: [
'start',
'refocus',
'release',
'isFollowing',
'current',
'onChanged',
],
trails: ['create', 'createHead', 'removeHead'],
});
/**
* The members of AIRCRAFT_RENDERER_SHAPE that `renderer` lacks
* (['group.member', …]); empty for a complete renderer.
*/
export function missingAircraftRendererMembers(renderer) {
const missing = [];
for (const key of ['kind', 'view', 'surfaceExclusions', 'destroy'])
if (renderer?.[key] === undefined) missing.push(key);
for (const [group, members] of Object.entries(AIRCRAFT_RENDERER_SHAPE))
for (const member of members)
if (typeof renderer?.[group]?.[member] !== 'function')
missing.push(`${group}.${member}`);
return missing;
}