From 9f32bf3d9291dd4e856475f8985735f7828df9e9 Mon Sep 17 00:00:00 2001 From: disco Date: Mon, 26 Oct 2026 19:27:30 -0600 Subject: [PATCH 1/9] feat: export Director cameras for Blender --- .gitignore | 3 + docs/BLENDER-CAMERAS.md | 124 ++++++++++ docs/CURRENT-STATE.md | 10 + scripts/format-scope.json | 3 + src/tooling/blenderCamera.js | 276 +++++++++++++++++++++ src/tooling/blenderCamera.test.mjs | 367 ++++++++++++++++++++++++++++ tools/README.md | 12 +- tools/blender/camera_import.py | 266 ++++++++++++++++++++ tools/blender/check_import.py | 140 +++++++++++ tools/blender/make_fixture.mjs | 173 +++++++++++++ tools/blender/test_camera_import.py | 91 +++++++ tools/export-blender-camera.mjs | 72 ++++++ 12 files changed, 1536 insertions(+), 1 deletion(-) create mode 100644 docs/BLENDER-CAMERAS.md create mode 100644 src/tooling/blenderCamera.js create mode 100644 src/tooling/blenderCamera.test.mjs create mode 100644 tools/blender/camera_import.py create mode 100644 tools/blender/check_import.py create mode 100644 tools/blender/make_fixture.mjs create mode 100644 tools/blender/test_camera_import.py create mode 100644 tools/export-blender-camera.mjs diff --git a/.gitignore b/.gitignore index 11e081e7d8..fa4008e088 100644 --- a/.gitignore +++ b/.gitignore @@ -28,3 +28,6 @@ pinokio/.installed # Transient: a release interrupted mid-assembly (npm run changelog recovers it) changelog.d/.assembling/ + +# Optional Blender camera importer Python cache. +tools/blender/__pycache__/ diff --git a/docs/BLENDER-CAMERAS.md b/docs/BLENDER-CAMERAS.md new file mode 100644 index 0000000000..a3d1ca6b6f --- /dev/null +++ b/docs/BLENDER-CAMERAS.md @@ -0,0 +1,124 @@ +# GEV cameras in Blender + +Export one saved Director scene into a camera-only JSON manifest, then import +editable shot cameras into a new Blender scene. This offline path requires no +API key, browser, imagery, terrain, model provider or rendering. 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 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: + +```sh +node tools/export-blender-camera.mjs --input scene.json --output cameras.json --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; 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 +are never implicitly converted from mean sea level or above ground level. +Positions must be complete; legacy documents without saved IDs or positions +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)`. +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))`. + +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 the CLI also enforces 64 MiB. Every shot needs at least +one sampled frame. + +## Timing and camera semantics + +Sampling uses GEV's Director **seek** interpolation and authored timing. 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. + +The bridge does not reproduce Cesium's implicit live `flyTo` trajectory, +provider readiness, registered data-pack timing overrides, runtime layer holds, +layer-owned camera motion, lens changes, visual effects, media or geometry. +Export authored camera moves when repeatable playback framing is required. +This feature does not depend on GEV video export. + +Frame 1 samples time zero. Frame `n` samples `(n - 1) * denominator / numerator` +seconds. The final sample precedes the exclusive scene end; frame count is the +ceiling of duration times fps, with rounding noise at integer boundaries removed. +Shot ranges are half open: `frameStart <= frame < frameEndExclusive`. Fractional +shot boundaries switch at the first sampled time at or after the boundary. +Both authored seconds and sampled frame ranges are retained. + +## Import into Blender + +The importer is a standalone Python file using the standard library and +Blender's bundled Python API. Tested with Blender 5.2.2 LTS; other versions +need their own check before use. + +```sh +blender --background --factory-startup --disable-autoexec --threads 1 --python-exit-code 1 --python tools/blender/camera_import.py -- cameras.json cameras.blend +``` + +Both paths after `--` are required. Choose a new filename ending in lowercase +`.blend`; a missing or different extension is rejected before creating a scene. The importer +validates the entire manifest before changing Blender data and creates a new +scene, preserving existing scenes. It adds an identity ENU origin object, +one perspective camera per shot, sampled location/quaternion keyframes and +camera-bound timeline markers. Camera local X points right, local Y points up, +and local negative Z looks forward. Scene X/Y/Z are east/north/up, in meters. +Sensor fit is explicitly horizontal. Quaternion signs are kept continuous and +keyframe interpolation is linear between sampled frames. + +Scene custom properties `gev_source`, `gev_coordinates` and `gev_timeline` +preserve geographic, attribution and rational-fps metadata. Camera custom +properties preserve source scene/shot IDs, titles, pack identifiers, endpoints +and authored timing. Source data-pack attributions are retained as text; no +referenced assets are fetched. The original fps ratio is preserved exactly in +metadata; Blender's `fps_base` is floating point, so its effective rate has a +small representation error. Cameras use a 0.01 m near plane and 200 km far +plane; adjust clipping for your separately authored set if needed. + +For an existing Blender session, load this trusted module and call +`import_file(path)`; it also creates and selects a new scene. When writing your +own headless checks, activate that scene before evaluating its animation. + +## Reproducible, provider-free check + +Use a fresh output directory for each run. These commands create synthetic +camera data, run standard Python validation, import the actual cameras, compare +landmark projection to a separate Cesium Camera oracle, then save/reopen a +`.blend` and repeat. They do not render or launch a browser. + +```sh +node --test src/tooling/blenderCamera.test.mjs +python tools/blender/test_camera_import.py +node tools/blender/make_fixture.mjs --output output/blender-camera-check +blender --background --factory-startup --disable-autoexec --threads 1 --python-exit-code 1 --python tools/blender/check_import.py -- output/blender-camera-check +``` + +The check covers moving and held cameras, nonzero roll, scene-local tangent +frames, a cut, landscape/portrait projection, rational fps, source metadata, +timeline marker selection, rejected malformed input and preservation of existing +scenes. `blender-receipt.json` records measured projection error and Blender +version. A successful run prints `BLENDER_CAMERA_PROJECTION_OK`. + +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. diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 09ae87f1a9..b8d3b7df17 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -585,6 +585,16 @@ seek and keeps the last settled position. Undeclared operator layers remain 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 ENU meter camera samples with an explicit WGS84 ellipsoid +origin, horizontal lens and rational fps. It reuses Director seek interpolation +and authored timing; runtime layer timing, implicit live flyTo paths, imagery +and geometry are outside this camera-only format. The Python importer creates +a separate editable scene with per-shot cameras and timeline markers. +The synthetic `tools/blender/check_import.py` check compares actual Blender +projection and saved-file reload against a separate Cesium Camera oracle +without rendering or provider access. + Realtime voice composes separate connection, response/tool, Radio handoff, input and audio-meter, cost, viewport-context and diagnostic owners. The existing controller exports and session/backend contracts remain available. Tool protocol, diff --git a/scripts/format-scope.json b/scripts/format-scope.json index 5947f8811c..3d16f307d8 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -1,4 +1,7 @@ [ + "src/tooling/blenderCamera.test.mjs", + "tools/export-blender-camera.mjs", + "tools/blender/make_fixture.mjs", ".prettierrc.json", "package.json", "scripts/format-scope.json", diff --git a/src/tooling/blenderCamera.js b/src/tooling/blenderCamera.js new file mode 100644 index 0000000000..e90c4861cf --- /dev/null +++ b/src/tooling/blenderCamera.js @@ -0,0 +1,276 @@ +/** Camera-only 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'; + +export const CAMERA_MANIFEST_SCHEMA = 'gev.camera-manifest.v1'; +export const MAX_CAMERA_FRAMES = 100000; + +function number(value, label, min, max) { + if ( + typeof value !== 'number' || + !Number.isFinite(value) || + value < min || + value > max + ) { + throw new RangeError( + `${label} must be a finite number in [${min}, ${max}]`, + ); + } + return value; +} + +function position(pose, heightKey = 'alt') { + if (!pose) throw new TypeError('A complete camera position is required'); + number(pose.lat, 'lat', -90, 90); + number(pose.lon, 'lon', -180, 180); + number(pose[heightKey], heightKey, -12000, 1e9); +} + +/** Convert Cesium's WGS84/heading-pitch-roll pose to a fixed Blender ENU frame. + * Angles are degrees; alt and origin.height are WGS84 ellipsoid meters. + * The returned columns are Blender's local X (right), Y (up), Z (back). + */ +export function cameraPoseToEnu(pose, origin) { + position(pose); + position(origin, 'height'); + // Short-arc sampling can pass 360 degrees even when both saved endpoints do not. + for (const key of ['heading', 'roll']) number(pose[key], key, -720, 720); + number(pose.pitch, 'pitch', -90, 90); + const xyz = C.Cartesian3.fromDegrees( + pose.lon, + pose.lat, + pose.alt, + C.Ellipsoid.WGS84, + ); + const anchor = C.Cartesian3.fromDegrees( + origin.lon, + origin.lat, + origin.height, + C.Ellipsoid.WGS84, + ); + if (C.Cartesian3.distance(xyz, anchor) > 100000) + throw new RangeError('Camera exceeds the 100 km local-origin limit'); + const inverse = C.Matrix4.inverseTransformation( + C.Transforms.eastNorthUpToFixedFrame(anchor), + 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( + 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 right = C.Cartesian3.cross(forward, up, new C.Cartesian3()); + const array = (v) => [v.x, v.y, v.z]; + return { + position: array(local), + basisColumns: [ + array(right), + array(up), + array(C.Cartesian3.negate(forward, new C.Cartesian3())), + ], + }; +} + +function identity(value, label) { + if (typeof value !== 'string' || !value.trim()) + throw new TypeError(`${label} requires a saved ID`); + return value; +} + +/** Export one existing scene using Director seek interpolation and authored 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. + */ +export function exportCameraManifest( + project, + { + sceneId, + origin, + fps, + width, + height, + horizontalFovDegrees, + sensorWidthMm = 36, + } = {}, +) { + 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'); + } + 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`); + } + 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 frameAt = (seconds) => { + const frame = seconds * rate; + return ( + (Math.abs(frame - Math.round(frame)) < 1e-9 + ? Math.round(frame) + : Math.ceil(frame)) + 1 + ); + }; + let elapsed = 0; + let rounding = 0; + const shots = scene.shots.map((shot) => { + identity(shot.id, 'Shot'); + const camera = resolveCameraPose(scene, shot.camera); + position(camera); + const move = resolveCameraMove(scene, shot); + if (move) position(move.from); + cameraPoseToEnu(camera, origin); + if (move) cameraPoseToEnu(move.from, origin); + const durationSec = shot.durationSec || 4; + const holdSec = shot.holdSec || 0; + const startTimeSec = elapsed; + // Compensated summation prevents long decimal timelines gaining a frame. + const increment = durationSec + holdSec - rounding; + const next = elapsed + increment; + rounding = next - elapsed - increment; + elapsed = next; + const frameStart = frameAt(startTimeSec); + const frameEndExclusive = frameAt(elapsed); + if (frameStart >= frameEndExclusive) + throw new Error(`Shot ${shot.id} has no sampled frame at this fps`); + return { + id: shot.id, + title: shot.title || '', + ...(shot.sourcePackId + ? { + sourcePackId: shot.sourcePackId, + sourcePackVersion: shot.sourcePackVersion ?? null, + } + : {}), + startTimeSec, + endTimeSec: elapsed, + durationSec, + holdSec, + frameStart, + frameEndExclusive, + camera, + move, + }; + }); + const frameCount = frameAt(elapsed) - 1; + if (frameCount > MAX_CAMERA_FRAMES) + throw new RangeError(`Export exceeds ${MAX_CAMERA_FRAMES} camera frames`); + const frames = []; + let shotIndex = 0; + for (let frame = 1; frame <= frameCount; frame += 1) { + while ( + frame >= shots[shotIndex].frameEndExclusive && + shotIndex < shots.length - 1 + ) + shotIndex += 1; + const shot = shots[shotIndex]; + const timeSec = ((frame - 1) * fps.denominator) / fps.numerator; + const progress = Math.max( + 0, + Math.min( + 1, + (timeSec - shot.startTimeSec) / Math.max(0.001, shot.durationSec), + ), + ); + const pose = shot.move + ? sampleCameraMove(shot.move, progress) + : cameraAtProgress( + shots[shotIndex - 1]?.camera || shot.camera, + shot.camera, + progress, + ); + frames.push({ + frame, + timeSec, + shotId: shot.id, + ...cameraPoseToEnu(pose, origin), + }); + } + const horizontalFovRadians = C.Math.toRadians(horizontalFovDegrees); + const lensMm = number( + sensorWidthMm / (2 * Math.tan(horizontalFovRadians / 2)), + 'Blender lens mm', + 1, + 10000, + ); + return { + schema: CAMERA_MANIFEST_SCHEMA, + source: { + sceneId: scene.id, + sceneTitle: scene.title || '', + documentVersion: project.version ?? 1, + sampling: 'director-seek-authored-timing', + 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', + }, + camera: { + projection: 'perspective', + sensorFit: 'HORIZONTAL', + sensorWidthMm, + lensMm, + horizontalFovRadians, + verticalFovRadians: + 2 * Math.atan((Math.tan(horizontalFovRadians / 2) * height) / width), + }, + timeline: { + fps: { ...fps }, + width, + height, + pixelAspect: [1, 1], + frameStart: 1, + frameEnd: frameCount, + durationSec: elapsed, + }, + shots, + frames, + }; +} diff --git a/src/tooling/blenderCamera.test.mjs b/src/tooling/blenderCamera.test.mjs new file mode 100644 index 0000000000..4507e2f5df --- /dev/null +++ b/src/tooling/blenderCamera.test.mjs @@ -0,0 +1,367 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import * as Cesium from 'cesium'; +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 } from 'node:child_process'; +import { sceneSeekState } from '../director/timeline.js'; + +const adapter = await import('./blenderCamera.js'); +test('a portable camera manifest adapter exists', () => { + assert.equal(typeof adapter.exportCameraManifest, 'function'); +}); + +const origin = { lat: 0, lon: 0, height: 0 }; +const pose = (changes = {}) => ({ + lat: 0, + lon: 0, + alt: 0, + heading: 0, + pitch: 0, + roll: 0, + ...changes, +}); +const options = (changes = {}) => ({ + origin, + fps: { numerator: 30, denominator: 1 }, + width: 1920, + height: 1080, + horizontalFovDegrees: 90, + ...changes, +}); +const project = ( + shots = [{ id: 'north', durationSec: 1, holdSec: 0, camera: pose() }], +) => ({ + version: 6, + scenes: [{ id: 'scene', title: 'Synthetic cameras', shots }], +}); +const near = (a, b, eps = 1e-8) => + a.forEach((v, i) => assert.ok(Math.abs(v - b[i]) < eps, `${a} != ${b}`)); +const camera = (changes = {}, opts = {}) => + adapter.exportCameraManifest( + project([{ id: 'camera', durationSec: 1, camera: pose(changes) }]), + options(opts), + ).frames[0]; + +test('cardinal cameras use Blender X right, Y up, negative Z forward', () => { + for (const [heading, right, back] of [ + [0, [1, 0, 0], [0, -1, 0]], + [90, [0, -1, 0], [-1, 0, 0]], + [180, [-1, 0, 0], [0, 1, 0]], + [270, [0, 1, 0], [1, 0, 0]], + ]) { + const result = camera({ heading }); + near(result.basisColumns[0], right); + near(result.basisColumns[1], [0, 0, 1]); + near(result.basisColumns[2], back); + } + near(camera({ pitch: -90 }).basisColumns[2], [0, 0, 1]); + near(camera({ roll: 90 }).basisColumns[1], [1, 0, 0]); +}); + +test('ENU translation uses WGS84 meters and ellipsoid heights', () => { + near(camera({ alt: 100 }).position, [0, 0, 100]); + 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); +}); + +test('changed tangent frames and nonzero roll match an independent Cesium Camera', () => { + const anchor = { lat: 39.7, lon: -105, height: 1600 }; + const p = pose({ + lat: 39.73, + lon: -104.97, + alt: 2400, + heading: 47, + pitch: -29, + roll: 37, + }); + const reference = new Cesium.Camera({ + drawingBufferWidth: 1920, + drawingBufferHeight: 1080, + mapProjection: new Cesium.GeographicProjection(), + mode: Cesium.SceneMode.SCENE3D, + }); + reference.setView({ + destination: Cesium.Cartesian3.fromDegrees(p.lon, p.lat, p.alt), + orientation: { + heading: Cesium.Math.toRadians(p.heading), + pitch: Cesium.Math.toRadians(p.pitch), + roll: Cesium.Math.toRadians(p.roll), + }, + }); + const inverse = Cesium.Matrix4.inverseTransformation( + Cesium.Transforms.eastNorthUpToFixedFrame( + Cesium.Cartesian3.fromDegrees(anchor.lon, anchor.lat, anchor.height), + ), + new Cesium.Matrix4(), + ); + const arr = (v) => [v.x, v.y, v.z]; + const local = (v) => + arr( + Cesium.Matrix4.multiplyByPointAsVector( + inverse, + v, + new Cesium.Cartesian3(), + ), + ); + const actual = camera(p, { origin: anchor }); + near(actual.basisColumns[0], local(reference.rightWC)); + near(actual.basisColumns[1], local(reference.upWC)); + near( + actual.basisColumns[2], + local( + Cesium.Cartesian3.negate(reference.directionWC, new Cesium.Cartesian3()), + ), + ); +}); + +test('explicit horizontal lens works for landscape and portrait output', () => { + for (const [width, height] of [ + [1920, 1080], + [1080, 1920], + ]) { + const m = adapter.exportCameraManifest( + project(), + options({ width, height }), + ); + assert.ok(Math.abs(m.camera.lensMm - 18) < 1e-10); + assert.equal(m.camera.sensorFit, 'HORIZONTAL'); + assert.ok( + Math.abs(m.camera.verticalFovRadians - 2 * Math.atan(height / width)) < + 1e-10, + ); + } +}); + +test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON round trip', () => { + const p = project([ + { + id: 'move', + durationSec: 0.4, + holdSec: 0.2, + camera: { anchorId: 'end', heading: 10, pitch: 0, roll: 20 }, + move: { + from: { + ...pose({ lon: 179.999, heading: 350 }), + altitudeReference: 'ellipsoid', + }, + easing: 'cubic-in-out', + }, + }, + { + id: 'cut', + durationSec: 0.2, + holdSec: 0, + camera: pose({ lon: -179.999, heading: 90 }), + }, + ]); + p.scenes[0].anchors = [ + { + id: 'end', + lat: 0, + lon: -179.999, + alt: 20, + altitudeReference: 'ellipsoid', + }, + ]; + const m = adapter.exportCameraManifest( + p, + options({ + origin: { lat: 0, lon: 180, height: 0 }, + fps: { numerator: 30000, denominator: 1001 }, + }), + ); + assert.equal(m.frames.length, 24); + assert.equal(m.source.sceneId, 'scene'); + assert.deepEqual( + m.shots.map((s) => s.id), + ['move', 'cut'], + ); + assert.equal(m.shots[0].endTimeSec, 0.6000000000000001); + assert.equal(m.frames[18].shotId, 'cut'); + assert.equal(m.frames[18].timeSec, (18 * 1001) / 30000); + near(m.frames[12].position, m.frames[17].position); + assert.deepEqual(JSON.parse(JSON.stringify(m)), m); + assert.equal(p.scenes[0].shots[0].camera.anchorId, 'end'); +}); + +test('invalid or ambiguous input fails before export', () => { + for (const change of [ + { fps: { numerator: 0, denominator: 1 } }, + { horizontalFovDegrees: undefined }, + { width: 0 }, + { origin: { lat: 0, lon: NaN, height: 0 } }, + { horizontalFovDegrees: 180 }, + ]) { + assert.throws(() => + adapter.exportCameraManifest(project(), options(change)), + ); + } + assert.throws(() => camera({ lon: 20 }), /100 km/); + const multiple = project(); + multiple.scenes.push({ ...multiple.scenes[0], id: 'other' }); + assert.throws( + () => adapter.exportCameraManifest(multiple, options()), + /scene/i, + ); + assert.throws( + () => + adapter.exportCameraManifest( + project([{ id: 'missing', camera: { heading: 0 } }]), + options(), + ), + /lat|position/i, + ); + assert.throws( + () => + adapter.exportCameraManifest( + project([{ id: 'long', camera: pose(), durationSec: 86400 }]), + options(), + ), + /frame/i, + ); +}); + +test('projection settings cannot be silently clamped by Blender', () => { + assert.throws( + () => adapter.exportCameraManifest(project(), options({ width: 1 })), + /width/, + ); + assert.throws( + () => + adapter.exportCameraManifest( + project(), + options({ horizontalFovDegrees: 179, sensorWidthMm: 1 }), + ), + /lens/i, + ); +}); + +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.exportCameraManifest(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 manifest.json'); + writeFileSync(input, JSON.stringify(project())); + const script = fileURLToPath( + new URL('../../tools/export-blender-camera.mjs', import.meta.url), + ); + const args = [ + script, + '--input', + input, + '--output', + output, + '--origin', + '0,0,0', + '--fps', + '30000/1001', + '--width', + '1920', + '--height', + '1080', + '--horizontal-fov-deg', + '60', + ]; + const first = spawnSync(process.execPath, args, { encoding: 'utf8' }); + assert.equal(first.status, 0, first.stderr); + assert.match(first.stdout, /CAMERA_EXPORT_OK/); + const contents = readFileSync(output, 'utf8'); + assert.equal(JSON.parse(contents).timeline.fps.denominator, 1001); + const repeat = spawnSync(process.execPath, args, { encoding: 'utf8' }); + assert.equal(repeat.status, 1); + assert.equal(readFileSync(output, 'utf8'), contents); + const invalidOutput = join(directory, 'invalid.json'); + const invalid = [...args]; + invalid[invalid.indexOf(output)] = invalidOutput; + invalid[invalid.length - 1] = '180'; + assert.equal( + spawnSync(process.execPath, invalid, { encoding: 'utf8' }).status, + 1, + ); + assert.equal(existsSync(invalidOutput), false); + } 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.exportCameraManifest(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', () => { + const p = project( + Array.from({ length: 10000 }, (_, i) => ({ + id: `shot-${i}`, + durationSec: 0.1, + holdSec: 0, + camera: pose(), + })), + ); + const m = adapter.exportCameraManifest(p, options()); + assert.equal(m.timeline.durationSec, 1000); + assert.equal(m.frames.length, 30000); + assert.equal(m.shots[9999].frameEndExclusive, 30001); +}); diff --git a/tools/README.md b/tools/README.md index 5fd2521873..88b40ad0e7 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1,6 +1,16 @@ # Tools -CLI scripts for fetching, rendering, and reprojecting geospatial imagery. All tools read the Google Maps API key from `.env` automatically. +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 + +`export-blender-camera.mjs` exports cameras from a saved Director scene; +`blender/camera_import.py` imports an editable rig into a new Blender scene. +These tools require no key, environment file, browser or network access and +export no imagery or geometry. Usage, format and synthetic projection checks: +[Blender cameras](../docs/BLENDER-CAMERAS.md). Output files go to `output/` by default (gitignored). diff --git a/tools/blender/camera_import.py b/tools/blender/camera_import.py new file mode 100644 index 0000000000..113909ff46 --- /dev/null +++ b/tools/blender/camera_import.py @@ -0,0 +1,266 @@ +"""Import camera-only GEV JSON. Python validation needs no Blender installation. + +Blender console: import camera_import; camera_import.import_file('/path/camera.json') +CLI: blender --background --factory-startup --disable-autoexec --threads 1 + --python tools/blender/camera_import.py -- camera.json output.blend +No image, geometry, network access or rendering is performed. +""" +import json +import math +from pathlib import Path +import sys + +SCHEMA = "gev.camera-manifest.v1" +MAX_BYTES = 64 * 1024 * 1024 +MAX_FRAMES = 100000 + + +def _number(value, label, low, high, integer=False): + if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value): + raise ValueError(f"{label}: expected a finite number") + if not low <= value <= high or (integer and int(value) != value): + raise ValueError(f"{label}: outside supported range") + return int(value) if integer else value + + +def _text(value, label): + if not isinstance(value, str) or not value.strip() or len(value) > 4096: + raise ValueError(f"{label}: expected a nonempty string") + return value + + +def _near(actual, expected, label, tolerance=1e-8): + if not math.isclose(actual, expected, rel_tol=1e-10, abs_tol=tolerance): + raise ValueError(f"{label}: does not match the declared timing or projection") + + +def _vector(value, label): + if not isinstance(value, list) or len(value) != 3: + raise ValueError(f"{label}: expected three coordinates") + for component in value: + _number(component, label, -100001, 100001) + return value + + +def _dot(a, b): + return sum(x * y for x, y in zip(a, b)) + + +def _cross(a, b): + return [a[1]*b[2]-a[2]*b[1], a[2]*b[0]-a[0]*b[2], a[0]*b[1]-a[1]*b[0]] + + +def _frame_at(seconds, rate): + value = seconds * rate + return (round(value) if abs(value - round(value)) < 1e-9 else math.ceil(value)) + 1 + + +def validate_manifest(data): + """Validate the complete data before importing bpy or mutating a scene.""" + if not isinstance(data, dict) or data.get("schema") != SCHEMA: + raise ValueError("Unsupported GEV camera manifest schema") + source = data["source"] + _text(source["sceneId"], "scene ID") + if source.get("sampling") != "director-seek-authored-timing": + raise ValueError("Unsupported camera sampling semantics") + coordinates = data["coordinates"] + required = {"units": "meters", "axes": "east-north-up", "heightDatum": "WGS84-ellipsoid", "cameraAxes": "X-right,Y-up,-Z-forward"} + if any(coordinates.get(key) != value for key, value in required.items()): + raise ValueError("Explicit ENU meters, WGS84 ellipsoid and Blender camera axes required") + origin = coordinates["origin"] + for key, low, high in [("lat", -90, 90), ("lon", -180, 180), ("height", -12000, 1e9)]: + _number(origin[key], f"origin.{key}", low, high) + timeline = data["timeline"] + fps = timeline["fps"] + for key in ["numerator", "denominator"]: + _number(fps[key], f"fps.{key}", 1, 1000000, integer=True) + rate = _number(fps["numerator"] / fps["denominator"], "fps", 1, 240) + for key in ["width", "height"]: + _number(timeline[key], key, 4, 16384, integer=True) + if timeline["pixelAspect"] != [1, 1] or any(isinstance(value, bool) for value in timeline["pixelAspect"]): + raise ValueError("Only square pixels are supported") + if timeline["frameStart"] != 1 or isinstance(timeline["frameStart"], bool): + raise ValueError("Timeline must start at frame 1") + count = _number(timeline["frameEnd"], "frameEnd", 1, MAX_FRAMES, integer=True) + _number(timeline["durationSec"], "durationSec", 0, 100000) + if count != _frame_at(timeline["durationSec"], rate) - 1: + raise ValueError("Frame count differs from declared duration and fps") + camera = data["camera"] + if camera["projection"] != "perspective" or camera["sensorFit"] != "HORIZONTAL": + raise ValueError("Only a perspective horizontal-sensor camera is supported") + sensor = _number(camera["sensorWidthMm"], "sensorWidthMm", 1, 100) + hfov = _number(camera["horizontalFovRadians"], "horizontalFovRadians", math.pi/180, math.pi*179/180) + lens = _number(camera["lensMm"], "lensMm", 1, 10000) + _near(lens, sensor / (2 * math.tan(hfov / 2)), "lens") + _near(_number(camera["verticalFovRadians"], "verticalFovRadians", 0, math.pi), 2 * math.atan(math.tan(hfov / 2) * timeline["height"] / timeline["width"]), "vertical FOV") + shots = data["shots"] + if not isinstance(shots, list) or not 1 <= len(shots) <= count: + raise ValueError("Expected bounded nonempty shots") + ids = set() + elapsed = 0 + rounding = 0 + for shot in shots: + shot_id = _text(shot["id"], "shot ID") + if shot_id in ids: + raise ValueError("Duplicate shot ID") + ids.add(shot_id) + for key in ["startTimeSec", "endTimeSec", "durationSec", "holdSec"]: + _number(shot[key], key, 0, 100000) + if shot["durationSec"] <= 0: + raise ValueError("Shot duration must be positive") + _near(shot["startTimeSec"], elapsed, "shot start") + increment = shot["durationSec"] + shot["holdSec"] - rounding + next_time = elapsed + increment + rounding = next_time - elapsed - increment + elapsed = next_time + _near(shot["endTimeSec"], elapsed, "shot end") + for key, expected in [("frameStart", _frame_at(shot["startTimeSec"], rate)), ("frameEndExclusive", _frame_at(elapsed, rate))]: + _number(shot[key], key, 1, count + 1, integer=True) + if shot[key] != expected: + raise ValueError("Shot frame boundaries do not match timing") + if shot["frameStart"] >= shot["frameEndExclusive"]: + raise ValueError("Shot has no sampled frames") + _near(elapsed, timeline["durationSec"], "total duration") + frames = data["frames"] + if not isinstance(frames, list) or len(frames) != count: + raise ValueError("Frame count differs from frame samples") + shot_index = 0 + for index, sample in enumerate(frames, start=1): + if sample["frame"] != index or isinstance(sample["frame"], bool): + raise ValueError("Frames must be sequential integers starting at 1") + _near(_number(sample["timeSec"], "timeSec", 0, 100000), (index - 1) * fps["denominator"] / fps["numerator"], "sample time") + while index >= shots[shot_index]["frameEndExclusive"] and shot_index < len(shots) - 1: + shot_index += 1 + if sample["shotId"] != shots[shot_index]["id"]: + raise ValueError("Sample references the wrong shot") + location = _vector(sample["position"], "position") + if _dot(location, location) > 100000**2 + 0.01: + raise ValueError("Camera exceeds 100 km local-origin limit") + basis = sample["basisColumns"] + if not isinstance(basis, list) or len(basis) != 3: + raise ValueError("Expected three camera basis columns") + x, y, z = [_vector(column, "basis") for column in basis] + for column in [x, y, z]: + _near(_dot(column, column), 1, "unit camera axis", 1e-6) + for a, b in [(x, y), (y, z), (z, x)]: + _near(_dot(a, b), 0, "orthogonal camera axes", 1e-6) + _near(_dot(_cross(x, y), z), 1, "right-handed camera basis", 1e-6) + return data + + +def read_manifest(path): + """Read bounded JSON only. No imports, URLs or expressions are evaluated.""" + with Path(path).open("rb") as stream: + payload = stream.read(MAX_BYTES + 1) + if len(payload) > MAX_BYTES: + raise ValueError("Camera manifest exceeds 64 MiB") + return validate_manifest(json.loads(payload)) + + +def import_manifest(data): + """Create a new scene with editable per-shot cameras; preserve existing scenes.""" + validate_manifest(data) + import bpy + from mathutils import Matrix, Vector + + scene = bpy.data.scenes.new(f"GEV {data['source'].get('sceneTitle') or data['source']['sceneId']}") + scene.unit_settings.system = "METRIC" + scene.unit_settings.scale_length = 1.0 + timeline = data["timeline"] + rate = timeline["fps"]["numerator"] / timeline["fps"]["denominator"] + scene.render.fps = round(rate) + scene.render.fps_base = round(rate) / rate + scene.render.resolution_x = int(timeline["width"]) + scene.render.resolution_y = int(timeline["height"]) + scene.render.resolution_percentage = 100 + scene.render.pixel_aspect_x = scene.render.pixel_aspect_y = 1.0 + scene.frame_start = 1 + scene.frame_end = int(timeline["frameEnd"]) + scene["gev_schema"] = SCHEMA + scene["gev_source"] = json.dumps(data["source"], ensure_ascii=False) + scene["gev_coordinates"] = json.dumps(data["coordinates"], ensure_ascii=False) + scene["gev_timeline"] = json.dumps(timeline) + root = bpy.data.objects.new("GEV ENU origin", None) + scene.collection.objects.link(root) + cameras = {} + for shot in data["shots"]: + camera_data = bpy.data.cameras.new(f"GEV {shot['id']}") + camera_data.type = "PERSP" + camera_data.sensor_fit = "HORIZONTAL" + camera_data.sensor_width = data["camera"]["sensorWidthMm"] + camera_data.lens = data["camera"]["lensMm"] + camera_data.clip_start = 0.01 + camera_data.clip_end = 200000 + camera = bpy.data.objects.new(f"GEV {shot['id']}", camera_data) + camera.rotation_mode = "QUATERNION" + camera.parent = root + camera["gev_shot"] = json.dumps(shot, ensure_ascii=False) + camera["gev_scene_id"] = data["source"]["sceneId"] + scene.collection.objects.link(camera) + cameras[shot["id"]] = camera + marker = scene.timeline_markers.new(f"GEV {shot['id']}", frame=int(shot["frameStart"])) + marker.camera = camera + previous = {} + for sample in data["frames"]: + camera = cameras[sample["shotId"]] + # Manifest vectors are columns, while mathutils.Matrix accepts rows. + basis = Matrix(sample["basisColumns"]).transposed() + rotation = basis.to_quaternion().normalized() + old = previous.get(sample["shotId"]) + if old is not None and rotation.dot(old) < 0: + rotation.negate() + previous[sample["shotId"]] = rotation.copy() + camera.location = Vector(sample["position"]) + camera.rotation_quaternion = rotation + camera.keyframe_insert(data_path="location", frame=sample["frame"]) + camera.keyframe_insert(data_path="rotation_quaternion", frame=sample["frame"]) + # Blender defaults to Bezier, which would alter motion between sampled frames. + for camera in cameras.values(): + action = camera.animation_data.action + if hasattr(action, "layers") and action.layers: + for layer in action.layers: + for strip in layer.strips: + bag = strip.channelbag(camera.animation_data.action_slot) + for curve in bag.fcurves if bag else []: + for key in curve.keyframe_points: + key.interpolation = "LINEAR" + else: + for curve in action.fcurves: + for key in curve.keyframe_points: + key.interpolation = "LINEAR" + scene.camera = cameras[data["shots"][0]["id"]] + if bpy.context.window: + bpy.context.window.scene = scene + scene.frame_set(1) + return scene + + +def import_file(path): + """Import a camera JSON file into a new Blender scene without rendering.""" + return import_manifest(read_manifest(path)) + + +def new_blend_output(path): + """Require Blender's final extension before checking overwrite protection.""" + output = Path(path).resolve() + if output.suffix != '.blend': + raise ValueError('Output must end in lowercase .blend') + if output.exists(): + raise FileExistsError('Output already exists; choose a new .blend path') + return output + + +if __name__ == "__main__": + args = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else [] + if len(args) != 2: + raise SystemExit("Usage: blender --background --factory-startup --disable-autoexec --threads 1 --python camera_import.py -- camera.json output.blend") + output = new_blend_output(args[1]) + import_file(args[0]) + import bpy + preview = bpy.context.preferences.filepaths.file_preview_type + try: + bpy.context.preferences.filepaths.file_preview_type = 'NONE' + bpy.ops.wm.save_as_mainfile(filepath=str(output.resolve()), check_existing=False) + finally: + bpy.context.preferences.filepaths.file_preview_type = preview + print("CAMERA_IMPORT_OK") diff --git a/tools/blender/check_import.py b/tools/blender/check_import.py new file mode 100644 index 0000000000..5295ebf72f --- /dev/null +++ b/tools/blender/check_import.py @@ -0,0 +1,140 @@ +"""Synthetic CPU-only Blender import, projection and .blend round-trip check. + +blender --background --factory-startup --disable-autoexec --threads 1 + --python tools/blender/check_import.py -- fixture-directory +No renderer or GPU context is requested. All landmarks are synthetic empties. +""" +import importlib.util +import json +from pathlib import Path +import sys + +import bpy +from bpy_extras.object_utils import world_to_camera_view +from mathutils import Vector + +spec = importlib.util.spec_from_file_location("camera_import", Path(__file__).with_name("camera_import.py")) +importer = importlib.util.module_from_spec(spec) +spec.loader.exec_module(importer) +args = sys.argv[sys.argv.index("--") + 1:] +if len(args) != 1: + raise SystemExit("Expected one fixture directory") +directory = Path(args[0]) +reference = json.loads((directory / "projection-reference.json").read_text()) +original_names = set(bpy.data.scenes.keys()) +original_settings = {scene.name: (scene.render.resolution_x, scene.render.resolution_y, scene.frame_end) for scene in bpy.data.scenes} +bpy.context.preferences.filepaths.file_preview_type = 'NONE' + + +def block(scene, name, center, size): + """Tiny owned synthetic blockout, so the saved rig has an editable set.""" + x, y, z = center + sx, sy, sz = [value / 2 for value in size] + vertices = [(x+dx*sx, y+dy*sy, z+dz*sz) for dx, dy, dz in [(-1,-1,-1),(1,-1,-1),(1,1,-1),(-1,1,-1),(-1,-1,1),(1,-1,1),(1,1,1),(-1,1,1)]] + faces = [(0,3,2,1),(4,5,6,7),(0,1,5,4),(1,2,6,5),(2,3,7,6),(3,0,4,7)] + mesh = bpy.data.meshes.new(name) + mesh.from_pydata(vertices, [], faces) + mesh.update() + obj = bpy.data.objects.new(name, mesh) + scene.collection.objects.link(obj) + + +cases = [] +for case in reference["cases"]: + manifest = importer.read_manifest(directory / case["manifest"]) + scene = importer.import_manifest(manifest) + # All validation occurs before bpy mutation. + malformed = json.loads(json.dumps(manifest)) + malformed["frames"][-1]["basisColumns"][0] = [2, 0, 0] + names = set(bpy.data.scenes.keys()) + objects = set(bpy.data.objects.keys()) + try: + importer.import_manifest(malformed) + raise AssertionError("Malformed transform was accepted") + except ValueError: + assert set(bpy.data.scenes.keys()) == names + assert set(bpy.data.objects.keys()) == objects + for index, point in enumerate(case["checks"][0]["points"]): + landmark = bpy.data.objects.new(f"Synthetic landmark {index}", None) + landmark.location = point["position"] + scene.collection.objects.link(landmark) + block(scene, 'Synthetic ground, no map data', [0, 0, -1], [1400, 1400, 2]) + for index in [0, 6, 9]: + sample = manifest['frames'][index] + point = case['checks'][index]['points'][0]['position'] + direction = [(point[i]-sample['position'][i])/100 for i in range(3)] + distance = -sample['position'][2]/direction[2] + center = [sample['position'][i]+direction[i]*distance for i in range(2)] + [10] + block(scene, f'Synthetic block {index}', center, [24, 24, 20]) + cases.append((case, manifest, scene.name)) + +# JSON may spell an integer-valued number as 1920.0. Blender RNA requires ints. +float_case = dict(reference['cases'][0], name='integer-valued JSON floats') +float_manifest = importer.read_manifest(directory / float_case['manifest']) +for key in ['width', 'height', 'frameEnd']: + float_manifest['timeline'][key] = float(float_manifest['timeline'][key]) +for shot in float_manifest['shots']: + shot['frameStart'] = float(shot['frameStart']) +float_scene = importer.import_manifest(float_manifest) +cases.append((float_case, float_manifest, float_scene.name)) + + +def check_all(): + max_error = 0.0 + projection_count = 0 + for case, manifest, scene_name in cases: + scene = bpy.data.scenes[scene_name] + bpy.context.window.scene = scene + bpy.context.view_layer.update() + metadata = json.loads(scene["gev_source"]) + assert metadata["sceneId"] == manifest["source"]["sceneId"] + assert json.loads(scene["gev_coordinates"]) == manifest["coordinates"] + assert json.loads(scene["gev_timeline"]) == manifest["timeline"] + assert scene.frame_start == 1 and scene.frame_end == len(manifest["frames"]) + expected_rate = manifest["timeline"]["fps"]["numerator"] / manifest["timeline"]["fps"]["denominator"] + assert abs(scene.render.fps / scene.render.fps_base - expected_rate) < 2e-6 + assert scene.unit_settings.scale_length == 1 + assert scene.render.resolution_x == manifest["timeline"]["width"] + assert scene.render.resolution_y == manifest["timeline"]["height"] + cameras = {json.loads(obj["gev_shot"])["id"]: obj for obj in scene.objects if "gev_shot" in obj} + assert set(cameras) == {shot["id"] for shot in manifest["shots"]} + for shot in manifest["shots"]: + assert json.loads(cameras[shot["id"]]["gev_shot"]) == shot + for item in case["checks"]: + scene.frame_set(item["frame"]) + active = scene.camera + camera = cameras[item["shotId"]] + assert active == camera, "Timeline marker selected the wrong camera" + assert camera.data.sensor_fit == "HORIZONTAL" + assert abs(camera.data.lens - manifest["camera"]["lensMm"]) < 1e-5 + for point in item["points"]: + projected = world_to_camera_view(scene, camera, Vector(point["position"])) + assert projected.z > 0, (case['name'], item['frame'], 'landmark behind camera') + error = max(abs(projected.x - point["uv"][0]), abs(projected.y - point["uv"][1])) + max_error = max(error, max_error) + assert error < 2e-5, (case["name"], item["frame"], error) + projection_count += 1 + for name in original_names: + scene = bpy.data.scenes[name] + assert (scene.render.resolution_x, scene.render.resolution_y, scene.frame_end) == original_settings[name] + return max_error, projection_count + + +before_error, count = check_all() +blend = directory / "synthetic-cameras.blend" +if blend.exists(): + raise SystemExit("Synthetic output already exists; choose a fresh fixture directory") +bpy.context.window.scene = bpy.data.scenes[cases[0][2]] +bpy.context.scene.frame_set(1) +for area in bpy.context.screen.areas: + if area.type == 'VIEW_3D': + area.spaces.active.region_3d.view_perspective = 'CAMERA' +bpy.ops.wm.save_as_mainfile(filepath=str(blend.resolve()), check_existing=False) +assert blend.stat().st_size > 10000 +bpy.ops.wm.open_mainfile(filepath=str(blend.resolve()), load_ui=False, use_scripts=False) +assert bpy.context.scene.name == cases[0][2], 'Demo must reopen on the blockout scene' +after_error, after_count = check_all() +assert after_count == count +receipt = {"state": "BLENDER_CAMERA_PROJECTION_OK", "blenderVersion": bpy.app.version_string, "cases": len(cases), "projectionsBeforeSave": count, "projectionsAfterReload": after_count, "maxUvError": max(before_error, after_error), "rendered": False, "gpuRequested": False, "blend": blend.name} +(directory / "blender-receipt.json").write_text(json.dumps(receipt, indent=2) + "\n") +print(json.dumps(receipt)) diff --git a/tools/blender/make_fixture.mjs b/tools/blender/make_fixture.mjs new file mode 100644 index 0000000000..0eab273670 --- /dev/null +++ b/tools/blender/make_fixture.mjs @@ -0,0 +1,173 @@ +#!/usr/bin/env node +/** Generate tiny, provider-free fixtures plus an independent Cesium projection oracle. */ +import { mkdir, writeFile } from 'node:fs/promises'; +import { resolve } from 'node:path'; +import { parseArgs } from 'node:util'; +import * as C from 'cesium'; +import { exportCameraManifest } from '../../src/tooling/blenderCamera.js'; +import { sceneSeekState } from '../../src/director/timeline.js'; + +const { values } = parseArgs({ options: { output: { type: 'string' } } }); +if (!values.output) + throw new Error( + 'Usage: node tools/blender/make_fixture.mjs --output directory', + ); +const output = resolve(values.output); +await mkdir(output, { recursive: true }); +const pose = (values) => ({ + lat: 39.7003, + lon: -105.0004, + alt: 1750, + heading: 20, + pitch: -25, + roll: 17, + altitudeReference: 'ellipsoid', + ...values, +}); +const finish = pose({ + lat: 39.7005, + lon: -104.9995, + alt: 1800, + heading: 95, + pitch: -40, + roll: -25, +}); +const cut = pose({ + lat: 39.6998, + lon: -105.0003, + alt: 1725, + heading: 230, + pitch: -15, + roll: 35, +}); +const document = { + version: 6, + scenes: [ + { + id: 'synthetic-scene', + title: 'Synthetic camera bridge', + shots: [ + { + id: 'rolled-move', + title: 'Move and hold', + durationSec: 0.2, + holdSec: 0.1, + camera: finish, + move: { from: pose({}), easing: 'cubic-in-out' }, + }, + { + id: 'cut', + title: 'Explicit cut and hold', + durationSec: 0.2, + holdSec: 0.1, + camera: cut, + move: { from: cut, easing: 'linear' }, + }, + ], + }, + ], +}; +const origin = { lat: 39.7, lon: -105, height: 1600 }; +const anchor = C.Cartesian3.fromDegrees(origin.lon, origin.lat, origin.height); +const worldToLocal = C.Matrix4.inverseTransformation( + C.Transforms.eastNorthUpToFixedFrame(anchor), + new C.Matrix4(), +); +const cases = []; +for (const [name, width, height] of [ + ['landscape', 1920, 1080], + ['portrait', 1080, 1920], +]) { + const manifest = exportCameraManifest(document, { + origin, + fps: { numerator: 30000, denominator: 1001 }, + width, + height, + horizontalFovDegrees: 70, + }); + await writeFile( + resolve(output, `${name}.camera.json`), + JSON.stringify(manifest, null, 2) + '\n', + ); + const camera = new C.Camera({ + drawingBufferWidth: width, + drawingBufferHeight: height, + mapProjection: new C.GeographicProjection(), + mode: C.SceneMode.SCENE3D, + }); + camera.frustum.aspectRatio = width / height; + camera.frustum.fov = + width >= height + ? manifest.camera.horizontalFovRadians + : manifest.camera.verticalFovRadians; + camera.frustum.near = 0.01; + camera.frustum.far = 200000; + const checks = []; + for (const sample of manifest.frames) { + const state = sceneSeekState( + document.scenes[0], + sample.timeSec / manifest.timeline.durationSec, + (_scene, shot) => shot.durationSec + shot.holdSec, + (_scene, shot) => shot.holdSec, + ); + const p = state.camera; + camera.setView({ + destination: C.Cartesian3.fromDegrees(p.lon, p.lat, p.alt), + orientation: { + heading: C.Math.toRadians(p.heading), + pitch: C.Math.toRadians(p.pitch), + roll: C.Math.toRadians(p.roll), + }, + }); + const projectionView = C.Matrix4.multiply( + camera.frustum.projectionMatrix, + camera.viewMatrix, + new C.Matrix4(), + ); + const points = []; + for (const [right, up] of [ + [0, 0], + [25, 0], + [-25, 15], + [0, -20], + ]) { + const world = C.Cartesian3.clone(camera.positionWC); + for (const [axis, distance] of [ + [camera.directionWC, 100], + [camera.rightWC, right], + [camera.upWC, up], + ]) { + C.Cartesian3.add( + world, + C.Cartesian3.multiplyByScalar(axis, distance, new C.Cartesian3()), + world, + ); + } + const clip = C.Matrix4.multiplyByVector( + projectionView, + new C.Cartesian4(world.x, world.y, world.z, 1), + new C.Cartesian4(), + ); + const local = C.Matrix4.multiplyByPoint( + worldToLocal, + world, + new C.Cartesian3(), + ); + points.push({ + position: [local.x, local.y, local.z], + uv: [(clip.x / clip.w + 1) / 2, (clip.y / clip.w + 1) / 2], + }); + } + checks.push({ frame: sample.frame, shotId: sample.shotId, points }); + } + cases.push({ name, manifest: `${name}.camera.json`, checks }); +} +await writeFile( + resolve(output, 'scene.json'), + JSON.stringify(document, null, 2) + '\n', +); +await writeFile( + resolve(output, 'projection-reference.json'), + JSON.stringify({ origin, cases }, null, 2) + '\n', +); +console.log('CAMERA_FIXTURE_OK'); diff --git a/tools/blender/test_camera_import.py b/tools/blender/test_camera_import.py new file mode 100644 index 0000000000..2f2b262dea --- /dev/null +++ b/tools/blender/test_camera_import.py @@ -0,0 +1,91 @@ +"""Data validation checks. Standard Python only; no Blender or rendering required.""" +import copy +import importlib.util +import math +from pathlib import Path +import sys +import tempfile +import unittest + +module_path = Path(__file__).with_name("camera_import.py") +if module_path.exists(): + spec = importlib.util.spec_from_file_location("camera_import", module_path) + importer = importlib.util.module_from_spec(spec) + spec.loader.exec_module(importer) +else: + importer = None + + +def fixture(): + return { + "schema": "gev.camera-manifest.v1", + "source": {"sceneId": "scene", "sceneTitle": "Fixture", "sampling": "director-seek-authored-timing", "attributions": []}, + "coordinates": {"units": "meters", "axes": "east-north-up", "heightDatum": "WGS84-ellipsoid", "origin": {"lat": 0, "lon": 0, "height": 0}, "cameraAxes": "X-right,Y-up,-Z-forward"}, + "camera": {"projection": "perspective", "sensorFit": "HORIZONTAL", "sensorWidthMm": 36, "lensMm": 18, "horizontalFovRadians": math.pi / 2, "verticalFovRadians": math.pi / 2}, + "timeline": {"fps": {"numerator": 30, "denominator": 1}, "width": 100, "height": 100, "pixelAspect": [1, 1], "frameStart": 1, "frameEnd": 1, "durationSec": 1 / 30}, + "shots": [{"id": "north", "title": "North", "startTimeSec": 0, "endTimeSec": 1 / 30, "durationSec": 1 / 30, "holdSec": 0, "frameStart": 1, "frameEndExclusive": 2}], + "frames": [{"frame": 1, "timeSec": 0, "shotId": "north", "position": [0, 0, 0], "basisColumns": [[1, 0, 0], [0, 0, 1], [0, -1, 0]]}], + } + + +class ValidationTests(unittest.TestCase): + def test_validator_exists(self): + self.assertIsNotNone(importer, "camera importer is missing") + + def test_valid_manifest_is_not_mutated_and_does_not_import_bpy(self): + data = fixture() + before = copy.deepcopy(data) + importer.validate_manifest(data) + self.assertEqual(data, before) + self.assertNotIn("bpy", sys.modules) + + def test_rejects_datum_axes_lens_fps_and_timing_mismatches(self): + mutations = [ + lambda m: m.update(schema="other"), + lambda m: m["coordinates"].update(heightDatum="MSL"), + lambda m: m["coordinates"].update(axes="north-east-down"), + lambda m: m["camera"].update(lensMm=35), + lambda m: m["camera"].update(lensMm=0.5), + lambda m: m["camera"].update(verticalFovRadians=1), + lambda m: m["timeline"]["fps"].update(denominator=0), + lambda m: m["timeline"].update(frameEnd=2), + lambda m: m["timeline"].update(width=1), + lambda m: m["timeline"].update(pixelAspect=[2, 1]), + lambda m: m["frames"][0].update(frame=2), + lambda m: m["frames"][0].update(timeSec=1), + lambda m: m["frames"][0].update(shotId="missing"), + lambda m: m["shots"][0].update(frameStart=2), + lambda m: m["shots"][0].update(endTimeSec=2), + lambda m: m["frames"][0].update(position=[100001, 0, 0]), + lambda m: m["frames"][0].update(position=[False, 0, 0]), + lambda m: m["frames"][0].update(position=[math.nan, 0, 0]), + lambda m: m["frames"][0].update(basisColumns=[[1, 0, 0], [1, 0, 0], [0, 0, 1]]), + lambda m: m["frames"][0].update(basisColumns=[[-1, 0, 0], [0, 0, 1], [0, -1, 0]]), + ] + for mutate in mutations: + data = fixture() + mutate(data) + with self.subTest(mutation=mutations.index(mutate)): + with self.assertRaises((ValueError, TypeError, KeyError)): + importer.validate_manifest(data) + + def test_output_extension_is_checked_before_existing_file_guard(self): + with tempfile.TemporaryDirectory(prefix='gev-blender-output-') as directory: + output = Path(directory) / 'camera.blend' + output.write_bytes(b'existing file must survive') + with self.assertRaises(ValueError): + importer.new_blend_output(Path(directory) / 'camera') + with self.assertRaises(FileExistsError): + importer.new_blend_output(output) + with self.assertRaises(ValueError): + importer.new_blend_output(Path(directory) / 'new.BLEND') + self.assertEqual(output.read_bytes(), b'existing file must survive') + self.assertEqual(importer.new_blend_output(Path(directory) / 'new.blend').name, 'new.blend') + + +if __name__ == "__main__": + result = unittest.main(exit=False) + if result.result.wasSuccessful(): + print("IMPORT_VALIDATION_OK") + else: + sys.exit(1) diff --git a/tools/export-blender-camera.mjs b/tools/export-blender-camera.mjs new file mode 100644 index 0000000000..d0e13c2f1f --- /dev/null +++ b/tools/export-blender-camera.mjs @@ -0,0 +1,72 @@ +#!/usr/bin/env node +/** Offline scene-to-camera manifest CLI. Reads JSON only; never loads .env or a viewer. */ +import { readFile, writeFile, stat } from 'node:fs/promises'; +import { parseArgs } from 'node:util'; +import { + parseSceneDocument, + SCENE_DOCUMENT_LIMITS, +} from '../src/director/document.js'; +import { exportCameraManifest } from '../src/tooling/blenderCamera.js'; + +try { + const { values } = parseArgs({ + options: { + input: { type: 'string' }, + output: { type: 'string' }, + scene: { type: 'string' }, + origin: { type: 'string' }, + fps: { type: 'string' }, + width: { type: 'string' }, + height: { type: 'string' }, + 'horizontal-fov-deg': { type: 'string' }, + 'sensor-width-mm': { type: 'string', default: '36' }, + help: { type: 'boolean', default: false }, + }, + }); + if (values.help) { + console.log( + 'Usage: node tools/export-blender-camera.mjs --input scene.json --output camera.json --origin lat,lon,ellipsoidHeight --fps 30 (or 30000/1001) --width 1920 --height 1080 --horizontal-fov-deg 60 [--scene id] [--sensor-width-mm 36]', + ); + } else { + for (const key of [ + 'input', + 'output', + 'origin', + 'fps', + 'width', + 'height', + 'horizontal-fov-deg', + ]) { + if (!values[key]?.trim()) throw new Error(`Missing --${key}; use --help`); + } + if (!/^\d+(?:\/\d+)?$/.test(values.fps)) + throw new Error('fps must be an integer or integer ratio'); + 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 [numerator, denominator = 1] = values.fps.split('/').map(Number); + const [lat, lon, height] = originParts.map(Number); + const manifest = exportCameraManifest(document, { + sceneId: values.scene, + origin: { lat, lon, height }, + fps: { numerator, denominator }, + width: Number(values.width), + height: Number(values.height), + horizontalFovDegrees: Number(values['horizontal-fov-deg']), + sensorWidthMm: Number(values['sensor-width-mm']), + }); + const json = JSON.stringify(manifest, null, 2) + '\n'; + if (Buffer.byteLength(json) > 64 * 1024 * 1024) + throw new Error('Camera manifest exceeds 64 MiB'); + await writeFile(values.output, json, { flag: 'wx' }); + console.log( + `CAMERA_EXPORT_OK: ${manifest.shots.length} shots, ${manifest.frames.length} frames`, + ); + } +} catch (error) { + console.error(`Camera export failed: ${error.message}`); + process.exitCode = 1; +} From d41c7dcfce56ca7cee3efd056d9713d6c20e817a Mon Sep 17 00:00:00 2001 From: disco Date: Wed, 28 Oct 2026 20:16:17 -0600 Subject: [PATCH 2/9] docs: add Blender camera bridge changelog for #1460 --- changelog.d/1460-blender-camera-interchange.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 changelog.d/1460-blender-camera-interchange.md diff --git a/changelog.d/1460-blender-camera-interchange.md b/changelog.d/1460-blender-camera-interchange.md new file mode 100644 index 0000000000..61e348b413 --- /dev/null +++ b/changelog.d/1460-blender-camera-interchange.md @@ -0,0 +1,3 @@ +- Export saved Director scenes to editable Blender cameras with a camera-only + offline manifest preserving ENU coordinates, lens and rational timing, plus + an importer and projection checks (UBN606, #1460). From 24df77bb5c445170ca5761cc6cac26dbe8ab920e Mon Sep 17 00:00:00 2001 From: disco Date: Wed, 28 Oct 2026 20:18:35 -0600 Subject: [PATCH 3/9] test: resolve sky fixture URLs as native file paths --- src/tooling/skyAssets.paintOut.test.mjs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/tooling/skyAssets.paintOut.test.mjs b/src/tooling/skyAssets.paintOut.test.mjs index ddb57589a8..22589dfb05 100644 --- a/src/tooling/skyAssets.paintOut.test.mjs +++ b/src/tooling/skyAssets.paintOut.test.mjs @@ -1,6 +1,7 @@ import assert from 'node:assert/strict'; import test from 'node:test'; import sharp from 'sharp'; +import { fileURLToPath } from 'node:url'; import { CUBE_FACES, FACE_FILE_SUFFIX, @@ -24,7 +25,7 @@ test('painted-out planets leave no disc brighter than the sky around them', asyn })); for (const face of CUBE_FACES) { const { data, info } = await sharp( - new URL(`milkyway_${FACE_FILE_SUFFIX[face]}.webp`, SKY).pathname, + fileURLToPath(new URL(`milkyway_${FACE_FILE_SUFFIX[face]}.webp`, SKY)), ) .raw() .toBuffer({ resolveWithObject: true }); From 6169b8defb52a66afb5db66302b03d35383c6648 Mon Sep 17 00:00:00 2001 From: disco Date: Wed, 28 Oct 2026 20:37:58 -0600 Subject: [PATCH 4/9] perf: bulk-write Blender camera animation curves --- tools/blender/camera_import.py | 61 +++++++++++++++++++++++----------- tools/blender/check_import.py | 9 ++++- 2 files changed, 49 insertions(+), 21 deletions(-) diff --git a/tools/blender/camera_import.py b/tools/blender/camera_import.py index 113909ff46..134bd33368 100644 --- a/tools/blender/camera_import.py +++ b/tools/blender/camera_import.py @@ -157,11 +157,47 @@ def read_manifest(path): return validate_manifest(json.loads(payload)) +def _camera_curves(camera): + """Read this camera's curves from current slotted or older legacy actions.""" + action = camera.animation_data.action + if hasattr(action, "layers") and action.layers: + for layer in action.layers: + for strip in layer.strips: + bag = strip.channelbag(camera.animation_data.action_slot) + if bag: + yield from bag.fcurves + else: + yield from action.fcurves + + +def _write_camera_keys(camera, samples): + """Allocate each F-Curve once, avoiding repeated insertion/handle updates.""" + first = samples[0] + camera.location = first[1] + camera.rotation_quaternion = first[2] + # Let Blender create the appropriate action/slot for its own API version. + camera.keyframe_insert(data_path="location", frame=first[0]) + camera.keyframe_insert(data_path="rotation_quaternion", frame=first[0]) + for curve in _camera_curves(camera): + channel = 1 if curve.data_path == "location" else 2 + component = curve.array_index + coordinates = [value for frame, location, rotation in samples + for value in (frame, (location if channel == 1 else rotation)[component])] + points = curve.keyframe_points + points.clear() + points.add(len(samples)) + points.foreach_set("co", coordinates) + # Keep the exact sampled motion, rather than Blender's default Bezier. + for key in points: + key.interpolation = "LINEAR" + curve.update() + + def import_manifest(data): """Create a new scene with editable per-shot cameras; preserve existing scenes.""" validate_manifest(data) import bpy - from mathutils import Matrix, Vector + from mathutils import Matrix scene = bpy.data.scenes.new(f"GEV {data['source'].get('sceneTitle') or data['source']['sceneId']}") scene.unit_settings.system = "METRIC" @@ -201,8 +237,8 @@ def import_manifest(data): marker = scene.timeline_markers.new(f"GEV {shot['id']}", frame=int(shot["frameStart"])) marker.camera = camera previous = {} + keys = {shot_id: [] for shot_id in cameras} for sample in data["frames"]: - camera = cameras[sample["shotId"]] # Manifest vectors are columns, while mathutils.Matrix accepts rows. basis = Matrix(sample["basisColumns"]).transposed() rotation = basis.to_quaternion().normalized() @@ -210,24 +246,9 @@ def import_manifest(data): if old is not None and rotation.dot(old) < 0: rotation.negate() previous[sample["shotId"]] = rotation.copy() - camera.location = Vector(sample["position"]) - camera.rotation_quaternion = rotation - camera.keyframe_insert(data_path="location", frame=sample["frame"]) - camera.keyframe_insert(data_path="rotation_quaternion", frame=sample["frame"]) - # Blender defaults to Bezier, which would alter motion between sampled frames. - for camera in cameras.values(): - action = camera.animation_data.action - if hasattr(action, "layers") and action.layers: - for layer in action.layers: - for strip in layer.strips: - bag = strip.channelbag(camera.animation_data.action_slot) - for curve in bag.fcurves if bag else []: - for key in curve.keyframe_points: - key.interpolation = "LINEAR" - else: - for curve in action.fcurves: - for key in curve.keyframe_points: - key.interpolation = "LINEAR" + keys[sample["shotId"]].append((sample["frame"], sample["position"], tuple(rotation))) + for shot_id, camera in cameras.items(): + _write_camera_keys(camera, keys[shot_id]) scene.camera = cameras[data["shots"][0]["id"]] if bpy.context.window: bpy.context.window.scene = scene diff --git a/tools/blender/check_import.py b/tools/blender/check_import.py index 5295ebf72f..1026965b44 100644 --- a/tools/blender/check_import.py +++ b/tools/blender/check_import.py @@ -99,7 +99,14 @@ def check_all(): cameras = {json.loads(obj["gev_shot"])["id"]: obj for obj in scene.objects if "gev_shot" in obj} assert set(cameras) == {shot["id"] for shot in manifest["shots"]} for shot in manifest["shots"]: - assert json.loads(cameras[shot["id"]]["gev_shot"]) == shot + camera = cameras[shot["id"]] + assert json.loads(camera["gev_shot"]) == shot + expected_frames = [sample["frame"] for sample in manifest["frames"] if sample["shotId"] == shot["id"]] + curves = list(importer._camera_curves(camera)) + assert len(curves) == 7, "Expected three location and four quaternion channels" + for curve in curves: + assert [key.co[0] for key in curve.keyframe_points] == expected_frames + assert all(key.interpolation == "LINEAR" for key in curve.keyframe_points) for item in case["checks"]: scene.frame_set(item["frame"]) active = scene.camera From 21ac12c105d1f1b5d7c8fd110ba5012ed45adafa Mon Sep 17 00:00:00 2001 From: disco Date: Wed, 28 Oct 2026 20:41:59 -0600 Subject: [PATCH 5/9] docs: record verified Blender camera import capacity --- docs/BLENDER-CAMERAS.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/BLENDER-CAMERAS.md b/docs/BLENDER-CAMERAS.md index a3d1ca6b6f..e93d42d88b 100644 --- a/docs/BLENDER-CAMERAS.md +++ b/docs/BLENDER-CAMERAS.md @@ -119,6 +119,14 @@ timeline marker selection, rejected malformed input and preservation of existing scenes. `blender-receipt.json` records measured projection error and Blender version. A successful run prints `BLENDER_CAMERA_PROJECTION_OK`. +Camera keys are allocated in batches per animation channel. A synthetic +single-camera capacity check on Windows with Blender 5.2.2 LTS imported all +100,000 supported frames (700,000 location/quaternion keys) in 1.42 seconds, +saved in 0.19 seconds and reopened in 0.06 seconds. It checked every channel's +key count and linear interpolation, plus the first, middle and last camera +poses before saving and after reopening. These timings measure camera-data +import, without rendering. + 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. From e18aa3769840435c203e1cc7d8c7e796e0410f85 Mon Sep 17 00:00:00 2001 From: UBN606 Date: Fri, 30 Oct 2026 12:52:06 +0000 Subject: [PATCH 6/9] test: match #1461's import order for the sky fixture path fix Identical hunks let git merge #1460 with #1461, #1093 or #1397's copy of this fix without a duplicate fileURLToPath import. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BahZiPo19eToFS7Hd4jTQG --- src/tooling/skyAssets.paintOut.test.mjs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/tooling/skyAssets.paintOut.test.mjs b/src/tooling/skyAssets.paintOut.test.mjs index 22589dfb05..78a91519eb 100644 --- a/src/tooling/skyAssets.paintOut.test.mjs +++ b/src/tooling/skyAssets.paintOut.test.mjs @@ -1,7 +1,7 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import sharp from 'sharp'; import { fileURLToPath } from 'node:url'; +import sharp from 'sharp'; import { CUBE_FACES, FACE_FILE_SUFFIX, From 159c0cfcb0be3522e3378f2c646178ec334e43bd Mon Sep 17 00:00:00 2001 From: UBN606 Date: Tue, 3 Nov 2026 19:34:33 +0000 Subject: [PATCH 7/9] Export Director cameras as a USD stage and use runtime shot timing Address review on #1460: - Replace the custom JSON manifest and the bpy importer with a plain-text .usda stage written from Node (no new dependency) that Blender imports natively: Z-up, metersPerUnit 1, one camera per shot with per-frame xformOp:transform samples, time codes equal to frame numbers, and lens attributes in tenths of a scene unit (Blender multiplies by 100 * metersPerUnit). - Take shot timing from shotRuntimeDurationSec/effectiveShotHoldSec, the functions Director playback and seeking use, so pack hold overrides, minimum holds and evidence-sequence durations match the app. - Extract runtimeLayerStatesForShot in shotPresentation.js (behaviour unchanged) so holds for long scenes are resolved without quadratic work. - Remove tools/blender Python files; update docs, tests and changelog. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01BahZiNcXqNSvAmR5TCuTAu --- .gitignore | 3 - .../1460-blender-camera-interchange.md | 6 +- docs/BLENDER-CAMERAS.md | 159 +++++----- docs/CURRENT-STATE.md | 16 +- scripts/format-scope.json | 1 - src/scenes/shotPresentation.js | 16 +- src/tooling/blenderCamera.js | 287 +++++++++++++++--- src/tooling/blenderCamera.test.mjs | 276 +++++++++++++++-- tools/README.md | 10 +- tools/blender/camera_import.py | 287 ------------------ tools/blender/check_import.py | 147 --------- tools/blender/make_fixture.mjs | 173 ----------- tools/blender/test_camera_import.py | 91 ------ tools/export-blender-camera.mjs | 17 +- 14 files changed, 624 insertions(+), 865 deletions(-) delete mode 100644 tools/blender/camera_import.py delete mode 100644 tools/blender/check_import.py delete mode 100644 tools/blender/make_fixture.mjs delete mode 100644 tools/blender/test_camera_import.py diff --git a/.gitignore b/.gitignore index fa4008e088..11e081e7d8 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,3 @@ pinokio/.installed # Transient: a release interrupted mid-assembly (npm run changelog recovers it) changelog.d/.assembling/ - -# Optional Blender camera importer Python cache. -tools/blender/__pycache__/ diff --git a/changelog.d/1460-blender-camera-interchange.md b/changelog.d/1460-blender-camera-interchange.md index 61e348b413..207c58fdea 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 to editable Blender cameras with a camera-only - offline manifest preserving ENU coordinates, lens and rational timing, plus - an importer and projection checks (UBN606, #1460). +- 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). diff --git a/docs/BLENDER-CAMERAS.md b/docs/BLENDER-CAMERAS.md index e93d42d88b..668939bb62 100644 --- a/docs/BLENDER-CAMERAS.md +++ b/docs/BLENDER-CAMERAS.md @@ -1,9 +1,11 @@ # GEV cameras in Blender -Export one saved Director scene into a camera-only JSON manifest, then import -editable shot cameras into a new Blender scene. This offline path requires no -API key, browser, imagery, terrain, model provider or rendering. It does not -export any tiles or geometry. Use independently licensed assets for your set. +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 @@ -15,12 +17,12 @@ Use the repository's supported Node runtime and installed dependencies. Save a Director project as JSON, then run from the repository root: ```sh -node tools/export-blender-camera.mjs --input scene.json --output cameras.json --scene my-scene-id --origin 39.7,-105,1600 --fps 30000/1001 --width 1920 --height 1080 --horizontal-fov-deg 70 +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 ``` Quote paths containing spaces. Omit `--scene` only when the document contains -exactly one scene. Output must be a new file; the tool refuses to overwrite it. -No environment files are read. +exactly one scene. Output 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 @@ -41,91 +43,104 @@ 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 the CLI also enforces 64 MiB. Every shot needs at least -one sampled frame. +to 100,000 frames and 64 MiB. Every shot needs at least one sampled frame. ## Timing and camera semantics -Sampling uses GEV's Director **seek** interpolation and authored timing. 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. +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 +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. + +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`. The bridge does not reproduce Cesium's implicit live `flyTo` trajectory, -provider readiness, registered data-pack timing overrides, runtime layer holds, -layer-owned camera motion, lens changes, visual effects, media or geometry. -Export authored camera moves when repeatable playback framing is required. -This feature does not depend on GEV video export. +provider readiness, layer-owned camera motion, lens changes, visual effects, +media or geometry. Export authored camera moves when repeatable playback +framing is required. This feature does not depend on GEV video export. Frame 1 samples time zero. Frame `n` samples `(n - 1) * denominator / numerator` seconds. The final sample precedes the exclusive scene end; frame count is the ceiling of duration times fps, with rounding noise at integer boundaries removed. -Shot ranges are half open: `frameStart <= frame < frameEndExclusive`. Fractional -shot boundaries switch at the first sampled time at or after the boundary. -Both authored seconds and sampled frame ranges are retained. +Shot ranges are half open: `frameStart <= frame < frameEndExclusive`. A shot +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. +- 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. +- A root `GEV` transform at identity, with one perspective `Camera` per shot + named `Shot_001_`, `Shot_002_` and so on. Each camera has an + `xformOp:transform` matrix time sample on every frame of its own shot range, + and holds its first or last pose outside that range. Camera local X points + right, local Y up and local -Z forward, which is both the USD and the Blender + camera convention. +- Lens attributes in USD's units: `focalLength`, `horizontalAperture` and + `verticalAperture` are in **tenths of a scene unit**, so with + `metersPerUnit = 1` one unit of these attributes is 100 mm. A 25 mm lens on + a 36 mm sensor is written as `focalLength = 0.25` and + `horizontalAperture = 0.36`. The vertical aperture is the sensor width times + `height / width`, so it matches the output aspect. +- 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. ## Import into Blender -The importer is a standalone Python file using the standard library and -Blender's bundled Python API. Tested with Blender 5.2.2 LTS; other versions -need their own check before use. +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. +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**). -```sh -blender --background --factory-startup --disable-autoexec --threads 1 --python-exit-code 1 --python tools/blender/camera_import.py -- cameras.json cameras.blend -``` +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`. -Both paths after `--` are required. Choose a new filename ending in lowercase -`.blend`; a missing or different extension is rejected before creating a scene. The importer -validates the entire manifest before changing Blender data and creates a new -scene, preserving existing scenes. It adds an identity ENU origin object, -one perspective camera per shot, sampled location/quaternion keyframes and -camera-bound timeline markers. Camera local X points right, local Y points up, -and local negative Z looks forward. Scene X/Y/Z are east/north/up, in meters. -Sensor fit is explicitly horizontal. Quaternion signs are kept continuous and -keyframe interpolation is linear between sampled frames. +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. -Scene custom properties `gev_source`, `gev_coordinates` and `gev_timeline` -preserve geographic, attribution and rational-fps metadata. Camera custom -properties preserve source scene/shot IDs, titles, pack identifiers, endpoints -and authored timing. Source data-pack attributions are retained as text; no -referenced assets are fetched. The original fps ratio is preserved exactly in -metadata; Blender's `fps_base` is floating point, so its effective rate has a -small representation error. Cameras use a 0.01 m near plane and 200 km far -plane; adjust clipping for your separately authored set if needed. - -For an existing Blender session, load this trusted module and call -`import_file(path)`; it also creates and selects a new scene. When writing your -own headless checks, activate that scene before evaluating its animation. - -## Reproducible, provider-free check - -Use a fresh output directory for each run. These commands create synthetic -camera data, run standard Python validation, import the actual cameras, compare -landmark projection to a separate Cesium Camera oracle, then save/reopen a -`.blend` and repeat. They do not render or launch a browser. +## Checks ```sh node --test src/tooling/blenderCamera.test.mjs -python tools/blender/test_camera_import.py -node tools/blender/make_fixture.mjs --output output/blender-camera-check -blender --background --factory-startup --disable-autoexec --threads 1 --python-exit-code 1 --python tools/blender/check_import.py -- output/blender-camera-check ``` -The check covers moving and held cameras, nonzero roll, scene-local tangent -frames, a cut, landscape/portrait projection, rational fps, source metadata, -timeline marker selection, rejected malformed input and preservation of existing -scenes. `blender-receipt.json` records measured projection error and Blender -version. A successful run prints `BLENDER_CAMERA_PROJECTION_OK`. - -Camera keys are allocated in batches per animation channel. A synthetic -single-camera capacity check on Windows with Blender 5.2.2 LTS imported all -100,000 supported frames (700,000 location/quaternion keys) in 1.42 seconds, -saved in 0.19 seconds and reopened in 0.06 seconds. It checked every channel's -key count and linear interpolation, plus the first, middle and last camera -poses before saving and after reopening. These timings measure camera-data -import, without rendering. +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. 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 f74cbb2aba..a489331ae0 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -647,14 +647,14 @@ 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 ENU meter camera samples with an explicit WGS84 ellipsoid -origin, horizontal lens and rational fps. It reuses Director seek interpolation -and authored timing; runtime layer timing, implicit live flyTo paths, imagery -and geometry are outside this camera-only format. The Python importer creates -a separate editable scene with per-shot cameras and timeline markers. -The synthetic `tools/blender/check_import.py` check compares actual Blender -projection and saved-file reload against a separate Cesium Camera oracle -without rendering or provider access. +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. Realtime voice composes separate connection, response/tool, Radio handoff, input and audio-meter, cost, viewport-context and diagnostic owners. The existing diff --git a/scripts/format-scope.json b/scripts/format-scope.json index f2c43139d8..a40feb990c 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -1,7 +1,6 @@ [ "src/tooling/blenderCamera.test.mjs", "tools/export-blender-camera.mjs", - "tools/blender/make_fixture.mjs", ".prettierrc.json", "package.json", "scripts/format-scope.json", diff --git a/src/scenes/shotPresentation.js b/src/scenes/shotPresentation.js index 04759fc3fb..1c27b5d6ff 100644 --- a/src/scenes/shotPresentation.js +++ b/src/scenes/shotPresentation.js @@ -153,8 +153,8 @@ export function effectiveShotHoldSec( ); } -/** Estimate flight plus effective hold without mutating saved layer parameters. */ -export function shotRuntimeDurationSec(scene, shot, packs) { +/** Copy a shot's layer states with registered runtime controls, without mutating saved parameters. */ +export function runtimeLayerStatesForShot(shot, packs) { const states = deepClone(shot?.layers || {}); const sourceRecipe = packs.recipeForShot(shot); for (const state of Object.values(states)) { @@ -168,8 +168,18 @@ export function shotRuntimeDurationSec(scene, shot, packs) { }; } } + return states; +} + +/** 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, states) + effectiveShotHoldSec( + scene, + shot, + packs, + runtimeLayerStatesForShot(shot, packs), + ) ); } diff --git a/src/tooling/blenderCamera.js b/src/tooling/blenderCamera.js index e90c4861cf..b7f14f934d 100644 --- a/src/tooling/blenderCamera.js +++ b/src/tooling/blenderCamera.js @@ -1,4 +1,4 @@ -/** Camera-only interchange. No viewer, providers, environment files or terrain access. */ +/** Camera-only USD interchange. No viewer, providers, environment files or terrain access. */ import * as C from 'cesium'; import { validateSceneDocument } from '../director/document.js'; import { @@ -7,9 +7,20 @@ import { sampleCameraMove, } from '../director/camera.js'; import { cameraAtProgress } from '../director/timeline.js'; +import { + effectiveShotHoldSec, + runtimeLayerStatesForShot, + shotRuntimeDurationSec, +} from '../scenes/shotPresentation.js'; +import { createDefaultScenePacks } from '../scenes/packs/defaults.js'; -export const CAMERA_MANIFEST_SCHEMA = 'gev.camera-manifest.v1'; +export const CAMERA_USD_SCHEMA = 'gev.camera-usd.v1'; export const MAX_CAMERA_FRAMES = 100000; +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 ( @@ -34,7 +45,8 @@ function position(pose, heightKey = 'alt') { /** Convert Cesium's WGS84/heading-pitch-roll pose to a fixed Blender ENU frame. * Angles are degrees; alt and origin.height are WGS84 ellipsoid meters. - * The returned columns are Blender's local X (right), Y (up), Z (back). + * 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) { position(pose); @@ -105,11 +117,40 @@ function identity(value, label) { return value; } -/** Export one existing scene using Director seek interpolation and authored timing. +/** Resolve the flight-plus-hold seconds and holds that Director playback and seeking use. + * Both come from shotPresentation.js, so registered pack overrides, minimum holds and + * evidence-sequence durations match the app instead of the saved holdSec alone. + */ +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 }); + } + return { + durationFor: (_scene, shot) => byShot.get(shot).durationSec, + holdFor: (_scene, shot) => byShot.get(shot).holdSec, + }; +} + +/** Sample one saved scene with Director seek interpolation and runtime playback 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. */ -export function exportCameraManifest( +export function sampleSceneCameras( project, { sceneId, @@ -119,6 +160,7 @@ export function exportCameraManifest( height, horizontalFovDegrees, sensorWidthMm = 36, + scenePacks = createDefaultScenePacks(), } = {}, ) { validateSceneDocument(project); @@ -144,6 +186,7 @@ export function exportCameraManifest( 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 ( @@ -154,6 +197,14 @@ export function exportCameraManifest( }; 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) => { identity(shot.id, 'Shot'); const camera = resolveCameraPose(scene, shot.camera); @@ -162,18 +213,13 @@ export function exportCameraManifest( if (move) position(move.from); cameraPoseToEnu(camera, origin); if (move) cameraPoseToEnu(move.from, origin); - const durationSec = shot.durationSec || 4; - const holdSec = shot.holdSec || 0; + const runtimeDurationSec = timing.durationFor(scene, shot); const startTimeSec = elapsed; // Compensated summation prevents long decimal timelines gaining a frame. - const increment = durationSec + holdSec - rounding; + const increment = runtimeDurationSec - rounding; const next = elapsed + increment; rounding = next - elapsed - increment; elapsed = next; - const frameStart = frameAt(startTimeSec); - const frameEndExclusive = frameAt(elapsed); - if (frameStart >= frameEndExclusive) - throw new Error(`Shot ${shot.id} has no sampled frame at this fps`); return { id: shot.id, title: shot.title || '', @@ -185,41 +231,56 @@ export function exportCameraManifest( : {}), startTimeSec, endTimeSec: elapsed, - durationSec, - holdSec, - frameStart, - frameEndExclusive, - camera, - move, + flightDurationSec: shot.durationSec || 4, + authoredHoldSec: Number(shot.holdSec) || 0, + runtimeHoldSec: timing.holdFor(scene, shot), + frameStart: 0, + frameEndExclusive: 0, }; }); const frameCount = frameAt(elapsed) - 1; 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 ( - frame >= shots[shotIndex].frameEndExclusive && - shotIndex < shots.length - 1 + shotIndex < shots.length - 1 && + !(normalized < seekEnds[shotIndex] / seekTotalSec) ) shotIndex += 1; - const shot = shots[shotIndex]; - const timeSec = ((frame - 1) * fps.denominator) / fps.numerator; - const progress = Math.max( - 0, - Math.min( - 1, - (timeSec - shot.startTimeSec) / Math.max(0.001, shot.durationSec), - ), + 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 pose = shot.move - ? sampleCameraMove(shot.move, progress) - : cameraAtProgress( - shots[shotIndex - 1]?.camera || shot.camera, - shot.camera, - progress, - ); + 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]; + if (!shot.frameStart) shot.frameStart = frame; + shot.frameEndExclusive = frame + 1; frames.push({ frame, timeSec, @@ -227,6 +288,10 @@ export function exportCameraManifest( ...cameraPoseToEnu(pose, origin), }); } + 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)), @@ -235,12 +300,12 @@ export function exportCameraManifest( 10000, ); return { - schema: CAMERA_MANIFEST_SCHEMA, + schema: CAMERA_USD_SCHEMA, source: { sceneId: scene.id, sceneTitle: scene.title || '', documentVersion: project.version ?? 1, - sampling: 'director-seek-authored-timing', + sampling: 'director-seek-runtime-timing', attributions: (scene.dataPacks || []).map(({ attribution }) => structuredClone(attribution), ), @@ -254,8 +319,8 @@ export function exportCameraManifest( }, camera: { projection: 'perspective', - sensorFit: 'HORIZONTAL', sensorWidthMm, + sensorHeightMm: (sensorWidthMm * height) / width, lensMm, horizontalFovRadians, verticalFovRadians: @@ -274,3 +339,149 @@ export function exportCameraManifest( frames, }; } + +/** Shortest decimal for a finite double, without signed zero or 17-digit noise. */ +function usdNumber(value) { + const rounded = Number(value.toPrecision(15)); + return Object.is(rounded, -0) ? '0' : String(rounded); +} + +/** Quote text for a .usda string literal. */ +function usdString(value) { + return `"${String(value) + .replace(/\\/g, '\\\\') + .replace(/"/g, '\\"') + .replace(/\n/g, '\\n') + .replace(/\r/g, '\\r') + .replace(/\t/g, '\\t') + .replace( + /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, + (char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`, + )}"`; +} + +/** USD prim names are identifiers; saved IDs stay in custom properties. */ +function shotPrimName(shot, index) { + const safe = shot.id.replace(/[^A-Za-z0-9_]/g, '_').slice(0, 40); + return `Shot_${String(index + 1).padStart(3, '0')}_${safe}`; +} + +/** USD matrices are row-vector: rows are camera X, Y, Z axes, then translation. */ +function usdMatrix({ position: p, basisColumns: [right, up, back] }) { + const row = (values, w) => `(${[...values, w].map(usdNumber).join(', ')})`; + return `( ${row(right, 0)}, ${row(up, 0)}, ${row(back, 0)}, ${row(p, 1)} )`; +} + +/** Write sampled cameras as a plain-text USD stage that Blender imports natively. + * Z-up meters, one perspective camera per shot, time codes equal to frame numbers. + */ +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', + '(', + ' customLayerData = {', + ` string gevCamera = ${json(camera)}`, + ` string gevCoordinates = ${json(coordinates)}`, + ` string gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`, + ` string gevShots = ${json(shotTable)}`, + ` 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}`, + ` framesPerSecond = ${rate}`, + ' metersPerUnit = 1', + ` startTimeCode = ${timeline.frameStart}`, + ` timeCodesPerSecond = ${rate}`, + ' upAxis = "Z"', + ')', + '', + 'def Xform "GEV"', + '{', + ` custom string userProperties:gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`, + ` custom string userProperties:gevSceneId = ${usdString(source.sceneId)}`, + ` custom string userProperties:gevSceneTitle = ${usdString(source.sceneTitle)}`, + ` custom string userProperties:gevOrigin = ${json(coordinates.origin)}`, + ` custom string userProperties:gevFps = ${usdString(`${timeline.fps.numerator}/${timeline.fps.denominator}`)}`, + ` custom int userProperties:gevWidth = ${timeline.width}`, + ` custom int userProperties:gevHeight = ${timeline.height}`, + ` custom string userProperties:gevAttributions = ${json(source.attributions)}`, + ]; + shots.forEach((shot, index) => { + out.push( + '', + ` def Camera ${usdString(shotPrimName(shot, index))}`, + ' {', + ' float2 clippingRange = (0.01, 200000)', + ` float focalLength = ${usdNumber(camera.lensMm / MM_PER_USD_LENS_UNIT)}`, + ` float horizontalAperture = ${usdNumber(camera.sensorWidthMm / MM_PER_USD_LENS_UNIT)}`, + ` float verticalAperture = ${usdNumber(camera.sensorHeightMm / MM_PER_USD_LENS_UNIT)}`, + ' token projection = "perspective"', + ` custom string userProperties:gevShotId = ${usdString(shot.id)}`, + ` custom string userProperties:gevShotTitle = ${usdString(shot.title)}`, + ...(shot.sourcePackId + ? [ + ` custom string userProperties:gevSourcePackId = ${usdString(shot.sourcePackId)}`, + ` custom string userProperties:gevSourcePackVersion = ${usdString(shot.sourcePackVersion ?? '')}`, + ] + : []), + ` 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:gevFlightDurationSec = ${usdNumber(shot.flightDurationSec)}`, + ` custom double userProperties:gevAuthoredHoldSec = ${usdNumber(shot.authoredHoldSec)}`, + ` custom double userProperties:gevRuntimeHoldSec = ${usdNumber(shot.runtimeHoldSec)}`, + ' matrix4d xformOp:transform.timeSamples = {', + ); + for (let f = shot.frameStart; f < shot.frameEndExclusive; f += 1) { + out.push(` ${f}: ${usdMatrix(frames[f - 1])},`); + } + out.push( + ' }', + ' uniform token[] xformOpOrder = ["xformOp:transform"]', + ' }', + ); + }); + out.push('}', ''); + 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); + if (Buffer.byteLength(usda) > MAX_CAMERA_USDA_BYTES) + throw new RangeError('Camera USD exceeds 64 MiB'); + return { usda, samples }; +} diff --git a/src/tooling/blenderCamera.test.mjs b/src/tooling/blenderCamera.test.mjs index 4507e2f5df..523719634f 100644 --- a/src/tooling/blenderCamera.test.mjs +++ b/src/tooling/blenderCamera.test.mjs @@ -13,10 +13,17 @@ import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; import { spawnSync } from 'node:child_process'; import { sceneSeekState } from '../director/timeline.js'; +import { + effectiveShotHoldSec, + shotRuntimeDurationSec, +} from '../scenes/shotPresentation.js'; +import { createDefaultScenePacks } from '../scenes/packs/defaults.js'; +import { createScenePackRegistry } from '../scenes/packs/registry.js'; const adapter = await import('./blenderCamera.js'); -test('a portable camera manifest adapter exists', () => { - assert.equal(typeof adapter.exportCameraManifest, 'function'); +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 }; @@ -46,7 +53,7 @@ const project = ( const near = (a, b, eps = 1e-8) => a.forEach((v, i) => assert.ok(Math.abs(v - b[i]) < eps, `${a} != ${b}`)); const camera = (changes = {}, opts = {}) => - adapter.exportCameraManifest( + adapter.sampleSceneCameras( project([{ id: 'camera', durationSec: 1, camera: pose(changes) }]), options(opts), ).frames[0]; @@ -129,12 +136,11 @@ test('explicit horizontal lens works for landscape and portrait output', () => { [1920, 1080], [1080, 1920], ]) { - const m = adapter.exportCameraManifest( - project(), - options({ width, height }), - ); + const m = adapter.sampleSceneCameras(project(), options({ width, height })); assert.ok(Math.abs(m.camera.lensMm - 18) < 1e-10); - assert.equal(m.camera.sensorFit, 'HORIZONTAL'); + 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, @@ -142,7 +148,7 @@ test('explicit horizontal lens works for landscape and portrait output', () => { } }); -test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON round trip', () => { +test('anchors, cubic moves, cuts, holds and rational frame timing are sampled', () => { const p = project([ { id: 'move', @@ -173,7 +179,7 @@ test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON r altitudeReference: 'ellipsoid', }, ]; - const m = adapter.exportCameraManifest( + const m = adapter.sampleSceneCameras( p, options({ origin: { lat: 0, lon: 180, height: 0 }, @@ -190,7 +196,6 @@ test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON r assert.equal(m.frames[18].shotId, 'cut'); assert.equal(m.frames[18].timeSec, (18 * 1001) / 30000); near(m.frames[12].position, m.frames[17].position); - assert.deepEqual(JSON.parse(JSON.stringify(m)), m); assert.equal(p.scenes[0].shots[0].camera.anchorId, 'end'); }); @@ -202,20 +207,18 @@ test('invalid or ambiguous input fails before export', () => { { origin: { lat: 0, lon: NaN, height: 0 } }, { horizontalFovDegrees: 180 }, ]) { - assert.throws(() => - adapter.exportCameraManifest(project(), options(change)), - ); + assert.throws(() => adapter.sampleSceneCameras(project(), options(change))); } assert.throws(() => camera({ lon: 20 }), /100 km/); const multiple = project(); multiple.scenes.push({ ...multiple.scenes[0], id: 'other' }); assert.throws( - () => adapter.exportCameraManifest(multiple, options()), + () => adapter.sampleSceneCameras(multiple, options()), /scene/i, ); assert.throws( () => - adapter.exportCameraManifest( + adapter.sampleSceneCameras( project([{ id: 'missing', camera: { heading: 0 } }]), options(), ), @@ -223,7 +226,7 @@ test('invalid or ambiguous input fails before export', () => { ); assert.throws( () => - adapter.exportCameraManifest( + adapter.sampleSceneCameras( project([{ id: 'long', camera: pose(), durationSec: 86400 }]), options(), ), @@ -233,12 +236,12 @@ test('invalid or ambiguous input fails before export', () => { test('projection settings cannot be silently clamped by Blender', () => { assert.throws( - () => adapter.exportCameraManifest(project(), options({ width: 1 })), + () => adapter.sampleSceneCameras(project(), options({ width: 1 })), /width/, ); assert.throws( () => - adapter.exportCameraManifest( + adapter.sampleSceneCameras( project(), options({ horizontalFovDegrees: 179, sensorWidthMm: 1 }), ), @@ -261,7 +264,7 @@ test('every exported sample agrees with Director seeking at fractional shot boun holdSec: 0.13, }, ]); - const m = adapter.exportCameraManifest(p, options()); + const m = adapter.sampleSceneCameras(p, options()); assert.equal(m.frames.length, 21); for (const sample of m.frames) { const state = sceneSeekState( @@ -283,7 +286,7 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio const directory = mkdtempSync(join(tmpdir(), 'gev camera ')); try { const input = join(directory, 'saved scene.json'); - const output = join(directory, 'camera manifest.json'); + const output = join(directory, 'camera stage.usda'); writeFileSync(input, JSON.stringify(project())); const script = fileURLToPath( new URL('../../tools/export-blender-camera.mjs', import.meta.url), @@ -309,11 +312,21 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio assert.equal(first.status, 0, first.stderr); assert.match(first.stdout, /CAMERA_EXPORT_OK/); const contents = readFileSync(output, 'utf8'); - assert.equal(JSON.parse(contents).timeline.fps.denominator, 1001); + assert.match(contents, /^#usda 1\.0\n/); + assert.match(contents, /userProperties:gevFps = "30000\/1001"/); const repeat = spawnSync(process.execPath, args, { encoding: 'utf8' }); assert.equal(repeat.status, 1); assert.equal(readFileSync(output, 'utf8'), contents); - const invalidOutput = join(directory, 'invalid.json'); + const jsonOutput = join(directory, 'cameras.json'); + const wrongExtension = [...args]; + wrongExtension[wrongExtension.indexOf(output)] = jsonOutput; + const rejected = spawnSync(process.execPath, wrongExtension, { + encoding: 'utf8', + }); + assert.equal(rejected.status, 1); + assert.match(rejected.stderr, /\.usda/); + assert.equal(existsSync(jsonOutput), false); + const invalidOutput = join(directory, 'invalid.usda'); const invalid = [...args]; invalid[invalid.indexOf(output)] = invalidOutput; invalid[invalid.length - 1] = '180'; @@ -337,7 +350,7 @@ test('ordinary submillisecond shots retain the Director seek duration floor', () holdSec: 0.1, }, ]); - const m = adapter.exportCameraManifest(p, options()); + const m = adapter.sampleSceneCameras(p, options()); const sample = m.frames[1]; const state = sceneSeekState( p.scenes[0], @@ -360,8 +373,221 @@ test('long decimal timelines do not gain a rounding-only frame', () => { camera: pose(), })), ); - const m = adapter.exportCameraManifest(p, options()); + 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); }); + +const runtimeSeek = (scene, timeSec, durationSec, packs) => + sceneSeekState( + scene, + timeSec / durationSec, + (s, shot) => shotRuntimeDurationSec(s, shot, packs), + (s, shot) => effectiveShotHoldSec(s, shot, packs), + ); + +test('shot timing follows Director runtime holds, not only the saved holdSec', () => { + // The Director's Mailung trim plays a 7.65 s hold although 15 s was saved. + const p = project([ + { + id: 'mailung', + sourcePackId: 'bhote-koshi-nepal-evidence-pack', + durationSec: 4.2, + holdSec: 15, + camera: pose(), + layers: { + 'bhote-koshi-2026': { + enabled: true, + params: { presentation: 'scene-beat', beatId: 'mailung-bazzar' }, + }, + }, + }, + { id: 'next', durationSec: 1, holdSec: 0, camera: pose({ heading: 90 }) }, + ]); + const before = structuredClone(p); + const m = adapter.sampleSceneCameras(p, options()); + const [first, second] = m.shots; + assert.equal(first.authoredHoldSec, 15); + assert.equal(first.runtimeHoldSec, 7.65); + assert.equal(second.startTimeSec, 4.2 + 7.65); + // Summing authored holds would start the next shot 7.35 s (220 frames) later. + assert.equal(second.frameStart, Math.ceil((4.2 + 7.65) * 30) + 1); + assert.equal(m.timeline.durationSec, 4.2 + 7.65 + 1); + const packs = createDefaultScenePacks(); + p.scenes[0].shots.forEach((shot, i) => + assert.equal( + m.shots[i].runtimeHoldSec, + effectiveShotHoldSec(p.scenes[0], shot, packs), + ), + ); + for (const sample of m.frames) { + const state = runtimeSeek( + p.scenes[0], + sample.timeSec, + m.timeline.durationSec, + packs, + ); + assert.equal(sample.shotId, state.shot.id); + const expected = adapter.cameraPoseToEnu(state.camera, origin); + near(sample.position, expected.position); + sample.basisColumns.forEach((axis, i) => + near(axis, expected.basisColumns[i]), + ); + } + assert.deepEqual(p, before, 'export never rewrites saved shots'); +}); + +test('registered minimum holds and evidence-sequence durations shift later shots', () => { + const packs = createScenePackRegistry({ + recipes: [ + { + id: 'sample', + runtimeControlsByBeat: { + arrival: { evidenceSequence: true, evidenceSequenceDurationSec: 2.5 }, + }, + }, + ], + adapters: [ + { minimumHoldSec: (states) => (states.overview?.enabled ? 3 : 0) }, + ], + }); + const p = project([ + { + id: 'evidence', + sourcePackId: 'sample', + durationSec: 1, + holdSec: 0.5, + camera: pose(), + layers: { + sample: { + enabled: true, + params: { presentation: 'scene-beat', beatId: 'arrival' }, + }, + }, + }, + { + id: 'overview', + durationSec: 1, + holdSec: 0, + camera: pose({ heading: 45 }), + layers: { overview: { enabled: true, params: {} } }, + }, + { id: 'last', durationSec: 1, holdSec: 0, camera: pose({ heading: 90 }) }, + ]); + const m = adapter.sampleSceneCameras(p, options({ scenePacks: packs })); + assert.deepEqual( + m.shots.map((s) => [s.startTimeSec, s.runtimeHoldSec, s.frameStart]), + [ + [0, 2.5, 1], + [3.5, 3, 106], + [7.5, 0, 226], + ], + ); + assert.equal(m.frames.length, 255); + // The holds match the Director's own seek path, which resolves layer states itself. + p.scenes[0].shots.forEach((shot, i) => + assert.equal( + m.shots[i].runtimeHoldSec, + 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) => + text.match(/-?\d+(?:\.\d+)?(?:e[-+]?\d+)?/g).map(Number); + +test('USD stage is Z-up meters with one camera per shot and per-frame matrices', () => { + const p = project([ + { + id: 'first shot', + title: 'He said "hi"\n', + durationSec: 0.2, + holdSec: 0, + camera: pose({ heading: 30, roll: 10, alt: 50 }), + }, + { + id: 'second', + durationSec: 0.1, + holdSec: 0, + camera: pose({ heading: 200, lon: 0.0005, pitch: -30 }), + }, + ]); + const { usda, samples } = adapter.exportCameraUsda(p, options()); + assert.match(usda, /^#usda 1\.0\n/); + for (const line of [ + 'upAxis = "Z"', + 'metersPerUnit = 1', + 'startTimeCode = 1', + `endTimeCode = ${samples.timeline.frameEnd}`, + 'timeCodesPerSecond = 30', + 'framesPerSecond = 30', + 'defaultPrim = "GEV"', + ]) + assert.ok(usda.includes(`\n ${line}\n`), line); + assert.match(usda, /string 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"/); + assert.match(cameras[1], /^"Shot_002_second"/); + // USD lens values are tenths of a scene unit (100 mm at metersPerUnit 1): + // a 90 degree horizontal FOV on a 36 mm sensor is an 18 mm lens. + assert.match(cameras[0], /\n {8}float focalLength = 0\.18\n/); + assert.match(cameras[0], /\n {8}float horizontalAperture = 0\.36\n/); + assert.match(cameras[0], /\n {8}float verticalAperture = 0\.2025\n/); + assert.match(cameras[0], /\n {8}token projection = "perspective"\n/); + assert.ok( + cameras[0].includes( + 'custom string userProperties:gevShotTitle = "He said \\"hi\\"\\n"', + ), + ); + assert.ok( + cameras[0].includes( + 'custom string userProperties:gevShotId = "first shot"', + ), + ); + cameras.forEach((text, index) => { + const shot = samples.shots[index]; + const keys = [...text.matchAll(/\n {12}(\d+): \((.*)\),/g)]; + assert.deepEqual( + keys.map(([, key]) => Number(key)), + Array.from( + { length: shot.frameEndExclusive - shot.frameStart }, + (_, i) => shot.frameStart + i, + ), + ); + for (const [, key, matrix] of keys) { + const values = usdNumbers(matrix); + const frame = samples.frames[Number(key) - 1]; + assert.equal(frame.shotId, shot.id); + const [right, up, back] = frame.basisColumns; + near(values, [...right, 0, ...up, 0, ...back, 0, ...frame.position, 1]); + } + assert.match( + text, + /uniform token\[\] xformOpOrder = \["xformOp:transform"\]/, + ); + }); +}); + +test('USD stage records rational fps and portrait apertures', () => { + const { usda, samples } = adapter.exportCameraUsda( + project(), + options({ + width: 1080, + height: 1920, + fps: { numerator: 30000, denominator: 1001 }, + }), + ); + assert.ok(usda.includes(`\n timeCodesPerSecond = ${30000 / 1001}\n`)); + assert.ok(usda.includes('userProperties:gevFps = "30000/1001"')); + assert.match(usda, /float verticalAperture = 0\.64\n/); + assert.equal(samples.timeline.frameEnd, 30); +}); diff --git a/tools/README.md b/tools/README.md index 88b40ad0e7..4c8618ac5d 100644 --- a/tools/README.md +++ b/tools/README.md @@ -6,11 +6,11 @@ automatically. ## Offline Blender camera interchange -`export-blender-camera.mjs` exports cameras from a saved Director scene; -`blender/camera_import.py` imports an editable rig into a new Blender scene. -These tools require no key, environment file, browser or network access and -export no imagery or geometry. Usage, format and synthetic projection checks: -[Blender cameras](../docs/BLENDER-CAMERAS.md). +`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). diff --git a/tools/blender/camera_import.py b/tools/blender/camera_import.py deleted file mode 100644 index 134bd33368..0000000000 --- a/tools/blender/camera_import.py +++ /dev/null @@ -1,287 +0,0 @@ -"""Import camera-only GEV JSON. Python validation needs no Blender installation. - -Blender console: import camera_import; camera_import.import_file('/path/camera.json') -CLI: blender --background --factory-startup --disable-autoexec --threads 1 - --python tools/blender/camera_import.py -- camera.json output.blend -No image, geometry, network access or rendering is performed. -""" -import json -import math -from pathlib import Path -import sys - -SCHEMA = "gev.camera-manifest.v1" -MAX_BYTES = 64 * 1024 * 1024 -MAX_FRAMES = 100000 - - -def _number(value, label, low, high, integer=False): - if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value): - raise ValueError(f"{label}: expected a finite number") - if not low <= value <= high or (integer and int(value) != value): - raise ValueError(f"{label}: outside supported range") - return int(value) if integer else value - - -def _text(value, label): - if not isinstance(value, str) or not value.strip() or len(value) > 4096: - raise ValueError(f"{label}: expected a nonempty string") - return value - - -def _near(actual, expected, label, tolerance=1e-8): - if not math.isclose(actual, expected, rel_tol=1e-10, abs_tol=tolerance): - raise ValueError(f"{label}: does not match the declared timing or projection") - - -def _vector(value, label): - if not isinstance(value, list) or len(value) != 3: - raise ValueError(f"{label}: expected three coordinates") - for component in value: - _number(component, label, -100001, 100001) - return value - - -def _dot(a, b): - return sum(x * y for x, y in zip(a, b)) - - -def _cross(a, b): - return [a[1]*b[2]-a[2]*b[1], a[2]*b[0]-a[0]*b[2], a[0]*b[1]-a[1]*b[0]] - - -def _frame_at(seconds, rate): - value = seconds * rate - return (round(value) if abs(value - round(value)) < 1e-9 else math.ceil(value)) + 1 - - -def validate_manifest(data): - """Validate the complete data before importing bpy or mutating a scene.""" - if not isinstance(data, dict) or data.get("schema") != SCHEMA: - raise ValueError("Unsupported GEV camera manifest schema") - source = data["source"] - _text(source["sceneId"], "scene ID") - if source.get("sampling") != "director-seek-authored-timing": - raise ValueError("Unsupported camera sampling semantics") - coordinates = data["coordinates"] - required = {"units": "meters", "axes": "east-north-up", "heightDatum": "WGS84-ellipsoid", "cameraAxes": "X-right,Y-up,-Z-forward"} - if any(coordinates.get(key) != value for key, value in required.items()): - raise ValueError("Explicit ENU meters, WGS84 ellipsoid and Blender camera axes required") - origin = coordinates["origin"] - for key, low, high in [("lat", -90, 90), ("lon", -180, 180), ("height", -12000, 1e9)]: - _number(origin[key], f"origin.{key}", low, high) - timeline = data["timeline"] - fps = timeline["fps"] - for key in ["numerator", "denominator"]: - _number(fps[key], f"fps.{key}", 1, 1000000, integer=True) - rate = _number(fps["numerator"] / fps["denominator"], "fps", 1, 240) - for key in ["width", "height"]: - _number(timeline[key], key, 4, 16384, integer=True) - if timeline["pixelAspect"] != [1, 1] or any(isinstance(value, bool) for value in timeline["pixelAspect"]): - raise ValueError("Only square pixels are supported") - if timeline["frameStart"] != 1 or isinstance(timeline["frameStart"], bool): - raise ValueError("Timeline must start at frame 1") - count = _number(timeline["frameEnd"], "frameEnd", 1, MAX_FRAMES, integer=True) - _number(timeline["durationSec"], "durationSec", 0, 100000) - if count != _frame_at(timeline["durationSec"], rate) - 1: - raise ValueError("Frame count differs from declared duration and fps") - camera = data["camera"] - if camera["projection"] != "perspective" or camera["sensorFit"] != "HORIZONTAL": - raise ValueError("Only a perspective horizontal-sensor camera is supported") - sensor = _number(camera["sensorWidthMm"], "sensorWidthMm", 1, 100) - hfov = _number(camera["horizontalFovRadians"], "horizontalFovRadians", math.pi/180, math.pi*179/180) - lens = _number(camera["lensMm"], "lensMm", 1, 10000) - _near(lens, sensor / (2 * math.tan(hfov / 2)), "lens") - _near(_number(camera["verticalFovRadians"], "verticalFovRadians", 0, math.pi), 2 * math.atan(math.tan(hfov / 2) * timeline["height"] / timeline["width"]), "vertical FOV") - shots = data["shots"] - if not isinstance(shots, list) or not 1 <= len(shots) <= count: - raise ValueError("Expected bounded nonempty shots") - ids = set() - elapsed = 0 - rounding = 0 - for shot in shots: - shot_id = _text(shot["id"], "shot ID") - if shot_id in ids: - raise ValueError("Duplicate shot ID") - ids.add(shot_id) - for key in ["startTimeSec", "endTimeSec", "durationSec", "holdSec"]: - _number(shot[key], key, 0, 100000) - if shot["durationSec"] <= 0: - raise ValueError("Shot duration must be positive") - _near(shot["startTimeSec"], elapsed, "shot start") - increment = shot["durationSec"] + shot["holdSec"] - rounding - next_time = elapsed + increment - rounding = next_time - elapsed - increment - elapsed = next_time - _near(shot["endTimeSec"], elapsed, "shot end") - for key, expected in [("frameStart", _frame_at(shot["startTimeSec"], rate)), ("frameEndExclusive", _frame_at(elapsed, rate))]: - _number(shot[key], key, 1, count + 1, integer=True) - if shot[key] != expected: - raise ValueError("Shot frame boundaries do not match timing") - if shot["frameStart"] >= shot["frameEndExclusive"]: - raise ValueError("Shot has no sampled frames") - _near(elapsed, timeline["durationSec"], "total duration") - frames = data["frames"] - if not isinstance(frames, list) or len(frames) != count: - raise ValueError("Frame count differs from frame samples") - shot_index = 0 - for index, sample in enumerate(frames, start=1): - if sample["frame"] != index or isinstance(sample["frame"], bool): - raise ValueError("Frames must be sequential integers starting at 1") - _near(_number(sample["timeSec"], "timeSec", 0, 100000), (index - 1) * fps["denominator"] / fps["numerator"], "sample time") - while index >= shots[shot_index]["frameEndExclusive"] and shot_index < len(shots) - 1: - shot_index += 1 - if sample["shotId"] != shots[shot_index]["id"]: - raise ValueError("Sample references the wrong shot") - location = _vector(sample["position"], "position") - if _dot(location, location) > 100000**2 + 0.01: - raise ValueError("Camera exceeds 100 km local-origin limit") - basis = sample["basisColumns"] - if not isinstance(basis, list) or len(basis) != 3: - raise ValueError("Expected three camera basis columns") - x, y, z = [_vector(column, "basis") for column in basis] - for column in [x, y, z]: - _near(_dot(column, column), 1, "unit camera axis", 1e-6) - for a, b in [(x, y), (y, z), (z, x)]: - _near(_dot(a, b), 0, "orthogonal camera axes", 1e-6) - _near(_dot(_cross(x, y), z), 1, "right-handed camera basis", 1e-6) - return data - - -def read_manifest(path): - """Read bounded JSON only. No imports, URLs or expressions are evaluated.""" - with Path(path).open("rb") as stream: - payload = stream.read(MAX_BYTES + 1) - if len(payload) > MAX_BYTES: - raise ValueError("Camera manifest exceeds 64 MiB") - return validate_manifest(json.loads(payload)) - - -def _camera_curves(camera): - """Read this camera's curves from current slotted or older legacy actions.""" - action = camera.animation_data.action - if hasattr(action, "layers") and action.layers: - for layer in action.layers: - for strip in layer.strips: - bag = strip.channelbag(camera.animation_data.action_slot) - if bag: - yield from bag.fcurves - else: - yield from action.fcurves - - -def _write_camera_keys(camera, samples): - """Allocate each F-Curve once, avoiding repeated insertion/handle updates.""" - first = samples[0] - camera.location = first[1] - camera.rotation_quaternion = first[2] - # Let Blender create the appropriate action/slot for its own API version. - camera.keyframe_insert(data_path="location", frame=first[0]) - camera.keyframe_insert(data_path="rotation_quaternion", frame=first[0]) - for curve in _camera_curves(camera): - channel = 1 if curve.data_path == "location" else 2 - component = curve.array_index - coordinates = [value for frame, location, rotation in samples - for value in (frame, (location if channel == 1 else rotation)[component])] - points = curve.keyframe_points - points.clear() - points.add(len(samples)) - points.foreach_set("co", coordinates) - # Keep the exact sampled motion, rather than Blender's default Bezier. - for key in points: - key.interpolation = "LINEAR" - curve.update() - - -def import_manifest(data): - """Create a new scene with editable per-shot cameras; preserve existing scenes.""" - validate_manifest(data) - import bpy - from mathutils import Matrix - - scene = bpy.data.scenes.new(f"GEV {data['source'].get('sceneTitle') or data['source']['sceneId']}") - scene.unit_settings.system = "METRIC" - scene.unit_settings.scale_length = 1.0 - timeline = data["timeline"] - rate = timeline["fps"]["numerator"] / timeline["fps"]["denominator"] - scene.render.fps = round(rate) - scene.render.fps_base = round(rate) / rate - scene.render.resolution_x = int(timeline["width"]) - scene.render.resolution_y = int(timeline["height"]) - scene.render.resolution_percentage = 100 - scene.render.pixel_aspect_x = scene.render.pixel_aspect_y = 1.0 - scene.frame_start = 1 - scene.frame_end = int(timeline["frameEnd"]) - scene["gev_schema"] = SCHEMA - scene["gev_source"] = json.dumps(data["source"], ensure_ascii=False) - scene["gev_coordinates"] = json.dumps(data["coordinates"], ensure_ascii=False) - scene["gev_timeline"] = json.dumps(timeline) - root = bpy.data.objects.new("GEV ENU origin", None) - scene.collection.objects.link(root) - cameras = {} - for shot in data["shots"]: - camera_data = bpy.data.cameras.new(f"GEV {shot['id']}") - camera_data.type = "PERSP" - camera_data.sensor_fit = "HORIZONTAL" - camera_data.sensor_width = data["camera"]["sensorWidthMm"] - camera_data.lens = data["camera"]["lensMm"] - camera_data.clip_start = 0.01 - camera_data.clip_end = 200000 - camera = bpy.data.objects.new(f"GEV {shot['id']}", camera_data) - camera.rotation_mode = "QUATERNION" - camera.parent = root - camera["gev_shot"] = json.dumps(shot, ensure_ascii=False) - camera["gev_scene_id"] = data["source"]["sceneId"] - scene.collection.objects.link(camera) - cameras[shot["id"]] = camera - marker = scene.timeline_markers.new(f"GEV {shot['id']}", frame=int(shot["frameStart"])) - marker.camera = camera - previous = {} - keys = {shot_id: [] for shot_id in cameras} - for sample in data["frames"]: - # Manifest vectors are columns, while mathutils.Matrix accepts rows. - basis = Matrix(sample["basisColumns"]).transposed() - rotation = basis.to_quaternion().normalized() - old = previous.get(sample["shotId"]) - if old is not None and rotation.dot(old) < 0: - rotation.negate() - previous[sample["shotId"]] = rotation.copy() - keys[sample["shotId"]].append((sample["frame"], sample["position"], tuple(rotation))) - for shot_id, camera in cameras.items(): - _write_camera_keys(camera, keys[shot_id]) - scene.camera = cameras[data["shots"][0]["id"]] - if bpy.context.window: - bpy.context.window.scene = scene - scene.frame_set(1) - return scene - - -def import_file(path): - """Import a camera JSON file into a new Blender scene without rendering.""" - return import_manifest(read_manifest(path)) - - -def new_blend_output(path): - """Require Blender's final extension before checking overwrite protection.""" - output = Path(path).resolve() - if output.suffix != '.blend': - raise ValueError('Output must end in lowercase .blend') - if output.exists(): - raise FileExistsError('Output already exists; choose a new .blend path') - return output - - -if __name__ == "__main__": - args = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else [] - if len(args) != 2: - raise SystemExit("Usage: blender --background --factory-startup --disable-autoexec --threads 1 --python camera_import.py -- camera.json output.blend") - output = new_blend_output(args[1]) - import_file(args[0]) - import bpy - preview = bpy.context.preferences.filepaths.file_preview_type - try: - bpy.context.preferences.filepaths.file_preview_type = 'NONE' - bpy.ops.wm.save_as_mainfile(filepath=str(output.resolve()), check_existing=False) - finally: - bpy.context.preferences.filepaths.file_preview_type = preview - print("CAMERA_IMPORT_OK") diff --git a/tools/blender/check_import.py b/tools/blender/check_import.py deleted file mode 100644 index 1026965b44..0000000000 --- a/tools/blender/check_import.py +++ /dev/null @@ -1,147 +0,0 @@ -"""Synthetic CPU-only Blender import, projection and .blend round-trip check. - -blender --background --factory-startup --disable-autoexec --threads 1 - --python tools/blender/check_import.py -- fixture-directory -No renderer or GPU context is requested. All landmarks are synthetic empties. -""" -import importlib.util -import json -from pathlib import Path -import sys - -import bpy -from bpy_extras.object_utils import world_to_camera_view -from mathutils import Vector - -spec = importlib.util.spec_from_file_location("camera_import", Path(__file__).with_name("camera_import.py")) -importer = importlib.util.module_from_spec(spec) -spec.loader.exec_module(importer) -args = sys.argv[sys.argv.index("--") + 1:] -if len(args) != 1: - raise SystemExit("Expected one fixture directory") -directory = Path(args[0]) -reference = json.loads((directory / "projection-reference.json").read_text()) -original_names = set(bpy.data.scenes.keys()) -original_settings = {scene.name: (scene.render.resolution_x, scene.render.resolution_y, scene.frame_end) for scene in bpy.data.scenes} -bpy.context.preferences.filepaths.file_preview_type = 'NONE' - - -def block(scene, name, center, size): - """Tiny owned synthetic blockout, so the saved rig has an editable set.""" - x, y, z = center - sx, sy, sz = [value / 2 for value in size] - vertices = [(x+dx*sx, y+dy*sy, z+dz*sz) for dx, dy, dz in [(-1,-1,-1),(1,-1,-1),(1,1,-1),(-1,1,-1),(-1,-1,1),(1,-1,1),(1,1,1),(-1,1,1)]] - faces = [(0,3,2,1),(4,5,6,7),(0,1,5,4),(1,2,6,5),(2,3,7,6),(3,0,4,7)] - mesh = bpy.data.meshes.new(name) - mesh.from_pydata(vertices, [], faces) - mesh.update() - obj = bpy.data.objects.new(name, mesh) - scene.collection.objects.link(obj) - - -cases = [] -for case in reference["cases"]: - manifest = importer.read_manifest(directory / case["manifest"]) - scene = importer.import_manifest(manifest) - # All validation occurs before bpy mutation. - malformed = json.loads(json.dumps(manifest)) - malformed["frames"][-1]["basisColumns"][0] = [2, 0, 0] - names = set(bpy.data.scenes.keys()) - objects = set(bpy.data.objects.keys()) - try: - importer.import_manifest(malformed) - raise AssertionError("Malformed transform was accepted") - except ValueError: - assert set(bpy.data.scenes.keys()) == names - assert set(bpy.data.objects.keys()) == objects - for index, point in enumerate(case["checks"][0]["points"]): - landmark = bpy.data.objects.new(f"Synthetic landmark {index}", None) - landmark.location = point["position"] - scene.collection.objects.link(landmark) - block(scene, 'Synthetic ground, no map data', [0, 0, -1], [1400, 1400, 2]) - for index in [0, 6, 9]: - sample = manifest['frames'][index] - point = case['checks'][index]['points'][0]['position'] - direction = [(point[i]-sample['position'][i])/100 for i in range(3)] - distance = -sample['position'][2]/direction[2] - center = [sample['position'][i]+direction[i]*distance for i in range(2)] + [10] - block(scene, f'Synthetic block {index}', center, [24, 24, 20]) - cases.append((case, manifest, scene.name)) - -# JSON may spell an integer-valued number as 1920.0. Blender RNA requires ints. -float_case = dict(reference['cases'][0], name='integer-valued JSON floats') -float_manifest = importer.read_manifest(directory / float_case['manifest']) -for key in ['width', 'height', 'frameEnd']: - float_manifest['timeline'][key] = float(float_manifest['timeline'][key]) -for shot in float_manifest['shots']: - shot['frameStart'] = float(shot['frameStart']) -float_scene = importer.import_manifest(float_manifest) -cases.append((float_case, float_manifest, float_scene.name)) - - -def check_all(): - max_error = 0.0 - projection_count = 0 - for case, manifest, scene_name in cases: - scene = bpy.data.scenes[scene_name] - bpy.context.window.scene = scene - bpy.context.view_layer.update() - metadata = json.loads(scene["gev_source"]) - assert metadata["sceneId"] == manifest["source"]["sceneId"] - assert json.loads(scene["gev_coordinates"]) == manifest["coordinates"] - assert json.loads(scene["gev_timeline"]) == manifest["timeline"] - assert scene.frame_start == 1 and scene.frame_end == len(manifest["frames"]) - expected_rate = manifest["timeline"]["fps"]["numerator"] / manifest["timeline"]["fps"]["denominator"] - assert abs(scene.render.fps / scene.render.fps_base - expected_rate) < 2e-6 - assert scene.unit_settings.scale_length == 1 - assert scene.render.resolution_x == manifest["timeline"]["width"] - assert scene.render.resolution_y == manifest["timeline"]["height"] - cameras = {json.loads(obj["gev_shot"])["id"]: obj for obj in scene.objects if "gev_shot" in obj} - assert set(cameras) == {shot["id"] for shot in manifest["shots"]} - for shot in manifest["shots"]: - camera = cameras[shot["id"]] - assert json.loads(camera["gev_shot"]) == shot - expected_frames = [sample["frame"] for sample in manifest["frames"] if sample["shotId"] == shot["id"]] - curves = list(importer._camera_curves(camera)) - assert len(curves) == 7, "Expected three location and four quaternion channels" - for curve in curves: - assert [key.co[0] for key in curve.keyframe_points] == expected_frames - assert all(key.interpolation == "LINEAR" for key in curve.keyframe_points) - for item in case["checks"]: - scene.frame_set(item["frame"]) - active = scene.camera - camera = cameras[item["shotId"]] - assert active == camera, "Timeline marker selected the wrong camera" - assert camera.data.sensor_fit == "HORIZONTAL" - assert abs(camera.data.lens - manifest["camera"]["lensMm"]) < 1e-5 - for point in item["points"]: - projected = world_to_camera_view(scene, camera, Vector(point["position"])) - assert projected.z > 0, (case['name'], item['frame'], 'landmark behind camera') - error = max(abs(projected.x - point["uv"][0]), abs(projected.y - point["uv"][1])) - max_error = max(error, max_error) - assert error < 2e-5, (case["name"], item["frame"], error) - projection_count += 1 - for name in original_names: - scene = bpy.data.scenes[name] - assert (scene.render.resolution_x, scene.render.resolution_y, scene.frame_end) == original_settings[name] - return max_error, projection_count - - -before_error, count = check_all() -blend = directory / "synthetic-cameras.blend" -if blend.exists(): - raise SystemExit("Synthetic output already exists; choose a fresh fixture directory") -bpy.context.window.scene = bpy.data.scenes[cases[0][2]] -bpy.context.scene.frame_set(1) -for area in bpy.context.screen.areas: - if area.type == 'VIEW_3D': - area.spaces.active.region_3d.view_perspective = 'CAMERA' -bpy.ops.wm.save_as_mainfile(filepath=str(blend.resolve()), check_existing=False) -assert blend.stat().st_size > 10000 -bpy.ops.wm.open_mainfile(filepath=str(blend.resolve()), load_ui=False, use_scripts=False) -assert bpy.context.scene.name == cases[0][2], 'Demo must reopen on the blockout scene' -after_error, after_count = check_all() -assert after_count == count -receipt = {"state": "BLENDER_CAMERA_PROJECTION_OK", "blenderVersion": bpy.app.version_string, "cases": len(cases), "projectionsBeforeSave": count, "projectionsAfterReload": after_count, "maxUvError": max(before_error, after_error), "rendered": False, "gpuRequested": False, "blend": blend.name} -(directory / "blender-receipt.json").write_text(json.dumps(receipt, indent=2) + "\n") -print(json.dumps(receipt)) diff --git a/tools/blender/make_fixture.mjs b/tools/blender/make_fixture.mjs deleted file mode 100644 index 0eab273670..0000000000 --- a/tools/blender/make_fixture.mjs +++ /dev/null @@ -1,173 +0,0 @@ -#!/usr/bin/env node -/** Generate tiny, provider-free fixtures plus an independent Cesium projection oracle. */ -import { mkdir, writeFile } from 'node:fs/promises'; -import { resolve } from 'node:path'; -import { parseArgs } from 'node:util'; -import * as C from 'cesium'; -import { exportCameraManifest } from '../../src/tooling/blenderCamera.js'; -import { sceneSeekState } from '../../src/director/timeline.js'; - -const { values } = parseArgs({ options: { output: { type: 'string' } } }); -if (!values.output) - throw new Error( - 'Usage: node tools/blender/make_fixture.mjs --output directory', - ); -const output = resolve(values.output); -await mkdir(output, { recursive: true }); -const pose = (values) => ({ - lat: 39.7003, - lon: -105.0004, - alt: 1750, - heading: 20, - pitch: -25, - roll: 17, - altitudeReference: 'ellipsoid', - ...values, -}); -const finish = pose({ - lat: 39.7005, - lon: -104.9995, - alt: 1800, - heading: 95, - pitch: -40, - roll: -25, -}); -const cut = pose({ - lat: 39.6998, - lon: -105.0003, - alt: 1725, - heading: 230, - pitch: -15, - roll: 35, -}); -const document = { - version: 6, - scenes: [ - { - id: 'synthetic-scene', - title: 'Synthetic camera bridge', - shots: [ - { - id: 'rolled-move', - title: 'Move and hold', - durationSec: 0.2, - holdSec: 0.1, - camera: finish, - move: { from: pose({}), easing: 'cubic-in-out' }, - }, - { - id: 'cut', - title: 'Explicit cut and hold', - durationSec: 0.2, - holdSec: 0.1, - camera: cut, - move: { from: cut, easing: 'linear' }, - }, - ], - }, - ], -}; -const origin = { lat: 39.7, lon: -105, height: 1600 }; -const anchor = C.Cartesian3.fromDegrees(origin.lon, origin.lat, origin.height); -const worldToLocal = C.Matrix4.inverseTransformation( - C.Transforms.eastNorthUpToFixedFrame(anchor), - new C.Matrix4(), -); -const cases = []; -for (const [name, width, height] of [ - ['landscape', 1920, 1080], - ['portrait', 1080, 1920], -]) { - const manifest = exportCameraManifest(document, { - origin, - fps: { numerator: 30000, denominator: 1001 }, - width, - height, - horizontalFovDegrees: 70, - }); - await writeFile( - resolve(output, `${name}.camera.json`), - JSON.stringify(manifest, null, 2) + '\n', - ); - const camera = new C.Camera({ - drawingBufferWidth: width, - drawingBufferHeight: height, - mapProjection: new C.GeographicProjection(), - mode: C.SceneMode.SCENE3D, - }); - camera.frustum.aspectRatio = width / height; - camera.frustum.fov = - width >= height - ? manifest.camera.horizontalFovRadians - : manifest.camera.verticalFovRadians; - camera.frustum.near = 0.01; - camera.frustum.far = 200000; - const checks = []; - for (const sample of manifest.frames) { - const state = sceneSeekState( - document.scenes[0], - sample.timeSec / manifest.timeline.durationSec, - (_scene, shot) => shot.durationSec + shot.holdSec, - (_scene, shot) => shot.holdSec, - ); - const p = state.camera; - camera.setView({ - destination: C.Cartesian3.fromDegrees(p.lon, p.lat, p.alt), - orientation: { - heading: C.Math.toRadians(p.heading), - pitch: C.Math.toRadians(p.pitch), - roll: C.Math.toRadians(p.roll), - }, - }); - const projectionView = C.Matrix4.multiply( - camera.frustum.projectionMatrix, - camera.viewMatrix, - new C.Matrix4(), - ); - const points = []; - for (const [right, up] of [ - [0, 0], - [25, 0], - [-25, 15], - [0, -20], - ]) { - const world = C.Cartesian3.clone(camera.positionWC); - for (const [axis, distance] of [ - [camera.directionWC, 100], - [camera.rightWC, right], - [camera.upWC, up], - ]) { - C.Cartesian3.add( - world, - C.Cartesian3.multiplyByScalar(axis, distance, new C.Cartesian3()), - world, - ); - } - const clip = C.Matrix4.multiplyByVector( - projectionView, - new C.Cartesian4(world.x, world.y, world.z, 1), - new C.Cartesian4(), - ); - const local = C.Matrix4.multiplyByPoint( - worldToLocal, - world, - new C.Cartesian3(), - ); - points.push({ - position: [local.x, local.y, local.z], - uv: [(clip.x / clip.w + 1) / 2, (clip.y / clip.w + 1) / 2], - }); - } - checks.push({ frame: sample.frame, shotId: sample.shotId, points }); - } - cases.push({ name, manifest: `${name}.camera.json`, checks }); -} -await writeFile( - resolve(output, 'scene.json'), - JSON.stringify(document, null, 2) + '\n', -); -await writeFile( - resolve(output, 'projection-reference.json'), - JSON.stringify({ origin, cases }, null, 2) + '\n', -); -console.log('CAMERA_FIXTURE_OK'); diff --git a/tools/blender/test_camera_import.py b/tools/blender/test_camera_import.py deleted file mode 100644 index 2f2b262dea..0000000000 --- a/tools/blender/test_camera_import.py +++ /dev/null @@ -1,91 +0,0 @@ -"""Data validation checks. Standard Python only; no Blender or rendering required.""" -import copy -import importlib.util -import math -from pathlib import Path -import sys -import tempfile -import unittest - -module_path = Path(__file__).with_name("camera_import.py") -if module_path.exists(): - spec = importlib.util.spec_from_file_location("camera_import", module_path) - importer = importlib.util.module_from_spec(spec) - spec.loader.exec_module(importer) -else: - importer = None - - -def fixture(): - return { - "schema": "gev.camera-manifest.v1", - "source": {"sceneId": "scene", "sceneTitle": "Fixture", "sampling": "director-seek-authored-timing", "attributions": []}, - "coordinates": {"units": "meters", "axes": "east-north-up", "heightDatum": "WGS84-ellipsoid", "origin": {"lat": 0, "lon": 0, "height": 0}, "cameraAxes": "X-right,Y-up,-Z-forward"}, - "camera": {"projection": "perspective", "sensorFit": "HORIZONTAL", "sensorWidthMm": 36, "lensMm": 18, "horizontalFovRadians": math.pi / 2, "verticalFovRadians": math.pi / 2}, - "timeline": {"fps": {"numerator": 30, "denominator": 1}, "width": 100, "height": 100, "pixelAspect": [1, 1], "frameStart": 1, "frameEnd": 1, "durationSec": 1 / 30}, - "shots": [{"id": "north", "title": "North", "startTimeSec": 0, "endTimeSec": 1 / 30, "durationSec": 1 / 30, "holdSec": 0, "frameStart": 1, "frameEndExclusive": 2}], - "frames": [{"frame": 1, "timeSec": 0, "shotId": "north", "position": [0, 0, 0], "basisColumns": [[1, 0, 0], [0, 0, 1], [0, -1, 0]]}], - } - - -class ValidationTests(unittest.TestCase): - def test_validator_exists(self): - self.assertIsNotNone(importer, "camera importer is missing") - - def test_valid_manifest_is_not_mutated_and_does_not_import_bpy(self): - data = fixture() - before = copy.deepcopy(data) - importer.validate_manifest(data) - self.assertEqual(data, before) - self.assertNotIn("bpy", sys.modules) - - def test_rejects_datum_axes_lens_fps_and_timing_mismatches(self): - mutations = [ - lambda m: m.update(schema="other"), - lambda m: m["coordinates"].update(heightDatum="MSL"), - lambda m: m["coordinates"].update(axes="north-east-down"), - lambda m: m["camera"].update(lensMm=35), - lambda m: m["camera"].update(lensMm=0.5), - lambda m: m["camera"].update(verticalFovRadians=1), - lambda m: m["timeline"]["fps"].update(denominator=0), - lambda m: m["timeline"].update(frameEnd=2), - lambda m: m["timeline"].update(width=1), - lambda m: m["timeline"].update(pixelAspect=[2, 1]), - lambda m: m["frames"][0].update(frame=2), - lambda m: m["frames"][0].update(timeSec=1), - lambda m: m["frames"][0].update(shotId="missing"), - lambda m: m["shots"][0].update(frameStart=2), - lambda m: m["shots"][0].update(endTimeSec=2), - lambda m: m["frames"][0].update(position=[100001, 0, 0]), - lambda m: m["frames"][0].update(position=[False, 0, 0]), - lambda m: m["frames"][0].update(position=[math.nan, 0, 0]), - lambda m: m["frames"][0].update(basisColumns=[[1, 0, 0], [1, 0, 0], [0, 0, 1]]), - lambda m: m["frames"][0].update(basisColumns=[[-1, 0, 0], [0, 0, 1], [0, -1, 0]]), - ] - for mutate in mutations: - data = fixture() - mutate(data) - with self.subTest(mutation=mutations.index(mutate)): - with self.assertRaises((ValueError, TypeError, KeyError)): - importer.validate_manifest(data) - - def test_output_extension_is_checked_before_existing_file_guard(self): - with tempfile.TemporaryDirectory(prefix='gev-blender-output-') as directory: - output = Path(directory) / 'camera.blend' - output.write_bytes(b'existing file must survive') - with self.assertRaises(ValueError): - importer.new_blend_output(Path(directory) / 'camera') - with self.assertRaises(FileExistsError): - importer.new_blend_output(output) - with self.assertRaises(ValueError): - importer.new_blend_output(Path(directory) / 'new.BLEND') - self.assertEqual(output.read_bytes(), b'existing file must survive') - self.assertEqual(importer.new_blend_output(Path(directory) / 'new.blend').name, 'new.blend') - - -if __name__ == "__main__": - result = unittest.main(exit=False) - if result.result.wasSuccessful(): - print("IMPORT_VALIDATION_OK") - else: - sys.exit(1) diff --git a/tools/export-blender-camera.mjs b/tools/export-blender-camera.mjs index d0e13c2f1f..e482aa52e5 100644 --- a/tools/export-blender-camera.mjs +++ b/tools/export-blender-camera.mjs @@ -1,12 +1,12 @@ #!/usr/bin/env node -/** Offline scene-to-camera manifest CLI. Reads JSON only; never loads .env or a viewer. */ +/** Offline scene-to-USD camera CLI. Reads JSON only; never loads .env or a viewer. */ import { readFile, writeFile, stat } from 'node:fs/promises'; import { parseArgs } from 'node:util'; import { parseSceneDocument, SCENE_DOCUMENT_LIMITS, } from '../src/director/document.js'; -import { exportCameraManifest } from '../src/tooling/blenderCamera.js'; +import { exportCameraUsda } from '../src/tooling/blenderCamera.js'; try { const { values } = parseArgs({ @@ -25,7 +25,7 @@ try { }); if (values.help) { console.log( - 'Usage: node tools/export-blender-camera.mjs --input scene.json --output camera.json --origin lat,lon,ellipsoidHeight --fps 30 (or 30000/1001) --width 1920 --height 1080 --horizontal-fov-deg 60 [--scene id] [--sensor-width-mm 36]', + 'Usage: node tools/export-blender-camera.mjs --input scene.json --output cameras.usda --origin lat,lon,ellipsoidHeight --fps 30 (or 30000/1001) --width 1920 --height 1080 --horizontal-fov-deg 60 [--scene id] [--sensor-width-mm 36]', ); } else { for (const key of [ @@ -39,6 +39,8 @@ try { ]) { if (!values[key]?.trim()) throw new Error(`Missing --${key}; use --help`); } + if (!values.output.endsWith('.usda')) + throw new Error('output must be a new file ending in .usda'); if (!/^\d+(?:\/\d+)?$/.test(values.fps)) throw new Error('fps must be an integer or integer ratio'); const originParts = values.origin.split(','); @@ -49,7 +51,7 @@ try { const document = parseSceneDocument(await readFile(values.input, 'utf8')); const [numerator, denominator = 1] = values.fps.split('/').map(Number); const [lat, lon, height] = originParts.map(Number); - const manifest = exportCameraManifest(document, { + const { usda, samples } = exportCameraUsda(document, { sceneId: values.scene, origin: { lat, lon, height }, fps: { numerator, denominator }, @@ -58,12 +60,9 @@ try { horizontalFovDegrees: Number(values['horizontal-fov-deg']), sensorWidthMm: Number(values['sensor-width-mm']), }); - const json = JSON.stringify(manifest, null, 2) + '\n'; - if (Buffer.byteLength(json) > 64 * 1024 * 1024) - throw new Error('Camera manifest exceeds 64 MiB'); - await writeFile(values.output, json, { flag: 'wx' }); + await writeFile(values.output, usda, { flag: 'wx' }); console.log( - `CAMERA_EXPORT_OK: ${manifest.shots.length} shots, ${manifest.frames.length} frames`, + `CAMERA_EXPORT_OK: ${samples.shots.length} shots, ${samples.frames.length} frames`, ); } } catch (error) { From 235938e19b7ce6debc94581ada25192faa6dcd37 Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Thu, 19 Nov 2026 18:24:55 +0400 Subject: [PATCH 8/9] 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, { From 7db4bb35f773ffdb6e775287055e7b5cd3543c8c Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Fri, 20 Nov 2026 03:38:04 +0400 Subject: [PATCH 9/9] 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. --- docs/BLENDER-CAMERAS.md | 108 +++---- scripts/format-scope.json | 7 + src/scenes/shotPresentation.js | 20 +- src/tooling/blender-cut-time.test.mjs | 100 +++++++ src/tooling/blender-import-timing.test.mjs | 64 ++++ src/tooling/blender-legacy-numbers.test.mjs | 52 ++++ src/tooling/blenderCamera.js | 275 +++++++----------- src/tooling/blenderCamera.test.mjs | 227 ++++++++------- src/tooling/blenderCameraBom.test.mjs | 96 ++++++ src/tooling/blenderCameraFifoInput.test.mjs | 76 +++++ .../blenderCameraPartialWrite.test.mjs | 91 ++++++ src/tooling/blenderCameraStderr.test.mjs | 106 +++++++ tools/README.md | 23 +- tools/export-blender-camera.mjs | 36 ++- 14 files changed, 908 insertions(+), 373 deletions(-) create mode 100644 src/tooling/blender-cut-time.test.mjs create mode 100644 src/tooling/blender-import-timing.test.mjs create mode 100644 src/tooling/blender-legacy-numbers.test.mjs create mode 100644 src/tooling/blenderCameraBom.test.mjs create mode 100644 src/tooling/blenderCameraFifoInput.test.mjs create mode 100644 src/tooling/blenderCameraPartialWrite.test.mjs create mode 100644 src/tooling/blenderCameraStderr.test.mjs 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; }