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

+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