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).
This commit is contained in:
Denis Groshev committed 2026-11-17 16:45:53 +01:00
1 parent 808941d973
commit 2c9a268694
12 files changed
+137 -4

No files matched your search

+3
View File
@@ -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) },
+5 -2
View File
@@ -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
+3
View File
@@ -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.
+2
View File
@@ -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.
+8 -1
View File
@@ -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 }), [
+65
View File
@@ -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',
+2
View File
@@ -68,6 +68,8 @@ export interface ConformanceHarness {
): void | Promise<void>;
assets?: {
model?: string;
/** The name of a node `model` has, for the `nodes` check. */
modelNode?: string;
missingModel?: string;
modelBytes?: () => Promise<Uint8Array>;
};
+2
View File
@@ -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. */
+2 -1
View File
@@ -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<Record<string, ArrayLike<number>>>;
/**
+1
View File
@@ -19,6 +19,7 @@ export const CAPABILITIES = Object.freeze([
'finestHeights',
'terrain',
'modelAtmosphere',
'modelNodes',
'weather',
'imageryOnTiles',
'splitSwipe',
+2
View File
@@ -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]),
+42
View File
@@ -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