@photivra/engine 0.5.1 → 0.6.0

package/dist/sensor/spatial-sample-reduction.js

@@ -0,0 +1,299 @@
+// SPDX-License-Identifier: Apache-2.0
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+const SQUARE_MICROMETERS_TO_SQUARE_METERS = 1e-12;
+const WEIGHT_TOLERANCE = 1e-10;
+const AREA_TOLERANCE = 1e-10;
+function requireSafeNonNegativeInteger(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < 0) {
+        throw new InvalidScientificInputError(path +
+            " must be a non-negative safe integer.");
+    }
+    return value;
+}
+function requireNonNegativeFinite(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        value < 0) {
+        throw new InvalidScientificInputError(path +
+            " must be a finite number greater than or equal to zero.");
+    }
+    return value;
+}
+function requirePositiveFinite(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        value <= 0) {
+        throw new InvalidScientificInputError(path +
+            " must be a finite number greater than zero.");
+    }
+    return value;
+}
+function parseValueDomain(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value)) {
+        throw new InvalidScientificInputError("valueDomain must be an object.");
+    }
+    const record = value;
+    if (record.kind === "relative-linear") {
+        if (record.unit !== "relative" ||
+            record.semantic !==
+                "nonnegative-sensor-plane-irradiance-proxy") {
+            throw new InvalidScientificInputError("relative-linear valueDomain must use unit \"relative\" and the canonical nonnegative sensor-plane irradiance-proxy semantic.");
+        }
+        return {
+            kind: "relative-linear",
+            unit: "relative",
+            semantic: "nonnegative-sensor-plane-irradiance-proxy"
+        };
+    }
+    if (record.kind === "radiometric-irradiance") {
+        if (record.unit !== "W/m^2" ||
+            record.semantic !==
+                "sensor-plane-irradiance") {
+            throw new InvalidScientificInputError("radiometric-irradiance valueDomain must use unit \"W/m^2\" and semantic \"sensor-plane-irradiance\".");
+        }
+        return {
+            kind: "radiometric-irradiance",
+            unit: "W/m^2",
+            semantic: "sensor-plane-irradiance"
+        };
+    }
+    throw new InvalidScientificInputError("valueDomain.kind is invalid.");
+}
+function nodeIdentityKey(identity) {
+    return (identity.antiAliasingComponentIndex +
+        ":" +
+        identity.apertureSampleXIndex +
+        ":" +
+        identity.apertureSampleYIndex);
+}
+function validateQuadratureNode(node, index) {
+    const identity = {
+        antiAliasingComponentIndex: requireSafeNonNegativeInteger(node.antiAliasingComponentIndex, "quadrature.nodes[" +
+            index +
+            "].antiAliasingComponentIndex"),
+        apertureSampleXIndex: requireSafeNonNegativeInteger(node.apertureSampleXIndex, "quadrature.nodes[" +
+            index +
+            "].apertureSampleXIndex"),
+        apertureSampleYIndex: requireSafeNonNegativeInteger(node.apertureSampleYIndex, "quadrature.nodes[" +
+            index +
+            "].apertureSampleYIndex")
+    };
+    requireNonNegativeFinite(node.combinedNormalizedSpatialWeight, "quadrature.nodes[" +
+        index +
+        "].combinedNormalizedSpatialWeight");
+    requireNonNegativeFinite(node.combinedAreaMeasureSquareMicrometers, "quadrature.nodes[" +
+        index +
+        "].combinedAreaMeasureSquareMicrometers");
+    return identity;
+}
+function approximatelyEqual(actual, expected, tolerance) {
+    const scale = Math.max(1, Math.abs(actual), Math.abs(expected));
+    return (Math.abs(actual - expected) <=
+        tolerance * scale);
+}
+function validateQuadrature(quadrature) {
+    if (typeof quadrature !== "object" ||
+        quadrature === null ||
+        !Array.isArray(quadrature.nodes)) {
+        throw new InvalidScientificInputError("quadrature must contain a nodes array.");
+    }
+    const totalNodeCount = requireSafeNonNegativeInteger(quadrature.totalNodeCount, "quadrature.totalNodeCount");
+    if (totalNodeCount === 0 ||
+        quadrature.nodes.length !==
+            totalNodeCount) {
+        throw new InvalidScientificInputError("quadrature.totalNodeCount must be positive and exactly match quadrature.nodes.length.");
+    }
+    if (typeof quadrature.channelId !== "string" ||
+        quadrature.channelId.trim().length === 0) {
+        throw new InvalidScientificInputError("quadrature.channelId must be a non-empty string.");
+    }
+    requireSafeNonNegativeInteger(quadrature.site.x, "quadrature.site.x");
+    requireSafeNonNegativeInteger(quadrature.site.y, "quadrature.site.y");
+    const geometricArea = requirePositiveFinite(quadrature.geometricApertureAreaSquareMicrometers, "quadrature.geometricApertureAreaSquareMicrometers");
+    const nodesByKey = new Map();
+    let weightSum = 0;
+    let areaSum = 0;
+    quadrature.nodes.forEach((node, index) => {
+        const identity = validateQuadratureNode(node, index);
+        const key = nodeIdentityKey(identity);
+        if (nodesByKey.has(key)) {
+            throw new InvalidScientificInputError("quadrature contains duplicate node identities.");
+        }
+        nodesByKey.set(key, node);
+        weightSum +=
+            node.combinedNormalizedSpatialWeight;
+        areaSum +=
+            node.combinedAreaMeasureSquareMicrometers;
+        if (!Number.isFinite(weightSum) ||
+            !Number.isFinite(areaSum)) {
+            throw new InvalidScientificInputError("quadrature aggregate weights/measures must remain finite.");
+        }
+    });
+    if (!approximatelyEqual(weightSum, 1, WEIGHT_TOLERANCE)) {
+        throw new InvalidScientificInputError("quadrature combined normalized spatial weights must sum to 1.");
+    }
+    if (!approximatelyEqual(areaSum, geometricArea, AREA_TOLERANCE)) {
+        throw new InvalidScientificInputError("quadrature combined geometric area measures must sum to the geometric aperture area.");
+    }
+    if (!approximatelyEqual(quadrature.normalizedSpatialWeightSum, weightSum, WEIGHT_TOLERANCE)) {
+        throw new InvalidScientificInputError("quadrature.normalizedSpatialWeightSum does not match node weights.");
+    }
+    if (!approximatelyEqual(quadrature.combinedAreaMeasureSumSquareMicrometers, areaSum, AREA_TOLERANCE)) {
+        throw new InvalidScientificInputError("quadrature.combinedAreaMeasureSumSquareMicrometers does not match node measures.");
+    }
+    return nodesByKey;
+}
+function parseNodeValues(nodeValues, nodesByKey) {
+    if (!Array.isArray(nodeValues)) {
+        throw new InvalidScientificInputError("nodeValues must be an array.");
+    }
+    if (nodeValues.length !==
+        nodesByKey.size) {
+        throw new InvalidScientificInputError("nodeValues must contain exactly one value for every quadrature node.");
+    }
+    const valuesByKey = new Map();
+    nodeValues.forEach((entry, index) => {
+        if (typeof entry !== "object" ||
+            entry === null ||
+            typeof entry.node !== "object" ||
+            entry.node === null) {
+            throw new InvalidScientificInputError("nodeValues[" +
+                index +
+                "] must contain a node identity object.");
+        }
+        const identity = {
+            antiAliasingComponentIndex: requireSafeNonNegativeInteger(entry.node
+                .antiAliasingComponentIndex, "nodeValues[" +
+                index +
+                "].node.antiAliasingComponentIndex"),
+            apertureSampleXIndex: requireSafeNonNegativeInteger(entry.node.apertureSampleXIndex, "nodeValues[" +
+                index +
+                "].node.apertureSampleXIndex"),
+            apertureSampleYIndex: requireSafeNonNegativeInteger(entry.node.apertureSampleYIndex, "nodeValues[" +
+                index +
+                "].node.apertureSampleYIndex")
+        };
+        const key = nodeIdentityKey(identity);
+        if (!nodesByKey.has(key)) {
+            throw new InvalidScientificInputError("nodeValues[" +
+                index +
+                "] identifies a node that is not present in quadrature.");
+        }
+        if (valuesByKey.has(key)) {
+            throw new InvalidScientificInputError("nodeValues contains duplicate node identities.");
+        }
+        valuesByKey.set(key, requireNonNegativeFinite(entry.value, "nodeValues[" +
+            index +
+            "].value"));
+    });
+    return valuesByKey;
+}
+/**
+ * Reduces explicitly identified nonnegative linear scalar values over a
+ * validated sensor spatial quadrature.
+ *
+ * This function does not sample a renderer or optical model itself. Callers
+ * evaluate one value at every quadrature node's preAntiAliasingSourcePointMm
+ * and provide those values with exact node identity. Ordering is deliberately
+ * irrelevant.
+ *
+ * Two domains are supported:
+ *
+ * - relative-linear: dimensionless nonnegative irradiance-like proxy for
+ *   deterministic renderer/science regression;
+ * - radiometric-irradiance: physical sensor-plane irradiance in W/m^2.
+ *
+ * The destination site's channelId is metadata only. No CFA spectral
+ * transmittance/sensitivity is applied, so the output must not be called a
+ * physically color-filtered mosaic sample or RAW value.
+ */
+export function reduceSensorSpatialSamplingQuadrature(input) {
+    const domain = parseValueDomain(input.valueDomain);
+    const nodesByKey = validateQuadrature(input.quadrature);
+    const valuesByKey = parseNodeValues(input.nodeValues, nodesByKey);
+    let weightedAverage = 0;
+    let areaWeightedIntegral = 0;
+    nodesByKey.forEach((node, key) => {
+        const value = valuesByKey.get(key);
+        if (value === undefined) {
+            throw new InvalidScientificInputError("A quadrature node is missing its explicit source value.");
+        }
+        weightedAverage +=
+            value *
+                node.combinedNormalizedSpatialWeight;
+        areaWeightedIntegral +=
+            value *
+                node.combinedAreaMeasureSquareMicrometers;
+        if (!Number.isFinite(weightedAverage) ||
+            !Number.isFinite(areaWeightedIntegral)) {
+            throw new InvalidScientificInputError("Reduced spatial sample must remain finite.");
+        }
+    });
+    const reducedValue = domain.kind === "relative-linear"
+        ? {
+            kind: "relative-linear",
+            unit: "relative",
+            semantic: "nonnegative-sensor-plane-irradiance-proxy",
+            normalizedSpatialAverageRelative: weightedAverage,
+            geometricAreaIntegralRelativeSquareMicrometers: areaWeightedIntegral
+        }
+        : {
+            kind: "radiometric-irradiance",
+            unit: "W/m^2",
+            semantic: "sensor-plane-irradiance",
+            normalizedSpatialAverageIrradianceWattsPerSquareMeter: weightedAverage,
+            geometricApertureIncidentFluxWatts: areaWeightedIntegral *
+                SQUARE_MICROMETERS_TO_SQUARE_METERS
+        };
+    return approximationResult({
+        site: {
+            ...input.quadrature.site
+        },
+        channelId: input.quadrature.channelId,
+        outputMeaning: "channel-tagged-pre-response-spatial-sample",
+        valueDomain: domain,
+        nodeCount: input.quadrature.totalNodeCount,
+        sourceValuesMatchedBy: "quadrature-node-identity",
+        sourceValuesSuppliedForAllNodes: true,
+        outsideImagingAreaSourceValuesRequired: input.quadrature
+            .preAntiAliasingSourceOutsideImagingAreaNodeCount >
+            0,
+        normalizedSpatialWeightSum: input.quadrature
+            .normalizedSpatialWeightSum,
+        geometricApertureAreaSquareMicrometers: input.quadrature
+            .geometricApertureAreaSquareMicrometers,
+        reducedValue,
+        cfaSpectralFilteringApplied: false,
+        channelIdIsSpectralResponse: false,
+        temporalIntegrationApplied: false,
+        exposureDurationApplied: false,
+        quantumEfficiencyApplied: false,
+        microlensResponseApplied: false,
+        opticalThroughputAppliedByReducer: false,
+        photonsCalculated: false,
+        electronsCalculated: false,
+        shotNoiseApplied: false,
+        readNoiseApplied: false,
+        adcQuantizationApplied: false,
+        blackLevelApplied: false,
+        saturationApplied: false,
+        rawCodeValueProduced: false,
+        demosaicOrReconstructionApplied: false
+    }, "sensor-spatial-sample-reduction", "1.0.0", [
+        "Input values are nonnegative linear scalars evaluated at each quadrature node's pre-AA source coordinate.",
+        "Node values are matched by explicit quadrature-node identity rather than positional array order.",
+        "The destination CFA/color channel is metadata only; no spectral transmittance, sensor spectral responsivity or quantum efficiency is applied.",
+        "Relative-linear values are dimensionless irradiance-like proxies for deterministic testing and do not become physical radiometry.",
+        "Radiometric-irradiance values use W/m^2; geometric aperture integration converts square micrometres to square metres to report incident radiant flux in watts.",
+        "The physical irradiance branch reports geometric-aperture incident flux under the caller-supplied irradiance field and normalized AA spatial redistribution; it does not add omitted optical-stack throughput, microlens response, CFA response or sensor conversion.",
+        "Every quadrature node requires an explicit source value, including pre-AA source points outside the active imaging area; no automatic clamping, zero-fill, extrapolation or renormalization occurs.",
+        "Negative, NaN and infinite source values are rejected; signed intermediate color-transform values are outside this pre-response sensor-plane contract.",
+        "Temporal exposure integration, wavelength integration, photons/electrons, noise, saturation, black level, ADC quantization, RAW code values and reconstruction remain separate future work."
+    ]);
+}
+//# sourceMappingURL=spatial-sample-reduction.js.map

package/dist/sensor/spatial-sample-reduction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-sample-reduction.js","sourceRoot":"","sources":["../../src/sensor/spatial-sample-reduction.ts"],"names":[],"mappings":"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"}

package/dist/sensor/spatial-sampling-quadrature.d.ts

@@ -0,0 +1,155 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+import type { NativeEffectiveRasterColorSamplingBindingProfile } from "./capture-color-sampling-binding.js";
+import type { NativeColorSamplingSiteIndex, SensorColorSamplingProfile } from "./color-sampling.js";
+import { type SensorOpticalStackProfile } from "./optical-stack.js";
+import { type SensorSamplingApertureProfile } from "./sampling-aperture.js";
+import type { NativeImageRaster, SensorImagingArea } from "./sensor-geometry.js";
+export interface CalculateSensorSpatialSamplingQuadratureInput {
+    imagingArea: SensorImagingArea;
+    nativeRaster: NativeImageRaster;
+    colorSamplingProfile: SensorColorSamplingProfile;
+    colorSamplingBindingProfile: NativeEffectiveRasterColorSamplingBindingProfile;
+    samplingApertureProfile: SensorSamplingApertureProfile;
+    opticalStackProfile: SensorOpticalStackProfile;
+    site: NativeColorSamplingSiteIndex;
+    /** Number of midpoint cells across the geometric aperture width. */
+    spatialSampleCountX: number;
+    /** Number of midpoint cells across the geometric aperture height. */
+    spatialSampleCountY: number;
+}
+export interface SensorSpatialSamplingQuadratureNode {
+    antiAliasingComponentIndex: number;
+    apertureSampleXIndex: number;
+    apertureSampleYIndex: number;
+    /**
+     * Destination point inside the geometric sensitive aperture after the
+     * declared AA point-splitting response.
+     *
+     * Native sensor physical coordinates, millimetres from the optical axis.
+     */
+    destinationAperturePointMm: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Declared AA displacement of optical energy on the sensor plane.
+     *
+     * +X right, +Y down; micrometres.
+     */
+    antiAliasingOffsetMicrometers: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Pre-AA source point that maps to destinationAperturePointMm under the
+     * declared split component:
+     *
+     * source = destination - AA offset
+     */
+    preAntiAliasingSourcePointMm: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Whether the pre-AA source point lies inside the active physical imaging
+     * area. False is not an error; downstream source-coverage policy decides how
+     * to handle valid optical support outside the active sampling area.
+     */
+    preAntiAliasingSourceInsideImagingArea: boolean;
+    /** Dimensionless midpoint weight for the aperture-area average. */
+    normalizedApertureWeight: number;
+    /** Dimensionless normalized weight from the AA split component. */
+    normalizedAntiAliasingWeight: number;
+    /**
+     * Dimensionless product used for a spatial average of a downstream optical
+     * field under this quadrature approximation.
+     */
+    combinedNormalizedSpatialWeight: number;
+    /**
+     * Geometric area measure represented by this aperture midpoint before the
+     * AA component weight is applied. Units: square micrometres.
+     */
+    apertureAreaMeasureSquareMicrometers: number;
+    /**
+     * Geometric area measure multiplied by the dimensionless AA component
+     * weight. Units remain square micrometres.
+     *
+     * This is not an effective radiometric collection area.
+     */
+    combinedAreaMeasureSquareMicrometers: number;
+}
+export interface SensorSpatialSamplingQuadrature {
+    coordinateSystem: "native-sensor-physical";
+    site: NativeColorSamplingSiteIndex;
+    channelId: string;
+    quadratureScheme: "tensor-product-uniform-midpoint";
+    outputMeaning: "pre-aa-optical-field-spatial-quadrature-nodes";
+    spatialSampleCountX: number;
+    spatialSampleCountY: number;
+    antiAliasingComponentCount: number;
+    totalNodeCount: number;
+    geometricApertureAreaSquareMicrometers: number;
+    normalizedSpatialWeightSum: number;
+    combinedAreaMeasureSumSquareMicrometers: number;
+    preAntiAliasingSourceOutsideImagingAreaNodeCount: number;
+    sourcePointRule: "pre-aa-source-equals-destination-minus-aa-offset";
+    destinationCfaChannelAppliesToAllNodes: true;
+    cfaReassignmentBySourceCoordinate: false;
+    sourceCoveragePolicy: "not-applied";
+    nodes: readonly SensorSpatialSamplingQuadratureNode[];
+    /**
+     * Hard scientific boundaries.
+     */
+    opticalFieldValuesIncluded: false;
+    radianceIncluded: false;
+    photonsIncluded: false;
+    electronsIncluded: false;
+    spectralResponseIncluded: false;
+    quantumEfficiencyIncluded: false;
+    opticalThroughputIncluded: false;
+    microlensResponseIncluded: false;
+    chargeDiffusionIncluded: false;
+    electricalCrosstalkIncluded: false;
+    temporalIntegrationIncluded: false;
+    rawSampleValueIncluded: false;
+    reconstructedPixelValueIncluded: false;
+    geometricAreaMeasureIsRadiometricCollectionArea: false;
+    componentEvidence: {
+        samplingApertureProfile: readonly import("../core/evidence-provenance.js").EvidenceProvenance[];
+        samplingApertureLattice: readonly import("../core/evidence-provenance.js").EvidenceProvenance[];
+        geometricSensitiveAperture: readonly import("../core/evidence-provenance.js").EvidenceProvenance[];
+        opticalStackProfile: readonly import("../core/evidence-provenance.js").EvidenceProvenance[];
+        antiAliasingResponse: readonly import("../core/evidence-provenance.js").EvidenceProvenance[];
+    };
+}
+/**
+ * Builds deterministic spatial quadrature nodes for one CFA/color-sampling site.
+ *
+ * The quadrature composes:
+ *
+ * 1. the resolved geometric sensitive aperture from the sampling-aperture
+ *    foundation; and
+ * 2. the resolved effective AA point-splitting kernel from the optical-stack
+ *    foundation.
+ *
+ * The first aperture integration uses a tensor-product uniform midpoint rule.
+ * For an AA component that moves optical energy by +delta on the sensor plane,
+ * a destination aperture point samples the pre-AA optical field at
+ * destination - delta. This inverse-source convention prevents applying the AA
+ * shift twice.
+ *
+ * The destination sensor site's CFA channel applies to every node. The
+ * pre-AA source coordinate is an optical-field location, not another CFA site;
+ * therefore shifted source coordinates never reassign the destination channel.
+ *
+ * Nodes whose pre-AA source coordinates fall outside the active imaging area
+ * are retained. They are neither clamped nor dropped/renormalized. A renderer
+ * or optical-field provider owns source-coverage policy.
+ *
+ * normalized weights approximate a spatial average. Square-micrometre measures
+ * approximate a geometric area integral. Neither includes radiometric
+ * throughput, QE, photon conversion, microlenses, diffusion/crosstalk, or
+ * temporal integration.
+ */
+export declare function calculateSensorSpatialSamplingQuadrature(input: CalculateSensorSpatialSamplingQuadratureInput): CalculationResult<SensorSpatialSamplingQuadrature>;
+//# sourceMappingURL=spatial-sampling-quadrature.d.ts.map

package/dist/sensor/spatial-sampling-quadrature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spatial-sampling-quadrature.d.ts","sourceRoot":"","sources":["../../src/sensor/spatial-sampling-quadrature.ts"],"names":[],"mappings":"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"}