@photivra/engine 1.4.0 → 2.0.0

package/dist/motion/projected-motion.js

@@ -1,19 +1,26 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Calculates sensor-plane motion during an exposure using ideal rectilinear projection and constant
- * linear object velocity. Without focusDistanceM, nominal focal length is the backwards-compatible
- * pinhole projection distance. With focusDistanceM, the selected thin-lens sensor-plane image distance
- * is used. The calculation projects the object's shutter-open and shutter-close positions onto the
- * image plane and measures the displacement between them. It therefore handles lateral and
- * depth-direction motion without relying on a generic "subject speed" category.
- * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * How far a moving object travels across the sensor during an exposure. Uses ideal rectilinear
+ * projection and a constant straight-line object velocity.
+ * - Without focusDistanceM, the projection distance is the nominal focal length (the older pinhole
+ *   behaviour).
+ * - With focusDistanceM, it is the thin-lens image distance for that focus.
+ *
+ * The object's positions when the shutter opens and closes are both projected onto the image plane,
+ * and the distance between them is measured. So sideways motion and motion toward or away from the
+ * camera are both handled, without a generic "subject speed" category.
+ * @see docs/MOTION_AND_SIGNAL.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { calculatedResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
+import { portableHypot } from "../core/portable-math.js";
 import { calculateThinLensImageDistance } from "../optics/thin-lens.js";
+import { rejectUnknownFields, requireInputKeys, requireInputObject } from "../core/record-validation.js";
+const VECTOR3_FIELDS = ["x", "y", "z"];
 function requireFiniteVector3(name, value) {
+    requireInputObject(value, name);
+    rejectUnknownFields(value, VECTOR3_FIELDS, name);
     for (const component of ["x", "y", "z"]) {
         if (!Number.isFinite(value[component])) {
             throw new InvalidScientificInputError(`${name}.${component} must be finite.`);
@@ -24,19 +31,20 @@ function requireFiniteVector3(name, value) {
  * Calculates sensor-plane motion during an exposure using ideal rectilinear
  * projection and constant linear object velocity.
  *
- * Without focusDistanceM, nominal focal length is the backwards-compatible
- * pinhole projection distance. With focusDistanceM, the selected thin-lens
- * sensor-plane image distance is used.
+ * Without focusDistanceM, the projection distance is the nominal focal length
+ * (the older pinhole behaviour). With focusDistanceM, it is the thin-lens
+ * image distance for that focus.
  *
- * The calculation projects the object's shutter-open and shutter-close
- * positions onto the image plane and measures the displacement between them.
- * It therefore handles lateral and depth-direction motion without relying on a
- * generic "subject speed" category.
+ * The object's positions when the shutter opens and closes are both projected
+ * onto the image plane, and the distance between them is measured. So
+ * sideways motion and motion toward or away from the camera are both handled,
+ * without a generic "subject speed" category.
  *
  * @param input Camera, exposure, object-position, and velocity inputs.
  * @returns Projected sensor-plane displacement.
  */
 export function calculateProjectedMotionBlur(input) {
+    requireInputKeys(input, "calculateProjectedMotionBlur", ["focalLengthMm", "shutterSeconds", "positionM", "velocityMps", "focusDistanceM", "pixelPitchMicrometers"]);
     requirePositiveFinite("focalLengthMm", input.focalLengthMm);
     requirePositiveFinite("shutterSeconds", input.shutterSeconds);
     requireFiniteVector3("positionM", input.positionM);
@@ -65,7 +73,7 @@ export function calculateProjectedMotionBlur(input) {
     const endYmm = projectionDistanceMm * (endPositionM.y / endPositionM.z);
     const deltaXMm = endXmm - startXmm;
     const deltaYMm = endYmm - startYmm;
-    const distanceMm = Math.hypot(deltaXMm, deltaYMm);
+    const distanceMm = portableHypot(deltaXMm, deltaYMm);
     let distancePixels;
     if (input.pixelPitchMicrometers !== undefined) {
         requirePositiveFinite("pixelPitchMicrometers", input.pixelPitchMicrometers);

package/dist/motion/projected-motion.js.map

@@ -1 +1 @@
-{"version":3,"file":"projected-motion.js","sourceRoot":"","sources":["../../src/motion/projected-motion.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"projected-motion.js","sourceRoot":"","sources":["../../src/motion/projected-motion.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * How far a moving object travels across the sensor during an exposure. Uses ideal rectilinear\n * projection and a constant straight-line object velocity.\n * - Without focusDistanceM, the projection distance is the nominal focal length (the older pinhole\n *   behaviour).\n * - With focusDistanceM, it is the thin-lens image distance for that focus.\n *\n * The object's positions when the shutter opens and closes are both projected onto the image plane,\n * and the distance between them is measured. So sideways motion and motion toward or away from the\n * camera are both handled, without a generic \"subject speed\" category.\n * @see docs/MOTION_AND_SIGNAL.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport { portableHypot } from \"../core/portable-math.js\";\nimport { calculateThinLensImageDistance } from \"../optics/thin-lens.js\";\nimport type { Vector3 } from \"../schema/scene.js\";\nimport { rejectUnknownFields, requireInputKeys, requireInputObject } from \"../core/record-validation.js\";\n\nconst VECTOR3_FIELDS = [\"x\", \"y\", \"z\"] as const;\n\nexport interface CalculateProjectedMotionBlurInput {\n  /** Lens focal length in millimetres. */\n  focalLengthMm: number;\n  /** Shutter-open duration in seconds. */\n  shutterSeconds: number;\n  /** Object position at shutter open, in camera-relative metres. +z is away from the camera. */\n  positionM: Vector3;\n  /** Constant world-space velocity during the exposure, in metres per second. */\n  velocityMps: Vector3;\n  /** Optional focus distance in metres for focus-aware sensor-plane projection. */\n  focusDistanceM?: number;\n  /** Optional sensor pixel pitch in micrometres for pixel-domain blur reporting. */\n  pixelPitchMicrometers?: number;\n}\n\nexport interface ProjectedMotionBlur {\n  deltaXMm: number;\n  deltaYMm: number;\n  distanceMm: number;\n  projectionDistanceMm: number;\n  distancePixels?: number;\n}\n\nfunction requireFiniteVector3(name: string, value: Vector3): void {\n  requireInputObject(value, name);\n  rejectUnknownFields(value, VECTOR3_FIELDS, name);\n  for (const component of [\"x\", \"y\", \"z\"] as const) {\n    if (!Number.isFinite(value[component])) {\n      throw new InvalidScientificInputError(\n        `${name}.${component} must be finite.`\n      );\n    }\n  }\n}\n\n/**\n * Calculates sensor-plane motion during an exposure using ideal rectilinear\n * projection and constant linear object velocity.\n *\n * Without focusDistanceM, the projection distance is the nominal focal length\n * (the older pinhole behaviour). With focusDistanceM, it is the thin-lens\n * image distance for that focus.\n *\n * The object's positions when the shutter opens and closes are both projected\n * onto the image plane, and the distance between them is measured. So\n * sideways motion and motion toward or away from the camera are both handled,\n * without a generic \"subject speed\" category.\n *\n * @param input Camera, exposure, object-position, and velocity inputs.\n * @returns Projected sensor-plane displacement.\n */\nexport function calculateProjectedMotionBlur(\n  input: CalculateProjectedMotionBlurInput\n): CalculationResult<ProjectedMotionBlur> {\n  requireInputKeys(input, \"calculateProjectedMotionBlur\", [\"focalLengthMm\", \"shutterSeconds\", \"positionM\", \"velocityMps\", \"focusDistanceM\", \"pixelPitchMicrometers\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"shutterSeconds\", input.shutterSeconds);\n\n  requireFiniteVector3(\"positionM\", input.positionM);\n  requireFiniteVector3(\"velocityMps\", input.velocityMps);\n\n  if (input.positionM.z <= 0) {\n    throw new InvalidScientificInputError(\n      \"positionM.z must place the object in front of the camera.\"\n    );\n  }\n\n  const endPositionM = {\n    x: input.positionM.x + input.velocityMps.x * input.shutterSeconds,\n    y: input.positionM.y + input.velocityMps.y * input.shutterSeconds,\n    z: input.positionM.z + input.velocityMps.z * input.shutterSeconds\n  };\n\n  if (endPositionM.z <= 0) {\n    throw new InvalidScientificInputError(\n      \"Object motion crosses or reaches the camera plane during the exposure.\"\n    );\n  }\n\n  const focusProjection =\n    input.focusDistanceM === undefined\n      ? undefined\n      : calculateThinLensImageDistance({\n          focalLengthMm: input.focalLengthMm,\n          objectDistanceM: input.focusDistanceM\n        });\n  const projectionDistanceMm =\n    focusProjection?.value.imageDistanceMm ?? input.focalLengthMm;\n\n  const startXmm =\n    projectionDistanceMm * (input.positionM.x / input.positionM.z);\n  const startYmm =\n    projectionDistanceMm * (input.positionM.y / input.positionM.z);\n  const endXmm =\n    projectionDistanceMm * (endPositionM.x / endPositionM.z);\n  const endYmm =\n    projectionDistanceMm * (endPositionM.y / endPositionM.z);\n\n  const deltaXMm = endXmm - startXmm;\n  const deltaYMm = endYmm - startYmm;\n  const distanceMm = portableHypot(deltaXMm, deltaYMm);\n\n  let distancePixels: number | undefined;\n  if (input.pixelPitchMicrometers !== undefined) {\n    requirePositiveFinite(\n      \"pixelPitchMicrometers\",\n      input.pixelPitchMicrometers\n    );\n    distancePixels = distanceMm / (input.pixelPitchMicrometers / 1000);\n  }\n\n  return calculatedResult(\n    {\n      deltaXMm,\n      deltaYMm,\n      distanceMm,\n      projectionDistanceMm,\n      ...(distancePixels === undefined ? {} : { distancePixels })\n    },\n    focusProjection === undefined\n      ? \"constant-velocity-pinhole-motion\"\n      : \"focus-aware-constant-velocity-thin-lens-motion\",\n    \"1.0.0\",\n    focusProjection === undefined\n      ? [\n          \"Ideal rectilinear/pinhole projection\",\n          \"Constant object velocity during the exposure\",\n          \"Camera motion is not included in this calculation\"\n        ]\n      : [\n          \"Ideal rectilinear paraxial thin-lens projection to the selected sensor plane\",\n          \"Constant object velocity during the exposure\",\n          \"Camera motion is not included in this calculation\",\n          \"Real-lens focus breathing is not modeled\"\n        ]\n  );\n}\n"]}

package/dist/motion/temporal-exposure-sum.d.ts

@@ -0,0 +1,55 @@
+export declare const TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION: "0.1.0";
+export declare const TEMPORAL_EXPOSURE_SUM_LIMITS: Readonly<{
+    maximumPixels: 24000000;
+    maximumDimension: 16384;
+    maximumTemporalSamples: 256;
+    maximumDisplacementSites: 4096;
+    maximumRowWeights: 4194304;
+    /** Keeps every float32 partial sum finite: 256 · 2^16 · 2^100 < 2^128. */
+    maximumSampleMagnitude: number;
+    maximumWeight: number;
+}>;
+export interface TemporalExposureSumInput {
+    schemaVersion: typeof TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION;
+    width: number;
+    height: number;
+    /** Row-major rate samples E₀ at site centres. Finite, non-negative, linear and additive (irradiance, photon or electron rate). */
+    samples: Float32Array | Float64Array;
+    /** Image displacement at each temporal node in grid sites, interleaved (dx₀, dy₀, dx₁, dy₁, …); +x right, +y down. */
+    displacements: Float64Array;
+    /** Quadrature weights `[k][row]` (nodes × height), finite and non-negative, for example seconds of each row's window near t_k. */
+    rowWeights: Float32Array | Float64Array;
+    boundary: "zero-outside-grid";
+}
+/** One temporal node: integer source offset of the top-left tap and the four bilinear weights (float64). */
+export interface TemporalExposureSumNode {
+    offsetX: number;
+    offsetY: number;
+    weights: readonly [number, number, number, number];
+}
+export interface TemporalExposureSumPlan {
+    width: number;
+    height: number;
+    nodeCount: number;
+    nodes: readonly TemporalExposureSumNode[];
+    maximumSampleMagnitude: number;
+    /** Largest Σ_k w_k(y) over rows; the operator's weight sum for error composition. */
+    maximumRowWeightSum: number;
+    maximumWeight: number;
+    /** True when every displacement is a whole number of sites (no interpolation). */
+    integerDisplacements: boolean;
+}
+/** Validates the request (every value once) and returns its plan. */
+export declare function calculateTemporalExposureSumPlan(input: TemporalExposureSumInput): TemporalExposureSumPlan;
+/**
+ * Reference rows `[y0, y1)` into `output` at `(y − y0)·width + x`. The order (node ascending; taps 00,
+ * 10, 01, 11 summed left to right; then times the row weight) is part of the contract shared with the
+ * WGSL kernel.
+ * @internal
+ */
+export declare function sumTemporalExposureRows(plan: TemporalExposureSumPlan, samples: Float32Array | Float64Array, rowWeights: Float32Array | Float64Array, y0: number, y1: number, output: Float64Array): void;
+/** Synchronous float64 reference for bounded grids. Use the image-kernel accelerator for large grids. */
+export declare function calculateTemporalExposureSum(input: TemporalExposureSumInput): {
+    plan: TemporalExposureSumPlan;
+    values: Float64Array;
+};

package/dist/motion/temporal-exposure-sum.js

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Exposure and motion as a weighted sum of shifted frames (#277, image-formation step 3). The CPU
+ * float64 reference for the `webgpu-f32` temporal stage; see docs/WEBGPU.md.
+ *
+ * A site's exposure is the time integral of its image-plane rate quantity over its own exposure window,
+ * H = ∫ E(x, t) dt (EMVA Standard 1288 Release 4.0 Linear, §2, free; CIPA DC-004-2020 §5.5, free). For an
+ * image that translates rigidly by d(t) on the sensor, E(x, t) = E₀(x − d(t)), so a temporal quadrature
+ * with nodes t_k and weights w_k gives
+ *
+ *   out(x, y) = Σ_k w_k(y) · E₀(x − dx_k, y − dy_k).
+ *
+ * Motion blur is this superposition of displaced images (Szeliski, *Computer Vision: Algorithms and
+ * Applications*, 2nd ed., 2022, free at https://szeliski.org/Book/). The weights depend on the row so a
+ * rolling shutter, whose rows start and end their exposure at different times, is the same sum with
+ * row-dependent windows (Meingast, Geyer & Sastry, "Geometric Models of Rolling-Shutter Cameras",
+ * arXiv:cs/0503076, free); a global shutter uses the same weights on every row.
+ *
+ * Declared approximations, owned by the caller: the quadrature nodes and weights, and rigid translation
+ * (no rotation, warp or occlusion). Sub-site displacements use bilinear interpolation between the four
+ * nearest site centres, which is linear interpolation and slightly low-pass; it is labelled as an
+ * approximation, not exact resampling. Sources outside the grid are zero; no padding or renormalization.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { requireAllowlistedRecord } from "../core/record-validation.js";
+export const TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION = "0.1.0";
+export const TEMPORAL_EXPOSURE_SUM_LIMITS = Object.freeze({
+    maximumPixels: 24_000_000,
+    maximumDimension: 16_384,
+    maximumTemporalSamples: 256,
+    maximumDisplacementSites: 4_096,
+    maximumRowWeights: 4_194_304,
+    /** Keeps every float32 partial sum finite: 256 · 2^16 · 2^100 < 2^128. */
+    maximumSampleMagnitude: 2 ** 100,
+    maximumWeight: 2 ** 16
+});
+function positiveInteger(value, maximum) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0 || value > maximum) {
+        throw new InvalidConfigurationError("Invalid temporal exposure sum geometry.");
+    }
+    return value;
+}
+/** Validates the request (every value once) and returns its plan. */
+export function calculateTemporalExposureSumPlan(input) {
+    const r = requireAllowlistedRecord(input, ["schemaVersion", "width", "height", "samples", "displacements", "rowWeights", "boundary"], "Invalid temporal exposure sum input.");
+    const L = TEMPORAL_EXPOSURE_SUM_LIMITS;
+    if (r.schemaVersion !== TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION || r.boundary !== "zero-outside-grid") {
+        throw new InvalidConfigurationError("Unsupported temporal exposure sum schema or boundary.");
+    }
+    const width = positiveInteger(r.width, L.maximumDimension), height = positiveInteger(r.height, L.maximumDimension);
+    if (width * height > L.maximumPixels)
+        throw new InvalidConfigurationError("Temporal exposure sum grid exceeds the pixel limit.");
+    const samples = r.samples, displacements = r.displacements, weights = r.rowWeights;
+    if (!(displacements instanceof Float64Array) || displacements.length < 2 || displacements.length % 2 !== 0 ||
+        displacements.length / 2 > L.maximumTemporalSamples) {
+        throw new InvalidConfigurationError("Temporal exposure sum needs 1 to 256 displacement pairs.");
+    }
+    const nodeCount = displacements.length / 2;
+    if (!(samples instanceof Float32Array || samples instanceof Float64Array) || samples.length !== width * height ||
+        !(weights instanceof Float32Array || weights instanceof Float64Array) || weights.length !== nodeCount * height ||
+        weights.length > L.maximumRowWeights) {
+        throw new InvalidConfigurationError("Temporal exposure sum arrays do not match the declared geometry.");
+    }
+    let maximumSampleMagnitude = 0;
+    for (let i = 0; i < samples.length; i++) {
+        const v = samples[i];
+        if (!(v >= 0 && v <= L.maximumSampleMagnitude))
+            throw new InvalidConfigurationError("Temporal samples must be finite, non-negative and bounded.");
+        if (v > maximumSampleMagnitude)
+            maximumSampleMagnitude = v;
+    }
+    let maximumWeight = 0, maximumRowWeightSum = 0;
+    const rowSums = new Float64Array(height);
+    for (let k = 0; k < nodeCount; k++) {
+        for (let y = 0; y < height; y++) {
+            const w = weights[k * height + y];
+            if (!(w >= 0 && w <= L.maximumWeight))
+                throw new InvalidConfigurationError("Temporal row weights must be finite, non-negative and bounded.");
+            if (w > maximumWeight)
+                maximumWeight = w;
+            rowSums[y] += w;
+        }
+    }
+    for (const s of rowSums)
+        if (s > maximumRowWeightSum)
+            maximumRowWeightSum = s;
+    let integerDisplacements = true;
+    const nodes = [];
+    for (let k = 0; k < nodeCount; k++) {
+        const dx = displacements[2 * k], dy = displacements[2 * k + 1];
+        if (!(Math.abs(dx) <= L.maximumDisplacementSites && Math.abs(dy) <= L.maximumDisplacementSites)) {
+            throw new InvalidConfigurationError("Temporal displacements must be finite and within 4096 sites.");
+        }
+        // Source position x − dx = x + offsetX + ax with ax in [0, 1).
+        const offsetX = Math.floor(-dx), offsetY = Math.floor(-dy), ax = -dx - offsetX, ay = -dy - offsetY;
+        if (ax !== 0 || ay !== 0)
+            integerDisplacements = false;
+        nodes.push(Object.freeze({ offsetX, offsetY,
+            weights: Object.freeze([(1 - ax) * (1 - ay), ax * (1 - ay), (1 - ax) * ay, ax * ay]) }));
+    }
+    return Object.freeze({ width, height, nodeCount, nodes: Object.freeze(nodes), maximumSampleMagnitude, maximumRowWeightSum, maximumWeight,
+        integerDisplacements });
+}
+/**
+ * Reference rows `[y0, y1)` into `output` at `(y − y0)·width + x`. The order (node ascending; taps 00,
+ * 10, 01, 11 summed left to right; then times the row weight) is part of the contract shared with the
+ * WGSL kernel.
+ * @internal
+ */
+export function sumTemporalExposureRows(plan, samples, rowWeights, y0, y1, output) {
+    const { width, height, nodes } = plan;
+    for (let y = y0; y < y1; y++) {
+        for (let x = 0; x < width; x++) {
+            let sum = 0;
+            for (let k = 0; k < nodes.length; k++) {
+                const node = nodes[k], sx = x + node.offsetX, sy = y + node.offsetY, b = node.weights;
+                const left = sx >= 0 && sx < width, right = sx + 1 >= 0 && sx + 1 < width;
+                const top = sy >= 0 && sy < height, bottom = sy + 1 >= 0 && sy + 1 < height;
+                let inner = 0;
+                if (top && left)
+                    inner += b[0] * samples[sy * width + sx];
+                if (top && right)
+                    inner += b[1] * samples[sy * width + sx + 1];
+                if (bottom && left)
+                    inner += b[2] * samples[(sy + 1) * width + sx];
+                if (bottom && right)
+                    inner += b[3] * samples[(sy + 1) * width + sx + 1];
+                sum += rowWeights[k * height + y] * inner;
+            }
+            output[(y - y0) * width + x] = sum;
+        }
+    }
+}
+/** Synchronous float64 reference for bounded grids. Use the image-kernel accelerator for large grids. */
+export function calculateTemporalExposureSum(input) {
+    const plan = calculateTemporalExposureSumPlan(input);
+    const values = new Float64Array(plan.width * plan.height);
+    sumTemporalExposureRows(plan, input.samples, input.rowWeights, 0, plan.height, values);
+    return { plan, values };
+}
+//# sourceMappingURL=temporal-exposure-sum.js.map

package/dist/motion/temporal-exposure-sum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-exposure-sum.js","sourceRoot":"","sources":["../../src/motion/temporal-exposure-sum.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Exposure and motion as a weighted sum of shifted frames (#277, image-formation step 3). The CPU\n * float64 reference for the `webgpu-f32` temporal stage; see docs/WEBGPU.md.\n *\n * A site's exposure is the time integral of its image-plane rate quantity over its own exposure window,\n * H = ∫ E(x, t) dt (EMVA Standard 1288 Release 4.0 Linear, §2, free; CIPA DC-004-2020 §5.5, free). For an\n * image that translates rigidly by d(t) on the sensor, E(x, t) = E₀(x − d(t)), so a temporal quadrature\n * with nodes t_k and weights w_k gives\n *\n *   out(x, y) = Σ_k w_k(y) · E₀(x − dx_k, y − dy_k).\n *\n * Motion blur is this superposition of displaced images (Szeliski, *Computer Vision: Algorithms and\n * Applications*, 2nd ed., 2022, free at https://szeliski.org/Book/). The weights depend on the row so a\n * rolling shutter, whose rows start and end their exposure at different times, is the same sum with\n * row-dependent windows (Meingast, Geyer & Sastry, \"Geometric Models of Rolling-Shutter Cameras\",\n * arXiv:cs/0503076, free); a global shutter uses the same weights on every row.\n *\n * Declared approximations, owned by the caller: the quadrature nodes and weights, and rigid translation\n * (no rotation, warp or occlusion). Sub-site displacements use bilinear interpolation between the four\n * nearest site centres, which is linear interpolation and slightly low-pass; it is labelled as an\n * approximation, not exact resampling. Sources outside the grid are zero; no padding or renormalization.\n */\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { requireAllowlistedRecord } from \"../core/record-validation.js\";\n\nexport const TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION = \"0.1.0\" as const;\nexport const TEMPORAL_EXPOSURE_SUM_LIMITS = Object.freeze({\n  maximumPixels: 24_000_000,\n  maximumDimension: 16_384,\n  maximumTemporalSamples: 256,\n  maximumDisplacementSites: 4_096,\n  maximumRowWeights: 4_194_304,\n  /** Keeps every float32 partial sum finite: 256 · 2^16 · 2^100 < 2^128. */\n  maximumSampleMagnitude: 2 ** 100,\n  maximumWeight: 2 ** 16\n});\n\nexport interface TemporalExposureSumInput {\n  schemaVersion: typeof TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION;\n  width: number;\n  height: number;\n  /** Row-major rate samples E₀ at site centres. Finite, non-negative, linear and additive (irradiance, photon or electron rate). */\n  samples: Float32Array | Float64Array;\n  /** Image displacement at each temporal node in grid sites, interleaved (dx₀, dy₀, dx₁, dy₁, …); +x right, +y down. */\n  displacements: Float64Array;\n  /** Quadrature weights `[k][row]` (nodes × height), finite and non-negative, for example seconds of each row's window near t_k. */\n  rowWeights: Float32Array | Float64Array;\n  boundary: \"zero-outside-grid\";\n}\n\n/** One temporal node: integer source offset of the top-left tap and the four bilinear weights (float64). */\nexport interface TemporalExposureSumNode {\n  offsetX: number;\n  offsetY: number;\n  weights: readonly [number, number, number, number];\n}\n\nexport interface TemporalExposureSumPlan {\n  width: number;\n  height: number;\n  nodeCount: number;\n  nodes: readonly TemporalExposureSumNode[];\n  maximumSampleMagnitude: number;\n  /** Largest Σ_k w_k(y) over rows; the operator's weight sum for error composition. */\n  maximumRowWeightSum: number;\n  maximumWeight: number;\n  /** True when every displacement is a whole number of sites (no interpolation). */\n  integerDisplacements: boolean;\n}\n\nfunction positiveInteger(value: unknown, maximum: number): number {\n  if (typeof value !== \"number\" || !Number.isSafeInteger(value) || value <= 0 || value > maximum) {\n    throw new InvalidConfigurationError(\"Invalid temporal exposure sum geometry.\");\n  }\n  return value;\n}\n\n/** Validates the request (every value once) and returns its plan. */\nexport function calculateTemporalExposureSumPlan(input: TemporalExposureSumInput): TemporalExposureSumPlan {\n  const r = requireAllowlistedRecord(input, [\"schemaVersion\", \"width\", \"height\", \"samples\", \"displacements\", \"rowWeights\", \"boundary\"],\n    \"Invalid temporal exposure sum input.\");\n  const L = TEMPORAL_EXPOSURE_SUM_LIMITS;\n  if (r.schemaVersion !== TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION || r.boundary !== \"zero-outside-grid\") {\n    throw new InvalidConfigurationError(\"Unsupported temporal exposure sum schema or boundary.\");\n  }\n  const width = positiveInteger(r.width, L.maximumDimension), height = positiveInteger(r.height, L.maximumDimension);\n  if (width * height > L.maximumPixels) throw new InvalidConfigurationError(\"Temporal exposure sum grid exceeds the pixel limit.\");\n  const samples = r.samples, displacements = r.displacements, weights = r.rowWeights;\n  if (!(displacements instanceof Float64Array) || displacements.length < 2 || displacements.length % 2 !== 0 ||\n      displacements.length / 2 > L.maximumTemporalSamples) {\n    throw new InvalidConfigurationError(\"Temporal exposure sum needs 1 to 256 displacement pairs.\");\n  }\n  const nodeCount = displacements.length / 2;\n  if (!(samples instanceof Float32Array || samples instanceof Float64Array) || samples.length !== width * height ||\n      !(weights instanceof Float32Array || weights instanceof Float64Array) || weights.length !== nodeCount * height ||\n      weights.length > L.maximumRowWeights) {\n    throw new InvalidConfigurationError(\"Temporal exposure sum arrays do not match the declared geometry.\");\n  }\n  let maximumSampleMagnitude = 0;\n  for (let i = 0; i < samples.length; i++) {\n    const v = samples[i]!;\n    if (!(v >= 0 && v <= L.maximumSampleMagnitude)) throw new InvalidConfigurationError(\"Temporal samples must be finite, non-negative and bounded.\");\n    if (v > maximumSampleMagnitude) maximumSampleMagnitude = v;\n  }\n  let maximumWeight = 0, maximumRowWeightSum = 0;\n  const rowSums = new Float64Array(height);\n  for (let k = 0; k < nodeCount; k++) {\n    for (let y = 0; y < height; y++) {\n      const w = weights[k * height + y]!;\n      if (!(w >= 0 && w <= L.maximumWeight)) throw new InvalidConfigurationError(\"Temporal row weights must be finite, non-negative and bounded.\");\n      if (w > maximumWeight) maximumWeight = w;\n      rowSums[y]! += w;\n    }\n  }\n  for (const s of rowSums) if (s > maximumRowWeightSum) maximumRowWeightSum = s;\n  let integerDisplacements = true;\n  const nodes: TemporalExposureSumNode[] = [];\n  for (let k = 0; k < nodeCount; k++) {\n    const dx = displacements[2 * k]!, dy = displacements[2 * k + 1]!;\n    if (!(Math.abs(dx) <= L.maximumDisplacementSites && Math.abs(dy) <= L.maximumDisplacementSites)) {\n      throw new InvalidConfigurationError(\"Temporal displacements must be finite and within 4096 sites.\");\n    }\n    // Source position x − dx = x + offsetX + ax with ax in [0, 1).\n    const offsetX = Math.floor(-dx), offsetY = Math.floor(-dy), ax = -dx - offsetX, ay = -dy - offsetY;\n    if (ax !== 0 || ay !== 0) integerDisplacements = false;\n    nodes.push(Object.freeze({ offsetX, offsetY,\n      weights: Object.freeze([(1 - ax) * (1 - ay), ax * (1 - ay), (1 - ax) * ay, ax * ay] as const) }));\n  }\n  return Object.freeze({ width, height, nodeCount, nodes: Object.freeze(nodes), maximumSampleMagnitude, maximumRowWeightSum, maximumWeight,\n    integerDisplacements });\n}\n\n/**\n * Reference rows `[y0, y1)` into `output` at `(y − y0)·width + x`. The order (node ascending; taps 00,\n * 10, 01, 11 summed left to right; then times the row weight) is part of the contract shared with the\n * WGSL kernel.\n * @internal\n */\nexport function sumTemporalExposureRows(plan: TemporalExposureSumPlan, samples: Float32Array | Float64Array, rowWeights: Float32Array | Float64Array,\n  y0: number, y1: number, output: Float64Array): void {\n  const { width, height, nodes } = plan;\n  for (let y = y0; y < y1; y++) {\n    for (let x = 0; x < width; x++) {\n      let sum = 0;\n      for (let k = 0; k < nodes.length; k++) {\n        const node = nodes[k]!, sx = x + node.offsetX, sy = y + node.offsetY, b = node.weights;\n        const left = sx >= 0 && sx < width, right = sx + 1 >= 0 && sx + 1 < width;\n        const top = sy >= 0 && sy < height, bottom = sy + 1 >= 0 && sy + 1 < height;\n        let inner = 0;\n        if (top && left) inner += b[0] * samples[sy * width + sx]!;\n        if (top && right) inner += b[1] * samples[sy * width + sx + 1]!;\n        if (bottom && left) inner += b[2] * samples[(sy + 1) * width + sx]!;\n        if (bottom && right) inner += b[3] * samples[(sy + 1) * width + sx + 1]!;\n        sum += rowWeights[k * height + y]! * inner;\n      }\n      output[(y - y0) * width + x] = sum;\n    }\n  }\n}\n\n/** Synchronous float64 reference for bounded grids. Use the image-kernel accelerator for large grids. */\nexport function calculateTemporalExposureSum(input: TemporalExposureSumInput): { plan: TemporalExposureSumPlan; values: Float64Array } {\n  const plan = calculateTemporalExposureSumPlan(input);\n  const values = new Float64Array(plan.width * plan.height);\n  sumTemporalExposureRows(plan, input.samples, input.rowWeights, 0, plan.height, values);\n  return { plan, values };\n}\n"]}

package/dist/motion/video-sequence.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Video frame sequences. Builds a deterministic sequence of frames from the "video" optical capture
+ * state (frameRateHz) and a shutter angle.
+ *
+ * Each frame is an ordinary ResolvedReleaseFrame, so the production capture snapshot and
+ * image-formation plan use it unchanged. An optional electronic rolling shutter gives every frame the
+ * same line-by-line exposure offsets. Frame timing, seeds and schedules depend only on the inputs and
+ * the absolute frame index. They never depend on how the sequence is split into chunks, or on
+ * earlier frames.
+ * @see docs/MOTION_AND_SIGNAL.md#video-frame-sequences for equations, conventions and limits.
+ */
+import { type EvidenceProvenance } from "../core/evidence-provenance.js";
+import type { ReleaseAutomationState, ResolvedReleaseFrame } from "../capture/release-sequence.js";
+import { type FocusPlane } from "../optics/focus-state.js";
+import { type OpticalProfileState } from "../optics/profile-contract.js";
+import { createRollingShutterCaptureExposureSchedule, type ElectronicRollingShutterExposureSchedule } from "../sensor/readout-exposure-linkage.js";
+import type { RollingSensorReadoutTimingDeclaration } from "../sensor/readout-timing.js";
+export declare const VIDEO_FRAME_SEQUENCE_VERSION: "1.0.0";
+/** Stream identifier ("VIDF"). Keeps per-frame video seeds separate from per-site noise streams. */
+export declare const VIDEO_FRAME_SEED_STREAM_ID: 1447642182;
+/** Maximum frames per call. Resolve longer clips in chunks using firstFrameIndex. */
+export declare const VIDEO_FRAME_SEQUENCE_MAXIMUM_FRAMES: 100000;
+/**
+ * Exposure time for a shutter angle (as on a rotary film-camera shutter): t = (angle / 360) / frameRateHz.
+ * A 180° angle exposes for half of each frame period.
+ */
+export declare function calculateShutterAngleExposureSeconds(frameRateHz: number, shutterAngleDegrees: number): number;
+/** Inverse of {@link calculateShutterAngleExposureSeconds}: angle = 360 · frameRateHz · t. */
+export declare function calculateShutterAngleFromExposureSeconds(frameRateHz: number, exposureSeconds: number): number;
+export interface ShutterAngleRuleAssessment {
+    frameRateHz: number;
+    shutterAngleDegrees: number;
+    exposureSeconds: number;
+    /** 1 / (2 · frameRateHz): the 180° convention. */
+    conventionExposureSeconds: number;
+    /** log2(exposure / convention): negative is shorter (crisper, more staccato) motion. */
+    deviationStops: number;
+    classification: "matches-180-degree-convention" | "shorter-than-convention" | "longer-than-convention";
+    /** The 180° rule is a cinematographic convention for motion-blur appearance, not a physical law. */
+    conventionNotPhysics: true;
+}
+/**
+ * Compares a shutter angle with the 180° cinematographic convention (exposure = half the frame
+ * period). Within a relative 1e-9 the angle "matches". Otherwise the signed deviation is reported.
+ */
+export declare function assessShutterAngleRule(frameRateHz: number, shutterAngleDegrees: number): ShutterAngleRuleAssessment;
+export interface ResolveVideoFrameSequenceInput {
+    sequenceId: string;
+    /** Exact optical capture state. captureMode must be "video", with a positive frameRateHz. */
+    opticalState: OpticalProfileState;
+    /** Shutter angle in (0, 360]; exposure = angle / 360 / frameRateHz. */
+    shutterAngleDegrees: number;
+    /** Absolute index of the first frame to resolve (default 0). */
+    firstFrameIndex?: number;
+    frameCount: number;
+    sequenceSeedUint32: number;
+    iso: number;
+    /** Defaults to the optical state's finite focus distance. */
+    focus?: FocusPlane;
+    automation: {
+        ae: ReleaseAutomationState;
+        af: ReleaseAutomationState;
+        awb: ReleaseAutomationState;
+    };
+    whiteBalanceStateId?: string;
+    /** Evidence for the commanded frame rate and shutter-angle timing. Used for the exposure fact. */
+    timingEvidence: readonly EvidenceProvenance[];
+    /** Optional electronic rolling shutter applied identically to every frame. */
+    rollingShutter?: {
+        readout: RollingSensorReadoutTimingDeclaration;
+        linkageEvidence: readonly EvidenceProvenance[];
+    };
+}
+export interface VideoFrameSequence {
+    version: typeof VIDEO_FRAME_SEQUENCE_VERSION;
+    sequenceId: string;
+    frameRateHz: number;
+    framePeriodSeconds: number;
+    shutterAngleDegrees: number;
+    exposureSeconds: number;
+    shutterAngleRule: ShutterAngleRuleAssessment;
+    firstFrameIndex: number;
+    frameCount: number;
+    sequenceSeedUint32: number;
+    seedDerivation: "murmur3-x86-32(sequenceSeed, absoluteFrameIndex, VIDEO_FRAME_SEED_STREAM_ID)";
+    frameTimeDerivation: "absoluteFrameIndex / frameRateHz";
+    /**
+     * Exposure schedule for each frame. It is the same for every frame; times are relative to each
+     * frame's own first-opening phase. Null when no rolling shutter is declared; the caller then
+     * supplies the global schedule of its capture mode.
+     */
+    exposureSchedule: ReturnType<typeof createRollingShutterCaptureExposureSchedule> | null;
+    rollingShutter: Pick<ElectronicRollingShutterExposureSchedule, "modelId" | "modelVersion" | "lineScanSkewSeconds" | "linkage"> | null;
+    /** Ordinary release frames: pass each to createProductionCaptureSnapshotFromReleaseFrame. */
+    frames: readonly ResolvedReleaseFrame[];
+    limitations: readonly string[];
+}
+/**
+ * Resolves `frameCount` consecutive video frames starting at `firstFrameIndex`.
+ *
+ * Frame k (absolute index) opens k / frameRateHz seconds after the sequence starts, and exposes for
+ * (angle / 360) / frameRateHz. Its random seed is a MurmurHash3 of (sequence seed, k, stream id).
+ *
+ * Every value depends only on the inputs and k. So resolving frames 0–99 at once, or as 0–49 then
+ * 50–99, gives identical frames.
+ *
+ * With a rolling shutter, the line at normalized scan position s in frame k integrates over
+ * [k/f + s·τ, k/f + s·τ + T]. τ must not exceed the frame period, so each line is read once per
+ * frame.
+ */
+export declare function resolveVideoFrameSequence(input: ResolveVideoFrameSequenceInput): VideoFrameSequence;

package/dist/motion/video-sequence.js

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Video frame sequences. Builds a deterministic sequence of frames from the "video" optical capture
+ * state (frameRateHz) and a shutter angle.
+ *
+ * Each frame is an ordinary ResolvedReleaseFrame, so the production capture snapshot and
+ * image-formation plan use it unchanged. An optional electronic rolling shutter gives every frame the
+ * same line-by-line exposure offsets. Frame timing, seeds and schedules depend only on the inputs and
+ * the absolute frame index. They never depend on how the sequence is split into chunks, or on
+ * earlier frames.
+ * @see docs/MOTION_AND_SIGNAL.md#video-frame-sequences for equations, conventions and limits.
+ */
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { rejectUnknownFields, requireInputObject, requirePublicOpaqueId, requireInputKeys } from "../core/record-validation.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { parseFocusPlane } from "../optics/focus-state.js";
+import { parseOpticalProfileState } from "../optics/profile-contract.js";
+import { resolveElectronicRollingShutterExposureSchedule, ELECTRONIC_ROLLING_SHUTTER_MODEL, createRollingShutterCaptureExposureSchedule } from "../sensor/readout-exposure-linkage.js";
+import { deriveNativeSiteStreamSeedUint32 } from "../sensor/stochastic-seed.js";
+export const VIDEO_FRAME_SEQUENCE_VERSION = "1.0.0";
+/** Stream identifier ("VIDF"). Keeps per-frame video seeds separate from per-site noise streams. */
+export const VIDEO_FRAME_SEED_STREAM_ID = 0x56494446;
+/** Maximum frames per call. Resolve longer clips in chunks using firstFrameIndex. */
+export const VIDEO_FRAME_SEQUENCE_MAXIMUM_FRAMES = 100_000;
+function requireFrameRate(frameRateHz) {
+    if (typeof frameRateHz !== "number" || !Number.isFinite(frameRateHz) || frameRateHz <= 0) {
+        throw new InvalidScientificInputError("frameRateHz must be a finite number greater than zero.");
+    }
+    return frameRateHz;
+}
+function requireShutterAngle(shutterAngleDegrees) {
+    if (typeof shutterAngleDegrees !== "number" || !Number.isFinite(shutterAngleDegrees) ||
+        shutterAngleDegrees <= 0 || shutterAngleDegrees > 360) {
+        throw new InvalidScientificInputError("shutterAngleDegrees must lie in (0, 360].");
+    }
+    return shutterAngleDegrees;
+}
+/**
+ * Exposure time for a shutter angle (as on a rotary film-camera shutter): t = (angle / 360) / frameRateHz.
+ * A 180° angle exposes for half of each frame period.
+ */
+export function calculateShutterAngleExposureSeconds(frameRateHz, shutterAngleDegrees) {
+    return requireShutterAngle(shutterAngleDegrees) / 360 / requireFrameRate(frameRateHz);
+}
+/** Inverse of {@link calculateShutterAngleExposureSeconds}: angle = 360 · frameRateHz · t. */
+export function calculateShutterAngleFromExposureSeconds(frameRateHz, exposureSeconds) {
+    if (typeof exposureSeconds !== "number" || !Number.isFinite(exposureSeconds) || exposureSeconds <= 0) {
+        throw new InvalidScientificInputError("exposureSeconds must be a finite number greater than zero.");
+    }
+    const angle = 360 * requireFrameRate(frameRateHz) * exposureSeconds;
+    if (angle > 360 * (1 + 1e-12)) {
+        throw new InvalidScientificInputError("Exposure longer than one frame period has no shutter angle.");
+    }
+    return Math.min(360, angle);
+}
+/**
+ * Compares a shutter angle with the 180° cinematographic convention (exposure = half the frame
+ * period). Within a relative 1e-9 the angle "matches". Otherwise the signed deviation is reported.
+ */
+export function assessShutterAngleRule(frameRateHz, shutterAngleDegrees) {
+    const exposureSeconds = calculateShutterAngleExposureSeconds(frameRateHz, shutterAngleDegrees);
+    const conventionExposureSeconds = 1 / (2 * frameRateHz);
+    const ratio = exposureSeconds / conventionExposureSeconds;
+    return {
+        frameRateHz, shutterAngleDegrees, exposureSeconds, conventionExposureSeconds,
+        deviationStops: Math.log2(ratio),
+        classification: Math.abs(ratio - 1) <= 1e-9 ? "matches-180-degree-convention"
+            : ratio < 1 ? "shorter-than-convention" : "longer-than-convention",
+        conventionNotPhysics: true
+    };
+}
+/**
+ * Resolves `frameCount` consecutive video frames starting at `firstFrameIndex`.
+ *
+ * Frame k (absolute index) opens k / frameRateHz seconds after the sequence starts, and exposes for
+ * (angle / 360) / frameRateHz. Its random seed is a MurmurHash3 of (sequence seed, k, stream id).
+ *
+ * Every value depends only on the inputs and k. So resolving frames 0–99 at once, or as 0–49 then
+ * 50–99, gives identical frames.
+ *
+ * With a rolling shutter, the line at normalized scan position s in frame k integrates over
+ * [k/f + s·τ, k/f + s·τ + T]. τ must not exceed the frame period, so each line is read once per
+ * frame.
+ */
+export function resolveVideoFrameSequence(input) {
+    requireInputKeys(input, "resolveVideoFrameSequence", ["sequenceId", "opticalState", "shutterAngleDegrees", "firstFrameIndex", "frameCount", "sequenceSeedUint32", "iso", "focus", "automation", "whiteBalanceStateId", "timingEvidence", "rollingShutter"]);
+    requireInputObject(input.automation, "resolveVideoFrameSequence automation");
+    rejectUnknownFields(input.automation, ["ae", "af", "awb"], "resolveVideoFrameSequence automation");
+    if (input.rollingShutter !== undefined) {
+        requireInputObject(input.rollingShutter, "resolveVideoFrameSequence rollingShutter");
+        rejectUnknownFields(input.rollingShutter, ["readout", "linkageEvidence"], "resolveVideoFrameSequence rollingShutter");
+    }
+    const sequenceId = requirePublicOpaqueId(input.sequenceId, "Invalid video sequence ID.");
+    const optical = parseOpticalProfileState(input.opticalState);
+    if (optical.captureMode !== "video") {
+        throw new InvalidConfigurationError("Video frame sequences require an optical state with captureMode \"video\".");
+    }
+    const frameRateHz = optical.frameRateHz;
+    const shutterAngleDegrees = requireShutterAngle(input.shutterAngleDegrees);
+    const exposureSeconds = calculateShutterAngleExposureSeconds(frameRateHz, shutterAngleDegrees);
+    const first = input.firstFrameIndex ?? 0;
+    if (!Number.isSafeInteger(first) || first < 0 || !Number.isSafeInteger(input.frameCount) || input.frameCount < 1 ||
+        input.frameCount > VIDEO_FRAME_SEQUENCE_MAXIMUM_FRAMES || first + input.frameCount - 1 > 0xffffffff) {
+        throw new InvalidScientificInputError("Video frames need a non-negative first index, 1–100000 frames and uint32 frame indices.");
+    }
+    const seed = input.sequenceSeedUint32;
+    if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff) {
+        throw new InvalidScientificInputError("sequenceSeedUint32 must be a uint32 integer.");
+    }
+    if (typeof input.iso !== "number" || !Number.isFinite(input.iso) || input.iso <= 0) {
+        throw new InvalidScientificInputError("iso must be a finite number greater than zero.");
+    }
+    const timingEvidence = parseEvidenceList(input.timingEvidence, "video.timingEvidence");
+    const focus = parseFocusPlane(input.focus ?? { kind: "finite", distanceM: optical.focusDistanceM });
+    const automation = { ae: input.automation.ae, af: input.automation.af, awb: input.automation.awb };
+    for (const state of Object.values(automation)) {
+        if (state !== "manual" && state !== "locked" && state !== "continuous") {
+            throw new InvalidConfigurationError("Video automation states must be manual, locked or continuous.");
+        }
+    }
+    const whiteBalanceStateId = input.whiteBalanceStateId === undefined ? undefined
+        : requirePublicOpaqueId(input.whiteBalanceStateId, "Invalid white-balance state ID.");
+    const framePeriodSeconds = 1 / frameRateHz;
+    let rolling = null;
+    if (input.rollingShutter !== undefined) {
+        rolling = resolveElectronicRollingShutterExposureSchedule({ readout: input.rollingShutter.readout,
+            nominalExposureDurationSeconds: { value: exposureSeconds, unit: "s", evidence: timingEvidence },
+            linkageEvidence: input.rollingShutter.linkageEvidence });
+        if (rolling.lineScanSkewSeconds > framePeriodSeconds) {
+            throw new InvalidScientificInputError("Rolling-shutter line skew exceeds the video frame period; lines cannot be read once per frame.");
+        }
+    }
+    const start = (index) => index / frameRateHz;
+    const frames = Array.from({ length: input.frameCount }, (_, offset) => {
+        const frameIndex = first + offset, exposureStartTimeSeconds = start(frameIndex);
+        return {
+            sequenceId,
+            frameIndex,
+            releaseFrameId: sequenceId + ":video:" + frameIndex,
+            exposureStartTimeSeconds,
+            exposureEndTimeSeconds: exposureStartTimeSeconds + exposureSeconds,
+            sceneTimeSecondsFromSequenceStart: exposureStartTimeSeconds,
+            startIntervalFromPreviousSeconds: frameIndex === 0 ? null : exposureStartTimeSeconds - start(frameIndex - 1),
+            timingConstraints: ["requested-cadence"],
+            stochasticSeedUint32: deriveNativeSiteStreamSeedUint32(seed, frameIndex, VIDEO_FRAME_SEED_STREAM_ID),
+            exposure: { aperture: optical.aperture, shutterSeconds: exposureSeconds, iso: input.iso },
+            focus: { ...focus },
+            automation: { ...automation },
+            ...(whiteBalanceStateId === undefined ? {} : { whiteBalanceStateId })
+        };
+    });
+    return {
+        version: VIDEO_FRAME_SEQUENCE_VERSION,
+        sequenceId,
+        frameRateHz,
+        framePeriodSeconds,
+        shutterAngleDegrees,
+        exposureSeconds,
+        shutterAngleRule: assessShutterAngleRule(frameRateHz, shutterAngleDegrees),
+        firstFrameIndex: first,
+        frameCount: input.frameCount,
+        sequenceSeedUint32: seed,
+        seedDerivation: "murmur3-x86-32(sequenceSeed, absoluteFrameIndex, VIDEO_FRAME_SEED_STREAM_ID)",
+        frameTimeDerivation: "absoluteFrameIndex / frameRateHz",
+        exposureSchedule: rolling === null ? null : createRollingShutterCaptureExposureSchedule(rolling),
+        rollingShutter: rolling === null ? null : { modelId: ELECTRONIC_ROLLING_SHUTTER_MODEL.id,
+            modelVersion: ELECTRONIC_ROLLING_SHUTTER_MODEL.version, lineScanSkewSeconds: rolling.lineScanSkewSeconds,
+            linkage: rolling.linkage },
+        frames,
+        limitations: [
+            "Frame timing is ideal: no frame-rate drift, dropped frames, variable frame rate or sensor-mode switching.",
+            "Exposure follows the shutter-angle relation t = angle/360/f; automatic exposure between frames is not modeled.",
+            "The 180-degree rule is reported as a cinematographic convention, not a physical requirement.",
+            "Video encoding, compression, temporal noise reduction and frame interpolation are not modeled."
+        ]
+    };
+}
+//# sourceMappingURL=video-sequence.js.map