fix(blender-camera): match Director timing and harden the export CLI

Sample frames with Director's normalized shots and runtime timing, count
frames with a tolerance bounded by float rounding, coerce legacy numeric
text, open the input without blocking, strip a BOM, remove a partial
output on failure, and escape control characters in errors.
This commit is contained in:
German Khokhlov committed 2026-11-20 03:38:04 +04:00
1 parent 68958bf34b
commit 7db4bb35f7
14 files changed
+908 -373

No files matched your search

+8 -12
View File
@@ -153,8 +153,8 @@ export function effectiveShotHoldSec(
);
}
/** Copy a shot's layer states with registered runtime controls, without mutating saved parameters. */
export function runtimeLayerStatesForShot(shot, packs) {
/** Resolve a shot's effective hold and flight-plus-hold seconds without mutating saved layer parameters. */
export function shotRuntimeTiming(scene, shot, packs) {
const states = deepClone(shot?.layers || {});
const sourceRecipe = packs.recipeForShot(shot);
for (const state of Object.values(states)) {
@@ -168,18 +168,14 @@ export function runtimeLayerStatesForShot(shot, packs) {
};
}
}
return states;
const holdSec = effectiveShotHoldSec(scene, shot, packs, states);
return {
holdSec,
durationSec: (shot?.durationSec || DEFAULT_SHOT_DURATION_SEC) + holdSec,
};
}
/** 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,
runtimeLayerStatesForShot(shot, packs),
)
);
return shotRuntimeTiming(scene, shot, packs).durationSec;
}
+100
View File
@@ -0,0 +1,100 @@
// Reproduction: shot start/end times and timeline duration come from a different sum than frame ownership.
import test from 'node:test';
import assert from 'node:assert/strict';
import { sceneSeekState } from '../director/timeline.js';
import {
effectiveShotHoldSec,
shotRuntimeDurationSec,
} from '../scenes/shotPresentation.js';
import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
import { exportCameraUsda } from './blenderCamera.js';
const packs = createDefaultScenePacks();
const pose = (heading) => ({
lat: 0,
lon: 0,
alt: 0,
heading,
pitch: 0,
roll: 0,
altitudeReference: 'ellipsoid',
});
const shot = (id, heading, durationSec) => ({
id,
durationSec,
holdSec: 0,
camera: pose(heading),
move: { from: pose(heading), easing: 'linear' },
});
const options = {
origin: { lat: 0, lon: 0, height: 0 },
fps: { numerator: 30, denominator: 1 },
width: 1920,
height: 1080,
horizontalFovDegrees: 90,
};
const dur = (s, sh) => shotRuntimeDurationSec(s, sh, packs);
const hold = (s, sh) => effectiveShotHoldSec(s, sh, packs);
for (const [name, count, seconds] of [
['nine shot cut', 9, 0.7],
['six shot seek total', 6, 0.2],
]) {
test(name, () => {
const scene = {
id: 'scene',
title: 'S',
shots: Array.from({ length: count }, (_, i) =>
shot(`s${i + 1}`, i * 10, seconds),
),
};
const { samples, usda } = exportCameraUsda(
{ version: 6, scenes: [scene] },
options,
);
for (const [attribute, field] of [
['gevStartTimeSec', 'startTimeSec'],
['gevEndTimeSec', 'endTimeSec'],
]) {
const times = [
...usda.matchAll(new RegExp(`userProperties:${attribute} = (.+)`, 'g')),
];
assert.deepEqual(
times.map(([, value]) => Number(value)),
samples.shots.map((shot) => shot[field]),
attribute,
);
}
// Each frame's camera still follows Director seeking.
const total = scene.shots.reduce((sum, sh) => sum + dur(scene, sh), 0);
for (const frame of samples.frames)
assert.equal(
frame.shotId,
sceneSeekState(scene, frame.timeSec / total, dur, hold).shot.id,
);
// The published duration seeks to the same owner.
for (const frame of samples.frames)
assert.equal(
frame.shotId,
sceneSeekState(
scene,
frame.timeSec / samples.timeline.durationSec,
dur,
hold,
).shot.id,
`published total, frame ${frame.frame}`,
);
// Documented rule: a shot starts at the first sampled time at or after its start time.
for (const s of samples.shots) {
assert.ok(
samples.frames[s.frameStart - 1].timeSec >= s.startTimeSec,
`${s.id} starts before startTimeSec`,
);
if (s.frameStart > 1)
assert.ok(
samples.frames[s.frameStart - 2].timeSec < s.startTimeSec,
`${s.id}: frame ${s.frameStart - 1} at ${samples.frames[s.frameStart - 2].timeSec} s is at/after startTimeSec ${s.startTimeSec} but belongs to the previous shot`,
);
}
});
}
@@ -0,0 +1,64 @@
// Reproduction: the exporter samples the raw document, Director seeks the normalized one.
import test from 'node:test';
import assert from 'node:assert/strict';
import { sceneSeekState } from '../director/timeline.js';
import { parseSceneDocument } from '../director/document.js';
import { normalizeProject } from '../scenes/project.js';
import {
effectiveShotHoldSec,
shotRuntimeDurationSec,
} from '../scenes/shotPresentation.js';
import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
import { sampleSceneCameras } from './blenderCamera.js';
const packs = createDefaultScenePacks();
const pose = (heading) => ({
lat: 0,
lon: 0,
alt: 0,
heading,
pitch: 0,
roll: 0,
});
const options = {
origin: { lat: 0, lon: 0, height: 0 },
fps: { numerator: 30, denominator: 1 },
width: 1920,
height: 1080,
horizontalFovDegrees: 90,
};
test('Director import timing', () => {
const text = JSON.stringify({
version: 6,
scenes: [
{
id: 'scene',
title: 'S',
shots: [
{ id: 'A', durationSec: 0.1, holdSec: 0, camera: pose(0) },
{ id: 'B', durationSec: 1, holdSec: 0, camera: pose(90) },
],
},
],
});
const loaded = normalizeProject(parseSceneDocument(text)).scenes[0];
assert.equal(loaded.shots[0].durationSec, 0.2, 'Director loads A as 0.2 s');
let samples;
try {
samples = sampleSceneCameras(parseSceneDocument(text), options);
} catch (error) {
// Rejecting a timing-changing document is an acceptable fix.
assert.match(error.message, /duration/i);
return;
}
const dur = (s, shot) => shotRuntimeDurationSec(s, shot, packs);
const hold = (s, shot) => effectiveShotHoldSec(s, shot, packs);
const total = loaded.shots.reduce((sum, shot) => sum + dur(loaded, shot), 0);
for (const frame of samples.frames) {
const reference = sceneSeekState(loaded, frame.timeSec / total, dur, hold)
.shot.id;
assert.equal(frame.shotId, reference, `frame ${frame.frame}`);
}
assert.equal(samples.shots[1].frameStart, 7);
});
@@ -0,0 +1,52 @@
// Reproduction: version 1-2 documents with numeric strings parse but do not export.
import test from 'node:test';
import assert from 'node:assert/strict';
import { parseSceneDocument } from '../director/document.js';
import { sampleSceneCameras } from './blenderCamera.js';
const options = {
origin: { lat: 45, lon: 10, height: 0 },
fps: { numerator: 30, denominator: 1 },
width: 1920,
height: 1080,
horizontalFovDegrees: 90,
};
const doc = (shotChanges, cameraChanges) =>
JSON.stringify({
version: 2,
scenes: [
{
id: 'scene',
title: 'S',
shots: [
{
id: 'A',
durationSec: 4,
holdSec: 0,
...shotChanges,
camera: {
lat: 45,
lon: 10,
alt: 100,
heading: 0,
pitch: -30,
roll: 0,
...cameraChanges,
},
},
],
},
],
});
test('legacy numeric fields', () => {
const numeric = sampleSceneCameras(parseSceneDocument(doc({}, {})), options);
for (const [label, text] of [
['string coordinates', doc({}, { lat: '45', lon: '10', alt: '100' })],
['string duration', doc({ durationSec: '4' }, {})],
]) {
const parsed = parseSceneDocument(text); // the Director validator accepts it
const samples = sampleSceneCameras(parsed, options);
assert.deepEqual(samples.frames, numeric.frames, label);
}
});
+107 -168
View File
@@ -1,17 +1,11 @@
/** Camera-only USD interchange. No viewer, providers, environment files or terrain access. */
import * as C from 'cesium';
import { validateSceneDocument } from '../director/document.js';
import {
resolveCameraPose,
resolveCameraMove,
sampleCameraMove,
} from '../director/camera.js';
import { cameraAtProgress } from '../director/timeline.js';
import {
effectiveShotHoldSec,
runtimeLayerStatesForShot,
shotRuntimeDurationSec,
} from '../scenes/shotPresentation.js';
import { resolveCameraPose } from '../director/camera.js';
import { sceneSeekState } from '../director/timeline.js';
import { headingPitchRollFrame } from '../geo/quaternion.js';
import { normalizeProject } from '../scenes/project.js';
import { shotRuntimeTiming } from '../scenes/shotPresentation.js';
import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
export const CAMERA_USD_SCHEMA = 'gev.camera-usd.v1';
@@ -20,7 +14,6 @@ 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 (
@@ -36,6 +29,12 @@ function number(value, label, min, max) {
return value;
}
function integer(value, label, min, max) {
if (!Number.isInteger(number(value, label, min, max)))
throw new RangeError(`${label} must be an integer`);
return value;
}
function position(pose, heightKey = 'alt') {
if (!pose) throw new TypeError('A complete camera position is required');
number(pose.lat, 'lat', -90, 90);
@@ -48,7 +47,7 @@ function position(pose, heightKey = 'alt') {
* 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) {
export function cameraPoseToEnu(pose, origin, label = 'Camera') {
position(pose);
position(origin, 'height');
// Short-arc sampling can pass 360 degrees even when both saved endpoints do not.
@@ -66,8 +65,11 @@ export function cameraPoseToEnu(pose, origin) {
origin.height,
C.Ellipsoid.WGS84,
);
if (C.Cartesian3.distance(xyz, anchor) > 100000)
throw new RangeError('Camera exceeds the 100 km local-origin limit');
const distance = C.Cartesian3.distance(xyz, anchor);
if (distance > 100000)
throw new RangeError(
`${label} is ${(distance / 1000).toFixed(1)} km from the origin (limit 100 km)`,
);
// Geodetic ENU (as in PROJ): axes from the ellipsoid normal at the origin's
// lat/lon, origin raised along it. Cesium's frame at a raised point tilts.
const frame = C.Transforms.eastNorthUpToFixedFrame(
@@ -79,30 +81,15 @@ export function cameraPoseToEnu(pose, origin) {
);
const local = C.Matrix4.multiplyByPoint(inverse, xyz, new C.Cartesian3());
// Same basis as Cesium Camera.setView3D, including its heading - PI/2 offset.
const rotation = C.Matrix3.fromQuaternion(
C.Quaternion.fromHeadingPitchRoll(
new C.HeadingPitchRoll(
C.Math.toRadians(pose.heading) - Math.PI / 2,
C.Math.toRadians(pose.pitch),
C.Math.toRadians(pose.roll),
),
),
);
const cameraFrame = C.Transforms.eastNorthUpToFixedFrame(xyz);
const transform = (vector) =>
C.Matrix4.multiplyByPointAsVector(
inverse,
C.Matrix4.multiplyByPointAsVector(
cameraFrame,
vector,
new C.Cartesian3(),
),
new C.Cartesian3(),
);
const forward = transform(
C.Matrix3.getColumn(rotation, 0, new C.Cartesian3()),
);
const up = transform(C.Matrix3.getColumn(rotation, 2, new C.Cartesian3()));
const body = headingPitchRollFrame(xyz, {
heading: C.Math.toRadians(pose.heading) - Math.PI / 2,
pitch: C.Math.toRadians(pose.pitch),
roll: C.Math.toRadians(pose.roll),
});
const toLocal = (axis) =>
C.Matrix4.multiplyByPointAsVector(inverse, axis, new C.Cartesian3());
const forward = toLocal(body.x);
const up = toLocal(body.z);
const right = C.Cartesian3.cross(forward, up, new C.Cartesian3());
const array = (v) => [v.x, v.y, v.z];
return {
@@ -121,28 +108,17 @@ function identity(value, label) {
return value;
}
/** Resolve the flight-plus-hold seconds and holds that Director seeking uses.
* Both come from shotPresentation.js, so registered pack overrides, minimum holds and
* evidence-sequence durations match the app instead of the saved holdSec alone.
*/
/** Resolve each shot's runtime seconds and hold once, as Director seeking does. */
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 });
const timing = shotRuntimeTiming(scene, shot, scenePacks);
number(timing.durationSec, `Shot ${shot.id} runtime duration`, 0, 1e7);
number(timing.holdSec, `Shot ${shot.id} runtime hold`, 0, 1e7);
byShot.set(shot, timing);
}
return {
durationFor: (_scene, shot) => byShot.get(shot).durationSec,
@@ -168,64 +144,56 @@ export function sampleSceneCameras(
} = {},
) {
validateSceneDocument(project);
position(origin, 'height');
for (const key of ['numerator', 'denominator']) {
number(fps?.[key], `fps.${key}`, 1, 1000000);
if (!Number.isInteger(fps[key]))
throw new RangeError('fps must be a positive integer ratio');
}
for (const key of ['numerator', 'denominator'])
integer(fps?.[key], `fps.${key}`, 1, 1000000);
const rate = number(fps.numerator / fps.denominator, 'frame rate', 1, 240);
for (const [key, value] of Object.entries({ width, height })) {
number(value, key, 4, 16384);
if (!Number.isInteger(value))
throw new RangeError(`${key} must be an integer`);
}
integer(width, 'width', 4, 16384);
integer(height, 'height', 4, 16384);
number(horizontalFovDegrees, 'horizontal FOV degrees', 1, 179);
number(sensorWidthMm, 'sensor width mm', 1, 100);
const candidates = project.scenes.filter(
(scene) => sceneId === undefined || scene.id === sceneId,
);
if (candidates.length !== 1)
throw new Error('Select exactly one scene with sceneId');
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 (
(Math.abs(frame - Math.round(frame)) < 1e-9
? Math.round(frame)
: Math.ceil(frame)) + 1
if (candidates.length !== 1) {
const ids = project.scenes
.slice(0, 10)
.map(({ id }) => id)
.join(', ');
throw new Error(
sceneId === undefined
? `Choose one scene with --scene: ${ids}`
: `No scene has ID ${sceneId}; scenes: ${ids}`,
);
};
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, index) => {
}
const saved = candidates[0];
identity(saved.id, 'Scene');
if (!saved.shots.length) throw new Error('Scene has no camera shots');
for (const shot of saved.shots) {
identity(shot.id, 'Shot');
const { target: camera, move } = resolved[index];
position(camera);
if (move) position(move.from);
cameraPoseToEnu(camera, origin);
if (move) cameraPoseToEnu(move.from, origin);
const runtimeDurationSec = timing.durationFor(scene, shot);
const pose = resolveCameraPose(saved, shot.camera);
if (!pose || [pose.lat, pose.lon, pose.alt].includes(undefined))
throw new TypeError(
`Shot ${shot.id} requires a saved position; save the scene again in GEV`,
);
}
// Director seeks the normalized project: legacy numeric text becomes
// numbers and ordinary shots fly for at least 0.2 s.
const scene = normalizeProject({ version: project.version, scenes: [saved] })
.scenes[0];
const timing = sceneRuntimeTiming(scene, scenePacks);
let elapsed = 0;
const shots = scene.shots.map((shot) => {
const label = `Shot ${shot.id}`;
cameraPoseToEnu(resolveCameraPose(scene, shot.camera), origin, label);
if (shot.move)
cameraPoseToEnu(resolveCameraPose(scene, shot.move.from), origin, label);
// Running sums in sceneSeekState's order, so published seconds agree
// with the frame each shot owns.
const startTimeSec = elapsed;
// Compensated summation prevents long decimal timelines gaining a frame.
const increment = runtimeDurationSec - rounding;
const next = elapsed + increment;
rounding = next - elapsed - increment;
elapsed = next;
elapsed += timing.durationFor(scene, shot);
return {
id: shot.id,
title: shot.title || '',
title: shot.title,
...(shot.sourcePackId
? {
sourcePackId: shot.sourcePackId,
@@ -234,106 +202,74 @@ export function sampleSceneCameras(
: {}),
startTimeSec,
endTimeSec: elapsed,
flightDurationSec: shot.durationSec || 4,
authoredHoldSec: Number(shot.holdSec) || 0,
flightDurationSec: shot.durationSec,
authoredHoldSec: shot.holdSec,
runtimeHoldSec: timing.holdFor(scene, shot),
frameStart: 0,
frameEndExclusive: 0,
};
});
const frameCount = frameAt(elapsed) - 1;
// Ceiling of duration times fps. The tolerance bounds the rounding error of
// decimal flight and hold seconds and their sums, so only that noise at a
// frame boundary is dropped, never a real fraction of a frame.
const exactFrames = elapsed * rate;
const frameCount =
Math.abs(exactFrames - Math.round(exactFrames)) <
Number.EPSILON * (2 * shots.length + 1) * exactFrames
? Math.round(exactFrames)
: Math.ceil(exactFrames);
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 (
shotIndex < shots.length - 1 &&
!(normalized < seekEnds[shotIndex] / seekTotalSec)
)
shotIndex += 1;
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 state = sceneSeekState(
scene,
timeSec / elapsed,
timing.durationFor,
timing.holdFor,
);
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];
const shot = shots[state.shotIndex];
if (!shot.frameStart) shot.frameStart = frame;
shot.frameEndExclusive = frame + 1;
frames.push({
frame,
timeSec,
shotId: shot.id,
...cameraPoseToEnu(pose, origin),
...cameraPoseToEnu(state.camera, origin, `Shot ${shot.id}`),
});
}
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)),
sensorWidthMm / (2 * Math.tan(C.Math.toRadians(horizontalFovDegrees) / 2)),
'Blender lens mm',
1,
10000,
);
return {
schema: CAMERA_USD_SCHEMA,
source: {
sceneId: scene.id,
sceneTitle: scene.title || '',
documentVersion: project.version ?? 1,
sampling: 'director-seek-runtime-timing',
sceneTitle: saved.title || '',
attributions: (scene.dataPacks || []).map(({ attribution }) =>
structuredClone(attribution),
),
},
coordinates: {
units: 'meters',
axes: 'east-north-up',
heightDatum: 'WGS84-ellipsoid',
origin: { ...origin },
cameraAxes: 'X-right,Y-up,-Z-forward',
origin: { lat: origin.lat, lon: origin.lon, height: origin.height },
},
camera: {
projection: 'perspective',
sensorWidthMm,
sensorHeightMm: (sensorWidthMm * height) / width,
lensMm,
horizontalFovRadians,
verticalFovRadians:
2 * Math.atan((Math.tan(horizontalFovRadians / 2) * height) / width),
},
timeline: {
fps: { ...fps },
fps: { numerator: fps.numerator, denominator: fps.denominator },
width,
height,
pixelAspect: [1, 1],
frameStart: 1,
frameEnd: frameCount,
durationSec: elapsed,
@@ -349,7 +285,6 @@ function usdNumber(value) {
return Object.is(rounded, -0) ? '0' : String(rounded);
}
/** Quote text for a .usda string literal. */
function usdString(value) {
return `"${String(value)
.replace(/\\/g, '\\\\')
@@ -380,19 +315,24 @@ function usdMatrix({ position: p, basisColumns: [right, up, back] }) {
*/
export function cameraSamplesToUsda(samples) {
const { source, coordinates, camera, timeline, shots, frames } = samples;
integer(timeline.width, 'width', 4, 16384);
integer(timeline.height, 'height', 4, 16384);
integer(timeline.frameStart, 'frameStart', 1, MAX_CAMERA_FRAMES);
integer(timeline.frameEnd, 'frameEnd', 1, MAX_CAMERA_FRAMES);
for (const shot of shots) {
integer(shot.frameStart, 'frameStart', 1, MAX_CAMERA_FRAMES);
integer(
shot.frameEndExclusive,
'frameEndExclusive',
2,
MAX_CAMERA_FRAMES + 1,
);
}
const rate = timeline.fps.numerator / timeline.fps.denominator;
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(shots)}`,
` 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}`,
@@ -434,8 +374,8 @@ export function cameraSamplesToUsda(samples) {
: []),
` 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:gevStartTimeSec = ${number(shot.startTimeSec, 'startTimeSec', 0, Infinity)}`,
` custom double userProperties:gevEndTimeSec = ${number(shot.endTimeSec, 'endTimeSec', 0, Infinity)}`,
` custom double userProperties:gevFlightDurationSec = ${usdNumber(shot.flightDurationSec)}`,
` custom double userProperties:gevAuthoredHoldSec = ${usdNumber(shot.authoredHoldSec)}`,
` custom double userProperties:gevRuntimeHoldSec = ${usdNumber(shot.runtimeHoldSec)}`,
@@ -454,7 +394,6 @@ export function cameraSamplesToUsda(samples) {
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);
+114 -113
View File
@@ -145,10 +145,6 @@ test('explicit horizontal lens works for landscape and portrait output', () => {
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,
);
}
});
@@ -253,45 +249,14 @@ test('projection settings cannot be silently clamped by Blender', () => {
);
});
test('every exported sample agrees with Director seeking at fractional shot boundaries', () => {
const p = project([
{
id: 'first',
camera: pose({ heading: 350, roll: -350 }),
durationSec: 0.21,
holdSec: 0.11,
},
{
id: 'second',
camera: pose({ lon: 0.001, heading: 10, roll: 350 }),
durationSec: 0.22,
holdSec: 0.13,
},
]);
const m = adapter.sampleSceneCameras(p, options());
assert.equal(m.frames.length, 21);
for (const sample of m.frames) {
const state = sceneSeekState(
p.scenes[0],
sample.timeSec / m.timeline.durationSec,
(_scene, shot) => shot.durationSec + shot.holdSec,
(_scene, shot) => shot.holdSec,
);
const expected = adapter.cameraPoseToEnu(state.camera, origin);
assert.equal(sample.shotId, state.shot.id);
near(sample.position, expected.position);
sample.basisColumns.forEach((axis, i) =>
near(axis, expected.basisColumns[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');
writeFileSync(input, JSON.stringify(project()));
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),
);
@@ -301,8 +266,11 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio
input,
'--output',
output,
'--scene',
'other',
// A leading minus must not read as a missing --origin value.
'--origin',
'0,0,0',
'-0,0,0',
'--fps',
'30000/1001',
'--width',
@@ -318,6 +286,20 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio
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);
@@ -344,80 +326,52 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio
}
});
test('CLI accepts a negative latitude passed as --origin <value>', () => {
const directory = mkdtempSync(join(tmpdir(), 'gev origin '));
try {
const script = fileURLToPath(
new URL('../../tools/export-blender-camera.mjs', import.meta.url),
);
const result = spawnSync(
process.execPath,
[
script,
'--input',
join(directory, 'missing scene.json'),
'--output',
join(directory, 'cameras.usda'),
'--origin',
'-33.8568,151.2153,0',
'--fps',
'30',
'--width',
'1920',
'--height',
'1080',
'--horizontal-fov-deg',
'60',
],
{ encoding: 'utf8' },
);
// The input file does not exist, so the run still fails, but only after
// argument parsing: the error must be about the input, not about --origin.
assert.equal(result.status, 1);
assert.doesNotMatch(result.stderr, /ambiguous|--origin/);
assert.match(result.stderr, /ENOENT|no such file/i);
} finally {
rmSync(directory, { recursive: true, force: true });
}
});
test('ordinary submillisecond shots retain the Director seek duration floor', () => {
const p = project([
{ id: 'start', camera: pose(), durationSec: 0.033, holdSec: 0 },
{
id: 'short',
camera: pose({ heading: 90 }),
durationSec: 0.0005,
holdSec: 0.1,
},
]);
const m = adapter.sampleSceneCameras(p, options());
const sample = m.frames[1];
const state = sceneSeekState(
p.scenes[0],
sample.timeSec / m.timeline.durationSec,
(_scene, shot) => shot.durationSec + shot.holdSec,
(_scene, shot) => shot.holdSec,
);
const expected = adapter.cameraPoseToEnu(state.camera, origin);
sample.basisColumns.forEach((axis, i) =>
near(axis, expected.basisColumns[i]),
);
});
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: 10000 }, (_, i) => ({
Array.from({ length: 1000 }, (_, i) => ({
id: `shot-${i}`,
durationSec: 0.1,
durationSec: 2.13,
holdSec: 0,
camera: pose(),
})),
);
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);
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) =>
@@ -533,13 +487,6 @@ test('registered minimum holds and evidence-sequence durations shift later shots
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) =>
@@ -573,7 +520,7 @@ test('USD stage is Z-up meters with one camera per shot and per-frame matrices',
'defaultPrim = "GEV"',
])
assert.ok(usda.includes(`\n ${line}\n`), line);
assert.match(usda, /string gevSchema = "gev\.camera-usd\.v1"/);
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"/);
@@ -632,3 +579,57 @@ test('USD stage records rational fps and portrait apertures', () => {
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 });
}
},
);
+96
View File
@@ -0,0 +1,96 @@
import test from 'node:test';
import assert from 'node:assert/strict';
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, execFileSync } from 'node:child_process';
import { SCENE_DOCUMENT_LIMITS } from '../director/document.js';
const cli = fileURLToPath(
new URL('../../tools/export-blender-camera.mjs', import.meta.url),
);
const pose = (c = {}) => ({
lat: 0,
lon: 0,
alt: 10,
heading: 0,
pitch: 0,
roll: 0,
...c,
});
const doc = (shots, extra = {}) => ({
version: 6,
scenes: [{ id: 'scene', title: 'Synthetic', shots, ...extra }],
});
const one = [{ id: 'a', durationSec: 1, holdSec: 0, camera: pose() }];
const argsFor = (input, output, fps = '30') => [
cli,
'--input',
input,
'--output',
output,
'--origin',
'0,0,0',
'--fps',
fps,
'--width',
'1920',
'--height',
'1080',
'--horizontal-fov-deg',
'60',
];
const dir = () => mkdtempSync(join(tmpdir(), 'gev-camera-repro-'));
test('a UTF-8 BOM scene exports like the same scene without BOM (Director import accepts both)', () => {
const d = dir();
try {
const body = Buffer.from(JSON.stringify(doc(one)));
const plain = join(d, 'plain.json');
const bom = join(d, 'bom.json');
writeFileSync(plain, body);
writeFileSync(bom, Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), body]));
const a = spawnSync(process.execPath, argsFor(plain, join(d, 'a.usda')), {
encoding: 'utf8',
});
const b = spawnSync(process.execPath, argsFor(bom, join(d, 'b.usda')), {
encoding: 'utf8',
});
assert.equal(a.status, 0, a.stderr);
assert.equal(b.status, 0, b.stderr);
assert.deepEqual(
readFileSync(join(d, 'b.usda')),
readFileSync(join(d, 'a.usda')),
);
} finally {
rmSync(d, { recursive: true, force: true });
}
});
test('the input file size limit includes the UTF-8 BOM', () => {
const d = dir();
try {
const input = join(d, 'scene.json');
const output = join(d, 'camera.usda');
const scene = JSON.stringify(doc(one)).padEnd(
SCENE_DOCUMENT_LIMITS.bytes,
' ',
);
writeFileSync(input, '\uFEFF' + scene);
const result = spawnSync(process.execPath, argsFor(input, output), {
encoding: 'utf8',
});
assert.equal(result.status, 1);
assert.match(result.stderr, /exceeds 5 MiB/);
assert.equal(existsSync(output), false);
} finally {
rmSync(d, { recursive: true, force: true });
}
});
@@ -0,0 +1,76 @@
import test from 'node:test';
import assert from 'node:assert/strict';
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, execFileSync } from 'node:child_process';
const cli = fileURLToPath(
new URL('../../tools/export-blender-camera.mjs', import.meta.url),
);
const pose = (c = {}) => ({
lat: 0,
lon: 0,
alt: 10,
heading: 0,
pitch: 0,
roll: 0,
...c,
});
const doc = (shots, extra = {}) => ({
version: 6,
scenes: [{ id: 'scene', title: 'Synthetic', shots, ...extra }],
});
const one = [{ id: 'a', durationSec: 1, holdSec: 0, camera: pose() }];
const argsFor = (input, output, fps = '30') => [
cli,
'--input',
input,
'--output',
output,
'--origin',
'0,0,0',
'--fps',
fps,
'--width',
'1920',
'--height',
'1080',
'--horizontal-fov-deg',
'60',
];
const dir = () => mkdtempSync(join(tmpdir(), 'gev-camera-repro-'));
test(
'a FIFO --input without a writer is rejected as non-regular instead of hanging',
{ skip: process.platform === 'win32' },
() => {
const d = dir();
try {
const fifo = join(d, 'scene.json');
execFileSync('mkfifo', [fifo]);
const out = join(d, 'out.usda');
const r = spawnSync(process.execPath, argsFor(fifo, out), {
encoding: 'utf8',
timeout: 30000,
});
assert.equal(
r.signal,
null,
'CLI hung in open() and was killed by the timeout',
);
assert.equal(r.status, 1);
assert.match(r.stderr, /regular file/);
assert.equal(existsSync(out), false);
} finally {
rmSync(d, { recursive: true, force: true });
}
},
);
@@ -0,0 +1,91 @@
import test from 'node:test';
import assert from 'node:assert/strict';
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, execFileSync } from 'node:child_process';
const cli = fileURLToPath(
new URL('../../tools/export-blender-camera.mjs', import.meta.url),
);
const pose = (c = {}) => ({
lat: 0,
lon: 0,
alt: 10,
heading: 0,
pitch: 0,
roll: 0,
...c,
});
const doc = (shots, extra = {}) => ({
version: 6,
scenes: [{ id: 'scene', title: 'Synthetic', shots, ...extra }],
});
const one = [{ id: 'a', durationSec: 1, holdSec: 0, camera: pose() }];
const argsFor = (input, output, fps = '30') => [
cli,
'--input',
input,
'--output',
output,
'--origin',
'0,0,0',
'--fps',
fps,
'--width',
'1920',
'--height',
'1080',
'--horizontal-fov-deg',
'60',
];
const dir = () => mkdtempSync(join(tmpdir(), 'gev-camera-repro-'));
test(
'a failed write leaves no partial stage and a retry succeeds',
{ skip: process.platform === 'win32' },
() => {
const d = dir();
try {
const input = join(d, 'scene.json');
writeFileSync(
input,
JSON.stringify(
doc([{ id: 'a', durationSec: 60, holdSec: 0, camera: pose() }]),
),
);
const out = join(d, 'o.usda');
// RLIMIT_FSIZE (32 KiB) stands in for a full disk: write() fails with EFBIG after a prefix.
const r = spawnSync(
'/bin/sh',
[
'-c',
'ulimit -f 64; exec "$0" "$@"',
process.execPath,
...argsFor(input, out),
],
{ encoding: 'utf8' },
);
assert.equal(r.status, 1, r.stderr);
assert.equal(
existsSync(out),
false,
'truncated stage left at the final path',
);
const retry = spawnSync(process.execPath, argsFor(input, out), {
encoding: 'utf8',
});
assert.equal(retry.status, 0, retry.stderr);
assert.ok(readFileSync(out, 'utf8').trimEnd().endsWith('}'));
} finally {
rmSync(d, { recursive: true, force: true });
}
},
);
+106
View File
@@ -0,0 +1,106 @@
import test from 'node:test';
import assert from 'node:assert/strict';
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, execFileSync } from 'node:child_process';
const cli = fileURLToPath(
new URL('../../tools/export-blender-camera.mjs', import.meta.url),
);
const pose = (c = {}) => ({
lat: 0,
lon: 0,
alt: 10,
heading: 0,
pitch: 0,
roll: 0,
...c,
});
const doc = (shots, extra = {}) => ({
version: 6,
scenes: [{ id: 'scene', title: 'Synthetic', shots, ...extra }],
});
const one = [{ id: 'a', durationSec: 1, holdSec: 0, camera: pose() }];
const argsFor = (input, output, fps = '30') => [
cli,
'--input',
input,
'--output',
output,
'--origin',
'0,0,0',
'--fps',
fps,
'--width',
'1920',
'--height',
'1080',
'--horizontal-fov-deg',
'60',
];
const dir = () => mkdtempSync(join(tmpdir(), 'gev-camera-repro-'));
const oneLineNoControl = (stderr) => {
assert.equal(stderr.at(-1), 0x0a, 'ends with one newline');
const body = stderr.subarray(0, stderr.length - 1);
assert.equal(
body.includes(0x0a),
false,
'diagnostic split over several lines',
);
assert.equal(
/[\x00-\x1f\x7f-\x9f]/.test(body.toString('utf8')),
false,
'raw control byte in stderr',
);
};
test('validator diagnostics from document field names are one line without raw control bytes', () => {
const d = dir();
try {
const input = join(d, 'scene.json');
writeFileSync(input, JSON.stringify(doc(one, { 'x\ty\nz': 1 })));
const r = spawnSync(process.execPath, argsFor(input, join(d, 'o.usda')));
assert.equal(r.status, 1);
assert.match(String(r.stderr), /unsupported field/);
assert.ok(String(r.stderr).includes('x\\x09y\\x0az'));
oneLineNoControl(r.stderr);
} finally {
rmSync(d, { recursive: true, force: true });
}
});
test('exporter diagnostics with a shot ID are one line without raw control bytes', () => {
const d = dir();
try {
const input = join(d, 'scene.json');
writeFileSync(
input,
JSON.stringify(
doc([
{ id: 'a', durationSec: 0.25, holdSec: 0, camera: pose() },
{ id: 'b\tc', durationSec: 0.25, holdSec: 0, camera: pose() },
{ id: 'd', durationSec: 1.5, holdSec: 0, camera: pose() },
]),
),
);
const r = spawnSync(
process.execPath,
argsFor(input, join(d, 'o.usda'), '1'),
);
assert.equal(r.status, 1);
assert.match(String(r.stderr), /has no sampled frame/);
assert.ok(String(r.stderr).includes('b\\x09c'));
oneLineNoControl(r.stderr);
} finally {
rmSync(d, { recursive: true, force: true });
}
});