diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 2b314a9fb..dd9029743 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -20,6 +20,7 @@ "src/render/cesium/frame.js", "src/render/cesium/query.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -899,6 +900,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -1050,6 +1052,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -1491,6 +1494,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -1597,6 +1601,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -1800,6 +1805,7 @@ "src/queries/heights.js", "src/render/cesium/effects.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -1887,6 +1893,7 @@ "src/render/cesium/credits.js", "src/render/creditMarkup.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -1980,6 +1987,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -2047,6 +2055,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -2132,6 +2141,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -2329,6 +2339,7 @@ "src/render/cesium/drawHit.js", "src/render/cesium/cameraInput.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/cesium/frame.js", @@ -2456,6 +2467,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -2739,6 +2751,7 @@ "src/render/cesium/heights.js", "src/queries/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -2914,6 +2927,7 @@ "src/render/cesium/credits.js", "src/render/cesium/tileRequests.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -3142,6 +3156,7 @@ "src/render/cesium/globe.js", "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/quality.js", "src/render/cesium/credits.js", @@ -4139,6 +4154,7 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -4817,6 +4833,7 @@ "src/render/cesium/heights.js", "src/render/cesium/drawHit.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -5492,6 +5509,7 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -5637,6 +5655,7 @@ "src/render/cesium/credits.js", "src/render/creditMarkup.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -5893,6 +5912,7 @@ "src/render/cesium/query.js", "src/render/cesium/heights.js", "src/render/cesium/draw.js", + "src/render/cesium/drawModels.js", "src/geo/polyline.js", "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", @@ -6179,6 +6199,7 @@ "modules": [ "src/render/contract/index.js", "src/render/stub/index.js", + "src/render/color.js", "src/geo/polyline.js", "src/render/motion/iconMotion.js", "src/geo/horizon.js", diff --git a/src/data/infrastructure.test.mjs b/src/data/infrastructure.test.mjs index 94b49085a..c058e89e6 100644 --- a/src/data/infrastructure.test.mjs +++ b/src/data/infrastructure.test.mjs @@ -198,6 +198,7 @@ test('consumer build includes only infrastructure code and resolves assets under 'dispatcher.js', 'draw.js', 'drawHit.js', + 'drawModels.js', 'events.js', 'follow.js', 'frame.js', diff --git a/src/render/cesium/draw.js b/src/render/cesium/draw.js index 337e6000a..935e55060 100644 --- a/src/render/cesium/draw.js +++ b/src/render/cesium/draw.js @@ -3,7 +3,8 @@ * @description The Cesium renderer's draw port * (`src/render/contract/draw.d.ts`): batched sets of items, each set one * primitive collection in the scene, rebuilt when its items change (icon - * sets, and unclamped points restyled or moved, change in place). Every + * sets, unclamped points restyled or moved, and models, change in place; + * `drawModels.js`). Every * item carries a pick id `{set, id, meta, lodGroup}`, which the query port * (`ports.js`) reads picks back through. * @@ -30,6 +31,7 @@ import { alongLength } from '../../geo/polyline.js'; import { provideUnboundDraw } from '../rendererOf.js'; import { listenerList, toCartesian, uncaught } from './common.js'; import { createGpuIcons, GPU_ICON_CAPABILITIES } from './gpuIcons.js'; +import { createModelSets } from './drawModels.js'; /** The contract's colour as Cesium's. */ export function toColor(color, alpha = 1) { @@ -324,7 +326,11 @@ export function createCesiumDraw({ } // Points restyled or moved, and lines that only change how they show // or where an undraped one runs, are changed where they are. - if (patchPoints(record, list) || patchLines(record, list)) { + if ( + patchPoints(record, list) || + patchLines(record, list) || + (kind === 'models' && modelSets.upsert(record, list)) + ) { for (const item of list) items.set(item.id, item); if (kind === 'lines') noteFlows(record); setsVersion += 1; @@ -384,6 +390,7 @@ export function createCesiumDraw({ // while the new builds, it would keep hiding the ground from picks. if (pickable && spec.pickable === false) retire(record); record.gpu?.restyle(); + if (kind === 'models') modelSets.restyle(record); setsVersion += 1; showHosts(record); // No longer culled: what the cull hid comes back. @@ -2029,52 +2036,15 @@ export function createCesiumDraw({ replaceHost(record, collect(host, ground), ground, host); } - function buildModels(record) { - const host = new Cesium.PrimitiveCollection(); - replaceHost(record, host); - // A model counts as loading until it is ready or fails, not when added; - // each model settles once, and a failure is kept for `whenSettled`. - host.loading = record.items.size; - host.failed = 0; - for (const item of record.items.values()) { - let settled = false; - const settle = (failed) => { - if (settled) return; - settled = true; - host.loading -= 1; - if (failed) host.failed += 1; - scene.requestRender(); - }; - const o = item.orientation; - const modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame( - toCartesian(item.pos), - new Cesium.HeadingPitchRoll(o.heading, o.pitch, o.roll), - ); - Cesium.Model.fromGltfAsync({ - url: item.url, - modelMatrix, - scale: item.scale ?? 1, - minimumPixelSize: item.minPixelSize ?? 0, - // All textures before ready, so a settled capture is the whole model. - incrementallyLoadTextures: false, - id: pickId(record, item), - }).then( - (model) => { - // Rebuilt, disposed, or the renderer is gone. - if (record.host !== host || host.isDestroyed()) - return model.destroy(); - host.add(model); - model.readyEvent.addEventListener(() => { - settle(false); - record.listeners.ready.fire(item.id); - }); - model.errorEvent.addEventListener(() => settle(true)); - scene.requestRender(); - }, - () => settle(true), - ); - } - } + const modelSets = createModelSets({ + scene, + toColor, + pickId, + replaceHost, + horizonNow, + requestRender, + }); + const buildModels = (record) => modelSets.build(record); /** The 3D tilesets in the scene, shown or not. */ function tilesets() { @@ -2154,6 +2124,7 @@ export function createCesiumDraw({ beforeRender() { cullHorizon(); runFlows(); + modelSets.beforeRender(sets.values()); }, /** Each frame, after it drew: clamp state, and ground swaps. */ afterRender() { diff --git a/src/render/cesium/draw.test.mjs b/src/render/cesium/draw.test.mjs index 5994363b9..ceb91030a 100644 --- a/src/render/cesium/draw.test.mjs +++ b/src/render/cesium/draw.test.mjs @@ -3623,3 +3623,271 @@ test('a segmented line, then plain and moved while its set rebuilds, is hidden s set.dispose(); }), )); + +/** `Cesium.Model.fromGltfAsync` replaced by loads a test resolves. */ +function fakeModelLoads() { + const loads = []; + const real = Cesium.Model.fromGltfAsync; + Cesium.Model.fromGltfAsync = (options) => + new Promise((resolve, reject) => { + const model = { + ...options, + modelMatrix: Cesium.Matrix4.clone(options.modelMatrix), + ready: false, + color: undefined, + colorBlendMode: Cesium.ColorBlendMode.HIGHLIGHT, + colorBlendAmount: 0.5, + environmentMapManager: { + enabled: options.environmentMapOptions?.enabled ?? true, + }, + readyEvent: new Cesium.Event(), + errorEvent: new Cesium.Event(), + boundingSphere: { radius: 10 * (options.scale ?? 1) }, + destroyed: false, + destroy() { + this.destroyed = true; + }, + isDestroyed() { + return this.destroyed; + }, + update() {}, + }; + loads.push({ + options, + model, + resolve: () => resolve(model), + reject, + ready() { + model.ready = true; + model.readyEvent.raiseEvent(model); + }, + }); + }); + return { loads, restore: () => (Cesium.Model.fromGltfAsync = real) }; +} + +const settle = () => new Promise((resolve) => setTimeout(resolve, 0)); + +test('models re-pose and restyle in place; only a new url loads again', async () => { + const { loads, restore } = fakeModelLoads(); + try { + const scene = fakeScene(); + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + }); + const set = part.port.models({ id: 'planes' }); + const ready = []; + set.on('ready', (id) => ready.push(id)); + const plane = (extra = {}) => ({ + id: 'p', + pos: { lon: 10, lat: 20, height: 100 }, + url: 'a.glb', + orientation: { heading: 0, pitch: 0, roll: 0 }, + environmentMap: false, + meta: { n: 1 }, + ...extra, + }); + set.set([plane()]); + assert.equal(loads.length, 1); + assert.equal(loads[0].options.environmentMapOptions.enabled, false); + assert.equal(loads[0].options.show, false, 'hidden until ready'); + const host = scene.added[0]; + assert.equal(host.loading, 1, 'loading'); + loads[0].resolve(); + await settle(); + const model = loads[0].model; + assert.equal(model.show, false, 'loaded, not yet ready'); + loads[0].ready(); + assert.deepEqual(ready, ['p'], 'ready once loaded and posed'); + assert.equal(model.show, true); + assert.equal(host.loading, 0); + assert.deepEqual(model.id, { + set: 'planes', + id: 'p', + meta: { n: 1 }, + lodGroup: undefined, + }); + + // Moved, turned and restyled: the same model, no load, no ready. + set.upsert([ + plane({ + pos: { lon: 11, lat: 21, height: 200 }, + orientation: { heading: 1, pitch: 0.1, roll: 0.2 }, + tint: [1, 0, 0, 0.5], + colorBlend: { mode: 'mix', amount: 0.8 }, + shading: 'unlit', + environmentMap: true, + scale: 2, + minPixelSize: 32, + maxScale: 50, + meta: { n: 2 }, + }), + ]); + assert.equal(loads.length, 1, 'not loaded again'); + assert.deepEqual(ready, ['p'], 'no second ready'); + const expected = Cesium.Transforms.headingPitchRollToFixedFrame( + Cesium.Cartesian3.fromDegrees(11, 21, 200), + new Cesium.HeadingPitchRoll(1, 0.1, 0.2), + ); + assert.ok(Cesium.Matrix4.equalsEpsilon(model.modelMatrix, expected, 1e-6)); + assert.deepEqual( + [model.color.red, model.color.green, model.color.blue, model.color.alpha], + [1, 0, 0, 0.5], + ); + assert.equal(model.colorBlendMode, Cesium.ColorBlendMode.MIX); + assert.equal(model.colorBlendAmount, 0.8); + assert.ok(model.customShader instanceof Cesium.CustomShader, 'unlit'); + assert.equal(model.environmentMapManager.enabled, true); + assert.equal(model.scale, 2); + assert.equal(model.minimumPixelSize, 32); + assert.equal(model.maximumScale, 50); + assert.deepEqual(model.id.meta, { n: 2 }, 'the pick id follows'); + set.upsert([ + plane({ shading: 'pbr', tint: '#00f', colorBlend: { mode: 'replace' } }), + ]); + assert.equal(model.customShader, undefined, 'lit again'); + assert.equal(model.colorBlendMode, Cesium.ColorBlendMode.REPLACE); + set.upsert([plane({ colorBlend: { mode: 'replace' } })]); + assert.equal( + model.colorBlendMode, + Cesium.ColorBlendMode.HIGHLIGHT, + 'no tint to blend in: its own colour', + ); + assert.equal(model.color.alpha, 1); + set.upsert([plane({ show: false })]); + assert.equal(model.show, false, 'hidden in place'); + + // A new url loads; the old model draws until the new one is ready. + set.upsert([plane({ url: 'b.glb' })]); + assert.equal(loads.length, 2); + loads[1].resolve(); + await settle(); + assert.ok(host.contains(model), 'the old model still draws'); + loads[1].ready(); + assert.equal(host.contains(model), false, 'swapped once ready'); + assert.ok(host.contains(loads[1].model)); + assert.deepEqual(ready, ['p', 'p']); + + // Away and back before the other loads: no second load of the first. + set.upsert([plane({ url: 'c.glb' })]); + set.upsert([plane({ url: 'b.glb', pos: { lon: 12, lat: 22 } })]); + assert.equal(loads.length, 3); + assert.equal(host.loading, 0, 'the load in between is let go'); + const moved = Cesium.Matrix4.getTranslation( + loads[1].model.modelMatrix, + new Cesium.Cartesian3(), + ); + assert.ok( + Cesium.Cartesian3.distance(moved, Cesium.Cartesian3.fromDegrees(12, 22)) < + 1e-3, + 'the drawn model kept moving', + ); + + set.remove(['p']); + assert.equal(host.length, 0, 'removed'); + assert.equal(set.size(), 0); + set.dispose(); + } finally { + restore(); + } +}); + +test('a model load superseded or failed settles once', async () => { + const { loads, restore } = fakeModelLoads(); + try { + const scene = fakeScene(); + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + }); + const set = part.port.models({ id: 'm' }); + const item = (url) => ({ + id: 'a', + pos: { lon: 0, lat: 0 }, + url, + orientation: { heading: 0, pitch: 0, roll: 0 }, + }); + set.set([item('a.glb')]); + const host = scene.added[0]; + set.upsert([item('b.glb')]); + assert.equal(host.loading, 1, 'the first is superseded'); + loads[0].resolve(); + await settle(); + assert.equal(loads[0].model.destroyed, true, 'a stale load is let go'); + loads[1].reject(new Error('no such model')); + await settle(); + assert.equal(host.loading, 0); + assert.equal(host.failed, 1, 'kept for whenSettled'); + // A model that fails as it loads is let go once its update is done. + set.upsert([item('c.glb')]); + assert.equal(host.failed, 0, 'a new url clears the failure'); + loads[2].resolve(); + await settle(); + const bad = loads[2].model; + bad.errorEvent.raiseEvent(new Error('bad texture')); + assert.ok(host.contains(bad), 'not destroyed inside its own update'); + assert.equal(host.failed, 1); + await settle(); + assert.equal(host.contains(bad), false, 'then let go'); + set.clear(); + assert.equal(host.failed, 0, 'gone with its item'); + set.dispose(); + } finally { + restore(); + } +}); + +test('a model past its pixel cap is scaled down each frame; fades and culls too', async () => { + const { loads, restore } = fakeModelLoads(); + try { + const scene = fakeScene(); + scene.drawingBufferWidth = 1000; + scene.drawingBufferHeight = 500; + let metresPerPixel = 0.1; + scene.camera.getPixelSize = () => metresPerPixel; + const part = createCesiumDraw({ + scene, + report: (error) => assert.fail(error), + }); + const set = part.port.models({ id: 'm', horizonCull: true }); + const eye = scene.camera.positionWC; + const at = Cesium.Cartesian3.fromDegrees(0, 0, 1000); + const distance = Cesium.Cartesian3.distance(eye, at); + set.set([ + { + id: 'a', + pos: { lon: 0, lat: 0, height: 1000 }, + url: 'a.glb', + orientation: { heading: 0, pitch: 0, roll: 0 }, + scale: 4, + maxPixelSize: 100, + fadeByDistance: { + near: distance - 10, + nearValue: 1, + far: distance + 10, + farValue: 0, + }, + }, + ]); + loads[0].resolve(); + await settle(); + const model = loads[0].model; + loads[0].ready(); + part.beforeRender(); + // Radius 10 m at scale 1: 100 px at 0.1 m/px is 10 m across, scale 0.5. + assert.ok(Math.abs(model.scale - 0.5) < 1e-9, `capped: ${model.scale}`); + assert.ok(Math.abs(model.color.alpha - 0.5) < 1e-6, 'faded halfway'); + metresPerPixel = 10; + part.beforeRender(); + assert.equal(model.scale, 4, 'under the cap: its own scale'); + assert.equal(model.show, true); + // Behind the earth from an eye on the far side. + scene.camera.positionWC = new Cesium.Cartesian3(-2e7, 0, 0); + part.beforeRender(); + assert.equal(model.show, false, 'culled past the horizon'); + set.dispose(); + } finally { + restore(); + } +}); diff --git a/src/render/cesium/drawModels.js b/src/render/cesium/drawModels.js new file mode 100644 index 000000000..c9e5df414 --- /dev/null +++ b/src/render/cesium/drawModels.js @@ -0,0 +1,485 @@ +/** + * @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 and pixel bounds, `shading`, `tint`, `colorBlend`, + * `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. + * + * 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`. + * + * `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, +}; + +/** Cesium's own blend amount, for a `mix` that names none. */ +const DEFAULT_MIX = 0.5; + +let unlitShader = null; +let thermalShader = null; + +/** 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 scratchMatrix = new Cesium.Matrix4(); +const scratchSphere = new Cesium.BoundingSphere(); +const scratchColor = new Cesium.Color(); +/** The colour last written to each model, as a key. */ +const writtenColors = new WeakMap(); + +/** 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, + ); +} + +/** 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 settleLoad = () => settle(false); + const settle = (failed) => { + if (settled) return; + settled = true; + if (entry.settleLoad === settleLoad) entry.settleLoad = null; + host.loading -= 1; + if (failed && entry.token === token) { + entry.failed = true; + host.failed += 1; + } + requestRender(); + }; + entry.settleLoad = settleLoad; + const item = entry.item; + const current = () => + entry.token === token && record.host === host && !host.isDestroyed(); + Cesium.Model.fromGltfAsync({ + url: item.url, + modelMatrix: matrixOf(entry, new Cesium.Matrix4()), + scale: item.scale ?? 1, + minimumPixelSize: item.minPixelSize ?? 0, + maximumScale: item.maxScale, + customShader: shaderOf(item.shading), + 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, + 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(() => { + 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); + }); + requestRender(); + }, + () => settle(true), + ); + } + + function matrixOf(entry, result) { + const o = entry.item.orientation ?? {}; + scratchHpr.heading = o.heading ?? 0; + scratchHpr.pitch = o.pitch ?? 0; + scratchHpr.roll = o.roll ?? 0; + return Cesium.Transforms.headingPitchRollToFixedFrame( + entry.at, + scratchHpr, + Cesium.Ellipsoid.WGS84, + undefined, + 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 = shaderOf(item.shading); + if (model.customShader !== shader) model.customShader = shader; + 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]); + entry.styled = { range: rangeKey }; + entry.dynamic = needsFrame(item, record.spec); + const frame = entry.frame ?? { scale: 1, alpha: 1, shown: true }; + apply(entry, model, frame, 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 key = `${color.red},${color.green},${color.blue},${color.alpha}`; + if (writtenColors.get(model) !== key) { + writtenColors.set(model, key); + 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, + radius: 0, + next: null, + token: null, + failed: false, + 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; + entry.pickId.lodGroup = item.lodGroup; + } + positionOf(item.pos, entry.at); + entry.tint = + item.tint === undefined || item.tint === null ? null : toColor(item.tint); + 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); + if (entry.url !== item.url) 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 }; +} diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 0df9a3c39..67a695877 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -45,6 +45,8 @@ export const CESIUM_CHECKS = new Set([ 'draw.lines.segments', 'draw.ids', 'draw.models', + 'draw.models.tint', + 'draw.models.update', 'draw.motion', 'draw.motion.arc', 'draw.motion.climb', diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index df5d97621..039e92121 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -1754,6 +1754,148 @@ export function portChecks() { }, { capability: 'models' }, ), + check( + 'draw.models.update', + 'a model moves, turns and restyles in place; only a new url loads it again', + async (h, r) => { + if (!h.assets?.model) return { skip: 'no model asset in this harness' }; + await overAustin(h, r); + const set = r.draw.models({ id: 'conf:models.update' }); + const ready = []; + set.on('ready', (id) => ready.push(id)); + const here = h.toEcef({ ...AUSTIN, height: 0 }); + const there = h.toEcef({ + lon: AUSTIN.lon + 0.004, + lat: AUSTIN.lat, + height: 0, + }); + const model = (pos, extra = {}) => ({ + id: 'm', + pos, + url: h.assets.model, + orientation: { heading: 0, pitch: 0, roll: 0 }, + minPixelSize: 96, + ...extra, + }); + const untilReady = async (count) => { + for (let i = 0; i < 600 && ready.length < count; i++) + await drawn(h, r, 1); + }; + const picked = (pos) => { + const s = r.query.project(pos); + return ( + s !== null && + r.query.drillPick(s.x, s.y).some((hit) => hit.set === set.id) + ); + }; + set.set([model(here)]); + await untilReady(1); + deepEqual(ready, ['m'], 'ready once loaded'); + await drawn(h, r); + await settled(r); + ok(picked(here), 'picked where it is'); + set.upsert([ + model(there, { + orientation: { heading: 1.2, pitch: 0.1, roll: 0.2 }, + scale: 2, + shading: 'unlit', + tint: '#00ff00', + colorBlend: { mode: 'mix', amount: 0.5 }, + environmentMap: false, + meta: { n: 2 }, + }), + ]); + await drawn(h, r, 4); + await settled(r); + deepEqual(ready, ['m'], 'moved and restyled without loading again'); + ok(picked(there), 'picked where it moved to'); + ok(!picked(here), 'not where it was'); + const s = r.query.project(there); + const hit = r.query.drillPick(s.x, s.y).find((x) => x.set === set.id); + deepEqual(hit?.meta, { n: 2 }, 'its new meta'); + set.upsert([model(there, { url: `${h.assets.model}?again` })]); + await untilReady(2); + deepEqual(ready, ['m', 'm'], 'a new url loads again'); + await drawn(h, r); + await settled(r); + ok(picked(there), 'the new model is drawn'); + equal(set.size(), 1, 'one model'); + set.dispose(); + }, + { capability: 'models' }, + ), + check( + 'draw.models.tint', + 'a model’s tint and colour blend change live', + async (h, r) => { + if (!h.assets?.model) return { skip: 'no model asset in this harness' }; + await overAustin(h, r); + const set = r.draw.models({ id: 'conf:models.tint' }); + const ready = []; + set.on('ready', (id) => ready.push(id)); + const pos = h.toEcef({ ...AUSTIN, height: 0 }); + const model = (extra) => ({ + id: 'm', + pos, + url: h.assets.model, + orientation: { heading: 0, pitch: 0, roll: 0 }, + minPixelSize: 160, + environmentMap: false, + ...extra, + }); + set.set([model({ shading: 'pbr' })]); + for (let i = 0; i < 600 && !ready.length; i++) await drawn(h, r, 1); + deepEqual(ready, ['m'], 'ready'); + const s = r.query.project(pos); + // How many pixels of a patch at the model's centre `like` holds. + const count = async (like) => { + await drawn(h, r, 3); + await settled(r); + r.frame.renderNow(); + const image = r.readPixels({ + crop: { + x: Math.round(s.x) - 4, + y: Math.round(s.y) - 4, + width: 9, + height: 9, + }, + }); + let n = 0; + for (let i = 0; i < image.data.length; i += 4) + if (like(image.data[i], image.data[i + 1], image.data[i + 2])) n++; + return n; + }; + const red = (r0, g, b) => r0 > 180 && g < 70 && b < 70; + const blue = (r0, g, b) => b > 180 && r0 < 70 && g < 70; + set.upsert([ + model({ + shading: 'unlit', + tint: '#ff0000', + colorBlend: { mode: 'replace' }, + }), + ]); + ok((await count(red)) >= 40, 'replaced by a red tint'); + set.upsert([ + model({ + shading: 'unlit', + tint: '#0000ff', + colorBlend: { mode: 'replace' }, + }), + ]); + ok((await count(blue)) >= 40, 'the tint changes live'); + set.upsert([ + model({ + shading: 'unlit', + tint: '#0000ff', + colorBlend: { mode: 'mix', amount: 0 }, + }), + ]); + equal(await count(blue), 0, 'mixed in at none, its own colour'); + deepEqual(ready, ['m'], 'restyled without loading again'); + set.dispose(); + }, + { capability: 'models' }, + ), // --- Query ------------------------------------------------------------- check( diff --git a/src/render/stub/harness.js b/src/render/stub/harness.js index 969890f09..7a102bdab 100644 --- a/src/render/stub/harness.js +++ b/src/render/stub/harness.js @@ -23,5 +23,7 @@ export function createStubHarness(name = 'stub') { pointer: (r, type, x, y, extra) => r.testing.pointer(type, x, y, extra), scriptHeights: (r, fn) => r.testing.setHeights(fn), wallTime: (r) => r.testing.wallTime(), + // The stub loads nothing: any url is a model it draws. + assets: { model: 'stub:model.glb' }, }; } diff --git a/src/render/stub/index.js b/src/render/stub/index.js index ec852d516..89bb32430 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -12,6 +12,7 @@ import { horizonFrom } from '../../geo/horizon.js'; import { alongLength } from '../../geo/polyline.js'; import { createInputRouter } from '../input/router.js'; +import { cssColor } from '../color.js'; import { CAPABILITIES, CONTRACT_VERSION } from '../contract/index.js'; import { createStubCamera } from './camera.js'; import { motionPosition } from '../motion/iconMotion.js'; @@ -316,24 +317,35 @@ export function createStubRenderer(options = {}) { }; sets.set(spec.id, record); log('draw', kind, [spec]); + // A model is ready once per load: when it is new or its url changes, + // not when it is moved or restyled. + const loads = (items) => + kind === 'models' + ? items + .filter( + (item) => record.items.get(String(item.id))?.url !== item.url, + ) + .map((item) => String(item.id)) + : []; const ready = (ids) => { - if (kind !== 'models') return; for (const id of ids) deliver(record.readyListeners, id); }; const handle = { id: spec.id, set(items) { + const loading = loads(items); record.items.clear(); for (const item of items) record.items.set(String(item.id), { ...item }); requestRender('draw'); - ready(items.map((item) => String(item.id))); + ready(loading); }, upsert(items) { + const loading = loads(items); for (const item of items) record.items.set(String(item.id), { ...item }); requestRender('draw'); - ready(items.map((item) => String(item.id))); + ready(loading); }, remove(ids) { for (const id of ids) record.items.delete(String(id)); @@ -546,6 +558,67 @@ export function createStubRenderer(options = {}) { return base; } + /** + * The shown models as the stub draws them: a square as wide as a pick + * takes (at most `maxPixelSize`, at least `minPixelSize`), far + * ones first, in white shading blended with the tint by `colorBlend`. + */ + function modelSquares() { + const squares = []; + for (const set of sets.values()) { + if (set.kind !== 'models' || !set.show) continue; + for (const item of set.items.values()) { + if (item.show === false) continue; + const p = itemPosition(set, item); + if (!p || isOccluded(p)) continue; + const distance = magnitude(sub(p, eye().position)); + if (item.displayRange) { + const [nearM, farM] = item.displayRange; + if (distance < nearM || distance >= farM) continue; + } + const s = project(p); + if (!s) continue; + // The pixel floor wins over the cap, as Cesium's does. + let side = 10; + if (item.maxPixelSize > 0) side = Math.min(side, item.maxPixelSize); + side = Math.max(side, item.minPixelSize ?? 0); + squares.push({ + x: s.x, + y: s.y, + half: side / 2, + distance, + rgba: modelColor(item), + }); + } + } + return squares.sort((a, b) => b.distance - a.distance); + } + + /** A model's colour: white shading, the tint blended in by `colorBlend`. */ + function modelColor(item) { + const shaded = [1, 1, 1]; + const tint = + item.tint === undefined || item.tint === null + ? null + : typeof item.tint === 'string' + ? cssColor(item.tint) + : item.tint; + let rgb = shaded; + if (tint) { + const mode = item.colorBlend?.mode ?? 'highlight'; + const amount = + mode === 'replace' + ? 1 + : mode === 'mix' + ? (item.colorBlend.amount ?? 0.5) + : null; + rgb = shaded.map((c, i) => + amount === null ? c * tint[i] : c + (tint[i] - c) * amount, + ); + } + return [...rgb.map((c) => Math.round(c * 255)), 255]; + } + /** Where a drawn item is now (or `aheadMs` from now), or null. */ function drawnPosition(ref, aheadMs = 0) { const set = sets.get(ref.set); @@ -1260,18 +1333,30 @@ export function createStubRenderer(options = {}) { return new Blob([], { type: `image/${opts.type ?? 'png'}` }); }, readPixels(opts = {}) { - const width = Math.round( - (opts.crop?.width ?? viewport.width) * (opts.scale ?? 1), - ); - const height = Math.round( - (opts.crop?.height ?? viewport.height) * (opts.scale ?? 1), - ); + const crop = opts.crop ?? { + x: 0, + y: 0, + width: viewport.width, + height: viewport.height, + }; + const k = opts.scale ?? 1; + const width = Math.round(crop.width * k); + const height = Math.round(crop.height * k); + const data = new Uint8ClampedArray(width * height * 4); + // Models are the only things the stub draws into pixels. + for (const square of modelSquares()) { + for (let row = 0; row < height; row++) { + const y = crop.y + (row + 0.5) / k; + if (Math.abs(y - square.y) > square.half) continue; + for (let col = 0; col < width; col++) { + const x = crop.x + (col + 0.5) / k; + if (Math.abs(x - square.x) > square.half) continue; + data.set(square.rgba, (row * width + col) * 4); + } + } + } return /** @type {ImageData} */ ( - /** @type {unknown} */ ({ - width, - height, - data: new Uint8ClampedArray(width * height * 4), - }) + /** @type {unknown} */ ({ width, height, data }) ); }, async whenSettled() { diff --git a/src/render/stub/stub.test.mjs b/src/render/stub/stub.test.mjs index 5b4595b85..fc4dccf82 100644 --- a/src/render/stub/stub.test.mjs +++ b/src/render/stub/stub.test.mjs @@ -14,8 +14,7 @@ test('the stub passes the conformance suite', async () => { const skipped = report.results .filter((r) => r.status === 'skip') .map((r) => r.id); - // Only the model check, which needs a glTF asset the stub has no use for. - assert.deepEqual(skipped, ['draw.models']); + assert.deepEqual(skipped, []); }); test('a frame runs the contract’s steps in order', () => {