From 2c9a268694350113d02407c08528958d7df458d6 Mon Sep 17 00:00:00 2001 From: Denis Groshev Date: Tue, 17 Nov 2026 16:45:53 +0100 Subject: [PATCH] Renderer contract: model nodes behind a modelNodes capability, with a conformance check ModelItem.nodes had no conformance check. A renderer that poses a model's named glTF nodes now lists modelNodes (the Cesium port does); one without it draws the model as authored. The check draw.models.nodes moves the harness model's node off the screen's centre through nodes, live, ignores a name the model lacks, and gives the node its authored pose back when it leaves the map; it runs on the Cesium harness (141 passed, 0 failed) and on the stub, whose model is one node named after its file. Each harness names its model's node (assets.modelNode). --- dev/conformance/main.js | 3 ++ docs/RENDERER-CONTRACT.md | 7 ++- src/render/cesium/harness.js | 3 ++ src/render/cesium/ports.js | 2 + src/render/cesium/ports.test.mjs | 9 +++- src/render/conformance/checks/ports.js | 65 ++++++++++++++++++++++++++ src/render/conformance/index.d.ts | 2 + src/render/contract/common.d.ts | 2 + src/render/contract/draw.d.ts | 3 +- src/render/contract/index.js | 1 + src/render/stub/harness.js | 2 + src/render/stub/index.js | 42 +++++++++++++++++ 12 files changed, 137 insertions(+), 4 deletions(-) diff --git a/dev/conformance/main.js b/dev/conformance/main.js index a1fb6c48a2..c2762dddd8 100644 --- a/dev/conformance/main.js +++ b/dev/conformance/main.js @@ -31,6 +31,8 @@ const ctx = { toEcef, assets: { model: '/models/fleet/aircraft/c172.glb', + // Its one node, which the `nodes` check moves. + modelNode: 'c172', // Not served: the model failure check loads it. missingModel: '/models/conformance-missing.glb', }, @@ -47,6 +49,7 @@ const HARNESSES = { cesium: () => [ createCesiumHarness({ model: ctx.assets.model, + modelNode: ctx.assets.modelNode, missingModel: ctx.assets.missingModel, }), { only: (id) => CESIUM_CHECKS.has(id) }, diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 0977aadb26..9a62456336 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -304,8 +304,11 @@ model's named glTF nodes, each a column-major 4×4 matrix in the node's parent frame that replaces the node's own (the ISS's solar arrays, radiators, dishes and arms). They change live; a node whose name leaves the map goes back to its authored pose, and names the model lacks are ignored. -The Cesium port writes each node's matrix once the model is ready, and -again only when its numbers change. +A renderer that poses nodes lists `modelNodes`; one without it draws the +model as authored. The Cesium port lists it, and writes each node's matrix +once the model is ready, and again only when its numbers change. The check +`draw.models.nodes` moves the harness model's node off the screen's centre +and back. The Cesium port draws timed imagery (`imageryFrames`): a layer given a timed source hides its own imagery and draws each frame its clock shows as a Cesium diff --git a/src/render/cesium/harness.js b/src/render/cesium/harness.js index 62f06cf0fc..b8d0cb6a22 100644 --- a/src/render/cesium/harness.js +++ b/src/render/cesium/harness.js @@ -82,6 +82,7 @@ export const CESIUM_CHECKS = new Set([ 'draw.models', 'draw.shapes.lit', 'draw.models.loadFailed', + 'draw.models.nodes', 'draw.models.tint', 'draw.models.blend', 'draw.models.update', @@ -194,6 +195,7 @@ function nextFrame() { export function createCesiumHarness({ name = 'cesium', model, + modelNode, missingModel, cameraController, } = {}) { @@ -266,6 +268,7 @@ export function createCesiumHarness({ ? { assets: { model, + ...(modelNode ? { modelNode } : {}), missingModel, // The model's bytes, for the check that a model drawn from them // never fetches its url. diff --git a/src/render/cesium/ports.js b/src/render/cesium/ports.js index e368983307..2d98b2d0d1 100644 --- a/src/render/cesium/ports.js +++ b/src/render/cesium/ports.js @@ -73,6 +73,8 @@ export function cesiumCapabilities(scene, only) { // Cesium scatters drawn models through the atmosphere wherever the // scene draws fog (its models' atmosphere stage). 'modelAtmosphere', + // A model item's nodes, written to the model's runtime nodes. + 'modelNodes', 'quads', 'meshes', // Raster shells; other field kinds are refused. diff --git a/src/render/cesium/ports.test.mjs b/src/render/cesium/ports.test.mjs index 04ef937fd1..82d48441e2 100644 --- a/src/render/cesium/ports.test.mjs +++ b/src/render/cesium/ports.test.mjs @@ -33,7 +33,14 @@ test('capabilities follow what the scene supports', () => { 'vectorBase', ]; const globe = { show: true }; - const draw = ['models', 'modelAtmosphere', 'quads', 'meshes', 'fields']; + const draw = [ + 'models', + 'modelAtmosphere', + 'modelNodes', + 'quads', + 'meshes', + 'fields', + ]; assert.deepEqual(cesiumCapabilities({}), [...draw, ...effects]); // A scene with a globe reads its visibility back. assert.deepEqual(cesiumCapabilities({ globe }), [ diff --git a/src/render/conformance/checks/ports.js b/src/render/conformance/checks/ports.js index faf4a8468e..4c18e4638f 100644 --- a/src/render/conformance/checks/ports.js +++ b/src/render/conformance/checks/ports.js @@ -3768,6 +3768,71 @@ export function portChecks() { }, { capability: 'models' }, ), + check( + 'draw.models.nodes', + "a model item's nodes pose its named glTF nodes, live, and a node that leaves the map goes back to its authored pose", + async (h, r) => { + if (!h.assets?.model || !h.assets?.modelNode) + return { skip: 'no model with a named node in this harness' }; + const NODE = h.assets.modelNode; + await overAustin(h, r); + const set = r.draw.models({ id: 'conf:models.nodes' }); + const ready = []; + set.on('ready', (id) => ready.push(id)); + const pos = h.toEcef({ ...AUSTIN, height: 0 }); + // Far off along the node's own x axis: off the screen's centre. + const away = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 5000, 0, 0, 1]; + const model = (nodes) => ({ + id: 'm', + pos, + url: h.assets.model, + orientation: { heading: 0, pitch: 0, roll: 0 }, + minPixelSize: 160, + environmentMap: false, + shading: 'unlit', + tint: '#ff0000', + colorBlend: { mode: 'replace' }, + ...(nodes ? { nodes } : {}), + }); + try { + set.set([model(null)]); + 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 are red. + const red = async () => { + 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) { + const [r0, g, b] = image.data.subarray(i, i + 3); + if (r0 > 180 && g < 70 && b < 70) n++; + } + return n; + }; + ok((await red()) >= 40, 'authored pose: at the centre'); + set.upsert([model({ [NODE]: away })]); + ok((await red()) < 10, 'the node moved away, live'); + set.upsert([model({ [NODE]: away, NO_SUCH_NODE: away })]); + ok((await red()) < 10, 'a name the model lacks changes nothing'); + set.upsert([model(null)]); + ok((await red()) >= 40, 'the node left the map: authored pose'); + deepEqual(ready, ['m'], 'without loading again'); + } finally { + set.dispose(); + } + }, + { capability: 'modelNodes', bareSky: true }, + ), check( 'draw.models.loadFailed', 'a model set says when a model fails to load, and loads it when added again', diff --git a/src/render/conformance/index.d.ts b/src/render/conformance/index.d.ts index 33407e78a1..27c5a21f63 100644 --- a/src/render/conformance/index.d.ts +++ b/src/render/conformance/index.d.ts @@ -68,6 +68,8 @@ export interface ConformanceHarness { ): void | Promise; assets?: { model?: string; + /** The name of a node `model` has, for the `nodes` check. */ + modelNode?: string; missingModel?: string; modelBytes?: () => Promise; }; diff --git a/src/render/contract/common.d.ts b/src/render/contract/common.d.ts index 010498e7e9..4759533938 100644 --- a/src/render/contract/common.d.ts +++ b/src/render/contract/common.d.ts @@ -157,6 +157,8 @@ export type Capability = | 'terrain' /** Atmosphere scattering applied to drawn models. */ | 'modelAtmosphere' + /** A model item's `nodes` pose the model's named glTF nodes. */ + | 'modelNodes' /** Clouds, fog, haze, rain and snow around the view (`globe.weather`). */ | 'weather' /** Imagery draped onto 3D tiles as well as the globe. */ diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts index 2cf5086e32..32ff6d341e 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -449,7 +449,8 @@ export interface ModelItem extends Placed { * joints): each a column-major 4×4 matrix in the node's parent frame that * replaces the node's own transform. A node whose name leaves the map goes * back to its authored pose; names the model lacks are ignored. Applied - * once the model is ready. Can change live. + * once the model is ready, on a renderer with the `modelNodes` + * capability; elsewhere the model draws as authored. Can change live. */ nodes?: Readonly>>; /** diff --git a/src/render/contract/index.js b/src/render/contract/index.js index d494467fab..b3aac8966c 100644 --- a/src/render/contract/index.js +++ b/src/render/contract/index.js @@ -19,6 +19,7 @@ export const CAPABILITIES = Object.freeze([ 'finestHeights', 'terrain', 'modelAtmosphere', + 'modelNodes', 'weather', 'imageryOnTiles', 'splitSwipe', diff --git a/src/render/stub/harness.js b/src/render/stub/harness.js index dc82744cbb..fbf7fa9fca 100644 --- a/src/render/stub/harness.js +++ b/src/render/stub/harness.js @@ -45,6 +45,8 @@ export function createStubHarness(name = 'stub') { // its failing scheme. assets: { model: 'stub:model.glb', + // A stub model is one node, named after its file. + modelNode: 'model', missingModel: `${STUB_FAILING_MODEL_SCHEME}model.glb`, // Any bytes: the stub parses none. modelBytes: async () => new Uint8Array([0x67, 0x6c, 0x54, 0x46]), diff --git a/src/render/stub/index.js b/src/render/stub/index.js index 9eb21cfc58..d5cb486af2 100644 --- a/src/render/stub/index.js +++ b/src/render/stub/index.js @@ -10,6 +10,7 @@ * loop on a virtual clock, one frame at a time, in the contract's order. */ import { horizonFrom } from '../../geo/horizon.js'; +import { headingPitchRollFrame } from '../../geo/quaternion.js'; import { alongLength } from '../../geo/polyline.js'; import { clusterScreenPoints } from '../../geo/screenCluster.js'; import { createInputRouter } from '../input/router.js'; @@ -808,6 +809,7 @@ export function createStubRenderer(options = {}) { function itemPosition(set, item, aheadMs = 0) { if (!item.pos) return null; const base = toEcef(item.pos); + if (set.kind === 'models') return posedModelPosition(item, base); const p = set.kind === 'icons' && item.motion && capabilities.has('motionSegments') ? motionPosition(item.motion, base, motionTime(set) + aheadMs) @@ -821,6 +823,46 @@ export function createStubRenderer(options = {}) { : p; } + /** + * Where the stub draws a model. A stub model is one node, named after its + * file (`/models/c172.glb` is `c172`, `stub:model.glb` is `model`): with + * `modelNodes`, an item's + * `nodes` entry for that name moves it by the matrix's translation, on the + * model's axes and at its scale; any other name is one the model lacks. + */ + function posedModelPosition(item, base) { + if (!capabilities.has('modelNodes') || !item.nodes) return base; + const file = String(item.url ?? '') + .split(/[?#]/)[0] + .split(/[/:]/) + .pop(); + const name = file.replace(/\.[^.]*$/, ''); + const m = name ? item.nodes[name] : null; + if (!m || m.length < 16) return base; + const k = item.scale ?? 1; + const frame = headingPitchRollFrame(base, { + heading: item.orientation?.heading ?? 0, + pitch: item.orientation?.pitch ?? 0, + roll: item.orientation?.roll ?? 0, + }); + const along = (axis, t) => ({ + x: axis.x * t * k, + y: axis.y * t * k, + z: axis.z * t * k, + }); + let p = base; + for (const [axis, t] of [ + [frame.x, m[12]], + [frame.y, m[13]], + [frame.z, m[14]], + ]) + if (t) { + const d = along(axis, t); + p = { x: p.x + d.x, y: p.y + d.y, z: p.z + d.z }; + } + return p; + } + /** * The shown models as the stub draws them: a square as wide as a pick * takes (at most `maxPixelSize`, at least `minPixelSize`), far