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

+46 -62
View File
@@ -1,28 +1,23 @@
# GEV cameras in Blender
Export one saved Director scene as a camera-only USD stage (`.usda`, plain
text), then open it with Blender's built-in importer: **File > Import >
Universal Scene Description**. The exporter is a Node script with no new
dependency. This offline path requires no API key, browser, imagery, terrain,
model provider, rendering or Blender add-on. It does not export any tiles or
geometry. Use independently licensed assets for your set.
The source remains the existing Director scene document. This adapter adds no
new tour authoring format or playback UI. It complements the scripted-camera
work discussed in [issue #1081](https://github.com/bilawalsidhu/gods-eye-view/issues/1081).
Export the cameras of one saved Director scene as a camera-only USD stage
(`.usda`, plain text) and open it with Blender's built-in importer. The export
needs no API key, network, browser or Blender add-on and contains no imagery or
geometry, so use independently licensed assets for your set.
## Export a saved scene
Use the repository's supported Node runtime and installed dependencies. Save a
Director project as JSON, then run from the repository root:
Save a Director project as JSON, then run from the repository root:
```sh
node tools/export-blender-camera.mjs --input scene.json --output cameras.usda --scene my-scene-id --origin 39.7,-105,1600 --fps 30000/1001 --width 1920 --height 1080 --horizontal-fov-deg 70
mkdir -p output
node tools/export-blender-camera.mjs --input scene.json --output output/cameras.usda --scene my-scene-id --origin 39.7,-105,1600 --fps 30000/1001 --width 1920 --height 1080 --horizontal-fov-deg 70
```
Quote paths containing spaces. Omit `--scene` only when the document contains
exactly one scene. Output must be a new file ending in `.usda`; the tool
refuses to overwrite it. No environment files are read.
Paths are relative to the current directory; `output/` is ignored by git.
Omit `--scene` only when the document contains exactly one scene. `--output`
is required and must be a new file ending in `.usda`; the tool refuses to
overwrite it. No environment files are read.
`--origin` is latitude, longitude and **WGS84 ellipsoid height in meters**.
Positions and sampled paths must remain within 100 km of that origin. Heights
@@ -32,8 +27,9 @@ need to be saved again in GEV before export.
Projection and fps are required because Director documents do not record a
viewport lens, aspect ratio or video frame rate. `--horizontal-fov-deg` is the
horizontal perspective FOV, even for portrait output. If deriving it from a
Cesium `PerspectiveFrustum`, use `2 * atan(tan(fovy / 2) * aspectRatio)`.
horizontal perspective FOV in degrees, even for portrait output. If deriving it
from a Cesium `PerspectiveFrustum`, use
`2 * atan(tan(fovy / 2) * aspectRatio) * 180 / π` (`fovy` is in radians).
Do not assume `frustum.fov` is horizontal: it is the wider-dimension FOV.
The optional `--sensor-width-mm` defaults to 36; focal length is
`sensorWidthMm / (2 * tan(horizontalFovRadians / 2))`.
@@ -48,24 +44,21 @@ sampled frame.
## Timing and camera semantics
Shot timing is the Director's **runtime** timing, not only the saved
`durationSec` and `holdSec`. Each shot's length and hold come from
`shotRuntimeDurationSec` and `effectiveShotHoldSec` in
`src/scenes/shotPresentation.js` with the installed default scene packs, the
same functions Director seeking and scrubbing use. Registered pack hold
Timing is the Director's **runtime** seek timing. The exporter loads the
document as Director does, so ordinary shots fly for at least 0.2 s, and takes
each shot's length and hold from `shotRuntimeTiming` in
`src/scenes/shotPresentation.js` with the default scene packs. Registered hold
overrides, minimum holds and evidence-sequence durations therefore move later
shots exactly as they do when seeking in the app. Live playback can run longer:
it flies each shot for at least 0.2 s and can wait for a layer's media to finish
before the next shot. Saved shots are never rewritten; each camera records both
the authored and the runtime hold.
shots as they do when seeking in the app. Live playback can run longer when it
waits for a layer's media. Saved shots are never rewritten; each camera
records both the authored and the runtime hold.
Camera poses follow GEV's Director **seek** interpolation. Named anchors and
explicit `move.from` endpoints resolve through the existing camera owner;
explicit linear/cubic moves reuse its sampler. Ordinary shots use the same
cubic, shortest-angle interpolation as Director seeking from the previous shot
camera. The first ordinary shot starts at its own camera. A cut can be authored
as an explicit move with identical start/end poses. Unit tests compare every
exported sample with the Director's `sceneSeekState`.
Each frame's camera is the Director's `sceneSeekState` pose at that time.
Named anchors and explicit `move.from` endpoints resolve through the existing
camera owner, and explicit linear/cubic moves use its sampler. Ordinary shots
interpolate cubically, by the shortest angle, from the previous shot's camera;
a shot that opens the scene starts at its own camera. A cut can be authored as
an explicit move with identical start/end poses.
The bridge does not reproduce Cesium's implicit live `flyTo` trajectory,
provider readiness, layer-owned camera motion, lens changes, visual effects,
@@ -102,16 +95,17 @@ boundary switches at the first sampled time at or after the boundary.
- Clipping range 0.01 m to 200 km; adjust it for your set if needed.
- Source scene and shot IDs, titles, pack identifiers, authored and runtime
timing, frame ranges, origin, fps ratio, image size and data-pack
attribution text, as `userProperties:` attributes and as JSON in the layer's
`customLayerData`. No referenced assets are fetched.
attribution text, as `userProperties:` attributes. No referenced assets are
fetched.
## Import into Blender
1. In Blender, choose **File > Import > Universal Scene Description**, select
the `.usda` file and keep **Set Frame Range** enabled.
2. Set **Output Properties > Format** to the exported `--width`, `--height` and
frame rate. USD carries the time codes but not render resolution, and
Blender does not take its scene frame rate from the file.
frame rate, with **Aspect X:Y** at 1:1. USD carries the time codes but not
render resolution, and Blender does not take its scene frame rate from the
file.
3. Pick a shot camera as the active camera, or bind cameras to timeline markers
at each shot's `gevFrameStart` (shown under **Object Data Properties >
Custom Properties**).
@@ -120,35 +114,25 @@ How Blender maps the lens: its USD importer multiplies `focalLength` and the
apertures by `100 * metersPerUnit` to get millimeters. With this exporter's
`metersPerUnit = 1` that is ×100, so the imported **Focal Length** and
**Sensor Width** equal the `lensMm` and `--sensor-width-mm` values. Blender
chooses horizontal sensor fit when the horizontal aperture is the larger one
and vertical fit otherwise, so portrait exports import with vertical fit and the
same field of view. This mapping is in Blender's
`source/blender/io/usd/intern/usd_reader_camera.cc` and is the same in 4.2 LTS,
4.5, 5.0 and current `main`.
chooses horizontal sensor fit when the horizontal aperture is at least as large
as the vertical one and vertical fit otherwise, so portrait exports import with
vertical fit and the same field of view. This mapping is in Blender's
`usd_reader_camera.cc`.
Blender imports animated USD transforms as a **Transform Cache** constraint
that reads the `.usda` file, so keep the file next to the `.blend`, or select
the cameras and use **Object > Animation > Bake Action…** with **Visual
Keying** and **Clear Constraints** for a self-contained file. Blender stores object transforms in single precision;
within the 100 km origin limit this is millimeter-level at the edge and finer
closer to the origin.
that keeps the absolute path of the imported `.usda`. Put the file in its
permanent place before importing, or update the path in the constraint after
moving it. For a self-contained file, select the cameras and use **Object >
Animation > Bake Action…** with **Visual Keying** and **Clear Constraints**.
Blender stores object transforms in single precision: up to about 4 mm of
rounding at 100 km, less closer to the origin.
## Checks
```sh
node --test src/tooling/blenderCamera.test.mjs
node --test src/tooling/blender*.test.mjs
```
These Node tests run in CI and compare the export with an independent Cesium
camera and the Director's `sceneSeekState`.
They do not parse the stage with USD itself; to check that, open it in
Blender as above or with OpenUSD (`pip install usd-core`):
```sh
python3 -c "import sys; from pxr import Usd; print(Usd.Stage.Open(sys.argv[1]).GetEndTimeCode())" cameras.usda
```
Run the repository's normal unit, build, format and boundary checks too. The
contribution guide additionally requires live tracking/browser checks before
submission; this camera check does not replace them.
The tests compare the export with an independent Cesium camera and the
Director's runtime timing, and parse the stage with OpenUSD's `usdcat` when it
is installed.
+7
View File
@@ -1,5 +1,12 @@
[
"src/tooling/blender-cut-time.test.mjs",
"src/tooling/blender-import-timing.test.mjs",
"src/tooling/blender-legacy-numbers.test.mjs",
"src/tooling/blenderCamera.test.mjs",
"src/tooling/blenderCameraBom.test.mjs",
"src/tooling/blenderCameraFifoInput.test.mjs",
"src/tooling/blenderCameraPartialWrite.test.mjs",
"src/tooling/blenderCameraStderr.test.mjs",
"tools/export-blender-camera.mjs",
".prettierrc.json",
"package.json",
+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 });
}
});
+13 -10
View File
@@ -4,17 +4,9 @@ CLI scripts for camera interchange and for fetching, rendering, and reprojecting
geospatial imagery. The imagery tools read the Google Maps API key from `.env`
automatically.
## Offline Blender camera interchange
Imagery tool output files go to `output/` by default (gitignored).
`export-blender-camera.mjs` exports the cameras of a saved Director scene as a
plain-text USD stage (`.usda`) that Blender opens with File > Import >
Universal Scene Description. It requires no key, environment file, browser,
network access or Blender add-on, and exports no imagery or geometry. Usage,
format and lens units: [Blender cameras](../docs/BLENDER-CAMERAS.md).
Output files go to `output/` by default (gitignored).
When invoking these tools from a separate project, set `GEV_PROJECT_ROOT` to its
When invoking the imagery tools from a separate project, set `GEV_PROJECT_ROOT` to its
absolute directory. Environment files, dependencies and relative output paths
resolve there; bundled rendering HTML stays with the tool. The same setting is
supported by `dev-fresh.sh`, `dev-secure.sh`, `opensky-import-client.sh` and the
@@ -196,3 +188,14 @@ node tools/streetview-headings.mjs --lat 30.266476 --lon -97.73719
# 5. Render a 3D view of the same location from above
node tools/cesium-render.mjs --lookat-lat 30.266476 --lookat-lon -97.73719 --pitch -90 --height 50 --fov 90 --width 2560 --height-px 1440
```
---
## export-blender-camera.mjs
Exports the cameras of a saved Director scene as a plain-text USD stage
(`.usda`) that Blender opens with File > Import > Universal Scene Description.
It needs no key, environment file, browser, network access or Blender add-on,
and exports no imagery or geometry. `--output` is required; paths are relative
to the current directory and `GEV_PROJECT_ROOT` is not read. Usage, format and
lens units: [Blender cameras](../docs/BLENDER-CAMERAS.md).
+28 -8
View File
@@ -1,6 +1,7 @@
#!/usr/bin/env node
/** Offline scene-to-USD camera CLI. Reads JSON only; never loads .env or a viewer. */
import { open, writeFile } from 'node:fs/promises';
import { constants } from 'node:fs';
import { open, unlink } from 'node:fs/promises';
import { parseArgs } from 'node:util';
import {
parseSceneDocument,
@@ -10,7 +11,12 @@ import { exportCameraUsda } from '../src/tooling/blenderCamera.js';
/** Read a regular file through one descriptor, at most one byte past the scene limit. */
async function readSceneText(path) {
const file = await open(path, 'r');
// Non-blocking, so a FIFO without a writer reaches the isFile check instead
// of hanging in open(). Windows has no O_NONBLOCK.
const file = await open(
path,
constants.O_RDONLY | (constants.O_NONBLOCK ?? 0),
);
try {
if (!(await file.stat()).isFile())
throw new Error('input must be a regular file');
@@ -22,12 +28,12 @@ async function readSceneText(path) {
length,
buffer.length - length,
);
if (!bytesRead) break;
// Decode at EOF, dropping a UTF-8 BOM as Director's File.text() does.
if (!bytesRead)
return new TextDecoder().decode(buffer.subarray(0, length));
length += bytesRead;
}
if (length > SCENE_DOCUMENT_LIMITS.bytes)
throw new Error('Scene exceeds 5 MiB');
return buffer.toString('utf8', 0, length);
throw new Error('Scene exceeds 5 MiB');
} finally {
await file.close();
}
@@ -91,12 +97,26 @@ try {
horizontalFovDegrees: Number(values['horizontal-fov-deg']),
sensorWidthMm: Number(values['sensor-width-mm']),
});
await writeFile(values.output, usda, { flag: 'wx' });
const file = await open(values.output, 'wx', 0o600);
try {
await file.writeFile(usda);
await file.close();
} catch (error) {
// Remove the partial stage this run created, so a retry can succeed.
await file.close().catch(() => {});
await unlink(values.output);
throw error;
}
console.log(
`CAMERA_EXPORT_OK: ${samples.shots.length} shots, ${samples.frames.length} frames`,
);
}
} catch (error) {
console.error(`Camera export failed: ${error.message}`);
// Field names and IDs come from the document: escape terminal control bytes.
const message = String(error.message).replace(
/[\x00-\x1f\x7f-\x9f]/g,
(char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`,
);
console.error(`Camera export failed: ${message}`);
process.exitCode = 1;
}