mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-20 18:22:25 +00:00
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.
404 lines
15 KiB
JavaScript
404 lines
15 KiB
JavaScript
/** 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 } 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';
|
|
export const MAX_CAMERA_FRAMES = 100000;
|
|
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;
|
|
|
|
function number(value, label, min, max) {
|
|
if (
|
|
typeof value !== 'number' ||
|
|
!Number.isFinite(value) ||
|
|
value < min ||
|
|
value > max
|
|
) {
|
|
throw new RangeError(
|
|
`${label} must be a finite number in [${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);
|
|
number(pose.lon, 'lon', -180, 180);
|
|
number(pose[heightKey], heightKey, -12000, 1e9);
|
|
}
|
|
|
|
/** Convert Cesium's WGS84/heading-pitch-roll pose to a fixed Blender ENU frame.
|
|
* Angles are degrees; alt and origin.height are WGS84 ellipsoid meters.
|
|
* 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, label = 'Camera') {
|
|
position(pose);
|
|
position(origin, 'height');
|
|
// Short-arc sampling can pass 360 degrees even when both saved endpoints do not.
|
|
for (const key of ['heading', 'roll']) number(pose[key], key, -720, 720);
|
|
number(pose.pitch, 'pitch', -90, 90);
|
|
const xyz = C.Cartesian3.fromDegrees(
|
|
pose.lon,
|
|
pose.lat,
|
|
pose.alt,
|
|
C.Ellipsoid.WGS84,
|
|
);
|
|
const anchor = C.Cartesian3.fromDegrees(
|
|
origin.lon,
|
|
origin.lat,
|
|
origin.height,
|
|
C.Ellipsoid.WGS84,
|
|
);
|
|
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(
|
|
C.Cartesian3.fromDegrees(origin.lon, origin.lat, 0, C.Ellipsoid.WGS84),
|
|
);
|
|
const inverse = C.Matrix4.inverseTransformation(
|
|
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.
|
|
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 {
|
|
position: array(local),
|
|
basisColumns: [
|
|
array(right),
|
|
array(up),
|
|
array(C.Cartesian3.negate(forward, new C.Cartesian3())),
|
|
],
|
|
};
|
|
}
|
|
|
|
function identity(value, label) {
|
|
if (typeof value !== 'string' || !value.trim())
|
|
throw new TypeError(`${label} requires a saved ID`);
|
|
return value;
|
|
}
|
|
|
|
/** 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 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,
|
|
holdFor: (_scene, shot) => byShot.get(shot).holdSec,
|
|
};
|
|
}
|
|
|
|
/** 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.
|
|
*/
|
|
export function sampleSceneCameras(
|
|
project,
|
|
{
|
|
sceneId,
|
|
origin,
|
|
fps,
|
|
width,
|
|
height,
|
|
horizontalFovDegrees,
|
|
sensorWidthMm = 36,
|
|
scenePacks = createDefaultScenePacks(),
|
|
} = {},
|
|
) {
|
|
validateSceneDocument(project);
|
|
for (const key of ['numerator', 'denominator'])
|
|
integer(fps?.[key], `fps.${key}`, 1, 1000000);
|
|
const rate = number(fps.numerator / fps.denominator, 'frame rate', 1, 240);
|
|
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) {
|
|
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}`,
|
|
);
|
|
}
|
|
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 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;
|
|
elapsed += timing.durationFor(scene, shot);
|
|
return {
|
|
id: shot.id,
|
|
title: shot.title,
|
|
...(shot.sourcePackId
|
|
? {
|
|
sourcePackId: shot.sourcePackId,
|
|
sourcePackVersion: shot.sourcePackVersion ?? null,
|
|
}
|
|
: {}),
|
|
startTimeSec,
|
|
endTimeSec: elapsed,
|
|
flightDurationSec: shot.durationSec,
|
|
authoredHoldSec: shot.holdSec,
|
|
runtimeHoldSec: timing.holdFor(scene, shot),
|
|
frameStart: 0,
|
|
frameEndExclusive: 0,
|
|
};
|
|
});
|
|
// 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');
|
|
const frames = [];
|
|
for (let frame = 1; frame <= frameCount; frame += 1) {
|
|
const timeSec = ((frame - 1) * fps.denominator) / fps.numerator;
|
|
const state = sceneSeekState(
|
|
scene,
|
|
timeSec / elapsed,
|
|
timing.durationFor,
|
|
timing.holdFor,
|
|
);
|
|
const shot = shots[state.shotIndex];
|
|
if (!shot.frameStart) shot.frameStart = frame;
|
|
shot.frameEndExclusive = frame + 1;
|
|
frames.push({
|
|
frame,
|
|
timeSec,
|
|
shotId: shot.id,
|
|
...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 lensMm = number(
|
|
sensorWidthMm / (2 * Math.tan(C.Math.toRadians(horizontalFovDegrees) / 2)),
|
|
'Blender lens mm',
|
|
1,
|
|
10000,
|
|
);
|
|
return {
|
|
source: {
|
|
sceneId: scene.id,
|
|
sceneTitle: saved.title || '',
|
|
attributions: (scene.dataPacks || []).map(({ attribution }) =>
|
|
structuredClone(attribution),
|
|
),
|
|
},
|
|
coordinates: {
|
|
origin: { lat: origin.lat, lon: origin.lon, height: origin.height },
|
|
},
|
|
camera: {
|
|
sensorWidthMm,
|
|
sensorHeightMm: (sensorWidthMm * height) / width,
|
|
lensMm,
|
|
},
|
|
timeline: {
|
|
fps: { numerator: fps.numerator, denominator: fps.denominator },
|
|
width,
|
|
height,
|
|
frameStart: 1,
|
|
frameEnd: frameCount,
|
|
durationSec: elapsed,
|
|
},
|
|
shots,
|
|
frames,
|
|
};
|
|
}
|
|
|
|
/** 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);
|
|
}
|
|
|
|
function usdString(value) {
|
|
return `"${String(value)
|
|
.replace(/\\/g, '\\\\')
|
|
.replace(/"/g, '\\"')
|
|
.replace(/\n/g, '\\n')
|
|
.replace(/\r/g, '\\r')
|
|
.replace(/\t/g, '\\t')
|
|
.replace(
|
|
/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g,
|
|
(char) => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`,
|
|
)}"`;
|
|
}
|
|
|
|
/** USD prim names are identifiers; saved IDs stay in custom properties. */
|
|
function shotPrimName(shot, index) {
|
|
const safe = shot.id.replace(/[^A-Za-z0-9_]/g, '_').slice(0, 40);
|
|
return `Shot_${String(index + 1).padStart(3, '0')}_${safe}`;
|
|
}
|
|
|
|
/** USD matrices are row-vector: rows are camera X, Y, Z axes, then translation. */
|
|
function usdMatrix({ position: p, basisColumns: [right, up, back] }) {
|
|
const row = (values, w) => `(${[...values, w].map(usdNumber).join(', ')})`;
|
|
return `( ${row(right, 0)}, ${row(up, 0)}, ${row(back, 0)}, ${row(p, 1)} )`;
|
|
}
|
|
|
|
/** Write sampled cameras as a plain-text USD stage that Blender imports natively.
|
|
* Z-up meters, one perspective camera per shot, time codes equal to frame numbers.
|
|
*/
|
|
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',
|
|
'(',
|
|
' 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}`,
|
|
` framesPerSecond = ${rate}`,
|
|
' metersPerUnit = 1',
|
|
` startTimeCode = ${timeline.frameStart}`,
|
|
` timeCodesPerSecond = ${rate}`,
|
|
' upAxis = "Z"',
|
|
')',
|
|
'',
|
|
'def Xform "GEV"',
|
|
'{',
|
|
` custom string userProperties:gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`,
|
|
` custom string userProperties:gevSceneId = ${usdString(source.sceneId)}`,
|
|
` custom string userProperties:gevSceneTitle = ${usdString(source.sceneTitle)}`,
|
|
` custom string userProperties:gevOrigin = ${json(coordinates.origin)}`,
|
|
` custom string userProperties:gevFps = ${usdString(`${timeline.fps.numerator}/${timeline.fps.denominator}`)}`,
|
|
` custom int userProperties:gevWidth = ${timeline.width}`,
|
|
` custom int userProperties:gevHeight = ${timeline.height}`,
|
|
` custom string userProperties:gevAttributions = ${json(source.attributions)}`,
|
|
];
|
|
shots.forEach((shot, index) => {
|
|
out.push(
|
|
'',
|
|
` def Camera ${usdString(shotPrimName(shot, index))}`,
|
|
' {',
|
|
' float2 clippingRange = (0.01, 200000)',
|
|
` float focalLength = ${usdNumber(camera.lensMm / MM_PER_USD_LENS_UNIT)}`,
|
|
` float horizontalAperture = ${usdNumber(camera.sensorWidthMm / MM_PER_USD_LENS_UNIT)}`,
|
|
` float verticalAperture = ${usdNumber(camera.sensorHeightMm / MM_PER_USD_LENS_UNIT)}`,
|
|
' token projection = "perspective"',
|
|
` custom string userProperties:gevShotId = ${usdString(shot.id)}`,
|
|
` custom string userProperties:gevShotTitle = ${usdString(shot.title)}`,
|
|
...(shot.sourcePackId
|
|
? [
|
|
` custom string userProperties:gevSourcePackId = ${usdString(shot.sourcePackId)}`,
|
|
` custom string userProperties:gevSourcePackVersion = ${usdString(shot.sourcePackVersion ?? '')}`,
|
|
]
|
|
: []),
|
|
` custom int userProperties:gevFrameStart = ${shot.frameStart}`,
|
|
` custom int userProperties:gevFrameEndExclusive = ${shot.frameEndExclusive}`,
|
|
` 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)}`,
|
|
' matrix4d xformOp:transform.timeSamples = {',
|
|
);
|
|
for (let f = shot.frameStart; f < shot.frameEndExclusive; f += 1) {
|
|
out.push(` ${f}: ${usdMatrix(frames[f - 1])},`);
|
|
}
|
|
out.push(
|
|
' }',
|
|
' uniform token[] xformOpOrder = ["xformOp:transform"]',
|
|
' }',
|
|
);
|
|
});
|
|
out.push('}', '');
|
|
return out.join('\n');
|
|
}
|
|
|
|
export function exportCameraUsda(project, options) {
|
|
const samples = sampleSceneCameras(project, options);
|
|
const usda = cameraSamplesToUsda(samples);
|
|
if (Buffer.byteLength(usda) > MAX_CAMERA_USDA_BYTES)
|
|
throw new RangeError('Camera USD exceeds 64 MiB');
|
|
return { usda, samples };
|
|
}
|