@photivra/engine 2.15.0 → 2.17.0

package/dist/facade/defocus-bokeh-zones.d.ts

@@ -0,0 +1,33 @@
+import type { SiteKernelFieldZones } from "./diffraction-provider.js";
+import { type DefocusBokehSiteKernel, type ResolvedDefocusBokehOptions } from "../optics/defocus-bokeh-kernel.js";
+export interface DefocusBokehZonePlan {
+    zones: SiteKernelFieldZones;
+    /** Field tangent of each zone centre (output-image axes, +Y up), row-major. */
+    fields: readonly {
+        x: number;
+        y: number;
+    }[];
+    /** Smallest open-area ratio over the zone centres, and the largest change between two zones sharing an edge. */
+    minimumOpenAreaRatio: number;
+    largestAdjacentOpenAreaRatioChange: number;
+}
+/**
+ * Plans the zones. `fieldOf(x, y)` is the field tangent of native point (x, y) in sites from the raster's top-left corner;
+ * `kernelAt(field)` builds a zone's kernel (its radius at most `radius`). Kernels are built on first use by the gather.
+ */
+export declare function planDefocusBokehZones(input: {
+    options: ResolvedDefocusBokehOptions;
+    nativeWidth: number;
+    nativeHeight: number;
+    radius: number;
+    fNumber: number;
+    focalLengthMm: number;
+    fieldOf: (x: number, y: number) => {
+        x: number;
+        y: number;
+    };
+    kernelAt: (field: {
+        x: number;
+        y: number;
+    }) => DefocusBokehSiteKernel;
+}): DefocusBokehZonePlan;

package/dist/facade/defocus-bokeh-zones.js

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `lens.defocus` with a cat's eye (#553): the field zones of the capture's field-varying defocus kernel. The native raster is
+ * cut into square zones (`fieldZonesAcrossLongSide` across its long side); each zone's kernel is the shaped kernel of the
+ * field point at the zone's centre (`createDefocusBokehSiteKernel`), padded to the axis kernel's radius (the cat's eye only
+ * removes light from the opening, so no zone's blur reaches further than the unclipped one). The gather
+ * (`createZonedGather`) gives every site its zone's kernel: a piecewise-constant approximation of the space-variant blur,
+ * whose step between neighbouring zones is reported (the largest change of the open-area ratio). Internal.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { openPupilAreaRatio } from "../optics/defocus-bokeh-kernel.js";
+/**
+ * Plans the zones. `fieldOf(x, y)` is the field tangent of native point (x, y) in sites from the raster's top-left corner;
+ * `kernelAt(field)` builds a zone's kernel (its radius at most `radius`). Kernels are built on first use by the gather.
+ */
+export function planDefocusBokehZones(input) {
+    const { options, nativeWidth: W, nativeHeight: H, radius: R } = input;
+    const across = options.catsEye.fieldZonesAcrossLongSide, size = Math.ceil(Math.max(W, H) / across);
+    const columns = Math.ceil(W / size), rows = Math.ceil(H / size), fields = [], ratios = [];
+    for (let zy = 0; zy < rows; zy++)
+        for (let zx = 0; zx < columns; zx++) {
+            const field = input.fieldOf((zx * size + Math.min(W, (zx + 1) * size)) / 2, (zy * size + Math.min(H, (zy + 1) * size)) / 2);
+            fields.push(field);
+            ratios.push(openPupilAreaRatio(options, input.fNumber, input.focalLengthMm, field));
+        }
+    let minimum = Infinity, step = 0;
+    for (let zy = 0; zy < rows; zy++)
+        for (let zx = 0; zx < columns; zx++) {
+            const r = ratios[zy * columns + zx];
+            minimum = Math.min(minimum, r);
+            if (zx + 1 < columns)
+                step = Math.max(step, Math.abs(r - ratios[zy * columns + zx + 1]));
+            if (zy + 1 < rows)
+                step = Math.max(step, Math.abs(r - ratios[(zy + 1) * columns + zx]));
+        }
+    const width = 2 * R + 1;
+    return {
+        fields, minimumOpenAreaRatio: minimum, largestAdjacentOpenAreaRatioChange: step,
+        zones: { size, columns, rows, kernelOf(zone) {
+                const k = input.kernelAt(fields[zone]);
+                if (k.radius === R)
+                    return k.weights;
+                if (k.radius > R)
+                    throw new InvalidConfigurationError("lens.defocus: a cat's-eye zone kernel reaches beyond the unclipped kernel's radius.");
+                const padded = new Float64Array(width * width), offset = R - k.radius;
+                for (let j = 0; j < k.width; j++)
+                    for (let i = 0; i < k.width; i++)
+                        padded[(j + offset) * width + i + offset] = k.weights[j * k.width + i];
+                return padded;
+            } }
+    };
+}
+//# sourceMappingURL=defocus-bokeh-zones.js.map

package/dist/facade/defocus-bokeh-zones.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defocus-bokeh-zones.js","sourceRoot":"","sources":["../../src/facade/defocus-bokeh-zones.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * `lens.defocus` with a cat's eye (#553): the field zones of the capture's field-varying defocus kernel. The native raster is\n * cut into square zones (`fieldZonesAcrossLongSide` across its long side); each zone's kernel is the shaped kernel of the\n * field point at the zone's centre (`createDefocusBokehSiteKernel`), padded to the axis kernel's radius (the cat's eye only\n * removes light from the opening, so no zone's blur reaches further than the unclipped one). The gather\n * (`createZonedGather`) gives every site its zone's kernel: a piecewise-constant approximation of the space-variant blur,\n * whose step between neighbouring zones is reported (the largest change of the open-area ratio). Internal.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport type { SiteKernelFieldZones } from \"./diffraction-provider.js\";\nimport { openPupilAreaRatio, type DefocusBokehSiteKernel, type ResolvedDefocusBokehOptions } from \"../optics/defocus-bokeh-kernel.js\";\n\nexport interface DefocusBokehZonePlan {\n  zones: SiteKernelFieldZones;\n  /** Field tangent of each zone centre (output-image axes, +Y up), row-major. */\n  fields: readonly { x: number; y: number }[];\n  /** Smallest open-area ratio over the zone centres, and the largest change between two zones sharing an edge. */\n  minimumOpenAreaRatio: number;\n  largestAdjacentOpenAreaRatioChange: number;\n}\n\n/**\n * Plans the zones. `fieldOf(x, y)` is the field tangent of native point (x, y) in sites from the raster's top-left corner;\n * `kernelAt(field)` builds a zone's kernel (its radius at most `radius`). Kernels are built on first use by the gather.\n */\nexport function planDefocusBokehZones(input: { options: ResolvedDefocusBokehOptions; nativeWidth: number; nativeHeight: number; radius: number;\n  fNumber: number; focalLengthMm: number; fieldOf: (x: number, y: number) => { x: number; y: number }; kernelAt: (field: { x: number; y: number }) => DefocusBokehSiteKernel }): DefocusBokehZonePlan {\n  const { options, nativeWidth: W, nativeHeight: H, radius: R } = input;\n  const across = options.catsEye!.fieldZonesAcrossLongSide, size = Math.ceil(Math.max(W, H) / across);\n  const columns = Math.ceil(W / size), rows = Math.ceil(H / size), fields: { x: number; y: number }[] = [], ratios: number[] = [];\n  for (let zy = 0; zy < rows; zy++) for (let zx = 0; zx < columns; zx++) {\n    const field = input.fieldOf((zx * size + Math.min(W, (zx + 1) * size)) / 2, (zy * size + Math.min(H, (zy + 1) * size)) / 2);\n    fields.push(field);\n    ratios.push(openPupilAreaRatio(options, input.fNumber, input.focalLengthMm, field));\n  }\n  let minimum = Infinity, step = 0;\n  for (let zy = 0; zy < rows; zy++) for (let zx = 0; zx < columns; zx++) {\n    const r = ratios[zy * columns + zx]!;\n    minimum = Math.min(minimum, r);\n    if (zx + 1 < columns) step = Math.max(step, Math.abs(r - ratios[zy * columns + zx + 1]!));\n    if (zy + 1 < rows) step = Math.max(step, Math.abs(r - ratios[(zy + 1) * columns + zx]!));\n  }\n  const width = 2 * R + 1;\n  return {\n    fields, minimumOpenAreaRatio: minimum, largestAdjacentOpenAreaRatioChange: step,\n    zones: { size, columns, rows, kernelOf(zone: number): Float64Array {\n      const k = input.kernelAt(fields[zone]!);\n      if (k.radius === R) return k.weights;\n      if (k.radius > R) throw new InvalidConfigurationError(\"lens.defocus: a cat's-eye zone kernel reaches beyond the unclipped kernel's radius.\");\n      const padded = new Float64Array(width * width), offset = R - k.radius;\n      for (let j = 0; j < k.width; j++) for (let i = 0; i < k.width; i++) padded[(j + offset) * width + i + offset] = k.weights[j * k.width + i]!;\n      return padded;\n    } }\n  };\n}\n"]}

package/dist/facade/defocus-image-space-provider.d.ts

@@ -0,0 +1,118 @@
+import { type CameraAngularVelocityRadPerSec } from "../motion/camera-rotation.js";
+import { type IlluminationVignettingProfile } from "../optics/illumination-vignetting.js";
+import { type PreparedEnvironmentLensFieldMapping } from "../optics/sensor-environment-query.js";
+import { type SiteKernelFieldZones } from "./diffraction-provider.js";
+import type { PlanarSceneRadianceProvider } from "./scene-radiance.js";
+import { type LargeDefocusKernel } from "./large-defocus-lattice.js";
+/** The camera geometry the environment uses for each site query (the same options as the site inputs). */
+export interface DefocusImageSpaceGeometry {
+    focalLengthMm: number;
+    focusDistanceM: number;
+    angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
+    /** The site inputs' `lensFieldMapping`, prepared; omitted for the ideal rectilinear, distortion-free mapping. */
+    lensMapping?: PreparedEnvironmentLensFieldMapping;
+    /** The site inputs' radial-illumination-vignetting profile; omitted for unity field throughput. */
+    vignetting?: IlluminationVignettingProfile;
+}
+/** Internal: the scene ray and field factor of sensor points, and the sensor point of a scene ray, for one geometry. */
+export interface PreparedDefocusImageSpaceGeometry {
+    /**
+     * The unit look direction (toward the scene, reference camera axes at exposure start) of native sensor point (x, y) mm
+     * (+X right, +Y down) at time t, and its field factor F = T·A (vignetting throughput × distortion area factor).
+     */
+    lookOf(xMm: number, yMm: number, timeSeconds: number): {
+        x: number;
+        y: number;
+        z: number;
+        factor: number;
+    };
+    /** The native sensor point (mm, +Y down) whose scene ray at time t is the look direction; undefined outside the mapping. */
+    sensorPointOf(look: {
+        x: number;
+        y: number;
+        z: number;
+    }, timeSeconds: number): {
+        x: number;
+        y: number;
+    } | undefined;
+    /** True with camera rotation: the ray of a sensor point depends on time. */
+    timeDependent: boolean;
+}
+/** Internal: prepares {@link PreparedDefocusImageSpaceGeometry} with the environment's own conventions and arithmetic. */
+export declare function prepareDefocusImageSpaceGeometry(geometry: DefocusImageSpaceGeometry): PreparedDefocusImageSpaceGeometry;
+export interface DefocusImageSpaceProviderInput {
+    base: PlanarSceneRadianceProvider;
+    geometry: PreparedDefocusImageSpaceGeometry;
+    /** Each spectral node's kernel on the site lattice, (2·kernelRadius + 1)² taps, row-major (the disc, or diffraction ⊛ disc). */
+    siteKernels: (wavelengthNm: number) => Float64Array;
+    wavelengthsNm: readonly number[];
+    kernelRadius: number;
+    nativeWidth: number;
+    nativeHeight: number;
+    sitePitchMicrometers: number;
+    /** Planar geometry of the base provider (plane distance and frame-unit scale), to find the plane point of a ray as it does. */
+    distanceM: number;
+    metresPerFrameUnit: number;
+    /** Offsets of the query points from the site centres, in sites (+x right, +y down). Default: one zero offset. */
+    queryOffsetsSites?: readonly {
+        x: number;
+        y: number;
+    }[];
+    /** Region renders: the native sites that will be queried. Values are bit-identical to the whole render's. Default: the whole raster. */
+    window?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Most distinct request times kept per band (the temporal sample count). Default 1. */
+    timesPerBand?: number;
+    /** Called with the duration in ms of each band convolution (diagnostics only). */
+    onConvolution?: (milliseconds: number) => void;
+    /**
+     * #564: a defocus kernel above the direct radius, convolved by runs in fixed tiles (`large-defocus-lattice.ts`), with each
+     * node's diffraction kernel after it; used instead of `siteKernels` (`kernelRadius` is then unused).
+     */
+    largeKernel?: LargeDefocusKernel;
+    /** #553: a field-varying kernel by zones (the cat's eye of lens.defocus), gathered instead of `siteKernels`, the same at every node. */
+    fieldZones?: SiteKernelFieldZones;
+}
+/** Internal (not exported from the package): the base provider with the defocus disc applied in image space (#548). */
+export declare function createDefocusImageSpaceProvider(input: DefocusImageSpaceProviderInput): PlanarSceneRadianceProvider;
+/** Field-variation bounds of the image-space disc for one request (#548), recorded in the `lens.defocus` assumption. */
+export interface DefocusFieldVariation {
+    /** Sensor points the bounds were evaluated at: a grid of this many points per side over the native raster, edges included. */
+    gridPointsPerSide: number;
+    /**
+     * Camera rotation (pitch or yaw tilts the scene plane in the camera frame): the largest change of the disc diameter, in
+     * sites, between the axial depth of each scene point in the rotated camera frame and the subject distance, over the grid and
+     * the rendered temporal midpoints. 0 for roll only; null without rotation.
+     */
+    rotationMaximumDiameterChangeSites: number | null;
+    /**
+     * Distortion: the largest deviation from 1 of the local scale of the distortion map (singular values of d distorted / d ideal)
+     * over the grid: the relative disc-size difference to a model that blurs the ideal image and then distorts it. Null without distortion.
+     */
+    distortionMaximumLocalScaleDeviation: number | null;
+    /**
+     * A non-rectilinear projection: the largest change of the disc diameter, in sites, between the distance along each scene
+     * point's ray and its axial depth (the thin-lens model uses the axial depth). Null for the rectilinear projection.
+     */
+    projectionMaximumDiameterChangeSites: number | null;
+}
+/** Internal: {@link DefocusFieldVariation} on a 9 × 9 grid of sensor points (the extremes of these smooth maps lie on the frame's edges). */
+export declare function calculateDefocusFieldVariation(input: {
+    geometry: PreparedDefocusImageSpaceGeometry;
+    lensMapping?: PreparedEnvironmentLensFieldMapping;
+    focalLengthMm: number;
+    fNumber: number;
+    focusDistanceM: number;
+    subjectDistanceM: number;
+    pitchMicrometers: number;
+    nativeWidth: number;
+    nativeHeight: number;
+    angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
+    temporalMidpointsSeconds: readonly number[];
+    diameterSites: number;
+    discAt: (subjectDistanceM: number) => number;
+}): DefocusFieldVariation;