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
@@ -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