fix(blender-camera): match Director timing and harden the export CLI

Sample frames with Director's normalized shots and runtime timing, count
frames with a tolerance bounded by float rounding, coerce legacy numeric
text, open the input without blocking, strip a BOM, remove a partial
output on failure, and escape control characters in errors.
This commit is contained in:
German Khokhlov committed 2026-11-20 03:38:04 +04:00
1 parent 68958bf34b
commit 7db4bb35f7
14 files changed
+908 -373

No files matched your search

+46 -62
View File
@@ -1,28 +1,23 @@
# GEV cameras in Blender
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
work discussed in [issue #1081](https://github.com/bilawalsidhu/gods-eye-view/issues/1081).
Export the cameras of one saved Director scene as a camera-only USD stage
(`.usda`, plain text) and open it with Blender's built-in importer. The export
needs no API key, network, browser or Blender add-on and contains no imagery or
geometry, so use independently licensed assets for your set.
## Export a saved scene
Use the repository's supported Node runtime and installed dependencies. Save a
Director project as JSON, then run from the repository root:
Save a Director project as JSON, then run from the repository root:
```sh
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
mkdir -p output
node tools/export-blender-camera.mjs --input scene.json --output 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 ending in `.usda`; the tool
refuses to overwrite it. No environment files are read.
Paths are relative to the current directory; `output/` is ignored by git.
Omit `--scene` only when the document contains exactly one scene. `--output`
is required and 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
@@ -32,8 +27,9 @@ need to be saved again in GEV before export.
Projection and fps are required because Director documents do not record a
viewport lens, aspect ratio or video frame rate. `--horizontal-fov-deg` is the
horizontal perspective FOV, even for portrait output. If deriving it from a
Cesium `PerspectiveFrustum`, use `2 * atan(tan(fovy / 2) * aspectRatio)`.
horizontal perspective FOV in degrees, even for portrait output. If deriving it
from a Cesium `PerspectiveFrustum`, use
`2 * atan(tan(fovy / 2) * aspectRatio) * 180 / π` (`fovy` is in radians).
Do not assume `frustum.fov` is horizontal: it is the wider-dimension FOV.
The optional `--sensor-width-mm` defaults to 36; focal length is
`sensorWidthMm / (2 * tan(horizontalFovRadians / 2))`.
@@ -48,24 +44,21 @@ sampled frame.
## Timing and camera semantics
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 seeking and scrubbing use. Registered pack hold
Timing is the Director's **runtime** seek timing. The exporter loads the
document as Director does, so ordinary shots fly for at least 0.2 s, and takes
each shot's length and hold from `shotRuntimeTiming` in
`src/scenes/shotPresentation.js` with the default scene packs. Registered hold
overrides, minimum holds and evidence-sequence durations therefore move later
shots exactly as they do when seeking in the app. Live playback can run longer:
it flies each shot for at least 0.2 s and can wait for a layer's media to finish
before the next shot. Saved shots are never rewritten; each camera records both
the authored and the runtime hold.
shots as they do when seeking in the app. Live playback can run longer when it
waits for a layer's media. 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`.
Each frame's camera is the Director's `sceneSeekState` pose at that time.
Named anchors and explicit `move.from` endpoints resolve through the existing
camera owner, and explicit linear/cubic moves use its sampler. Ordinary shots
interpolate cubically, by the shortest angle, from the previous shot's camera;
a shot that opens the scene starts at its own camera. A cut can be authored as
an explicit move with identical start/end poses.
The bridge does not reproduce Cesium's implicit live `flyTo` trajectory,
provider readiness, layer-owned camera motion, lens changes, visual effects,
@@ -102,16 +95,17 @@ boundary switches at the first sampled time at or after the boundary.
- 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.
attribution text, as `userProperties:` attributes. No referenced assets are
fetched.
## Import into Blender
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.
frame rate, with **Aspect X:Y** at 1:1. 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**).
@@ -120,35 +114,25 @@ 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`.
chooses horizontal sensor fit when the horizontal aperture is at least as large
as the vertical one and vertical fit otherwise, so portrait exports import with
vertical fit and the same field of view. This mapping is in Blender's
`usd_reader_camera.cc`.
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.
that keeps the absolute path of the imported `.usda`. Put the file in its
permanent place before importing, or update the path in the constraint after
moving it. For a self-contained file, select the cameras and use **Object >
Animation > Bake Action…** with **Visual Keying** and **Clear Constraints**.
Blender stores object transforms in single precision: up to about 4 mm of
rounding at 100 km, less closer to the origin.
## Checks
```sh
node --test src/tooling/blenderCamera.test.mjs
node --test src/tooling/blender*.test.mjs
```
These Node tests run in CI and compare the export with an independent Cesium
camera and the Director's `sceneSeekState`.
They do not parse the stage with USD itself; to check that, open it in
Blender as above or with OpenUSD (`pip install usd-core`):
```sh
python3 -c "import sys; from pxr import Usd; print(Usd.Stage.Open(sys.argv[1]).GetEndTimeCode())" cameras.usda
```
Run the repository's normal unit, build, format and boundary checks too. The
contribution guide additionally requires live tracking/browser checks before
submission; this camera check does not replace them.
The tests compare the export with an independent Cesium camera and the
Director's runtime timing, and parse the stage with OpenUSD's `usdcat` when it
is installed.