Merge branch 'main' into german/recent-imagery-auto-successor

This commit is contained in:
German Khokhlov authored and GitHub committed 2026-11-20 17:10:30 +04:00
commit 1a57469fd1
16 files changed
+1927 -9

No files matched your search

+138
View File
@@ -0,0 +1,138 @@
# GEV cameras in Blender
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
Save a Director project as JSON, then run from the repository root:
```sh
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
```
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
are never implicitly converted from mean sea level or above ground level.
Positions must be complete; legacy documents without saved IDs or positions
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 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))`.
The exporter supports integer fps or an integer ratio such as `30000/1001`,
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 must be a regular file within the existing 5 MiB scene-document limit;
output is limited to 100,000 frames and 64 MiB. Every shot needs at least one
sampled frame.
## Timing and camera semantics
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 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.
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,
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`. 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`, in the geodetic ENU frame (axes
from the WGS84 ellipsoid normal at the origin's latitude and longitude), 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. 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, 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**).
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 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 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/blender*.test.mjs
```
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.
+4
View File
@@ -1577,6 +1577,10 @@ seek and keeps the last settled position. Undeclared operator layers remain
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 a camera-only USD stage (`.usda`) with Director seek
interpolation and runtime shot timing; format, units and limits are in that guide.
Realtime voice composes separate connection, response/tool, Radio handoff, input
and audio-meter, cost, viewport-context and diagnostic owners. The existing
controller exports and session/backend contracts remain available. Tool protocol,