mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-20 18:22:25 +00:00
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:
1 parent
68958bf34b
commit
7db4bb35f7
14 files changed
+908
-373
No files matched your search
+46
-62
@@ -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.
|
||||
Reference in new issue
Block a user