import test from 'node:test'; import assert from 'node:assert/strict'; import * as Cesium from 'cesium'; import { mkdtempSync, writeFileSync, readFileSync, rmSync, existsSync, } from 'node:fs'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; import { spawnSync } from 'node:child_process'; import { sceneSeekState } from '../director/timeline.js'; import { effectiveShotHoldSec, shotRuntimeDurationSec, } from '../scenes/shotPresentation.js'; import { createDefaultScenePacks } from '../scenes/packs/defaults.js'; import { createScenePackRegistry } from '../scenes/packs/registry.js'; const adapter = await import('./blenderCamera.js'); const origin = { lat: 0, lon: 0, height: 0 }; const pose = (changes = {}) => ({ lat: 0, lon: 0, alt: 0, heading: 0, pitch: 0, roll: 0, ...changes, }); const options = (changes = {}) => ({ origin, fps: { numerator: 30, denominator: 1 }, width: 1920, height: 1080, horizontalFovDegrees: 90, ...changes, }); const project = ( shots = [{ id: 'north', durationSec: 1, holdSec: 0, camera: pose() }], ) => ({ version: 6, scenes: [{ id: 'scene', title: 'Synthetic cameras', shots }], }); const near = (a, b, eps = 1e-8) => a.forEach((v, i) => assert.ok(Math.abs(v - b[i]) < eps, `${a} != ${b}`)); const camera = (changes = {}, opts = {}) => adapter.sampleSceneCameras( project([{ id: 'camera', durationSec: 1, camera: pose(changes) }]), options(opts), ).frames[0]; test('cardinal cameras use Blender X right, Y up, negative Z forward', () => { for (const [heading, right, back] of [ [0, [1, 0, 0], [0, -1, 0]], [90, [0, -1, 0], [-1, 0, 0]], [180, [-1, 0, 0], [0, 1, 0]], [270, [0, 1, 0], [1, 0, 0]], ]) { const result = camera({ heading }); near(result.basisColumns[0], right); near(result.basisColumns[1], [0, 0, 1]); near(result.basisColumns[2], back); } near(camera({ pitch: -90 }).basisColumns[2], [0, 0, 1]); near(camera({ roll: 90 }).basisColumns[1], [1, 0, 0]); }); test('ENU translation uses WGS84 meters and ellipsoid heights', () => { near(camera({ alt: 100 }).position, [0, 0, 100]); near( camera( { lat: 39.7, lon: -105, alt: 2600 }, { origin: { lat: 39.7, lon: -105, height: 1600 } }, ).position, [0, 0, 1000], 1e-6, ); const east = camera({ lon: 0.001 }).position; assert.ok(Math.abs(east[0] - 111.3194907876) < 1e-6); assert.ok(Math.abs(east[2] + 0.0009714458) < 1e-6); }); test('changed tangent frames and nonzero roll match an independent Cesium Camera', () => { const anchor = { lat: 39.7, lon: -105, height: 1600 }; const p = pose({ lat: 39.73, lon: -104.97, alt: 2400, heading: 47, pitch: -29, roll: 37, }); const reference = new Cesium.Camera({ drawingBufferWidth: 1920, drawingBufferHeight: 1080, mapProjection: new Cesium.GeographicProjection(), mode: Cesium.SceneMode.SCENE3D, }); reference.setView({ destination: Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.alt), orientation: { heading: Cesium.Math.toRadians(p.heading), pitch: Cesium.Math.toRadians(p.pitch), roll: Cesium.Math.toRadians(p.roll), }, }); const inverse = Cesium.Matrix4.inverseTransformation( Cesium.Transforms.eastNorthUpToFixedFrame( Cesium.Cartesian3.fromDegrees(anchor.lon, anchor.lat, 0), ), new Cesium.Matrix4(), ); const arr = (v) => [v.x, v.y, v.z]; const local = (v) => arr( Cesium.Matrix4.multiplyByPointAsVector( inverse, v, new Cesium.Cartesian3(), ), ); const actual = camera(p, { origin: anchor }); near(actual.basisColumns[0], local(reference.rightWC)); near(actual.basisColumns[1], local(reference.upWC)); near( actual.basisColumns[2], local( Cesium.Cartesian3.negate(reference.directionWC, new Cesium.Cartesian3()), ), ); }); test('explicit horizontal lens works for landscape and portrait output', () => { for (const [width, height] of [ [1920, 1080], [1080, 1920], ]) { const m = adapter.sampleSceneCameras(project(), options({ width, height })); assert.ok(Math.abs(m.camera.lensMm - 18) < 1e-10); assert.ok( Math.abs(m.camera.sensorHeightMm - (36 * height) / width) < 1e-10, ); } }); test('anchors, cubic moves, cuts, holds and rational frame timing are sampled', () => { const p = project([ { id: 'move', durationSec: 0.4, holdSec: 0.2, camera: { anchorId: 'end', heading: 10, pitch: 0, roll: 20 }, move: { from: { ...pose({ lon: 179.999, heading: 350 }), altitudeReference: 'ellipsoid', }, easing: 'cubic-in-out', }, }, { id: 'cut', durationSec: 0.2, holdSec: 0, camera: pose({ lon: -179.999, heading: 90 }), }, ]); p.scenes[0].anchors = [ { id: 'end', lat: 0, lon: -179.999, alt: 20, altitudeReference: 'ellipsoid', }, ]; const m = adapter.sampleSceneCameras( p, options({ origin: { lat: 0, lon: 180, height: 0 }, fps: { numerator: 30000, denominator: 1001 }, }), ); assert.equal(m.frames.length, 24); assert.equal(m.source.sceneId, 'scene'); assert.deepEqual( m.shots.map((s) => s.id), ['move', 'cut'], ); assert.equal(m.shots[0].endTimeSec, 0.6000000000000001); assert.equal(m.frames[18].shotId, 'cut'); assert.equal(m.frames[18].timeSec, (18 * 1001) / 30000); near(m.frames[12].position, m.frames[17].position); assert.equal(p.scenes[0].shots[0].camera.anchorId, 'end'); }); test('invalid or ambiguous input fails before export', () => { for (const change of [ { fps: { numerator: 0, denominator: 1 } }, { horizontalFovDegrees: undefined }, { width: 0 }, { origin: { lat: 0, lon: NaN, height: 0 } }, { horizontalFovDegrees: 180 }, ]) { assert.throws(() => adapter.sampleSceneCameras(project(), options(change))); } assert.throws(() => camera({ lon: 20 }), /100 km/); const multiple = project(); multiple.scenes.push({ ...multiple.scenes[0], id: 'other' }); assert.throws( () => adapter.sampleSceneCameras(multiple, options()), /scene/i, ); assert.throws( () => adapter.sampleSceneCameras( project([{ id: 'missing', camera: { heading: 0 } }]), options(), ), /lat|position/i, ); assert.throws( () => adapter.sampleSceneCameras( project([{ id: 'long', camera: pose(), durationSec: 86400 }]), options(), ), /frame/i, ); }); test('projection settings cannot be silently clamped by Blender', () => { assert.throws( () => adapter.sampleSceneCameras(project(), options({ width: 1 })), /width/, ); assert.throws( () => adapter.sampleSceneCameras( project(), options({ horizontalFovDegrees: 179, sensorWidthMm: 1 }), ), /lens/i, ); }); test('CLI works in paths with spaces and refuses overwrites or invalid projection', () => { const directory = mkdtempSync(join(tmpdir(), 'gev camera ')); try { const input = join(directory, 'saved scene.json'); const output = join(directory, 'camera stage.usda'); const scenes = project(); scenes.scenes.push({ ...scenes.scenes[0], id: 'other' }); writeFileSync(input, JSON.stringify(scenes)); const script = fileURLToPath( new URL('../../tools/export-blender-camera.mjs', import.meta.url), ); const args = [ script, '--input', input, '--output', output, '--scene', 'other', // A leading minus must not read as a missing --origin value. '--origin', '-0,0,0', '--fps', '30000/1001', '--width', '1920', '--height', '1080', '--horizontal-fov-deg', '60', ]; const first = spawnSync(process.execPath, args, { encoding: 'utf8' }); assert.equal(first.status, 0, first.stderr); assert.match(first.stdout, /CAMERA_EXPORT_OK/); const contents = readFileSync(output, 'utf8'); assert.match(contents, /^#usda 1\.0\n/); assert.match(contents, /userProperties:gevFps = "30000\/1001"/); assert.match(contents, /userProperties:gevSceneId = "other"/); const unknownOutput = join(directory, 'unknown.usda'); const unknown = [...args]; unknown[unknown.indexOf('other')] = 'missing'; unknown[unknown.indexOf(output)] = unknownOutput; const missingScene = spawnSync(process.execPath, unknown, { encoding: 'utf8', }); assert.equal(missingScene.status, 1); assert.match( missingScene.stderr, /No scene has ID missing; scenes: scene, other/, ); assert.equal(existsSync(unknownOutput), false); const repeat = spawnSync(process.execPath, args, { encoding: 'utf8' }); assert.equal(repeat.status, 1); assert.equal(readFileSync(output, 'utf8'), contents); const jsonOutput = join(directory, 'cameras.json'); const wrongExtension = [...args]; wrongExtension[wrongExtension.indexOf(output)] = jsonOutput; const rejected = spawnSync(process.execPath, wrongExtension, { encoding: 'utf8', }); assert.equal(rejected.status, 1); assert.match(rejected.stderr, /\.usda/); assert.equal(existsSync(jsonOutput), false); const invalidOutput = join(directory, 'invalid.usda'); const invalid = [...args]; invalid[invalid.indexOf(output)] = invalidOutput; invalid[invalid.length - 1] = '180'; assert.equal( spawnSync(process.execPath, invalid, { encoding: 'utf8' }).status, 1, ); assert.equal(existsSync(invalidOutput), false); } finally { rmSync(directory, { recursive: true, force: true }); } }); test('long decimal timelines do not gain a rounding-only frame', () => { // At 30 fps the accumulated duration is 63900.00000000164 frames. const p = project( Array.from({ length: 1000 }, (_, i) => ({ id: `shot-${i}`, durationSec: 2.13, holdSec: 0, camera: pose(), })), ); const m = adapter.sampleSceneCameras(p, options()); assert.equal(m.frames.length, 63900); assert.equal(m.shots[999].frameEndExclusive, 63901); // 1.06 + 2.99 s is 243.00000000000006 frames at 60 fps. const held = adapter.sampleSceneCameras( project([{ id: 'held', durationSec: 1.06, holdSec: 2.99, camera: pose() }]), options({ fps: { numerator: 60, denominator: 1 } }), ); assert.equal(held.frames.length, 243); }); test('a frame before the exclusive scene end is never dropped', () => { for (const [durationSec, numerator, denominator, frames] of [ [666.333, 23976, 1000, 15977], [366.333, 2997, 100, 10980], [2000.000001, 30, 1, 60001], ]) { const m = adapter.sampleSceneCameras( project([{ id: 'shot', durationSec, holdSec: 0, camera: pose() }]), options({ fps: { numerator, denominator } }), ); assert.equal(m.frames.length, frames, `${durationSec} s`); assert.ok(m.frames.at(-1).timeSec < durationSec); } // The last shot owns only the final frame at t = 120 s. const m = adapter.sampleSceneCameras( project([ { id: 'a', durationSec: 119.80000003, holdSec: 0, camera: pose() }, { id: 'b', durationSec: 0.2, holdSec: 0, camera: pose({ heading: 10 }) }, ]), options({ fps: { numerator: 1, denominator: 1 } }), ); assert.deepEqual( [m.shots[1].frameStart, m.shots[1].frameEndExclusive], [121, 122], ); }); const runtimeSeek = (scene, timeSec, durationSec, packs) => sceneSeekState( scene, timeSec / durationSec, (s, shot) => shotRuntimeDurationSec(s, shot, packs), (s, shot) => effectiveShotHoldSec(s, shot, packs), ); test('shot timing follows Director runtime holds, not only the saved holdSec', () => { // The Director's Mailung trim plays a 7.65 s hold although 15 s was saved. const p = project([ { id: 'mailung', sourcePackId: 'bhote-koshi-nepal-evidence-pack', durationSec: 4.2, holdSec: 15, camera: pose(), layers: { 'bhote-koshi-2026': { enabled: true, params: { presentation: 'scene-beat', beatId: 'mailung-bazzar' }, }, }, }, { id: 'next', durationSec: 1, holdSec: 0, camera: pose({ heading: 90 }) }, ]); const before = structuredClone(p); const m = adapter.sampleSceneCameras(p, options()); const [first, second] = m.shots; assert.equal(first.authoredHoldSec, 15); assert.equal(first.runtimeHoldSec, 7.65); assert.equal(second.startTimeSec, 4.2 + 7.65); // Summing authored holds would start the next shot 7.35 s (220 frames) later. assert.equal(second.frameStart, Math.ceil((4.2 + 7.65) * 30) + 1); assert.equal(m.timeline.durationSec, 4.2 + 7.65 + 1); const packs = createDefaultScenePacks(); p.scenes[0].shots.forEach((shot, i) => assert.equal( m.shots[i].runtimeHoldSec, effectiveShotHoldSec(p.scenes[0], shot, packs), ), ); for (const sample of m.frames) { const state = runtimeSeek( p.scenes[0], sample.timeSec, m.timeline.durationSec, packs, ); assert.equal(sample.shotId, state.shot.id); const expected = adapter.cameraPoseToEnu(state.camera, origin); near(sample.position, expected.position); sample.basisColumns.forEach((axis, i) => near(axis, expected.basisColumns[i]), ); } assert.deepEqual(p, before, 'export never rewrites saved shots'); }); test('registered minimum holds and evidence-sequence durations shift later shots', () => { const packs = createScenePackRegistry({ recipes: [ { id: 'sample', runtimeControlsByBeat: { arrival: { evidenceSequence: true, evidenceSequenceDurationSec: 2.5 }, }, }, ], adapters: [ { minimumHoldSec: (states) => (states.overview?.enabled ? 3 : 0) }, ], }); const p = project([ { id: 'evidence', sourcePackId: 'sample', durationSec: 1, holdSec: 0.5, camera: pose(), layers: { sample: { enabled: true, params: { presentation: 'scene-beat', beatId: 'arrival' }, }, }, }, { id: 'overview', durationSec: 1, holdSec: 0, camera: pose({ heading: 45 }), layers: { overview: { enabled: true, params: {} } }, }, { id: 'last', durationSec: 1, holdSec: 0, camera: pose({ heading: 90 }) }, ]); const m = adapter.sampleSceneCameras(p, options({ scenePacks: packs })); assert.deepEqual( m.shots.map((s) => [s.startTimeSec, s.runtimeHoldSec, s.frameStart]), [ [0, 2.5, 1], [3.5, 3, 106], [7.5, 0, 226], ], ); assert.equal(m.frames.length, 255); // The holds match the Director's own seek path, which resolves layer states itself. p.scenes[0].shots.forEach((shot, i) => assert.equal( m.shots[i].runtimeHoldSec, effectiveShotHoldSec(p.scenes[0], shot, packs), ), ); }); const usdNumbers = (text) => text.match(/-?\d+(?:\.\d+)?(?:e[-+]?\d+)?/g).map(Number); test('USD stage is Z-up meters with one camera per shot and per-frame matrices', () => { const p = project([ { id: 'first shot', title: 'He said "hi"\n', durationSec: 0.2, holdSec: 0, camera: pose({ heading: 30, roll: 10, alt: 50 }), }, { id: 'second', durationSec: 0.1, holdSec: 0, camera: pose({ heading: 200, lon: 0.0005, pitch: -30 }), }, ]); const { usda, samples } = adapter.exportCameraUsda(p, options()); assert.match(usda, /^#usda 1\.0\n/); for (const line of [ 'upAxis = "Z"', 'metersPerUnit = 1', 'startTimeCode = 1', `endTimeCode = ${samples.timeline.frameEnd}`, 'timeCodesPerSecond = 30', 'framesPerSecond = 30', 'defaultPrim = "GEV"', ]) assert.ok(usda.includes(`\n ${line}\n`), line); assert.match(usda, /userProperties:gevSchema = "gev\.camera-usd\.v1"/); const cameras = usda.split('\n def Camera ').slice(1); assert.equal(cameras.length, 2); assert.match(cameras[0], /^"Shot_001_first_shot"/); assert.match(cameras[1], /^"Shot_002_second"/); // USD lens values are tenths of a scene unit (100 mm at metersPerUnit 1): // a 90 degree horizontal FOV on a 36 mm sensor is an 18 mm lens. assert.match(cameras[0], /\n {8}float focalLength = 0\.18\n/); assert.match(cameras[0], /\n {8}float horizontalAperture = 0\.36\n/); assert.match(cameras[0], /\n {8}float verticalAperture = 0\.2025\n/); assert.match(cameras[0], /\n {8}token projection = "perspective"\n/); assert.ok( cameras[0].includes( 'custom string userProperties:gevShotTitle = "He said \\"hi\\"\\n"', ), ); assert.ok( cameras[0].includes( 'custom string userProperties:gevShotId = "first shot"', ), ); cameras.forEach((text, index) => { const shot = samples.shots[index]; const keys = [...text.matchAll(/\n {12}(\d+): \((.*)\),/g)]; assert.deepEqual( keys.map(([, key]) => Number(key)), Array.from( { length: shot.frameEndExclusive - shot.frameStart }, (_, i) => shot.frameStart + i, ), ); for (const [, key, matrix] of keys) { const values = usdNumbers(matrix); const frame = samples.frames[Number(key) - 1]; assert.equal(frame.shotId, shot.id); const [right, up, back] = frame.basisColumns; near(values, [...right, 0, ...up, 0, ...back, 0, ...frame.position, 1]); } assert.match( text, /uniform token\[\] xformOpOrder = \["xformOp:transform"\]/, ); }); }); test('USD stage records rational fps and portrait apertures', () => { const { usda, samples } = adapter.exportCameraUsda( project(), options({ width: 1080, height: 1920, fps: { numerator: 30000, denominator: 1001 }, }), ); assert.ok(usda.includes(`\n timeCodesPerSecond = ${30000 / 1001}\n`)); assert.ok(usda.includes('userProperties:gevFps = "30000/1001"')); assert.match(usda, /float verticalAperture = 0\.64\n/); assert.equal(samples.timeline.frameEnd, 30); }); test('a scene is selected by sceneId', () => { const p = project(); p.scenes.push({ id: 'other', title: 'Other', shots: [ { id: 'east', durationSec: 1, holdSec: 0, camera: pose({ lon: 0.001 }) }, ], }); const m = adapter.sampleSceneCameras(p, options({ sceneId: 'other' })); assert.equal(m.source.sceneId, 'other'); assert.deepEqual( m.shots.map((s) => s.id), ['east'], ); near( m.frames[0].position, adapter.cameraPoseToEnu(pose({ lon: 0.001 }), origin).position, ); assert.throws( () => adapter.sampleSceneCameras(p, options()), /--scene: scene, other/, ); }); const usdcat = spawnSync('usdcat', ['--help']).status === 0; test( 'OpenUSD parses the stage', { skip: !usdcat && 'usdcat is not installed' }, () => { const directory = mkdtempSync(join(tmpdir(), 'gev usd ')); try { const file = join(directory, 'cameras.usda'); const p = project([ { id: 'a', durationSec: 0.2, holdSec: 0, camera: pose() }, { id: 'b', durationSec: 0.2, holdSec: 0, camera: pose({ heading: 90 }), }, ]); writeFileSync(file, adapter.exportCameraUsda(p, options()).usda); const result = spawnSync('usdcat', [file], { encoding: 'utf8' }); assert.equal(result.status, 0, result.stderr); assert.match(result.stdout, /def Camera "Shot_002_b"/); assert.match(result.stdout, /float focalLength = 0\.18/); assert.match(result.stdout, /\b7: \( \(/); } finally { rmSync(directory, { recursive: true, force: true }); } }, );