Export Director cameras as a USD stage and use runtime shot timing

Address review on #1460:

- Replace the custom JSON manifest and the bpy importer with a plain-text
  .usda stage written from Node (no new dependency) that Blender imports
  natively: Z-up, metersPerUnit 1, one camera per shot with per-frame
  xformOp:transform samples, time codes equal to frame numbers, and lens
  attributes in tenths of a scene unit (Blender multiplies by
  100 * metersPerUnit).
- Take shot timing from shotRuntimeDurationSec/effectiveShotHoldSec, the
  functions Director playback and seeking use, so pack hold overrides,
  minimum holds and evidence-sequence durations match the app.
- Extract runtimeLayerStatesForShot in shotPresentation.js (behaviour
  unchanged) so holds for long scenes are resolved without quadratic work.
- Remove tools/blender Python files; update docs, tests and changelog.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01BahZiNcXqNSvAmR5TCuTAu
This commit is contained in:
UBN606andClaude Opus 5.5 committed 2026-11-03 19:34:33 +00:00
1 parent 6b60b9e969
commit 159c0cfcb0
14 files changed
+624 -865

No files matched your search

+13 -3
View File
@@ -153,8 +153,8 @@ export function effectiveShotHoldSec(
);
}
/** Estimate flight plus effective hold without mutating saved layer parameters. */
export function shotRuntimeDurationSec(scene, shot, packs) {
/** Copy a shot's layer states with registered runtime controls, without mutating saved parameters. */
export function runtimeLayerStatesForShot(shot, packs) {
const states = deepClone(shot?.layers || {});
const sourceRecipe = packs.recipeForShot(shot);
for (const state of Object.values(states)) {
@@ -168,8 +168,18 @@ export function shotRuntimeDurationSec(scene, shot, packs) {
};
}
}
return states;
}
/** Estimate flight plus effective hold without mutating saved layer parameters. */
export function shotRuntimeDurationSec(scene, shot, packs) {
return (
(shot?.durationSec || DEFAULT_SHOT_DURATION_SEC) +
effectiveShotHoldSec(scene, shot, packs, states)
effectiveShotHoldSec(
scene,
shot,
packs,
runtimeLayerStatesForShot(shot, packs),
)
);
}
+249 -38
View File
@@ -1,4 +1,4 @@
/** Camera-only interchange. No viewer, providers, environment files or terrain access. */
/** Camera-only USD interchange. No viewer, providers, environment files or terrain access. */
import * as C from 'cesium';
import { validateSceneDocument } from '../director/document.js';
import {
@@ -7,9 +7,20 @@ import {
sampleCameraMove,
} from '../director/camera.js';
import { cameraAtProgress } from '../director/timeline.js';
import {
effectiveShotHoldSec,
runtimeLayerStatesForShot,
shotRuntimeDurationSec,
} from '../scenes/shotPresentation.js';
import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
export const CAMERA_MANIFEST_SCHEMA = 'gev.camera-manifest.v1';
export const CAMERA_USD_SCHEMA = 'gev.camera-usd.v1';
export const MAX_CAMERA_FRAMES = 100000;
export const MAX_CAMERA_USDA_BYTES = 64 * 1024 * 1024;
// USD camera lens attributes are tenths of a scene unit. With metersPerUnit = 1
// one tenth is 100 mm; Blender's importer multiplies by 100 * metersPerUnit.
const MM_PER_USD_LENS_UNIT = 100;
const clamp01 = (value) => Math.max(0, Math.min(1, value));
function number(value, label, min, max) {
if (
@@ -34,7 +45,8 @@ function position(pose, heightKey = 'alt') {
/** Convert Cesium's WGS84/heading-pitch-roll pose to a fixed Blender ENU frame.
* Angles are degrees; alt and origin.height are WGS84 ellipsoid meters.
* The returned columns are Blender's local X (right), Y (up), Z (back).
* The returned columns are the camera's local X (right), Y (up), Z (back),
* which is the USD and Blender camera convention (looking down local -Z).
*/
export function cameraPoseToEnu(pose, origin) {
position(pose);
@@ -105,11 +117,40 @@ function identity(value, label) {
return value;
}
/** Export one existing scene using Director seek interpolation and authored timing.
/** Resolve the flight-plus-hold seconds and holds that Director playback and seeking use.
* Both come from shotPresentation.js, so registered pack overrides, minimum holds and
* evidence-sequence durations match the app instead of the saved holdSec alone.
*/
export function sceneRuntimeTiming(
scene,
scenePacks = createDefaultScenePacks(),
) {
const byShot = new Map();
for (const shot of scene.shots) {
const durationSec = shotRuntimeDurationSec(scene, shot, scenePacks);
// Same states shotRuntimeDurationSec uses; omitting them would rebuild
// every shot's timing per call (quadratic for long scenes).
const holdSec = effectiveShotHoldSec(
scene,
shot,
scenePacks,
runtimeLayerStatesForShot(shot, scenePacks),
);
number(durationSec, `Shot ${shot.id} runtime duration`, 0, 1e7);
number(holdSec, `Shot ${shot.id} runtime hold`, 0, 1e7);
byShot.set(shot, { durationSec, holdSec });
}
return {
durationFor: (_scene, shot) => byShot.get(shot).durationSec,
holdFor: (_scene, shot) => byShot.get(shot).holdSec,
};
}
/** Sample one saved scene with Director seek interpolation and runtime playback timing.
* Projection is explicit because scene documents do not store viewport lenses.
* Frame 1 samples time zero; the final sample precedes the exclusive end time.
*/
export function exportCameraManifest(
export function sampleSceneCameras(
project,
{
sceneId,
@@ -119,6 +160,7 @@ export function exportCameraManifest(
height,
horizontalFovDegrees,
sensorWidthMm = 36,
scenePacks = createDefaultScenePacks(),
} = {},
) {
validateSceneDocument(project);
@@ -144,6 +186,7 @@ export function exportCameraManifest(
const scene = candidates[0];
identity(scene.id, 'Scene');
if (!scene.shots.length) throw new Error('Scene has no camera shots');
const timing = sceneRuntimeTiming(scene, scenePacks);
const frameAt = (seconds) => {
const frame = seconds * rate;
return (
@@ -154,6 +197,14 @@ export function exportCameraManifest(
};
let elapsed = 0;
let rounding = 0;
const resolved = scene.shots.map((shot, index) => ({
target: resolveCameraPose(scene, shot.camera),
previous: resolveCameraPose(
scene,
scene.shots[index - 1]?.camera || shot.camera,
),
move: resolveCameraMove(scene, shot),
}));
const shots = scene.shots.map((shot) => {
identity(shot.id, 'Shot');
const camera = resolveCameraPose(scene, shot.camera);
@@ -162,18 +213,13 @@ export function exportCameraManifest(
if (move) position(move.from);
cameraPoseToEnu(camera, origin);
if (move) cameraPoseToEnu(move.from, origin);
const durationSec = shot.durationSec || 4;
const holdSec = shot.holdSec || 0;
const runtimeDurationSec = timing.durationFor(scene, shot);
const startTimeSec = elapsed;
// Compensated summation prevents long decimal timelines gaining a frame.
const increment = durationSec + holdSec - rounding;
const increment = runtimeDurationSec - rounding;
const next = elapsed + increment;
rounding = next - elapsed - increment;
elapsed = next;
const frameStart = frameAt(startTimeSec);
const frameEndExclusive = frameAt(elapsed);
if (frameStart >= frameEndExclusive)
throw new Error(`Shot ${shot.id} has no sampled frame at this fps`);
return {
id: shot.id,
title: shot.title || '',
@@ -185,41 +231,56 @@ export function exportCameraManifest(
: {}),
startTimeSec,
endTimeSec: elapsed,
durationSec,
holdSec,
frameStart,
frameEndExclusive,
camera,
move,
flightDurationSec: shot.durationSec || 4,
authoredHoldSec: Number(shot.holdSec) || 0,
runtimeHoldSec: timing.holdFor(scene, shot),
frameStart: 0,
frameEndExclusive: 0,
};
});
const frameCount = frameAt(elapsed) - 1;
if (frameCount > MAX_CAMERA_FRAMES)
throw new RangeError(`Export exceeds ${MAX_CAMERA_FRAMES} camera frames`);
if (frameCount < 1) throw new Error('Scene has no sampled frame at this fps');
// Mirror sceneSeekState (src/director/timeline.js) step for step, walking
// shots forward once instead of rescanning every shot for every frame.
// Tests compare each sample with sceneSeekState itself.
const seekEnds = [];
for (const shot of scene.shots)
seekEnds.push((seekEnds.at(-1) || 0) + timing.durationFor(scene, shot));
const seekTotalSec = seekEnds.at(-1);
const frames = [];
let shotIndex = 0;
for (let frame = 1; frame <= frameCount; frame += 1) {
const timeSec = ((frame - 1) * fps.denominator) / fps.numerator;
const normalized = clamp01(timeSec / seekTotalSec);
while (
frame >= shots[shotIndex].frameEndExclusive &&
shotIndex < shots.length - 1
shotIndex < shots.length - 1 &&
!(normalized < seekEnds[shotIndex] / seekTotalSec)
)
shotIndex += 1;
const shot = shots[shotIndex];
const timeSec = ((frame - 1) * fps.denominator) / fps.numerator;
const progress = Math.max(
0,
Math.min(
1,
(timeSec - shot.startTimeSec) / Math.max(0.001, shot.durationSec),
),
const source = scene.shots[shotIndex];
const startElapsedSec = shotIndex ? seekEnds[shotIndex - 1] : 0;
const elapsedSec = Math.max(normalized * seekTotalSec, startElapsedSec);
const flightDurationSec = source.durationSec || 4;
const shotDurationSec = Math.max(
0.001,
flightDurationSec + timing.holdFor(scene, source),
);
const pose = shot.move
? sampleCameraMove(shot.move, progress)
: cameraAtProgress(
shots[shotIndex - 1]?.camera || shot.camera,
shot.camera,
progress,
);
const shotElapsedSec = Math.max(
0,
Math.min(shotDurationSec, elapsedSec - startElapsedSec),
);
const cameraProgress = clamp01(
shotElapsedSec / Math.max(0.001, flightDurationSec),
);
const { target, previous, move } = resolved[shotIndex];
const pose = move
? sampleCameraMove(move, cameraProgress)
: cameraAtProgress(previous, target, cameraProgress);
const shot = shots[shotIndex];
if (!shot.frameStart) shot.frameStart = frame;
shot.frameEndExclusive = frame + 1;
frames.push({
frame,
timeSec,
@@ -227,6 +288,10 @@ export function exportCameraManifest(
...cameraPoseToEnu(pose, origin),
});
}
for (const shot of shots) {
if (!shot.frameStart)
throw new Error(`Shot ${shot.id} has no sampled frame at this fps`);
}
const horizontalFovRadians = C.Math.toRadians(horizontalFovDegrees);
const lensMm = number(
sensorWidthMm / (2 * Math.tan(horizontalFovRadians / 2)),
@@ -235,12 +300,12 @@ export function exportCameraManifest(
10000,
);
return {
schema: CAMERA_MANIFEST_SCHEMA,
schema: CAMERA_USD_SCHEMA,
source: {
sceneId: scene.id,
sceneTitle: scene.title || '',
documentVersion: project.version ?? 1,
sampling: 'director-seek-authored-timing',
sampling: 'director-seek-runtime-timing',
attributions: (scene.dataPacks || []).map(({ attribution }) =>
structuredClone(attribution),
),
@@ -254,8 +319,8 @@ export function exportCameraManifest(
},
camera: {
projection: 'perspective',
sensorFit: 'HORIZONTAL',
sensorWidthMm,
sensorHeightMm: (sensorWidthMm * height) / width,
lensMm,
horizontalFovRadians,
verticalFovRadians:
@@ -274,3 +339,149 @@ export function exportCameraManifest(
frames,
};
}
/** Shortest decimal for a finite double, without signed zero or 17-digit noise. */
function usdNumber(value) {
const rounded = Number(value.toPrecision(15));
return Object.is(rounded, -0) ? '0' : String(rounded);
}
/** Quote text for a .usda string literal. */
function usdString(value) {
return `"${String(value)
.replace(/\\/g, '\\\\')
.replace(/"/g, '\\"')
.replace(/\n/g, '\\n')
.replace(/\r/g, '\\r')
.replace(/\t/g, '\\t')
.replace(
/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g,
(char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`,
)}"`;
}
/** USD prim names are identifiers; saved IDs stay in custom properties. */
function shotPrimName(shot, index) {
const safe = shot.id.replace(/[^A-Za-z0-9_]/g, '_').slice(0, 40);
return `Shot_${String(index + 1).padStart(3, '0')}_${safe}`;
}
/** USD matrices are row-vector: rows are camera X, Y, Z axes, then translation. */
function usdMatrix({ position: p, basisColumns: [right, up, back] }) {
const row = (values, w) => `(${[...values, w].map(usdNumber).join(', ')})`;
return `( ${row(right, 0)}, ${row(up, 0)}, ${row(back, 0)}, ${row(p, 1)} )`;
}
/** Write sampled cameras as a plain-text USD stage that Blender imports natively.
* Z-up meters, one perspective camera per shot, time codes equal to frame numbers.
*/
export function cameraSamplesToUsda(samples) {
const { source, coordinates, camera, timeline, shots, frames } = samples;
const rate = timeline.fps.numerator / timeline.fps.denominator;
const shotTable = shots.map(
({
id,
title,
sourcePackId,
sourcePackVersion,
startTimeSec,
endTimeSec,
flightDurationSec,
authoredHoldSec,
runtimeHoldSec,
frameStart,
frameEndExclusive,
}) => ({
id,
title,
...(sourcePackId ? { sourcePackId, sourcePackVersion } : {}),
startTimeSec,
endTimeSec,
flightDurationSec,
authoredHoldSec,
runtimeHoldSec,
frameStart,
frameEndExclusive,
}),
);
const json = (value) => usdString(JSON.stringify(value));
const out = [
'#usda 1.0',
'(',
' customLayerData = {',
` string gevCamera = ${json(camera)}`,
` string gevCoordinates = ${json(coordinates)}`,
` string gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`,
` string gevShots = ${json(shotTable)}`,
` string gevSource = ${json(source)}`,
` string gevTimeline = ${json(timeline)}`,
' }',
' defaultPrim = "GEV"',
` doc = ${usdString("God's Eye View Director cameras: ENU meters around a WGS84 ellipsoid origin; time codes are frame numbers.")}`,
` endTimeCode = ${timeline.frameEnd}`,
` framesPerSecond = ${rate}`,
' metersPerUnit = 1',
` startTimeCode = ${timeline.frameStart}`,
` timeCodesPerSecond = ${rate}`,
' upAxis = "Z"',
')',
'',
'def Xform "GEV"',
'{',
` custom string userProperties:gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`,
` custom string userProperties:gevSceneId = ${usdString(source.sceneId)}`,
` custom string userProperties:gevSceneTitle = ${usdString(source.sceneTitle)}`,
` custom string userProperties:gevOrigin = ${json(coordinates.origin)}`,
` custom string userProperties:gevFps = ${usdString(`${timeline.fps.numerator}/${timeline.fps.denominator}`)}`,
` custom int userProperties:gevWidth = ${timeline.width}`,
` custom int userProperties:gevHeight = ${timeline.height}`,
` custom string userProperties:gevAttributions = ${json(source.attributions)}`,
];
shots.forEach((shot, index) => {
out.push(
'',
` def Camera ${usdString(shotPrimName(shot, index))}`,
' {',
' float2 clippingRange = (0.01, 200000)',
` float focalLength = ${usdNumber(camera.lensMm / MM_PER_USD_LENS_UNIT)}`,
` float horizontalAperture = ${usdNumber(camera.sensorWidthMm / MM_PER_USD_LENS_UNIT)}`,
` float verticalAperture = ${usdNumber(camera.sensorHeightMm / MM_PER_USD_LENS_UNIT)}`,
' token projection = "perspective"',
` custom string userProperties:gevShotId = ${usdString(shot.id)}`,
` custom string userProperties:gevShotTitle = ${usdString(shot.title)}`,
...(shot.sourcePackId
? [
` custom string userProperties:gevSourcePackId = ${usdString(shot.sourcePackId)}`,
` custom string userProperties:gevSourcePackVersion = ${usdString(shot.sourcePackVersion ?? '')}`,
]
: []),
` custom int userProperties:gevFrameStart = ${shot.frameStart}`,
` custom int userProperties:gevFrameEndExclusive = ${shot.frameEndExclusive}`,
` custom double userProperties:gevStartTimeSec = ${usdNumber(shot.startTimeSec)}`,
` custom double userProperties:gevEndTimeSec = ${usdNumber(shot.endTimeSec)}`,
` custom double userProperties:gevFlightDurationSec = ${usdNumber(shot.flightDurationSec)}`,
` custom double userProperties:gevAuthoredHoldSec = ${usdNumber(shot.authoredHoldSec)}`,
` custom double userProperties:gevRuntimeHoldSec = ${usdNumber(shot.runtimeHoldSec)}`,
' matrix4d xformOp:transform.timeSamples = {',
);
for (let f = shot.frameStart; f < shot.frameEndExclusive; f += 1) {
out.push(` ${f}: ${usdMatrix(frames[f - 1])},`);
}
out.push(
' }',
' uniform token[] xformOpOrder = ["xformOp:transform"]',
' }',
);
});
out.push('}', '');
return out.join('\n');
}
/** Export one saved scene as a .usda camera stage. */
export function exportCameraUsda(project, options) {
const samples = sampleSceneCameras(project, options);
const usda = cameraSamplesToUsda(samples);
if (Buffer.byteLength(usda) > MAX_CAMERA_USDA_BYTES)
throw new RangeError('Camera USD exceeds 64 MiB');
return { usda, samples };
}
+251 -25
View File
@@ -13,10 +13,17 @@ 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');
test('a portable camera manifest adapter exists', () => {
assert.equal(typeof adapter.exportCameraManifest, 'function');
test('a portable USD camera exporter exists', () => {
assert.equal(typeof adapter.sampleSceneCameras, 'function');
assert.equal(typeof adapter.exportCameraUsda, 'function');
});
const origin = { lat: 0, lon: 0, height: 0 };
@@ -46,7 +53,7 @@ const project = (
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.exportCameraManifest(
adapter.sampleSceneCameras(
project([{ id: 'camera', durationSec: 1, camera: pose(changes) }]),
options(opts),
).frames[0];
@@ -129,12 +136,11 @@ test('explicit horizontal lens works for landscape and portrait output', () => {
[1920, 1080],
[1080, 1920],
]) {
const m = adapter.exportCameraManifest(
project(),
options({ width, height }),
);
const m = adapter.sampleSceneCameras(project(), options({ width, height }));
assert.ok(Math.abs(m.camera.lensMm - 18) < 1e-10);
assert.equal(m.camera.sensorFit, 'HORIZONTAL');
assert.ok(
Math.abs(m.camera.sensorHeightMm - (36 * height) / width) < 1e-10,
);
assert.ok(
Math.abs(m.camera.verticalFovRadians - 2 * Math.atan(height / width)) <
1e-10,
@@ -142,7 +148,7 @@ test('explicit horizontal lens works for landscape and portrait output', () => {
}
});
test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON round trip', () => {
test('anchors, cubic moves, cuts, holds and rational frame timing are sampled', () => {
const p = project([
{
id: 'move',
@@ -173,7 +179,7 @@ test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON r
altitudeReference: 'ellipsoid',
},
];
const m = adapter.exportCameraManifest(
const m = adapter.sampleSceneCameras(
p,
options({
origin: { lat: 0, lon: 180, height: 0 },
@@ -190,7 +196,6 @@ test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON r
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.deepEqual(JSON.parse(JSON.stringify(m)), m);
assert.equal(p.scenes[0].shots[0].camera.anchorId, 'end');
});
@@ -202,20 +207,18 @@ test('invalid or ambiguous input fails before export', () => {
{ origin: { lat: 0, lon: NaN, height: 0 } },
{ horizontalFovDegrees: 180 },
]) {
assert.throws(() =>
adapter.exportCameraManifest(project(), options(change)),
);
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.exportCameraManifest(multiple, options()),
() => adapter.sampleSceneCameras(multiple, options()),
/scene/i,
);
assert.throws(
() =>
adapter.exportCameraManifest(
adapter.sampleSceneCameras(
project([{ id: 'missing', camera: { heading: 0 } }]),
options(),
),
@@ -223,7 +226,7 @@ test('invalid or ambiguous input fails before export', () => {
);
assert.throws(
() =>
adapter.exportCameraManifest(
adapter.sampleSceneCameras(
project([{ id: 'long', camera: pose(), durationSec: 86400 }]),
options(),
),
@@ -233,12 +236,12 @@ test('invalid or ambiguous input fails before export', () => {
test('projection settings cannot be silently clamped by Blender', () => {
assert.throws(
() => adapter.exportCameraManifest(project(), options({ width: 1 })),
() => adapter.sampleSceneCameras(project(), options({ width: 1 })),
/width/,
);
assert.throws(
() =>
adapter.exportCameraManifest(
adapter.sampleSceneCameras(
project(),
options({ horizontalFovDegrees: 179, sensorWidthMm: 1 }),
),
@@ -261,7 +264,7 @@ test('every exported sample agrees with Director seeking at fractional shot boun
holdSec: 0.13,
},
]);
const m = adapter.exportCameraManifest(p, options());
const m = adapter.sampleSceneCameras(p, options());
assert.equal(m.frames.length, 21);
for (const sample of m.frames) {
const state = sceneSeekState(
@@ -283,7 +286,7 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio
const directory = mkdtempSync(join(tmpdir(), 'gev camera '));
try {
const input = join(directory, 'saved scene.json');
const output = join(directory, 'camera manifest.json');
const output = join(directory, 'camera stage.usda');
writeFileSync(input, JSON.stringify(project()));
const script = fileURLToPath(
new URL('../../tools/export-blender-camera.mjs', import.meta.url),
@@ -309,11 +312,21 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio
assert.equal(first.status, 0, first.stderr);
assert.match(first.stdout, /CAMERA_EXPORT_OK/);
const contents = readFileSync(output, 'utf8');
assert.equal(JSON.parse(contents).timeline.fps.denominator, 1001);
assert.match(contents, /^#usda 1\.0\n/);
assert.match(contents, /userProperties:gevFps = "30000\/1001"/);
const repeat = spawnSync(process.execPath, args, { encoding: 'utf8' });
assert.equal(repeat.status, 1);
assert.equal(readFileSync(output, 'utf8'), contents);
const invalidOutput = join(directory, 'invalid.json');
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';
@@ -337,7 +350,7 @@ test('ordinary submillisecond shots retain the Director seek duration floor', ()
holdSec: 0.1,
},
]);
const m = adapter.exportCameraManifest(p, options());
const m = adapter.sampleSceneCameras(p, options());
const sample = m.frames[1];
const state = sceneSeekState(
p.scenes[0],
@@ -360,8 +373,221 @@ test('long decimal timelines do not gain a rounding-only frame', () => {
camera: pose(),
})),
);
const m = adapter.exportCameraManifest(p, options());
const m = adapter.sampleSceneCameras(p, options());
assert.equal(m.timeline.durationSec, 1000);
assert.equal(m.frames.length, 30000);
assert.equal(m.shots[9999].frameEndExclusive, 30001);
});
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),
),
);
for (const sample of m.frames) {
assert.equal(
sample.shotId,
runtimeSeek(p.scenes[0], sample.timeSec, m.timeline.durationSec, packs)
.shot.id,
);
}
});
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, /string 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);
});