@photivra/engine 1.5.0 → 2.0.0

package/dist/optics/front-of-lens-filter.js

@@ -1,24 +1,43 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Parses one generic front-of-lens transmission filter. Schema 0.1.0 is explicitly unbranded and
- * unpolarized. It models only passive transmission placed before the lens. Reflections between stacked
- * filters, polarization, flare/ghosting and wavelength-changing behavior are outside this contract.
- * Resolves one passive filter at one wavelength.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Generic filters that screw onto the front of the lens.
+ *
+ * Schema 0.1.0 is explicitly unbranded and unpolarized. It models only passive transmission in front
+ * of the lens. It does not cover reflections between stacked filters, flare or ghosting, or filters
+ * that change wavelength.
+ *
+ * Schema 0.2.0 adds one polarizing kind: a linear (partial) polarizer. It has a principal
+ * transmittance k1, an extinction ratio k1/k2 and a transmission-axis angle. Polarization is carried
+ * as linear Stokes parameters (S0, S1, S2). Filters are applied in order using the Mueller matrix of
+ * a linear diattenuator (Gil, arXiv:2002.04105, eqs. 134-135, free; Malus's law: OpenStax University
+ * Physics Vol. 3, sec. 1.7, free. Also see: Chipman, Handbook of Optics vol. I ch. 22, 3rd ed., 2010;
+ * Goldstein, Polarized Light, 3rd ed., ch. 4-5; Born & Wolf, Principles of Optics, sec. 1.4.2):
+ *   T = (k1 + k2)/2 + (k1 - k2)/2 * P * cos(2 (psi - theta))
+ * Here P is the incident light's degree of linear polarization, psi its polarization angle and theta
+ * the filter axis angle.
+ * - For P = 1 this is Malus's law: k1 cos^2(psi - theta) + k2 sin^2(psi - theta).
+ * - For unpolarized light it is (k1 + k2)/2, about half of k1.
+ * Not modelled: circular polarization, retardance (for example the quarter-wave plate in a circular
+ * polarizer), dependence on the angle of incidence, and depolarization.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { InvalidConfigurationError } from "../core/configuration-error.js";
 import { parseEvidenceList } from "../core/evidence-provenance.js";
 import { parseSpectralWavelengthBasis } from "../core/spectral.js";
 import { InvalidScientificInputError } from "../core/validation.js";
+import { requireInputKeys, rejectUnknownFields, rejectUnknownVariantFields, UNCERTAINTY_VARIANT_FIELDS } from "../core/record-validation.js";
 export const FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION = "0.1.0";
-function requireRecord(value, path) {
+/** Schema that also allows the `linear-polarizer` transmission kind. */
+export const FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION = "0.2.0";
+function requireRecord(value, path, allowedKeys) {
     if (typeof value !== "object" ||
         value === null ||
         Array.isArray(value)) {
         throw new InvalidConfigurationError(path + " must be an object.");
     }
+    if (allowedKeys !== null)
+        rejectUnknownFields(value, allowedKeys, path);
     return value;
 }
 function requireNonEmptyString(value, path) {
@@ -60,7 +79,7 @@ function requirePassiveTransmission(value, path) {
     return parsed;
 }
 function parseRange(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["minimum", "maximum"]);
     const minimum = requirePositiveFinite(record.minimum, path + ".minimum");
     const maximum = requirePositiveFinite(record.maximum, path + ".maximum");
     if (minimum > maximum) {
@@ -88,7 +107,8 @@ function parseScientificStatus(value, path) {
     return value;
 }
 function parseUncertainty(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, null);
+    rejectUnknownVariantFields(record, "kind", UNCERTAINTY_VARIANT_FIELDS, path);
     if (record.kind === "relative") {
         const fraction = requireNonNegativeFinite(record.fraction, path + ".fraction");
         if (fraction > 1) {
@@ -146,7 +166,7 @@ function parseSpectralSamples(value, path) {
             "[" +
             index +
             "]";
-        const record = requireRecord(entry, samplePath);
+        const record = requireRecord(entry, samplePath, ["wavelengthNanometers", "linearTransmissionFactor"]);
         const wavelengthNanometers = requirePositiveFinite(record.wavelengthNanometers, samplePath +
             ".wavelengthNanometers");
         if (wavelengthNanometers <=
@@ -163,12 +183,42 @@ function parseSpectralSamples(value, path) {
         };
     });
 }
-function parseTransmission(value, path) {
-    const record = requireRecord(value, path);
+function parseTransmission(value, path, polarizerAllowed) {
+    const record = requireRecord(value, path, null);
+    rejectUnknownVariantFields(record, "kind", {
+        "neutral-linear-transmission": ["kind", "linearTransmissionFactor"],
+        "neutral-optical-density": ["kind", "opticalDensityBase10"],
+        "spectral-transmission": ["kind", "samples"],
+        "linear-polarizer": ["kind", "principalTransmittance", "extinctionRatio", "transmissionAxisDegrees"]
+    }, path);
+    if (record.kind === "linear-polarizer") {
+        if (!polarizerAllowed) {
+            throw new InvalidConfigurationError(path + '.kind "linear-polarizer" requires schemaVersion "' +
+                FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION + '".');
+        }
+        const principal = requireRecord(record.principalTransmittance, path + ".principalTransmittance", ["value", "evidence"]);
+        const extinction = requireRecord(record.extinctionRatio, path + ".extinctionRatio", ["value", "evidence"]);
+        const ratio = requireFinite(extinction.value, path + ".extinctionRatio.value");
+        if (ratio < 1) {
+            throw new InvalidConfigurationError(path + ".extinctionRatio.value must be at least one.");
+        }
+        return {
+            kind: "linear-polarizer",
+            principalTransmittance: {
+                value: requirePassiveTransmission(principal.value, path + ".principalTransmittance.value"),
+                evidence: parseEvidenceList(principal.evidence, path + ".principalTransmittance.evidence")
+            },
+            extinctionRatio: {
+                value: ratio,
+                evidence: parseEvidenceList(extinction.evidence, path + ".extinctionRatio.evidence")
+            },
+            transmissionAxisDegrees: requireFinite(record.transmissionAxisDegrees, path + ".transmissionAxisDegrees")
+        };
+    }
     if (record.kind ===
         "neutral-linear-transmission") {
         const fact = requireRecord(record.linearTransmissionFactor, path +
-            ".linearTransmissionFactor");
+            ".linearTransmissionFactor", ["value", "evidence"]);
         return {
             kind: "neutral-linear-transmission",
             linearTransmissionFactor: {
@@ -182,7 +232,7 @@ function parseTransmission(value, path) {
     if (record.kind ===
         "neutral-optical-density") {
         const fact = requireRecord(record.opticalDensityBase10, path +
-            ".opticalDensityBase10");
+            ".opticalDensityBase10", ["value", "evidence"]);
         return {
             kind: "neutral-optical-density",
             opticalDensityBase10: {
@@ -195,7 +245,7 @@ function parseTransmission(value, path) {
     }
     if (record.kind ===
         "spectral-transmission") {
-        const fact = requireRecord(record.samples, path + ".samples");
+        const fact = requireRecord(record.samples, path + ".samples", ["value", "evidence"]);
         return {
             kind: "spectral-transmission",
             samples: {
@@ -212,18 +262,23 @@ function parseTransmission(value, path) {
  * Parses one generic front-of-lens transmission filter.
  *
  * Schema 0.1.0 is explicitly unbranded and unpolarized. It models only
- * passive transmission placed before the lens. Reflections between stacked
- * filters, polarization, flare/ghosting and wavelength-changing behavior are
- * outside this contract.
+ * passive transmission in front of the lens. It does not cover reflections
+ * between stacked filters, polarization, flare or ghosting, or filters that
+ * change wavelength.
  */
 export function parseFrontOfLensFilterProfile(value) {
-    const record = requireRecord(value, "frontOfLensFilterProfile");
+    const record = requireRecord(value, "frontOfLensFilterProfile", ["schemaVersion", "identityScope", "position", "wavelengthChangingBehaviorModeled", "polarizationModeled", "scientificStatus", "uncertainty", "wavelengthRangeNanometers", "transmission", "filterId", "profileVersion", "wavelengthBasis", "evidence", "limitations"]);
     if (record.schemaVersion !==
-        FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION) {
+        FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION &&
+        record.schemaVersion !==
+            FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('frontOfLensFilterProfile.schemaVersion must be "' +
             FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION +
+            '" or "' +
+            FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION +
             '".');
     }
+    const schemaVersion = record.schemaVersion;
     if (record.identityScope !==
         "photivra-generic-unbranded") {
         throw new InvalidConfigurationError('frontOfLensFilterProfile.identityScope must be "photivra-generic-unbranded".');
@@ -232,10 +287,11 @@ export function parseFrontOfLensFilterProfile(value) {
         "front-of-lens") {
         throw new InvalidConfigurationError('frontOfLensFilterProfile.position must be "front-of-lens".');
     }
-    if (record.polarizationModeled !==
+    if (record.wavelengthChangingBehaviorModeled !==
         false ||
-        record.wavelengthChangingBehaviorModeled !==
-            false) {
+        (schemaVersion ===
+            FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION &&
+            record.polarizationModeled !== false)) {
         throw new InvalidConfigurationError("frontOfLensFilterProfile must explicitly keep polarization and wavelength-changing behavior unmodeled in schema 0.1.0.");
     }
     const status = parseScientificStatus(record.scientificStatus, "frontOfLensFilterProfile.scientificStatus");
@@ -246,7 +302,12 @@ export function parseFrontOfLensFilterProfile(value) {
         throw new InvalidConfigurationError("A calibrated filter profile requires quantified relative uncertainty.");
     }
     const range = parseRange(record.wavelengthRangeNanometers, "frontOfLensFilterProfile.wavelengthRangeNanometers");
-    const transmission = parseTransmission(record.transmission, "frontOfLensFilterProfile.transmission");
+    const transmission = parseTransmission(record.transmission, "frontOfLensFilterProfile.transmission", schemaVersion ===
+        FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION);
+    const polarizationModeled = transmission.kind === "linear-polarizer";
+    if (record.polarizationModeled !== polarizationModeled) {
+        throw new InvalidConfigurationError("frontOfLensFilterProfile.polarizationModeled must be true exactly for a linear-polarizer transmission.");
+    }
     if (transmission.kind ===
         "spectral-transmission") {
         const samples = transmission.samples.value;
@@ -259,7 +320,7 @@ export function parseFrontOfLensFilterProfile(value) {
         }
     }
     return {
-        schemaVersion: FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION,
+        schemaVersion,
         filterId: requireNonEmptyString(record.filterId, "frontOfLensFilterProfile.filterId"),
         profileVersion: requireNonEmptyString(record.profileVersion, "frontOfLensFilterProfile.profileVersion"),
         identityScope: "photivra-generic-unbranded",
@@ -269,7 +330,7 @@ export function parseFrontOfLensFilterProfile(value) {
         wavelengthRangeNanometers: range,
         transmission,
         uncertainty,
-        polarizationModeled: false,
+        polarizationModeled,
         wavelengthChangingBehaviorModeled: false,
         evidence: parseEvidenceList(record.evidence, "frontOfLensFilterProfile.evidence"),
         limitations: parseLimitations(record.limitations, "frontOfLensFilterProfile.limitations")
@@ -329,13 +390,80 @@ function transmissionEvidence(transmission) {
             .opticalDensityBase10
             .evidence;
     }
+    if (transmission.kind === "linear-polarizer") {
+        return [
+            ...transmission.principalTransmittance.evidence,
+            ...transmission.extinctionRatio.evidence
+        ];
+    }
     return transmission
         .samples.evidence;
 }
+const UNPOLARIZED = Object.freeze({
+    degreeOfLinearPolarization: 0,
+    angleDegrees: 0
+});
+function parsePolarizationState(value, path) {
+    if (value === undefined) {
+        return { ...UNPOLARIZED };
+    }
+    if (typeof value !== "object" || value === null) {
+        throw new InvalidConfigurationError(path + " must be an object.");
+    }
+    const degree = value.degreeOfLinearPolarization;
+    const angle = value.angleDegrees;
+    if (typeof degree !== "number" ||
+        !Number.isFinite(degree) ||
+        degree < 0 ||
+        degree > 1) {
+        throw new InvalidScientificInputError(path + ".degreeOfLinearPolarization must lie in [0, 1].");
+    }
+    if (typeof angle !== "number" || !Number.isFinite(angle)) {
+        throw new InvalidScientificInputError(path + ".angleDegrees must be finite.");
+    }
+    return { degreeOfLinearPolarization: degree, angleDegrees: angle };
+}
+function stokesFromState(state) {
+    const twice = (2 * state.angleDegrees * Math.PI) / 180;
+    return {
+        s0: 1,
+        s1: state.degreeOfLinearPolarization * Math.cos(twice),
+        s2: state.degreeOfLinearPolarization * Math.sin(twice)
+    };
+}
+function stateFromStokes(stokes) {
+    const polarized = Math.hypot(stokes.s1, stokes.s2);
+    const degree = Math.min(1, polarized / stokes.s0);
+    if (degree === 0) {
+        return { ...UNPOLARIZED };
+    }
+    let angle = (Math.atan2(stokes.s2, stokes.s1) * 90) / Math.PI;
+    if (angle < 0)
+        angle += 180;
+    return { degreeOfLinearPolarization: degree, angleDegrees: angle };
+}
 /**
- * Resolves one passive filter at one wavelength.
+ * Mueller matrix of a linear diattenuator (principal intensity transmittances k1 along the axis
+ * and k2 across it, axis at theta) applied to a linear Stokes vector.
  */
-export function resolveFrontOfLensFilterTransmission(input) {
+function applyLinearPolarizer(stokes, k1, k2, axisDegrees) {
+    const twice = (2 * axisDegrees * Math.PI) / 180;
+    const c = Math.cos(twice);
+    const sn = Math.sin(twice);
+    const sum = (k1 + k2) / 2;
+    const difference = (k1 - k2) / 2;
+    const geometric = Math.sqrt(k1 * k2);
+    return {
+        s0: sum * stokes.s0 + difference * (c * stokes.s1 + sn * stokes.s2),
+        s1: difference * c * stokes.s0 +
+            (sum * c * c + geometric * sn * sn) * stokes.s1 +
+            (sum - geometric) * c * sn * stokes.s2,
+        s2: difference * sn * stokes.s0 +
+            (sum - geometric) * c * sn * stokes.s1 +
+            (sum * sn * sn + geometric * c * c) * stokes.s2
+    };
+}
+function resolveComponent(input, incoming) {
     const profile = parseFrontOfLensFilterProfile(input.profile);
     const wavelength = scientificWavelength(input.wavelengthNanometers);
     if (input.wavelengthBasis !==
@@ -353,24 +481,39 @@ export function resolveFrontOfLensFilterTransmission(input) {
         throw new InvalidScientificInputError("Requested wavelength lies outside the filter applicability range.");
     }
     let factor;
+    let outgoing;
     const transmission = profile.transmission;
     if (transmission.kind ===
-        "neutral-linear-transmission") {
-        factor =
-            transmission
-                .linearTransmissionFactor
-                .value;
-    }
-    else if (transmission.kind ===
-        "neutral-optical-density") {
-        factor =
-            Math.pow(10, -transmission
-                .opticalDensityBase10
-                .value);
+        "linear-polarizer") {
+        const k1 = transmission.principalTransmittance.value;
+        const k2 = k1 / transmission.extinctionRatio.value;
+        outgoing = applyLinearPolarizer(incoming, k1, k2, transmission.transmissionAxisDegrees);
+        factor = outgoing.s0 / incoming.s0;
     }
     else {
-        factor =
-            interpolateSpectralTransmission(transmission.samples.value, wavelength);
+        if (transmission.kind ===
+            "neutral-linear-transmission") {
+            factor =
+                transmission
+                    .linearTransmissionFactor
+                    .value;
+        }
+        else if (transmission.kind ===
+            "neutral-optical-density") {
+            factor =
+                Math.pow(10, -transmission
+                    .opticalDensityBase10
+                    .value);
+        }
+        else {
+            factor =
+                interpolateSpectralTransmission(transmission.samples.value, wavelength);
+        }
+        outgoing = {
+            s0: incoming.s0 * factor,
+            s1: incoming.s1 * factor,
+            s2: incoming.s2 * factor
+        };
     }
     if (!Number.isFinite(factor) ||
         factor <= 0 ||
@@ -383,56 +526,77 @@ export function resolveFrontOfLensFilterTransmission(input) {
         !Number.isFinite(opticalDensityBase10)) {
         throw new InvalidScientificInputError("Resolved filter attenuation diagnostics must remain finite.");
     }
+    const polarizer = transmission.kind === "linear-polarizer";
     return {
-        schemaVersion: FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION,
-        filterId: profile.filterId,
-        profileVersion: profile.profileVersion,
-        identityScope: "photivra-generic-unbranded",
-        position: "front-of-lens",
-        scientificStatus: profile.scientificStatus,
-        wavelengthNanometers: wavelength,
-        wavelengthBasis: input.wavelengthBasis,
-        transmissionKind: transmission.kind,
-        linearTransmissionFactor: factor,
-        attenuationStops,
-        opticalDensityBase10,
-        polarizationModeled: false,
-        wavelengthChangingBehaviorModeled: false,
-        lensTransmissionIncluded: false,
-        sensorOpticalStackIncluded: false,
-        fieldThroughputIncluded: false,
-        uncertainty: profile.uncertainty,
-        evidence: [
-            ...profile.evidence,
-            ...transmissionEvidence(transmission)
-        ],
-        limitations: [
-            ...profile.limitations,
-            "Front-of-lens transmission is independent of lens aperture geometry, focus/DOF, diffraction and sensor optical-stack response.",
-            "Polarization and inter-filter reflections/flare/ghosting are not modeled."
-        ]
+        outgoing,
+        resolved: {
+            schemaVersion: profile.schemaVersion,
+            filterId: profile.filterId,
+            profileVersion: profile.profileVersion,
+            identityScope: "photivra-generic-unbranded",
+            position: "front-of-lens",
+            scientificStatus: profile.scientificStatus,
+            wavelengthNanometers: wavelength,
+            wavelengthBasis: input.wavelengthBasis,
+            transmissionKind: transmission.kind,
+            linearTransmissionFactor: factor,
+            attenuationStops,
+            opticalDensityBase10,
+            polarizationModeled: polarizer,
+            incidentPolarization: stateFromStokes(incoming),
+            transmittedPolarization: stateFromStokes(outgoing),
+            wavelengthChangingBehaviorModeled: false,
+            lensTransmissionIncluded: false,
+            sensorOpticalStackIncluded: false,
+            fieldThroughputIncluded: false,
+            uncertainty: profile.uncertainty,
+            evidence: [
+                ...profile.evidence,
+                ...transmissionEvidence(transmission)
+            ],
+            limitations: [
+                ...profile.limitations,
+                "Front-of-lens transmission is independent of lens aperture geometry, focus/DOF, diffraction and sensor optical-stack response.",
+                polarizer
+                    ? "Linear diattenuator on linear Stokes parameters; circular polarization, retardance, angle-of-incidence dependence and inter-filter reflections/flare/ghosting are not modeled."
+                    : "Polarization and inter-filter reflections/flare/ghosting are not modeled."
+            ]
+        }
     };
 }
 /**
- * Composes multiple passive front-of-lens filters multiplicatively at one
- * wavelength while preserving each component's identity.
+ * Resolves one passive filter at one wavelength. Non-polarizing filters scale all Stokes
+ * components equally, so their transmission does not depend on the incident polarization.
+ */
+export function resolveFrontOfLensFilterTransmission(input) {
+    requireInputKeys(input, "resolveFrontOfLensFilterTransmission", ["profile", "wavelengthNanometers", "wavelengthBasis", "incidentPolarization"]);
+    return resolveComponent(input, stokesFromState(parsePolarizationState(input.incidentPolarization, "incidentPolarization"))).resolved;
+}
+/**
+ * Combines several passive front-of-lens filters at one wavelength, in light-path order, and keeps
+ * each filter's identity. Without a polarizer the result is the product of the transmissions. With
+ * one, linear Stokes parameters pass through the Mueller matrices in order.
  */
 export function composeFrontOfLensFilterTransmission(input) {
+    requireInputKeys(input, "composeFrontOfLensFilterTransmission", ["filters", "wavelengthNanometers", "wavelengthBasis", "incidentPolarization"]);
     if (!Array.isArray(input.filters) ||
         input.filters.length === 0) {
-        throw new InvalidScientificInputError("filters must be a non-empty array.");
-    }
-    const components = input.filters.map((profile) => resolveFrontOfLensFilterTransmission({
-        profile,
-        wavelengthNanometers: input.wavelengthNanometers,
-        wavelengthBasis: input.wavelengthBasis
-    }));
-    let combined = 1;
-    for (const component of components) {
-        combined *=
-            component
-                .linearTransmissionFactor;
-    }
+        throw new InvalidConfigurationError("filters must be a non-empty array.");
+    }
+    const incidentPolarization = parsePolarizationState(input.incidentPolarization, "incidentPolarization");
+    const incident = stokesFromState(incidentPolarization);
+    let stokes = incident;
+    const components = [];
+    for (const profile of input.filters) {
+        const component = resolveComponent({
+            profile,
+            wavelengthNanometers: input.wavelengthNanometers,
+            wavelengthBasis: input.wavelengthBasis
+        }, stokes);
+        components.push(component.resolved);
+        stokes = component.outgoing;
+    }
+    const combined = stokes.s0 / incident.s0;
     if (!Number.isFinite(combined) ||
         combined <= 0 ||
         combined > 1) {
@@ -442,8 +606,11 @@ export function composeFrontOfLensFilterTransmission(input) {
     if (!Number.isFinite(stops)) {
         throw new InvalidScientificInputError("Combined filter attenuation must remain finite.");
     }
+    const polarizationModeled = components.some((component) => component.polarizationModeled);
     return {
-        schemaVersion: FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION,
+        schemaVersion: polarizationModeled
+            ? FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION
+            : FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION,
         wavelengthNanometers: scientificWavelength(input.wavelengthNanometers),
         wavelengthBasis: input.wavelengthBasis,
         appliedFilterCount: components.length,
@@ -457,8 +624,12 @@ export function composeFrontOfLensFilterTransmission(input) {
             : "calibrated",
         uncertaintyPropagation: "not-propagated",
         uncertaintyLimitation: "Component filter uncertainties are preserved individually; aggregate numeric uncertainty is not propagated because independence/correlation is not assumed.",
-        compositionModel: "independent-multiplicative-unpolarized-transmission-no-inter-filter-reflections",
-        polarizationModeled: false,
+        compositionModel: polarizationModeled
+            ? "ordered-linear-stokes-mueller-no-inter-filter-reflections"
+            : "independent-multiplicative-unpolarized-transmission-no-inter-filter-reflections",
+        polarizationModeled,
+        incidentPolarization,
+        transmittedPolarization: stateFromStokes(stokes),
         wavelengthChangingBehaviorModeled: false,
         lensTransmissionIncluded: false,
         sensorOpticalStackIncluded: false,