@photivra/engine 2.20.0 → 2.22.0

package/dist/facade/display-view-rendering.d.ts

@@ -0,0 +1,97 @@
+import { type SdrToneCurve, type SdrToneCurveParameters } from "../output/sdr-rendering.js";
+import type { DisplayViewSetup } from "./display-view.js";
+/**
+ * Internal (exported for tests). The n-point Gauss–Hermite rule of the standard normal: Σ w_i f(x_i) ≈ E[f(Z)], Z ~ N(0, 1).
+ * The nodes are the eigenvalues of the Jacobi matrix of the orthonormal Hermite polynomials (zero diagonal, off-diagonal √k),
+ * found by Sturm-sequence bisection, and w_i = 1/Σ_k p_k(x_i)² (Golub & Welsch 1969). Only correctly rounded operations, so the
+ * rule has the same bits in every JavaScript engine.
+ */
+export declare function gaussHermite(n: number): {
+    x: Float64Array;
+    w: Float64Array;
+};
+/** Points per axis of the 3-D rule (full and fast) and of the fast 1-D luminance rule. */
+export declare const DISPLAY_VIEW_CHAIN_POINTS: Readonly<{
+    full: 16;
+    fast: 6;
+}>;
+export declare const DISPLAY_VIEW_LUMINANCE_FAST_POINTS = 8;
+/** What the view renders: the request's tone curve, highlight mode and gamut handling (#601), and whether the fast rules run. */
+export interface DisplayViewRenderingChoice {
+    toneCurve: SdrToneCurve;
+    toneCurveParameters?: SdrToneCurveParameters;
+    /** #602: "reconstruct-neighbors" rebuilds clipped channels from the ratios around each clipped region (src/color/neighbor-highlight-reconstruction.ts). */
+    highlightMode: "clip" | "reconstruct" | "reconstruct-neighbors";
+    gamutHandling: "clip-components" | "desaturate-to-luminance";
+    fast: boolean;
+}
+/** The coupled steps of one view (see the module notes), or null for a view without them (its arithmetic is unchanged). */
+export interface DisplayViewCoupledRendering {
+    readonly luminanceTone: boolean;
+    /** True with either reconstruct mode (the highlight step couples the channels). */
+    readonly reconstruct: boolean;
+    /** #602: the neighbor reconstruction (its pixels take their region's ratios, `bindView` and `at`). */
+    readonly neighbors: boolean;
+    /**
+     * #602: binds a render's expected (noise-free) camera channels, from which the clipped regions and their ratios are found on
+     * demand, and returns the counters of the regions it measured.
+     */
+    bindView?(setup: DisplayViewSetup): void;
+    /** #602: the real pixel (native site coordinates) whose moments `chain` computes next. */
+    at?(x: number, y: number): void;
+    /** #602: regions measured, and regions whose search stopped at the size cap (their ratios from the part found). */
+    readonly neighborRegions: {
+        measured: number;
+        capped: number;
+    };
+    readonly desaturate: boolean;
+    readonly choice: DisplayViewRenderingChoice;
+    /** Points per axis of the 3-D rule in use; the luminance rule's Gauss–Hermite nodes and weights (8 points), for the GPU kernels. */
+    readonly chainPoints: number;
+    readonly chainRule: {
+        x: Float64Array;
+        w: Float64Array;
+    };
+    readonly luminanceRule: {
+        x: Float64Array;
+        w: Float64Array;
+    };
+    /** The luminance curve's ratio limit r(0+) (1, 0, 1/(σ·g(Lw)) or ∞). */
+    readonly ratioAtZero: number;
+    /** Renders one deterministic camera pixel (WB, highlight, matrix, tone, gamut, clip) into out (the AHD correction's pixels). */
+    pixel(c0: number, c1: number, c2: number, out: Float64Array): void;
+    /**
+     * The moments of the rendered pixel for camera channels c ~ N(cm, C) (C row-major 3 × 3), integrated over the whole chain:
+     * mean (hm), variance (hv) and the expected slopes ∂out_k/∂c_j (A, row-major 3 × 3). Returns the number of nodes evaluated.
+     */
+    chain(cm: Float64Array, C: Float64Array, hm: Float64Array, hv: Float64Array, A: Float64Array): number;
+    /**
+     * Whether the reconstruct blend is within reach of channels c ~ N(cm, C): some channel's mean + 8.5σ above the blend's start.
+     * Out of reach the highlight step is the unclipped white balance.
+     */
+    reconstructInReach(cm: Float64Array, C: Float64Array): boolean;
+    /**
+     * The luminance tone curve on developed values y ~ N(μ, Σ) (Σ row-major 3 × 3): mean (hm), variance (hv) and the expected
+     * slopes J = E[∂out/∂y] (row-major). Returns false when a component reaches 1 within reach and the desaturation is on (the
+     * caller then integrates the chain), else true.
+     */
+    tone(mu: Float64Array, S: Float64Array, hm: Float64Array, hv: Float64Array, J: Float64Array): boolean;
+}
+/** #602: a render's noise-free camera channels at a real pixel (native coordinates), and the output raster's native bounds. */
+export interface NeighborView {
+    channels(x: number, y: number, out: Float64Array): void;
+    x0: number;
+    y0: number;
+    width: number;
+    height: number;
+}
+/** #602: the most pixels a clipped region's search visits (fast and full); a larger region takes its ratios from the part found. */
+export declare const DISPLAY_VIEW_NEIGHBOR_REGION_LIMIT: Readonly<{
+    fast: number;
+    full: number;
+}>;
+/**
+ * Internal: the coupled rendering of a view, or null when its tone curve is per channel, its highlight mode `clip` and its gamut
+ * handling the component clip (the view's own per-component arithmetic then runs, byte for byte as before).
+ */
+export declare function createDisplayViewCoupledRendering(choice: DisplayViewRenderingChoice, gains: readonly number[], clipLevel: number, matrix: readonly (readonly number[])[]): DisplayViewCoupledRendering | null;