mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-20 18:22:25 +00:00
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:
14 files changed
+624
-865
No files matched your search
+87
-72
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user