@photivra/engine 1.5.0 → 2.0.0

package/dist/sensor/sensor-geometry.js.map

@@ -1 +1 @@
-{"version":3,"file":"sensor-geometry.js","sourceRoot":"","sources":["../../src/sensor/sensor-geometry.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,uBAAuB,GAAG,EAAE,CAAC;AACnC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AACpC,MAAM,0BAA0B,GAAG,IAAI,CAAC,KAAK,CAC3C,uBAAuB,EACvB,wBAAwB,CACzB,CAAC;AAkFF;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CACzC,WAA8B;IAE9B,qBAAqB,CAAC,qBAAqB,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAClE,qBAAqB,CAAC,sBAAsB,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAEpE,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;IAEzE,OAAO,gBAAgB,CACrB;QACE,UAAU;QACV,WAAW,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,QAAQ;QACvD,cAAc,EAAE,0BAA0B,GAAG,UAAU;KACxD,EACD,qBAAqB,EACrB,OAAO,EACP;QACE,wEAAwE;QACxE,6EAA6E;KAC9E,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,8BAA8B,CAC5C,KAA0C;IAE1C,qBAAqB,CAAC,qBAAqB,EAAE,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACxE,qBAAqB,CAAC,sBAAsB,EAAE,KAAK,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC1E,sBAAsB,CACpB,yBAAyB,EACzB,KAAK,CAAC,YAAY,CAAC,UAAU,CAC9B,CAAC;IACF,sBAAsB,CACpB,0BAA0B,EAC1B,KAAK,CAAC,YAAY,CAAC,WAAW,CAC/B,CAAC;IAEF,MAAM,iBAAiB,GACrB,KAAK,CAAC,YAAY,CAAC,UAAU,GAAG,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC;IACjE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,2BAA2B,CACnC,wEAAwE,CACzE,CAAC;IACJ,CAAC;IAED,MAAM,kBAAkB,GAAG,2BAA2B,CACpD,KAAK,CAAC,WAAW,CAClB,CAAC,KAAK,CAAC;IACR,MAAM,iBAAiB,GACrB,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,GAAG,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IACrE,MAAM,iBAAiB,GACrB,CAAC,KAAK,CAAC,WAAW,CAAC,QAAQ,GAAG,KAAK,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;IAEvE,OAAO,gBAAgB,CACrB;QACE,WAAW,EAAE,kBAAkB;QAC/B,YAAY,EAAE;YACZ,iBAAiB;YACjB,UAAU,EAAE,iBAAiB,GAAG,SAAS;YACzC,WAAW,EACT,KAAK,CAAC,YAAY,CAAC,UAAU,GAAG,KAAK,CAAC,YAAY,CAAC,WAAW;SACjE;QACD,QAAQ,EAAE;YACR,iBAAiB;YACjB,iBAAiB;YACjB,gBAAgB,EAAE,iBAAiB,GAAG,iBAAiB;SACxD;KACF,EACD,mCAAmC,EACnC,OAAO,EACP;QACE,wEAAwE;QACxE,0FAA0F;QAC1F,+GAA+G;KAChH,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"sensor-geometry.js","sourceRoot":"","sources":["../../src/sensor/sensor-geometry.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Sensor geometry: physical size of the imaging area (diagonal, aspect ratio, 35 mm crop factor) and\n * the native pixel grid (megapixels, pixel pitch).\n *\n * Sensor size and resolution are kept independent. Crop factor is the ratio of diagonals to a\n * 36 × 24 mm frame, and does not include any digital or output crop. Pixel pitch here is only the\n * spacing between samples; it is not the photosite's fill factor or light-collecting area.\n * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support\n * limits.\n */\n\nimport {\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite,\n  requirePositiveInteger\n} from \"../core/validation.js\";\nimport { portableHypot } from \"../core/portable-math.js\";\nimport { requireInputObject, requireInputKeys } from \"../core/record-validation.js\";\n\nconst REFERENCE_35MM_WIDTH_MM = 36;\nconst REFERENCE_35MM_HEIGHT_MM = 24;\n/** 36² + 24² mm²: the squared diagonal of the 35 mm reference frame (exact as a double). */\nconst REFERENCE_35MM_DIAGONAL_SQUARED_MM2 =\n  REFERENCE_35MM_WIDTH_MM * REFERENCE_35MM_WIDTH_MM +\n  REFERENCE_35MM_HEIGHT_MM * REFERENCE_35MM_HEIGHT_MM;\n\n/**\n * Diagonal 35 mm crop factor, √(1872 / (w² + h²)). It uses only correctly rounded operations, so the\n * stored value is bit-identical in every JavaScript engine (see core/portable-math.ts).\n */\nfunction diagonalCropFactor35Mm(widthMm: number, heightMm: number, diagonalMm: number): number {\n  const diagonalSquaredMm2 = widthMm * widthMm + heightMm * heightMm;\n  return Number.isFinite(diagonalSquaredMm2) && diagonalSquaredMm2 > 0\n    ? Math.sqrt(REFERENCE_35MM_DIAGONAL_SQUARED_MM2 / diagonalSquaredMm2)\n    : Math.sqrt(REFERENCE_35MM_DIAGONAL_SQUARED_MM2) / diagonalMm;\n}\n\n/**\n * The physical light-sensitive imaging area used for image formation.\n *\n * It is deliberately not the size of the sensor package or die.\n */\nexport interface SensorImagingArea {\n  /** Physical active imaging width in millimetres. */\n  widthMm: number;\n  /** Physical active imaging height in millimetres. */\n  heightMm: number;\n}\n\n/**\n * Width and height of an image grid in pixels.\n *\n * Pixels here are image samples. That does not mean each sample matches one\n * physical photodiode (photosite).\n */\nexport interface RasterDimensions {\n  /** Horizontal image-sample/pixel count. */\n  pixelWidth: number;\n  /** Vertical image-sample/pixel count. */\n  pixelHeight: number;\n}\n\n/**\n * The native pixel grid of an imaging area.\n *\n * This alias names the role. For other grids, such as active or output\n * images, use RasterDimensions.\n */\nexport type NativeImageRaster = RasterDimensions;\n\nexport interface ImagingAreaMetrics {\n  /** Physical imaging-area diagonal in millimetres. */\n  diagonalMm: number;\n  /** Physical width divided by physical height. */\n  aspectRatio: number;\n  /**\n   * Diagonal crop factor relative to a 36 × 24 mm reference frame.\n   *\n   * It describes the physical imaging area only, and does not include any\n   * later digital or output crop.\n   */\n  cropFactor35Mm: number;\n}\n\nexport interface CalculateSensorGeometryMetricsInput {\n  imagingArea: SensorImagingArea;\n  nativeRaster: NativeImageRaster;\n}\n\nexport interface SensorGeometryMetrics {\n  imagingArea: ImagingAreaMetrics;\n  nativeRaster: {\n    /** Exact product of native raster width and height. */\n    totalImageSamples: number;\n    /** Derived megapixels from the exact native raster. */\n    megapixels: number;\n    /** Native raster width divided by native raster height. */\n    aspectRatio: number;\n  };\n  sampling: {\n    /**\n     * Horizontal sample spacing (pitch) in micrometres.\n     *\n     * This is the spacing between image samples, not the photodiode's active area.\n     */\n    pitchXMicrometers: number;\n    /**\n     * Vertical sample spacing (pitch) in micrometres.\n     *\n     * This is the spacing between image samples, not the photodiode's active area.\n     */\n    pitchYMicrometers: number;\n    /** Horizontal sampling pitch divided by vertical sampling pitch. */\n    pitchAspectRatio: number;\n  };\n}\n\n/**\n * Calculates metrics of the physical imaging area, independent of pixel count.\n *\n * Crop factor is the ratio of diagonals to a 36 × 24 mm reference frame. It\n * does not include any digital or output crop.\n *\n * @param imagingArea Physical photosensitive imaging area.\n * @returns Physical diagonal, aspect ratio, and diagonal 35 mm crop factor.\n */\nexport function calculateImagingAreaMetrics(\n  imagingArea: SensorImagingArea\n): CalculationResult<ImagingAreaMetrics> {\n  requireInputKeys(imagingArea, \"calculateImagingAreaMetrics\", [\"widthMm\", \"heightMm\"]);\n  requirePositiveFinite(\"imagingArea.widthMm\", imagingArea.widthMm);\n  requirePositiveFinite(\"imagingArea.heightMm\", imagingArea.heightMm);\n\n  const diagonalMm = portableHypot(imagingArea.widthMm, imagingArea.heightMm);\n\n  return calculatedResult(\n    {\n      diagonalMm,\n      aspectRatio: imagingArea.widthMm / imagingArea.heightMm,\n      cropFactor35Mm: diagonalCropFactor35Mm(imagingArea.widthMm, imagingArea.heightMm, diagonalMm)\n    },\n    \"sensor-imaging-area\",\n    \"1.0.0\",\n    [\n      \"35 mm reference frame is 36 × 24 mm and crop factor is diagonal-based.\",\n      \"Digital/output cropping is excluded from physical imaging-area crop factor.\"\n    ]\n  );\n}\n\n/**\n * Calculates metrics of the physical imaging area, the native pixel grid and\n * the sample spacing, keeping sensor size and resolution independent.\n *\n * The grid is assumed to cover the whole imaging area. The derived pitch is\n * only the spacing between samples. Do not read it as the photosite's fill\n * factor or light-collecting area.\n *\n * @param input Physical imaging area and native effective image raster.\n * @returns Derived imaging-area, raster, and sampling metrics.\n */\nexport function calculateSensorGeometryMetrics(\n  input: CalculateSensorGeometryMetricsInput\n): CalculationResult<SensorGeometryMetrics> {\n  requireInputKeys(input, \"calculateSensorGeometryMetrics\", [\"imagingArea\", \"nativeRaster\"]);\n  requireInputObject(input.imagingArea, \"imagingArea\");\n  requirePositiveFinite(\"imagingArea.widthMm\", input.imagingArea.widthMm);\n  requirePositiveFinite(\"imagingArea.heightMm\", input.imagingArea.heightMm);\n  requireInputObject(input.nativeRaster, \"nativeRaster\");\n  requirePositiveInteger(\n    \"nativeRaster.pixelWidth\",\n    input.nativeRaster.pixelWidth\n  );\n  requirePositiveInteger(\n    \"nativeRaster.pixelHeight\",\n    input.nativeRaster.pixelHeight\n  );\n\n  const totalImageSamples =\n    input.nativeRaster.pixelWidth * input.nativeRaster.pixelHeight;\n  if (!Number.isSafeInteger(totalImageSamples)) {\n    throw new InvalidScientificInputError(\n      \"nativeRaster total image-sample count must be a positive safe integer.\"\n    );\n  }\n\n  const imagingAreaMetrics = calculateImagingAreaMetrics(\n    input.imagingArea\n  ).value;\n  const pitchXMicrometers =\n    (input.imagingArea.widthMm / input.nativeRaster.pixelWidth) * 1000;\n  const pitchYMicrometers =\n    (input.imagingArea.heightMm / input.nativeRaster.pixelHeight) * 1000;\n\n  return calculatedResult(\n    {\n      imagingArea: imagingAreaMetrics,\n      nativeRaster: {\n        totalImageSamples,\n        megapixels: totalImageSamples / 1_000_000,\n        aspectRatio:\n          input.nativeRaster.pixelWidth / input.nativeRaster.pixelHeight\n      },\n      sampling: {\n        pitchXMicrometers,\n        pitchYMicrometers,\n        pitchAspectRatio: pitchXMicrometers / pitchYMicrometers\n      }\n    },\n    \"sensor-imaging-area-native-raster\",\n    \"1.0.0\",\n    [\n      \"35 mm reference frame is 36 × 24 mm and crop factor is diagonal-based.\",\n      \"The native effective image raster is assumed to span the supplied physical imaging area.\",\n      \"Derived sampling pitch is geometric image-sample spacing, not physical photodiode active area or fill factor.\"\n    ]\n  );\n}\n"]}

package/dist/sensor/signal-noise.d.ts

@@ -1,25 +1,24 @@
 /**
- * Module boundary and integration notes.
- * Converts mean incident photon count to mean photoelectron count. This is an expectation value; the
- * stochastic shot-noise realization is not generated by this deterministic calculation.
- * Calculates expected SNR from Poisson shot noise and independent RMS read noise. Variances are
- * combined as signalElectrons + readNoiseElectrons^2. Dark current, fixed-pattern noise, quantization,
- * clipping, and downstream processing are intentionally outside this primitive.
+ * Basic signal and noise: mean photoelectrons from photons and quantum efficiency (QE), and the
+ * expected signal-to-noise ratio (SNR) from shot noise and read noise.
+ *
+ * These are expected (mean) values; no random noise is generated. Dark current, fixed-pattern noise,
+ * quantization, clipping and later processing are deliberately left out.
  * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 export interface CalculatePhotoelectronsInput {
-    /** Mean photons incident on the photosite/measurement region. */
+    /** Mean number of photons reaching the photosite (or measurement region). */
     incidentPhotons: number;
     /** Quantum efficiency from 0 to 1 inclusive. */
     quantumEfficiency: number;
 }
 /**
- * Converts mean incident photon count to mean photoelectron count.
+ * Converts the mean incident photon count to the mean photoelectron count.
  *
- * This is an expectation value; the stochastic shot-noise realization is not
- * generated by this deterministic calculation.
+ * This is an expected value. This deterministic calculation does not generate
+ * random shot noise.
  */
 export declare function calculatePhotoelectrons(input: CalculatePhotoelectronsInput): CalculationResult<number>;
 export interface CalculateSignalToNoiseInput {
@@ -32,16 +31,15 @@ export interface SignalToNoise {
     shotNoiseStdElectrons: number;
     combinedNoiseStdElectrons: number;
     snrLinear: number;
-    /** Null when the signal is zero because -Infinity dB is not JSON-safe. */
+    /** Null when the signal is zero, because -Infinity dB cannot be stored in JSON. */
     snrDb: number | null;
 }
 /**
- * Calculates expected SNR from Poisson shot noise and independent RMS read
+ * Calculates the expected SNR from Poisson shot noise and independent RMS read
  * noise.
  *
- * Variances are combined as signalElectrons + readNoiseElectrons^2.
- * Dark current, fixed-pattern noise, quantization, clipping, and downstream
- * processing are intentionally outside this primitive.
+ * Variances add: total variance = signalElectrons + readNoiseElectrons^2.
+ * Dark current, fixed-pattern noise, quantization, clipping and later
+ * processing are deliberately left out.
  */
 export declare function calculateSignalToNoise(input: CalculateSignalToNoiseInput): CalculationResult<SignalToNoise>;
-//# sourceMappingURL=signal-noise.d.ts.map

package/dist/sensor/signal-noise.js

@@ -1,28 +1,29 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Converts mean incident photon count to mean photoelectron count. This is an expectation value; the
- * stochastic shot-noise realization is not generated by this deterministic calculation.
- * Calculates expected SNR from Poisson shot noise and independent RMS read noise. Variances are
- * combined as signalElectrons + readNoiseElectrons^2. Dark current, fixed-pattern noise, quantization,
- * clipping, and downstream processing are intentionally outside this primitive.
+ * Basic signal and noise: mean photoelectrons from photons and quantum efficiency (QE), and the
+ * expected signal-to-noise ratio (SNR) from shot noise and read noise.
+ *
+ * These are expected (mean) values; no random noise is generated. Dark current, fixed-pattern noise,
+ * quantization, clipping and later processing are deliberately left out.
  * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
 import { calculatedResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError } from "../core/validation.js";
+import { requireInputKeys } from "../core/record-validation.js";
 function requireNonNegativeFinite(name, value) {
     if (!Number.isFinite(value) || value < 0) {
         throw new InvalidScientificInputError(`${name} must be a finite number greater than or equal to zero.`);
     }
 }
 /**
- * Converts mean incident photon count to mean photoelectron count.
+ * Converts the mean incident photon count to the mean photoelectron count.
  *
- * This is an expectation value; the stochastic shot-noise realization is not
- * generated by this deterministic calculation.
+ * This is an expected value. This deterministic calculation does not generate
+ * random shot noise.
  */
 export function calculatePhotoelectrons(input) {
+    requireInputKeys(input, "calculatePhotoelectrons", ["incidentPhotons", "quantumEfficiency"]);
     requireNonNegativeFinite("incidentPhotons", input.incidentPhotons);
     if (!Number.isFinite(input.quantumEfficiency) ||
         input.quantumEfficiency < 0 ||
@@ -32,14 +33,15 @@ export function calculatePhotoelectrons(input) {
     return calculatedResult(input.incidentPhotons * input.quantumEfficiency, "mean-photoelectron-conversion", "1.0.0", ["Quantum efficiency is supplied by the caller"]);
 }
 /**
- * Calculates expected SNR from Poisson shot noise and independent RMS read
+ * Calculates the expected SNR from Poisson shot noise and independent RMS read
  * noise.
  *
- * Variances are combined as signalElectrons + readNoiseElectrons^2.
- * Dark current, fixed-pattern noise, quantization, clipping, and downstream
- * processing are intentionally outside this primitive.
+ * Variances add: total variance = signalElectrons + readNoiseElectrons^2.
+ * Dark current, fixed-pattern noise, quantization, clipping and later
+ * processing are deliberately left out.
  */
 export function calculateSignalToNoise(input) {
+    requireInputKeys(input, "calculateSignalToNoise", ["signalElectrons", "readNoiseElectrons"]);
     requireNonNegativeFinite("signalElectrons", input.signalElectrons);
     requireNonNegativeFinite("readNoiseElectrons", input.readNoiseElectrons);
     const shotNoiseStdElectrons = Math.sqrt(input.signalElectrons);

package/dist/sensor/signal-noise.js.map

@@ -1 +1 @@
-{"version":3,"file":"signal-noise.js","sourceRoot":"","sources":["../../src/sensor/signal-noise.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;GASG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEpE,SAAS,wBAAwB,CAAC,IAAY,EAAE,KAAa;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,2BAA2B,CACnC,GAAG,IAAI,yDAAyD,CACjE,CAAC;IACJ,CAAC;AACH,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAmC;IAEnC,wBAAwB,CAAC,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAEnE,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,iBAAiB,CAAC;QACzC,KAAK,CAAC,iBAAiB,GAAG,CAAC;QAC3B,KAAK,CAAC,iBAAiB,GAAG,CAAC,EAC3B,CAAC;QACD,MAAM,IAAI,2BAA2B,CACnC,6DAA6D,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,gBAAgB,CACrB,KAAK,CAAC,eAAe,GAAG,KAAK,CAAC,iBAAiB,EAC/C,+BAA+B,EAC/B,OAAO,EACP,CAAC,8CAA8C,CAAC,CACjD,CAAC;AACJ,CAAC;AAiBD;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAkC;IAElC,wBAAwB,CAAC,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACnE,wBAAwB,CAAC,oBAAoB,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAEzE,MAAM,qBAAqB,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAC/D,MAAM,yBAAyB,GAAG,IAAI,CAAC,IAAI,CACzC,KAAK,CAAC,eAAe;QACnB,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,kBAAkB,CACtD,CAAC;IACF,MAAM,SAAS,GACb,yBAAyB,KAAK,CAAC;QAC7B,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,KAAK,CAAC,eAAe,GAAG,yBAAyB,CAAC;IACxD,MAAM,KAAK,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAElE,OAAO,gBAAgB,CACrB;QACE,qBAAqB;QACrB,yBAAyB;QACzB,SAAS;QACT,KAAK;KACN,EACD,kCAAkC,EAClC,OAAO,EACP;QACE,8BAA8B;QAC9B,qDAAqD;QACrD,uDAAuD;KACxD,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"signal-noise.js","sourceRoot":"","sources":["../../src/sensor/signal-noise.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;GAQG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE,SAAS,wBAAwB,CAAC,IAAY,EAAE,KAAa;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,2BAA2B,CACnC,GAAG,IAAI,yDAAyD,CACjE,CAAC;IACJ,CAAC;AACH,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAmC;IAEnC,gBAAgB,CAAC,KAAK,EAAE,yBAAyB,EAAE,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAC7F,wBAAwB,CAAC,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAEnE,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,iBAAiB,CAAC;QACzC,KAAK,CAAC,iBAAiB,GAAG,CAAC;QAC3B,KAAK,CAAC,iBAAiB,GAAG,CAAC,EAC3B,CAAC;QACD,MAAM,IAAI,2BAA2B,CACnC,6DAA6D,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,gBAAgB,CACrB,KAAK,CAAC,eAAe,GAAG,KAAK,CAAC,iBAAiB,EAC/C,+BAA+B,EAC/B,OAAO,EACP,CAAC,8CAA8C,CAAC,CACjD,CAAC;AACJ,CAAC;AAiBD;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAkC;IAElC,gBAAgB,CAAC,KAAK,EAAE,wBAAwB,EAAE,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAC7F,wBAAwB,CAAC,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IACnE,wBAAwB,CAAC,oBAAoB,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAEzE,MAAM,qBAAqB,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAC/D,MAAM,yBAAyB,GAAG,IAAI,CAAC,IAAI,CACzC,KAAK,CAAC,eAAe;QACnB,KAAK,CAAC,kBAAkB,GAAG,KAAK,CAAC,kBAAkB,CACtD,CAAC;IACF,MAAM,SAAS,GACb,yBAAyB,KAAK,CAAC;QAC7B,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,KAAK,CAAC,eAAe,GAAG,yBAAyB,CAAC;IACxD,MAAM,KAAK,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAElE,OAAO,gBAAgB,CACrB;QACE,qBAAqB;QACrB,yBAAyB;QACzB,SAAS;QACT,KAAK;KACN,EACD,kCAAkC,EAClC,OAAO,EACP;QACE,8BAA8B;QAC9B,qDAAqD;QACrD,uDAAuD;KACxD,CACF,CAAC;AACJ,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Basic signal and noise: mean photoelectrons from photons and quantum efficiency (QE), and the\n * expected signal-to-noise ratio (SNR) from shot noise and read noise.\n *\n * These are expected (mean) values; no random noise is generated. Dark current, fixed-pattern noise,\n * quantization, clipping and later processing are deliberately left out.\n * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support\n * limits.\n */\n\nimport {\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\nfunction requireNonNegativeFinite(name: string, value: number): void {\n  if (!Number.isFinite(value) || value < 0) {\n    throw new InvalidScientificInputError(\n      `${name} must be a finite number greater than or equal to zero.`\n    );\n  }\n}\n\nexport interface CalculatePhotoelectronsInput {\n  /** Mean number of photons reaching the photosite (or measurement region). */\n  incidentPhotons: number;\n  /** Quantum efficiency from 0 to 1 inclusive. */\n  quantumEfficiency: number;\n}\n\n/**\n * Converts the mean incident photon count to the mean photoelectron count.\n *\n * This is an expected value. This deterministic calculation does not generate\n * random shot noise.\n */\nexport function calculatePhotoelectrons(\n  input: CalculatePhotoelectronsInput\n): CalculationResult<number> {\n  requireInputKeys(input, \"calculatePhotoelectrons\", [\"incidentPhotons\", \"quantumEfficiency\"]);\n  requireNonNegativeFinite(\"incidentPhotons\", input.incidentPhotons);\n\n  if (\n    !Number.isFinite(input.quantumEfficiency) ||\n    input.quantumEfficiency < 0 ||\n    input.quantumEfficiency > 1\n  ) {\n    throw new InvalidScientificInputError(\n      \"quantumEfficiency must be a finite number from 0 through 1.\"\n    );\n  }\n\n  return calculatedResult(\n    input.incidentPhotons * input.quantumEfficiency,\n    \"mean-photoelectron-conversion\",\n    \"1.0.0\",\n    [\"Quantum efficiency is supplied by the caller\"]\n  );\n}\n\nexport interface CalculateSignalToNoiseInput {\n  /** Mean signal in electrons. */\n  signalElectrons: number;\n  /** RMS read noise in electrons. */\n  readNoiseElectrons: number;\n}\n\nexport interface SignalToNoise {\n  shotNoiseStdElectrons: number;\n  combinedNoiseStdElectrons: number;\n  snrLinear: number;\n  /** Null when the signal is zero, because -Infinity dB cannot be stored in JSON. */\n  snrDb: number | null;\n}\n\n/**\n * Calculates the expected SNR from Poisson shot noise and independent RMS read\n * noise.\n *\n * Variances add: total variance = signalElectrons + readNoiseElectrons^2.\n * Dark current, fixed-pattern noise, quantization, clipping and later\n * processing are deliberately left out.\n */\nexport function calculateSignalToNoise(\n  input: CalculateSignalToNoiseInput\n): CalculationResult<SignalToNoise> {\n  requireInputKeys(input, \"calculateSignalToNoise\", [\"signalElectrons\", \"readNoiseElectrons\"]);\n  requireNonNegativeFinite(\"signalElectrons\", input.signalElectrons);\n  requireNonNegativeFinite(\"readNoiseElectrons\", input.readNoiseElectrons);\n\n  const shotNoiseStdElectrons = Math.sqrt(input.signalElectrons);\n  const combinedNoiseStdElectrons = Math.sqrt(\n    input.signalElectrons +\n      input.readNoiseElectrons * input.readNoiseElectrons\n  );\n  const snrLinear =\n    combinedNoiseStdElectrons === 0\n      ? 0\n      : input.signalElectrons / combinedNoiseStdElectrons;\n  const snrDb = snrLinear === 0 ? null : 20 * Math.log10(snrLinear);\n\n  return calculatedResult(\n    {\n      shotNoiseStdElectrons,\n      combinedNoiseStdElectrons,\n      snrLinear,\n      snrDb\n    },\n    \"poisson-shot-plus-read-noise-snr\",\n    \"1.0.0\",\n    [\n      \"Photon shot noise is Poisson\",\n      \"Read noise is supplied as independent RMS electrons\",\n      \"Dark current and fixed-pattern noise are not included\"\n    ]\n  );\n}\n"]}

package/dist/sensor/spatial-sample-reduction.d.ts

@@ -1,15 +1,11 @@
 /**
- * Module boundary and integration notes.
- * Create the deterministic matching key for a spatial quadrature node; this is sample identity, not a
- * cryptographic checksum. Spatial node identity binds supplied values to deterministic AA/aperture
- * quadrature. Average weights and square-micrometre geometric area measures are separate.
- * Negative/non-finite irradiance or incomplete/duplicate coverage fail; geometry does not establish
- * QE, radiometric collection area or calibrated transport.
- * Revalidate node coordinates, weights, geometric measures and coverage before using a spatial plan as
- * a trusted scientific input. Spatial node identity binds supplied values to deterministic AA/aperture
- * quadrature. Average weights and square-micrometre geometric area measures are separate.
- * Negative/non-finite irradiance or incomplete/duplicate coverage fail; geometry does not establish
- * QE, radiometric collection area or calibrated transport.
+ * Spatial sample reduction: combines values sampled at the spatial quadrature nodes of one sensor site
+ * (its aperture plus the anti-aliasing (AA) split) into a site average and an area integral.
+ *
+ * Each supplied value is matched to its node by an explicit identity key. Average weights and
+ * geometric area measures (in square micrometres) are kept separate. Negative or non-finite irradiance,
+ * and missing or duplicate nodes, are rejected. The geometry does not establish QE (quantum
+ * efficiency), an effective light-collection area or calibrated light transport.
  * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
@@ -32,10 +28,9 @@ export interface SensorSpatialQuadratureNodeIdentity {
 export interface SensorSpatialQuadratureNodeValue {
     node: SensorSpatialQuadratureNodeIdentity;
     /**
-     * Nonnegative finite scalar in the declared value domain.
+     * A nonnegative, finite number in the declared value domain.
      *
-     * Values are evaluated at the corresponding quadrature node's
-     * preAntiAliasingSourcePointMm.
+     * It is evaluated at the matching node's preAntiAliasingSourcePointMm.
      */
     value: number;
 }
@@ -43,9 +38,9 @@ export interface ReduceSensorSpatialSamplingQuadratureInput {
     quadrature: SensorSpatialSamplingQuadrature;
     valueDomain: SensorSpatialSampleValueDomain;
     /**
-     * Exactly one explicitly identified value per quadrature node.
+     * Exactly one value per quadrature node, each with its node identity.
      *
-     * Ordering is not significant; node identity is.
+     * Order does not matter; the node identity does.
      */
     nodeValues: readonly SensorSpatialQuadratureNodeValue[];
 }
@@ -54,13 +49,13 @@ export type SensorSpatialSampleReductionValue = {
     unit: "relative";
     semantic: "nonnegative-sensor-plane-irradiance-proxy";
     /**
-     * Dimensionless weighted spatial average in the same relative domain.
+     * Weighted spatial average (dimensionless), in the same relative domain.
      */
     normalizedSpatialAverageRelative: number;
     /**
      * Relative value × square micrometres.
      *
-     * This is a geometric area-weighted diagnostic, not radiometric power.
+     * A geometric, area-weighted diagnostic, not a radiometric power.
      */
     geometricAreaIntegralRelativeSquareMicrometers: number;
 } | {
@@ -68,18 +63,17 @@ export type SensorSpatialSampleReductionValue = {
     unit: "W/m^2";
     semantic: "sensor-plane-irradiance";
     /**
-     * Weighted mean irradiance over the geometric aperture after applying
-     * the declared normalized AA spatial redistribution.
+     * Weighted mean irradiance over the geometric aperture, after the
+     * declared normalized AA spreading.
      */
     normalizedSpatialAverageIrradianceWattsPerSquareMeter: number;
     /**
-     * Incident radiant flux represented by integrating the supplied
-     * irradiance over the geometric aperture under the declared normalized
-     * AA redistribution. Units: watts.
+     * Incident radiant flux: the supplied irradiance integrated over the
+     * geometric aperture, with the declared normalized AA spreading.
+     * Units: watts.
      *
-     * This remains pre-CFA-response, pre-QE, pre-microlens-response and
-     * excludes any optical-stack throughput not already present in the
-     * caller-supplied irradiance values.
+     * It is before any CFA response, QE or microlens response, and excludes
+     * any optical-stack throughput not already in the caller's irradiance values.
      */
     geometricApertureIncidentFluxWatts: number;
 };
@@ -89,9 +83,9 @@ export interface SensorSpatialSampleReduction {
         y: number;
     };
     /**
-     * Semantic destination CFA/color-site label only.
+     * Label of the destination CFA (colour filter array) site only.
      *
-     * No spectral filter response is applied by this reducer.
+     * This reducer applies no spectral filter response.
      */
     channelId: string;
     outputMeaning: "channel-tagged-pre-response-spatial-sample";
@@ -121,51 +115,42 @@ export interface SensorSpatialSampleReduction {
     demosaicOrReconstructionApplied: false;
 }
 /**
- * Create the deterministic matching key for a spatial quadrature node; this is sample identity, not a
- * cryptographic checksum.
- *
- * Spatial node identity binds supplied values to deterministic AA/aperture quadrature. Average weights
- * and square-micrometre geometric area measures are separate. Negative/non-finite irradiance or
- * incomplete/duplicate coverage fail; geometry does not establish QE, radiometric collection area or
- * calibrated transport.
- * @param identity - SensorSpatialQuadratureNodeIdentity. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns string. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Makes the deterministic key used to match a value to its spatial quadrature node. It identifies the
+ * sample; it is not a cryptographic checksum.
+ * @param identity - The input; see `SensorSpatialQuadratureNodeIdentity` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export declare function sensorSpatialQuadratureNodeIdentityKey(identity: SensorSpatialQuadratureNodeIdentity): string;
 /**
- * Revalidate node coordinates, weights, geometric measures and coverage before using a spatial plan as
- * a trusted scientific input.
+ * Rechecks node coordinates, weights, geometric measures and coverage before a spatial plan is trusted
+ * as scientific input.
  *
- * Spatial node identity binds supplied values to deterministic AA/aperture quadrature. Average weights
- * and square-micrometre geometric area measures are separate. Negative/non-finite irradiance or
- * incomplete/duplicate coverage fail; geometry does not establish QE, radiometric collection area or
- * calibrated transport.
- * @param quadrature - SensorSpatialSamplingQuadrature. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns Map<string, SensorSpatialSamplingQuadratureNode>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Average weights and geometric area measures are kept separate. The geometry does not establish QE,
+ * an effective light-collection area or calibrated light transport.
+ * @param quadrature - The input; see `SensorSpatialSamplingQuadrature` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export declare function validateSensorSpatialSamplingQuadrature(quadrature: SensorSpatialSamplingQuadrature): Map<string, SensorSpatialSamplingQuadratureNode>;
 /**
- * Reduces explicitly identified nonnegative linear scalar values over a
+ * Combines nonnegative linear values, each tagged with its node, 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.
+ * It does not sample a renderer or optical model itself. Callers evaluate one
+ * value at every node's preAntiAliasingSourcePointMm and pass the values with
+ * their exact node identity. Order does not matter.
  *
- * Two domains are supported:
+ * Two value 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.
+ * - relative-linear: a dimensionless, nonnegative stand-in for irradiance, for
+ *   deterministic renderer and science regression tests;
+ * - radiometric-irradiance: physical irradiance on the sensor plane 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.
+ * The destination site's channelId is a label only. No CFA spectral
+ * transmittance or sensitivity is applied, so do not call the output a
+ * colour-filtered mosaic sample or a RAW value.
  */
 export declare function reduceSensorSpatialSamplingQuadrature(input: ReduceSensorSpatialSamplingQuadratureInput): CalculationResult<SensorSpatialSampleReduction>;
-//# sourceMappingURL=spatial-sample-reduction.d.ts.map

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

@@ -1,21 +1,19 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Create the deterministic matching key for a spatial quadrature node; this is sample identity, not a
- * cryptographic checksum. Spatial node identity binds supplied values to deterministic AA/aperture
- * quadrature. Average weights and square-micrometre geometric area measures are separate.
- * Negative/non-finite irradiance or incomplete/duplicate coverage fail; geometry does not establish
- * QE, radiometric collection area or calibrated transport.
- * Revalidate node coordinates, weights, geometric measures and coverage before using a spatial plan as
- * a trusted scientific input. Spatial node identity binds supplied values to deterministic AA/aperture
- * quadrature. Average weights and square-micrometre geometric area measures are separate.
- * Negative/non-finite irradiance or incomplete/duplicate coverage fail; geometry does not establish
- * QE, radiometric collection area or calibrated transport.
+ * Spatial sample reduction: combines values sampled at the spatial quadrature nodes of one sensor site
+ * (its aperture plus the anti-aliasing (AA) split) into a site average and an area integral.
+ *
+ * Each supplied value is matched to its node by an explicit identity key. Average weights and
+ * geometric area measures (in square micrometres) are kept separate. Negative or non-finite irradiance,
+ * and missing or duplicate nodes, are rejected. The geometry does not establish QE (quantum
+ * efficiency), an effective light-collection area or calibrated light transport.
  * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
  * limits.
  */
 import { approximationResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError } from "../core/validation.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 const SQUARE_MICROMETERS_TO_SQUARE_METERS = 1e-12;
 const WEIGHT_TOLERANCE = 1e-10;
 const AREA_TOLERANCE = 1e-10;
@@ -50,7 +48,7 @@ function parseValueDomain(value) {
     if (typeof value !== "object" ||
         value === null ||
         Array.isArray(value)) {
-        throw new InvalidScientificInputError("valueDomain must be an object.");
+        throw new InvalidConfigurationError("valueDomain must be an object.");
     }
     const record = value;
     if (record.kind === "relative-linear") {
@@ -77,20 +75,15 @@ function parseValueDomain(value) {
             semantic: "sensor-plane-irradiance"
         };
     }
-    throw new InvalidScientificInputError("valueDomain.kind is invalid.");
+    throw new InvalidConfigurationError("valueDomain.kind is invalid.");
 }
 /**
- * Create the deterministic matching key for a spatial quadrature node; this is sample identity, not a
- * cryptographic checksum.
- *
- * Spatial node identity binds supplied values to deterministic AA/aperture quadrature. Average weights
- * and square-micrometre geometric area measures are separate. Negative/non-finite irradiance or
- * incomplete/duplicate coverage fail; geometry does not establish QE, radiometric collection area or
- * calibrated transport.
- * @param identity - SensorSpatialQuadratureNodeIdentity. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns string. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Makes the deterministic key used to match a value to its spatial quadrature node. It identifies the
+ * sample; it is not a cryptographic checksum.
+ * @param identity - The input; see `SensorSpatialQuadratureNodeIdentity` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export function sensorSpatialQuadratureNodeIdentityKey(identity) {
     return (identity.antiAliasingComponentIndex +
@@ -125,23 +118,21 @@ function approximatelyEqual(actual, expected, tolerance) {
         tolerance * scale);
 }
 /**
- * Revalidate node coordinates, weights, geometric measures and coverage before using a spatial plan as
- * a trusted scientific input.
+ * Rechecks node coordinates, weights, geometric measures and coverage before a spatial plan is trusted
+ * as scientific input.
  *
- * Spatial node identity binds supplied values to deterministic AA/aperture quadrature. Average weights
- * and square-micrometre geometric area measures are separate. Negative/non-finite irradiance or
- * incomplete/duplicate coverage fail; geometry does not establish QE, radiometric collection area or
- * calibrated transport.
- * @param quadrature - SensorSpatialSamplingQuadrature. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns Map<string, SensorSpatialSamplingQuadratureNode>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Average weights and geometric area measures are kept separate. The geometry does not establish QE,
+ * an effective light-collection area or calibrated light transport.
+ * @param quadrature - The input; see `SensorSpatialSamplingQuadrature` for its fields, units and coordinates.
+ * @returns The result. Success does not imply calibration.
  *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ * @see docs/API_REFERENCE.md for the package export and its full type definitions.
  */
 export function validateSensorSpatialSamplingQuadrature(quadrature) {
     if (typeof quadrature !== "object" ||
         quadrature === null ||
         !Array.isArray(quadrature.nodes)) {
-        throw new InvalidScientificInputError("quadrature must contain a nodes array.");
+        throw new InvalidConfigurationError("quadrature must contain a nodes array.");
     }
     const totalNodeCount = requireSafeNonNegativeInteger(quadrature.totalNodeCount, "quadrature.totalNodeCount");
     if (totalNodeCount === 0 ||
@@ -152,11 +143,11 @@ export function validateSensorSpatialSamplingQuadrature(quadrature) {
     if (quadrature.colorSamplingProfileId !== undefined &&
         (typeof quadrature.colorSamplingProfileId !== "string" ||
             quadrature.colorSamplingProfileId.trim().length === 0)) {
-        throw new InvalidScientificInputError("quadrature.colorSamplingProfileId must be a non-empty string when supplied.");
+        throw new InvalidConfigurationError("quadrature.colorSamplingProfileId must be a non-empty string when supplied.");
     }
     if (typeof quadrature.channelId !== "string" ||
         quadrature.channelId.trim().length === 0) {
-        throw new InvalidScientificInputError("quadrature.channelId must be a non-empty string.");
+        throw new InvalidConfigurationError("quadrature.channelId must be a non-empty string.");
     }
     requireSafeNonNegativeInteger(quadrature.site.x, "quadrature.site.x");
     requireSafeNonNegativeInteger(quadrature.site.y, "quadrature.site.y");
@@ -196,7 +187,7 @@ export function validateSensorSpatialSamplingQuadrature(quadrature) {
 }
 function parseNodeValues(nodeValues, nodesByKey) {
     if (!Array.isArray(nodeValues)) {
-        throw new InvalidScientificInputError("nodeValues must be an array.");
+        throw new InvalidConfigurationError("nodeValues must be an array.");
     }
     if (nodeValues.length !==
         nodesByKey.size) {
@@ -240,25 +231,25 @@ function parseNodeValues(nodeValues, nodesByKey) {
     return valuesByKey;
 }
 /**
- * Reduces explicitly identified nonnegative linear scalar values over a
+ * Combines nonnegative linear values, each tagged with its node, 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.
+ * It does not sample a renderer or optical model itself. Callers evaluate one
+ * value at every node's preAntiAliasingSourcePointMm and pass the values with
+ * their exact node identity. Order does not matter.
  *
- * Two domains are supported:
+ * Two value 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.
+ * - relative-linear: a dimensionless, nonnegative stand-in for irradiance, for
+ *   deterministic renderer and science regression tests;
+ * - radiometric-irradiance: physical irradiance on the sensor plane 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.
+ * The destination site's channelId is a label only. No CFA spectral
+ * transmittance or sensitivity is applied, so do not call the output a
+ * colour-filtered mosaic sample or a RAW value.
  */
 export function reduceSensorSpatialSamplingQuadrature(input) {
+    requireInputKeys(input, "reduceSensorSpatialSamplingQuadrature", ["quadrature", "valueDomain", "nodeValues"]);
     const domain = parseValueDomain(input.valueDomain);
     const nodesByKey = validateSensorSpatialSamplingQuadrature(input.quadrature);
     const valuesByKey = parseNodeValues(input.nodeValues, nodesByKey);

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

@@ -1 +1 @@
-{"version":3,"file":"spatial-sample-reduction.js","sourceRoot":"","sources":["../../src/sensor/spatial-sample-reduction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"spatial-sample-reduction.js","sourceRoot":"","sources":["../../src/sensor/spatial-sample-reduction.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Spatial sample reduction: combines values sampled at the spatial quadrature nodes of one sensor site\n * (its aperture plus the anti-aliasing (AA) split) into a site average and an area integral.\n *\n * Each supplied value is matched to its node by an explicit identity key. Average weights and\n * geometric area measures (in square micrometres) are kept separate. Negative or non-finite irradiance,\n * and missing or duplicate nodes, are rejected. The geometry does not establish QE (quantum\n * efficiency), an effective light-collection area or calibrated light transport.\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 { InvalidScientificInputError } from \"../core/validation.js\";\nimport type {\n  SensorSpatialSamplingQuadrature,\n  SensorSpatialSamplingQuadratureNode\n} from \"./spatial-sampling-quadrature.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nconst SQUARE_MICROMETERS_TO_SQUARE_METERS = 1e-12;\nconst WEIGHT_TOLERANCE = 1e-10;\nconst AREA_TOLERANCE = 1e-10;\n\nexport type SensorSpatialSampleValueDomain =\n  | {\n      kind: \"relative-linear\";\n      unit: \"relative\";\n      semantic:\n        \"nonnegative-sensor-plane-irradiance-proxy\";\n    }\n  | {\n      kind: \"radiometric-irradiance\";\n      unit: \"W/m^2\";\n      semantic: \"sensor-plane-irradiance\";\n    };\n\nexport interface SensorSpatialQuadratureNodeIdentity {\n  antiAliasingComponentIndex: number;\n  apertureSampleXIndex: number;\n  apertureSampleYIndex: number;\n}\n\nexport interface SensorSpatialQuadratureNodeValue {\n  node: SensorSpatialQuadratureNodeIdentity;\n  /**\n   * A nonnegative, finite number in the declared value domain.\n   *\n   * It is evaluated at the matching node's preAntiAliasingSourcePointMm.\n   */\n  value: number;\n}\n\nexport interface ReduceSensorSpatialSamplingQuadratureInput {\n  quadrature: SensorSpatialSamplingQuadrature;\n  valueDomain: SensorSpatialSampleValueDomain;\n  /**\n   * Exactly one value per quadrature node, each with its node identity.\n   *\n   * Order does not matter; the node identity does.\n   */\n  nodeValues: readonly SensorSpatialQuadratureNodeValue[];\n}\n\nexport type SensorSpatialSampleReductionValue =\n  | {\n      kind: \"relative-linear\";\n      unit: \"relative\";\n      semantic:\n        \"nonnegative-sensor-plane-irradiance-proxy\";\n      /**\n       * Weighted spatial average (dimensionless), in the same relative domain.\n       */\n      normalizedSpatialAverageRelative: number;\n      /**\n       * Relative value × square micrometres.\n       *\n       * A geometric, area-weighted diagnostic, not a radiometric power.\n       */\n      geometricAreaIntegralRelativeSquareMicrometers: number;\n    }\n  | {\n      kind: \"radiometric-irradiance\";\n      unit: \"W/m^2\";\n      semantic: \"sensor-plane-irradiance\";\n      /**\n       * Weighted mean irradiance over the geometric aperture, after the\n       * declared normalized AA spreading.\n       */\n      normalizedSpatialAverageIrradianceWattsPerSquareMeter: number;\n      /**\n       * Incident radiant flux: the supplied irradiance integrated over the\n       * geometric aperture, with the declared normalized AA spreading.\n       * Units: watts.\n       *\n       * It is before any CFA response, QE or microlens response, and excludes\n       * any optical-stack throughput not already in the caller's irradiance values.\n       */\n      geometricApertureIncidentFluxWatts: number;\n    };\n\nexport interface SensorSpatialSampleReduction {\n  site: {\n    x: number;\n    y: number;\n  };\n  /**\n   * Label of the destination CFA (colour filter array) site only.\n   *\n   * This reducer applies no spectral filter response.\n   */\n  channelId: string;\n  outputMeaning:\n    \"channel-tagged-pre-response-spatial-sample\";\n  valueDomain: SensorSpatialSampleValueDomain;\n  nodeCount: number;\n  sourceValuesMatchedBy:\n    \"quadrature-node-identity\";\n  sourceValuesSuppliedForAllNodes: true;\n  outsideImagingAreaSourceValuesRequired: boolean;\n  normalizedSpatialWeightSum: number;\n  geometricApertureAreaSquareMicrometers: number;\n  reducedValue: SensorSpatialSampleReductionValue;\n  cfaSpectralFilteringApplied: false;\n  channelIdIsSpectralResponse: false;\n  temporalIntegrationApplied: false;\n  exposureDurationApplied: false;\n  quantumEfficiencyApplied: false;\n  microlensResponseApplied: false;\n  opticalThroughputAppliedByReducer: false;\n  photonsCalculated: false;\n  electronsCalculated: false;\n  shotNoiseApplied: false;\n  readNoiseApplied: false;\n  adcQuantizationApplied: false;\n  blackLevelApplied: false;\n  saturationApplied: false;\n  rawCodeValueProduced: false;\n  demosaicOrReconstructionApplied: false;\n}\n\nfunction requireSafeNonNegativeInteger(\n  value: unknown,\n  path: string\n): number {\n  if (\n    typeof value !== \"number\" ||\n    !Number.isSafeInteger(value) ||\n    value < 0\n  ) {\n    throw new InvalidScientificInputError(\n      path +\n        \" must be a non-negative safe integer.\"\n    );\n  }\n  return value;\n}\n\nfunction requireNonNegativeFinite(\n  value: unknown,\n  path: string\n): number {\n  if (\n    typeof value !== \"number\" ||\n    !Number.isFinite(value) ||\n    value < 0\n  ) {\n    throw new InvalidScientificInputError(\n      path +\n        \" must be a finite number greater than or equal to zero.\"\n    );\n  }\n  return value;\n}\n\nfunction requirePositiveFinite(\n  value: unknown,\n  path: string\n): number {\n  if (\n    typeof value !== \"number\" ||\n    !Number.isFinite(value) ||\n    value <= 0\n  ) {\n    throw new InvalidScientificInputError(\n      path +\n        \" must be a finite number greater than zero.\"\n    );\n  }\n  return value;\n}\n\nfunction parseValueDomain(\n  value: unknown\n): SensorSpatialSampleValueDomain {\n  if (\n    typeof value !== \"object\" ||\n    value === null ||\n    Array.isArray(value)\n  ) {\n    throw new InvalidConfigurationError(\n      \"valueDomain must be an object.\"\n    );\n  }\n\n  const record = value as Record<string, unknown>;\n\n  if (record.kind === \"relative-linear\") {\n    if (\n      record.unit !== \"relative\" ||\n      record.semantic !==\n        \"nonnegative-sensor-plane-irradiance-proxy\"\n    ) {\n      throw new InvalidScientificInputError(\n        \"relative-linear valueDomain must use unit \\\"relative\\\" and the canonical nonnegative sensor-plane irradiance-proxy semantic.\"\n      );\n    }\n    return {\n      kind: \"relative-linear\",\n      unit: \"relative\",\n      semantic:\n        \"nonnegative-sensor-plane-irradiance-proxy\"\n    };\n  }\n\n  if (\n    record.kind === \"radiometric-irradiance\"\n  ) {\n    if (\n      record.unit !== \"W/m^2\" ||\n      record.semantic !==\n        \"sensor-plane-irradiance\"\n    ) {\n      throw new InvalidScientificInputError(\n        \"radiometric-irradiance valueDomain must use unit \\\"W/m^2\\\" and semantic \\\"sensor-plane-irradiance\\\".\"\n      );\n    }\n    return {\n      kind: \"radiometric-irradiance\",\n      unit: \"W/m^2\",\n      semantic: \"sensor-plane-irradiance\"\n    };\n  }\n\n  throw new InvalidConfigurationError(\n    \"valueDomain.kind is invalid.\"\n  );\n}\n\n/**\n * Makes the deterministic key used to match a value to its spatial quadrature node. It identifies the\n * sample; it is not a cryptographic checksum.\n * @param identity - The input; see `SensorSpatialQuadratureNodeIdentity` for its fields, units and coordinates.\n * @returns The result. Success does not imply calibration.\n *\n * @see docs/API_REFERENCE.md for the package export and its full type definitions.\n */\nexport function sensorSpatialQuadratureNodeIdentityKey(\n  identity: SensorSpatialQuadratureNodeIdentity\n): string {\n  return (\n    identity.antiAliasingComponentIndex +\n    \":\" +\n    identity.apertureSampleXIndex +\n    \":\" +\n    identity.apertureSampleYIndex\n  );\n}\n\nfunction validateQuadratureNode(\n  node: SensorSpatialSamplingQuadratureNode,\n  index: number\n): SensorSpatialQuadratureNodeIdentity {\n  const identity = {\n    antiAliasingComponentIndex:\n      requireSafeNonNegativeInteger(\n        node.antiAliasingComponentIndex,\n        \"quadrature.nodes[\" +\n          index +\n          \"].antiAliasingComponentIndex\"\n      ),\n    apertureSampleXIndex:\n      requireSafeNonNegativeInteger(\n        node.apertureSampleXIndex,\n        \"quadrature.nodes[\" +\n          index +\n          \"].apertureSampleXIndex\"\n      ),\n    apertureSampleYIndex:\n      requireSafeNonNegativeInteger(\n        node.apertureSampleYIndex,\n        \"quadrature.nodes[\" +\n          index +\n          \"].apertureSampleYIndex\"\n      )\n  };\n\n  requireNonNegativeFinite(\n    node.combinedNormalizedSpatialWeight,\n    \"quadrature.nodes[\" +\n      index +\n      \"].combinedNormalizedSpatialWeight\"\n  );\n  requireNonNegativeFinite(\n    node.combinedAreaMeasureSquareMicrometers,\n    \"quadrature.nodes[\" +\n      index +\n      \"].combinedAreaMeasureSquareMicrometers\"\n  );\n\n  return identity;\n}\n\nfunction approximatelyEqual(\n  actual: number,\n  expected: number,\n  tolerance: number\n): boolean {\n  const scale = Math.max(\n    1,\n    Math.abs(actual),\n    Math.abs(expected)\n  );\n  return (\n    Math.abs(actual - expected) <=\n    tolerance * scale\n  );\n}\n\n/**\n * Rechecks node coordinates, weights, geometric measures and coverage before a spatial plan is trusted\n * as scientific input.\n *\n * Average weights and geometric area measures are kept separate. The geometry does not establish QE,\n * an effective light-collection area or calibrated light transport.\n * @param quadrature - The input; see `SensorSpatialSamplingQuadrature` for its fields, units and coordinates.\n * @returns The result. Success does not imply calibration.\n *\n * @see docs/API_REFERENCE.md for the package export and its full type definitions.\n */\nexport function validateSensorSpatialSamplingQuadrature(\n  quadrature: SensorSpatialSamplingQuadrature\n): Map<string, SensorSpatialSamplingQuadratureNode> {\n  if (\n    typeof quadrature !== \"object\" ||\n    quadrature === null ||\n    !Array.isArray(quadrature.nodes)\n  ) {\n    throw new InvalidConfigurationError(\n      \"quadrature must contain a nodes array.\"\n    );\n  }\n\n  const totalNodeCount =\n    requireSafeNonNegativeInteger(\n      quadrature.totalNodeCount,\n      \"quadrature.totalNodeCount\"\n    );\n\n  if (\n    totalNodeCount === 0 ||\n    quadrature.nodes.length !==\n      totalNodeCount\n  ) {\n    throw new InvalidScientificInputError(\n      \"quadrature.totalNodeCount must be positive and exactly match quadrature.nodes.length.\"\n    );\n  }\n\n  if (\n    quadrature.colorSamplingProfileId !== undefined &&\n    (\n      typeof quadrature.colorSamplingProfileId !== \"string\" ||\n      quadrature.colorSamplingProfileId.trim().length === 0\n    )\n  ) {\n    throw new InvalidConfigurationError(\n      \"quadrature.colorSamplingProfileId must be a non-empty string when supplied.\"\n    );\n  }\n\n  if (\n    typeof quadrature.channelId !== \"string\" ||\n    quadrature.channelId.trim().length === 0\n  ) {\n    throw new InvalidConfigurationError(\n      \"quadrature.channelId must be a non-empty string.\"\n    );\n  }\n\n  requireSafeNonNegativeInteger(\n    quadrature.site.x,\n    \"quadrature.site.x\"\n  );\n  requireSafeNonNegativeInteger(\n    quadrature.site.y,\n    \"quadrature.site.y\"\n  );\n\n  const geometricArea =\n    requirePositiveFinite(\n      quadrature.geometricApertureAreaSquareMicrometers,\n      \"quadrature.geometricApertureAreaSquareMicrometers\"\n    );\n\n  const nodesByKey =\n    new Map<\n      string,\n      SensorSpatialSamplingQuadratureNode\n    >();\n  let weightSum = 0;\n  let areaSum = 0;\n\n  quadrature.nodes.forEach(\n    (node, index) => {\n      const identity =\n        validateQuadratureNode(node, index);\n      const key = sensorSpatialQuadratureNodeIdentityKey(identity);\n\n      if (nodesByKey.has(key)) {\n        throw new InvalidScientificInputError(\n          \"quadrature contains duplicate node identities.\"\n        );\n      }\n\n      nodesByKey.set(key, node);\n      weightSum +=\n        node.combinedNormalizedSpatialWeight;\n      areaSum +=\n        node.combinedAreaMeasureSquareMicrometers;\n\n      if (\n        !Number.isFinite(weightSum) ||\n        !Number.isFinite(areaSum)\n      ) {\n        throw new InvalidScientificInputError(\n          \"quadrature aggregate weights/measures must remain finite.\"\n        );\n      }\n    }\n  );\n\n  if (\n    !approximatelyEqual(\n      weightSum,\n      1,\n      WEIGHT_TOLERANCE\n    )\n  ) {\n    throw new InvalidScientificInputError(\n      \"quadrature combined normalized spatial weights must sum to 1.\"\n    );\n  }\n\n  if (\n    !approximatelyEqual(\n      areaSum,\n      geometricArea,\n      AREA_TOLERANCE\n    )\n  ) {\n    throw new InvalidScientificInputError(\n      \"quadrature combined geometric area measures must sum to the geometric aperture area.\"\n    );\n  }\n\n  if (\n    !approximatelyEqual(\n      quadrature.normalizedSpatialWeightSum,\n      weightSum,\n      WEIGHT_TOLERANCE\n    )\n  ) {\n    throw new InvalidScientificInputError(\n      \"quadrature.normalizedSpatialWeightSum does not match node weights.\"\n    );\n  }\n\n  if (\n    !approximatelyEqual(\n      quadrature.combinedAreaMeasureSumSquareMicrometers,\n      areaSum,\n      AREA_TOLERANCE\n    )\n  ) {\n    throw new InvalidScientificInputError(\n      \"quadrature.combinedAreaMeasureSumSquareMicrometers does not match node measures.\"\n    );\n  }\n\n  return nodesByKey;\n}\n\nfunction parseNodeValues(\n  nodeValues: readonly SensorSpatialQuadratureNodeValue[],\n  nodesByKey: ReadonlyMap<\n    string,\n    SensorSpatialSamplingQuadratureNode\n  >\n): Map<string, number> {\n  if (!Array.isArray(nodeValues)) {\n    throw new InvalidConfigurationError(\n      \"nodeValues must be an array.\"\n    );\n  }\n\n  if (\n    nodeValues.length !==\n    nodesByKey.size\n  ) {\n    throw new InvalidScientificInputError(\n      \"nodeValues must contain exactly one value for every quadrature node.\"\n    );\n  }\n\n  const valuesByKey = new Map<string, number>();\n\n  nodeValues.forEach((entry, index) => {\n    if (\n      typeof entry !== \"object\" ||\n      entry === null ||\n      typeof entry.node !== \"object\" ||\n      entry.node === null\n    ) {\n      throw new InvalidScientificInputError(\n        \"nodeValues[\" +\n          index +\n          \"] must contain a node identity object.\"\n      );\n    }\n\n    const identity = {\n      antiAliasingComponentIndex:\n        requireSafeNonNegativeInteger(\n          entry.node\n            .antiAliasingComponentIndex,\n          \"nodeValues[\" +\n            index +\n            \"].node.antiAliasingComponentIndex\"\n        ),\n      apertureSampleXIndex:\n        requireSafeNonNegativeInteger(\n          entry.node.apertureSampleXIndex,\n          \"nodeValues[\" +\n            index +\n            \"].node.apertureSampleXIndex\"\n        ),\n      apertureSampleYIndex:\n        requireSafeNonNegativeInteger(\n          entry.node.apertureSampleYIndex,\n          \"nodeValues[\" +\n            index +\n            \"].node.apertureSampleYIndex\"\n        )\n    };\n    const key = sensorSpatialQuadratureNodeIdentityKey(identity);\n\n    if (!nodesByKey.has(key)) {\n      throw new InvalidScientificInputError(\n        \"nodeValues[\" +\n          index +\n          \"] identifies a node that is not present in quadrature.\"\n      );\n    }\n    if (valuesByKey.has(key)) {\n      throw new InvalidScientificInputError(\n        \"nodeValues contains duplicate node identities.\"\n      );\n    }\n\n    valuesByKey.set(\n      key,\n      requireNonNegativeFinite(\n        entry.value,\n        \"nodeValues[\" +\n          index +\n          \"].value\"\n      )\n    );\n  });\n\n  return valuesByKey;\n}\n\n/**\n * Combines nonnegative linear values, each tagged with its node, over a\n * validated sensor spatial quadrature.\n *\n * It does not sample a renderer or optical model itself. Callers evaluate one\n * value at every node's preAntiAliasingSourcePointMm and pass the values with\n * their exact node identity. Order does not matter.\n *\n * Two value domains are supported:\n *\n * - relative-linear: a dimensionless, nonnegative stand-in for irradiance, for\n *   deterministic renderer and science regression tests;\n * - radiometric-irradiance: physical irradiance on the sensor plane in W/m^2.\n *\n * The destination site's channelId is a label only. No CFA spectral\n * transmittance or sensitivity is applied, so do not call the output a\n * colour-filtered mosaic sample or a RAW value.\n */\nexport function reduceSensorSpatialSamplingQuadrature(\n  input: ReduceSensorSpatialSamplingQuadratureInput\n): CalculationResult<SensorSpatialSampleReduction> {\n  requireInputKeys(input, \"reduceSensorSpatialSamplingQuadrature\", [\"quadrature\", \"valueDomain\", \"nodeValues\"]);\n  const domain = parseValueDomain(\n    input.valueDomain\n  );\n  const nodesByKey = validateSensorSpatialSamplingQuadrature(\n    input.quadrature\n  );\n  const valuesByKey = parseNodeValues(\n    input.nodeValues,\n    nodesByKey\n  );\n\n  let weightedAverage = 0;\n  let areaWeightedIntegral = 0;\n\n  nodesByKey.forEach((node, key) => {\n    const value = valuesByKey.get(key);\n    if (value === undefined) {\n      throw new InvalidScientificInputError(\n        \"A quadrature node is missing its explicit source value.\"\n      );\n    }\n\n    weightedAverage +=\n      value *\n      node.combinedNormalizedSpatialWeight;\n    areaWeightedIntegral +=\n      value *\n      node.combinedAreaMeasureSquareMicrometers;\n\n    if (\n      !Number.isFinite(weightedAverage) ||\n      !Number.isFinite(areaWeightedIntegral)\n    ) {\n      throw new InvalidScientificInputError(\n        \"Reduced spatial sample must remain finite.\"\n      );\n    }\n  });\n\n  const reducedValue:\n    SensorSpatialSampleReductionValue =\n    domain.kind === \"relative-linear\"\n      ? {\n          kind: \"relative-linear\",\n          unit: \"relative\",\n          semantic:\n            \"nonnegative-sensor-plane-irradiance-proxy\",\n          normalizedSpatialAverageRelative:\n            weightedAverage,\n          geometricAreaIntegralRelativeSquareMicrometers:\n            areaWeightedIntegral\n        }\n      : {\n          kind: \"radiometric-irradiance\",\n          unit: \"W/m^2\",\n          semantic:\n            \"sensor-plane-irradiance\",\n          normalizedSpatialAverageIrradianceWattsPerSquareMeter:\n            weightedAverage,\n          geometricApertureIncidentFluxWatts:\n            areaWeightedIntegral *\n            SQUARE_MICROMETERS_TO_SQUARE_METERS\n        };\n\n  return approximationResult(\n    {\n      site: {\n        ...input.quadrature.site\n      },\n      channelId:\n        input.quadrature.channelId,\n      outputMeaning:\n        \"channel-tagged-pre-response-spatial-sample\",\n      valueDomain: domain,\n      nodeCount:\n        input.quadrature.totalNodeCount,\n      sourceValuesMatchedBy:\n        \"quadrature-node-identity\",\n      sourceValuesSuppliedForAllNodes: true,\n      outsideImagingAreaSourceValuesRequired:\n        input.quadrature\n          .preAntiAliasingSourceOutsideImagingAreaNodeCount >\n        0,\n      normalizedSpatialWeightSum:\n        input.quadrature\n          .normalizedSpatialWeightSum,\n      geometricApertureAreaSquareMicrometers:\n        input.quadrature\n          .geometricApertureAreaSquareMicrometers,\n      reducedValue,\n      cfaSpectralFilteringApplied: false,\n      channelIdIsSpectralResponse: false,\n      temporalIntegrationApplied: false,\n      exposureDurationApplied: false,\n      quantumEfficiencyApplied: false,\n      microlensResponseApplied: false,\n      opticalThroughputAppliedByReducer:\n        false,\n      photonsCalculated: false,\n      electronsCalculated: false,\n      shotNoiseApplied: false,\n      readNoiseApplied: false,\n      adcQuantizationApplied: false,\n      blackLevelApplied: false,\n      saturationApplied: false,\n      rawCodeValueProduced: false,\n      demosaicOrReconstructionApplied: false\n    },\n    \"sensor-spatial-sample-reduction\",\n    \"1.0.0\",\n    [\n      \"Input values are nonnegative linear scalars evaluated at each quadrature node's pre-AA source coordinate.\",\n      \"Node values are matched by explicit quadrature-node identity rather than positional array order.\",\n      \"The destination CFA/color channel is metadata only; no spectral transmittance, sensor spectral responsivity or quantum efficiency is applied.\",\n      \"Relative-linear values are dimensionless irradiance-like proxies for deterministic testing and do not become physical radiometry.\",\n      \"Radiometric-irradiance values use W/m^2; geometric aperture integration converts square micrometres to square metres to report incident radiant flux in watts.\",\n      \"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.\",\n      \"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.\",\n      \"Negative, NaN and infinite source values are rejected; signed intermediate color-transform values are outside this pre-response sensor-plane contract.\",\n      \"Temporal exposure integration, wavelength integration, photons/electrons, noise, saturation, black level, ADC quantization, RAW code values and reconstruction remain separate future work.\"\n    ]\n  );\n}\n"]}