diff --git a/docs/BLENDER-CAMERAS.md b/docs/BLENDER-CAMERAS.md index df6deec4a2..8231cacb81 100644 --- a/docs/BLENDER-CAMERAS.md +++ b/docs/BLENDER-CAMERAS.md @@ -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. diff --git a/scripts/format-scope.json b/scripts/format-scope.json index d1989f305a..5b835e08c7 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -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", diff --git a/src/scenes/shotPresentation.js b/src/scenes/shotPresentation.js index 1c27b5d6ff..3c80428936 100644 --- a/src/scenes/shotPresentation.js +++ b/src/scenes/shotPresentation.js @@ -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; } diff --git a/src/tooling/blender-cut-time.test.mjs b/src/tooling/blender-cut-time.test.mjs new file mode 100644 index 0000000000..73c4277a7c --- /dev/null +++ b/src/tooling/blender-cut-time.test.mjs @@ -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`, + ); + } + }); +} diff --git a/src/tooling/blender-import-timing.test.mjs b/src/tooling/blender-import-timing.test.mjs new file mode 100644 index 0000000000..622a43cc1f --- /dev/null +++ b/src/tooling/blender-import-timing.test.mjs @@ -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); +}); diff --git a/src/tooling/blender-legacy-numbers.test.mjs b/src/tooling/blender-legacy-numbers.test.mjs new file mode 100644 index 0000000000..3d56505248 --- /dev/null +++ b/src/tooling/blender-legacy-numbers.test.mjs @@ -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); + } +}); diff --git a/src/tooling/blenderCamera.js b/src/tooling/blenderCamera.js index 4439f5925b..59218cb95f 100644 --- a/src/tooling/blenderCamera.js +++ b/src/tooling/blenderCamera.js @@ -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); diff --git a/src/tooling/blenderCamera.test.mjs b/src/tooling/blenderCamera.test.mjs index 77b572cc34..9888782ae1 100644 --- a/src/tooling/blenderCamera.test.mjs +++ b/src/tooling/blenderCamera.test.mjs @@ -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 ', () => { - 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 }); + } + }, +); diff --git a/src/tooling/blenderCameraBom.test.mjs b/src/tooling/blenderCameraBom.test.mjs new file mode 100644 index 0000000000..c716cd50bb --- /dev/null +++ b/src/tooling/blenderCameraBom.test.mjs @@ -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 }); + } +}); diff --git a/src/tooling/blenderCameraFifoInput.test.mjs b/src/tooling/blenderCameraFifoInput.test.mjs new file mode 100644 index 0000000000..183e92f61a --- /dev/null +++ b/src/tooling/blenderCameraFifoInput.test.mjs @@ -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 }); + } + }, +); diff --git a/src/tooling/blenderCameraPartialWrite.test.mjs b/src/tooling/blenderCameraPartialWrite.test.mjs new file mode 100644 index 0000000000..d29dda6b27 --- /dev/null +++ b/src/tooling/blenderCameraPartialWrite.test.mjs @@ -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 }); + } + }, +); diff --git a/src/tooling/blenderCameraStderr.test.mjs b/src/tooling/blenderCameraStderr.test.mjs new file mode 100644 index 0000000000..28b1d7d026 --- /dev/null +++ b/src/tooling/blenderCameraStderr.test.mjs @@ -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 }); + } +}); diff --git a/tools/README.md b/tools/README.md index 4c8618ac5d..f32d6aed66 100644 --- a/tools/README.md +++ b/tools/README.md @@ -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). diff --git a/tools/export-blender-camera.mjs b/tools/export-blender-camera.mjs index 2ee12f193a..567c8cda57 100644 --- a/tools/export-blender-camera.mjs +++ b/tools/export-blender-camera.mjs @@ -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; }