feat: export Director cameras for Blender

This commit is contained in:
disco committed 2026-10-28 20:13:26 -06:00
1 parent f2c6ff082d
commit 9f32bf3d92
12 files changed
+1536 -1

No files matched your search

+3
View File
@@ -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__/
+124
View File
@@ -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.
+10
View File
@@ -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,
+3
View File
@@ -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",
+276
View File
@@ -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,
};
}
+367
View File
@@ -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);
});
+11 -1
View File
@@ -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).
+266
View File
@@ -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")
+140
View File
@@ -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))
+173
View File
@@ -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');
+91
View File
@@ -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)
+72
View File
@@ -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;
}