mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-20 18:22:25 +00:00
fix(blender-camera): accept southern origins and bound the scene read
- Join a space-separated negative latitude to --origin before parseArgs, so `--origin -33.86,151.21,0` works as the usage and docs show. - Read the input through one descriptor, regular files only, at most one byte past the 5 MiB scene limit. - Use geodetic ENU axes at the origin (ellipsoid normal at its lat/lon, raised to its height) instead of Cesium's frame at the raised point. - Reuse the shots already resolved, serialize the sampled shot table directly, and drop the typeof-only export test. - Docs: timing matches Director seeking, with the playback differences; add a manual OpenUSD/Blender check; shorten the overview and test list.
This commit is contained in:
1 parent
4668f26e0e
commit
235938e19b
6 files changed
+116
-66
No files matched your search
@@ -1,3 +1,3 @@
|
||||
- Export saved Director scenes as camera-only USD (`.usda`) stages that Blender
|
||||
imports natively, with ENU meter coordinates, lens in USD units, rational fps
|
||||
and the same runtime shot timing as Director playback (UBN606, #1460).
|
||||
and the same runtime shot timing as Director seeking (UBN606, #1460).
|
||||
+20
-13
@@ -42,8 +42,9 @@ 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 is bounded to 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.
|
||||
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
|
||||
|
||||
@@ -51,10 +52,12 @@ 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
|
||||
same functions Director seeking and scrubbing 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.
|
||||
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.
|
||||
|
||||
Camera poses follow GEV's Director **seek** interpolation. Named anchors and
|
||||
explicit `move.from` endpoints resolve through the existing camera owner;
|
||||
@@ -78,8 +81,9 @@ 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.
|
||||
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.
|
||||
@@ -135,12 +139,15 @@ closer to the origin.
|
||||
node --test src/tooling/blenderCamera.test.mjs
|
||||
```
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
@@ -689,14 +689,8 @@ 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`) 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.
|
||||
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
|
||||
|
||||
@@ -68,13 +68,17 @@ export function cameraPoseToEnu(pose, origin) {
|
||||
);
|
||||
if (C.Cartesian3.distance(xyz, anchor) > 100000)
|
||||
throw new RangeError('Camera exceeds the 100 km local-origin limit');
|
||||
// Geodetic ENU (as in PROJ): axes from the ellipsoid normal at the origin's
|
||||
// lat/lon, origin raised along it. Cesium's frame at a raised point tilts.
|
||||
const frame = C.Transforms.eastNorthUpToFixedFrame(
|
||||
C.Cartesian3.fromDegrees(origin.lon, origin.lat, 0, C.Ellipsoid.WGS84),
|
||||
);
|
||||
const inverse = C.Matrix4.inverseTransformation(
|
||||
C.Transforms.eastNorthUpToFixedFrame(anchor),
|
||||
C.Matrix4.setTranslation(frame, anchor, frame),
|
||||
new C.Matrix4(),
|
||||
);
|
||||
const local = C.Matrix4.multiplyByPoint(inverse, xyz, new C.Cartesian3());
|
||||
// Same basis as Cesium Camera.setView3D, including its heading - PI/2 offset.
|
||||
// This is the coordinate math retained from the staged ENU camera prototype.
|
||||
const rotation = C.Matrix3.fromQuaternion(
|
||||
C.Quaternion.fromHeadingPitchRoll(
|
||||
new C.HeadingPitchRoll(
|
||||
@@ -117,7 +121,7 @@ function identity(value, label) {
|
||||
return value;
|
||||
}
|
||||
|
||||
/** Resolve the flight-plus-hold seconds and holds that Director playback and seeking use.
|
||||
/** Resolve the flight-plus-hold seconds and holds that Director seeking uses.
|
||||
* Both come from shotPresentation.js, so registered pack overrides, minimum holds and
|
||||
* evidence-sequence durations match the app instead of the saved holdSec alone.
|
||||
*/
|
||||
@@ -146,7 +150,7 @@ export function sceneRuntimeTiming(
|
||||
};
|
||||
}
|
||||
|
||||
/** Sample one saved scene with Director seek interpolation and runtime playback timing.
|
||||
/** Sample one saved scene with Director seek interpolation and runtime seek timing.
|
||||
* Projection is explicit because scene documents do not store viewport lenses.
|
||||
* Frame 1 samples time zero; the final sample precedes the exclusive end time.
|
||||
*/
|
||||
@@ -205,11 +209,10 @@ export function sampleSceneCameras(
|
||||
),
|
||||
move: resolveCameraMove(scene, shot),
|
||||
}));
|
||||
const shots = scene.shots.map((shot) => {
|
||||
const shots = scene.shots.map((shot, index) => {
|
||||
identity(shot.id, 'Shot');
|
||||
const camera = resolveCameraPose(scene, shot.camera);
|
||||
const { target: camera, move } = resolved[index];
|
||||
position(camera);
|
||||
const move = resolveCameraMove(scene, shot);
|
||||
if (move) position(move.from);
|
||||
cameraPoseToEnu(camera, origin);
|
||||
if (move) cameraPoseToEnu(move.from, origin);
|
||||
@@ -340,7 +343,7 @@ export function sampleSceneCameras(
|
||||
};
|
||||
}
|
||||
|
||||
/** Shortest decimal for a finite double, without signed zero or 17-digit noise. */
|
||||
/** Round a finite double to 15 significant digits and normalize signed zero. */
|
||||
function usdNumber(value) {
|
||||
const rounded = Number(value.toPrecision(15));
|
||||
return Object.is(rounded, -0) ? '0' : String(rounded);
|
||||
@@ -378,32 +381,6 @@ function usdMatrix({ position: p, basisColumns: [right, up, back] }) {
|
||||
export function cameraSamplesToUsda(samples) {
|
||||
const { source, coordinates, camera, timeline, shots, frames } = samples;
|
||||
const rate = timeline.fps.numerator / timeline.fps.denominator;
|
||||
const shotTable = shots.map(
|
||||
({
|
||||
id,
|
||||
title,
|
||||
sourcePackId,
|
||||
sourcePackVersion,
|
||||
startTimeSec,
|
||||
endTimeSec,
|
||||
flightDurationSec,
|
||||
authoredHoldSec,
|
||||
runtimeHoldSec,
|
||||
frameStart,
|
||||
frameEndExclusive,
|
||||
}) => ({
|
||||
id,
|
||||
title,
|
||||
...(sourcePackId ? { sourcePackId, sourcePackVersion } : {}),
|
||||
startTimeSec,
|
||||
endTimeSec,
|
||||
flightDurationSec,
|
||||
authoredHoldSec,
|
||||
runtimeHoldSec,
|
||||
frameStart,
|
||||
frameEndExclusive,
|
||||
}),
|
||||
);
|
||||
const json = (value) => usdString(JSON.stringify(value));
|
||||
const out = [
|
||||
'#usda 1.0',
|
||||
@@ -412,7 +389,7 @@ export function cameraSamplesToUsda(samples) {
|
||||
` string gevCamera = ${json(camera)}`,
|
||||
` string gevCoordinates = ${json(coordinates)}`,
|
||||
` string gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`,
|
||||
` string gevShots = ${json(shotTable)}`,
|
||||
` string gevShots = ${json(shots)}`,
|
||||
` string gevSource = ${json(source)}`,
|
||||
` string gevTimeline = ${json(timeline)}`,
|
||||
' }',
|
||||
|
||||
@@ -21,10 +21,6 @@ import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
|
||||
import { createScenePackRegistry } from '../scenes/packs/registry.js';
|
||||
|
||||
const adapter = await import('./blenderCamera.js');
|
||||
test('a portable USD camera exporter exists', () => {
|
||||
assert.equal(typeof adapter.sampleSceneCameras, 'function');
|
||||
assert.equal(typeof adapter.exportCameraUsda, 'function');
|
||||
});
|
||||
|
||||
const origin = { lat: 0, lon: 0, height: 0 };
|
||||
const pose = (changes = {}) => ({
|
||||
@@ -76,6 +72,14 @@ test('cardinal cameras use Blender X right, Y up, negative Z forward', () => {
|
||||
|
||||
test('ENU translation uses WGS84 meters and ellipsoid heights', () => {
|
||||
near(camera({ alt: 100 }).position, [0, 0, 100]);
|
||||
near(
|
||||
camera(
|
||||
{ lat: 39.7, lon: -105, alt: 2600 },
|
||||
{ origin: { lat: 39.7, lon: -105, height: 1600 } },
|
||||
).position,
|
||||
[0, 0, 1000],
|
||||
1e-6,
|
||||
);
|
||||
const east = camera({ lon: 0.001 }).position;
|
||||
assert.ok(Math.abs(east[0] - 111.3194907876) < 1e-6);
|
||||
assert.ok(Math.abs(east[2] + 0.0009714458) < 1e-6);
|
||||
@@ -107,7 +111,7 @@ test('changed tangent frames and nonzero roll match an independent Cesium Camera
|
||||
});
|
||||
const inverse = Cesium.Matrix4.inverseTransformation(
|
||||
Cesium.Transforms.eastNorthUpToFixedFrame(
|
||||
Cesium.Cartesian3.fromDegrees(anchor.lon, anchor.lat, anchor.height),
|
||||
Cesium.Cartesian3.fromDegrees(anchor.lon, anchor.lat, 0),
|
||||
),
|
||||
new Cesium.Matrix4(),
|
||||
);
|
||||
@@ -340,6 +344,43 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio
|
||||
}
|
||||
});
|
||||
|
||||
test('CLI accepts a negative latitude passed as --origin <value>', () => {
|
||||
const directory = mkdtempSync(join(tmpdir(), 'gev origin '));
|
||||
try {
|
||||
const script = fileURLToPath(
|
||||
new URL('../../tools/export-blender-camera.mjs', import.meta.url),
|
||||
);
|
||||
const result = spawnSync(
|
||||
process.execPath,
|
||||
[
|
||||
script,
|
||||
'--input',
|
||||
join(directory, 'missing scene.json'),
|
||||
'--output',
|
||||
join(directory, 'cameras.usda'),
|
||||
'--origin',
|
||||
'-33.8568,151.2153,0',
|
||||
'--fps',
|
||||
'30',
|
||||
'--width',
|
||||
'1920',
|
||||
'--height',
|
||||
'1080',
|
||||
'--horizontal-fov-deg',
|
||||
'60',
|
||||
],
|
||||
{ encoding: 'utf8' },
|
||||
);
|
||||
// The input file does not exist, so the run still fails, but only after
|
||||
// argument parsing: the error must be about the input, not about --origin.
|
||||
assert.equal(result.status, 1);
|
||||
assert.doesNotMatch(result.stderr, /ambiguous|--origin/);
|
||||
assert.match(result.stderr, /ENOENT|no such file/i);
|
||||
} finally {
|
||||
rmSync(directory, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test('ordinary submillisecond shots retain the Director seek duration floor', () => {
|
||||
const p = project([
|
||||
{ id: 'start', camera: pose(), durationSec: 0.033, holdSec: 0 },
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
#!/usr/bin/env node
|
||||
/** Offline scene-to-USD camera CLI. Reads JSON only; never loads .env or a viewer. */
|
||||
import { readFile, writeFile, stat } from 'node:fs/promises';
|
||||
import { open, writeFile } from 'node:fs/promises';
|
||||
import { parseArgs } from 'node:util';
|
||||
import {
|
||||
parseSceneDocument,
|
||||
@@ -8,8 +8,41 @@ import {
|
||||
} from '../src/director/document.js';
|
||||
import { exportCameraUsda } from '../src/tooling/blenderCamera.js';
|
||||
|
||||
/** Read a regular file through one descriptor, at most one byte past the scene limit. */
|
||||
async function readSceneText(path) {
|
||||
const file = await open(path, 'r');
|
||||
try {
|
||||
if (!(await file.stat()).isFile())
|
||||
throw new Error('input must be a regular file');
|
||||
const buffer = Buffer.alloc(SCENE_DOCUMENT_LIMITS.bytes + 1);
|
||||
let length = 0;
|
||||
while (length < buffer.length) {
|
||||
const { bytesRead } = await file.read(
|
||||
buffer,
|
||||
length,
|
||||
buffer.length - length,
|
||||
);
|
||||
if (!bytesRead) break;
|
||||
length += bytesRead;
|
||||
}
|
||||
if (length > SCENE_DOCUMENT_LIMITS.bytes)
|
||||
throw new Error('Scene exceeds 5 MiB');
|
||||
return buffer.toString('utf8', 0, length);
|
||||
} finally {
|
||||
await file.close();
|
||||
}
|
||||
}
|
||||
|
||||
try {
|
||||
// parseArgs reads a value starting with "-" as a missing argument, so join a
|
||||
// southern-hemisphere `--origin -33.86,151.21,0` into `--origin=...` first.
|
||||
const args = process.argv.slice(2);
|
||||
for (let i = args.length - 2; i >= 0; i -= 1) {
|
||||
if (args[i] === '--origin' && /^-[\d.]/.test(args[i + 1]))
|
||||
args.splice(i, 2, `--origin=${args[i + 1]}`);
|
||||
}
|
||||
const { values } = parseArgs({
|
||||
args,
|
||||
options: {
|
||||
input: { type: 'string' },
|
||||
output: { type: 'string' },
|
||||
@@ -46,9 +79,7 @@ try {
|
||||
const originParts = values.origin.split(',');
|
||||
if (originParts.length !== 3 || originParts.some((part) => !part.trim()))
|
||||
throw new Error('origin must be lat,lon,ellipsoidHeight');
|
||||
if ((await stat(values.input)).size > SCENE_DOCUMENT_LIMITS.bytes)
|
||||
throw new Error('Scene exceeds 5 MiB');
|
||||
const document = parseSceneDocument(await readFile(values.input, 'utf8'));
|
||||
const document = parseSceneDocument(await readSceneText(values.input));
|
||||
const [numerator, denominator = 1] = values.fps.split('/').map(Number);
|
||||
const [lat, lon, height] = originParts.map(Number);
|
||||
const { usda, samples } = exportCameraUsda(document, {
|
||||
|
||||
Reference in new issue
Block a user