From 235938e19b7ce6debc94581ada25192faa6dcd37 Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Thu, 19 Nov 2026 18:24:55 +0400 Subject: [PATCH] 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. --- .../1460-blender-camera-interchange.md | 2 +- docs/BLENDER-CAMERAS.md | 33 +++++++----- docs/CURRENT-STATE.md | 10 +--- src/tooling/blenderCamera.js | 47 +++++------------ src/tooling/blenderCamera.test.mjs | 51 +++++++++++++++++-- tools/export-blender-camera.mjs | 39 ++++++++++++-- 6 files changed, 116 insertions(+), 66 deletions(-) diff --git a/changelog.d/1460-blender-camera-interchange.md b/changelog.d/1460-blender-camera-interchange.md index 207c58fdea..eb8f77773c 100644 --- a/changelog.d/1460-blender-camera-interchange.md +++ b/changelog.d/1460-blender-camera-interchange.md @@ -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). diff --git a/docs/BLENDER-CAMERAS.md b/docs/BLENDER-CAMERAS.md index 668939bb62..df6deec4a2 100644 --- a/docs/BLENDER-CAMERAS.md +++ b/docs/BLENDER-CAMERAS.md @@ -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 diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 65cbd65e35..2e671984fd 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -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 diff --git a/src/tooling/blenderCamera.js b/src/tooling/blenderCamera.js index b7f14f934d..4439f5925b 100644 --- a/src/tooling/blenderCamera.js +++ b/src/tooling/blenderCamera.js @@ -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)}`, ' }', diff --git a/src/tooling/blenderCamera.test.mjs b/src/tooling/blenderCamera.test.mjs index 523719634f..77b572cc34 100644 --- a/src/tooling/blenderCamera.test.mjs +++ b/src/tooling/blenderCamera.test.mjs @@ -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 ', () => { + 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 }, diff --git a/tools/export-blender-camera.mjs b/tools/export-blender-camera.mjs index e482aa52e5..2ee12f193a 100644 --- a/tools/export-blender-camera.mjs +++ b/tools/export-blender-camera.mjs @@ -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, {