Export Director cameras as a USD stage and use runtime shot timing

Address review on #1460:

- Replace the custom JSON manifest and the bpy importer with a plain-text
  .usda stage written from Node (no new dependency) that Blender imports
  natively: Z-up, metersPerUnit 1, one camera per shot with per-frame
  xformOp:transform samples, time codes equal to frame numbers, and lens
  attributes in tenths of a scene unit (Blender multiplies by
  100 * metersPerUnit).
- Take shot timing from shotRuntimeDurationSec/effectiveShotHoldSec, the
  functions Director playback and seeking use, so pack hold overrides,
  minimum holds and evidence-sequence durations match the app.
- Extract runtimeLayerStatesForShot in shotPresentation.js (behaviour
  unchanged) so holds for long scenes are resolved without quadratic work.
- Remove tools/blender Python files; update docs, tests and changelog.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01BahZiNcXqNSvAmR5TCuTAu
This commit is contained in:
UBN606andClaude Opus 5.5 committed 2026-11-03 19:34:33 +00:00
1 parent 6b60b9e969
commit 159c0cfcb0
14 files changed
+624 -865

No files matched your search

-3
View File
@@ -28,6 +28,3 @@ pinokio/.installed
# Transient: a release interrupted mid-assembly (npm run changelog recovers it)
changelog.d/.assembling/
# Optional Blender camera importer Python cache.
tools/blender/__pycache__/
@@ -1,3 +1,3 @@
- Export saved Director scenes to editable Blender cameras with a camera-only
offline manifest preserving ENU coordinates, lens and rational timing, plus
an importer and projection checks (UBN606, #1460).
- Export saved Director scenes as camera-only USD (`.usda`) stages that Blender
imports natively, with ENU meter coordinates, lens in USD units, rational fps
and the same runtime shot timing as Director playback (UBN606, #1460).
+87 -72
View File
@@ -1,9 +1,11 @@
# GEV cameras in Blender
Export one saved Director scene into a camera-only JSON manifest, then import
editable shot cameras into a new Blender scene. This offline path requires no
API key, browser, imagery, terrain, model provider or rendering. It does not
export any tiles or geometry. Use independently licensed assets for your set.
Export one saved Director scene as a camera-only USD stage (`.usda`, plain
text), then open it with Blender's built-in importer: **File > Import >
Universal Scene Description**. The exporter is a Node script with no new
dependency. This offline path requires no API key, browser, imagery, terrain,
model provider, rendering or Blender add-on. It does not export any tiles or
geometry. Use independently licensed assets for your set.
The source remains the existing Director scene document. This adapter adds no
new tour authoring format or playback UI. It complements the scripted-camera
@@ -15,12 +17,12 @@ Use the repository's supported Node runtime and installed dependencies. Save a
Director project as JSON, then run from the repository root:
```sh
node tools/export-blender-camera.mjs --input scene.json --output cameras.json --scene my-scene-id --origin 39.7,-105,1600 --fps 30000/1001 --width 1920 --height 1080 --horizontal-fov-deg 70
node tools/export-blender-camera.mjs --input scene.json --output cameras.usda --scene my-scene-id --origin 39.7,-105,1600 --fps 30000/1001 --width 1920 --height 1080 --horizontal-fov-deg 70
```
Quote paths containing spaces. Omit `--scene` only when the document contains
exactly one scene. Output must be a new file; the tool refuses to overwrite it.
No environment files are read.
exactly one scene. Output must be a new file ending in `.usda`; the tool
refuses to overwrite it. No environment files are read.
`--origin` is latitude, longitude and **WGS84 ellipsoid height in meters**.
Positions and sampled paths must remain within 100 km of that origin. Heights
@@ -41,91 +43,104 @@ with an effective rate from 1 to 240. Image dimensions are integers from 4 to
16384, pixels are square, horizontal FOV is 1 to 179 degrees and sensor width
is 1 to 100 mm. A lens shorter than Blender's 1 mm minimum is rejected.
Input is bounded to the existing 5 MiB scene-document limit; output is limited
to 100,000 frames and the CLI also enforces 64 MiB. Every shot needs at least
one sampled frame.
to 100,000 frames and 64 MiB. Every shot needs at least one sampled frame.
## Timing and camera semantics
Sampling uses GEV's Director **seek** interpolation and authored timing. Named
anchors and explicit `move.from` endpoints resolve through the existing camera
owner; explicit linear/cubic moves reuse its sampler. Ordinary shots use the
same cubic, shortest-angle interpolation as Director seeking from the previous
shot camera. The first ordinary shot starts at its own camera. A cut can be
authored as an explicit move with identical start/end poses.
Shot timing is the Director's **runtime** timing, not only the saved
`durationSec` and `holdSec`. Each shot's length and hold come from
`shotRuntimeDurationSec` and `effectiveShotHoldSec` in
`src/scenes/shotPresentation.js` with the installed default scene packs, the
same functions Director playback and seeking use. Registered pack hold
overrides, minimum holds and evidence-sequence durations therefore move later
shots exactly as they do in the app. Saved shots are never rewritten; each
camera records both the authored and the runtime hold.
Camera poses follow GEV's Director **seek** interpolation. Named anchors and
explicit `move.from` endpoints resolve through the existing camera owner;
explicit linear/cubic moves reuse its sampler. Ordinary shots use the same
cubic, shortest-angle interpolation as Director seeking from the previous shot
camera. The first ordinary shot starts at its own camera. A cut can be authored
as an explicit move with identical start/end poses. Unit tests compare every
exported sample with the Director's `sceneSeekState`.
The bridge does not reproduce Cesium's implicit live `flyTo` trajectory,
provider readiness, registered data-pack timing overrides, runtime layer holds,
layer-owned camera motion, lens changes, visual effects, media or geometry.
Export authored camera moves when repeatable playback framing is required.
This feature does not depend on GEV video export.
provider readiness, layer-owned camera motion, lens changes, visual effects,
media or geometry. Export authored camera moves when repeatable playback
framing is required. This feature does not depend on GEV video export.
Frame 1 samples time zero. Frame `n` samples `(n - 1) * denominator / numerator`
seconds. The final sample precedes the exclusive scene end; frame count is the
ceiling of duration times fps, with rounding noise at integer boundaries removed.
Shot ranges are half open: `frameStart <= frame < frameEndExclusive`. Fractional
shot boundaries switch at the first sampled time at or after the boundary.
Both authored seconds and sampled frame ranges are retained.
Shot ranges are half open: `frameStart <= frame < frameEndExclusive`. A shot
boundary switches at the first sampled time at or after the boundary.
## What the USD stage contains
- Stage metadata `upAxis = "Z"` and `metersPerUnit = 1`. Scene X/Y/Z are
east/north/up in meters around `--origin`, so Blender applies no axis or
unit conversion.
- USD time codes equal frame numbers: `startTimeCode = 1`, `endTimeCode` is the
last frame, and `timeCodesPerSecond`/`framesPerSecond` hold the effective
rate. The exact fps ratio is kept as text.
- A root `GEV` transform at identity, with one perspective `Camera` per shot
named `Shot_001_<id>`, `Shot_002_<id>` and so on. Each camera has an
`xformOp:transform` matrix time sample on every frame of its own shot range,
and holds its first or last pose outside that range. Camera local X points
right, local Y up and local -Z forward, which is both the USD and the Blender
camera convention.
- Lens attributes in USD's units: `focalLength`, `horizontalAperture` and
`verticalAperture` are in **tenths of a scene unit**, so with
`metersPerUnit = 1` one unit of these attributes is 100 mm. A 25 mm lens on
a 36 mm sensor is written as `focalLength = 0.25` and
`horizontalAperture = 0.36`. The vertical aperture is the sensor width times
`height / width`, so it matches the output aspect.
- Clipping range 0.01 m to 200 km; adjust it for your set if needed.
- Source scene and shot IDs, titles, pack identifiers, authored and runtime
timing, frame ranges, origin, fps ratio, image size and data-pack
attribution text, as `userProperties:` attributes and as JSON in the layer's
`customLayerData`. No referenced assets are fetched.
## Import into Blender
The importer is a standalone Python file using the standard library and
Blender's bundled Python API. Tested with Blender 5.2.2 LTS; other versions
need their own check before use.
1. In Blender, choose **File > Import > Universal Scene Description**, select
the `.usda` file and keep **Set Frame Range** enabled.
2. Set **Output Properties > Format** to the exported `--width`, `--height` and
frame rate. USD carries the time codes but not render resolution, and
Blender does not take its scene frame rate from the file.
3. Pick a shot camera as the active camera, or bind cameras to timeline markers
at each shot's `gevFrameStart` (shown under **Object Data Properties >
Custom Properties**).
```sh
blender --background --factory-startup --disable-autoexec --threads 1 --python-exit-code 1 --python tools/blender/camera_import.py -- cameras.json cameras.blend
```
How Blender maps the lens: its USD importer multiplies `focalLength` and the
apertures by `100 * metersPerUnit` to get millimeters. With this exporter's
`metersPerUnit = 1` that is ×100, so the imported **Focal Length** and
**Sensor Width** equal the `lensMm` and `--sensor-width-mm` values. Blender
chooses horizontal sensor fit when the horizontal aperture is the larger one
and vertical fit otherwise, so portrait exports import with vertical fit and the
same field of view. This mapping is in Blender's
`source/blender/io/usd/intern/usd_reader_camera.cc` and is the same in 4.2 LTS,
4.5, 5.0 and current `main`.
Both paths after `--` are required. Choose a new filename ending in lowercase
`.blend`; a missing or different extension is rejected before creating a scene. The importer
validates the entire manifest before changing Blender data and creates a new
scene, preserving existing scenes. It adds an identity ENU origin object,
one perspective camera per shot, sampled location/quaternion keyframes and
camera-bound timeline markers. Camera local X points right, local Y points up,
and local negative Z looks forward. Scene X/Y/Z are east/north/up, in meters.
Sensor fit is explicitly horizontal. Quaternion signs are kept continuous and
keyframe interpolation is linear between sampled frames.
Blender imports animated USD transforms as a **Transform Cache** constraint
that reads the `.usda` file, so keep the file next to the `.blend`, or select
the cameras and use **Object > Animation > Bake Action…** with **Visual
Keying** and **Clear Constraints** for a self-contained file. Blender stores object transforms in single precision;
within the 100 km origin limit this is millimeter-level at the edge and finer
closer to the origin.
Scene custom properties `gev_source`, `gev_coordinates` and `gev_timeline`
preserve geographic, attribution and rational-fps metadata. Camera custom
properties preserve source scene/shot IDs, titles, pack identifiers, endpoints
and authored timing. Source data-pack attributions are retained as text; no
referenced assets are fetched. The original fps ratio is preserved exactly in
metadata; Blender's `fps_base` is floating point, so its effective rate has a
small representation error. Cameras use a 0.01 m near plane and 200 km far
plane; adjust clipping for your separately authored set if needed.
For an existing Blender session, load this trusted module and call
`import_file(path)`; it also creates and selects a new scene. When writing your
own headless checks, activate that scene before evaluating its animation.
## Reproducible, provider-free check
Use a fresh output directory for each run. These commands create synthetic
camera data, run standard Python validation, import the actual cameras, compare
landmark projection to a separate Cesium Camera oracle, then save/reopen a
`.blend` and repeat. They do not render or launch a browser.
## Checks
```sh
node --test src/tooling/blenderCamera.test.mjs
python tools/blender/test_camera_import.py
node tools/blender/make_fixture.mjs --output output/blender-camera-check
blender --background --factory-startup --disable-autoexec --threads 1 --python-exit-code 1 --python tools/blender/check_import.py -- output/blender-camera-check
```
The check covers moving and held cameras, nonzero roll, scene-local tangent
frames, a cut, landscape/portrait projection, rational fps, source metadata,
timeline marker selection, rejected malformed input and preservation of existing
scenes. `blender-receipt.json` records measured projection error and Blender
version. A successful run prints `BLENDER_CAMERA_PROJECTION_OK`.
Camera keys are allocated in batches per animation channel. A synthetic
single-camera capacity check on Windows with Blender 5.2.2 LTS imported all
100,000 supported frames (700,000 location/quaternion keys) in 1.42 seconds,
saved in 0.19 seconds and reopened in 0.06 seconds. It checked every channel's
key count and linear interpolation, plus the first, middle and last camera
poses before saving and after reopening. These timings measure camera-data
import, without rendering.
These Node tests run in CI. They cover camera axes against an independent
Cesium Camera, ENU translation, landscape and portrait lenses, rational fps,
cuts, anchors and moves, runtime holds from registered packs (including the
Director's Mailung trim, which plays a 7.65 s hold where 15 s was saved), every
sample against `sceneSeekState`, the USD stage metadata, lens units and
per-frame matrices, CLI overwrite and extension refusals, and input limits.
Run the repository's normal unit, build, format and boundary checks too. The
contribution guide additionally requires live tracking/browser checks before
+8 -8
View File
@@ -647,14 +647,14 @@ untouched, and the shot is not rebuilt.
See [camera directions](DIRECTOR-CAMERA.md).
An opt-in offline [Blender camera bridge](BLENDER-CAMERAS.md) exports a saved
Director scene as ENU meter camera samples with an explicit WGS84 ellipsoid
origin, horizontal lens and rational fps. It reuses Director seek interpolation
and authored timing; runtime layer timing, implicit live flyTo paths, imagery
and geometry are outside this camera-only format. The Python importer creates
a separate editable scene with per-shot cameras and timeline markers.
The synthetic `tools/blender/check_import.py` check compares actual Blender
projection and saved-file reload against a separate Cesium Camera oracle
without rendering or provider access.
Director scene as a camera-only USD stage (`.usda`) that Blender imports
natively: Z-up meters in a local ENU frame around an explicit WGS84 ellipsoid
origin, one camera per shot with per-frame transforms, lens values in USD's
tenths of a scene unit and rational fps recorded alongside frame-number time
codes. It uses Director seek interpolation and the runtime shot timing from
`shotPresentation.js`, so registered pack holds, minimum holds and
evidence-sequence durations match playback. Implicit live flyTo paths, imagery
and geometry are outside this camera-only format.
Realtime voice composes separate connection, response/tool, Radio handoff, input
and audio-meter, cost, viewport-context and diagnostic owners. The existing
-1
View File
@@ -1,7 +1,6 @@
[
"src/tooling/blenderCamera.test.mjs",
"tools/export-blender-camera.mjs",
"tools/blender/make_fixture.mjs",
".prettierrc.json",
"package.json",
"scripts/format-scope.json",
+13 -3
View File
@@ -153,8 +153,8 @@ export function effectiveShotHoldSec(
);
}
/** Estimate flight plus effective hold without mutating saved layer parameters. */
export function shotRuntimeDurationSec(scene, shot, packs) {
/** Copy a shot's layer states with registered runtime controls, without mutating saved parameters. */
export function runtimeLayerStatesForShot(shot, packs) {
const states = deepClone(shot?.layers || {});
const sourceRecipe = packs.recipeForShot(shot);
for (const state of Object.values(states)) {
@@ -168,8 +168,18 @@ export function shotRuntimeDurationSec(scene, shot, packs) {
};
}
}
return states;
}
/** Estimate flight plus effective hold without mutating saved layer parameters. */
export function shotRuntimeDurationSec(scene, shot, packs) {
return (
(shot?.durationSec || DEFAULT_SHOT_DURATION_SEC) +
effectiveShotHoldSec(scene, shot, packs, states)
effectiveShotHoldSec(
scene,
shot,
packs,
runtimeLayerStatesForShot(shot, packs),
)
);
}
+249 -38
View File
@@ -1,4 +1,4 @@
/** Camera-only interchange. No viewer, providers, environment files or terrain access. */
/** Camera-only USD interchange. No viewer, providers, environment files or terrain access. */
import * as C from 'cesium';
import { validateSceneDocument } from '../director/document.js';
import {
@@ -7,9 +7,20 @@ import {
sampleCameraMove,
} from '../director/camera.js';
import { cameraAtProgress } from '../director/timeline.js';
import {
effectiveShotHoldSec,
runtimeLayerStatesForShot,
shotRuntimeDurationSec,
} from '../scenes/shotPresentation.js';
import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
export const CAMERA_MANIFEST_SCHEMA = 'gev.camera-manifest.v1';
export const CAMERA_USD_SCHEMA = 'gev.camera-usd.v1';
export const MAX_CAMERA_FRAMES = 100000;
export const MAX_CAMERA_USDA_BYTES = 64 * 1024 * 1024;
// USD camera lens attributes are tenths of a scene unit. With metersPerUnit = 1
// one tenth is 100 mm; Blender's importer multiplies by 100 * metersPerUnit.
const MM_PER_USD_LENS_UNIT = 100;
const clamp01 = (value) => Math.max(0, Math.min(1, value));
function number(value, label, min, max) {
if (
@@ -34,7 +45,8 @@ function position(pose, heightKey = 'alt') {
/** Convert Cesium's WGS84/heading-pitch-roll pose to a fixed Blender ENU frame.
* Angles are degrees; alt and origin.height are WGS84 ellipsoid meters.
* The returned columns are Blender's local X (right), Y (up), Z (back).
* The returned columns are the camera's local X (right), Y (up), Z (back),
* which is the USD and Blender camera convention (looking down local -Z).
*/
export function cameraPoseToEnu(pose, origin) {
position(pose);
@@ -105,11 +117,40 @@ function identity(value, label) {
return value;
}
/** Export one existing scene using Director seek interpolation and authored timing.
/** Resolve the flight-plus-hold seconds and holds that Director playback and seeking use.
* Both come from shotPresentation.js, so registered pack overrides, minimum holds and
* evidence-sequence durations match the app instead of the saved holdSec alone.
*/
export function sceneRuntimeTiming(
scene,
scenePacks = createDefaultScenePacks(),
) {
const byShot = new Map();
for (const shot of scene.shots) {
const durationSec = shotRuntimeDurationSec(scene, shot, scenePacks);
// Same states shotRuntimeDurationSec uses; omitting them would rebuild
// every shot's timing per call (quadratic for long scenes).
const holdSec = effectiveShotHoldSec(
scene,
shot,
scenePacks,
runtimeLayerStatesForShot(shot, scenePacks),
);
number(durationSec, `Shot ${shot.id} runtime duration`, 0, 1e7);
number(holdSec, `Shot ${shot.id} runtime hold`, 0, 1e7);
byShot.set(shot, { durationSec, holdSec });
}
return {
durationFor: (_scene, shot) => byShot.get(shot).durationSec,
holdFor: (_scene, shot) => byShot.get(shot).holdSec,
};
}
/** Sample one saved scene with Director seek interpolation and runtime playback timing.
* Projection is explicit because scene documents do not store viewport lenses.
* Frame 1 samples time zero; the final sample precedes the exclusive end time.
*/
export function exportCameraManifest(
export function sampleSceneCameras(
project,
{
sceneId,
@@ -119,6 +160,7 @@ export function exportCameraManifest(
height,
horizontalFovDegrees,
sensorWidthMm = 36,
scenePacks = createDefaultScenePacks(),
} = {},
) {
validateSceneDocument(project);
@@ -144,6 +186,7 @@ export function exportCameraManifest(
const scene = candidates[0];
identity(scene.id, 'Scene');
if (!scene.shots.length) throw new Error('Scene has no camera shots');
const timing = sceneRuntimeTiming(scene, scenePacks);
const frameAt = (seconds) => {
const frame = seconds * rate;
return (
@@ -154,6 +197,14 @@ export function exportCameraManifest(
};
let elapsed = 0;
let rounding = 0;
const resolved = scene.shots.map((shot, index) => ({
target: resolveCameraPose(scene, shot.camera),
previous: resolveCameraPose(
scene,
scene.shots[index - 1]?.camera || shot.camera,
),
move: resolveCameraMove(scene, shot),
}));
const shots = scene.shots.map((shot) => {
identity(shot.id, 'Shot');
const camera = resolveCameraPose(scene, shot.camera);
@@ -162,18 +213,13 @@ export function exportCameraManifest(
if (move) position(move.from);
cameraPoseToEnu(camera, origin);
if (move) cameraPoseToEnu(move.from, origin);
const durationSec = shot.durationSec || 4;
const holdSec = shot.holdSec || 0;
const runtimeDurationSec = timing.durationFor(scene, shot);
const startTimeSec = elapsed;
// Compensated summation prevents long decimal timelines gaining a frame.
const increment = durationSec + holdSec - rounding;
const increment = runtimeDurationSec - rounding;
const next = elapsed + increment;
rounding = next - elapsed - increment;
elapsed = next;
const frameStart = frameAt(startTimeSec);
const frameEndExclusive = frameAt(elapsed);
if (frameStart >= frameEndExclusive)
throw new Error(`Shot ${shot.id} has no sampled frame at this fps`);
return {
id: shot.id,
title: shot.title || '',
@@ -185,41 +231,56 @@ export function exportCameraManifest(
: {}),
startTimeSec,
endTimeSec: elapsed,
durationSec,
holdSec,
frameStart,
frameEndExclusive,
camera,
move,
flightDurationSec: shot.durationSec || 4,
authoredHoldSec: Number(shot.holdSec) || 0,
runtimeHoldSec: timing.holdFor(scene, shot),
frameStart: 0,
frameEndExclusive: 0,
};
});
const frameCount = frameAt(elapsed) - 1;
if (frameCount > MAX_CAMERA_FRAMES)
throw new RangeError(`Export exceeds ${MAX_CAMERA_FRAMES} camera frames`);
if (frameCount < 1) throw new Error('Scene has no sampled frame at this fps');
// Mirror sceneSeekState (src/director/timeline.js) step for step, walking
// shots forward once instead of rescanning every shot for every frame.
// Tests compare each sample with sceneSeekState itself.
const seekEnds = [];
for (const shot of scene.shots)
seekEnds.push((seekEnds.at(-1) || 0) + timing.durationFor(scene, shot));
const seekTotalSec = seekEnds.at(-1);
const frames = [];
let shotIndex = 0;
for (let frame = 1; frame <= frameCount; frame += 1) {
const timeSec = ((frame - 1) * fps.denominator) / fps.numerator;
const normalized = clamp01(timeSec / seekTotalSec);
while (
frame >= shots[shotIndex].frameEndExclusive &&
shotIndex < shots.length - 1
shotIndex < shots.length - 1 &&
!(normalized < seekEnds[shotIndex] / seekTotalSec)
)
shotIndex += 1;
const shot = shots[shotIndex];
const timeSec = ((frame - 1) * fps.denominator) / fps.numerator;
const progress = Math.max(
0,
Math.min(
1,
(timeSec - shot.startTimeSec) / Math.max(0.001, shot.durationSec),
),
const source = scene.shots[shotIndex];
const startElapsedSec = shotIndex ? seekEnds[shotIndex - 1] : 0;
const elapsedSec = Math.max(normalized * seekTotalSec, startElapsedSec);
const flightDurationSec = source.durationSec || 4;
const shotDurationSec = Math.max(
0.001,
flightDurationSec + timing.holdFor(scene, source),
);
const pose = shot.move
? sampleCameraMove(shot.move, progress)
: cameraAtProgress(
shots[shotIndex - 1]?.camera || shot.camera,
shot.camera,
progress,
);
const shotElapsedSec = Math.max(
0,
Math.min(shotDurationSec, elapsedSec - startElapsedSec),
);
const cameraProgress = clamp01(
shotElapsedSec / Math.max(0.001, flightDurationSec),
);
const { target, previous, move } = resolved[shotIndex];
const pose = move
? sampleCameraMove(move, cameraProgress)
: cameraAtProgress(previous, target, cameraProgress);
const shot = shots[shotIndex];
if (!shot.frameStart) shot.frameStart = frame;
shot.frameEndExclusive = frame + 1;
frames.push({
frame,
timeSec,
@@ -227,6 +288,10 @@ export function exportCameraManifest(
...cameraPoseToEnu(pose, origin),
});
}
for (const shot of shots) {
if (!shot.frameStart)
throw new Error(`Shot ${shot.id} has no sampled frame at this fps`);
}
const horizontalFovRadians = C.Math.toRadians(horizontalFovDegrees);
const lensMm = number(
sensorWidthMm / (2 * Math.tan(horizontalFovRadians / 2)),
@@ -235,12 +300,12 @@ export function exportCameraManifest(
10000,
);
return {
schema: CAMERA_MANIFEST_SCHEMA,
schema: CAMERA_USD_SCHEMA,
source: {
sceneId: scene.id,
sceneTitle: scene.title || '',
documentVersion: project.version ?? 1,
sampling: 'director-seek-authored-timing',
sampling: 'director-seek-runtime-timing',
attributions: (scene.dataPacks || []).map(({ attribution }) =>
structuredClone(attribution),
),
@@ -254,8 +319,8 @@ export function exportCameraManifest(
},
camera: {
projection: 'perspective',
sensorFit: 'HORIZONTAL',
sensorWidthMm,
sensorHeightMm: (sensorWidthMm * height) / width,
lensMm,
horizontalFovRadians,
verticalFovRadians:
@@ -274,3 +339,149 @@ export function exportCameraManifest(
frames,
};
}
/** Shortest decimal for a finite double, without signed zero or 17-digit noise. */
function usdNumber(value) {
const rounded = Number(value.toPrecision(15));
return Object.is(rounded, -0) ? '0' : String(rounded);
}
/** Quote text for a .usda string literal. */
function usdString(value) {
return `"${String(value)
.replace(/\\/g, '\\\\')
.replace(/"/g, '\\"')
.replace(/\n/g, '\\n')
.replace(/\r/g, '\\r')
.replace(/\t/g, '\\t')
.replace(
/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g,
(char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`,
)}"`;
}
/** USD prim names are identifiers; saved IDs stay in custom properties. */
function shotPrimName(shot, index) {
const safe = shot.id.replace(/[^A-Za-z0-9_]/g, '_').slice(0, 40);
return `Shot_${String(index + 1).padStart(3, '0')}_${safe}`;
}
/** USD matrices are row-vector: rows are camera X, Y, Z axes, then translation. */
function usdMatrix({ position: p, basisColumns: [right, up, back] }) {
const row = (values, w) => `(${[...values, w].map(usdNumber).join(', ')})`;
return `( ${row(right, 0)}, ${row(up, 0)}, ${row(back, 0)}, ${row(p, 1)} )`;
}
/** Write sampled cameras as a plain-text USD stage that Blender imports natively.
* Z-up meters, one perspective camera per shot, time codes equal to frame numbers.
*/
export function cameraSamplesToUsda(samples) {
const { source, coordinates, camera, timeline, shots, frames } = samples;
const rate = timeline.fps.numerator / timeline.fps.denominator;
const shotTable = shots.map(
({
id,
title,
sourcePackId,
sourcePackVersion,
startTimeSec,
endTimeSec,
flightDurationSec,
authoredHoldSec,
runtimeHoldSec,
frameStart,
frameEndExclusive,
}) => ({
id,
title,
...(sourcePackId ? { sourcePackId, sourcePackVersion } : {}),
startTimeSec,
endTimeSec,
flightDurationSec,
authoredHoldSec,
runtimeHoldSec,
frameStart,
frameEndExclusive,
}),
);
const json = (value) => usdString(JSON.stringify(value));
const out = [
'#usda 1.0',
'(',
' customLayerData = {',
` string gevCamera = ${json(camera)}`,
` string gevCoordinates = ${json(coordinates)}`,
` string gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`,
` string gevShots = ${json(shotTable)}`,
` string gevSource = ${json(source)}`,
` string gevTimeline = ${json(timeline)}`,
' }',
' defaultPrim = "GEV"',
` doc = ${usdString("God's Eye View Director cameras: ENU meters around a WGS84 ellipsoid origin; time codes are frame numbers.")}`,
` endTimeCode = ${timeline.frameEnd}`,
` framesPerSecond = ${rate}`,
' metersPerUnit = 1',
` startTimeCode = ${timeline.frameStart}`,
` timeCodesPerSecond = ${rate}`,
' upAxis = "Z"',
')',
'',
'def Xform "GEV"',
'{',
` custom string userProperties:gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`,
` custom string userProperties:gevSceneId = ${usdString(source.sceneId)}`,
` custom string userProperties:gevSceneTitle = ${usdString(source.sceneTitle)}`,
` custom string userProperties:gevOrigin = ${json(coordinates.origin)}`,
` custom string userProperties:gevFps = ${usdString(`${timeline.fps.numerator}/${timeline.fps.denominator}`)}`,
` custom int userProperties:gevWidth = ${timeline.width}`,
` custom int userProperties:gevHeight = ${timeline.height}`,
` custom string userProperties:gevAttributions = ${json(source.attributions)}`,
];
shots.forEach((shot, index) => {
out.push(
'',
` def Camera ${usdString(shotPrimName(shot, index))}`,
' {',
' float2 clippingRange = (0.01, 200000)',
` float focalLength = ${usdNumber(camera.lensMm / MM_PER_USD_LENS_UNIT)}`,
` float horizontalAperture = ${usdNumber(camera.sensorWidthMm / MM_PER_USD_LENS_UNIT)}`,
` float verticalAperture = ${usdNumber(camera.sensorHeightMm / MM_PER_USD_LENS_UNIT)}`,
' token projection = "perspective"',
` custom string userProperties:gevShotId = ${usdString(shot.id)}`,
` custom string userProperties:gevShotTitle = ${usdString(shot.title)}`,
...(shot.sourcePackId
? [
` custom string userProperties:gevSourcePackId = ${usdString(shot.sourcePackId)}`,
` custom string userProperties:gevSourcePackVersion = ${usdString(shot.sourcePackVersion ?? '')}`,
]
: []),
` custom int userProperties:gevFrameStart = ${shot.frameStart}`,
` custom int userProperties:gevFrameEndExclusive = ${shot.frameEndExclusive}`,
` custom double userProperties:gevStartTimeSec = ${usdNumber(shot.startTimeSec)}`,
` custom double userProperties:gevEndTimeSec = ${usdNumber(shot.endTimeSec)}`,
` custom double userProperties:gevFlightDurationSec = ${usdNumber(shot.flightDurationSec)}`,
` custom double userProperties:gevAuthoredHoldSec = ${usdNumber(shot.authoredHoldSec)}`,
` custom double userProperties:gevRuntimeHoldSec = ${usdNumber(shot.runtimeHoldSec)}`,
' matrix4d xformOp:transform.timeSamples = {',
);
for (let f = shot.frameStart; f < shot.frameEndExclusive; f += 1) {
out.push(` ${f}: ${usdMatrix(frames[f - 1])},`);
}
out.push(
' }',
' uniform token[] xformOpOrder = ["xformOp:transform"]',
' }',
);
});
out.push('}', '');
return out.join('\n');
}
/** Export one saved scene as a .usda camera stage. */
export function exportCameraUsda(project, options) {
const samples = sampleSceneCameras(project, options);
const usda = cameraSamplesToUsda(samples);
if (Buffer.byteLength(usda) > MAX_CAMERA_USDA_BYTES)
throw new RangeError('Camera USD exceeds 64 MiB');
return { usda, samples };
}
+251 -25
View File
@@ -13,10 +13,17 @@ import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { spawnSync } from 'node:child_process';
import { sceneSeekState } from '../director/timeline.js';
import {
effectiveShotHoldSec,
shotRuntimeDurationSec,
} from '../scenes/shotPresentation.js';
import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
import { createScenePackRegistry } from '../scenes/packs/registry.js';
const adapter = await import('./blenderCamera.js');
test('a portable camera manifest adapter exists', () => {
assert.equal(typeof adapter.exportCameraManifest, 'function');
test('a portable USD camera exporter exists', () => {
assert.equal(typeof adapter.sampleSceneCameras, 'function');
assert.equal(typeof adapter.exportCameraUsda, 'function');
});
const origin = { lat: 0, lon: 0, height: 0 };
@@ -46,7 +53,7 @@ const project = (
const near = (a, b, eps = 1e-8) =>
a.forEach((v, i) => assert.ok(Math.abs(v - b[i]) < eps, `${a} != ${b}`));
const camera = (changes = {}, opts = {}) =>
adapter.exportCameraManifest(
adapter.sampleSceneCameras(
project([{ id: 'camera', durationSec: 1, camera: pose(changes) }]),
options(opts),
).frames[0];
@@ -129,12 +136,11 @@ test('explicit horizontal lens works for landscape and portrait output', () => {
[1920, 1080],
[1080, 1920],
]) {
const m = adapter.exportCameraManifest(
project(),
options({ width, height }),
);
const m = adapter.sampleSceneCameras(project(), options({ width, height }));
assert.ok(Math.abs(m.camera.lensMm - 18) < 1e-10);
assert.equal(m.camera.sensorFit, 'HORIZONTAL');
assert.ok(
Math.abs(m.camera.sensorHeightMm - (36 * height) / width) < 1e-10,
);
assert.ok(
Math.abs(m.camera.verticalFovRadians - 2 * Math.atan(height / width)) <
1e-10,
@@ -142,7 +148,7 @@ test('explicit horizontal lens works for landscape and portrait output', () => {
}
});
test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON round trip', () => {
test('anchors, cubic moves, cuts, holds and rational frame timing are sampled', () => {
const p = project([
{
id: 'move',
@@ -173,7 +179,7 @@ test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON r
altitudeReference: 'ellipsoid',
},
];
const m = adapter.exportCameraManifest(
const m = adapter.sampleSceneCameras(
p,
options({
origin: { lat: 0, lon: 180, height: 0 },
@@ -190,7 +196,6 @@ test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON r
assert.equal(m.frames[18].shotId, 'cut');
assert.equal(m.frames[18].timeSec, (18 * 1001) / 30000);
near(m.frames[12].position, m.frames[17].position);
assert.deepEqual(JSON.parse(JSON.stringify(m)), m);
assert.equal(p.scenes[0].shots[0].camera.anchorId, 'end');
});
@@ -202,20 +207,18 @@ test('invalid or ambiguous input fails before export', () => {
{ origin: { lat: 0, lon: NaN, height: 0 } },
{ horizontalFovDegrees: 180 },
]) {
assert.throws(() =>
adapter.exportCameraManifest(project(), options(change)),
);
assert.throws(() => adapter.sampleSceneCameras(project(), options(change)));
}
assert.throws(() => camera({ lon: 20 }), /100 km/);
const multiple = project();
multiple.scenes.push({ ...multiple.scenes[0], id: 'other' });
assert.throws(
() => adapter.exportCameraManifest(multiple, options()),
() => adapter.sampleSceneCameras(multiple, options()),
/scene/i,
);
assert.throws(
() =>
adapter.exportCameraManifest(
adapter.sampleSceneCameras(
project([{ id: 'missing', camera: { heading: 0 } }]),
options(),
),
@@ -223,7 +226,7 @@ test('invalid or ambiguous input fails before export', () => {
);
assert.throws(
() =>
adapter.exportCameraManifest(
adapter.sampleSceneCameras(
project([{ id: 'long', camera: pose(), durationSec: 86400 }]),
options(),
),
@@ -233,12 +236,12 @@ test('invalid or ambiguous input fails before export', () => {
test('projection settings cannot be silently clamped by Blender', () => {
assert.throws(
() => adapter.exportCameraManifest(project(), options({ width: 1 })),
() => adapter.sampleSceneCameras(project(), options({ width: 1 })),
/width/,
);
assert.throws(
() =>
adapter.exportCameraManifest(
adapter.sampleSceneCameras(
project(),
options({ horizontalFovDegrees: 179, sensorWidthMm: 1 }),
),
@@ -261,7 +264,7 @@ test('every exported sample agrees with Director seeking at fractional shot boun
holdSec: 0.13,
},
]);
const m = adapter.exportCameraManifest(p, options());
const m = adapter.sampleSceneCameras(p, options());
assert.equal(m.frames.length, 21);
for (const sample of m.frames) {
const state = sceneSeekState(
@@ -283,7 +286,7 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio
const directory = mkdtempSync(join(tmpdir(), 'gev camera '));
try {
const input = join(directory, 'saved scene.json');
const output = join(directory, 'camera manifest.json');
const output = join(directory, 'camera stage.usda');
writeFileSync(input, JSON.stringify(project()));
const script = fileURLToPath(
new URL('../../tools/export-blender-camera.mjs', import.meta.url),
@@ -309,11 +312,21 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio
assert.equal(first.status, 0, first.stderr);
assert.match(first.stdout, /CAMERA_EXPORT_OK/);
const contents = readFileSync(output, 'utf8');
assert.equal(JSON.parse(contents).timeline.fps.denominator, 1001);
assert.match(contents, /^#usda 1\.0\n/);
assert.match(contents, /userProperties:gevFps = "30000\/1001"/);
const repeat = spawnSync(process.execPath, args, { encoding: 'utf8' });
assert.equal(repeat.status, 1);
assert.equal(readFileSync(output, 'utf8'), contents);
const invalidOutput = join(directory, 'invalid.json');
const jsonOutput = join(directory, 'cameras.json');
const wrongExtension = [...args];
wrongExtension[wrongExtension.indexOf(output)] = jsonOutput;
const rejected = spawnSync(process.execPath, wrongExtension, {
encoding: 'utf8',
});
assert.equal(rejected.status, 1);
assert.match(rejected.stderr, /\.usda/);
assert.equal(existsSync(jsonOutput), false);
const invalidOutput = join(directory, 'invalid.usda');
const invalid = [...args];
invalid[invalid.indexOf(output)] = invalidOutput;
invalid[invalid.length - 1] = '180';
@@ -337,7 +350,7 @@ test('ordinary submillisecond shots retain the Director seek duration floor', ()
holdSec: 0.1,
},
]);
const m = adapter.exportCameraManifest(p, options());
const m = adapter.sampleSceneCameras(p, options());
const sample = m.frames[1];
const state = sceneSeekState(
p.scenes[0],
@@ -360,8 +373,221 @@ test('long decimal timelines do not gain a rounding-only frame', () => {
camera: pose(),
})),
);
const m = adapter.exportCameraManifest(p, options());
const m = adapter.sampleSceneCameras(p, options());
assert.equal(m.timeline.durationSec, 1000);
assert.equal(m.frames.length, 30000);
assert.equal(m.shots[9999].frameEndExclusive, 30001);
});
const runtimeSeek = (scene, timeSec, durationSec, packs) =>
sceneSeekState(
scene,
timeSec / durationSec,
(s, shot) => shotRuntimeDurationSec(s, shot, packs),
(s, shot) => effectiveShotHoldSec(s, shot, packs),
);
test('shot timing follows Director runtime holds, not only the saved holdSec', () => {
// The Director's Mailung trim plays a 7.65 s hold although 15 s was saved.
const p = project([
{
id: 'mailung',
sourcePackId: 'bhote-koshi-nepal-evidence-pack',
durationSec: 4.2,
holdSec: 15,
camera: pose(),
layers: {
'bhote-koshi-2026': {
enabled: true,
params: { presentation: 'scene-beat', beatId: 'mailung-bazzar' },
},
},
},
{ id: 'next', durationSec: 1, holdSec: 0, camera: pose({ heading: 90 }) },
]);
const before = structuredClone(p);
const m = adapter.sampleSceneCameras(p, options());
const [first, second] = m.shots;
assert.equal(first.authoredHoldSec, 15);
assert.equal(first.runtimeHoldSec, 7.65);
assert.equal(second.startTimeSec, 4.2 + 7.65);
// Summing authored holds would start the next shot 7.35 s (220 frames) later.
assert.equal(second.frameStart, Math.ceil((4.2 + 7.65) * 30) + 1);
assert.equal(m.timeline.durationSec, 4.2 + 7.65 + 1);
const packs = createDefaultScenePacks();
p.scenes[0].shots.forEach((shot, i) =>
assert.equal(
m.shots[i].runtimeHoldSec,
effectiveShotHoldSec(p.scenes[0], shot, packs),
),
);
for (const sample of m.frames) {
const state = runtimeSeek(
p.scenes[0],
sample.timeSec,
m.timeline.durationSec,
packs,
);
assert.equal(sample.shotId, state.shot.id);
const expected = adapter.cameraPoseToEnu(state.camera, origin);
near(sample.position, expected.position);
sample.basisColumns.forEach((axis, i) =>
near(axis, expected.basisColumns[i]),
);
}
assert.deepEqual(p, before, 'export never rewrites saved shots');
});
test('registered minimum holds and evidence-sequence durations shift later shots', () => {
const packs = createScenePackRegistry({
recipes: [
{
id: 'sample',
runtimeControlsByBeat: {
arrival: { evidenceSequence: true, evidenceSequenceDurationSec: 2.5 },
},
},
],
adapters: [
{ minimumHoldSec: (states) => (states.overview?.enabled ? 3 : 0) },
],
});
const p = project([
{
id: 'evidence',
sourcePackId: 'sample',
durationSec: 1,
holdSec: 0.5,
camera: pose(),
layers: {
sample: {
enabled: true,
params: { presentation: 'scene-beat', beatId: 'arrival' },
},
},
},
{
id: 'overview',
durationSec: 1,
holdSec: 0,
camera: pose({ heading: 45 }),
layers: { overview: { enabled: true, params: {} } },
},
{ id: 'last', durationSec: 1, holdSec: 0, camera: pose({ heading: 90 }) },
]);
const m = adapter.sampleSceneCameras(p, options({ scenePacks: packs }));
assert.deepEqual(
m.shots.map((s) => [s.startTimeSec, s.runtimeHoldSec, s.frameStart]),
[
[0, 2.5, 1],
[3.5, 3, 106],
[7.5, 0, 226],
],
);
assert.equal(m.frames.length, 255);
// The holds match the Director's own seek path, which resolves layer states itself.
p.scenes[0].shots.forEach((shot, i) =>
assert.equal(
m.shots[i].runtimeHoldSec,
effectiveShotHoldSec(p.scenes[0], shot, packs),
),
);
for (const sample of m.frames) {
assert.equal(
sample.shotId,
runtimeSeek(p.scenes[0], sample.timeSec, m.timeline.durationSec, packs)
.shot.id,
);
}
});
const usdNumbers = (text) =>
text.match(/-?\d+(?:\.\d+)?(?:e[-+]?\d+)?/g).map(Number);
test('USD stage is Z-up meters with one camera per shot and per-frame matrices', () => {
const p = project([
{
id: 'first shot',
title: 'He said "hi"\n',
durationSec: 0.2,
holdSec: 0,
camera: pose({ heading: 30, roll: 10, alt: 50 }),
},
{
id: 'second',
durationSec: 0.1,
holdSec: 0,
camera: pose({ heading: 200, lon: 0.0005, pitch: -30 }),
},
]);
const { usda, samples } = adapter.exportCameraUsda(p, options());
assert.match(usda, /^#usda 1\.0\n/);
for (const line of [
'upAxis = "Z"',
'metersPerUnit = 1',
'startTimeCode = 1',
`endTimeCode = ${samples.timeline.frameEnd}`,
'timeCodesPerSecond = 30',
'framesPerSecond = 30',
'defaultPrim = "GEV"',
])
assert.ok(usda.includes(`\n ${line}\n`), line);
assert.match(usda, /string gevSchema = "gev\.camera-usd\.v1"/);
const cameras = usda.split('\n def Camera ').slice(1);
assert.equal(cameras.length, 2);
assert.match(cameras[0], /^"Shot_001_first_shot"/);
assert.match(cameras[1], /^"Shot_002_second"/);
// USD lens values are tenths of a scene unit (100 mm at metersPerUnit 1):
// a 90 degree horizontal FOV on a 36 mm sensor is an 18 mm lens.
assert.match(cameras[0], /\n {8}float focalLength = 0\.18\n/);
assert.match(cameras[0], /\n {8}float horizontalAperture = 0\.36\n/);
assert.match(cameras[0], /\n {8}float verticalAperture = 0\.2025\n/);
assert.match(cameras[0], /\n {8}token projection = "perspective"\n/);
assert.ok(
cameras[0].includes(
'custom string userProperties:gevShotTitle = "He said \\"hi\\"\\n"',
),
);
assert.ok(
cameras[0].includes(
'custom string userProperties:gevShotId = "first shot"',
),
);
cameras.forEach((text, index) => {
const shot = samples.shots[index];
const keys = [...text.matchAll(/\n {12}(\d+): \((.*)\),/g)];
assert.deepEqual(
keys.map(([, key]) => Number(key)),
Array.from(
{ length: shot.frameEndExclusive - shot.frameStart },
(_, i) => shot.frameStart + i,
),
);
for (const [, key, matrix] of keys) {
const values = usdNumbers(matrix);
const frame = samples.frames[Number(key) - 1];
assert.equal(frame.shotId, shot.id);
const [right, up, back] = frame.basisColumns;
near(values, [...right, 0, ...up, 0, ...back, 0, ...frame.position, 1]);
}
assert.match(
text,
/uniform token\[\] xformOpOrder = \["xformOp:transform"\]/,
);
});
});
test('USD stage records rational fps and portrait apertures', () => {
const { usda, samples } = adapter.exportCameraUsda(
project(),
options({
width: 1080,
height: 1920,
fps: { numerator: 30000, denominator: 1001 },
}),
);
assert.ok(usda.includes(`\n timeCodesPerSecond = ${30000 / 1001}\n`));
assert.ok(usda.includes('userProperties:gevFps = "30000/1001"'));
assert.match(usda, /float verticalAperture = 0\.64\n/);
assert.equal(samples.timeline.frameEnd, 30);
});
+5 -5
View File
@@ -6,11 +6,11 @@ automatically.
## Offline Blender camera interchange
`export-blender-camera.mjs` exports cameras from a saved Director scene;
`blender/camera_import.py` imports an editable rig into a new Blender scene.
These tools require no key, environment file, browser or network access and
export no imagery or geometry. Usage, format and synthetic projection checks:
[Blender cameras](../docs/BLENDER-CAMERAS.md).
`export-blender-camera.mjs` exports the cameras of a saved Director scene as a
plain-text USD stage (`.usda`) that Blender opens with File > Import >
Universal Scene Description. It requires no key, environment file, browser,
network access or Blender add-on, and exports no imagery or geometry. Usage,
format and lens units: [Blender cameras](../docs/BLENDER-CAMERAS.md).
Output files go to `output/` by default (gitignored).
-287
View File
@@ -1,287 +0,0 @@
"""Import camera-only GEV JSON. Python validation needs no Blender installation.
Blender console: import camera_import; camera_import.import_file('/path/camera.json')
CLI: blender --background --factory-startup --disable-autoexec --threads 1
--python tools/blender/camera_import.py -- camera.json output.blend
No image, geometry, network access or rendering is performed.
"""
import json
import math
from pathlib import Path
import sys
SCHEMA = "gev.camera-manifest.v1"
MAX_BYTES = 64 * 1024 * 1024
MAX_FRAMES = 100000
def _number(value, label, low, high, integer=False):
if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
raise ValueError(f"{label}: expected a finite number")
if not low <= value <= high or (integer and int(value) != value):
raise ValueError(f"{label}: outside supported range")
return int(value) if integer else value
def _text(value, label):
if not isinstance(value, str) or not value.strip() or len(value) > 4096:
raise ValueError(f"{label}: expected a nonempty string")
return value
def _near(actual, expected, label, tolerance=1e-8):
if not math.isclose(actual, expected, rel_tol=1e-10, abs_tol=tolerance):
raise ValueError(f"{label}: does not match the declared timing or projection")
def _vector(value, label):
if not isinstance(value, list) or len(value) != 3:
raise ValueError(f"{label}: expected three coordinates")
for component in value:
_number(component, label, -100001, 100001)
return value
def _dot(a, b):
return sum(x * y for x, y in zip(a, b))
def _cross(a, b):
return [a[1]*b[2]-a[2]*b[1], a[2]*b[0]-a[0]*b[2], a[0]*b[1]-a[1]*b[0]]
def _frame_at(seconds, rate):
value = seconds * rate
return (round(value) if abs(value - round(value)) < 1e-9 else math.ceil(value)) + 1
def validate_manifest(data):
"""Validate the complete data before importing bpy or mutating a scene."""
if not isinstance(data, dict) or data.get("schema") != SCHEMA:
raise ValueError("Unsupported GEV camera manifest schema")
source = data["source"]
_text(source["sceneId"], "scene ID")
if source.get("sampling") != "director-seek-authored-timing":
raise ValueError("Unsupported camera sampling semantics")
coordinates = data["coordinates"]
required = {"units": "meters", "axes": "east-north-up", "heightDatum": "WGS84-ellipsoid", "cameraAxes": "X-right,Y-up,-Z-forward"}
if any(coordinates.get(key) != value for key, value in required.items()):
raise ValueError("Explicit ENU meters, WGS84 ellipsoid and Blender camera axes required")
origin = coordinates["origin"]
for key, low, high in [("lat", -90, 90), ("lon", -180, 180), ("height", -12000, 1e9)]:
_number(origin[key], f"origin.{key}", low, high)
timeline = data["timeline"]
fps = timeline["fps"]
for key in ["numerator", "denominator"]:
_number(fps[key], f"fps.{key}", 1, 1000000, integer=True)
rate = _number(fps["numerator"] / fps["denominator"], "fps", 1, 240)
for key in ["width", "height"]:
_number(timeline[key], key, 4, 16384, integer=True)
if timeline["pixelAspect"] != [1, 1] or any(isinstance(value, bool) for value in timeline["pixelAspect"]):
raise ValueError("Only square pixels are supported")
if timeline["frameStart"] != 1 or isinstance(timeline["frameStart"], bool):
raise ValueError("Timeline must start at frame 1")
count = _number(timeline["frameEnd"], "frameEnd", 1, MAX_FRAMES, integer=True)
_number(timeline["durationSec"], "durationSec", 0, 100000)
if count != _frame_at(timeline["durationSec"], rate) - 1:
raise ValueError("Frame count differs from declared duration and fps")
camera = data["camera"]
if camera["projection"] != "perspective" or camera["sensorFit"] != "HORIZONTAL":
raise ValueError("Only a perspective horizontal-sensor camera is supported")
sensor = _number(camera["sensorWidthMm"], "sensorWidthMm", 1, 100)
hfov = _number(camera["horizontalFovRadians"], "horizontalFovRadians", math.pi/180, math.pi*179/180)
lens = _number(camera["lensMm"], "lensMm", 1, 10000)
_near(lens, sensor / (2 * math.tan(hfov / 2)), "lens")
_near(_number(camera["verticalFovRadians"], "verticalFovRadians", 0, math.pi), 2 * math.atan(math.tan(hfov / 2) * timeline["height"] / timeline["width"]), "vertical FOV")
shots = data["shots"]
if not isinstance(shots, list) or not 1 <= len(shots) <= count:
raise ValueError("Expected bounded nonempty shots")
ids = set()
elapsed = 0
rounding = 0
for shot in shots:
shot_id = _text(shot["id"], "shot ID")
if shot_id in ids:
raise ValueError("Duplicate shot ID")
ids.add(shot_id)
for key in ["startTimeSec", "endTimeSec", "durationSec", "holdSec"]:
_number(shot[key], key, 0, 100000)
if shot["durationSec"] <= 0:
raise ValueError("Shot duration must be positive")
_near(shot["startTimeSec"], elapsed, "shot start")
increment = shot["durationSec"] + shot["holdSec"] - rounding
next_time = elapsed + increment
rounding = next_time - elapsed - increment
elapsed = next_time
_near(shot["endTimeSec"], elapsed, "shot end")
for key, expected in [("frameStart", _frame_at(shot["startTimeSec"], rate)), ("frameEndExclusive", _frame_at(elapsed, rate))]:
_number(shot[key], key, 1, count + 1, integer=True)
if shot[key] != expected:
raise ValueError("Shot frame boundaries do not match timing")
if shot["frameStart"] >= shot["frameEndExclusive"]:
raise ValueError("Shot has no sampled frames")
_near(elapsed, timeline["durationSec"], "total duration")
frames = data["frames"]
if not isinstance(frames, list) or len(frames) != count:
raise ValueError("Frame count differs from frame samples")
shot_index = 0
for index, sample in enumerate(frames, start=1):
if sample["frame"] != index or isinstance(sample["frame"], bool):
raise ValueError("Frames must be sequential integers starting at 1")
_near(_number(sample["timeSec"], "timeSec", 0, 100000), (index - 1) * fps["denominator"] / fps["numerator"], "sample time")
while index >= shots[shot_index]["frameEndExclusive"] and shot_index < len(shots) - 1:
shot_index += 1
if sample["shotId"] != shots[shot_index]["id"]:
raise ValueError("Sample references the wrong shot")
location = _vector(sample["position"], "position")
if _dot(location, location) > 100000**2 + 0.01:
raise ValueError("Camera exceeds 100 km local-origin limit")
basis = sample["basisColumns"]
if not isinstance(basis, list) or len(basis) != 3:
raise ValueError("Expected three camera basis columns")
x, y, z = [_vector(column, "basis") for column in basis]
for column in [x, y, z]:
_near(_dot(column, column), 1, "unit camera axis", 1e-6)
for a, b in [(x, y), (y, z), (z, x)]:
_near(_dot(a, b), 0, "orthogonal camera axes", 1e-6)
_near(_dot(_cross(x, y), z), 1, "right-handed camera basis", 1e-6)
return data
def read_manifest(path):
"""Read bounded JSON only. No imports, URLs or expressions are evaluated."""
with Path(path).open("rb") as stream:
payload = stream.read(MAX_BYTES + 1)
if len(payload) > MAX_BYTES:
raise ValueError("Camera manifest exceeds 64 MiB")
return validate_manifest(json.loads(payload))
def _camera_curves(camera):
"""Read this camera's curves from current slotted or older legacy actions."""
action = camera.animation_data.action
if hasattr(action, "layers") and action.layers:
for layer in action.layers:
for strip in layer.strips:
bag = strip.channelbag(camera.animation_data.action_slot)
if bag:
yield from bag.fcurves
else:
yield from action.fcurves
def _write_camera_keys(camera, samples):
"""Allocate each F-Curve once, avoiding repeated insertion/handle updates."""
first = samples[0]
camera.location = first[1]
camera.rotation_quaternion = first[2]
# Let Blender create the appropriate action/slot for its own API version.
camera.keyframe_insert(data_path="location", frame=first[0])
camera.keyframe_insert(data_path="rotation_quaternion", frame=first[0])
for curve in _camera_curves(camera):
channel = 1 if curve.data_path == "location" else 2
component = curve.array_index
coordinates = [value for frame, location, rotation in samples
for value in (frame, (location if channel == 1 else rotation)[component])]
points = curve.keyframe_points
points.clear()
points.add(len(samples))
points.foreach_set("co", coordinates)
# Keep the exact sampled motion, rather than Blender's default Bezier.
for key in points:
key.interpolation = "LINEAR"
curve.update()
def import_manifest(data):
"""Create a new scene with editable per-shot cameras; preserve existing scenes."""
validate_manifest(data)
import bpy
from mathutils import Matrix
scene = bpy.data.scenes.new(f"GEV {data['source'].get('sceneTitle') or data['source']['sceneId']}")
scene.unit_settings.system = "METRIC"
scene.unit_settings.scale_length = 1.0
timeline = data["timeline"]
rate = timeline["fps"]["numerator"] / timeline["fps"]["denominator"]
scene.render.fps = round(rate)
scene.render.fps_base = round(rate) / rate
scene.render.resolution_x = int(timeline["width"])
scene.render.resolution_y = int(timeline["height"])
scene.render.resolution_percentage = 100
scene.render.pixel_aspect_x = scene.render.pixel_aspect_y = 1.0
scene.frame_start = 1
scene.frame_end = int(timeline["frameEnd"])
scene["gev_schema"] = SCHEMA
scene["gev_source"] = json.dumps(data["source"], ensure_ascii=False)
scene["gev_coordinates"] = json.dumps(data["coordinates"], ensure_ascii=False)
scene["gev_timeline"] = json.dumps(timeline)
root = bpy.data.objects.new("GEV ENU origin", None)
scene.collection.objects.link(root)
cameras = {}
for shot in data["shots"]:
camera_data = bpy.data.cameras.new(f"GEV {shot['id']}")
camera_data.type = "PERSP"
camera_data.sensor_fit = "HORIZONTAL"
camera_data.sensor_width = data["camera"]["sensorWidthMm"]
camera_data.lens = data["camera"]["lensMm"]
camera_data.clip_start = 0.01
camera_data.clip_end = 200000
camera = bpy.data.objects.new(f"GEV {shot['id']}", camera_data)
camera.rotation_mode = "QUATERNION"
camera.parent = root
camera["gev_shot"] = json.dumps(shot, ensure_ascii=False)
camera["gev_scene_id"] = data["source"]["sceneId"]
scene.collection.objects.link(camera)
cameras[shot["id"]] = camera
marker = scene.timeline_markers.new(f"GEV {shot['id']}", frame=int(shot["frameStart"]))
marker.camera = camera
previous = {}
keys = {shot_id: [] for shot_id in cameras}
for sample in data["frames"]:
# Manifest vectors are columns, while mathutils.Matrix accepts rows.
basis = Matrix(sample["basisColumns"]).transposed()
rotation = basis.to_quaternion().normalized()
old = previous.get(sample["shotId"])
if old is not None and rotation.dot(old) < 0:
rotation.negate()
previous[sample["shotId"]] = rotation.copy()
keys[sample["shotId"]].append((sample["frame"], sample["position"], tuple(rotation)))
for shot_id, camera in cameras.items():
_write_camera_keys(camera, keys[shot_id])
scene.camera = cameras[data["shots"][0]["id"]]
if bpy.context.window:
bpy.context.window.scene = scene
scene.frame_set(1)
return scene
def import_file(path):
"""Import a camera JSON file into a new Blender scene without rendering."""
return import_manifest(read_manifest(path))
def new_blend_output(path):
"""Require Blender's final extension before checking overwrite protection."""
output = Path(path).resolve()
if output.suffix != '.blend':
raise ValueError('Output must end in lowercase .blend')
if output.exists():
raise FileExistsError('Output already exists; choose a new .blend path')
return output
if __name__ == "__main__":
args = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else []
if len(args) != 2:
raise SystemExit("Usage: blender --background --factory-startup --disable-autoexec --threads 1 --python camera_import.py -- camera.json output.blend")
output = new_blend_output(args[1])
import_file(args[0])
import bpy
preview = bpy.context.preferences.filepaths.file_preview_type
try:
bpy.context.preferences.filepaths.file_preview_type = 'NONE'
bpy.ops.wm.save_as_mainfile(filepath=str(output.resolve()), check_existing=False)
finally:
bpy.context.preferences.filepaths.file_preview_type = preview
print("CAMERA_IMPORT_OK")
-147
View File
@@ -1,147 +0,0 @@
"""Synthetic CPU-only Blender import, projection and .blend round-trip check.
blender --background --factory-startup --disable-autoexec --threads 1
--python tools/blender/check_import.py -- fixture-directory
No renderer or GPU context is requested. All landmarks are synthetic empties.
"""
import importlib.util
import json
from pathlib import Path
import sys
import bpy
from bpy_extras.object_utils import world_to_camera_view
from mathutils import Vector
spec = importlib.util.spec_from_file_location("camera_import", Path(__file__).with_name("camera_import.py"))
importer = importlib.util.module_from_spec(spec)
spec.loader.exec_module(importer)
args = sys.argv[sys.argv.index("--") + 1:]
if len(args) != 1:
raise SystemExit("Expected one fixture directory")
directory = Path(args[0])
reference = json.loads((directory / "projection-reference.json").read_text())
original_names = set(bpy.data.scenes.keys())
original_settings = {scene.name: (scene.render.resolution_x, scene.render.resolution_y, scene.frame_end) for scene in bpy.data.scenes}
bpy.context.preferences.filepaths.file_preview_type = 'NONE'
def block(scene, name, center, size):
"""Tiny owned synthetic blockout, so the saved rig has an editable set."""
x, y, z = center
sx, sy, sz = [value / 2 for value in size]
vertices = [(x+dx*sx, y+dy*sy, z+dz*sz) for dx, dy, dz in [(-1,-1,-1),(1,-1,-1),(1,1,-1),(-1,1,-1),(-1,-1,1),(1,-1,1),(1,1,1),(-1,1,1)]]
faces = [(0,3,2,1),(4,5,6,7),(0,1,5,4),(1,2,6,5),(2,3,7,6),(3,0,4,7)]
mesh = bpy.data.meshes.new(name)
mesh.from_pydata(vertices, [], faces)
mesh.update()
obj = bpy.data.objects.new(name, mesh)
scene.collection.objects.link(obj)
cases = []
for case in reference["cases"]:
manifest = importer.read_manifest(directory / case["manifest"])
scene = importer.import_manifest(manifest)
# All validation occurs before bpy mutation.
malformed = json.loads(json.dumps(manifest))
malformed["frames"][-1]["basisColumns"][0] = [2, 0, 0]
names = set(bpy.data.scenes.keys())
objects = set(bpy.data.objects.keys())
try:
importer.import_manifest(malformed)
raise AssertionError("Malformed transform was accepted")
except ValueError:
assert set(bpy.data.scenes.keys()) == names
assert set(bpy.data.objects.keys()) == objects
for index, point in enumerate(case["checks"][0]["points"]):
landmark = bpy.data.objects.new(f"Synthetic landmark {index}", None)
landmark.location = point["position"]
scene.collection.objects.link(landmark)
block(scene, 'Synthetic ground, no map data', [0, 0, -1], [1400, 1400, 2])
for index in [0, 6, 9]:
sample = manifest['frames'][index]
point = case['checks'][index]['points'][0]['position']
direction = [(point[i]-sample['position'][i])/100 for i in range(3)]
distance = -sample['position'][2]/direction[2]
center = [sample['position'][i]+direction[i]*distance for i in range(2)] + [10]
block(scene, f'Synthetic block {index}', center, [24, 24, 20])
cases.append((case, manifest, scene.name))
# JSON may spell an integer-valued number as 1920.0. Blender RNA requires ints.
float_case = dict(reference['cases'][0], name='integer-valued JSON floats')
float_manifest = importer.read_manifest(directory / float_case['manifest'])
for key in ['width', 'height', 'frameEnd']:
float_manifest['timeline'][key] = float(float_manifest['timeline'][key])
for shot in float_manifest['shots']:
shot['frameStart'] = float(shot['frameStart'])
float_scene = importer.import_manifest(float_manifest)
cases.append((float_case, float_manifest, float_scene.name))
def check_all():
max_error = 0.0
projection_count = 0
for case, manifest, scene_name in cases:
scene = bpy.data.scenes[scene_name]
bpy.context.window.scene = scene
bpy.context.view_layer.update()
metadata = json.loads(scene["gev_source"])
assert metadata["sceneId"] == manifest["source"]["sceneId"]
assert json.loads(scene["gev_coordinates"]) == manifest["coordinates"]
assert json.loads(scene["gev_timeline"]) == manifest["timeline"]
assert scene.frame_start == 1 and scene.frame_end == len(manifest["frames"])
expected_rate = manifest["timeline"]["fps"]["numerator"] / manifest["timeline"]["fps"]["denominator"]
assert abs(scene.render.fps / scene.render.fps_base - expected_rate) < 2e-6
assert scene.unit_settings.scale_length == 1
assert scene.render.resolution_x == manifest["timeline"]["width"]
assert scene.render.resolution_y == manifest["timeline"]["height"]
cameras = {json.loads(obj["gev_shot"])["id"]: obj for obj in scene.objects if "gev_shot" in obj}
assert set(cameras) == {shot["id"] for shot in manifest["shots"]}
for shot in manifest["shots"]:
camera = cameras[shot["id"]]
assert json.loads(camera["gev_shot"]) == shot
expected_frames = [sample["frame"] for sample in manifest["frames"] if sample["shotId"] == shot["id"]]
curves = list(importer._camera_curves(camera))
assert len(curves) == 7, "Expected three location and four quaternion channels"
for curve in curves:
assert [key.co[0] for key in curve.keyframe_points] == expected_frames
assert all(key.interpolation == "LINEAR" for key in curve.keyframe_points)
for item in case["checks"]:
scene.frame_set(item["frame"])
active = scene.camera
camera = cameras[item["shotId"]]
assert active == camera, "Timeline marker selected the wrong camera"
assert camera.data.sensor_fit == "HORIZONTAL"
assert abs(camera.data.lens - manifest["camera"]["lensMm"]) < 1e-5
for point in item["points"]:
projected = world_to_camera_view(scene, camera, Vector(point["position"]))
assert projected.z > 0, (case['name'], item['frame'], 'landmark behind camera')
error = max(abs(projected.x - point["uv"][0]), abs(projected.y - point["uv"][1]))
max_error = max(error, max_error)
assert error < 2e-5, (case["name"], item["frame"], error)
projection_count += 1
for name in original_names:
scene = bpy.data.scenes[name]
assert (scene.render.resolution_x, scene.render.resolution_y, scene.frame_end) == original_settings[name]
return max_error, projection_count
before_error, count = check_all()
blend = directory / "synthetic-cameras.blend"
if blend.exists():
raise SystemExit("Synthetic output already exists; choose a fresh fixture directory")
bpy.context.window.scene = bpy.data.scenes[cases[0][2]]
bpy.context.scene.frame_set(1)
for area in bpy.context.screen.areas:
if area.type == 'VIEW_3D':
area.spaces.active.region_3d.view_perspective = 'CAMERA'
bpy.ops.wm.save_as_mainfile(filepath=str(blend.resolve()), check_existing=False)
assert blend.stat().st_size > 10000
bpy.ops.wm.open_mainfile(filepath=str(blend.resolve()), load_ui=False, use_scripts=False)
assert bpy.context.scene.name == cases[0][2], 'Demo must reopen on the blockout scene'
after_error, after_count = check_all()
assert after_count == count
receipt = {"state": "BLENDER_CAMERA_PROJECTION_OK", "blenderVersion": bpy.app.version_string, "cases": len(cases), "projectionsBeforeSave": count, "projectionsAfterReload": after_count, "maxUvError": max(before_error, after_error), "rendered": False, "gpuRequested": False, "blend": blend.name}
(directory / "blender-receipt.json").write_text(json.dumps(receipt, indent=2) + "\n")
print(json.dumps(receipt))
-173
View File
@@ -1,173 +0,0 @@
#!/usr/bin/env node
/** Generate tiny, provider-free fixtures plus an independent Cesium projection oracle. */
import { mkdir, writeFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { parseArgs } from 'node:util';
import * as C from 'cesium';
import { exportCameraManifest } from '../../src/tooling/blenderCamera.js';
import { sceneSeekState } from '../../src/director/timeline.js';
const { values } = parseArgs({ options: { output: { type: 'string' } } });
if (!values.output)
throw new Error(
'Usage: node tools/blender/make_fixture.mjs --output directory',
);
const output = resolve(values.output);
await mkdir(output, { recursive: true });
const pose = (values) => ({
lat: 39.7003,
lon: -105.0004,
alt: 1750,
heading: 20,
pitch: -25,
roll: 17,
altitudeReference: 'ellipsoid',
...values,
});
const finish = pose({
lat: 39.7005,
lon: -104.9995,
alt: 1800,
heading: 95,
pitch: -40,
roll: -25,
});
const cut = pose({
lat: 39.6998,
lon: -105.0003,
alt: 1725,
heading: 230,
pitch: -15,
roll: 35,
});
const document = {
version: 6,
scenes: [
{
id: 'synthetic-scene',
title: 'Synthetic camera bridge',
shots: [
{
id: 'rolled-move',
title: 'Move and hold',
durationSec: 0.2,
holdSec: 0.1,
camera: finish,
move: { from: pose({}), easing: 'cubic-in-out' },
},
{
id: 'cut',
title: 'Explicit cut and hold',
durationSec: 0.2,
holdSec: 0.1,
camera: cut,
move: { from: cut, easing: 'linear' },
},
],
},
],
};
const origin = { lat: 39.7, lon: -105, height: 1600 };
const anchor = C.Cartesian3.fromDegrees(origin.lon, origin.lat, origin.height);
const worldToLocal = C.Matrix4.inverseTransformation(
C.Transforms.eastNorthUpToFixedFrame(anchor),
new C.Matrix4(),
);
const cases = [];
for (const [name, width, height] of [
['landscape', 1920, 1080],
['portrait', 1080, 1920],
]) {
const manifest = exportCameraManifest(document, {
origin,
fps: { numerator: 30000, denominator: 1001 },
width,
height,
horizontalFovDegrees: 70,
});
await writeFile(
resolve(output, `${name}.camera.json`),
JSON.stringify(manifest, null, 2) + '\n',
);
const camera = new C.Camera({
drawingBufferWidth: width,
drawingBufferHeight: height,
mapProjection: new C.GeographicProjection(),
mode: C.SceneMode.SCENE3D,
});
camera.frustum.aspectRatio = width / height;
camera.frustum.fov =
width >= height
? manifest.camera.horizontalFovRadians
: manifest.camera.verticalFovRadians;
camera.frustum.near = 0.01;
camera.frustum.far = 200000;
const checks = [];
for (const sample of manifest.frames) {
const state = sceneSeekState(
document.scenes[0],
sample.timeSec / manifest.timeline.durationSec,
(_scene, shot) => shot.durationSec + shot.holdSec,
(_scene, shot) => shot.holdSec,
);
const p = state.camera;
camera.setView({
destination: C.Cartesian3.fromDegrees(p.lon, p.lat, p.alt),
orientation: {
heading: C.Math.toRadians(p.heading),
pitch: C.Math.toRadians(p.pitch),
roll: C.Math.toRadians(p.roll),
},
});
const projectionView = C.Matrix4.multiply(
camera.frustum.projectionMatrix,
camera.viewMatrix,
new C.Matrix4(),
);
const points = [];
for (const [right, up] of [
[0, 0],
[25, 0],
[-25, 15],
[0, -20],
]) {
const world = C.Cartesian3.clone(camera.positionWC);
for (const [axis, distance] of [
[camera.directionWC, 100],
[camera.rightWC, right],
[camera.upWC, up],
]) {
C.Cartesian3.add(
world,
C.Cartesian3.multiplyByScalar(axis, distance, new C.Cartesian3()),
world,
);
}
const clip = C.Matrix4.multiplyByVector(
projectionView,
new C.Cartesian4(world.x, world.y, world.z, 1),
new C.Cartesian4(),
);
const local = C.Matrix4.multiplyByPoint(
worldToLocal,
world,
new C.Cartesian3(),
);
points.push({
position: [local.x, local.y, local.z],
uv: [(clip.x / clip.w + 1) / 2, (clip.y / clip.w + 1) / 2],
});
}
checks.push({ frame: sample.frame, shotId: sample.shotId, points });
}
cases.push({ name, manifest: `${name}.camera.json`, checks });
}
await writeFile(
resolve(output, 'scene.json'),
JSON.stringify(document, null, 2) + '\n',
);
await writeFile(
resolve(output, 'projection-reference.json'),
JSON.stringify({ origin, cases }, null, 2) + '\n',
);
console.log('CAMERA_FIXTURE_OK');
-91
View File
@@ -1,91 +0,0 @@
"""Data validation checks. Standard Python only; no Blender or rendering required."""
import copy
import importlib.util
import math
from pathlib import Path
import sys
import tempfile
import unittest
module_path = Path(__file__).with_name("camera_import.py")
if module_path.exists():
spec = importlib.util.spec_from_file_location("camera_import", module_path)
importer = importlib.util.module_from_spec(spec)
spec.loader.exec_module(importer)
else:
importer = None
def fixture():
return {
"schema": "gev.camera-manifest.v1",
"source": {"sceneId": "scene", "sceneTitle": "Fixture", "sampling": "director-seek-authored-timing", "attributions": []},
"coordinates": {"units": "meters", "axes": "east-north-up", "heightDatum": "WGS84-ellipsoid", "origin": {"lat": 0, "lon": 0, "height": 0}, "cameraAxes": "X-right,Y-up,-Z-forward"},
"camera": {"projection": "perspective", "sensorFit": "HORIZONTAL", "sensorWidthMm": 36, "lensMm": 18, "horizontalFovRadians": math.pi / 2, "verticalFovRadians": math.pi / 2},
"timeline": {"fps": {"numerator": 30, "denominator": 1}, "width": 100, "height": 100, "pixelAspect": [1, 1], "frameStart": 1, "frameEnd": 1, "durationSec": 1 / 30},
"shots": [{"id": "north", "title": "North", "startTimeSec": 0, "endTimeSec": 1 / 30, "durationSec": 1 / 30, "holdSec": 0, "frameStart": 1, "frameEndExclusive": 2}],
"frames": [{"frame": 1, "timeSec": 0, "shotId": "north", "position": [0, 0, 0], "basisColumns": [[1, 0, 0], [0, 0, 1], [0, -1, 0]]}],
}
class ValidationTests(unittest.TestCase):
def test_validator_exists(self):
self.assertIsNotNone(importer, "camera importer is missing")
def test_valid_manifest_is_not_mutated_and_does_not_import_bpy(self):
data = fixture()
before = copy.deepcopy(data)
importer.validate_manifest(data)
self.assertEqual(data, before)
self.assertNotIn("bpy", sys.modules)
def test_rejects_datum_axes_lens_fps_and_timing_mismatches(self):
mutations = [
lambda m: m.update(schema="other"),
lambda m: m["coordinates"].update(heightDatum="MSL"),
lambda m: m["coordinates"].update(axes="north-east-down"),
lambda m: m["camera"].update(lensMm=35),
lambda m: m["camera"].update(lensMm=0.5),
lambda m: m["camera"].update(verticalFovRadians=1),
lambda m: m["timeline"]["fps"].update(denominator=0),
lambda m: m["timeline"].update(frameEnd=2),
lambda m: m["timeline"].update(width=1),
lambda m: m["timeline"].update(pixelAspect=[2, 1]),
lambda m: m["frames"][0].update(frame=2),
lambda m: m["frames"][0].update(timeSec=1),
lambda m: m["frames"][0].update(shotId="missing"),
lambda m: m["shots"][0].update(frameStart=2),
lambda m: m["shots"][0].update(endTimeSec=2),
lambda m: m["frames"][0].update(position=[100001, 0, 0]),
lambda m: m["frames"][0].update(position=[False, 0, 0]),
lambda m: m["frames"][0].update(position=[math.nan, 0, 0]),
lambda m: m["frames"][0].update(basisColumns=[[1, 0, 0], [1, 0, 0], [0, 0, 1]]),
lambda m: m["frames"][0].update(basisColumns=[[-1, 0, 0], [0, 0, 1], [0, -1, 0]]),
]
for mutate in mutations:
data = fixture()
mutate(data)
with self.subTest(mutation=mutations.index(mutate)):
with self.assertRaises((ValueError, TypeError, KeyError)):
importer.validate_manifest(data)
def test_output_extension_is_checked_before_existing_file_guard(self):
with tempfile.TemporaryDirectory(prefix='gev-blender-output-') as directory:
output = Path(directory) / 'camera.blend'
output.write_bytes(b'existing file must survive')
with self.assertRaises(ValueError):
importer.new_blend_output(Path(directory) / 'camera')
with self.assertRaises(FileExistsError):
importer.new_blend_output(output)
with self.assertRaises(ValueError):
importer.new_blend_output(Path(directory) / 'new.BLEND')
self.assertEqual(output.read_bytes(), b'existing file must survive')
self.assertEqual(importer.new_blend_output(Path(directory) / 'new.blend').name, 'new.blend')
if __name__ == "__main__":
result = unittest.main(exit=False)
if result.result.wasSuccessful():
print("IMPORT_VALIDATION_OK")
else:
sys.exit(1)
+8 -9
View File
@@ -1,12 +1,12 @@
#!/usr/bin/env node
/** Offline scene-to-camera manifest CLI. Reads JSON only; never loads .env or a viewer. */
/** Offline scene-to-USD camera CLI. Reads JSON only; never loads .env or a viewer. */
import { readFile, writeFile, stat } from 'node:fs/promises';
import { parseArgs } from 'node:util';
import {
parseSceneDocument,
SCENE_DOCUMENT_LIMITS,
} from '../src/director/document.js';
import { exportCameraManifest } from '../src/tooling/blenderCamera.js';
import { exportCameraUsda } from '../src/tooling/blenderCamera.js';
try {
const { values } = parseArgs({
@@ -25,7 +25,7 @@ try {
});
if (values.help) {
console.log(
'Usage: node tools/export-blender-camera.mjs --input scene.json --output camera.json --origin lat,lon,ellipsoidHeight --fps 30 (or 30000/1001) --width 1920 --height 1080 --horizontal-fov-deg 60 [--scene id] [--sensor-width-mm 36]',
'Usage: node tools/export-blender-camera.mjs --input scene.json --output cameras.usda --origin lat,lon,ellipsoidHeight --fps 30 (or 30000/1001) --width 1920 --height 1080 --horizontal-fov-deg 60 [--scene id] [--sensor-width-mm 36]',
);
} else {
for (const key of [
@@ -39,6 +39,8 @@ try {
]) {
if (!values[key]?.trim()) throw new Error(`Missing --${key}; use --help`);
}
if (!values.output.endsWith('.usda'))
throw new Error('output must be a new file ending in .usda');
if (!/^\d+(?:\/\d+)?$/.test(values.fps))
throw new Error('fps must be an integer or integer ratio');
const originParts = values.origin.split(',');
@@ -49,7 +51,7 @@ try {
const document = parseSceneDocument(await readFile(values.input, 'utf8'));
const [numerator, denominator = 1] = values.fps.split('/').map(Number);
const [lat, lon, height] = originParts.map(Number);
const manifest = exportCameraManifest(document, {
const { usda, samples } = exportCameraUsda(document, {
sceneId: values.scene,
origin: { lat, lon, height },
fps: { numerator, denominator },
@@ -58,12 +60,9 @@ try {
horizontalFovDegrees: Number(values['horizontal-fov-deg']),
sensorWidthMm: Number(values['sensor-width-mm']),
});
const json = JSON.stringify(manifest, null, 2) + '\n';
if (Buffer.byteLength(json) > 64 * 1024 * 1024)
throw new Error('Camera manifest exceeds 64 MiB');
await writeFile(values.output, json, { flag: 'wx' });
await writeFile(values.output, usda, { flag: 'wx' });
console.log(
`CAMERA_EXPORT_OK: ${manifest.shots.length} shots, ${manifest.frames.length} frames`,
`CAMERA_EXPORT_OK: ${samples.shots.length} shots, ${samples.frames.length} frames`,
);
}
} catch (error) {