diff --git a/changelog.d/1690-iss-3d-model.md b/changelog.d/1690-iss-3d-model.md index db740e1c44..357b040acc 100644 --- a/changelog.d/1690-iss-3d-model.md +++ b/changelog.d/1690-iss-3d-model.md @@ -3,4 +3,6 @@ radiators by the Sun, Ku-band dishes toward the relay satellites, robotic arms as an illustrative sway. Selecting the ISS opens NASA's official live video and a command panel with a zoom to the station, an Automatic mode and - Manual controls for each moving part (Itallo Brandão, @IMBrandao, #1690). + Manual controls for each moving part. The model draws through the renderer + contract, whose model items gain `nodes` for a model's moving joints + (Itallo Brandão, @IMBrandao, #1690). diff --git a/changelog.d/0000-iss-live-telemetry.md b/changelog.d/1690-iss-live-telemetry.md similarity index 90% rename from changelog.d/0000-iss-live-telemetry.md rename to changelog.d/1690-iss-live-telemetry.md index 9454463419..cfcd0e4d26 100644 --- a/changelog.d/0000-iss-live-telemetry.md +++ b/changelog.d/1690-iss-live-telemetry.md @@ -2,24 +2,24 @@ angles from NASA's public ISSLive telemetry. Off by default: set `ISS_TELEMETRY_ENABLED=1` and the server relays the feed over one connection, open only while the model is on screen; without signal the joints keep their - computed rules (Denis Groshev, @ZloyS, #0000). + computed rules (Denis Groshev, @ZloyS, #1690). - Ride the ISS in the Cockpit from the station itself: views looking out from Nauka, Zarya, Poisk, the Cupola, Kibo and a docked vehicle, with the 3D model drawn, instead of the straight-down picture. It opens on Nauka, two arrows step through the rest, the readout describes the module each view is from (the Cupola and Kibo, which have no catalog entries, with cards of - their own), and leaving selects Nauka (Denis Groshev, @ZloyS, #0000). + their own), and leaving selects Nauka (Denis Groshev, @ZloyS, #1690). - Keep the ISS model centred, and offer its STATION and LIVE sections, when a click on the station's dot selects Nauka or a docked vehicle instead of the ISS entry; such an entry shows the ISS's orbit ring rather than a second ring - of its own (Denis Groshev, @ZloyS, #0000). + of its own (Denis Groshev, @ZloyS, #1690). - Move the ISS's command panel from a floating window into a STATION section of Context, shown while the station is selected on the map: Automatic says where the joints' angles come from (telemetry and how old it is, or computed values and why), Manual pauses telemetry and offers the Sun positions, array and radiator folding, dish aim and the Canadarm2 sliders. Another station plugs in with a description of its own - (Denis Groshev, @ZloyS, #0000). + (Denis Groshev, @ZloyS, #1690). - Move the ISS's live video from a floating player into a LIVE section of Context: two NASA streams (exterior cameras; live video with space-to-ground audio), stepped with arrows, with an ON AIR dot while one plays and an @@ -27,7 +27,7 @@ muted, as soon as the station is selected; the section's +/- hides it without stopping it. In the Cockpit the same stream is the briefing's fourth page, LIVE, which Previous, Next and the tabs reach and the - automatic page cycle never turns to (Denis Groshev, @ZloyS, #0000). + automatic page cycle never turns to (Denis Groshev, @ZloyS, #1690). - Draw China's Tiangong station as a 3D model up close, the second station after the ISS: an original model of the T configuration with a Shenzhou forward and nadir and a Tianzhou aft, its wings following the Sun, its @@ -36,8 +36,8 @@ Tianhe, a lab or a docked ship gives the STATION section for Tiangong (Sun positions, each wing on its own slider, the two arms by joint); the model stands in for the docked entries' dots and is hidden while the Cockpit rides the station - (Denis Groshev, @ZloyS, #0000). + (Denis Groshev, @ZloyS, #1690). - Let a click on a mapped installation's label box count as a click on the site: it focuses the site in the orbital Cockpit view and selects it on the map, as a click on its 7 px dot did; from orbit the label is what a click - lands on (Denis Groshev, @ZloyS, #0000). + lands on (Denis Groshev, @ZloyS, #1690). diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 1181f4cda5..85726a294c 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1912,8 +1912,9 @@ waits while it is shown. The credit links the owner and the stream's own page, and the section's note says the video plays from YouTube. The model is NASA/JSC IGOAL's current-configuration station, reduced to 3 MB with its joints kept as nodes (`public/models/README.md`), fetched only once -the camera nears its range. `issArticulation.js` turns them every frame, by -default from computation: the two alpha joints and eight beta joints face +the camera nears its range, and drawn as an item of a `models` set of the +renderer's draw port, its joints posed through the item's `nodes`. +`issArticulation.js` turns them every frame, by default from computation: the two alpha joints and eight beta joints face the arrays to the Sun (feathered along the flight direction in the Earth's shadow, taken as a cylinder), the two radiator joints keep the radiators edge-on to it, the two Ku-band dishes aim at the highest TDRS nominal slots diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 9b055c2269..0977aadb26 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -299,6 +299,14 @@ correction turns them to, paints the mask in a custom shader per colour clipping plane through the model's origin. The checks `draw.models.bytes` and `draw.models.fleet` cover them. +An articulated model's joints are its item's `nodes`: transforms of the +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. + 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 imagery layer just above it (in `blend` mode the later frame over the earlier diff --git a/src/layers/satellites/stationModel.js b/src/layers/satellites/stationModel.js index 7e154d4da9..dcd77a6ef1 100644 --- a/src/layers/satellites/stationModel.js +++ b/src/layers/satellites/stationModel.js @@ -18,9 +18,9 @@ import { stationTrackedOn } from './policy.js'; * a second, which at model range would show as a jump). * * The moving parts (the joint driver, `createArticulation`) write node - * matrices into this part's node poses (`_nodePoses`), as they would into a - * model's nodes; the draw contract has no per-node posing yet, so the model - * draws rigid until it has, and the poses are kept for it. + * matrices into this part's node poses, as they would into a model's nodes; + * those poses are the draw item's `nodes`, which the renderer applies to the + * model's named glTF nodes. * * @typedef {object} StationModelSpec * @property {string} key Short id ('iss', 'tiangong'): the STATION @@ -147,12 +147,14 @@ export function stationModelOrientation(position, axes, localAxes) { /** * Node poses as a joint driver writes them: `getNode(name)` hands a node * whose `matrix` it sets (a column-major 4×4, copied on write, as a model's - * node copies), and `poses` keeps every matrix written, by node name. + * node copies), and `poses` keeps every matrix written, by node name: the + * draw item's `nodes` (`ModelItem.nodes`), one object for the item's life. * @returns {{ready: boolean, getNode: (name: string) => {matrix: Float64Array}, - * poses: Map, clear: () => void}} + * poses: Record, clear: () => void}} */ export function createNodePoses() { - const poses = new Map(); + /** @type {Record} */ + const poses = {}; const nodes = new Map(); return { ready: true, @@ -162,14 +164,10 @@ export function createNodePoses() { if (!node) { node = { get matrix() { - return poses.get(name); + return poses[name]; }, set matrix(value) { - let kept = poses.get(name); - if (!kept) { - kept = new Float64Array(16); - poses.set(name, kept); - } + const kept = (poses[name] ??= new Float64Array(16)); for (let i = 0; i < 16; i++) kept[i] = value[i]; }, }; @@ -177,8 +175,9 @@ export function createNodePoses() { } return node; }, + /** Every node back to its authored pose (its name leaves the map). */ clear() { - poses.clear(); + for (const name of Object.keys(poses)) delete poses[name]; }, }; } @@ -318,6 +317,8 @@ export function createStationModel( displayRange: nearRange, // So a click on the model tracks the station, as a click on its dot does. meta: { norad }, + // The joint driver's poses, applied to the model's named nodes. + nodes: nodePoses.poses, show: false, }; set.upsert([item]); @@ -763,7 +764,7 @@ export function createStationModel( _telemetryStatus: () => telemetry?.status() ?? null, /** The joint driver, for the STATION section. */ _articulation: articulation, - /** The node matrices the joint driver last wrote, by node name. */ + /** The node matrices the joint driver last wrote, by node name (the item's `nodes`). */ _nodePoses: nodePoses.poses, }; } diff --git a/src/layers/satellites/stationModel.test.mjs b/src/layers/satellites/stationModel.test.mjs index e2cbca7f30..2b85285284 100644 --- a/src/layers/satellites/stationModel.test.mjs +++ b/src/layers/satellites/stationModel.test.mjs @@ -248,7 +248,23 @@ test('posed, the model sits on the station with its flight axes as heading, pitc const track = column(ISS_MODEL_LOCAL_AXES.indexOf('x')); assert.ok(Math.abs(along(track)) < 1e-6, 'the along-track axis is level'); assert.equal(f.updates.length, 1, 'the joints are driven'); - assert.equal(f.updates[0][0].ready, true, 'into node poses'); + const nodes = f.updates[0][0]; + assert.equal(nodes.ready, true, 'into node poses'); + // What the driver writes to a node is the item's `nodes`, by name, as a + // column-major matrix the renderer applies to the model's glTF node. + const turned = new Float64Array(16); + turned[0] = turned[5] = turned[10] = turned[15] = 1; + turned[14] = 2.5; + nodes.getNode('SOLAR_JOINT').matrix = turned; + f.tick(); + assert.equal(item.nodes, f.model._nodePoses, 'one object for the item'); + assert.deepEqual(Array.from(item.nodes.SOLAR_JOINT), Array.from(turned)); + f.model._destroyStationModel(); + assert.equal( + Object.keys(f.model._nodePoses).length, + 0, + 'destroyed, every node goes back to its authored pose', + ); }); test('a station without views on its model hides it while the Cockpit rides the station, its own entry or a docked one', async (t) => { diff --git a/src/render/cesium/draw.test.mjs b/src/render/cesium/draw.test.mjs index 8a5ae33a5f..a593aa47d0 100644 --- a/src/render/cesium/draw.test.mjs +++ b/src/render/cesium/draw.test.mjs @@ -7053,6 +7053,62 @@ test('models moved every frame keep their shader and pick ids: only a new look o } }); +test('a model poses its named nodes once ready, writes only what changed, and gives a dropped one its own pose back', async () => { + const { loads, restore } = fakeModelLoads(); + try { + const part = createCesiumDraw({ + scene: fakeScene(), + report: (error) => assert.fail(error), + }); + const set = part.port.models({ id: 'station' }); + const turn = (x) => [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, 0, 0, 1]; + const item = (nodes) => ({ + id: 'iss', + pos: { lon: 0, lat: 0, height: 400e3 }, + url: 'iss.glb', + orientation: { heading: 0, pitch: 0, roll: 0 }, + nodes, + }); + set.upsert([item({ joint: turn(1), other: turn(2), missing: turn(3) })]); + loads[0].resolve(); + await settle(); + const model = loads[0].model; + const writes = []; + const nodes = {}; + for (const name of ['joint', 'other']) + nodes[name] = { + originalMatrix: Cesium.Matrix4.fromTranslation( + new Cesium.Cartesian3(9, 9, 9), + ), + set matrix(m) { + writes.push(name); + this.current = m; + }, + }; + model.getNode = (name) => { + assert.equal(model.ready, true, 'nodes are asked for once ready'); + return nodes[name]; + }; + loads[0].ready(); + assert.deepEqual(writes.sort(), ['joint', 'other'], 'posed when ready'); + assert.equal(nodes.joint.current[12], 1); + assert.equal(nodes.other.current[12], 2); + + writes.length = 0; + set.upsert([item({ joint: turn(1), other: turn(5), missing: turn(3) })]); + assert.deepEqual(writes, ['other'], 'only the node that moved'); + assert.equal(nodes.other.current[12], 5); + + writes.length = 0; + set.upsert([item({ other: turn(5) })]); + assert.deepEqual(writes, ['joint'], 'the dropped node, back to its pose'); + assert.equal(nodes.joint.current[12], 9); + set.dispose(); + } finally { + restore(); + } +}); + test('a model set that recedes fades its models toward the limb with their focus; focus alone dims', async () => { const { recedeFactors, recedeFrame, recedeParams, recededAlpha } = await import('../recession.js'); diff --git a/src/render/cesium/drawModels.js b/src/render/cesium/drawModels.js index 41dbb62c13..80e9e7c8e1 100644 --- a/src/render/cesium/drawModels.js +++ b/src/render/cesium/drawModels.js @@ -5,7 +5,7 @@ * 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`, - * `show`); only a new `url` loads again, and the old model keeps drawing + * `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. @@ -55,6 +55,46 @@ export const MODEL_RETRY_MS = 5000; */ 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(); + +/** + * 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); + const node = model.getNode(name); + if (node && last) 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 && sameMatrix(last, matrix)) continue; + const node = model.getNode(name); + posed.set(name, node ? Array.from(matrix).slice(0, 16) : null); + if (node) node.matrix = Cesium.Matrix4.fromArray(matrix); + } +} + +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; @@ -439,6 +479,7 @@ export function createModelSets({ 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); } diff --git a/src/render/contract/draw.d.ts b/src/render/contract/draw.d.ts index a1a1558e73..2cf5086e32 100644 --- a/src/render/contract/draw.d.ts +++ b/src/render/contract/draw.d.ts @@ -444,6 +444,14 @@ export interface ModelItem extends Placed { * would not hide what lies below it). Can change live. */ clip?: 'belowOrigin'; + /** + * Transforms of the model's named glTF nodes (an articulated model's + * 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. + */ + nodes?: Readonly>>; /** * Emphasis for a focused model, 0..1, 1 = none: the tint's alpha is * multiplied by it (in a set that recedes, as `RecedeSpec` says). Can