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; +}