Files
gods-eye-view/src/render/cesium/drawModels.js
T
Denis Groshev 0620d01140 Merge main into denis/iss-live-telemetry
Conflicts: the locale catalogs, package boundaries and format scope are
three-way merges (entries main removed, such as displayPanelScroll.js,
stay removed); applicationShell.js and ContextView.vue keep main's Space
Missions panel and the STATION and LIVE wiring, moved back into
_initGlobalContextPanel; installations take main's feedback module, and
their label box joins main's card-on-top click rule; ports.test.mjs lists
modelParts and modelNodes; CURRENT-STATE.md keeps both edits.

zh-Hant is regenerated from zh-CN, as main now requires. "Below" keeps
main's translations.
2026-11-19 17:07:48 +01:00

1386 lines
47 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`,
* `nodes`, `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), the set's `horizonCull`, and its `recede`: the tint's alpha times
* the focus and haze (`render/recession.js`), written again once that moves
* by more than `RECEDE_WRITE_EPSILON`. A model of a set that does not
* recede draws at its tint's alpha times its `focus`.
*
* 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.
*
* An item's `parts` (with `modelParts`) poses the moving parts of a model
* whose mesh carries `_PART` and whose root node carries a part table
* (`render/modelParts.js`): its model then draws with a custom shader of
* its own whose vertex stage moves each vertex by its part's matrix, read
* from a small float texture (`PARTS_VERTEX` says its layout), with the
* item's mask, unlit or thermal look in the same shader; a moved part's
* material normal turns with it. The texture is written again in place
* when the part state changes, and each frame while a part of a model in
* view spins (frames are asked for while one does). Spins keep their angle
* across a change of rate. A model at rest, or without a part table, draws
* exactly as it would without `parts`, on the shared shaders above. Cesium
* culls and picks a model by its bounds as its file draws it, so a part
* moved outside them is drawn only while those bounds are in view.
*/
import * as Cesium from 'cesium';
import {
recedeFactors,
recedeFrame,
recedeParams,
recededAlpha,
} from '../recession.js';
import { customShaderTexture } from './internals.js';
import {
glbJson,
gltfMeshMatrix,
gltfPartTable,
partMatrices,
PART_HIGHLIGHT,
asksHighlight,
} from '../modelParts.js';
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;
/**
* How far a receding model's emphasis (focus and haze) moves before its
* colour is written again: an eye in motion would otherwise write every
* model's colour every frame.
*/
export const RECEDE_WRITE_EPSILON = 0.005;
/**
* Each model's posed nodes (`ModelItem.nodes`): name → the 16 numbers last
* written, so an update that keeps a node's matrix writes nothing.
*/
const posedNodes = new WeakMap();
/** A posed name the model has no node for: looked up once, then skipped. */
const NO_NODE = Symbol('no such node');
const scratchNodeMatrix = new Cesium.Matrix4();
/**
* Write the item's node transforms to `model` once it is ready: changed
* ones only, and a node whose name left the map back to its authored pose.
* Names the model lacks are skipped.
*/
function poseNodes(item, model) {
if (model.ready !== true) return;
const wanted = item.nodes;
let posed = posedNodes.get(model);
if (!wanted && !posed) return;
if (!posed) posedNodes.set(model, (posed = new Map()));
for (const [name, last] of posed) {
if (wanted && Object.hasOwn(wanted, name)) continue;
posed.delete(name);
if (last === NO_NODE) continue;
const node = model.getNode(name);
if (node) node.matrix = Cesium.Matrix4.clone(node.originalMatrix);
}
if (!wanted) return;
for (const name of Object.keys(wanted)) {
const matrix = wanted[name];
if (!matrix || matrix.length < 16) continue;
const last = posed.get(name);
if (last === NO_NODE) continue;
if (last && sameMatrix(last, matrix)) continue;
const node = model.getNode(name);
if (!node) {
posed.set(name, NO_NODE);
continue;
}
// The last matrix written, kept in one array per node, copied in place.
let kept = last;
if (!(kept instanceof Float64Array)) {
kept = new Float64Array(16);
posed.set(name, kept);
}
for (let i = 0; i < 16; i++) kept[i] = matrix[i];
// The node copies the matrix it is given.
node.matrix = Cesium.Matrix4.fromArray(matrix, 0, scratchNodeMatrix);
}
}
function sameMatrix(a, b) {
for (let i = 0; i < 16; i++) if (a[i] !== b[i]) return false;
return true;
}
/** 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;
// Kept while its shading and mask colour are: a fleet re-poses every
// frame with the same look.
if (entry.shaderShading === shading && entry.shaderMask === entry.mask)
return entry.shader;
entry.shader =
entry.mask && shading !== 'thermal'
? maskShaderOf(shading, entry.mask)
: shaderOf(shading);
entry.shaderShading = shading;
entry.shaderMask = entry.mask;
return entry.shader;
}
/**
* 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;
}
/** The colour a part with `highlight: true` is drawn in. */
const PART_HIGHLIGHT_COLOR = '#ffc400';
/** How much of a highlighted part's colour the highlight replaces. */
const PART_HIGHLIGHT_MIX = 0.6;
/** Texels in a part's row of its texture. */
const PART_TEXELS = 8;
/** Floats in a part's row: `PART_TEXELS` RGBA texels. */
const PART_FLOATS = PART_TEXELS * 4;
/** A texel's centre across a part's row, as a texture coordinate. */
const texelAt = (i) => ((i + 0.5) / PART_TEXELS).toFixed(4);
/**
* The vertex stage of a posed model. A part's row of the texture holds the
* three rows of its matrix in the mesh's own frame (texels 0..2), the three
* rows of that matrix's inverse transpose (3..5; texel 3's alpha is 1 where
* the part is moved, 0 where it is at rest), and its highlight colour (6,
* alpha 0 for none). Each vertex is moved by its part's matrix; the normal
* turn is passed on in eye space, for the fragment stage to turn the
* material's own normal (normal maps and back-face flips kept) by it.
* Positions are the mesh's own (before its node's transform), as are the
* matrices written for it, and as `czm_normal` takes them to eye space.
*/
const PARTS_VERTEX = `
void vertexMain(VertexInput vsInput, inout czm_modelVertexOutput vsOutput) {
float row = (floor(vsInput.attributes.part + 0.5) + 0.5) / u_partRows;
vec4 r0 = texture(u_partMatrices, vec2(${texelAt(0)}, row));
vec4 r1 = texture(u_partMatrices, vec2(${texelAt(1)}, row));
vec4 r2 = texture(u_partMatrices, vec2(${texelAt(2)}, row));
vec4 n0 = texture(u_partMatrices, vec2(${texelAt(3)}, row));
v_partHighlight = texture(u_partMatrices, vec2(${texelAt(6)}, row));
vec4 p = vec4(vsOutput.positionMC, 1.0);
vsOutput.positionMC = vec3(dot(r0, p), dot(r1, p), dot(r2, p));
v_partMoved = n0.a;
if (n0.a > 0.5) {
vec4 n1 = texture(u_partMatrices, vec2(${texelAt(4)}, row));
vec4 n2 = texture(u_partMatrices, vec2(${texelAt(5)}, row));
mat3 turn = transpose(mat3(n0.xyz, n1.xyz, n2.xyz));
v_partNormalEC = czm_normal * turn * inverse(czm_normal);
} else {
v_partNormalEC = mat3(1.0);
}
}`;
/**
* A posed model's custom shader: its parts moved (`PARTS_VERTEX`), drawn in
* `shading` with `mask` painted where `_TINT` marks the model (not under
* `thermal`), and its highlighted parts in their colour. Lit, a moved
* part's material normal is turned with it; the body and parts at rest keep
* theirs as the material made them. `data` is the part texture's first
* contents, `rows` its parts.
*/
function partShaderOf(shading, mask, data, rows) {
const lit = shading !== 'unlit' && shading !== 'thermal';
const masked = Boolean(mask) && shading !== 'thermal';
return new Cesium.CustomShader({
mode: Cesium.CustomShaderMode.MODIFY_MATERIAL,
...(lit ? {} : { lightingModel: Cesium.LightingModel.UNLIT }),
uniforms: {
u_partMatrices: {
type: Cesium.UniformType.SAMPLER_2D,
value: partTexture(data, rows),
},
u_partRows: { type: Cesium.UniformType.FLOAT, value: rows },
...(masked
? {
u_maskColor: {
type: Cesium.UniformType.VEC3,
value: new Cesium.Cartesian3(mask.red, mask.green, mask.blue),
},
}
: {}),
},
varyings: {
v_partNormalEC: Cesium.VaryingType.MAT3,
v_partMoved: Cesium.VaryingType.FLOAT,
v_partHighlight: Cesium.VaryingType.VEC4,
},
vertexShaderText: PARTS_VERTEX,
fragmentShaderText: `
void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
${
lit
? ` if (v_partMoved > 0.5)
material.normalEC = normalize(v_partNormalEC * material.normalEC);`
: ''
}
${shading === 'thermal' ? ' material.diffuse = vec3(1.0);' : ''}
${
masked
? ` vec3 mask = czm_srgbToLinear(u_maskColor);
material.diffuse *= mix(vec3(1.0), mask, fsInput.attributes.tint);`
: ''
}
if (v_partHighlight.a > 0.0) {
vec3 highlight = czm_srgbToLinear(v_partHighlight.rgb);
material.diffuse = mix(material.diffuse, highlight, ${PART_HIGHLIGHT_MIX.toFixed(2)});
material.emissive = max(material.emissive, highlight * 0.5);
}
}`,
});
}
/** A part texture's contents as a texture uniform: `PART_TEXELS` float texels a row, read unfiltered. */
function partTexture(data, rows) {
return new Cesium.TextureUniform({
typedArray: data,
width: PART_TEXELS,
height: rows,
pixelFormat: Cesium.PixelFormat.RGBA,
pixelDatatype: Cesium.PixelDatatype.FLOAT,
repeat: false,
minificationFilter: Cesium.TextureMinificationFilter.NEAREST,
magnificationFilter: Cesium.TextureMagnificationFilter.NEAREST,
});
}
/** An affine column-major 4×4's inverse. */
function inverseAffine(m) {
const [a, b, c] = [m[0], m[1], m[2]];
const [d, e, f] = [m[4], m[5], m[6]];
const [g, h, i] = [m[8], m[9], m[10]];
const A = e * i - f * h;
const B = -(b * i - c * h);
const C = b * f - c * e;
const det = a * A + d * B + g * C;
if (!(Math.abs(det) > 1e-30)) return null;
const r = 1 / det;
const out = [
A * r,
B * r,
C * r,
0,
-(d * i - f * g) * r,
(a * i - c * g) * r,
-(a * f - c * d) * r,
0,
(d * h - e * g) * r,
-(a * h - b * g) * r,
(a * e - b * d) * r,
0,
0,
0,
0,
1,
];
for (let row = 0; row < 3; row++)
out[12 + row] = -(
out[row] * m[12] +
out[4 + row] * m[13] +
out[8 + row] * m[14]
);
return out;
}
/** What a glTF document (or GLB) says of its parts: its table and mesh frame; null without a table. */
const partInfos = new WeakMap();
/** `source`'s part table and mesh frame, read once; null for a model without moving parts. */
function partInfoOf(source) {
if (partInfos.has(source)) return partInfos.get(source);
let info = null;
try {
const json = source instanceof Uint8Array ? glbJson(source) : source;
const table = gltfPartTable(json);
const mesh = table && gltfMeshMatrix(json);
const meshInverse = mesh && inverseAffine(mesh);
if (table && table.parts.length > 1 && meshInverse)
info = { table, mesh, meshInverse };
} catch {
// A malformed table: the model draws whole.
info = null;
}
partInfos.set(source, info);
return info;
}
/** Whether a part state asks for anything. */
const asksParts = (state) =>
Boolean(state) &&
typeof state === 'object' &&
['spin', 'deploy', 'poses'].some(
(key) => state[key] && Object.keys(state[key]).length > 0,
);
/** Scratch for one model's part matrices and flags, and one matrix's rows. */
let scratchParts = new Float64Array(16 * 32);
let scratchFlags = new Uint8Array(32);
const scratchRow = new Float64Array(4);
const scratchL = new Float64Array(12);
/** How far from the identity a part's matrix may be and still be at rest. */
const AT_REST_EPSILON = 1e-9;
/** Highlight colours by what was asked, read once (a few at most). */
const highlightColors = new Map();
/**
* The colour a part's `highlight` asks for, read once: `true` the
* renderer's own, a colour that parses as itself; null for anything else
* (drawn without a highlight).
*/
export function partHighlightColor(value) {
if (!asksHighlight(value)) return null;
const key = value === true ? PART_HIGHLIGHT_COLOR : String(value);
let color = highlightColors.get(key);
if (color === undefined) {
if (value === true || typeof value === 'string')
color = Cesium.Color.fromCssColorString(key.trim()) ?? null;
else color = new Cesium.Color(value[0], value[1], value[2], 1);
if (highlightColors.size >= 256) highlightColors.clear();
highlightColors.set(key, color);
}
return color;
}
/**
* Write a model's part texture into `data` (`PART_FLOATS` a part, the
* layout `PARTS_VERTEX` reads) for `state` at `timeS`: for each part the
* rows of its matrix in the mesh's own frame, L = meshInverse · X · mesh,
* then the rows of L's inverse transpose (normals turn by it, exact under a
* stretch or a mesh frame that is not a rotation) with whether the part is
* moved, then its highlight colour. Whether any part is not at rest.
*/
export function writePartTexture(info, state, timeS, scale, data) {
const { table, mesh, meshInverse } = info;
const n = table.parts.length;
if (scratchParts.length < n * 16) {
scratchParts = new Float64Array(n * 16);
scratchFlags = new Uint8Array(n);
}
const posed = partMatrices(table, state, timeS, scratchParts, {
flags: scratchFlags,
scale,
});
const poses = state?.poses;
const x = scratchParts;
const ix = scratchRow;
const L = scratchL;
for (let k = 0; k < n; k++) {
const o = k * 16;
const d = k * PART_FLOATS;
let moved = false;
for (let row = 0; row < 3; row++) {
// (meshInverse · X) row `row`, as four column entries.
for (let col = 0; col < 4; col++) {
let sum = 0;
for (let j = 0; j < 4; j++)
sum += meshInverse[j * 4 + row] * x[o + col * 4 + j];
ix[col] = sum;
}
for (let col = 0; col < 4; col++) {
let sum = 0;
for (let j = 0; j < 4; j++) sum += ix[j] * mesh[col * 4 + j];
L[row * 4 + col] = sum;
data[d + row * 4 + col] = sum;
if (Math.abs(sum - (row === col ? 1 : 0)) > AT_REST_EPSILON)
moved = true;
}
}
// The inverse transpose of L's 3×3: its cofactors over its determinant.
const a = L[0];
const b = L[1];
const c = L[2];
const e = L[4];
const f = L[5];
const g = L[6];
const h = L[8];
const i = L[9];
const j = L[10];
const c00 = f * j - g * i;
const c01 = -(e * j - g * h);
const c02 = e * i - f * h;
const c10 = -(b * j - c * i);
const c11 = a * j - c * h;
const c12 = -(a * i - b * h);
const c20 = b * g - c * f;
const c21 = -(a * g - c * e);
const c22 = a * f - b * e;
const det = a * c00 + b * c01 + c * c02;
const nd = d + 12;
// At rest, or hidden (collapsed to a point): normals as they are.
const turned = moved && Math.abs(det) > 1e-12;
const r = turned ? 1 / det : 0;
data[nd] = turned ? c00 * r : 1;
data[nd + 1] = turned ? c01 * r : 0;
data[nd + 2] = turned ? c02 * r : 0;
data[nd + 3] = turned ? 1 : 0;
data[nd + 4] = turned ? c10 * r : 0;
data[nd + 5] = turned ? c11 * r : 1;
data[nd + 6] = turned ? c12 * r : 0;
data[nd + 7] = 0;
data[nd + 8] = turned ? c20 * r : 0;
data[nd + 9] = turned ? c21 * r : 0;
data[nd + 10] = turned ? c22 * r : 1;
data[nd + 11] = 0;
const color =
scratchFlags[k] & PART_HIGHLIGHT
? partHighlightColor(poses?.[table.parts[k].name]?.highlight)
: null;
const hd = d + 24;
data[hd] = color ? color.red : 0;
data[hd + 1] = color ? color.green : 0;
data[hd + 2] = color ? color.blue : 0;
data[hd + 3] = color ? 1 : 0;
}
return posed;
}
/**
* A posed model's spins, turned on to `timeS` (seconds): each spinning
* part's angle moves on at its rate since it last did, so a change of rate
* never makes a part jump. A part that stops spinning keeps its angle.
*/
export function advanceSpins(spins, timeS) {
const dt = timeS - spins.at;
spins.at = timeS;
if (!(dt > 0)) return;
for (const [name, rate] of spins.rates)
spins.angles[name] = (spins.angles[name] + rate * dt) % 360;
}
/**
* Spins at `state`'s rates from `timeS` on, carrying the angles reached; a
* part starting to spin starts at an angle of `startAngle`'s (by default a
* random one, so a fleet posed at once does not turn in step).
*/
export function respin(
spins,
table,
state,
timeS,
startAngle = () => Math.random() * 360,
) {
advanceSpins(spins, timeS);
spins.rates.clear();
for (const [name, rate] of Object.entries(state?.spin ?? {})) {
const index = table.byName.get(name);
if (
index === undefined ||
!table.parts[index].axis ||
typeof rate !== 'number' ||
!Number.isFinite(rate) ||
rate === 0
)
continue;
spins.rates.set(name, rate);
if (!(name in spins.angles)) spins.angles[name] = startAngle();
}
}
/** New spins: none yet, at `timeS`. */
export const newSpins = (timeS) => ({
rates: new Map(),
angles: {},
at: timeS,
});
/** 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();
const scratchFactors = { scale: 1, alpha: 1, limbRatio: null };
const scratchFrame = { active: false, limbM: 1, strength: 0 };
/** The colour last written to each model. */
const writtenColors = new WeakMap();
/** Written to a model drawn in its own colours: no colour at all. */
const NO_COLOR = Symbol('drawModels.noColor');
/** 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) ||
Boolean(spec.recede);
/** An item's focus, 0..1. */
const focusOf = (item) =>
Number.isFinite(item.focus) ? Math.min(1, Math.max(0, item.focus)) : 1;
/**
* The models part of a Cesium draw port.
* @param {{scene: object, toColor: Function, pickId: Function,
* replaceHost: Function, horizonNow: () => object|null,
* requestRender: () => void, parts?: boolean,
* now?: () => number}} options From the draw port: its colour
* conversion, pick ids, host swap, horizon and render request; whether it
* poses models' parts (`modelParts`), and the clock (milliseconds) spins
* are turned by.
*/
export function createModelSets({
scene,
toColor,
pickId,
replaceHost,
horizonNow,
requestRender,
parts: posesParts = false,
now = () => performance.now(),
}) {
/** Each Cesium model drawn posed: its part shader, texture and spins. */
const posings = new Map();
/** The GLB bytes each model was built from, where it was. */
const modelBytes = new WeakMap();
/** Part shaders let go, destroyed once no draw uses them. */
const retired = [];
// Float textures carry the part matrices, and WebGL 2's shading language
// turns the normals: without them models draw whole.
const canPose = () =>
scene.context?.floatingPointTexture !== false &&
scene.context?.webgl2 !== false;
/** A model's part table and mesh frame, or null. */
function partInfoOfModel(model) {
const bytes = modelBytes.get(model);
if (bytes) return partInfoOf(bytes);
const json = model.loader?.gltfJson;
return json ? partInfoOf(json) : null;
}
/** Let go of a model's posing: its shader goes once no draw uses it. */
function unpose(model) {
const posing = posings.get(model);
if (!posing) return;
posings.delete(model);
retired.push({ shader: posing.shader, frames: 0 });
}
/** Write a posing's texture where its shader reads it. */
function upload(posing) {
const texture = customShaderTexture(posing.shader, 'u_partMatrices');
if (
texture &&
!texture.isDestroyed?.() &&
texture.width === PART_TEXELS &&
texture.height === posing.rows
)
texture.copyFrom({
source: {
arrayBufferView: posing.data,
width: PART_TEXELS,
height: posing.rows,
},
});
else
posing.shader.setUniform(
'u_partMatrices',
partTexture(posing.data, posing.rows),
);
}
/**
* The state a posing's texture is written for: its item's deploys and
* poses, its spins as the angles they have reached (written at a time of
* 1 s, each angle given as a rate).
*/
function spunState(posing) {
const drawn = posing.drawn;
drawn.deploy = posing.state.deploy;
drawn.poses = posing.state.poses;
drawn.spin = posing.spins.angles;
return drawn;
}
/** Write a posing's texture for now. Whether any part is not at rest. */
function writePosing(posing, timeS) {
advanceSpins(posing.spins, timeS);
return writePartTexture(
posing.info,
spunState(posing),
1,
posing.scale,
posing.data,
);
}
/**
* The shader `model` draws its entry's item's `parts` with, its texture
* written for them now; undefined when the model draws whole (no `parts`,
* no part table, or every part at rest), its posing let go.
*/
function posedShader(entry, model) {
const item = entry.item;
const state = posesParts ? item.parts : undefined;
const posing = posings.get(model);
const info = asksParts(state) && canPose() ? partInfoOfModel(model) : null;
if (!info) {
unpose(model);
return undefined;
}
const axes = item.axisScale;
const scale =
axes && (axes[0] !== 1 || axes[1] !== 1 || axes[2] !== 1)
? axes
: undefined;
const key = JSON.stringify(state);
const scaleKey = scale ? scale.join(',') : '';
const shading = item.shading;
const sameLook =
posing?.info === info &&
posing.shading === shading &&
posing.mask === entry.mask;
// A fleet re-poses every frame with the same parts: written when they
// change (a spin turns in the frame pass).
if (sameLook && posing.key === key && posing.scaleKey === scaleKey)
return posing.shader;
const timeS = now() / 1000;
// Spins go on from where they were, whatever else changed.
const spins = posing?.info === info ? posing.spins : newSpins(timeS);
respin(spins, info.table, state, timeS);
const spinning = spins.rates.size > 0;
const rows = info.table.parts.length;
const next = {
info,
shader: sameLook ? posing.shader : null,
shading,
mask: entry.mask,
data: sameLook ? posing.data : new Float32Array(rows * PART_FLOATS),
rows,
key,
scaleKey,
scale,
spinning,
state,
spins,
drawn: posing?.drawn ?? {},
};
const posed = writePosing(next, timeS);
if (!posed && !spinning) {
unpose(model);
return undefined;
}
if (sameLook) {
Object.assign(posing, next);
upload(posing);
return posing.shader;
}
unpose(model);
next.shader = partShaderOf(shading, entry.mask, next.data, rows);
posings.set(model, next);
return next.shader;
}
/** Pixels across a model's bounds under which its spins are not turned. */
const MIN_SPIN_PIXELS = 4;
const scratchSpinSphere = new Cesium.BoundingSphere();
/**
* Whether a model is worth turning this frame: shown, in the view, and
* at least `MIN_SPIN_PIXELS` across.
*/
function seen(model, culling, width, height) {
if (!model.show || !model.ready) return false;
const sphere = model.boundingSphere;
if (!sphere || !(sphere.radius > 0)) return false;
if (
culling &&
culling.computeVisibility(sphere) === Cesium.Intersect.OUTSIDE
)
return false;
if (!(width > 0 && height > 0)) return true;
Cesium.BoundingSphere.clone(sphere, scratchSpinSphere);
scratchSpinSphere.radius = 0;
const metresPerPixel = scene.camera.getPixelSize(
scratchSpinSphere,
width,
height,
);
return (
!(metresPerPixel > 0) ||
!Number.isFinite(metresPerPixel) ||
(2 * sphere.radius) / metresPerPixel >= MIN_SPIN_PIXELS
);
}
/**
* Before a frame: turn the spinning parts of each model in view to now,
* sweep the posings of models gone, and destroy part shaders no draw
* uses any more. Whether any model in view spins (frames go on being
* asked for; one out of view or too small to see asks for none).
*/
function turnParts() {
for (let i = retired.length - 1; i >= 0; i--)
if ((retired[i].frames += 1) > 2) {
const [{ shader }] = retired.splice(i, 1);
shader.destroy?.();
}
if (!posings.size) return false;
const timeS = now() / 1000;
const camera = scene.camera;
const culling =
camera?.frustum?.computeCullingVolume && camera.positionWC
? camera.frustum.computeCullingVolume(
camera.positionWC,
camera.directionWC,
camera.upWC,
)
: null;
const width = scene.drawingBufferWidth ?? scene.canvas?.width ?? 0;
const height = scene.drawingBufferHeight ?? scene.canvas?.height ?? 0;
let spinning = false;
for (const [model, posing] of posings) {
if (model.isDestroyed?.()) {
unpose(model);
continue;
}
if (!posing.spinning || !seen(model, culling, width, height)) continue;
spinning = true;
writePosing(posing, timeS);
upload(posing);
}
return spinning;
}
/**
* Let go of every posing and part shader now, their textures with them:
* the port is done, and no frame comes to retire them. A model still
* drawn is left drawing whole.
*/
function dispose() {
for (const [model, posing] of posings) {
if (!model.isDestroyed?.() && model.customShader === posing.shader)
model.customShader = undefined;
posing.shader.destroy?.();
}
posings.clear();
for (const { shader } of retired.splice(0)) shader.destroy?.();
}
/** 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();
}
if (item.gltf) modelBytes.set(model, item.gltf);
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 = posedShader(entry, model) ?? 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);
poseNodes(item, model);
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 * (entry.emphasis ?? focusOf(item));
// An untinted model at full opacity is drawn without a colour: a colour
// adds a colour stage to every draw of the model.
const plain = !entry.tint && color.alpha === 1;
// 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 (plain) {
if (written !== NO_COLOR) {
writtenColors.set(model, NO_COLOR);
model.color = undefined;
}
} else if (
!written ||
written === NO_COLOR ||
!Cesium.Color.equals(written, color)
) {
writtenColors.set(
model,
Cesium.Color.clone(color, written === NO_COLOR ? undefined : 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. Whether any was added: models moved or
* restyled keep their pick ids, so only one added changes what height
* queries see through.
*/
function upsert(record, list) {
hostOf(record);
let added = false;
for (const item of list) if (put(record, item)) added = true;
if (added) notePickIds(record);
requestRender();
return added;
}
/** Draw `item` on its entry, made when it has none; true when made. */
function put(record, item) {
let entry = record.models.get(item.id);
const made = !entry;
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,
// The custom shader drawn with, for the shading and mask it is of
// (`entryShader`).
shader: undefined,
shaderShading: null,
shaderMask: null,
dynamic: false,
frame: null,
// Focus and haze in a set that recedes, else null (focus alone).
emphasis: 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);
return made;
}
/** 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, the cull and
* spinning parts. Whether any shown model spins.
*/
function beforeRender(sets) {
const spinning = turnParts();
const eye = scene.camera?.positionWC;
if (!eye) return spinning;
const width = scene.drawingBufferWidth ?? scene.canvas?.width ?? 0;
const height = scene.drawingBufferHeight ?? scene.canvas?.height ?? 0;
let horizon;
const eyeHeight = scene.camera.positionCartographic?.height;
for (const record of sets) {
if (record.kind !== 'models' || !record.models) continue;
if (record.recedeFrom !== record.spec.recede) {
record.recedeFrom = record.spec.recede;
record.recede = recedeParams(record.spec.recede);
}
const recede = record.recede;
const recedeNow = recede
? recedeFrame(eyeHeight, recede, scratchFrame)
: null;
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;
if (recede) {
const haze = recedeFactors(
distance,
recedeNow,
recede,
scratchFactors,
).alpha;
const emphasis = recededAlpha(focusOf(item), haze, recede);
if (
entry.emphasis === null ||
Math.abs(entry.emphasis - emphasis) > RECEDE_WRITE_EPSILON
)
entry.emphasis = emphasis;
} else entry.emphasis = null;
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);
}
}
return spinning;
}
/**
* 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);
if (!record.spec.recede) entry.emphasis = null;
}
}
return { build, upsert, beforeRender, restyle, dispose };
}