Files
gods-eye-view/src/render/cesium/drawModels.js
T
Sameh Khamis e3865f462f 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.
2026-11-13 14:14:42 -08:00

618 lines
22 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* @module render/cesium/drawModels
* @description The Cesium draw port's `models` sets: one `Cesium.Model` per
* item in the set's collection, changed where it is. An update that keeps an
* item's `url` re-poses and restyles its model in place (position,
* orientation, scale, `axisScale` and pixel bounds, `shading`, `tint`,
* `colorBlend`, `maskColor`, `clip`, `environmentMap`, `displayRange`,
* `show`); only a new `url` loads again, and the old model keeps drawing
* until the new one is ready, so a swap never blinks. `ready` fires once per
* load, when the model has loaded and is posed. An item with its `gltf`
* bytes is built from them; its url is then not fetched.
*
* What Cesium has no option for runs each frame before the scene draws:
* `maxPixelSize` (the scale capped so the bounding sphere spans at most that
* many drawing-buffer pixels at its distance from the eye, as Cesium
* measures `minPixelSize`), `scaleByDistance`, `fadeByDistance` (the tint's
* alpha) and the set's `horizonCull`.
*
* A failed load fires `loadFailed` (after the frame Cesium reported it in,
* so a listener may change the set), and is tried again when its item is
* next updated, once `MODEL_RETRY_MS` has passed.
*
* `shading: 'thermal'` draws the model unlit and white-hot (its texture
* left out), then tinted as asked: a hot target, as the thermal views draw
* them. Heights are absolute: models clamp nothing.
*/
import * as Cesium from 'cesium';
const BLEND_MODES = {
highlight: Cesium.ColorBlendMode.HIGHLIGHT,
replace: Cesium.ColorBlendMode.REPLACE,
mix: Cesium.ColorBlendMode.MIX,
};
/**
* How long a failed load waits before an update of its item tries the url
* again (a fleet updates every frame; a dropped request or a server
* hiccup should not leave the item without its model for good).
*/
export const MODEL_RETRY_MS = 5000;
/** Cesium's own blend amount, for a `mix` that names none. */
const DEFAULT_MIX = 0.5;
let unlitShader = null;
let thermalShader = null;
/** Mask shaders by shading and colour: one per pair, shared by its models. */
const maskShaders = new Map();
/**
* The custom shader that paints `mask` where a model's `_TINT` vertex
* attribute marks it: drawn colour = colour × mix(1, mask, _TINT), unlit
* under `unlit` shading.
*/
function maskShaderOf(shading, mask) {
const key = `${shading === 'unlit' ? 'unlit' : 'pbr'}|${mask.toCssHexString()}`;
let shader = maskShaders.get(key);
if (!shader) {
shader = new Cesium.CustomShader({
mode: Cesium.CustomShaderMode.MODIFY_MATERIAL,
...(shading === 'unlit'
? { lightingModel: Cesium.LightingModel.UNLIT }
: {}),
uniforms: {
u_maskColor: {
type: Cesium.UniformType.VEC3,
value: new Cesium.Cartesian3(mask.red, mask.green, mask.blue),
},
},
fragmentShaderText: `
void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
vec3 mask = czm_srgbToLinear(u_maskColor);
material.diffuse *= mix(vec3(1.0), mask, fsInput.attributes.tint);
}`,
});
maskShaders.set(key, shader);
}
return shader;
}
/**
* The custom shader an entry's item draws with: its mask colour's (but under
* `thermal`), else its `shading`'s.
*/
function entryShader(entry) {
const shading = entry.item.shading;
if (entry.mask && shading !== 'thermal')
return maskShaderOf(shading, entry.mask);
return shaderOf(shading);
}
/**
* A clipping plane through the model's origin, keeping what is above it:
* the planes sit in the model matrix's frame, whose origin is the item's
* position and whose Z axis is the local vertical. One per model: a
* collection belongs to the model it clips.
*/
function belowOriginClip() {
return new Cesium.ClippingPlaneCollection({
planes: [new Cesium.ClippingPlane(Cesium.Cartesian3.UNIT_Z, 0)],
edgeWidth: 0,
});
}
/** The custom shader a `shading` draws with; undefined for `pbr`. */
function shaderOf(shading) {
if (shading === 'unlit')
return (unlitShader ??= new Cesium.CustomShader({
lightingModel: Cesium.LightingModel.UNLIT,
}));
if (shading === 'thermal')
return (thermalShader ??= new Cesium.CustomShader({
lightingModel: Cesium.LightingModel.UNLIT,
fragmentShaderText: `
void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
material.diffuse = vec3(1.0);
}`,
}));
return undefined;
}
/** A contract distance curve's value at `distance`: linear, clamped. */
export function nearFarValue(curve, distance) {
if (!curve) return 1;
const { near, nearValue, far, farValue } = curve;
if (!(far > near)) return distance <= near ? nearValue : farValue;
const t = Math.min(1, Math.max(0, (distance - near) / (far - near)));
return nearValue + (farValue - nearValue) * t;
}
/**
* The scale that caps a model's bounding sphere (radius `radiusM` at scale
* 1) at `maxPixelSize` pixels, `metresPerPixel` at its distance; `scale`
* when it is under the cap already.
*/
export function cappedScale(scale, radiusM, metresPerPixel, maxPixelSize) {
if (
!(maxPixelSize > 0) ||
!(radiusM > 0) ||
!(metresPerPixel > 0) ||
!Number.isFinite(metresPerPixel)
)
return scale;
const cap = (maxPixelSize * metresPerPixel) / (2 * radiusM);
return Math.min(scale, cap);
}
const scratchHpr = new Cesium.HeadingPitchRoll();
const scratchAxes = new Cesium.Cartesian3();
const scratchMatrix = new Cesium.Matrix4();
const scratchSphere = new Cesium.BoundingSphere();
const scratchColor = new Cesium.Color();
/** The colour last written to each model. */
const writtenColors = new WeakMap();
/** What the per-frame pass found, for a model it does not run on. */
const STILL = Object.freeze({ scale: 1, alpha: 1, shown: true });
/** An item's position as Cesium's, into `result`. */
function positionOf(pos, result) {
if ('x' in pos)
return Cesium.Cartesian3.fromElements(pos.x, pos.y, pos.z, result);
return Cesium.Cartesian3.fromDegrees(
pos.lon,
pos.lat,
pos.height ?? 0,
Cesium.Ellipsoid.WGS84,
result,
);
}
/** A tint as a key: a CSS string as it is, an RGBA array joined. */
const tintKey = (tint) =>
tint === undefined || tint === null
? null
: typeof tint === 'string'
? tint
: tint.join(',');
/** Why a load failed, as `loadFailed` reports it. */
function failureMessage(error) {
if (error instanceof Error && error.message) return error.message;
const text = error === undefined || error === null ? '' : String(error);
return text && text !== '[object Object]' ? text : 'the model did not load';
}
/** Whether an item needs the per-frame pass. */
const needsFrame = (item, spec) =>
item.maxPixelSize > 0 ||
Boolean(item.scaleByDistance) ||
Boolean(item.fadeByDistance) ||
Boolean(spec.horizonCull);
/**
* The models part of a Cesium draw port.
* @param {{scene: object, toColor: Function, pickId: Function,
* replaceHost: Function, horizonNow: () => object|null,
* requestRender: () => void}} options From the draw port: its colour
* conversion, pick ids, host swap, horizon and render request.
*/
export function createModelSets({
scene,
toColor,
pickId,
replaceHost,
horizonNow,
requestRender,
}) {
/** The set's host, made once: its models are changed where they are. */
function hostOf(record) {
if (record.host && !record.host.isDestroyed?.()) return record.host;
const host = new Cesium.PrimitiveCollection();
host.loading = 0;
host.failed = 0;
record.models = new Map();
replaceHost(record, host);
return host;
}
/** Each live entry's pick id, for height queries to see through. */
function notePickIds(record) {
record.pickIds = [];
for (const entry of record.models.values())
record.pickIds.push(entry.pickId);
}
function drop(record, id) {
const entry = record.models.get(id);
if (!entry) return;
record.models.delete(id);
unload(record, entry);
}
/** Let go of an entry's models and its load. */
function unload(record, entry) {
const host = record.host;
cancel(record, entry);
if (entry.model && host && !host.isDestroyed()) host.remove(entry.model);
entry.model = null;
entry.modelUrl = null;
}
/** Start loading `entry`'s url; the model it draws now stays until ready. */
function load(record, entry) {
const host = hostOf(record);
cancel(record, entry);
const token = {};
entry.token = token;
entry.url = entry.item.url;
const url = entry.url;
// A load counts until it is ready, fails or is superseded; once.
host.loading += 1;
let settled = false;
const item = entry.item;
const current = () =>
entry.token === token && record.host === host && !host.isDestroyed();
const settleLoad = () => settle(false);
const settle = (failed, error) => {
if (settled) return;
settled = true;
if (entry.settleLoad === settleLoad) entry.settleLoad = null;
host.loading -= 1;
if (failed && entry.token === token) {
entry.failed = true;
entry.failedAt = Date.now();
host.failed += 1;
// Told once Cesium is done with the frame it raised this in; not
// when the item has moved on to another load meanwhile.
const message = failureMessage(error);
queueMicrotask(() => {
if (current() && entry.failed)
record.listeners.loadFailed.fire(item.id, message);
});
}
requestRender();
};
entry.settleLoad = settleLoad;
// Bytes loaded already are drawn from: the url is then only the base
// path (Cesium's glTF cache keys by it, so each model keeps its own).
const source = item.gltf
? { gltf: item.gltf, basePath: item.url }
: { url: item.url };
Cesium.Model.fromGltfAsync({
...source,
modelMatrix: matrixOf(entry, new Cesium.Matrix4()),
scale: item.scale ?? 1,
minimumPixelSize: item.minPixelSize ?? 0,
maximumScale: item.maxScale,
customShader: entryShader(entry),
clippingPlanes:
item.clip === 'belowOrigin' ? belowOriginClip() : undefined,
environmentMapOptions: { enabled: item.environmentMap !== false },
// Shown once ready and placed: the pass below shows it.
show: false,
// All textures before ready, so a settled capture is the whole model.
incrementallyLoadTextures: false,
// Off the frame-spread job queue that photoreal tiles contend for, so
// a model's readiness stays bounded while tiles stream.
asynchronous: false,
id: entry.pickId,
}).then(
(model) => {
if (!current()) {
settle(false);
return model.destroy();
}
entry.next = model;
entry.styled = null;
style(record, entry, model, true);
host.add(model);
model.readyEvent.addEventListener(() => {
if (!current() || entry.next !== model) return settle(false);
// The old model goes as the new one draws.
if (entry.model) host.remove(entry.model);
entry.model = model;
entry.modelUrl = url;
entry.next = null;
entry.radius = 0;
entry.styled = null;
style(record, entry, model, true);
settle(false);
record.listeners.ready.fire(item.id);
});
// A failed load is let go (Cesium would keep drawing frames for
// it); the failure stays for `whenSettled` until the item changes.
model.errorEvent.addEventListener((error) => {
if (current() && entry.next === model) {
entry.next = null;
// Cesium raises this inside the model's update: removing it
// (which destroys it) waits until that is done.
queueMicrotask(() => {
if (!host.isDestroyed() && host.contains(model))
host.remove(model);
});
}
settle(true, error);
});
requestRender();
},
(error) => settle(true, error),
);
}
function matrixOf(entry, result) {
const o = entry.item.orientation ?? {};
scratchHpr.heading = o.heading ?? 0;
scratchHpr.pitch = o.pitch ?? 0;
scratchHpr.roll = o.roll ?? 0;
Cesium.Transforms.headingPitchRollToFixedFrame(
entry.at,
scratchHpr,
Cesium.Ellipsoid.WGS84,
undefined,
result,
);
const axes = entry.item.axisScale;
if (axes && (axes[0] !== 1 || axes[1] !== 1 || axes[2] !== 1)) {
// Cesium's glTF axis correction (Y up to Z up, then Z forward to X
// forward) puts the model's own Z on local X, its X on local Y and
// its Y on local Z.
scratchAxes.x = axes[2];
scratchAxes.y = axes[0];
scratchAxes.z = axes[1];
Cesium.Matrix4.multiplyByScale(result, scratchAxes, result);
}
return result;
}
/**
* Pose and style `model` as its entry's item says. What the per-frame
* pass sets (scale, colour alpha, show) is set here from what it found
* last, so an update between frames draws the same.
*/
function style(record, entry, model, force = false) {
const item = entry.item;
matrixOf(entry, scratchMatrix);
Cesium.Matrix4.clone(scratchMatrix, model.modelMatrix);
const was = force ? null : entry.styled;
const minimum = item.minPixelSize ?? 0;
if (model.minimumPixelSize !== minimum) model.minimumPixelSize = minimum;
if (model.maximumScale !== item.maxScale)
model.maximumScale = item.maxScale;
const shader = entryShader(entry);
if (model.customShader !== shader) model.customShader = shader;
const clip = item.clip === 'belowOrigin';
if (Boolean(model.clippingPlanes) !== clip)
model.clippingPlanes = clip ? belowOriginClip() : undefined;
const environment = item.environmentMap !== false;
const manager = model.environmentMapManager;
if (manager && manager.enabled !== environment)
manager.enabled = environment;
const range = item.displayRange;
const rangeKey = range ? `${range[0]},${range[1]}` : '';
if (!was || was.range !== rangeKey)
model.distanceDisplayCondition =
range && range[1] > range[0]
? new Cesium.DistanceDisplayCondition(range[0], range[1])
: undefined;
// Without a tint there is nothing to blend in: the model's own colour.
const blend = entry.tint ? item.colorBlend : undefined;
const mode = BLEND_MODES[blend?.mode] ?? Cesium.ColorBlendMode.HIGHLIGHT;
if (model.colorBlendMode !== mode) model.colorBlendMode = mode;
const amount = blend?.mode === 'mix' ? (blend.amount ?? DEFAULT_MIX) : 0.5;
if (model.colorBlendAmount !== amount) model.colorBlendAmount = amount;
// An empty `displayRange` shows nothing.
const hidden = range && !(range[1] > range[0]);
if (entry.styled?.range !== rangeKey) entry.styled = { range: rangeKey };
entry.dynamic = needsFrame(item, record.spec);
apply(entry, model, entry.frame ?? STILL, hidden);
}
/**
* The parts the per-frame pass computes: the scale (by distance and the
* pixel cap), the tint's alpha (fade) and whether it shows (cull).
*/
function apply(entry, model, frame, hidden = false) {
const item = entry.item;
const scale = (item.scale ?? 1) * frame.scale;
if (model.scale !== scale) model.scale = scale;
const color = Cesium.Color.clone(
entry.tint ?? Cesium.Color.WHITE,
scratchColor,
);
color.alpha *= frame.alpha;
// Written only when what is asked changes, so a theme's own write to a
// model's colour stands until then.
const written = writtenColors.get(model);
if (!written || !Cesium.Color.equals(written, color)) {
writtenColors.set(model, Cesium.Color.clone(color, written));
model.color = color;
}
const show =
item.show !== false && frame.shown && !hidden && model.ready === true;
if (model.show !== show) model.show = show;
}
/** Add or change items, by id; true once handled (always, for models). */
function upsert(record, list) {
hostOf(record);
for (const item of list) put(record, item);
notePickIds(record);
requestRender();
return true;
}
function put(record, item) {
let entry = record.models.get(item.id);
if (!entry) {
entry = {
item,
url: null,
modelUrl: null,
model: null,
at: new Cesium.Cartesian3(),
tint: null,
tintKey: undefined,
mask: null,
maskKey: undefined,
radius: 0,
next: null,
token: null,
failed: false,
failedAt: 0,
settleLoad: null,
styled: null,
dynamic: false,
frame: null,
pickId: pickId(record, item),
};
record.models.set(item.id, entry);
} else {
entry.item = item;
// The pick id is the model's own object: changed where it is.
entry.pickId.meta = item.meta;
}
positionOf(item.pos, entry.at);
// A fleet re-poses every frame with the same tint: parsed when it changes.
const tint = tintKey(item.tint);
if (entry.tintKey !== tint) {
entry.tintKey = tint;
entry.tint = tint === null ? null : toColor(item.tint);
}
const mask = tintKey(item.maskColor);
if (entry.maskKey !== mask) {
entry.maskKey = mask;
entry.mask = mask === null ? null : toColor(item.maskColor);
}
if (entry.url !== item.url && item.url === entry.modelUrl) {
// Back to the url it draws: the load in between is not wanted.
cancel(record, entry);
entry.url = entry.modelUrl;
}
// The model it draws keeps up while another loads.
for (const model of [entry.model, entry.next])
if (model) style(record, entry, model);
const retry = entry.failed && Date.now() - entry.failedAt >= MODEL_RETRY_MS;
if (entry.url !== item.url || retry) load(record, entry);
}
/** Stop the entry's load in flight, keeping the model it draws. */
function cancel(record, entry) {
const host = record.host;
entry.settleLoad?.();
entry.token = null;
if (entry.next && host && !host.isDestroyed()) host.remove(entry.next);
entry.next = null;
if (entry.failed && host) host.failed -= 1;
entry.failed = false;
}
/**
* The set's items as they are now (after a `set`, `remove` or `clear`):
* models of items gone are dropped, the rest kept or changed in place.
*/
function build(record) {
hostOf(record);
for (const id of [...record.models.keys()])
if (!record.items.has(id)) drop(record, id);
for (const item of record.items.values()) put(record, item);
notePickIds(record);
}
/** Each frame, before it draws: distance curves, pixel caps and the cull. */
function beforeRender(sets) {
const eye = scene.camera?.positionWC;
if (!eye) return;
const width = scene.drawingBufferWidth ?? scene.canvas?.width ?? 0;
const height = scene.drawingBufferHeight ?? scene.canvas?.height ?? 0;
let horizon;
for (const record of sets) {
if (record.kind !== 'models' || !record.models) continue;
for (const entry of record.models.values()) {
if (!entry.dynamic) {
if (entry.frame) {
entry.frame = null;
for (const model of [entry.model, entry.next])
if (model) style(record, entry, model);
}
continue;
}
const item = entry.item;
const at = entry.at;
const distance = Cesium.Cartesian3.distance(eye, at);
const frame = (entry.frame ??= { scale: 1, alpha: 1, shown: true });
frame.alpha = item.fadeByDistance
? Math.min(
1,
Math.max(0, nearFarValue(item.fadeByDistance, distance)),
)
: 1;
let shown = frame.alpha > 0;
if (record.spec.horizonCull) {
horizon ??= horizonNow();
if (horizon && !horizon.isPointVisible(at)) shown = false;
}
frame.shown = shown;
let scale = item.scaleByDistance
? nearFarValue(item.scaleByDistance, distance)
: 1;
const model = entry.model;
const itemScale = item.scale ?? 1;
if (
item.maxPixelSize > 0 &&
itemScale > 0 &&
model?.ready &&
width > 0 &&
height > 0
) {
const radius = radiusOf(entry, model);
// Pixels at the model's centre: a sphere around the eye has none.
scratchSphere.center = at;
scratchSphere.radius = 0;
const metresPerPixel = scene.camera.getPixelSize(
scratchSphere,
width,
height,
);
if (radius > 0)
scale =
cappedScale(
itemScale * scale,
radius,
metresPerPixel,
item.maxPixelSize,
) / itemScale;
}
frame.scale = scale;
const hidden =
item.displayRange && !(item.displayRange[1] > item.displayRange[0]);
for (const m of [entry.model, entry.next])
if (m) apply(entry, m, frame, hidden);
}
}
}
/**
* The model's bounding radius at scale 1, read once it is drawn at a
* scale (Cesium's sphere is at its scale, capped by `maximumScale`); 0
* until then.
*/
function radiusOf(entry, model) {
if (entry.radius > 0) return entry.radius;
const own = Math.min(model.scale, model.maximumScale ?? Infinity);
if (!(own > 0)) return 0;
entry.radius = model.boundingSphere.radius / own;
return entry.radius;
}
/** The set's options changed: whether models need the frame pass. */
function restyle(record) {
if (!record.models) return;
for (const entry of record.models.values())
entry.dynamic = needsFrame(entry.item, record.spec);
}
return { build, upsert, beforeRender, restyle };
}