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
+107
-168
@@ -1,17 +1,11 @@
|
||||
/** Camera-only USD interchange. No viewer, providers, environment files or terrain access. */
|
||||
import * as C from 'cesium';
|
||||
import { validateSceneDocument } from '../director/document.js';
|
||||
import {
|
||||
resolveCameraPose,
|
||||
resolveCameraMove,
|
||||
sampleCameraMove,
|
||||
} from '../director/camera.js';
|
||||
import { cameraAtProgress } from '../director/timeline.js';
|
||||
import {
|
||||
effectiveShotHoldSec,
|
||||
runtimeLayerStatesForShot,
|
||||
shotRuntimeDurationSec,
|
||||
} from '../scenes/shotPresentation.js';
|
||||
import { resolveCameraPose } from '../director/camera.js';
|
||||
import { sceneSeekState } from '../director/timeline.js';
|
||||
import { headingPitchRollFrame } from '../geo/quaternion.js';
|
||||
import { normalizeProject } from '../scenes/project.js';
|
||||
import { shotRuntimeTiming } from '../scenes/shotPresentation.js';
|
||||
import { createDefaultScenePacks } from '../scenes/packs/defaults.js';
|
||||
|
||||
export const CAMERA_USD_SCHEMA = 'gev.camera-usd.v1';
|
||||
@@ -20,7 +14,6 @@ export const MAX_CAMERA_USDA_BYTES = 64 * 1024 * 1024;
|
||||
// USD camera lens attributes are tenths of a scene unit. With metersPerUnit = 1
|
||||
// one tenth is 100 mm; Blender's importer multiplies by 100 * metersPerUnit.
|
||||
const MM_PER_USD_LENS_UNIT = 100;
|
||||
const clamp01 = (value) => Math.max(0, Math.min(1, value));
|
||||
|
||||
function number(value, label, min, max) {
|
||||
if (
|
||||
@@ -36,6 +29,12 @@ function number(value, label, min, max) {
|
||||
return value;
|
||||
}
|
||||
|
||||
function integer(value, label, min, max) {
|
||||
if (!Number.isInteger(number(value, label, min, max)))
|
||||
throw new RangeError(`${label} must be an integer`);
|
||||
return value;
|
||||
}
|
||||
|
||||
function position(pose, heightKey = 'alt') {
|
||||
if (!pose) throw new TypeError('A complete camera position is required');
|
||||
number(pose.lat, 'lat', -90, 90);
|
||||
@@ -48,7 +47,7 @@ function position(pose, heightKey = 'alt') {
|
||||
* The returned columns are the camera's local X (right), Y (up), Z (back),
|
||||
* which is the USD and Blender camera convention (looking down local -Z).
|
||||
*/
|
||||
export function cameraPoseToEnu(pose, origin) {
|
||||
export function cameraPoseToEnu(pose, origin, label = 'Camera') {
|
||||
position(pose);
|
||||
position(origin, 'height');
|
||||
// Short-arc sampling can pass 360 degrees even when both saved endpoints do not.
|
||||
@@ -66,8 +65,11 @@ export function cameraPoseToEnu(pose, origin) {
|
||||
origin.height,
|
||||
C.Ellipsoid.WGS84,
|
||||
);
|
||||
if (C.Cartesian3.distance(xyz, anchor) > 100000)
|
||||
throw new RangeError('Camera exceeds the 100 km local-origin limit');
|
||||
const distance = C.Cartesian3.distance(xyz, anchor);
|
||||
if (distance > 100000)
|
||||
throw new RangeError(
|
||||
`${label} is ${(distance / 1000).toFixed(1)} km from the origin (limit 100 km)`,
|
||||
);
|
||||
// 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(
|
||||
@@ -79,30 +81,15 @@ export function cameraPoseToEnu(pose, origin) {
|
||||
);
|
||||
const local = C.Matrix4.multiplyByPoint(inverse, xyz, new C.Cartesian3());
|
||||
// Same basis as Cesium Camera.setView3D, including its heading - PI/2 offset.
|
||||
const rotation = C.Matrix3.fromQuaternion(
|
||||
C.Quaternion.fromHeadingPitchRoll(
|
||||
new C.HeadingPitchRoll(
|
||||
C.Math.toRadians(pose.heading) - Math.PI / 2,
|
||||
C.Math.toRadians(pose.pitch),
|
||||
C.Math.toRadians(pose.roll),
|
||||
),
|
||||
),
|
||||
);
|
||||
const cameraFrame = C.Transforms.eastNorthUpToFixedFrame(xyz);
|
||||
const transform = (vector) =>
|
||||
C.Matrix4.multiplyByPointAsVector(
|
||||
inverse,
|
||||
C.Matrix4.multiplyByPointAsVector(
|
||||
cameraFrame,
|
||||
vector,
|
||||
new C.Cartesian3(),
|
||||
),
|
||||
new C.Cartesian3(),
|
||||
);
|
||||
const forward = transform(
|
||||
C.Matrix3.getColumn(rotation, 0, new C.Cartesian3()),
|
||||
);
|
||||
const up = transform(C.Matrix3.getColumn(rotation, 2, new C.Cartesian3()));
|
||||
const body = headingPitchRollFrame(xyz, {
|
||||
heading: C.Math.toRadians(pose.heading) - Math.PI / 2,
|
||||
pitch: C.Math.toRadians(pose.pitch),
|
||||
roll: C.Math.toRadians(pose.roll),
|
||||
});
|
||||
const toLocal = (axis) =>
|
||||
C.Matrix4.multiplyByPointAsVector(inverse, axis, new C.Cartesian3());
|
||||
const forward = toLocal(body.x);
|
||||
const up = toLocal(body.z);
|
||||
const right = C.Cartesian3.cross(forward, up, new C.Cartesian3());
|
||||
const array = (v) => [v.x, v.y, v.z];
|
||||
return {
|
||||
@@ -121,28 +108,17 @@ function identity(value, label) {
|
||||
return value;
|
||||
}
|
||||
|
||||
/** 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.
|
||||
*/
|
||||
/** Resolve each shot's runtime seconds and hold once, as Director seeking does. */
|
||||
export function sceneRuntimeTiming(
|
||||
scene,
|
||||
scenePacks = createDefaultScenePacks(),
|
||||
) {
|
||||
const byShot = new Map();
|
||||
for (const shot of scene.shots) {
|
||||
const durationSec = shotRuntimeDurationSec(scene, shot, scenePacks);
|
||||
// Same states shotRuntimeDurationSec uses; omitting them would rebuild
|
||||
// every shot's timing per call (quadratic for long scenes).
|
||||
const holdSec = effectiveShotHoldSec(
|
||||
scene,
|
||||
shot,
|
||||
scenePacks,
|
||||
runtimeLayerStatesForShot(shot, scenePacks),
|
||||
);
|
||||
number(durationSec, `Shot ${shot.id} runtime duration`, 0, 1e7);
|
||||
number(holdSec, `Shot ${shot.id} runtime hold`, 0, 1e7);
|
||||
byShot.set(shot, { durationSec, holdSec });
|
||||
const timing = shotRuntimeTiming(scene, shot, scenePacks);
|
||||
number(timing.durationSec, `Shot ${shot.id} runtime duration`, 0, 1e7);
|
||||
number(timing.holdSec, `Shot ${shot.id} runtime hold`, 0, 1e7);
|
||||
byShot.set(shot, timing);
|
||||
}
|
||||
return {
|
||||
durationFor: (_scene, shot) => byShot.get(shot).durationSec,
|
||||
@@ -168,64 +144,56 @@ export function sampleSceneCameras(
|
||||
} = {},
|
||||
) {
|
||||
validateSceneDocument(project);
|
||||
position(origin, 'height');
|
||||
for (const key of ['numerator', 'denominator']) {
|
||||
number(fps?.[key], `fps.${key}`, 1, 1000000);
|
||||
if (!Number.isInteger(fps[key]))
|
||||
throw new RangeError('fps must be a positive integer ratio');
|
||||
}
|
||||
for (const key of ['numerator', 'denominator'])
|
||||
integer(fps?.[key], `fps.${key}`, 1, 1000000);
|
||||
const rate = number(fps.numerator / fps.denominator, 'frame rate', 1, 240);
|
||||
for (const [key, value] of Object.entries({ width, height })) {
|
||||
number(value, key, 4, 16384);
|
||||
if (!Number.isInteger(value))
|
||||
throw new RangeError(`${key} must be an integer`);
|
||||
}
|
||||
integer(width, 'width', 4, 16384);
|
||||
integer(height, 'height', 4, 16384);
|
||||
number(horizontalFovDegrees, 'horizontal FOV degrees', 1, 179);
|
||||
number(sensorWidthMm, 'sensor width mm', 1, 100);
|
||||
const candidates = project.scenes.filter(
|
||||
(scene) => sceneId === undefined || scene.id === sceneId,
|
||||
);
|
||||
if (candidates.length !== 1)
|
||||
throw new Error('Select exactly one scene with sceneId');
|
||||
const scene = candidates[0];
|
||||
identity(scene.id, 'Scene');
|
||||
if (!scene.shots.length) throw new Error('Scene has no camera shots');
|
||||
const timing = sceneRuntimeTiming(scene, scenePacks);
|
||||
const frameAt = (seconds) => {
|
||||
const frame = seconds * rate;
|
||||
return (
|
||||
(Math.abs(frame - Math.round(frame)) < 1e-9
|
||||
? Math.round(frame)
|
||||
: Math.ceil(frame)) + 1
|
||||
if (candidates.length !== 1) {
|
||||
const ids = project.scenes
|
||||
.slice(0, 10)
|
||||
.map(({ id }) => id)
|
||||
.join(', ');
|
||||
throw new Error(
|
||||
sceneId === undefined
|
||||
? `Choose one scene with --scene: ${ids}`
|
||||
: `No scene has ID ${sceneId}; scenes: ${ids}`,
|
||||
);
|
||||
};
|
||||
let elapsed = 0;
|
||||
let rounding = 0;
|
||||
const resolved = scene.shots.map((shot, index) => ({
|
||||
target: resolveCameraPose(scene, shot.camera),
|
||||
previous: resolveCameraPose(
|
||||
scene,
|
||||
scene.shots[index - 1]?.camera || shot.camera,
|
||||
),
|
||||
move: resolveCameraMove(scene, shot),
|
||||
}));
|
||||
const shots = scene.shots.map((shot, index) => {
|
||||
}
|
||||
const saved = candidates[0];
|
||||
identity(saved.id, 'Scene');
|
||||
if (!saved.shots.length) throw new Error('Scene has no camera shots');
|
||||
for (const shot of saved.shots) {
|
||||
identity(shot.id, 'Shot');
|
||||
const { target: camera, move } = resolved[index];
|
||||
position(camera);
|
||||
if (move) position(move.from);
|
||||
cameraPoseToEnu(camera, origin);
|
||||
if (move) cameraPoseToEnu(move.from, origin);
|
||||
const runtimeDurationSec = timing.durationFor(scene, shot);
|
||||
const pose = resolveCameraPose(saved, shot.camera);
|
||||
if (!pose || [pose.lat, pose.lon, pose.alt].includes(undefined))
|
||||
throw new TypeError(
|
||||
`Shot ${shot.id} requires a saved position; save the scene again in GEV`,
|
||||
);
|
||||
}
|
||||
// Director seeks the normalized project: legacy numeric text becomes
|
||||
// numbers and ordinary shots fly for at least 0.2 s.
|
||||
const scene = normalizeProject({ version: project.version, scenes: [saved] })
|
||||
.scenes[0];
|
||||
const timing = sceneRuntimeTiming(scene, scenePacks);
|
||||
let elapsed = 0;
|
||||
const shots = scene.shots.map((shot) => {
|
||||
const label = `Shot ${shot.id}`;
|
||||
cameraPoseToEnu(resolveCameraPose(scene, shot.camera), origin, label);
|
||||
if (shot.move)
|
||||
cameraPoseToEnu(resolveCameraPose(scene, shot.move.from), origin, label);
|
||||
// Running sums in sceneSeekState's order, so published seconds agree
|
||||
// with the frame each shot owns.
|
||||
const startTimeSec = elapsed;
|
||||
// Compensated summation prevents long decimal timelines gaining a frame.
|
||||
const increment = runtimeDurationSec - rounding;
|
||||
const next = elapsed + increment;
|
||||
rounding = next - elapsed - increment;
|
||||
elapsed = next;
|
||||
elapsed += timing.durationFor(scene, shot);
|
||||
return {
|
||||
id: shot.id,
|
||||
title: shot.title || '',
|
||||
title: shot.title,
|
||||
...(shot.sourcePackId
|
||||
? {
|
||||
sourcePackId: shot.sourcePackId,
|
||||
@@ -234,106 +202,74 @@ export function sampleSceneCameras(
|
||||
: {}),
|
||||
startTimeSec,
|
||||
endTimeSec: elapsed,
|
||||
flightDurationSec: shot.durationSec || 4,
|
||||
authoredHoldSec: Number(shot.holdSec) || 0,
|
||||
flightDurationSec: shot.durationSec,
|
||||
authoredHoldSec: shot.holdSec,
|
||||
runtimeHoldSec: timing.holdFor(scene, shot),
|
||||
frameStart: 0,
|
||||
frameEndExclusive: 0,
|
||||
};
|
||||
});
|
||||
const frameCount = frameAt(elapsed) - 1;
|
||||
// Ceiling of duration times fps. The tolerance bounds the rounding error of
|
||||
// decimal flight and hold seconds and their sums, so only that noise at a
|
||||
// frame boundary is dropped, never a real fraction of a frame.
|
||||
const exactFrames = elapsed * rate;
|
||||
const frameCount =
|
||||
Math.abs(exactFrames - Math.round(exactFrames)) <
|
||||
Number.EPSILON * (2 * shots.length + 1) * exactFrames
|
||||
? Math.round(exactFrames)
|
||||
: Math.ceil(exactFrames);
|
||||
if (frameCount > MAX_CAMERA_FRAMES)
|
||||
throw new RangeError(`Export exceeds ${MAX_CAMERA_FRAMES} camera frames`);
|
||||
if (frameCount < 1) throw new Error('Scene has no sampled frame at this fps');
|
||||
// Mirror sceneSeekState (src/director/timeline.js) step for step, walking
|
||||
// shots forward once instead of rescanning every shot for every frame.
|
||||
// Tests compare each sample with sceneSeekState itself.
|
||||
const seekEnds = [];
|
||||
for (const shot of scene.shots)
|
||||
seekEnds.push((seekEnds.at(-1) || 0) + timing.durationFor(scene, shot));
|
||||
const seekTotalSec = seekEnds.at(-1);
|
||||
const frames = [];
|
||||
let shotIndex = 0;
|
||||
for (let frame = 1; frame <= frameCount; frame += 1) {
|
||||
const timeSec = ((frame - 1) * fps.denominator) / fps.numerator;
|
||||
const normalized = clamp01(timeSec / seekTotalSec);
|
||||
while (
|
||||
shotIndex < shots.length - 1 &&
|
||||
!(normalized < seekEnds[shotIndex] / seekTotalSec)
|
||||
)
|
||||
shotIndex += 1;
|
||||
const source = scene.shots[shotIndex];
|
||||
const startElapsedSec = shotIndex ? seekEnds[shotIndex - 1] : 0;
|
||||
const elapsedSec = Math.max(normalized * seekTotalSec, startElapsedSec);
|
||||
const flightDurationSec = source.durationSec || 4;
|
||||
const shotDurationSec = Math.max(
|
||||
0.001,
|
||||
flightDurationSec + timing.holdFor(scene, source),
|
||||
const state = sceneSeekState(
|
||||
scene,
|
||||
timeSec / elapsed,
|
||||
timing.durationFor,
|
||||
timing.holdFor,
|
||||
);
|
||||
const shotElapsedSec = Math.max(
|
||||
0,
|
||||
Math.min(shotDurationSec, elapsedSec - startElapsedSec),
|
||||
);
|
||||
const cameraProgress = clamp01(
|
||||
shotElapsedSec / Math.max(0.001, flightDurationSec),
|
||||
);
|
||||
const { target, previous, move } = resolved[shotIndex];
|
||||
const pose = move
|
||||
? sampleCameraMove(move, cameraProgress)
|
||||
: cameraAtProgress(previous, target, cameraProgress);
|
||||
const shot = shots[shotIndex];
|
||||
const shot = shots[state.shotIndex];
|
||||
if (!shot.frameStart) shot.frameStart = frame;
|
||||
shot.frameEndExclusive = frame + 1;
|
||||
frames.push({
|
||||
frame,
|
||||
timeSec,
|
||||
shotId: shot.id,
|
||||
...cameraPoseToEnu(pose, origin),
|
||||
...cameraPoseToEnu(state.camera, origin, `Shot ${shot.id}`),
|
||||
});
|
||||
}
|
||||
for (const shot of shots) {
|
||||
if (!shot.frameStart)
|
||||
throw new Error(`Shot ${shot.id} has no sampled frame at this fps`);
|
||||
}
|
||||
const horizontalFovRadians = C.Math.toRadians(horizontalFovDegrees);
|
||||
const lensMm = number(
|
||||
sensorWidthMm / (2 * Math.tan(horizontalFovRadians / 2)),
|
||||
sensorWidthMm / (2 * Math.tan(C.Math.toRadians(horizontalFovDegrees) / 2)),
|
||||
'Blender lens mm',
|
||||
1,
|
||||
10000,
|
||||
);
|
||||
return {
|
||||
schema: CAMERA_USD_SCHEMA,
|
||||
source: {
|
||||
sceneId: scene.id,
|
||||
sceneTitle: scene.title || '',
|
||||
documentVersion: project.version ?? 1,
|
||||
sampling: 'director-seek-runtime-timing',
|
||||
sceneTitle: saved.title || '',
|
||||
attributions: (scene.dataPacks || []).map(({ attribution }) =>
|
||||
structuredClone(attribution),
|
||||
),
|
||||
},
|
||||
coordinates: {
|
||||
units: 'meters',
|
||||
axes: 'east-north-up',
|
||||
heightDatum: 'WGS84-ellipsoid',
|
||||
origin: { ...origin },
|
||||
cameraAxes: 'X-right,Y-up,-Z-forward',
|
||||
origin: { lat: origin.lat, lon: origin.lon, height: origin.height },
|
||||
},
|
||||
camera: {
|
||||
projection: 'perspective',
|
||||
sensorWidthMm,
|
||||
sensorHeightMm: (sensorWidthMm * height) / width,
|
||||
lensMm,
|
||||
horizontalFovRadians,
|
||||
verticalFovRadians:
|
||||
2 * Math.atan((Math.tan(horizontalFovRadians / 2) * height) / width),
|
||||
},
|
||||
timeline: {
|
||||
fps: { ...fps },
|
||||
fps: { numerator: fps.numerator, denominator: fps.denominator },
|
||||
width,
|
||||
height,
|
||||
pixelAspect: [1, 1],
|
||||
frameStart: 1,
|
||||
frameEnd: frameCount,
|
||||
durationSec: elapsed,
|
||||
@@ -349,7 +285,6 @@ function usdNumber(value) {
|
||||
return Object.is(rounded, -0) ? '0' : String(rounded);
|
||||
}
|
||||
|
||||
/** Quote text for a .usda string literal. */
|
||||
function usdString(value) {
|
||||
return `"${String(value)
|
||||
.replace(/\\/g, '\\\\')
|
||||
@@ -380,19 +315,24 @@ function usdMatrix({ position: p, basisColumns: [right, up, back] }) {
|
||||
*/
|
||||
export function cameraSamplesToUsda(samples) {
|
||||
const { source, coordinates, camera, timeline, shots, frames } = samples;
|
||||
integer(timeline.width, 'width', 4, 16384);
|
||||
integer(timeline.height, 'height', 4, 16384);
|
||||
integer(timeline.frameStart, 'frameStart', 1, MAX_CAMERA_FRAMES);
|
||||
integer(timeline.frameEnd, 'frameEnd', 1, MAX_CAMERA_FRAMES);
|
||||
for (const shot of shots) {
|
||||
integer(shot.frameStart, 'frameStart', 1, MAX_CAMERA_FRAMES);
|
||||
integer(
|
||||
shot.frameEndExclusive,
|
||||
'frameEndExclusive',
|
||||
2,
|
||||
MAX_CAMERA_FRAMES + 1,
|
||||
);
|
||||
}
|
||||
const rate = timeline.fps.numerator / timeline.fps.denominator;
|
||||
const json = (value) => usdString(JSON.stringify(value));
|
||||
const out = [
|
||||
'#usda 1.0',
|
||||
'(',
|
||||
' customLayerData = {',
|
||||
` string gevCamera = ${json(camera)}`,
|
||||
` string gevCoordinates = ${json(coordinates)}`,
|
||||
` string gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`,
|
||||
` string gevShots = ${json(shots)}`,
|
||||
` string gevSource = ${json(source)}`,
|
||||
` string gevTimeline = ${json(timeline)}`,
|
||||
' }',
|
||||
' defaultPrim = "GEV"',
|
||||
` doc = ${usdString("God's Eye View Director cameras: ENU meters around a WGS84 ellipsoid origin; time codes are frame numbers.")}`,
|
||||
` endTimeCode = ${timeline.frameEnd}`,
|
||||
@@ -434,8 +374,8 @@ export function cameraSamplesToUsda(samples) {
|
||||
: []),
|
||||
` custom int userProperties:gevFrameStart = ${shot.frameStart}`,
|
||||
` custom int userProperties:gevFrameEndExclusive = ${shot.frameEndExclusive}`,
|
||||
` custom double userProperties:gevStartTimeSec = ${usdNumber(shot.startTimeSec)}`,
|
||||
` custom double userProperties:gevEndTimeSec = ${usdNumber(shot.endTimeSec)}`,
|
||||
` custom double userProperties:gevStartTimeSec = ${number(shot.startTimeSec, 'startTimeSec', 0, Infinity)}`,
|
||||
` custom double userProperties:gevEndTimeSec = ${number(shot.endTimeSec, 'endTimeSec', 0, Infinity)}`,
|
||||
` custom double userProperties:gevFlightDurationSec = ${usdNumber(shot.flightDurationSec)}`,
|
||||
` custom double userProperties:gevAuthoredHoldSec = ${usdNumber(shot.authoredHoldSec)}`,
|
||||
` custom double userProperties:gevRuntimeHoldSec = ${usdNumber(shot.runtimeHoldSec)}`,
|
||||
@@ -454,7 +394,6 @@ export function cameraSamplesToUsda(samples) {
|
||||
return out.join('\n');
|
||||
}
|
||||
|
||||
/** Export one saved scene as a .usda camera stage. */
|
||||
export function exportCameraUsda(project, options) {
|
||||
const samples = sampleSceneCameras(project, options);
|
||||
const usda = cameraSamplesToUsda(samples);
|
||||
|
||||
Reference in new issue
Block a user