@photivra/engine 1.4.0 → 2.0.0

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

@@ -1,19 +1,14 @@
 /**
- * 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.
+ * Spatial sampling quadrature: the sample points (nodes) and weights used to average light over one
+ * sensor site.
+ *
+ * It combines the site's geometric light-sensitive aperture (sampling-aperture) with the anti-aliasing
+ * (AA) point-splitting kernel (optical-stack). The aperture is integrated with a grid of evenly spaced
+ * midpoints. If an AA component moves light by +delta on the sensor, a destination point samples the
+ * light field before AA at destination − delta, so the shift is never applied twice. Normalized weights
+ * give a spatial average; square-micrometre measures give a geometric area integral. Neither includes
+ * throughput, QE (quantum efficiency), photon conversion, microlenses, diffusion, crosstalk or
+ * integration over time.
  * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
@@ -41,17 +36,17 @@ export interface SensorSpatialSamplingQuadratureNode {
     apertureSampleXIndex: number;
     apertureSampleYIndex: number;
     /**
-     * Destination point inside the geometric sensitive aperture after the
-     * declared AA point-splitting response.
+     * Destination point inside the geometric sensitive aperture, after the
+     * declared AA point splitting.
      *
-     * Native sensor physical coordinates, millimetres from the optical axis.
+     * Native sensor physical coordinates, in millimetres from the optical axis.
      */
     destinationAperturePointMm: {
         x: number;
         y: number;
     };
     /**
-     * Declared AA displacement of optical energy on the sensor plane.
+     * How far the declared AA component moves light on the sensor plane.
      *
      * +X right, +Y down; micrometres.
      */
@@ -60,8 +55,8 @@ export interface SensorSpatialSamplingQuadratureNode {
         y: number;
     };
     /**
-     * Pre-AA source point that maps to destinationAperturePointMm under the
-     * declared split component:
+     * The point in the light field before AA that lands on
+     * destinationAperturePointMm through this split component:
      *
      * source = destination - AA offset
      */
@@ -70,9 +65,9 @@ export interface SensorSpatialSamplingQuadratureNode {
         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.
+     * Whether the pre-AA source point is inside the active physical imaging
+     * area. False is not an error; downstream code decides how to handle valid
+     * light from outside the active sampling area.
      */
     preAntiAliasingSourceInsideImagingArea: boolean;
     /** Dimensionless midpoint weight for the aperture-area average. */
@@ -80,20 +75,20 @@ export interface SensorSpatialSamplingQuadratureNode {
     /** 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.
+     * Product of the two weights (dimensionless), used to average a light field
+     * over the site with this quadrature.
      */
     combinedNormalizedSpatialWeight: number;
     /**
-     * Geometric area measure represented by this aperture midpoint before the
-     * AA component weight is applied. Units: square micrometres.
+     * Geometric area this aperture midpoint stands for, 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.
+     * Geometric area multiplied by the (dimensionless) AA component weight.
+     * Units are still square micrometres.
      *
-     * This is not an effective radiometric collection area.
+     * This is not an effective light-collection area.
      */
     combinedAreaMeasureSquareMicrometers: number;
 }
@@ -122,7 +117,7 @@ export interface SensorSpatialSamplingQuadrature {
     sourceCoveragePolicy: "not-applied";
     nodes: readonly SensorSpatialSamplingQuadratureNode[];
     /**
-     * Hard scientific boundaries.
+     * Fixed statements of what this result does not include.
      */
     opticalFieldValuesIncluded: false;
     radianceIncluded: false;
@@ -147,33 +142,30 @@ export interface SensorSpatialSamplingQuadrature {
     };
 }
 /**
- * Builds deterministic spatial quadrature nodes for one CFA/color-sampling site.
+ * Builds the deterministic spatial sample points (quadrature nodes) for one CFA
+ * (colour filter array) site.
  *
- * The quadrature composes:
+ * It combines:
  *
- * 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.
+ * 1. the site's geometric light-sensitive aperture (from sampling-aperture); and
+ * 2. the anti-aliasing (AA) point-splitting kernel (from optical-stack).
  *
- * 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 aperture is integrated with a grid of evenly spaced midpoints (a
+ * tensor-product midpoint rule). If an AA component moves light by +delta on
+ * the sensor, a destination point samples the light field before AA at
+ * destination − delta. Working backwards like this means the shift is never
+ * applied 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.
+ * The destination site's CFA channel applies to every node. The pre-AA source
+ * point is a position in the light field, not another CFA site, so a shifted
+ * source point never changes 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.
+ * Nodes whose pre-AA source point falls outside the active imaging area are
+ * kept. They are neither clamped nor dropped (and weights are not
+ * renormalized). The renderer or light-field provider decides how to cover them.
  *
- * 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.
+ * Normalized weights approximate a spatial average. Square-micrometre measures
+ * approximate a geometric area integral. Neither includes throughput, QE,
+ * photon conversion, microlenses, diffusion, crosstalk or integration over time.
  */
 export declare function calculateSensorSpatialSamplingQuadrature(input: CalculateSensorSpatialSamplingQuadratureInput): CalculationResult<SensorSpatialSamplingQuadrature>;
-//# sourceMappingURL=spatial-sampling-quadrature.d.ts.map

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

@@ -1,20 +1,15 @@
 // 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.
+ * Spatial sampling quadrature: the sample points (nodes) and weights used to average light over one
+ * sensor site.
+ *
+ * It combines the site's geometric light-sensitive aperture (sampling-aperture) with the anti-aliasing
+ * (AA) point-splitting kernel (optical-stack). The aperture is integrated with a grid of evenly spaced
+ * midpoints. If an AA component moves light by +delta on the sensor, a destination point samples the
+ * light field before AA at destination − delta, so the shift is never applied twice. Normalized weights
+ * give a spatial average; square-micrometre measures give a geometric area integral. Neither includes
+ * throughput, QE (quantum efficiency), photon conversion, microlenses, diffusion, crosstalk or
+ * integration over time.
  * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
@@ -22,6 +17,7 @@ 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";
+import { requireInputKeys } from "../core/record-validation.js";
 const MAX_SPATIAL_QUADRATURE_NODES = 100_000;
 function midpointCoordinate(index, count) {
     return (index + 0.5) / count;
@@ -35,35 +31,34 @@ function insideImagingArea(pointMm, imagingArea) {
         pointMm.y <= halfHeight);
 }
 /**
- * Builds deterministic spatial quadrature nodes for one CFA/color-sampling site.
+ * Builds the deterministic spatial sample points (quadrature nodes) for one CFA
+ * (colour filter array) site.
  *
- * The quadrature composes:
+ * It combines:
  *
- * 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.
+ * 1. the site's geometric light-sensitive aperture (from sampling-aperture); and
+ * 2. the anti-aliasing (AA) point-splitting kernel (from optical-stack).
  *
- * 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 aperture is integrated with a grid of evenly spaced midpoints (a
+ * tensor-product midpoint rule). If an AA component moves light by +delta on
+ * the sensor, a destination point samples the light field before AA at
+ * destination − delta. Working backwards like this means the shift is never
+ * applied 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.
+ * The destination site's CFA channel applies to every node. The pre-AA source
+ * point is a position in the light field, not another CFA site, so a shifted
+ * source point never changes 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.
+ * Nodes whose pre-AA source point falls outside the active imaging area are
+ * kept. They are neither clamped nor dropped (and weights are not
+ * renormalized). The renderer or light-field provider decides how to cover them.
  *
- * 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.
+ * Normalized weights approximate a spatial average. Square-micrometre measures
+ * approximate a geometric area integral. Neither includes throughput, QE,
+ * photon conversion, microlenses, diffusion, crosstalk or integration over time.
  */
 export function calculateSensorSpatialSamplingQuadrature(input) {
+    requireInputKeys(input, "calculateSensorSpatialSamplingQuadrature", ["imagingArea", "nativeRaster", "colorSamplingProfile", "colorSamplingBindingProfile", "samplingApertureProfile", "opticalStackProfile", "site", "spatialSampleCountX", "spatialSampleCountY"]);
     requirePositiveInteger("spatialSampleCountX", input.spatialSampleCountX);
     requirePositiveInteger("spatialSampleCountY", input.spatialSampleCountY);
     const samplingAperture = resolveSensorSamplingAperture({

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

@@ -1 +1 @@
-{"version":3,"file":"spatial-sampling-quadrature.js","sourceRoot":"","sources":["../../src/sensor/spatial-sampling-quadrature.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"spatial-sampling-quadrature.js","sourceRoot":"","sources":["../../src/sensor/spatial-sampling-quadrature.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Spatial sampling quadrature: the sample points (nodes) and weights used to average light over one\n * sensor site.\n *\n * It combines the site's geometric light-sensitive aperture (sampling-aperture) with the anti-aliasing\n * (AA) point-splitting kernel (optical-stack). The aperture is integrated with a grid of evenly spaced\n * midpoints. If an AA component moves light by +delta on the sensor, a destination point samples the\n * light field before AA at destination − delta, so the shift is never applied twice. Normalized weights\n * give a spatial average; square-micrometre measures give a geometric area integral. Neither includes\n * throughput, QE (quantum efficiency), photon conversion, microlenses, diffusion, crosstalk or\n * integration over time.\n * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support\n * limits.\n */\n\nimport {\n  approximationResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveInteger\n} from \"../core/validation.js\";\nimport type {\n  NativeEffectiveRasterColorSamplingBindingProfile\n} from \"./capture-color-sampling-binding.js\";\nimport type {\n  NativeColorSamplingSiteIndex,\n  SensorColorSamplingProfile\n} from \"./color-sampling.js\";\nimport {\n  resolveAntiAliasingSpatialKernel,\n  type SensorOpticalStackProfile\n} from \"./optical-stack.js\";\nimport {\n  resolveSensorSamplingAperture,\n  type SensorSamplingApertureProfile\n} from \"./sampling-aperture.js\";\nimport type {\n  NativeImageRaster,\n  SensorImagingArea\n} from \"./sensor-geometry.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\nconst MAX_SPATIAL_QUADRATURE_NODES = 100_000;\n\nexport interface CalculateSensorSpatialSamplingQuadratureInput {\n  imagingArea: SensorImagingArea;\n  nativeRaster: NativeImageRaster;\n  colorSamplingProfile: SensorColorSamplingProfile;\n  colorSamplingBindingProfile: NativeEffectiveRasterColorSamplingBindingProfile;\n  samplingApertureProfile: SensorSamplingApertureProfile;\n  opticalStackProfile: SensorOpticalStackProfile;\n  site: NativeColorSamplingSiteIndex;\n  /** Number of midpoint cells across the geometric aperture width. */\n  spatialSampleCountX: number;\n  /** Number of midpoint cells across the geometric aperture height. */\n  spatialSampleCountY: number;\n}\n\nexport interface SensorSpatialSamplingQuadratureNode {\n  antiAliasingComponentIndex: number;\n  apertureSampleXIndex: number;\n  apertureSampleYIndex: number;\n  /**\n   * Destination point inside the geometric sensitive aperture, after the\n   * declared AA point splitting.\n   *\n   * Native sensor physical coordinates, in millimetres from the optical axis.\n   */\n  destinationAperturePointMm: {\n    x: number;\n    y: number;\n  };\n  /**\n   * How far the declared AA component moves light on the sensor plane.\n   *\n   * +X right, +Y down; micrometres.\n   */\n  antiAliasingOffsetMicrometers: {\n    x: number;\n    y: number;\n  };\n  /**\n   * The point in the light field before AA that lands on\n   * destinationAperturePointMm through this split component:\n   *\n   * source = destination - AA offset\n   */\n  preAntiAliasingSourcePointMm: {\n    x: number;\n    y: number;\n  };\n  /**\n   * Whether the pre-AA source point is inside the active physical imaging\n   * area. False is not an error; downstream code decides how to handle valid\n   * light from outside the active sampling area.\n   */\n  preAntiAliasingSourceInsideImagingArea: boolean;\n  /** Dimensionless midpoint weight for the aperture-area average. */\n  normalizedApertureWeight: number;\n  /** Dimensionless normalized weight from the AA split component. */\n  normalizedAntiAliasingWeight: number;\n  /**\n   * Product of the two weights (dimensionless), used to average a light field\n   * over the site with this quadrature.\n   */\n  combinedNormalizedSpatialWeight: number;\n  /**\n   * Geometric area this aperture midpoint stands for, before the AA component\n   * weight is applied. Units: square micrometres.\n   */\n  apertureAreaMeasureSquareMicrometers: number;\n  /**\n   * Geometric area multiplied by the (dimensionless) AA component weight.\n   * Units are still square micrometres.\n   *\n   * This is not an effective light-collection area.\n   */\n  combinedAreaMeasureSquareMicrometers: number;\n}\n\nexport interface SensorSpatialSamplingQuadrature {\n  coordinateSystem: \"native-sensor-physical\";\n  colorSamplingProfileId?: string;\n  samplingApertureProfileId?: string;\n  opticalStackProfileId?: string;\n  site: NativeColorSamplingSiteIndex;\n  channelId: string;\n  quadratureScheme:\n    \"tensor-product-uniform-midpoint\";\n  outputMeaning:\n    \"pre-aa-optical-field-spatial-quadrature-nodes\";\n  spatialSampleCountX: number;\n  spatialSampleCountY: number;\n  antiAliasingComponentCount: number;\n  totalNodeCount: number;\n  geometricApertureAreaSquareMicrometers: number;\n  nominalSiteCellAreaSquareMicrometers?: number;\n  geometricSensitiveAreaFractionOfLatticeCell?: number;\n  normalizedSpatialWeightSum: number;\n  combinedAreaMeasureSumSquareMicrometers: number;\n  preAntiAliasingSourceOutsideImagingAreaNodeCount: number;\n  sourcePointRule:\n    \"pre-aa-source-equals-destination-minus-aa-offset\";\n  destinationCfaChannelAppliesToAllNodes: true;\n  cfaReassignmentBySourceCoordinate: false;\n  sourceCoveragePolicy: \"not-applied\";\n  nodes: readonly SensorSpatialSamplingQuadratureNode[];\n  /**\n   * Fixed statements of what this result does not include.\n   */\n  opticalFieldValuesIncluded: false;\n  radianceIncluded: false;\n  photonsIncluded: false;\n  electronsIncluded: false;\n  spectralResponseIncluded: false;\n  quantumEfficiencyIncluded: false;\n  opticalThroughputIncluded: false;\n  microlensResponseIncluded: false;\n  chargeDiffusionIncluded: false;\n  electricalCrosstalkIncluded: false;\n  temporalIntegrationIncluded: false;\n  rawSampleValueIncluded: false;\n  reconstructedPixelValueIncluded: false;\n  geometricAreaMeasureIsRadiometricCollectionArea: false;\n  componentEvidence: {\n    samplingApertureProfile: readonly import(\"../core/evidence-provenance.js\").EvidenceProvenance[];\n    samplingApertureLattice: readonly import(\"../core/evidence-provenance.js\").EvidenceProvenance[];\n    geometricSensitiveAperture: readonly import(\"../core/evidence-provenance.js\").EvidenceProvenance[];\n    opticalStackProfile: readonly import(\"../core/evidence-provenance.js\").EvidenceProvenance[];\n    antiAliasingResponse: readonly import(\"../core/evidence-provenance.js\").EvidenceProvenance[];\n  };\n}\n\nfunction midpointCoordinate(\n  index: number,\n  count: number\n): number {\n  return (index + 0.5) / count;\n}\n\nfunction insideImagingArea(\n  pointMm: { x: number; y: number },\n  imagingArea: SensorImagingArea\n): boolean {\n  const halfWidth = imagingArea.widthMm / 2;\n  const halfHeight = imagingArea.heightMm / 2;\n\n  return (\n    pointMm.x >= -halfWidth &&\n    pointMm.x <= halfWidth &&\n    pointMm.y >= -halfHeight &&\n    pointMm.y <= halfHeight\n  );\n}\n\n/**\n * Builds the deterministic spatial sample points (quadrature nodes) for one CFA\n * (colour filter array) site.\n *\n * It combines:\n *\n * 1. the site's geometric light-sensitive aperture (from sampling-aperture); and\n * 2. the anti-aliasing (AA) point-splitting kernel (from optical-stack).\n *\n * The aperture is integrated with a grid of evenly spaced midpoints (a\n * tensor-product midpoint rule). If an AA component moves light by +delta on\n * the sensor, a destination point samples the light field before AA at\n * destination − delta. Working backwards like this means the shift is never\n * applied twice.\n *\n * The destination site's CFA channel applies to every node. The pre-AA source\n * point is a position in the light field, not another CFA site, so a shifted\n * source point never changes the destination channel.\n *\n * Nodes whose pre-AA source point falls outside the active imaging area are\n * kept. They are neither clamped nor dropped (and weights are not\n * renormalized). The renderer or light-field provider decides how to cover them.\n *\n * Normalized weights approximate a spatial average. Square-micrometre measures\n * approximate a geometric area integral. Neither includes throughput, QE,\n * photon conversion, microlenses, diffusion, crosstalk or integration over time.\n */\nexport function calculateSensorSpatialSamplingQuadrature(\n  input: CalculateSensorSpatialSamplingQuadratureInput\n): CalculationResult<SensorSpatialSamplingQuadrature> {\n  requireInputKeys(input, \"calculateSensorSpatialSamplingQuadrature\", [\"imagingArea\", \"nativeRaster\", \"colorSamplingProfile\", \"colorSamplingBindingProfile\", \"samplingApertureProfile\", \"opticalStackProfile\", \"site\", \"spatialSampleCountX\", \"spatialSampleCountY\"]);\n  requirePositiveInteger(\n    \"spatialSampleCountX\",\n    input.spatialSampleCountX\n  );\n  requirePositiveInteger(\n    \"spatialSampleCountY\",\n    input.spatialSampleCountY\n  );\n\n  const samplingAperture =\n    resolveSensorSamplingAperture({\n      imagingArea: input.imagingArea,\n      nativeRaster: input.nativeRaster,\n      colorSamplingProfile:\n        input.colorSamplingProfile,\n      colorSamplingBindingProfile:\n        input.colorSamplingBindingProfile,\n      samplingApertureProfile:\n        input.samplingApertureProfile,\n      site: input.site\n    });\n\n  const antiAliasing =\n    resolveAntiAliasingSpatialKernel(\n      input.opticalStackProfile\n    );\n\n  const apertureNodeCount =\n    input.spatialSampleCountX *\n    input.spatialSampleCountY;\n  if (!Number.isSafeInteger(apertureNodeCount)) {\n    throw new InvalidScientificInputError(\n      \"spatialSampleCountX × spatialSampleCountY must be a safe integer.\"\n    );\n  }\n\n  const totalNodeCount =\n    apertureNodeCount *\n    antiAliasing.components.length;\n  if (!Number.isSafeInteger(totalNodeCount)) {\n    throw new InvalidScientificInputError(\n      \"Spatial quadrature node count must be a safe integer.\"\n    );\n  }\n  if (\n    totalNodeCount >\n    MAX_SPATIAL_QUADRATURE_NODES\n  ) {\n    throw new InvalidScientificInputError(\n      \"Spatial quadrature node count exceeds the per-site safety limit of \" +\n        MAX_SPATIAL_QUADRATURE_NODES +\n        \". Increase fidelity by tiling or batching downstream work rather than allocating one oversized node set.\"\n    );\n  }\n\n  const aperture =\n    samplingAperture.geometricSensitiveAperture;\n  const normalizedApertureWeight =\n    1 / apertureNodeCount;\n  const apertureAreaMeasureSquareMicrometers =\n    aperture.areaSquareMicrometers /\n    apertureNodeCount;\n\n  const apertureCenterMm =\n    aperture.centerFromOpticalAxisMm;\n  const widthMm =\n    aperture.widthMicrometers / 1000;\n  const heightMm =\n    aperture.heightMicrometers / 1000;\n  const leftMm =\n    apertureCenterMm.x - widthMm / 2;\n  const topMm =\n    apertureCenterMm.y - heightMm / 2;\n\n  const nodes: SensorSpatialSamplingQuadratureNode[] = [];\n  let outsideCount = 0;\n\n  antiAliasing.components.forEach(\n    (aaComponent, antiAliasingComponentIndex) => {\n      const aaOffsetMm = {\n        x:\n          aaComponent.offsetMicrometers.x /\n          1000,\n        y:\n          aaComponent.offsetMicrometers.y /\n          1000\n      };\n\n      for (\n        let apertureSampleYIndex = 0;\n        apertureSampleYIndex <\n        input.spatialSampleCountY;\n        apertureSampleYIndex += 1\n      ) {\n        const yPhase = midpointCoordinate(\n          apertureSampleYIndex,\n          input.spatialSampleCountY\n        );\n        const destinationY =\n          topMm + yPhase * heightMm;\n\n        for (\n          let apertureSampleXIndex = 0;\n          apertureSampleXIndex <\n          input.spatialSampleCountX;\n          apertureSampleXIndex += 1\n        ) {\n          const xPhase = midpointCoordinate(\n            apertureSampleXIndex,\n            input.spatialSampleCountX\n          );\n          const destinationX =\n            leftMm + xPhase * widthMm;\n          const destinationAperturePointMm = {\n            x: destinationX,\n            y: destinationY\n          };\n          const preAntiAliasingSourcePointMm = {\n            x:\n              destinationX -\n              aaOffsetMm.x,\n            y:\n              destinationY -\n              aaOffsetMm.y\n          };\n          const sourceInside = insideImagingArea(\n            preAntiAliasingSourcePointMm,\n            input.imagingArea\n          );\n          if (!sourceInside) {\n            outsideCount += 1;\n          }\n\n          const combinedNormalizedSpatialWeight =\n            normalizedApertureWeight *\n            aaComponent.normalizedWeight;\n          const combinedAreaMeasureSquareMicrometers =\n            apertureAreaMeasureSquareMicrometers *\n            aaComponent.normalizedWeight;\n\n          nodes.push({\n            antiAliasingComponentIndex,\n            apertureSampleXIndex,\n            apertureSampleYIndex,\n            destinationAperturePointMm,\n            antiAliasingOffsetMicrometers: {\n              ...aaComponent.offsetMicrometers\n            },\n            preAntiAliasingSourcePointMm,\n            preAntiAliasingSourceInsideImagingArea:\n              sourceInside,\n            normalizedApertureWeight,\n            normalizedAntiAliasingWeight:\n              aaComponent.normalizedWeight,\n            combinedNormalizedSpatialWeight,\n            apertureAreaMeasureSquareMicrometers,\n            combinedAreaMeasureSquareMicrometers\n          });\n        }\n      }\n    }\n  );\n\n  const normalizedSpatialWeightSum =\n    nodes.reduce(\n      (sum, node) =>\n        sum +\n        node.combinedNormalizedSpatialWeight,\n      0\n    );\n  const combinedAreaMeasureSumSquareMicrometers =\n    nodes.reduce(\n      (sum, node) =>\n        sum +\n        node.combinedAreaMeasureSquareMicrometers,\n      0\n    );\n\n  return approximationResult(\n    {\n      coordinateSystem:\n        \"native-sensor-physical\",\n      colorSamplingProfileId:\n        samplingAperture\n          .colorSamplingProfileId,\n      samplingApertureProfileId:\n        samplingAperture.profileId,\n      opticalStackProfileId:\n        antiAliasing.profileId,\n      site: {\n        ...samplingAperture.site\n      },\n      channelId:\n        samplingAperture.channelId,\n      quadratureScheme:\n        \"tensor-product-uniform-midpoint\",\n      outputMeaning:\n        \"pre-aa-optical-field-spatial-quadrature-nodes\",\n      spatialSampleCountX:\n        input.spatialSampleCountX,\n      spatialSampleCountY:\n        input.spatialSampleCountY,\n      antiAliasingComponentCount:\n        antiAliasing.components.length,\n      totalNodeCount,\n      geometricApertureAreaSquareMicrometers:\n        aperture.areaSquareMicrometers,\n      nominalSiteCellAreaSquareMicrometers:\n        samplingAperture.lattice\n          .nominalCellAreaSquareMicrometers,\n      geometricSensitiveAreaFractionOfLatticeCell:\n        aperture\n          .geometricSensitiveAreaFractionOfLatticeCell,\n      normalizedSpatialWeightSum,\n      combinedAreaMeasureSumSquareMicrometers,\n      preAntiAliasingSourceOutsideImagingAreaNodeCount:\n        outsideCount,\n      sourcePointRule:\n        \"pre-aa-source-equals-destination-minus-aa-offset\",\n      destinationCfaChannelAppliesToAllNodes:\n        true,\n      cfaReassignmentBySourceCoordinate:\n        false,\n      sourceCoveragePolicy:\n        \"not-applied\",\n      nodes,\n      opticalFieldValuesIncluded: false,\n      radianceIncluded: false,\n      photonsIncluded: false,\n      electronsIncluded: false,\n      spectralResponseIncluded: false,\n      quantumEfficiencyIncluded: false,\n      opticalThroughputIncluded: false,\n      microlensResponseIncluded: false,\n      chargeDiffusionIncluded: false,\n      electricalCrosstalkIncluded: false,\n      temporalIntegrationIncluded: false,\n      rawSampleValueIncluded: false,\n      reconstructedPixelValueIncluded: false,\n      geometricAreaMeasureIsRadiometricCollectionArea:\n        false,\n      componentEvidence: {\n        samplingApertureProfile:\n          samplingAperture.provenance.profile,\n        samplingApertureLattice:\n          samplingAperture.provenance.lattice,\n        geometricSensitiveAperture:\n          samplingAperture.provenance.aperture,\n        opticalStackProfile:\n          antiAliasing.provenance.profile,\n        antiAliasingResponse:\n          antiAliasing.provenance\n            .antiAliasingResponse\n      }\n    },\n    \"sensor-spatial-sampling-quadrature\",\n    \"1.0.0\",\n    [\n      \"Spatial aperture integration uses a deterministic tensor-product uniform midpoint rule.\",\n      \"The destination sensor site's semantic CFA/color channel applies to every quadrature node; pre-AA source coordinates never reassign the destination channel.\",\n      \"AA point-splitting is inverse-sampled: a +delta output displacement reads the pre-AA optical field at destination - delta.\",\n      \"AA component weights and aperture midpoint weights are dimensionless normalized spatial-average weights.\",\n      \"Square-micrometre measures are geometric integration measures only and are not effective radiometric collection area, throughput, QE, or photon count.\",\n      \"Pre-AA source points may leave the active physical imaging area and are not clamped, dropped, or renormalized.\",\n      \"The AA kernel remains the optical-stack foundation's field/wavelength/polarization-invariant approximation where applicable.\",\n      \"Microlens spatial response, charge diffusion, electrical/optical crosstalk, spectral response, radiometry, temporal integration, RAW sample generation, and reconstruction remain separate future work.\",\n      \"No geometry-only spatial quadrature error estimate is reported because downstream optical-field spatial frequency/content determines integration error.\"\n    ]\n  );\n}\n"]}

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

@@ -1,16 +1,9 @@
 /**
- * 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.
+ * Spatio-spectral reduction: integrates spectral irradiance on the sensor over one site's area and
+ * over wavelength, giving the incident light power on the site's geometric aperture.
+ *
+ * It stops before the sensor response: QE (quantum efficiency), A/W responsivity and colour-filter
+ * transmission are applied in later steps.
  * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
@@ -26,8 +19,8 @@ export interface SensorSpatioSpectralNodeIdentity {
 export interface SensorSpatioSpectralIrradianceSample {
     node: SensorSpatioSpectralNodeIdentity;
     /**
-     * Spectral irradiance evaluated at the spatial quadrature node's
-     * preAntiAliasingSourcePointMm and this spectral node's wavelength.
+     * Spectral irradiance at the spatial node's preAntiAliasingSourcePointMm
+     * and this spectral node's wavelength.
      *
      * Units: W/m^2/nm.
      */
@@ -37,10 +30,10 @@ 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.
+     * Exactly one E_lambda(x,y) value, with its node identity, for every
+     * combination of spatial node and spectral node.
      *
-     * Ordering is not significant; node identity is.
+     * Order does not matter; the node identity does.
      */
     sampleValues: readonly SensorSpatioSpectralIrradianceSample[];
 }
@@ -55,11 +48,10 @@ export interface SensorSpatioSpectralWavelengthReduction {
      */
     normalizedSpatialAverageSpectralIrradianceWattsPerSquareMeterPerNanometer: number;
     /**
-     * Spectral radiant flux density incident over the geometric sensitive
-     * aperture after the declared normalized AA redistribution.
-     * Units: W/nm.
+     * Spectral radiant flux reaching the geometric sensitive aperture, after the
+     * declared normalized AA spreading. Units: W/nm.
      *
-     * This uses geometric area, not an established radiometric collection area.
+     * This uses geometric area, not an established light-collection area.
      */
     geometricApertureIncidentSpectralFluxWattsPerNanometer: number;
     /**
@@ -115,11 +107,11 @@ export interface SensorSpatioSpectralIrradianceReduction {
      */
     wavelengthIntegratedSpatialAverageIrradianceWattsPerSquareMeter: number;
     /**
-     * Integral over the requested wavelength interval and geometric aperture
-     * area. Units: W.
+     * Integral over the requested wavelength interval and the 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.
+     * This is the incident radiant flux before the sensor response, over the
+     * declared wavelength interval. It is not collected power or generated charge.
      */
     wavelengthIntegratedGeometricApertureIncidentFluxWatts: number;
     spatialIntegrationApplied: true;
@@ -148,7 +140,7 @@ export interface SensorSpatioSpectralIrradianceReduction {
         spectral: SensorSpectralQuadrature["componentEvidence"];
     };
 }
-/** Internal shared node binding; domain callers retain value validation and equations. */
+/** Internal: matches samples to their spatial × spectral nodes. Each caller still validates values and applies its own equations. */
 export declare function bindSensorSpatioSpectralSamples<T extends {
     node: SensorSpatioSpectralNodeIdentity;
 }, V>(input: {
@@ -163,25 +155,23 @@ export declare function bindSensorSpatioSpectralSamples<T extends {
     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
+ * Integrates supplied spectral irradiance on the sensor plane, E_lambda(x,y),
+ * over every combination 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.
+ * Units: the density is in W/m^2/nm and wavelengthMeasureNanometers is dλ in
+ * nm, so their product is in W/m^2. Do not convert dλ to metres unless the
+ * density's per-nanometre unit is converted to match.
  *
- * 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.
+ * Area integration uses the spatial quadrature's geometric area measures,
+ * converted from square micrometres to square metres. The result is the
+ * incident radiant flux on the geometric aperture only; geometric area is not
+ * treated as an effective light-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.
+ * It deliberately stops before the sensor response. The spectral plan comes
+ * from a specific response channel, so its wavelength range and breakpoints
+ * fit that channel, but QE, A/W responsivity and colour-filter transmission are
+ * not applied here. Matching the response's scope and source plane is a
+ * separate later step.
  */
 export declare function reduceSensorSpatioSpectralIrradiance(input: ReduceSensorSpatioSpectralIrradianceInput): CalculationResult<SensorSpatioSpectralIrradianceReduction>;
-//# sourceMappingURL=spatio-spectral-reduction.d.ts.map

package/dist/sensor/spatio-spectral-reduction.js

@@ -1,17 +1,10 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * 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.
+ * Spatio-spectral reduction: integrates spectral irradiance on the sensor over one site's area and
+ * over wavelength, giving the incident light power on the site's geometric aperture.
+ *
+ * It stops before the sensor response: QE (quantum efficiency), A/W responsivity and colour-filter
+ * transmission are applied in later steps.
  * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
@@ -19,6 +12,8 @@ import { approximationResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError } from "../core/validation.js";
 import { sensorSpatialQuadratureNodeIdentityKey, validateSensorSpatialSamplingQuadrature } from "./spatial-sample-reduction.js";
 import { validateSensorSpectralQuadrature } from "./spectral-quadrature.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 const SQUARE_MICROMETERS_TO_SQUARE_METERS = 1e-12;
 const MAX_SPATIO_SPECTRAL_SAMPLE_VALUES = 100_000;
 function requireSafeNonNegativeInteger(value, path) {
@@ -45,7 +40,7 @@ function sampleKey(spatialNode, spectralSampleIndex) {
 }
 function parseSamples(sampleValues, spatialNodesByKey, spectralNodesByIndex, combinedSampleCount, valueForSample) {
     if (!Array.isArray(sampleValues)) {
-        throw new InvalidScientificInputError("sampleValues must be an array.");
+        throw new InvalidConfigurationError("sampleValues must be an array.");
     }
     if (sampleValues.length !==
         combinedSampleCount) {
@@ -107,7 +102,7 @@ function parseSamples(sampleValues, spatialNodesByKey, spectralNodesByIndex, com
     }
     return valuesByKey;
 }
-/** Internal shared node binding; domain callers retain value validation and equations. */
+/** Internal: matches samples to their spatial × spectral nodes. Each caller still validates values and applies its own equations. */
 export function bindSensorSpatioSpectralSamples(input, valueForSample) {
     const spatialNodesByKey = validateSensorSpatialSamplingQuadrature(input.spatialQuadrature);
     const spectralNodesByIndex = validateSensorSpectralQuadrature(input.spectralQuadrature);
@@ -152,27 +147,27 @@ export function bindSensorSpatioSpectralSamples(input, valueForSample) {
     return { spatialNodesByKey, spectralNodesByIndex, colorSamplingProfileId, combinedSampleCount, valuesByKey };
 }
 /**
- * Reduces explicitly supplied sensor-plane spectral irradiance E_lambda(x,y)
- * over the Cartesian product of an existing spatial quadrature and spectral
+ * Integrates supplied spectral irradiance on the sensor plane, E_lambda(x,y),
+ * over every combination 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.
+ * Units: the density is in W/m^2/nm and wavelengthMeasureNanometers is dλ in
+ * nm, so their product is in W/m^2. Do not convert dλ to metres unless the
+ * density's per-nanometre unit is converted to match.
  *
- * 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.
+ * Area integration uses the spatial quadrature's geometric area measures,
+ * converted from square micrometres to square metres. The result is the
+ * incident radiant flux on the geometric aperture only; geometric area is not
+ * treated as an effective light-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.
+ * It deliberately stops before the sensor response. The spectral plan comes
+ * from a specific response channel, so its wavelength range and breakpoints
+ * fit that channel, but QE, A/W responsivity and colour-filter transmission are
+ * not applied here. Matching the response's scope and source plane is a
+ * separate later step.
  */
 export function reduceSensorSpatioSpectralIrradiance(input) {
+    requireInputKeys(input, "reduceSensorSpatioSpectralIrradiance", ["spatialQuadrature", "spectralQuadrature", "sampleValues"]);
     const { spatialNodesByKey, spectralNodesByIndex, colorSamplingProfileId, combinedSampleCount, valuesByKey } = bindSensorSpatioSpectralSamples(input, (sample, sampleIndex) => requireNonNegativeFinite(sample.spectralIrradianceWattsPerSquareMeterPerNanometer, "sampleValues[" + sampleIndex + "].spectralIrradianceWattsPerSquareMeterPerNanometer"));
     const perWavelength = [];
     let wavelengthIntegratedSpatialAverage = 0;