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

+88
View File
@@ -0,0 +1,88 @@
// Engine-neutral layer colours (phase 3): the colour constants the layers
// used to build as Cesium.Color, without Cesium.
//
// An Rgba has Cesium.Color's fields and the methods the layers call on their
// colours (`withAlpha`, `clone`, `equals`), so it is accepted wherever a
// Cesium property clones a colour from its fields (Billboard.color,
// Model.color, a billboard graphics' colour), and a renderer on another
// engine reads the same four numbers (`rgba()` gives them as an array).
// Components are 0..1 floats computed exactly as Cesium computes them
// (`fromCssColorString`: byte / 255), so a constant here equals the
// Cesium.Color it replaces bit for bit (color.test.mjs).
export class Rgba {
constructor(red = 1, green = 1, blue = 1, alpha = 1) {
this.red = red;
this.green = green;
this.blue = blue;
this.alpha = alpha;
}
/** The same colour with `alpha` (Cesium.Color#withAlpha). */
withAlpha(alpha, result) {
if (!result) return new Rgba(this.red, this.green, this.blue, alpha);
result.red = this.red;
result.green = this.green;
result.blue = this.blue;
result.alpha = alpha;
return result;
}
clone(result) {
return this.withAlpha(this.alpha, result);
}
/** Field equality with an Rgba or a Cesium.Color. */
equals(other) {
return (
this === other ||
(!!other &&
this.red === other.red &&
this.green === other.green &&
this.blue === other.blue &&
this.alpha === other.alpha)
);
}
/** `[red, green, blue, alpha]`, 0..1. */
rgba() {
return [this.red, this.green, this.blue, this.alpha];
}
}
const HEX = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})?$/i;
/**
* A colour from `#rrggbb` or `#rrggbbaa`, as Cesium.Color.fromCssColorString
* reads it.
* @param {string} css
* @returns {Rgba}
*/
export function rgbaFromCss(css) {
const match = HEX.exec(String(css).trim());
if (!match) throw new TypeError(`Unsupported colour: ${css}`);
return new Rgba(
parseInt(match[1], 16) / 255.0,
parseInt(match[2], 16) / 255.0,
parseInt(match[3], 16) / 255.0,
parseInt(match[4] ?? 'ff', 16) / 255.0,
);
}
/** A frozen colour constant. */
export const constantRgba = (red, green, blue, alpha = 1) =>
Object.freeze(new Rgba(red, green, blue, alpha));
/** Cesium.Color.WHITE. */
export const WHITE = constantRgba(1, 1, 1, 1);
/** Cesium.Color.CYAN (#00FFFF). */
export const CYAN = constantRgba(0, 1, 1, 1);
/**
* A distance scale for sprites (Cesium.NearFarScalar's fields): the scale is
* `nearValue` at `near` metres from the camera and `farValue` at `far`.
* Plain data, accepted by Cesium's billboard setters, which copy the fields.
*/
export function nearFarScale(near, nearValue, far, farValue) {
return { near, nearValue, far, farValue };
}
+77
View File
@@ -0,0 +1,77 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import * as Cesium from 'cesium';
import {
CYAN,
Rgba,
WHITE,
constantRgba,
nearFarScale,
rgbaFromCss,
} from './color.js';
const fields = (color) => [color.red, color.green, color.blue, color.alpha];
test('css colours equal Cesium.Color.fromCssColorString bit for bit', () => {
for (const css of ['#FFB800', '#DCEEFF', '#00d4ff', '#39d0ff', '#ffd16680']) {
assert.deepEqual(
fields(rgbaFromCss(css)),
fields(Cesium.Color.fromCssColorString(css)),
css,
);
}
assert.throws(() => rgbaFromCss('teal'), /Unsupported colour/);
});
test('the named constants equal Cesium.Color.WHITE and CYAN', () => {
assert.deepEqual(fields(WHITE), fields(Cesium.Color.WHITE));
assert.deepEqual(fields(CYAN), fields(Cesium.Color.CYAN));
assert.ok(Object.isFrozen(WHITE) && Object.isFrozen(CYAN));
assert.ok(CYAN.equals(Cesium.Color.CYAN));
});
test('withAlpha, clone and equals behave as Cesium.Color', () => {
const amber = rgbaFromCss('#FFB800');
const cesium = Cesium.Color.fromCssColorString('#FFB800');
assert.deepEqual(
fields(amber.withAlpha(0.45)),
fields(cesium.withAlpha(0.45)),
);
const scratch = new Rgba();
assert.equal(amber.withAlpha(0.2, scratch), scratch);
assert.deepEqual(fields(scratch), fields(cesium.withAlpha(0.2)));
assert.deepEqual(
fields(CYAN.withAlpha(0)),
fields(Cesium.Color.CYAN.withAlpha(0)),
);
assert.ok(amber.clone().equals(amber));
assert.notEqual(amber.clone(), amber);
assert.deepEqual(amber.rgba(), fields(cesium));
assert.ok(Object.isFrozen(constantRgba(1, 0, 0)));
});
test('Cesium billboards and models take an Rgba as their colour', () => {
const collection = new Cesium.BillboardCollection();
const billboard = collection.add({
position: Cesium.Cartesian3.fromDegrees(0, 0, 10),
color: rgbaFromCss('#FFB800').withAlpha(0.5),
scaleByDistance: nearFarScale(1000, 3, 8_000_000, 0.5),
});
assert.ok(billboard.color instanceof Cesium.Color);
assert.ok(
billboard.color.equals(
Cesium.Color.fromCssColorString('#FFB800').withAlpha(0.5),
),
);
assert.ok(billboard.scaleByDistance instanceof Cesium.NearFarScalar);
assert.ok(
Cesium.NearFarScalar.equals(
billboard.scaleByDistance,
new Cesium.NearFarScalar(1000, 3, 8_000_000, 0.5),
),
);
billboard.color = CYAN;
assert.ok(billboard.color.equals(Cesium.Color.CYAN));
assert.notEqual(billboard.color, CYAN, 'the billboard keeps its own copy');
collection.destroy();
});