diff --git a/.gitignore b/.gitignore index fa4008e088..11e081e7d8 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,3 @@ pinokio/.installed # Transient: a release interrupted mid-assembly (npm run changelog recovers it) changelog.d/.assembling/ - -# Optional Blender camera importer Python cache. -tools/blender/__pycache__/ diff --git a/changelog.d/1460-blender-camera-interchange.md b/changelog.d/1460-blender-camera-interchange.md index 61e348b413..207c58fdea 100644 --- a/changelog.d/1460-blender-camera-interchange.md +++ b/changelog.d/1460-blender-camera-interchange.md @@ -1,3 +1,3 @@ -- Export saved Director scenes to editable Blender cameras with a camera-only - offline manifest preserving ENU coordinates, lens and rational timing, plus - an importer and projection checks (UBN606, #1460). +- 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). diff --git a/docs/BLENDER-CAMERAS.md b/docs/BLENDER-CAMERAS.md index e93d42d88b..668939bb62 100644 --- a/docs/BLENDER-CAMERAS.md +++ b/docs/BLENDER-CAMERAS.md @@ -1,9 +1,11 @@ # GEV cameras in Blender -Export one saved Director scene into a camera-only JSON manifest, then import -editable shot cameras into a new Blender scene. This offline path requires no -API key, browser, imagery, terrain, model provider or rendering. It does not -export any tiles or geometry. Use independently licensed assets for your set. +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 @@ -15,12 +17,12 @@ Use the repository's supported Node runtime and installed dependencies. Save a Director project as JSON, then run from the repository root: ```sh -node tools/export-blender-camera.mjs --input scene.json --output cameras.json --scene my-scene-id --origin 39.7,-105,1600 --fps 30000/1001 --width 1920 --height 1080 --horizontal-fov-deg 70 +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 ``` Quote paths containing spaces. Omit `--scene` only when the document contains -exactly one scene. Output must be a new file; the tool refuses to overwrite it. -No environment files are read. +exactly one scene. Output 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 @@ -41,91 +43,104 @@ 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 the CLI also enforces 64 MiB. Every shot needs at least -one sampled frame. +to 100,000 frames and 64 MiB. Every shot needs at least one sampled frame. ## Timing and camera semantics -Sampling uses GEV's Director **seek** interpolation and authored timing. 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. +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 +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. + +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`. The bridge does not reproduce Cesium's implicit live `flyTo` trajectory, -provider readiness, registered data-pack timing overrides, runtime layer holds, -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. +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`. Fractional -shot boundaries switch at the first sampled time at or after the boundary. -Both authored seconds and sampled frame ranges are retained. +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`, 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_`, `Shot_002_` 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 and as JSON in the layer's + `customLayerData`. No referenced assets are fetched. ## Import into Blender -The importer is a standalone Python file using the standard library and -Blender's bundled Python API. Tested with Blender 5.2.2 LTS; other versions -need their own check before use. +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. +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**). -```sh -blender --background --factory-startup --disable-autoexec --threads 1 --python-exit-code 1 --python tools/blender/camera_import.py -- cameras.json cameras.blend -``` +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`. -Both paths after `--` are required. Choose a new filename ending in lowercase -`.blend`; a missing or different extension is rejected before creating a scene. The importer -validates the entire manifest before changing Blender data and creates a new -scene, preserving existing scenes. It adds an identity ENU origin object, -one perspective camera per shot, sampled location/quaternion keyframes and -camera-bound timeline markers. Camera local X points right, local Y points up, -and local negative Z looks forward. Scene X/Y/Z are east/north/up, in meters. -Sensor fit is explicitly horizontal. Quaternion signs are kept continuous and -keyframe interpolation is linear between sampled frames. +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. -Scene custom properties `gev_source`, `gev_coordinates` and `gev_timeline` -preserve geographic, attribution and rational-fps metadata. Camera custom -properties preserve source scene/shot IDs, titles, pack identifiers, endpoints -and authored timing. Source data-pack attributions are retained as text; no -referenced assets are fetched. The original fps ratio is preserved exactly in -metadata; Blender's `fps_base` is floating point, so its effective rate has a -small representation error. Cameras use a 0.01 m near plane and 200 km far -plane; adjust clipping for your separately authored set if needed. - -For an existing Blender session, load this trusted module and call -`import_file(path)`; it also creates and selects a new scene. When writing your -own headless checks, activate that scene before evaluating its animation. - -## Reproducible, provider-free check - -Use a fresh output directory for each run. These commands create synthetic -camera data, run standard Python validation, import the actual cameras, compare -landmark projection to a separate Cesium Camera oracle, then save/reopen a -`.blend` and repeat. They do not render or launch a browser. +## Checks ```sh node --test src/tooling/blenderCamera.test.mjs -python tools/blender/test_camera_import.py -node tools/blender/make_fixture.mjs --output output/blender-camera-check -blender --background --factory-startup --disable-autoexec --threads 1 --python-exit-code 1 --python tools/blender/check_import.py -- output/blender-camera-check ``` -The check covers moving and held cameras, nonzero roll, scene-local tangent -frames, a cut, landscape/portrait projection, rational fps, source metadata, -timeline marker selection, rejected malformed input and preservation of existing -scenes. `blender-receipt.json` records measured projection error and Blender -version. A successful run prints `BLENDER_CAMERA_PROJECTION_OK`. - -Camera keys are allocated in batches per animation channel. A synthetic -single-camera capacity check on Windows with Blender 5.2.2 LTS imported all -100,000 supported frames (700,000 location/quaternion keys) in 1.42 seconds, -saved in 0.19 seconds and reopened in 0.06 seconds. It checked every channel's -key count and linear interpolation, plus the first, middle and last camera -poses before saving and after reopening. These timings measure camera-data -import, without rendering. +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. Run the repository's normal unit, build, format and boundary checks too. The contribution guide additionally requires live tracking/browser checks before diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index f74cbb2aba..a489331ae0 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -647,14 +647,14 @@ 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 ENU meter camera samples with an explicit WGS84 ellipsoid -origin, horizontal lens and rational fps. It reuses Director seek interpolation -and authored timing; runtime layer timing, implicit live flyTo paths, imagery -and geometry are outside this camera-only format. The Python importer creates -a separate editable scene with per-shot cameras and timeline markers. -The synthetic `tools/blender/check_import.py` check compares actual Blender -projection and saved-file reload against a separate Cesium Camera oracle -without rendering or provider access. +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. Realtime voice composes separate connection, response/tool, Radio handoff, input and audio-meter, cost, viewport-context and diagnostic owners. The existing diff --git a/scripts/format-scope.json b/scripts/format-scope.json index f2c43139d8..a40feb990c 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -1,7 +1,6 @@ [ "src/tooling/blenderCamera.test.mjs", "tools/export-blender-camera.mjs", - "tools/blender/make_fixture.mjs", ".prettierrc.json", "package.json", "scripts/format-scope.json", diff --git a/src/scenes/shotPresentation.js b/src/scenes/shotPresentation.js index 04759fc3fb..1c27b5d6ff 100644 --- a/src/scenes/shotPresentation.js +++ b/src/scenes/shotPresentation.js @@ -153,8 +153,8 @@ export function effectiveShotHoldSec( ); } -/** Estimate flight plus effective hold without mutating saved layer parameters. */ -export function shotRuntimeDurationSec(scene, shot, packs) { +/** Copy a shot's layer states with registered runtime controls, without mutating saved parameters. */ +export function runtimeLayerStatesForShot(shot, packs) { const states = deepClone(shot?.layers || {}); const sourceRecipe = packs.recipeForShot(shot); for (const state of Object.values(states)) { @@ -168,8 +168,18 @@ export function shotRuntimeDurationSec(scene, shot, packs) { }; } } + return states; +} + +/** Estimate flight plus effective hold without mutating saved layer parameters. */ +export function shotRuntimeDurationSec(scene, shot, packs) { return ( (shot?.durationSec || DEFAULT_SHOT_DURATION_SEC) + - effectiveShotHoldSec(scene, shot, packs, states) + effectiveShotHoldSec( + scene, + shot, + packs, + runtimeLayerStatesForShot(shot, packs), + ) ); } diff --git a/src/tooling/blenderCamera.js b/src/tooling/blenderCamera.js index e90c4861cf..b7f14f934d 100644 --- a/src/tooling/blenderCamera.js +++ b/src/tooling/blenderCamera.js @@ -1,4 +1,4 @@ -/** Camera-only interchange. No viewer, providers, environment files or terrain access. */ +/** Camera-only USD interchange. No viewer, providers, environment files or terrain access. */ import * as C from 'cesium'; import { validateSceneDocument } from '../director/document.js'; import { @@ -7,9 +7,20 @@ import { sampleCameraMove, } from '../director/camera.js'; import { cameraAtProgress } from '../director/timeline.js'; +import { + effectiveShotHoldSec, + runtimeLayerStatesForShot, + shotRuntimeDurationSec, +} from '../scenes/shotPresentation.js'; +import { createDefaultScenePacks } from '../scenes/packs/defaults.js'; -export const CAMERA_MANIFEST_SCHEMA = 'gev.camera-manifest.v1'; +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; +const clamp01 = (value) => Math.max(0, Math.min(1, value)); function number(value, label, min, max) { if ( @@ -34,7 +45,8 @@ function position(pose, heightKey = 'alt') { /** 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 Blender's local X (right), Y (up), Z (back). + * 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) { position(pose); @@ -105,11 +117,40 @@ function identity(value, label) { return value; } -/** Export one existing scene using Director seek interpolation and authored timing. +/** Resolve the flight-plus-hold seconds and holds that Director playback and seeking use. + * Both come from shotPresentation.js, so registered pack overrides, minimum holds and + * evidence-sequence durations match the app instead of the saved holdSec alone. + */ +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 }); + } + 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 playback 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 exportCameraManifest( +export function sampleSceneCameras( project, { sceneId, @@ -119,6 +160,7 @@ export function exportCameraManifest( height, horizontalFovDegrees, sensorWidthMm = 36, + scenePacks = createDefaultScenePacks(), } = {}, ) { validateSceneDocument(project); @@ -144,6 +186,7 @@ export function exportCameraManifest( 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 ( @@ -154,6 +197,14 @@ export function exportCameraManifest( }; 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) => { identity(shot.id, 'Shot'); const camera = resolveCameraPose(scene, shot.camera); @@ -162,18 +213,13 @@ export function exportCameraManifest( if (move) position(move.from); cameraPoseToEnu(camera, origin); if (move) cameraPoseToEnu(move.from, origin); - const durationSec = shot.durationSec || 4; - const holdSec = shot.holdSec || 0; + const runtimeDurationSec = timing.durationFor(scene, shot); const startTimeSec = elapsed; // Compensated summation prevents long decimal timelines gaining a frame. - const increment = durationSec + holdSec - rounding; + const increment = runtimeDurationSec - rounding; const next = elapsed + increment; rounding = next - elapsed - increment; elapsed = next; - const frameStart = frameAt(startTimeSec); - const frameEndExclusive = frameAt(elapsed); - if (frameStart >= frameEndExclusive) - throw new Error(`Shot ${shot.id} has no sampled frame at this fps`); return { id: shot.id, title: shot.title || '', @@ -185,41 +231,56 @@ export function exportCameraManifest( : {}), startTimeSec, endTimeSec: elapsed, - durationSec, - holdSec, - frameStart, - frameEndExclusive, - camera, - move, + flightDurationSec: shot.durationSec || 4, + authoredHoldSec: Number(shot.holdSec) || 0, + runtimeHoldSec: timing.holdFor(scene, shot), + frameStart: 0, + frameEndExclusive: 0, }; }); const frameCount = frameAt(elapsed) - 1; 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 ( - frame >= shots[shotIndex].frameEndExclusive && - shotIndex < shots.length - 1 + shotIndex < shots.length - 1 && + !(normalized < seekEnds[shotIndex] / seekTotalSec) ) shotIndex += 1; - const shot = shots[shotIndex]; - const timeSec = ((frame - 1) * fps.denominator) / fps.numerator; - const progress = Math.max( - 0, - Math.min( - 1, - (timeSec - shot.startTimeSec) / Math.max(0.001, shot.durationSec), - ), + 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 pose = shot.move - ? sampleCameraMove(shot.move, progress) - : cameraAtProgress( - shots[shotIndex - 1]?.camera || shot.camera, - shot.camera, - progress, - ); + 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]; + if (!shot.frameStart) shot.frameStart = frame; + shot.frameEndExclusive = frame + 1; frames.push({ frame, timeSec, @@ -227,6 +288,10 @@ export function exportCameraManifest( ...cameraPoseToEnu(pose, origin), }); } + 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)), @@ -235,12 +300,12 @@ export function exportCameraManifest( 10000, ); return { - schema: CAMERA_MANIFEST_SCHEMA, + schema: CAMERA_USD_SCHEMA, source: { sceneId: scene.id, sceneTitle: scene.title || '', documentVersion: project.version ?? 1, - sampling: 'director-seek-authored-timing', + sampling: 'director-seek-runtime-timing', attributions: (scene.dataPacks || []).map(({ attribution }) => structuredClone(attribution), ), @@ -254,8 +319,8 @@ export function exportCameraManifest( }, camera: { projection: 'perspective', - sensorFit: 'HORIZONTAL', sensorWidthMm, + sensorHeightMm: (sensorWidthMm * height) / width, lensMm, horizontalFovRadians, verticalFovRadians: @@ -274,3 +339,149 @@ export function exportCameraManifest( frames, }; } + +/** Shortest decimal for a finite double, without signed zero or 17-digit noise. */ +function usdNumber(value) { + const rounded = Number(value.toPrecision(15)); + return Object.is(rounded, -0) ? '0' : String(rounded); +} + +/** Quote text for a .usda string literal. */ +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; + 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', + '(', + ' customLayerData = {', + ` string gevCamera = ${json(camera)}`, + ` string gevCoordinates = ${json(coordinates)}`, + ` string gevSchema = ${usdString(CAMERA_USD_SCHEMA)}`, + ` string gevShots = ${json(shotTable)}`, + ` 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}`, + ` 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 = ${usdNumber(shot.startTimeSec)}`, + ` custom double userProperties:gevEndTimeSec = ${usdNumber(shot.endTimeSec)}`, + ` 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 one saved scene as a .usda camera stage. */ +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 }; +} diff --git a/src/tooling/blenderCamera.test.mjs b/src/tooling/blenderCamera.test.mjs index 4507e2f5df..523719634f 100644 --- a/src/tooling/blenderCamera.test.mjs +++ b/src/tooling/blenderCamera.test.mjs @@ -13,10 +13,17 @@ import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; import { spawnSync } from 'node:child_process'; import { sceneSeekState } from '../director/timeline.js'; +import { + effectiveShotHoldSec, + shotRuntimeDurationSec, +} from '../scenes/shotPresentation.js'; +import { createDefaultScenePacks } from '../scenes/packs/defaults.js'; +import { createScenePackRegistry } from '../scenes/packs/registry.js'; const adapter = await import('./blenderCamera.js'); -test('a portable camera manifest adapter exists', () => { - assert.equal(typeof adapter.exportCameraManifest, 'function'); +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 }; @@ -46,7 +53,7 @@ const project = ( const near = (a, b, eps = 1e-8) => a.forEach((v, i) => assert.ok(Math.abs(v - b[i]) < eps, `${a} != ${b}`)); const camera = (changes = {}, opts = {}) => - adapter.exportCameraManifest( + adapter.sampleSceneCameras( project([{ id: 'camera', durationSec: 1, camera: pose(changes) }]), options(opts), ).frames[0]; @@ -129,12 +136,11 @@ test('explicit horizontal lens works for landscape and portrait output', () => { [1920, 1080], [1080, 1920], ]) { - const m = adapter.exportCameraManifest( - project(), - options({ width, height }), - ); + const m = adapter.sampleSceneCameras(project(), options({ width, height })); assert.ok(Math.abs(m.camera.lensMm - 18) < 1e-10); - assert.equal(m.camera.sensorFit, 'HORIZONTAL'); + assert.ok( + Math.abs(m.camera.sensorHeightMm - (36 * height) / width) < 1e-10, + ); assert.ok( Math.abs(m.camera.verticalFovRadians - 2 * Math.atan(height / width)) < 1e-10, @@ -142,7 +148,7 @@ test('explicit horizontal lens works for landscape and portrait output', () => { } }); -test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON round trip', () => { +test('anchors, cubic moves, cuts, holds and rational frame timing are sampled', () => { const p = project([ { id: 'move', @@ -173,7 +179,7 @@ test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON r altitudeReference: 'ellipsoid', }, ]; - const m = adapter.exportCameraManifest( + const m = adapter.sampleSceneCameras( p, options({ origin: { lat: 0, lon: 180, height: 0 }, @@ -190,7 +196,6 @@ test('anchors, cubic moves, cuts, holds and rational frame timing survive JSON r assert.equal(m.frames[18].shotId, 'cut'); assert.equal(m.frames[18].timeSec, (18 * 1001) / 30000); near(m.frames[12].position, m.frames[17].position); - assert.deepEqual(JSON.parse(JSON.stringify(m)), m); assert.equal(p.scenes[0].shots[0].camera.anchorId, 'end'); }); @@ -202,20 +207,18 @@ test('invalid or ambiguous input fails before export', () => { { origin: { lat: 0, lon: NaN, height: 0 } }, { horizontalFovDegrees: 180 }, ]) { - assert.throws(() => - adapter.exportCameraManifest(project(), options(change)), - ); + assert.throws(() => adapter.sampleSceneCameras(project(), options(change))); } assert.throws(() => camera({ lon: 20 }), /100 km/); const multiple = project(); multiple.scenes.push({ ...multiple.scenes[0], id: 'other' }); assert.throws( - () => adapter.exportCameraManifest(multiple, options()), + () => adapter.sampleSceneCameras(multiple, options()), /scene/i, ); assert.throws( () => - adapter.exportCameraManifest( + adapter.sampleSceneCameras( project([{ id: 'missing', camera: { heading: 0 } }]), options(), ), @@ -223,7 +226,7 @@ test('invalid or ambiguous input fails before export', () => { ); assert.throws( () => - adapter.exportCameraManifest( + adapter.sampleSceneCameras( project([{ id: 'long', camera: pose(), durationSec: 86400 }]), options(), ), @@ -233,12 +236,12 @@ test('invalid or ambiguous input fails before export', () => { test('projection settings cannot be silently clamped by Blender', () => { assert.throws( - () => adapter.exportCameraManifest(project(), options({ width: 1 })), + () => adapter.sampleSceneCameras(project(), options({ width: 1 })), /width/, ); assert.throws( () => - adapter.exportCameraManifest( + adapter.sampleSceneCameras( project(), options({ horizontalFovDegrees: 179, sensorWidthMm: 1 }), ), @@ -261,7 +264,7 @@ test('every exported sample agrees with Director seeking at fractional shot boun holdSec: 0.13, }, ]); - const m = adapter.exportCameraManifest(p, options()); + const m = adapter.sampleSceneCameras(p, options()); assert.equal(m.frames.length, 21); for (const sample of m.frames) { const state = sceneSeekState( @@ -283,7 +286,7 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio const directory = mkdtempSync(join(tmpdir(), 'gev camera ')); try { const input = join(directory, 'saved scene.json'); - const output = join(directory, 'camera manifest.json'); + const output = join(directory, 'camera stage.usda'); writeFileSync(input, JSON.stringify(project())); const script = fileURLToPath( new URL('../../tools/export-blender-camera.mjs', import.meta.url), @@ -309,11 +312,21 @@ test('CLI works in paths with spaces and refuses overwrites or invalid projectio assert.equal(first.status, 0, first.stderr); assert.match(first.stdout, /CAMERA_EXPORT_OK/); const contents = readFileSync(output, 'utf8'); - assert.equal(JSON.parse(contents).timeline.fps.denominator, 1001); + assert.match(contents, /^#usda 1\.0\n/); + assert.match(contents, /userProperties:gevFps = "30000\/1001"/); const repeat = spawnSync(process.execPath, args, { encoding: 'utf8' }); assert.equal(repeat.status, 1); assert.equal(readFileSync(output, 'utf8'), contents); - const invalidOutput = join(directory, 'invalid.json'); + const jsonOutput = join(directory, 'cameras.json'); + const wrongExtension = [...args]; + wrongExtension[wrongExtension.indexOf(output)] = jsonOutput; + const rejected = spawnSync(process.execPath, wrongExtension, { + encoding: 'utf8', + }); + assert.equal(rejected.status, 1); + assert.match(rejected.stderr, /\.usda/); + assert.equal(existsSync(jsonOutput), false); + const invalidOutput = join(directory, 'invalid.usda'); const invalid = [...args]; invalid[invalid.indexOf(output)] = invalidOutput; invalid[invalid.length - 1] = '180'; @@ -337,7 +350,7 @@ test('ordinary submillisecond shots retain the Director seek duration floor', () holdSec: 0.1, }, ]); - const m = adapter.exportCameraManifest(p, options()); + const m = adapter.sampleSceneCameras(p, options()); const sample = m.frames[1]; const state = sceneSeekState( p.scenes[0], @@ -360,8 +373,221 @@ test('long decimal timelines do not gain a rounding-only frame', () => { camera: pose(), })), ); - const m = adapter.exportCameraManifest(p, options()); + const m = adapter.sampleSceneCameras(p, options()); assert.equal(m.timeline.durationSec, 1000); assert.equal(m.frames.length, 30000); assert.equal(m.shots[9999].frameEndExclusive, 30001); }); + +const runtimeSeek = (scene, timeSec, durationSec, packs) => + sceneSeekState( + scene, + timeSec / durationSec, + (s, shot) => shotRuntimeDurationSec(s, shot, packs), + (s, shot) => effectiveShotHoldSec(s, shot, packs), + ); + +test('shot timing follows Director runtime holds, not only the saved holdSec', () => { + // The Director's Mailung trim plays a 7.65 s hold although 15 s was saved. + const p = project([ + { + id: 'mailung', + sourcePackId: 'bhote-koshi-nepal-evidence-pack', + durationSec: 4.2, + holdSec: 15, + camera: pose(), + layers: { + 'bhote-koshi-2026': { + enabled: true, + params: { presentation: 'scene-beat', beatId: 'mailung-bazzar' }, + }, + }, + }, + { id: 'next', durationSec: 1, holdSec: 0, camera: pose({ heading: 90 }) }, + ]); + const before = structuredClone(p); + const m = adapter.sampleSceneCameras(p, options()); + const [first, second] = m.shots; + assert.equal(first.authoredHoldSec, 15); + assert.equal(first.runtimeHoldSec, 7.65); + assert.equal(second.startTimeSec, 4.2 + 7.65); + // Summing authored holds would start the next shot 7.35 s (220 frames) later. + assert.equal(second.frameStart, Math.ceil((4.2 + 7.65) * 30) + 1); + assert.equal(m.timeline.durationSec, 4.2 + 7.65 + 1); + const packs = createDefaultScenePacks(); + p.scenes[0].shots.forEach((shot, i) => + assert.equal( + m.shots[i].runtimeHoldSec, + effectiveShotHoldSec(p.scenes[0], shot, packs), + ), + ); + for (const sample of m.frames) { + const state = runtimeSeek( + p.scenes[0], + sample.timeSec, + m.timeline.durationSec, + packs, + ); + assert.equal(sample.shotId, state.shot.id); + const expected = adapter.cameraPoseToEnu(state.camera, origin); + near(sample.position, expected.position); + sample.basisColumns.forEach((axis, i) => + near(axis, expected.basisColumns[i]), + ); + } + assert.deepEqual(p, before, 'export never rewrites saved shots'); +}); + +test('registered minimum holds and evidence-sequence durations shift later shots', () => { + const packs = createScenePackRegistry({ + recipes: [ + { + id: 'sample', + runtimeControlsByBeat: { + arrival: { evidenceSequence: true, evidenceSequenceDurationSec: 2.5 }, + }, + }, + ], + adapters: [ + { minimumHoldSec: (states) => (states.overview?.enabled ? 3 : 0) }, + ], + }); + const p = project([ + { + id: 'evidence', + sourcePackId: 'sample', + durationSec: 1, + holdSec: 0.5, + camera: pose(), + layers: { + sample: { + enabled: true, + params: { presentation: 'scene-beat', beatId: 'arrival' }, + }, + }, + }, + { + id: 'overview', + durationSec: 1, + holdSec: 0, + camera: pose({ heading: 45 }), + layers: { overview: { enabled: true, params: {} } }, + }, + { id: 'last', durationSec: 1, holdSec: 0, camera: pose({ heading: 90 }) }, + ]); + const m = adapter.sampleSceneCameras(p, options({ scenePacks: packs })); + assert.deepEqual( + m.shots.map((s) => [s.startTimeSec, s.runtimeHoldSec, s.frameStart]), + [ + [0, 2.5, 1], + [3.5, 3, 106], + [7.5, 0, 226], + ], + ); + assert.equal(m.frames.length, 255); + // The holds match the Director's own seek path, which resolves layer states itself. + p.scenes[0].shots.forEach((shot, i) => + assert.equal( + m.shots[i].runtimeHoldSec, + effectiveShotHoldSec(p.scenes[0], shot, packs), + ), + ); + for (const sample of m.frames) { + assert.equal( + sample.shotId, + runtimeSeek(p.scenes[0], sample.timeSec, m.timeline.durationSec, packs) + .shot.id, + ); + } +}); + +const usdNumbers = (text) => + text.match(/-?\d+(?:\.\d+)?(?:e[-+]?\d+)?/g).map(Number); + +test('USD stage is Z-up meters with one camera per shot and per-frame matrices', () => { + const p = project([ + { + id: 'first shot', + title: 'He said "hi"\n', + durationSec: 0.2, + holdSec: 0, + camera: pose({ heading: 30, roll: 10, alt: 50 }), + }, + { + id: 'second', + durationSec: 0.1, + holdSec: 0, + camera: pose({ heading: 200, lon: 0.0005, pitch: -30 }), + }, + ]); + const { usda, samples } = adapter.exportCameraUsda(p, options()); + assert.match(usda, /^#usda 1\.0\n/); + for (const line of [ + 'upAxis = "Z"', + 'metersPerUnit = 1', + 'startTimeCode = 1', + `endTimeCode = ${samples.timeline.frameEnd}`, + 'timeCodesPerSecond = 30', + 'framesPerSecond = 30', + 'defaultPrim = "GEV"', + ]) + assert.ok(usda.includes(`\n ${line}\n`), line); + assert.match(usda, /string gevSchema = "gev\.camera-usd\.v1"/); + const cameras = usda.split('\n def Camera ').slice(1); + assert.equal(cameras.length, 2); + assert.match(cameras[0], /^"Shot_001_first_shot"/); + assert.match(cameras[1], /^"Shot_002_second"/); + // USD lens values are tenths of a scene unit (100 mm at metersPerUnit 1): + // a 90 degree horizontal FOV on a 36 mm sensor is an 18 mm lens. + assert.match(cameras[0], /\n {8}float focalLength = 0\.18\n/); + assert.match(cameras[0], /\n {8}float horizontalAperture = 0\.36\n/); + assert.match(cameras[0], /\n {8}float verticalAperture = 0\.2025\n/); + assert.match(cameras[0], /\n {8}token projection = "perspective"\n/); + assert.ok( + cameras[0].includes( + 'custom string userProperties:gevShotTitle = "He said \\"hi\\"\\n"', + ), + ); + assert.ok( + cameras[0].includes( + 'custom string userProperties:gevShotId = "first shot"', + ), + ); + cameras.forEach((text, index) => { + const shot = samples.shots[index]; + const keys = [...text.matchAll(/\n {12}(\d+): \((.*)\),/g)]; + assert.deepEqual( + keys.map(([, key]) => Number(key)), + Array.from( + { length: shot.frameEndExclusive - shot.frameStart }, + (_, i) => shot.frameStart + i, + ), + ); + for (const [, key, matrix] of keys) { + const values = usdNumbers(matrix); + const frame = samples.frames[Number(key) - 1]; + assert.equal(frame.shotId, shot.id); + const [right, up, back] = frame.basisColumns; + near(values, [...right, 0, ...up, 0, ...back, 0, ...frame.position, 1]); + } + assert.match( + text, + /uniform token\[\] xformOpOrder = \["xformOp:transform"\]/, + ); + }); +}); + +test('USD stage records rational fps and portrait apertures', () => { + const { usda, samples } = adapter.exportCameraUsda( + project(), + options({ + width: 1080, + height: 1920, + fps: { numerator: 30000, denominator: 1001 }, + }), + ); + assert.ok(usda.includes(`\n timeCodesPerSecond = ${30000 / 1001}\n`)); + assert.ok(usda.includes('userProperties:gevFps = "30000/1001"')); + assert.match(usda, /float verticalAperture = 0\.64\n/); + assert.equal(samples.timeline.frameEnd, 30); +}); diff --git a/tools/README.md b/tools/README.md index 88b40ad0e7..4c8618ac5d 100644 --- a/tools/README.md +++ b/tools/README.md @@ -6,11 +6,11 @@ automatically. ## Offline Blender camera interchange -`export-blender-camera.mjs` exports cameras from a saved Director scene; -`blender/camera_import.py` imports an editable rig into a new Blender scene. -These tools require no key, environment file, browser or network access and -export no imagery or geometry. Usage, format and synthetic projection checks: -[Blender cameras](../docs/BLENDER-CAMERAS.md). +`export-blender-camera.mjs` exports the cameras of a saved Director scene as a +plain-text USD stage (`.usda`) that Blender opens with File > Import > +Universal Scene Description. It requires no key, environment file, browser, +network access or Blender add-on, and exports no imagery or geometry. Usage, +format and lens units: [Blender cameras](../docs/BLENDER-CAMERAS.md). Output files go to `output/` by default (gitignored). diff --git a/tools/blender/camera_import.py b/tools/blender/camera_import.py deleted file mode 100644 index 134bd33368..0000000000 --- a/tools/blender/camera_import.py +++ /dev/null @@ -1,287 +0,0 @@ -"""Import camera-only GEV JSON. Python validation needs no Blender installation. - -Blender console: import camera_import; camera_import.import_file('/path/camera.json') -CLI: blender --background --factory-startup --disable-autoexec --threads 1 - --python tools/blender/camera_import.py -- camera.json output.blend -No image, geometry, network access or rendering is performed. -""" -import json -import math -from pathlib import Path -import sys - -SCHEMA = "gev.camera-manifest.v1" -MAX_BYTES = 64 * 1024 * 1024 -MAX_FRAMES = 100000 - - -def _number(value, label, low, high, integer=False): - if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value): - raise ValueError(f"{label}: expected a finite number") - if not low <= value <= high or (integer and int(value) != value): - raise ValueError(f"{label}: outside supported range") - return int(value) if integer else value - - -def _text(value, label): - if not isinstance(value, str) or not value.strip() or len(value) > 4096: - raise ValueError(f"{label}: expected a nonempty string") - return value - - -def _near(actual, expected, label, tolerance=1e-8): - if not math.isclose(actual, expected, rel_tol=1e-10, abs_tol=tolerance): - raise ValueError(f"{label}: does not match the declared timing or projection") - - -def _vector(value, label): - if not isinstance(value, list) or len(value) != 3: - raise ValueError(f"{label}: expected three coordinates") - for component in value: - _number(component, label, -100001, 100001) - return value - - -def _dot(a, b): - return sum(x * y for x, y in zip(a, b)) - - -def _cross(a, b): - return [a[1]*b[2]-a[2]*b[1], a[2]*b[0]-a[0]*b[2], a[0]*b[1]-a[1]*b[0]] - - -def _frame_at(seconds, rate): - value = seconds * rate - return (round(value) if abs(value - round(value)) < 1e-9 else math.ceil(value)) + 1 - - -def validate_manifest(data): - """Validate the complete data before importing bpy or mutating a scene.""" - if not isinstance(data, dict) or data.get("schema") != SCHEMA: - raise ValueError("Unsupported GEV camera manifest schema") - source = data["source"] - _text(source["sceneId"], "scene ID") - if source.get("sampling") != "director-seek-authored-timing": - raise ValueError("Unsupported camera sampling semantics") - coordinates = data["coordinates"] - required = {"units": "meters", "axes": "east-north-up", "heightDatum": "WGS84-ellipsoid", "cameraAxes": "X-right,Y-up,-Z-forward"} - if any(coordinates.get(key) != value for key, value in required.items()): - raise ValueError("Explicit ENU meters, WGS84 ellipsoid and Blender camera axes required") - origin = coordinates["origin"] - for key, low, high in [("lat", -90, 90), ("lon", -180, 180), ("height", -12000, 1e9)]: - _number(origin[key], f"origin.{key}", low, high) - timeline = data["timeline"] - fps = timeline["fps"] - for key in ["numerator", "denominator"]: - _number(fps[key], f"fps.{key}", 1, 1000000, integer=True) - rate = _number(fps["numerator"] / fps["denominator"], "fps", 1, 240) - for key in ["width", "height"]: - _number(timeline[key], key, 4, 16384, integer=True) - if timeline["pixelAspect"] != [1, 1] or any(isinstance(value, bool) for value in timeline["pixelAspect"]): - raise ValueError("Only square pixels are supported") - if timeline["frameStart"] != 1 or isinstance(timeline["frameStart"], bool): - raise ValueError("Timeline must start at frame 1") - count = _number(timeline["frameEnd"], "frameEnd", 1, MAX_FRAMES, integer=True) - _number(timeline["durationSec"], "durationSec", 0, 100000) - if count != _frame_at(timeline["durationSec"], rate) - 1: - raise ValueError("Frame count differs from declared duration and fps") - camera = data["camera"] - if camera["projection"] != "perspective" or camera["sensorFit"] != "HORIZONTAL": - raise ValueError("Only a perspective horizontal-sensor camera is supported") - sensor = _number(camera["sensorWidthMm"], "sensorWidthMm", 1, 100) - hfov = _number(camera["horizontalFovRadians"], "horizontalFovRadians", math.pi/180, math.pi*179/180) - lens = _number(camera["lensMm"], "lensMm", 1, 10000) - _near(lens, sensor / (2 * math.tan(hfov / 2)), "lens") - _near(_number(camera["verticalFovRadians"], "verticalFovRadians", 0, math.pi), 2 * math.atan(math.tan(hfov / 2) * timeline["height"] / timeline["width"]), "vertical FOV") - shots = data["shots"] - if not isinstance(shots, list) or not 1 <= len(shots) <= count: - raise ValueError("Expected bounded nonempty shots") - ids = set() - elapsed = 0 - rounding = 0 - for shot in shots: - shot_id = _text(shot["id"], "shot ID") - if shot_id in ids: - raise ValueError("Duplicate shot ID") - ids.add(shot_id) - for key in ["startTimeSec", "endTimeSec", "durationSec", "holdSec"]: - _number(shot[key], key, 0, 100000) - if shot["durationSec"] <= 0: - raise ValueError("Shot duration must be positive") - _near(shot["startTimeSec"], elapsed, "shot start") - increment = shot["durationSec"] + shot["holdSec"] - rounding - next_time = elapsed + increment - rounding = next_time - elapsed - increment - elapsed = next_time - _near(shot["endTimeSec"], elapsed, "shot end") - for key, expected in [("frameStart", _frame_at(shot["startTimeSec"], rate)), ("frameEndExclusive", _frame_at(elapsed, rate))]: - _number(shot[key], key, 1, count + 1, integer=True) - if shot[key] != expected: - raise ValueError("Shot frame boundaries do not match timing") - if shot["frameStart"] >= shot["frameEndExclusive"]: - raise ValueError("Shot has no sampled frames") - _near(elapsed, timeline["durationSec"], "total duration") - frames = data["frames"] - if not isinstance(frames, list) or len(frames) != count: - raise ValueError("Frame count differs from frame samples") - shot_index = 0 - for index, sample in enumerate(frames, start=1): - if sample["frame"] != index or isinstance(sample["frame"], bool): - raise ValueError("Frames must be sequential integers starting at 1") - _near(_number(sample["timeSec"], "timeSec", 0, 100000), (index - 1) * fps["denominator"] / fps["numerator"], "sample time") - while index >= shots[shot_index]["frameEndExclusive"] and shot_index < len(shots) - 1: - shot_index += 1 - if sample["shotId"] != shots[shot_index]["id"]: - raise ValueError("Sample references the wrong shot") - location = _vector(sample["position"], "position") - if _dot(location, location) > 100000**2 + 0.01: - raise ValueError("Camera exceeds 100 km local-origin limit") - basis = sample["basisColumns"] - if not isinstance(basis, list) or len(basis) != 3: - raise ValueError("Expected three camera basis columns") - x, y, z = [_vector(column, "basis") for column in basis] - for column in [x, y, z]: - _near(_dot(column, column), 1, "unit camera axis", 1e-6) - for a, b in [(x, y), (y, z), (z, x)]: - _near(_dot(a, b), 0, "orthogonal camera axes", 1e-6) - _near(_dot(_cross(x, y), z), 1, "right-handed camera basis", 1e-6) - return data - - -def read_manifest(path): - """Read bounded JSON only. No imports, URLs or expressions are evaluated.""" - with Path(path).open("rb") as stream: - payload = stream.read(MAX_BYTES + 1) - if len(payload) > MAX_BYTES: - raise ValueError("Camera manifest exceeds 64 MiB") - return validate_manifest(json.loads(payload)) - - -def _camera_curves(camera): - """Read this camera's curves from current slotted or older legacy actions.""" - action = camera.animation_data.action - if hasattr(action, "layers") and action.layers: - for layer in action.layers: - for strip in layer.strips: - bag = strip.channelbag(camera.animation_data.action_slot) - if bag: - yield from bag.fcurves - else: - yield from action.fcurves - - -def _write_camera_keys(camera, samples): - """Allocate each F-Curve once, avoiding repeated insertion/handle updates.""" - first = samples[0] - camera.location = first[1] - camera.rotation_quaternion = first[2] - # Let Blender create the appropriate action/slot for its own API version. - camera.keyframe_insert(data_path="location", frame=first[0]) - camera.keyframe_insert(data_path="rotation_quaternion", frame=first[0]) - for curve in _camera_curves(camera): - channel = 1 if curve.data_path == "location" else 2 - component = curve.array_index - coordinates = [value for frame, location, rotation in samples - for value in (frame, (location if channel == 1 else rotation)[component])] - points = curve.keyframe_points - points.clear() - points.add(len(samples)) - points.foreach_set("co", coordinates) - # Keep the exact sampled motion, rather than Blender's default Bezier. - for key in points: - key.interpolation = "LINEAR" - curve.update() - - -def import_manifest(data): - """Create a new scene with editable per-shot cameras; preserve existing scenes.""" - validate_manifest(data) - import bpy - from mathutils import Matrix - - scene = bpy.data.scenes.new(f"GEV {data['source'].get('sceneTitle') or data['source']['sceneId']}") - scene.unit_settings.system = "METRIC" - scene.unit_settings.scale_length = 1.0 - timeline = data["timeline"] - rate = timeline["fps"]["numerator"] / timeline["fps"]["denominator"] - scene.render.fps = round(rate) - scene.render.fps_base = round(rate) / rate - scene.render.resolution_x = int(timeline["width"]) - scene.render.resolution_y = int(timeline["height"]) - scene.render.resolution_percentage = 100 - scene.render.pixel_aspect_x = scene.render.pixel_aspect_y = 1.0 - scene.frame_start = 1 - scene.frame_end = int(timeline["frameEnd"]) - scene["gev_schema"] = SCHEMA - scene["gev_source"] = json.dumps(data["source"], ensure_ascii=False) - scene["gev_coordinates"] = json.dumps(data["coordinates"], ensure_ascii=False) - scene["gev_timeline"] = json.dumps(timeline) - root = bpy.data.objects.new("GEV ENU origin", None) - scene.collection.objects.link(root) - cameras = {} - for shot in data["shots"]: - camera_data = bpy.data.cameras.new(f"GEV {shot['id']}") - camera_data.type = "PERSP" - camera_data.sensor_fit = "HORIZONTAL" - camera_data.sensor_width = data["camera"]["sensorWidthMm"] - camera_data.lens = data["camera"]["lensMm"] - camera_data.clip_start = 0.01 - camera_data.clip_end = 200000 - camera = bpy.data.objects.new(f"GEV {shot['id']}", camera_data) - camera.rotation_mode = "QUATERNION" - camera.parent = root - camera["gev_shot"] = json.dumps(shot, ensure_ascii=False) - camera["gev_scene_id"] = data["source"]["sceneId"] - scene.collection.objects.link(camera) - cameras[shot["id"]] = camera - marker = scene.timeline_markers.new(f"GEV {shot['id']}", frame=int(shot["frameStart"])) - marker.camera = camera - previous = {} - keys = {shot_id: [] for shot_id in cameras} - for sample in data["frames"]: - # Manifest vectors are columns, while mathutils.Matrix accepts rows. - basis = Matrix(sample["basisColumns"]).transposed() - rotation = basis.to_quaternion().normalized() - old = previous.get(sample["shotId"]) - if old is not None and rotation.dot(old) < 0: - rotation.negate() - previous[sample["shotId"]] = rotation.copy() - keys[sample["shotId"]].append((sample["frame"], sample["position"], tuple(rotation))) - for shot_id, camera in cameras.items(): - _write_camera_keys(camera, keys[shot_id]) - scene.camera = cameras[data["shots"][0]["id"]] - if bpy.context.window: - bpy.context.window.scene = scene - scene.frame_set(1) - return scene - - -def import_file(path): - """Import a camera JSON file into a new Blender scene without rendering.""" - return import_manifest(read_manifest(path)) - - -def new_blend_output(path): - """Require Blender's final extension before checking overwrite protection.""" - output = Path(path).resolve() - if output.suffix != '.blend': - raise ValueError('Output must end in lowercase .blend') - if output.exists(): - raise FileExistsError('Output already exists; choose a new .blend path') - return output - - -if __name__ == "__main__": - args = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else [] - if len(args) != 2: - raise SystemExit("Usage: blender --background --factory-startup --disable-autoexec --threads 1 --python camera_import.py -- camera.json output.blend") - output = new_blend_output(args[1]) - import_file(args[0]) - import bpy - preview = bpy.context.preferences.filepaths.file_preview_type - try: - bpy.context.preferences.filepaths.file_preview_type = 'NONE' - bpy.ops.wm.save_as_mainfile(filepath=str(output.resolve()), check_existing=False) - finally: - bpy.context.preferences.filepaths.file_preview_type = preview - print("CAMERA_IMPORT_OK") diff --git a/tools/blender/check_import.py b/tools/blender/check_import.py deleted file mode 100644 index 1026965b44..0000000000 --- a/tools/blender/check_import.py +++ /dev/null @@ -1,147 +0,0 @@ -"""Synthetic CPU-only Blender import, projection and .blend round-trip check. - -blender --background --factory-startup --disable-autoexec --threads 1 - --python tools/blender/check_import.py -- fixture-directory -No renderer or GPU context is requested. All landmarks are synthetic empties. -""" -import importlib.util -import json -from pathlib import Path -import sys - -import bpy -from bpy_extras.object_utils import world_to_camera_view -from mathutils import Vector - -spec = importlib.util.spec_from_file_location("camera_import", Path(__file__).with_name("camera_import.py")) -importer = importlib.util.module_from_spec(spec) -spec.loader.exec_module(importer) -args = sys.argv[sys.argv.index("--") + 1:] -if len(args) != 1: - raise SystemExit("Expected one fixture directory") -directory = Path(args[0]) -reference = json.loads((directory / "projection-reference.json").read_text()) -original_names = set(bpy.data.scenes.keys()) -original_settings = {scene.name: (scene.render.resolution_x, scene.render.resolution_y, scene.frame_end) for scene in bpy.data.scenes} -bpy.context.preferences.filepaths.file_preview_type = 'NONE' - - -def block(scene, name, center, size): - """Tiny owned synthetic blockout, so the saved rig has an editable set.""" - x, y, z = center - sx, sy, sz = [value / 2 for value in size] - vertices = [(x+dx*sx, y+dy*sy, z+dz*sz) for dx, dy, dz in [(-1,-1,-1),(1,-1,-1),(1,1,-1),(-1,1,-1),(-1,-1,1),(1,-1,1),(1,1,1),(-1,1,1)]] - faces = [(0,3,2,1),(4,5,6,7),(0,1,5,4),(1,2,6,5),(2,3,7,6),(3,0,4,7)] - mesh = bpy.data.meshes.new(name) - mesh.from_pydata(vertices, [], faces) - mesh.update() - obj = bpy.data.objects.new(name, mesh) - scene.collection.objects.link(obj) - - -cases = [] -for case in reference["cases"]: - manifest = importer.read_manifest(directory / case["manifest"]) - scene = importer.import_manifest(manifest) - # All validation occurs before bpy mutation. - malformed = json.loads(json.dumps(manifest)) - malformed["frames"][-1]["basisColumns"][0] = [2, 0, 0] - names = set(bpy.data.scenes.keys()) - objects = set(bpy.data.objects.keys()) - try: - importer.import_manifest(malformed) - raise AssertionError("Malformed transform was accepted") - except ValueError: - assert set(bpy.data.scenes.keys()) == names - assert set(bpy.data.objects.keys()) == objects - for index, point in enumerate(case["checks"][0]["points"]): - landmark = bpy.data.objects.new(f"Synthetic landmark {index}", None) - landmark.location = point["position"] - scene.collection.objects.link(landmark) - block(scene, 'Synthetic ground, no map data', [0, 0, -1], [1400, 1400, 2]) - for index in [0, 6, 9]: - sample = manifest['frames'][index] - point = case['checks'][index]['points'][0]['position'] - direction = [(point[i]-sample['position'][i])/100 for i in range(3)] - distance = -sample['position'][2]/direction[2] - center = [sample['position'][i]+direction[i]*distance for i in range(2)] + [10] - block(scene, f'Synthetic block {index}', center, [24, 24, 20]) - cases.append((case, manifest, scene.name)) - -# JSON may spell an integer-valued number as 1920.0. Blender RNA requires ints. -float_case = dict(reference['cases'][0], name='integer-valued JSON floats') -float_manifest = importer.read_manifest(directory / float_case['manifest']) -for key in ['width', 'height', 'frameEnd']: - float_manifest['timeline'][key] = float(float_manifest['timeline'][key]) -for shot in float_manifest['shots']: - shot['frameStart'] = float(shot['frameStart']) -float_scene = importer.import_manifest(float_manifest) -cases.append((float_case, float_manifest, float_scene.name)) - - -def check_all(): - max_error = 0.0 - projection_count = 0 - for case, manifest, scene_name in cases: - scene = bpy.data.scenes[scene_name] - bpy.context.window.scene = scene - bpy.context.view_layer.update() - metadata = json.loads(scene["gev_source"]) - assert metadata["sceneId"] == manifest["source"]["sceneId"] - assert json.loads(scene["gev_coordinates"]) == manifest["coordinates"] - assert json.loads(scene["gev_timeline"]) == manifest["timeline"] - assert scene.frame_start == 1 and scene.frame_end == len(manifest["frames"]) - expected_rate = manifest["timeline"]["fps"]["numerator"] / manifest["timeline"]["fps"]["denominator"] - assert abs(scene.render.fps / scene.render.fps_base - expected_rate) < 2e-6 - assert scene.unit_settings.scale_length == 1 - assert scene.render.resolution_x == manifest["timeline"]["width"] - assert scene.render.resolution_y == manifest["timeline"]["height"] - cameras = {json.loads(obj["gev_shot"])["id"]: obj for obj in scene.objects if "gev_shot" in obj} - assert set(cameras) == {shot["id"] for shot in manifest["shots"]} - for shot in manifest["shots"]: - camera = cameras[shot["id"]] - assert json.loads(camera["gev_shot"]) == shot - expected_frames = [sample["frame"] for sample in manifest["frames"] if sample["shotId"] == shot["id"]] - curves = list(importer._camera_curves(camera)) - assert len(curves) == 7, "Expected three location and four quaternion channels" - for curve in curves: - assert [key.co[0] for key in curve.keyframe_points] == expected_frames - assert all(key.interpolation == "LINEAR" for key in curve.keyframe_points) - for item in case["checks"]: - scene.frame_set(item["frame"]) - active = scene.camera - camera = cameras[item["shotId"]] - assert active == camera, "Timeline marker selected the wrong camera" - assert camera.data.sensor_fit == "HORIZONTAL" - assert abs(camera.data.lens - manifest["camera"]["lensMm"]) < 1e-5 - for point in item["points"]: - projected = world_to_camera_view(scene, camera, Vector(point["position"])) - assert projected.z > 0, (case['name'], item['frame'], 'landmark behind camera') - error = max(abs(projected.x - point["uv"][0]), abs(projected.y - point["uv"][1])) - max_error = max(error, max_error) - assert error < 2e-5, (case["name"], item["frame"], error) - projection_count += 1 - for name in original_names: - scene = bpy.data.scenes[name] - assert (scene.render.resolution_x, scene.render.resolution_y, scene.frame_end) == original_settings[name] - return max_error, projection_count - - -before_error, count = check_all() -blend = directory / "synthetic-cameras.blend" -if blend.exists(): - raise SystemExit("Synthetic output already exists; choose a fresh fixture directory") -bpy.context.window.scene = bpy.data.scenes[cases[0][2]] -bpy.context.scene.frame_set(1) -for area in bpy.context.screen.areas: - if area.type == 'VIEW_3D': - area.spaces.active.region_3d.view_perspective = 'CAMERA' -bpy.ops.wm.save_as_mainfile(filepath=str(blend.resolve()), check_existing=False) -assert blend.stat().st_size > 10000 -bpy.ops.wm.open_mainfile(filepath=str(blend.resolve()), load_ui=False, use_scripts=False) -assert bpy.context.scene.name == cases[0][2], 'Demo must reopen on the blockout scene' -after_error, after_count = check_all() -assert after_count == count -receipt = {"state": "BLENDER_CAMERA_PROJECTION_OK", "blenderVersion": bpy.app.version_string, "cases": len(cases), "projectionsBeforeSave": count, "projectionsAfterReload": after_count, "maxUvError": max(before_error, after_error), "rendered": False, "gpuRequested": False, "blend": blend.name} -(directory / "blender-receipt.json").write_text(json.dumps(receipt, indent=2) + "\n") -print(json.dumps(receipt)) diff --git a/tools/blender/make_fixture.mjs b/tools/blender/make_fixture.mjs deleted file mode 100644 index 0eab273670..0000000000 --- a/tools/blender/make_fixture.mjs +++ /dev/null @@ -1,173 +0,0 @@ -#!/usr/bin/env node -/** Generate tiny, provider-free fixtures plus an independent Cesium projection oracle. */ -import { mkdir, writeFile } from 'node:fs/promises'; -import { resolve } from 'node:path'; -import { parseArgs } from 'node:util'; -import * as C from 'cesium'; -import { exportCameraManifest } from '../../src/tooling/blenderCamera.js'; -import { sceneSeekState } from '../../src/director/timeline.js'; - -const { values } = parseArgs({ options: { output: { type: 'string' } } }); -if (!values.output) - throw new Error( - 'Usage: node tools/blender/make_fixture.mjs --output directory', - ); -const output = resolve(values.output); -await mkdir(output, { recursive: true }); -const pose = (values) => ({ - lat: 39.7003, - lon: -105.0004, - alt: 1750, - heading: 20, - pitch: -25, - roll: 17, - altitudeReference: 'ellipsoid', - ...values, -}); -const finish = pose({ - lat: 39.7005, - lon: -104.9995, - alt: 1800, - heading: 95, - pitch: -40, - roll: -25, -}); -const cut = pose({ - lat: 39.6998, - lon: -105.0003, - alt: 1725, - heading: 230, - pitch: -15, - roll: 35, -}); -const document = { - version: 6, - scenes: [ - { - id: 'synthetic-scene', - title: 'Synthetic camera bridge', - shots: [ - { - id: 'rolled-move', - title: 'Move and hold', - durationSec: 0.2, - holdSec: 0.1, - camera: finish, - move: { from: pose({}), easing: 'cubic-in-out' }, - }, - { - id: 'cut', - title: 'Explicit cut and hold', - durationSec: 0.2, - holdSec: 0.1, - camera: cut, - move: { from: cut, easing: 'linear' }, - }, - ], - }, - ], -}; -const origin = { lat: 39.7, lon: -105, height: 1600 }; -const anchor = C.Cartesian3.fromDegrees(origin.lon, origin.lat, origin.height); -const worldToLocal = C.Matrix4.inverseTransformation( - C.Transforms.eastNorthUpToFixedFrame(anchor), - new C.Matrix4(), -); -const cases = []; -for (const [name, width, height] of [ - ['landscape', 1920, 1080], - ['portrait', 1080, 1920], -]) { - const manifest = exportCameraManifest(document, { - origin, - fps: { numerator: 30000, denominator: 1001 }, - width, - height, - horizontalFovDegrees: 70, - }); - await writeFile( - resolve(output, `${name}.camera.json`), - JSON.stringify(manifest, null, 2) + '\n', - ); - const camera = new C.Camera({ - drawingBufferWidth: width, - drawingBufferHeight: height, - mapProjection: new C.GeographicProjection(), - mode: C.SceneMode.SCENE3D, - }); - camera.frustum.aspectRatio = width / height; - camera.frustum.fov = - width >= height - ? manifest.camera.horizontalFovRadians - : manifest.camera.verticalFovRadians; - camera.frustum.near = 0.01; - camera.frustum.far = 200000; - const checks = []; - for (const sample of manifest.frames) { - const state = sceneSeekState( - document.scenes[0], - sample.timeSec / manifest.timeline.durationSec, - (_scene, shot) => shot.durationSec + shot.holdSec, - (_scene, shot) => shot.holdSec, - ); - const p = state.camera; - camera.setView({ - destination: C.Cartesian3.fromDegrees(p.lon, p.lat, p.alt), - orientation: { - heading: C.Math.toRadians(p.heading), - pitch: C.Math.toRadians(p.pitch), - roll: C.Math.toRadians(p.roll), - }, - }); - const projectionView = C.Matrix4.multiply( - camera.frustum.projectionMatrix, - camera.viewMatrix, - new C.Matrix4(), - ); - const points = []; - for (const [right, up] of [ - [0, 0], - [25, 0], - [-25, 15], - [0, -20], - ]) { - const world = C.Cartesian3.clone(camera.positionWC); - for (const [axis, distance] of [ - [camera.directionWC, 100], - [camera.rightWC, right], - [camera.upWC, up], - ]) { - C.Cartesian3.add( - world, - C.Cartesian3.multiplyByScalar(axis, distance, new C.Cartesian3()), - world, - ); - } - const clip = C.Matrix4.multiplyByVector( - projectionView, - new C.Cartesian4(world.x, world.y, world.z, 1), - new C.Cartesian4(), - ); - const local = C.Matrix4.multiplyByPoint( - worldToLocal, - world, - new C.Cartesian3(), - ); - points.push({ - position: [local.x, local.y, local.z], - uv: [(clip.x / clip.w + 1) / 2, (clip.y / clip.w + 1) / 2], - }); - } - checks.push({ frame: sample.frame, shotId: sample.shotId, points }); - } - cases.push({ name, manifest: `${name}.camera.json`, checks }); -} -await writeFile( - resolve(output, 'scene.json'), - JSON.stringify(document, null, 2) + '\n', -); -await writeFile( - resolve(output, 'projection-reference.json'), - JSON.stringify({ origin, cases }, null, 2) + '\n', -); -console.log('CAMERA_FIXTURE_OK'); diff --git a/tools/blender/test_camera_import.py b/tools/blender/test_camera_import.py deleted file mode 100644 index 2f2b262dea..0000000000 --- a/tools/blender/test_camera_import.py +++ /dev/null @@ -1,91 +0,0 @@ -"""Data validation checks. Standard Python only; no Blender or rendering required.""" -import copy -import importlib.util -import math -from pathlib import Path -import sys -import tempfile -import unittest - -module_path = Path(__file__).with_name("camera_import.py") -if module_path.exists(): - spec = importlib.util.spec_from_file_location("camera_import", module_path) - importer = importlib.util.module_from_spec(spec) - spec.loader.exec_module(importer) -else: - importer = None - - -def fixture(): - return { - "schema": "gev.camera-manifest.v1", - "source": {"sceneId": "scene", "sceneTitle": "Fixture", "sampling": "director-seek-authored-timing", "attributions": []}, - "coordinates": {"units": "meters", "axes": "east-north-up", "heightDatum": "WGS84-ellipsoid", "origin": {"lat": 0, "lon": 0, "height": 0}, "cameraAxes": "X-right,Y-up,-Z-forward"}, - "camera": {"projection": "perspective", "sensorFit": "HORIZONTAL", "sensorWidthMm": 36, "lensMm": 18, "horizontalFovRadians": math.pi / 2, "verticalFovRadians": math.pi / 2}, - "timeline": {"fps": {"numerator": 30, "denominator": 1}, "width": 100, "height": 100, "pixelAspect": [1, 1], "frameStart": 1, "frameEnd": 1, "durationSec": 1 / 30}, - "shots": [{"id": "north", "title": "North", "startTimeSec": 0, "endTimeSec": 1 / 30, "durationSec": 1 / 30, "holdSec": 0, "frameStart": 1, "frameEndExclusive": 2}], - "frames": [{"frame": 1, "timeSec": 0, "shotId": "north", "position": [0, 0, 0], "basisColumns": [[1, 0, 0], [0, 0, 1], [0, -1, 0]]}], - } - - -class ValidationTests(unittest.TestCase): - def test_validator_exists(self): - self.assertIsNotNone(importer, "camera importer is missing") - - def test_valid_manifest_is_not_mutated_and_does_not_import_bpy(self): - data = fixture() - before = copy.deepcopy(data) - importer.validate_manifest(data) - self.assertEqual(data, before) - self.assertNotIn("bpy", sys.modules) - - def test_rejects_datum_axes_lens_fps_and_timing_mismatches(self): - mutations = [ - lambda m: m.update(schema="other"), - lambda m: m["coordinates"].update(heightDatum="MSL"), - lambda m: m["coordinates"].update(axes="north-east-down"), - lambda m: m["camera"].update(lensMm=35), - lambda m: m["camera"].update(lensMm=0.5), - lambda m: m["camera"].update(verticalFovRadians=1), - lambda m: m["timeline"]["fps"].update(denominator=0), - lambda m: m["timeline"].update(frameEnd=2), - lambda m: m["timeline"].update(width=1), - lambda m: m["timeline"].update(pixelAspect=[2, 1]), - lambda m: m["frames"][0].update(frame=2), - lambda m: m["frames"][0].update(timeSec=1), - lambda m: m["frames"][0].update(shotId="missing"), - lambda m: m["shots"][0].update(frameStart=2), - lambda m: m["shots"][0].update(endTimeSec=2), - lambda m: m["frames"][0].update(position=[100001, 0, 0]), - lambda m: m["frames"][0].update(position=[False, 0, 0]), - lambda m: m["frames"][0].update(position=[math.nan, 0, 0]), - lambda m: m["frames"][0].update(basisColumns=[[1, 0, 0], [1, 0, 0], [0, 0, 1]]), - lambda m: m["frames"][0].update(basisColumns=[[-1, 0, 0], [0, 0, 1], [0, -1, 0]]), - ] - for mutate in mutations: - data = fixture() - mutate(data) - with self.subTest(mutation=mutations.index(mutate)): - with self.assertRaises((ValueError, TypeError, KeyError)): - importer.validate_manifest(data) - - def test_output_extension_is_checked_before_existing_file_guard(self): - with tempfile.TemporaryDirectory(prefix='gev-blender-output-') as directory: - output = Path(directory) / 'camera.blend' - output.write_bytes(b'existing file must survive') - with self.assertRaises(ValueError): - importer.new_blend_output(Path(directory) / 'camera') - with self.assertRaises(FileExistsError): - importer.new_blend_output(output) - with self.assertRaises(ValueError): - importer.new_blend_output(Path(directory) / 'new.BLEND') - self.assertEqual(output.read_bytes(), b'existing file must survive') - self.assertEqual(importer.new_blend_output(Path(directory) / 'new.blend').name, 'new.blend') - - -if __name__ == "__main__": - result = unittest.main(exit=False) - if result.result.wasSuccessful(): - print("IMPORT_VALIDATION_OK") - else: - sys.exit(1) diff --git a/tools/export-blender-camera.mjs b/tools/export-blender-camera.mjs index d0e13c2f1f..e482aa52e5 100644 --- a/tools/export-blender-camera.mjs +++ b/tools/export-blender-camera.mjs @@ -1,12 +1,12 @@ #!/usr/bin/env node -/** Offline scene-to-camera manifest CLI. Reads JSON only; never loads .env or a viewer. */ +/** Offline scene-to-USD camera CLI. Reads JSON only; never loads .env or a viewer. */ import { readFile, writeFile, stat } from 'node:fs/promises'; import { parseArgs } from 'node:util'; import { parseSceneDocument, SCENE_DOCUMENT_LIMITS, } from '../src/director/document.js'; -import { exportCameraManifest } from '../src/tooling/blenderCamera.js'; +import { exportCameraUsda } from '../src/tooling/blenderCamera.js'; try { const { values } = parseArgs({ @@ -25,7 +25,7 @@ try { }); if (values.help) { console.log( - 'Usage: node tools/export-blender-camera.mjs --input scene.json --output camera.json --origin lat,lon,ellipsoidHeight --fps 30 (or 30000/1001) --width 1920 --height 1080 --horizontal-fov-deg 60 [--scene id] [--sensor-width-mm 36]', + 'Usage: node tools/export-blender-camera.mjs --input scene.json --output cameras.usda --origin lat,lon,ellipsoidHeight --fps 30 (or 30000/1001) --width 1920 --height 1080 --horizontal-fov-deg 60 [--scene id] [--sensor-width-mm 36]', ); } else { for (const key of [ @@ -39,6 +39,8 @@ try { ]) { if (!values[key]?.trim()) throw new Error(`Missing --${key}; use --help`); } + if (!values.output.endsWith('.usda')) + throw new Error('output must be a new file ending in .usda'); if (!/^\d+(?:\/\d+)?$/.test(values.fps)) throw new Error('fps must be an integer or integer ratio'); const originParts = values.origin.split(','); @@ -49,7 +51,7 @@ try { const document = parseSceneDocument(await readFile(values.input, 'utf8')); const [numerator, denominator = 1] = values.fps.split('/').map(Number); const [lat, lon, height] = originParts.map(Number); - const manifest = exportCameraManifest(document, { + const { usda, samples } = exportCameraUsda(document, { sceneId: values.scene, origin: { lat, lon, height }, fps: { numerator, denominator }, @@ -58,12 +60,9 @@ try { horizontalFovDegrees: Number(values['horizontal-fov-deg']), sensorWidthMm: Number(values['sensor-width-mm']), }); - const json = JSON.stringify(manifest, null, 2) + '\n'; - if (Buffer.byteLength(json) > 64 * 1024 * 1024) - throw new Error('Camera manifest exceeds 64 MiB'); - await writeFile(values.output, json, { flag: 'wx' }); + await writeFile(values.output, usda, { flag: 'wx' }); console.log( - `CAMERA_EXPORT_OK: ${manifest.shots.length} shots, ${manifest.frames.length} frames`, + `CAMERA_EXPORT_OK: ${samples.shots.length} shots, ${samples.frames.length} frames`, ); } } catch (error) {