@photivra/engine 0.5.1 → 1.0.0

package/dist/sensor/spatial-sampling-quadrature.js

@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Module boundary and integration notes.
+ * 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.
+ * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
+ * limits.
+ */
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError, requirePositiveInteger } from "../core/validation.js";
+import { resolveAntiAliasingSpatialKernel } from "./optical-stack.js";
+import { resolveSensorSamplingAperture } from "./sampling-aperture.js";
+const MAX_SPATIAL_QUADRATURE_NODES = 100_000;
+function midpointCoordinate(index, count) {
+    return (index + 0.5) / count;
+}
+function insideImagingArea(pointMm, imagingArea) {
+    const halfWidth = imagingArea.widthMm / 2;
+    const halfHeight = imagingArea.heightMm / 2;
+    return (pointMm.x >= -halfWidth &&
+        pointMm.x <= halfWidth &&
+        pointMm.y >= -halfHeight &&
+        pointMm.y <= halfHeight);
+}
+/**
+ * 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 function calculateSensorSpatialSamplingQuadrature(input) {
+    requirePositiveInteger("spatialSampleCountX", input.spatialSampleCountX);
+    requirePositiveInteger("spatialSampleCountY", input.spatialSampleCountY);
+    const samplingAperture = resolveSensorSamplingAperture({
+        imagingArea: input.imagingArea,
+        nativeRaster: input.nativeRaster,
+        colorSamplingProfile: input.colorSamplingProfile,
+        colorSamplingBindingProfile: input.colorSamplingBindingProfile,
+        samplingApertureProfile: input.samplingApertureProfile,
+        site: input.site
+    });
+    const antiAliasing = resolveAntiAliasingSpatialKernel(input.opticalStackProfile);
+    const apertureNodeCount = input.spatialSampleCountX *
+        input.spatialSampleCountY;
+    if (!Number.isSafeInteger(apertureNodeCount)) {
+        throw new InvalidScientificInputError("spatialSampleCountX × spatialSampleCountY must be a safe integer.");
+    }
+    const totalNodeCount = apertureNodeCount *
+        antiAliasing.components.length;
+    if (!Number.isSafeInteger(totalNodeCount)) {
+        throw new InvalidScientificInputError("Spatial quadrature node count must be a safe integer.");
+    }
+    if (totalNodeCount >
+        MAX_SPATIAL_QUADRATURE_NODES) {
+        throw new InvalidScientificInputError("Spatial quadrature node count exceeds the per-site safety limit of " +
+            MAX_SPATIAL_QUADRATURE_NODES +
+            ". Increase fidelity by tiling or batching downstream work rather than allocating one oversized node set.");
+    }
+    const aperture = samplingAperture.geometricSensitiveAperture;
+    const normalizedApertureWeight = 1 / apertureNodeCount;
+    const apertureAreaMeasureSquareMicrometers = aperture.areaSquareMicrometers /
+        apertureNodeCount;
+    const apertureCenterMm = aperture.centerFromOpticalAxisMm;
+    const widthMm = aperture.widthMicrometers / 1000;
+    const heightMm = aperture.heightMicrometers / 1000;
+    const leftMm = apertureCenterMm.x - widthMm / 2;
+    const topMm = apertureCenterMm.y - heightMm / 2;
+    const nodes = [];
+    let outsideCount = 0;
+    antiAliasing.components.forEach((aaComponent, antiAliasingComponentIndex) => {
+        const aaOffsetMm = {
+            x: aaComponent.offsetMicrometers.x /
+                1000,
+            y: aaComponent.offsetMicrometers.y /
+                1000
+        };
+        for (let apertureSampleYIndex = 0; apertureSampleYIndex <
+            input.spatialSampleCountY; apertureSampleYIndex += 1) {
+            const yPhase = midpointCoordinate(apertureSampleYIndex, input.spatialSampleCountY);
+            const destinationY = topMm + yPhase * heightMm;
+            for (let apertureSampleXIndex = 0; apertureSampleXIndex <
+                input.spatialSampleCountX; apertureSampleXIndex += 1) {
+                const xPhase = midpointCoordinate(apertureSampleXIndex, input.spatialSampleCountX);
+                const destinationX = leftMm + xPhase * widthMm;
+                const destinationAperturePointMm = {
+                    x: destinationX,
+                    y: destinationY
+                };
+                const preAntiAliasingSourcePointMm = {
+                    x: destinationX -
+                        aaOffsetMm.x,
+                    y: destinationY -
+                        aaOffsetMm.y
+                };
+                const sourceInside = insideImagingArea(preAntiAliasingSourcePointMm, input.imagingArea);
+                if (!sourceInside) {
+                    outsideCount += 1;
+                }
+                const combinedNormalizedSpatialWeight = normalizedApertureWeight *
+                    aaComponent.normalizedWeight;
+                const combinedAreaMeasureSquareMicrometers = apertureAreaMeasureSquareMicrometers *
+                    aaComponent.normalizedWeight;
+                nodes.push({
+                    antiAliasingComponentIndex,
+                    apertureSampleXIndex,
+                    apertureSampleYIndex,
+                    destinationAperturePointMm,
+                    antiAliasingOffsetMicrometers: {
+                        ...aaComponent.offsetMicrometers
+                    },
+                    preAntiAliasingSourcePointMm,
+                    preAntiAliasingSourceInsideImagingArea: sourceInside,
+                    normalizedApertureWeight,
+                    normalizedAntiAliasingWeight: aaComponent.normalizedWeight,
+                    combinedNormalizedSpatialWeight,
+                    apertureAreaMeasureSquareMicrometers,
+                    combinedAreaMeasureSquareMicrometers
+                });
+            }
+        }
+    });
+    const normalizedSpatialWeightSum = nodes.reduce((sum, node) => sum +
+        node.combinedNormalizedSpatialWeight, 0);
+    const combinedAreaMeasureSumSquareMicrometers = nodes.reduce((sum, node) => sum +
+        node.combinedAreaMeasureSquareMicrometers, 0);
+    return approximationResult({
+        coordinateSystem: "native-sensor-physical",
+        colorSamplingProfileId: samplingAperture
+            .colorSamplingProfileId,
+        samplingApertureProfileId: samplingAperture.profileId,
+        opticalStackProfileId: antiAliasing.profileId,
+        site: {
+            ...samplingAperture.site
+        },
+        channelId: samplingAperture.channelId,
+        quadratureScheme: "tensor-product-uniform-midpoint",
+        outputMeaning: "pre-aa-optical-field-spatial-quadrature-nodes",
+        spatialSampleCountX: input.spatialSampleCountX,
+        spatialSampleCountY: input.spatialSampleCountY,
+        antiAliasingComponentCount: antiAliasing.components.length,
+        totalNodeCount,
+        geometricApertureAreaSquareMicrometers: aperture.areaSquareMicrometers,
+        nominalSiteCellAreaSquareMicrometers: samplingAperture.lattice
+            .nominalCellAreaSquareMicrometers,
+        geometricSensitiveAreaFractionOfLatticeCell: aperture
+            .geometricSensitiveAreaFractionOfLatticeCell,
+        normalizedSpatialWeightSum,
+        combinedAreaMeasureSumSquareMicrometers,
+        preAntiAliasingSourceOutsideImagingAreaNodeCount: outsideCount,
+        sourcePointRule: "pre-aa-source-equals-destination-minus-aa-offset",
+        destinationCfaChannelAppliesToAllNodes: true,
+        cfaReassignmentBySourceCoordinate: false,
+        sourceCoveragePolicy: "not-applied",
+        nodes,
+        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: samplingAperture.provenance.profile,
+            samplingApertureLattice: samplingAperture.provenance.lattice,
+            geometricSensitiveAperture: samplingAperture.provenance.aperture,
+            opticalStackProfile: antiAliasing.provenance.profile,
+            antiAliasingResponse: antiAliasing.provenance
+                .antiAliasingResponse
+        }
+    }, "sensor-spatial-sampling-quadrature", "1.0.0", [
+        "Spatial aperture integration uses a deterministic tensor-product uniform midpoint rule.",
+        "The destination sensor site's semantic CFA/color channel applies to every quadrature node; pre-AA source coordinates never reassign the destination channel.",
+        "AA point-splitting is inverse-sampled: a +delta output displacement reads the pre-AA optical field at destination - delta.",
+        "AA component weights and aperture midpoint weights are dimensionless normalized spatial-average weights.",
+        "Square-micrometre measures are geometric integration measures only and are not effective radiometric collection area, throughput, QE, or photon count.",
+        "Pre-AA source points may leave the active physical imaging area and are not clamped, dropped, or renormalized.",
+        "The AA kernel remains the optical-stack foundation's field/wavelength/polarization-invariant approximation where applicable.",
+        "Microlens spatial response, charge diffusion, electrical/optical crosstalk, spectral response, radiometry, temporal integration, RAW sample generation, and reconstruction remain separate future work.",
+        "No geometry-only spatial quadrature error estimate is reported because downstream optical-field spatial frequency/content determines integration error."
+    ]);
+}
+//# sourceMappingURL=spatial-sampling-quadrature.js.map

package/dist/sensor/spatial-sampling-quadrature.js.map

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

package/dist/sensor/spatio-spectral-reduction.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Module boundary and integration notes.
+ * Internal shared node binding; domain callers retain value validation and equations.
+ * Reduces explicitly supplied sensor-plane spectral irradiance E_lambda(x,y) over the Cartesian
+ * product of an existing spatial quadrature and spectral quadrature. The supplied density unit is
+ * W/m^2/nm and wavelengthMeasureNanometers is d-lambda in nm, so their direct product has units W/m^2.
+ * Do not convert d-lambda to metres unless the spectral-density denominator is converted consistently.
+ * Spatial area integration uses the spatial quadrature's geometric area measures converted from square
+ * micrometres to square metres. The result is geometric-aperture incident radiant flux only; geometric
+ * area is not upgraded to an effective radiometric collection area. This reducer deliberately stops
+ * before sensor response. The spectral plan was derived from a specific response channel so its
+ * support/knots are useful, but QE, A/W responsivity and channel-filter transmission are not applied
+ * here. Response-scope/source-plane matching therefore remains an explicit later composition step.
+ * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
+ * limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type SensorSpatialQuadratureNodeIdentity } from "./spatial-sample-reduction.js";
+import type { SensorSpatialSamplingQuadrature } from "./spatial-sampling-quadrature.js";
+import { type SensorSpectralQuadrature, type SensorSpectralQuadratureNode } from "./spectral-quadrature.js";
+export interface SensorSpatioSpectralNodeIdentity {
+    spatialNode: SensorSpatialQuadratureNodeIdentity;
+    spectralSampleIndex: number;
+    wavelengthNanometers: number;
+}
+export interface SensorSpatioSpectralIrradianceSample {
+    node: SensorSpatioSpectralNodeIdentity;
+    /**
+     * Spectral irradiance evaluated at the spatial quadrature node's
+     * preAntiAliasingSourcePointMm and this spectral node's wavelength.
+     *
+     * Units: W/m^2/nm.
+     */
+    spectralIrradianceWattsPerSquareMeterPerNanometer: number;
+}
+export interface ReduceSensorSpatioSpectralIrradianceInput {
+    spatialQuadrature: SensorSpatialSamplingQuadrature;
+    spectralQuadrature: SensorSpectralQuadrature;
+    /**
+     * Exactly one explicitly identified E_lambda(x,y) value for every Cartesian
+     * product of spatial and spectral quadrature nodes.
+     *
+     * Ordering is not significant; node identity is.
+     */
+    sampleValues: readonly SensorSpatioSpectralIrradianceSample[];
+}
+export interface SensorSpatioSpectralWavelengthReduction {
+    spectralSampleIndex: number;
+    wavelengthNanometers: number;
+    wavelengthMeasureNanometers: number;
+    normalizedWavelengthWeight: number;
+    /**
+     * Spatially reduced spectral irradiance at this wavelength.
+     * Units: W/m^2/nm.
+     */
+    normalizedSpatialAverageSpectralIrradianceWattsPerSquareMeterPerNanometer: number;
+    /**
+     * Spectral radiant flux density incident over the geometric sensitive
+     * aperture after the declared normalized AA redistribution.
+     * Units: W/nm.
+     *
+     * This uses geometric area, not an established radiometric collection area.
+     */
+    geometricApertureIncidentSpectralFluxWattsPerNanometer: number;
+    /**
+     * Contribution to the wavelength-integrated spatial average.
+     * Units: W/m^2.
+     */
+    wavelengthIntegratedSpatialAverageContributionWattsPerSquareMeter: number;
+    /**
+     * Contribution to wavelength-integrated geometric-aperture incident flux.
+     * Units: W.
+     */
+    wavelengthIntegratedGeometricApertureIncidentFluxContributionWatts: number;
+}
+export interface SensorSpatioSpectralIrradianceReduction {
+    colorSamplingProfileId: string;
+    samplingApertureProfileId?: string;
+    opticalStackProfileId?: string;
+    site: {
+        x: number;
+        y: number;
+    };
+    channelId: string;
+    responseProfileId: string;
+    sourceResponseKind: SensorSpectralQuadrature["sourceResponseKind"];
+    responseScope: SensorSpectralQuadrature["responseScope"];
+    responseScientificStatus: SensorSpectralQuadrature["responseScientificStatus"];
+    responseUncertainty: SensorSpectralQuadrature["responseUncertainty"];
+    responseChannelBinding?: SensorSpectralQuadrature["responseChannelBinding"];
+    responseReferenceConditions?: SensorSpectralQuadrature["responseReferenceConditions"];
+    wavelengthBasis: SensorSpectralQuadrature["wavelengthBasis"];
+    wavelengthBasisResolved: boolean;
+    wavelengthRangeNanometers: SensorSpectralQuadrature["wavelengthRangeNanometers"];
+    responseDeclaredWavelengthRangeNanometers: SensorSpectralQuadrature["responseDeclaredWavelengthRangeNanometers"];
+    outputMeaning: "pre-response-spatio-spectral-radiometric-reduction";
+    inputValueDomain: {
+        kind: "radiometric-spectral-irradiance";
+        unit: "W/m^2/nm";
+        semantic: "pre-aa-pre-response-sensor-plane-spectral-irradiance";
+    };
+    spatialNodeCount: number;
+    spectralNodeCount: number;
+    combinedSampleCount: number;
+    sourceValuesMatchedBy: "spatial-node-identity-plus-spectral-sample-index-and-wavelength";
+    sourceValuesSuppliedForAllCombinedNodes: true;
+    outsideImagingAreaSourceValuesRequired: boolean;
+    geometricApertureAreaSquareMicrometers?: number;
+    nominalSiteCellAreaSquareMicrometers?: number;
+    geometricSensitiveAreaFractionOfLatticeCell?: number;
+    perWavelength: readonly SensorSpatioSpectralWavelengthReduction[];
+    /**
+     * Integral over the requested wavelength interval of the spatially averaged
+     * spectral irradiance. Units: W/m^2.
+     */
+    wavelengthIntegratedSpatialAverageIrradianceWattsPerSquareMeter: number;
+    /**
+     * Integral over the requested wavelength interval and geometric aperture
+     * area. Units: W.
+     *
+     * This is pre-sensor-response incident radiant flux over the declared
+     * wavelength interval, not collected optical power or generated charge.
+     */
+    wavelengthIntegratedGeometricApertureIncidentFluxWatts: number;
+    spatialIntegrationApplied: true;
+    wavelengthIntegrationApplied: true;
+    spectralResponsePlanUsedForWavelengthSupport: true;
+    spectralResponseApplicationPerformed: false;
+    responseScopeMatchedToSourcePlane: false;
+    quantumEfficiencyApplied: false;
+    spectralResponsivityApplied: false;
+    channelFilterTransmissionApplied: false;
+    opticalTransmissionAppliedByReducer: false;
+    radiometricCollectionAreaEstablished: false;
+    temporalIntegrationApplied: false;
+    exposureDurationApplied: false;
+    photonsCalculated: false;
+    electronsCalculated: false;
+    currentCalculated: false;
+    shotNoiseApplied: false;
+    readNoiseApplied: false;
+    adcQuantizationApplied: false;
+    rawCodeValueProduced: false;
+    demosaicOrReconstructionApplied: false;
+    convergenceErrorEstimated: false;
+    componentEvidence: {
+        spatial: SensorSpatialSamplingQuadrature["componentEvidence"];
+        spectral: SensorSpectralQuadrature["componentEvidence"];
+    };
+}
+/** Internal shared node binding; domain callers retain value validation and equations. */
+export declare function bindSensorSpatioSpectralSamples<T extends {
+    node: SensorSpatioSpectralNodeIdentity;
+}, V>(input: {
+    spatialQuadrature: SensorSpatialSamplingQuadrature;
+    spectralQuadrature: SensorSpectralQuadrature;
+    sampleValues: readonly T[];
+}, valueForSample: (sample: T, sampleIndex: number) => V): {
+    spatialNodesByKey: Map<string, SensorSpatialSamplingQuadrature["nodes"][number]>;
+    spectralNodesByIndex: Map<number, SensorSpectralQuadratureNode>;
+    colorSamplingProfileId: string;
+    combinedSampleCount: number;
+    valuesByKey: Map<string, V>;
+};
+/**
+ * Reduces explicitly supplied sensor-plane spectral irradiance E_lambda(x,y)
+ * over the Cartesian product of an existing spatial quadrature and spectral
+ * quadrature.
+ *
+ * The supplied density unit is W/m^2/nm and wavelengthMeasureNanometers is
+ * d-lambda in nm, so their direct product has units W/m^2. Do not convert
+ * d-lambda to metres unless the spectral-density denominator is converted
+ * consistently.
+ *
+ * Spatial area integration uses the spatial quadrature's geometric area
+ * measures converted from square micrometres to square metres. The result is
+ * geometric-aperture incident radiant flux only; geometric area is not upgraded
+ * to an effective radiometric collection area.
+ *
+ * This reducer deliberately stops before sensor response. The spectral plan was
+ * derived from a specific response channel so its support/knots are useful, but
+ * QE, A/W responsivity and channel-filter transmission are not applied here.
+ * Response-scope/source-plane matching therefore remains an explicit later
+ * composition step.
+ */
+export declare function reduceSensorSpatioSpectralIrradiance(input: ReduceSensorSpatioSpectralIrradianceInput): CalculationResult<SensorSpatioSpectralIrradianceReduction>;
+//# sourceMappingURL=spatio-spectral-reduction.d.ts.map

package/dist/sensor/spatio-spectral-reduction.d.ts.map

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