fix(blender-camera): accept southern origins and bound the scene read

- Join a space-separated negative latitude to --origin before parseArgs,
  so `--origin -33.86,151.21,0` works as the usage and docs show.
- Read the input through one descriptor, regular files only, at most one
  byte past the 5 MiB scene limit.
- Use geodetic ENU axes at the origin (ellipsoid normal at its lat/lon,
  raised to its height) instead of Cesium's frame at the raised point.
- Reuse the shots already resolved, serialize the sampled shot table
  directly, and drop the typeof-only export test.
- Docs: timing matches Director seeking, with the playback differences;
  add a manual OpenUSD/Blender check; shorten the overview and test list.
This commit is contained in:
German Khokhlov committed 2026-11-19 18:24:55 +04:00
1 parent 4668f26e0e
commit 235938e19b
6 files changed
+116 -66

No files matched your search

@@ -1,3 +1,3 @@
- Export saved Director scenes as camera-only USD (`.usda`) stages that Blender
imports natively, with ENU meter coordinates, lens in USD units, rational fps
and the same runtime shot timing as Director playback (UBN606, #1460).
and the same runtime shot timing as Director seeking (UBN606, #1460).
+20 -13
View File
@@ -42,8 +42,9 @@ The exporter supports integer fps or an integer ratio such as `30000/1001`,
with an effective rate from 1 to 240. Image dimensions are integers from 4 to
16384, pixels are square, horizontal FOV is 1 to 179 degrees and sensor width
is 1 to 100 mm. A lens shorter than Blender's 1 mm minimum is rejected.
Input is bounded to the existing 5 MiB scene-document limit; output is limited
to 100,000 frames and 64 MiB. Every shot needs at least one sampled frame.
Input must be a regular file within the existing 5 MiB scene-document limit;
output is limited to 100,000 frames and 64 MiB. Every shot needs at least one
sampled frame.
## Timing and camera semantics
@@ -51,10 +52,12 @@ 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 playback and seeking use. Registered pack hold
same functions Director seeking and scrubbing use. Registered pack hold
overrides, minimum holds and evidence-sequence durations therefore move later
shots exactly as they do in the app. Saved shots are never rewritten; each
camera records both the authored and the runtime hold.
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.
Camera poses follow GEV's Director **seek** interpolation. Named anchors and
explicit `move.from` endpoints resolve through the existing camera owner;
@@ -78,8 +81,9 @@ boundary switches at the first sampled time at or after the boundary.
## What the USD stage contains
- Stage metadata `upAxis = "Z"` and `metersPerUnit = 1`. Scene X/Y/Z are
east/north/up in meters around `--origin`, so Blender applies no axis or
unit conversion.
east/north/up in meters around `--origin`, in the geodetic ENU frame (axes
from the WGS84 ellipsoid normal at the origin's latitude and longitude), so
Blender applies no axis or unit conversion.
- USD time codes equal frame numbers: `startTimeCode = 1`, `endTimeCode` is the
last frame, and `timeCodesPerSecond`/`framesPerSecond` hold the effective
rate. The exact fps ratio is kept as text.
@@ -135,12 +139,15 @@ closer to the origin.
node --test src/tooling/blenderCamera.test.mjs
```
These Node tests run in CI. They cover camera axes against an independent
Cesium Camera, ENU translation, landscape and portrait lenses, rational fps,
cuts, anchors and moves, runtime holds from registered packs (including the
Director's Mailung trim, which plays a 7.65 s hold where 15 s was saved), every
sample against `sceneSeekState`, the USD stage metadata, lens units and
per-frame matrices, CLI overwrite and extension refusals, and input limits.
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
+2 -8
View File
@@ -689,14 +689,8 @@ untouched, and the shot is not rebuilt.
See [camera directions](DIRECTOR-CAMERA.md).
An opt-in offline [Blender camera bridge](BLENDER-CAMERAS.md) exports a saved
Director scene as a camera-only USD stage (`.usda`) that Blender imports
natively: Z-up meters in a local ENU frame around an explicit WGS84 ellipsoid
origin, one camera per shot with per-frame transforms, lens values in USD's
tenths of a scene unit and rational fps recorded alongside frame-number time
codes. It uses Director seek interpolation and the runtime shot timing from
`shotPresentation.js`, so registered pack holds, minimum holds and
evidence-sequence durations match playback. Implicit live flyTo paths, imagery
and geometry are outside this camera-only format.
Director scene as a camera-only USD stage (`.usda`) with Director seek
interpolation and runtime shot timing; format, units and limits are in that guide.
Realtime voice composes separate connection, response/tool, Radio handoff, input
and audio-meter, cost, viewport-context and diagnostic owners. The existing
+12 -35
View File
@@ -68,13 +68,17 @@ export function cameraPoseToEnu(pose, origin) {
);
if (C.Cartesian3.distance(xyz, anchor) > 100000)
throw new RangeError('Camera exceeds the 100 km local-origin limit');
// 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(
C.Cartesian3.fromDegrees(origin.lon, origin.lat, 0, C.Ellipsoid.WGS84),
);
const inverse = C.Matrix4.inverseTransformation(
C.Transforms.eastNorthUpToFixedFrame(anchor),
C.Matrix4.setTranslation(frame, anchor, frame),
new C.Matrix4(),
);
const local = C.Matrix4.multiplyByPoint(inverse, xyz, new C.Cartesian3());
// Same basis as Cesium Camera.setView3D, including its heading - PI/2 offset.
// This is the coordinate math retained from the staged ENU camera prototype.
const rotation = C.Matrix3.fromQuaternion(
C.Quaternion.fromHeadingPitchRoll(
new C.HeadingPitchRoll(
@@ -117,7 +121,7 @@ function identity(value, label) {
return value;
}
/** Resolve the flight-plus-hold seconds and holds that Director playback and seeking use.
/** 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.
*/
@@ -146,7 +150,7 @@ export function sceneRuntimeTiming(
};
}
/** Sample one saved scene with Director seek interpolation and runtime playback timing.
/** Sample one saved scene with Director seek interpolation and runtime seek timing.
* Projection is explicit because scene documents do not store viewport lenses.
* Frame 1 samples time zero; the final sample precedes the exclusive end time.
*/
@@ -205,11 +209,10 @@ export function sampleSceneCameras(
),
move: resolveCameraMove(scene, shot),
}));
const shots = scene.shots.map((shot) => {
const shots = scene.shots.map((shot, index) => {
identity(shot.id, 'Shot');
const camera = resolveCameraPose(scene, shot.camera);
const { target: camera, move } = resolved[index];
position(camera);
const move = resolveCameraMove(scene, shot);
if (move) position(move.from);
cameraPoseToEnu(camera, origin);
if (move) cameraPoseToEnu(move.from, origin);
@@ -340,7 +343,7 @@ export function sampleSceneCameras(
};
}
/** Shortest decimal for a finite double, without signed zero or 17-digit noise. */
/** Round a finite double to 15 significant digits and normalize signed zero. */
function usdNumber(value) {
const rounded = Number(value.toPrecision(15));
return Object.is(rounded, -0) ? '0' : String(rounded);
@@ -378,32 +381,6 @@ function usdMatrix({ position: p, basisColumns: [right, up, back] }) {
export function cameraSamplesToUsda(samples) {
const { source, coordinates, camera, timeline, shots, frames } = samples;
const rate = timeline.fps.numerator / timeline.fps.denominator;
const shotTable = shots.map(
({
id,
title,
sourcePackId,
sourcePackVersion,
startTimeSec,
endTimeSec,
flightDurationSec,
authoredHoldSec,
runtimeHoldSec,
frameStart,
frameEndExclusive,
}) => ({
id,
title,
...(sourcePackId ? { sourcePackId, sourcePackVersion } : {}),
startTimeSec,
endTimeSec,
flightDurationSec,
authoredHoldSec,
runtimeHoldSec,
frameStart,
frameEndExclusive,
}),
);
const json = (value) => usdString(JSON.stringify(value));
const out = [
'#usda 1.0',
@@ -412,7 +389,7 @@ export function cameraSamplesToUsda(samples) {
` string gevCamera = ${json(camera)}`,
` string gevCoordinates = ${json(coordinates)}`,
` string gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`,
` string gevShots = ${json(shotTable)}`,
` string gevShots = ${json(shots)}`,
` string gevSource = ${json(source)}`,
` string gevTimeline = ${json(timeline)}`,
' }',
+46 -5
View File
@@ -21,10 +21,6 @@ import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
import { createScenePackRegistry } from '../scenes/packs/registry.js';
const adapter = await import('./blenderCamera.js');
test('a portable USD camera exporter exists', () => {
assert.equal(typeof adapter.sampleSceneCameras, 'function');
assert.equal(typeof adapter.exportCameraUsda, 'function');
});
const origin = { lat: 0, lon: 0, height: 0 };
const pose = (changes = {}) => ({
@@ -76,6 +72,14 @@ test('cardinal cameras use Blender X right, Y up, negative Z forward', () => {
test('ENU translation uses WGS84 meters and ellipsoid heights', () => {
near(camera({ alt: 100 }).position, [0, 0, 100]);
near(
camera(
{ lat: 39.7, lon: -105, alt: 2600 },
{ origin: { lat: 39.7, lon: -105, height: 1600 } },
).position,
[0, 0, 1000],
1e-6,
);
const east = camera({ lon: 0.001 }).position;
assert.ok(Math.abs(east[0] - 111.3194907876) < 1e-6);
assert.ok(Math.abs(east[2] + 0.0009714458) < 1e-6);
@@ -107,7 +111,7 @@ test('changed tangent frames and nonzero roll match an independent Cesium Camera
});
const inverse = Cesium.Matrix4.inverseTransformation(
Cesium.Transforms.eastNorthUpToFixedFrame(
Cesium.Cartesian3.fromDegrees(anchor.lon, anchor.lat, anchor.height),
Cesium.Cartesian3.fromDegrees(anchor.lon, anchor.lat, 0),
),
new Cesium.Matrix4(),
);
@@ -340,6 +344,43 @@ 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 },
+35 -4
View File
@@ -1,6 +1,6 @@
#!/usr/bin/env node
/** Offline scene-to-USD camera CLI. Reads JSON only; never loads .env or a viewer. */
import { readFile, writeFile, stat } from 'node:fs/promises';
import { open, writeFile } from 'node:fs/promises';
import { parseArgs } from 'node:util';
import {
parseSceneDocument,
@@ -8,8 +8,41 @@ import {
} from '../src/director/document.js';
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');
try {
if (!(await file.stat()).isFile())
throw new Error('input must be a regular file');
const buffer = Buffer.alloc(SCENE_DOCUMENT_LIMITS.bytes + 1);
let length = 0;
while (length < buffer.length) {
const { bytesRead } = await file.read(
buffer,
length,
buffer.length - length,
);
if (!bytesRead) break;
length += bytesRead;
}
if (length > SCENE_DOCUMENT_LIMITS.bytes)
throw new Error('Scene exceeds 5 MiB');
return buffer.toString('utf8', 0, length);
} finally {
await file.close();
}
}
try {
// parseArgs reads a value starting with "-" as a missing argument, so join a
// southern-hemisphere `--origin -33.86,151.21,0` into `--origin=...` first.
const args = process.argv.slice(2);
for (let i = args.length - 2; i >= 0; i -= 1) {
if (args[i] === '--origin' && /^-[\d.]/.test(args[i + 1]))
args.splice(i, 2, `--origin=${args[i + 1]}`);
}
const { values } = parseArgs({
args,
options: {
input: { type: 'string' },
output: { type: 'string' },
@@ -46,9 +79,7 @@ try {
const originParts = values.origin.split(',');
if (originParts.length !== 3 || originParts.some((part) => !part.trim()))
throw new Error('origin must be lat,lon,ellipsoidHeight');
if ((await stat(values.input)).size > SCENE_DOCUMENT_LIMITS.bytes)
throw new Error('Scene exceeds 5 MiB');
const document = parseSceneDocument(await readFile(values.input, 'utf8'));
const document = parseSceneDocument(await readSceneText(values.input));
const [numerator, denominator = 1] = values.fps.split('/').map(Number);
const [lat, lon, height] = originParts.map(Number);
const { usda, samples } = exportCameraUsda(document, {