@photivra/engine 1.5.0 → 2.1.0

package/dist/optics/focus-state.js

@@ -1,33 +1,38 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Parses an explicit focus-plane state from an untrusted JSON boundary. Missing/unknown focus is
- * rejected rather than being interpreted as infinity.
- * Calculates the ideal image-plane distance for an explicit focus state. Finite focus delegates to the
- * existing Gaussian thin-lens calculation, so its numerical result and provenance are unchanged.
- * Infinity focus resolves exactly to the nominal focal length with zero limiting magnification.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Explicit focus state: a finite focus distance, or infinity.
+ *
+ * The parser reads the state from untrusted JSON. Missing or unknown focus is rejected; it is never
+ * read as infinity.
+ *
+ * The image-distance function uses the existing Gaussian thin-lens calculation for finite focus, so
+ * its numbers and provenance are unchanged. Infinity focus gives exactly the nominal focal length,
+ * with a limiting magnification of zero.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { calculatedResult } from "../core/calculation-result.js";
 import { InvalidConfigurationError } from "../core/configuration-error.js";
 import { requirePositiveFinite } from "../core/validation.js";
 import { calculateThinLensImageDistance } from "./thin-lens.js";
-function requireRecord(value, path) {
+import { requireInputKeys, rejectUnknownFields } from "../core/record-validation.js";
+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;
 }
 /**
- * Parses an explicit focus-plane state from an untrusted JSON boundary.
+ * Parses an explicit focus-plane state from untrusted JSON.
  *
- * Missing/unknown focus is rejected rather than being interpreted as infinity.
+ * Missing or unknown focus is rejected. It is never read as infinity.
  */
 export function parseFocusPlane(value) {
-    const record = requireRecord(value, "focusPlane");
+    const record = requireRecord(value, "focusPlane", ["kind", "distanceM"]);
     if (record.kind === "infinity") {
         if (record.distanceM !== undefined) {
             throw new InvalidConfigurationError("focusPlane infinity state must not include distanceM.");
@@ -52,11 +57,12 @@ export function parseFocusPlane(value) {
 /**
  * Calculates the ideal image-plane distance for an explicit focus state.
  *
- * Finite focus delegates to the existing Gaussian thin-lens calculation, so
- * its numerical result and provenance are unchanged. Infinity focus resolves
- * exactly to the nominal focal length with zero limiting magnification.
+ * Finite focus uses the existing Gaussian thin-lens calculation, so its
+ * numbers and provenance are unchanged. Infinity focus gives exactly the
+ * nominal focal length, with a limiting magnification of zero.
  */
 export function calculateFocusPlaneImageDistance(input) {
+    requireInputKeys(input, "calculateFocusPlaneImageDistance", ["focalLengthMm", "focus"]);
     requirePositiveFinite("focalLengthMm", input.focalLengthMm);
     const focus = parseFocusPlane(input.focus);
     if (focus.kind === "finite") {

package/dist/optics/focus-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"focus-state.js","sourceRoot":"","sources":["../../src/optics/focus-state.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;GASG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACL,8BAA8B,EAE/B,MAAM,gBAAgB,CAAC;AA0BxB,SAAS,aAAa,CAAC,KAAc,EAAE,IAAY;IACjD,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EACpB,CAAC;QACD,MAAM,IAAI,yBAAyB,CACjC,IAAI,GAAG,qBAAqB,CAC7B,CAAC;IACJ,CAAC;IACD,OAAO,KAAgC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IAElD,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACnC,MAAM,IAAI,yBAAyB,CACjC,uDAAuD,CACxD,CAAC;QACJ,CAAC;QACD,OAAO;YACL,IAAI,EAAE,UAAU;SACjB,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IACE,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;YACpC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;YAClC,MAAM,CAAC,SAAS,IAAI,CAAC,EACrB,CAAC;YACD,MAAM,IAAI,yBAAyB,CACjC,iEAAiE,CAClE,CAAC;QACJ,CAAC;QACD,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,yBAAyB,CACjC,iDAAiD,CAClD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC,CAC9C,KAA4C;IAE5C,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAE5D,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAE3C,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,8BAA8B,CAAC;YACpC,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,eAAe,EAAE,KAAK,CAAC,SAAS;SACjC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,gBAAgB,CACrB;QACE,eAAe,EAAE,KAAK,CAAC,aAAa;QACpC,aAAa,EAAE,CAAC;QAChB,uBAAuB,EAAE,CAAC;KAC3B,EACD,qCAAqC,EACrC,OAAO,EACP;QACE,6CAA6C;QAC7C,gEAAgE;QAChE,yFAAyF;KAC1F,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"focus-state.js","sourceRoot":"","sources":["../../src/optics/focus-state.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACL,8BAA8B,EAE/B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAyBrF,SAAS,aAAa,CACpB,KAAc,EACd,IAAY,EACZ,WAAqC;IAErC,IACE,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EACpB,CAAC;QACD,MAAM,IAAI,yBAAyB,CACjC,IAAI,GAAG,qBAAqB,CAC7B,CAAC;IACJ,CAAC;IACD,IAAI,WAAW,KAAK,IAAI;QAAE,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;IACxE,OAAO,KAAgC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAEzE,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YACnC,MAAM,IAAI,yBAAyB,CACjC,uDAAuD,CACxD,CAAC;QACJ,CAAC;QACD,OAAO;YACL,IAAI,EAAE,UAAU;SACjB,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IACE,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;YACpC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;YAClC,MAAM,CAAC,SAAS,IAAI,CAAC,EACrB,CAAC;YACD,MAAM,IAAI,yBAAyB,CACjC,iEAAiE,CAClE,CAAC;QACJ,CAAC;QACD,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,yBAAyB,CACjC,iDAAiD,CAClD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC,CAC9C,KAA4C;IAE5C,gBAAgB,CAAC,KAAK,EAAE,kCAAkC,EAAE,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC;IACxF,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAE5D,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAE3C,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,8BAA8B,CAAC;YACpC,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,eAAe,EAAE,KAAK,CAAC,SAAS;SACjC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,gBAAgB,CACrB;QACE,eAAe,EAAE,KAAK,CAAC,aAAa;QACpC,aAAa,EAAE,CAAC;QAChB,uBAAuB,EAAE,CAAC;KAC3B,EACD,qCAAqC,EACrC,OAAO,EACP;QACE,6CAA6C;QAC7C,gEAAgE;QAChE,yFAAyF;KAC1F,CACF,CAAC;AACJ,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Explicit focus state: a finite focus distance, or infinity.\n *\n * The parser reads the state from untrusted JSON. Missing or unknown focus is rejected; it is never\n * read as infinity.\n *\n * The image-distance function uses the existing Gaussian thin-lens calculation for finite focus, so\n * its numbers and provenance are unchanged. Infinity focus gives exactly the nominal focal length,\n * with a limiting magnification of zero.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { requirePositiveFinite } from \"../core/validation.js\";\nimport {\n  calculateThinLensImageDistance,\n  type ThinLensImageDistance\n} from \"./thin-lens.js\";\nimport { requireInputKeys, rejectUnknownFields } from \"../core/record-validation.js\";\n\n/**\n * Explicit ideal focus-plane state.\n *\n * A finite distance is measured along the camera's optical axis, from the\n * ideal lens principal plane to the object plane. Infinity is a named state.\n * It is never stored as JavaScript Infinity or as a made-up large distance.\n */\nexport type FocusPlane =\n  | {\n      kind: \"finite\";\n      distanceM: number;\n    }\n  | {\n      kind: \"infinity\";\n    };\n\nexport interface CalculateFocusPlaneImageDistanceInput {\n  /** Lens focal length in millimetres. */\n  focalLengthMm: number;\n  /** Explicit finite or infinity focus-plane state. */\n  focus: FocusPlane;\n}\n\nfunction requireRecord(\n  value: unknown,\n  path: string,\n  allowedKeys: readonly string[] | null\n): Record<string, unknown> {\n  if (\n    typeof value !== \"object\" ||\n    value === null ||\n    Array.isArray(value)\n  ) {\n    throw new InvalidConfigurationError(\n      path + \" must be an object.\"\n    );\n  }\n  if (allowedKeys !== null) rejectUnknownFields(value, allowedKeys, path);\n  return value as Record<string, unknown>;\n}\n\n/**\n * Parses an explicit focus-plane state from untrusted JSON.\n *\n * Missing or unknown focus is rejected. It is never read as infinity.\n */\nexport function parseFocusPlane(value: unknown): FocusPlane {\n  const record = requireRecord(value, \"focusPlane\", [\"kind\", \"distanceM\"]);\n\n  if (record.kind === \"infinity\") {\n    if (record.distanceM !== undefined) {\n      throw new InvalidConfigurationError(\n        \"focusPlane infinity state must not include distanceM.\"\n      );\n    }\n    return {\n      kind: \"infinity\"\n    };\n  }\n\n  if (record.kind === \"finite\") {\n    if (\n      typeof record.distanceM !== \"number\" ||\n      !Number.isFinite(record.distanceM) ||\n      record.distanceM <= 0\n    ) {\n      throw new InvalidConfigurationError(\n        \"focusPlane.distanceM must be a finite number greater than zero.\"\n      );\n    }\n    return {\n      kind: \"finite\",\n      distanceM: record.distanceM\n    };\n  }\n\n  throw new InvalidConfigurationError(\n    'focusPlane.kind must be \"finite\" or \"infinity\".'\n  );\n}\n\n/**\n * Calculates the ideal image-plane distance for an explicit focus state.\n *\n * Finite focus uses the existing Gaussian thin-lens calculation, so its\n * numbers and provenance are unchanged. Infinity focus gives exactly the\n * nominal focal length, with a limiting magnification of zero.\n */\nexport function calculateFocusPlaneImageDistance(\n  input: CalculateFocusPlaneImageDistanceInput\n): CalculationResult<ThinLensImageDistance> {\n  requireInputKeys(input, \"calculateFocusPlaneImageDistance\", [\"focalLengthMm\", \"focus\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n\n  const focus = parseFocusPlane(input.focus);\n\n  if (focus.kind === \"finite\") {\n    return calculateThinLensImageDistance({\n      focalLengthMm: input.focalLengthMm,\n      objectDistanceM: focus.distanceM\n    });\n  }\n\n  return calculatedResult(\n    {\n      imageDistanceMm: input.focalLengthMm,\n      magnification: 0,\n      infinityProjectionScale: 1\n    },\n    \"ideal-infinity-focus-image-distance\",\n    \"1.0.0\",\n    [\n      \"Paraxial ideal-lens infinity-focus boundary\",\n      \"Image distance equals nominal focal length at optical infinity\",\n      \"Infinity is represented semantically rather than by a non-finite or fabricated distance\"\n    ]\n  );\n}\n"]}

package/dist/optics/front-of-lens-filter.d.ts

@@ -1,6 +1,16 @@
 import { type EvidenceBackedFact, type EvidenceProvenance } from "../core/evidence-provenance.js";
 import { type SpectralWavelengthBasis } from "../core/spectral.js";
 export declare const FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION: "0.1.0";
+/** Schema that also allows the `linear-polarizer` transmission kind. */
+export declare const FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION: "0.2.0";
+export type FrontOfLensFilterProfileSchemaVersion = typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION | typeof FRONT_OF_LENS_POLARIZER_PROFILE_SCHEMA_VERSION;
+/** Partially linearly polarized light: degree P in [0, 1] and polarization angle psi. */
+export interface LinearPolarizationState {
+    /** Degree of linear polarization P in [0, 1]; 0 is unpolarized. */
+    degreeOfLinearPolarization: number;
+    /** Electric-field polarization angle, degrees counter-clockwise from image +X. */
+    angleDegrees: number;
+}
 export type FrontOfLensFilterScientificStatus = "calibrated" | "approximation";
 export type FrontOfLensFilterUncertainty = {
     kind: "relative";
@@ -23,9 +33,18 @@ export type FrontOfLensFilterTransmissionModel = {
 } | {
     kind: "spectral-transmission";
     samples: EvidenceBackedFact<readonly FrontOfLensFilterSpectralSample[]>;
+} | {
+    /** Schema 0.2.0 only. Neutral (wavelength-independent) within the declared range. */
+    kind: "linear-polarizer";
+    /** k1: intensity transmittance for light polarized along the transmission axis, (0, 1]. */
+    principalTransmittance: EvidenceBackedFact<number>;
+    /** k1 / k2. Finite and >= 1. Use a large finite ratio for a near-ideal polarizer. */
+    extinctionRatio: EvidenceBackedFact<number>;
+    /** Transmission-axis angle as mounted, degrees counter-clockwise from image +X. */
+    transmissionAxisDegrees: number;
 };
 export interface FrontOfLensFilterProfile {
-    schemaVersion: typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+    schemaVersion: FrontOfLensFilterProfileSchemaVersion;
     filterId: string;
     profileVersion: string;
     identityScope: "photivra-generic-unbranded";
@@ -38,7 +57,8 @@ export interface FrontOfLensFilterProfile {
     };
     transmission: FrontOfLensFilterTransmissionModel;
     uncertainty: FrontOfLensFilterUncertainty;
-    polarizationModeled: false;
+    /** True exactly when the transmission kind is `linear-polarizer` (schema 0.2.0). */
+    polarizationModeled: boolean;
     wavelengthChangingBehaviorModeled: false;
     evidence: readonly EvidenceProvenance[];
     limitations: readonly string[];
@@ -47,9 +67,11 @@ export interface ResolveFrontOfLensFilterTransmissionInput {
     profile: FrontOfLensFilterProfile;
     wavelengthNanometers: number;
     wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+    /** Incident polarization; omitted means unpolarized. */
+    incidentPolarization?: LinearPolarizationState;
 }
 export interface ResolvedFrontOfLensFilterTransmission {
-    schemaVersion: typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+    schemaVersion: FrontOfLensFilterProfileSchemaVersion;
     filterId: string;
     profileVersion: string;
     identityScope: "photivra-generic-unbranded";
@@ -58,10 +80,13 @@ export interface ResolvedFrontOfLensFilterTransmission {
     wavelengthNanometers: number;
     wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
     transmissionKind: FrontOfLensFilterTransmissionModel["kind"];
+    /** Intensity transmittance for the declared incident polarization. */
     linearTransmissionFactor: number;
     attenuationStops: number;
     opticalDensityBase10: number;
-    polarizationModeled: false;
+    polarizationModeled: boolean;
+    incidentPolarization: LinearPolarizationState;
+    transmittedPolarization: LinearPolarizationState;
     wavelengthChangingBehaviorModeled: false;
     lensTransmissionIncluded: false;
     sensorOpticalStackIncluded: false;
@@ -71,12 +96,15 @@ export interface ResolvedFrontOfLensFilterTransmission {
     limitations: readonly string[];
 }
 export interface ComposeFrontOfLensFilterTransmissionInput {
+    /** Filters in light-path order (scene side first). */
     filters: readonly FrontOfLensFilterProfile[];
     wavelengthNanometers: number;
     wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+    /** Incident scene polarization; omitted means unpolarized. */
+    incidentPolarization?: LinearPolarizationState;
 }
 export interface ComposedFrontOfLensFilterTransmission {
-    schemaVersion: typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+    schemaVersion: FrontOfLensFilterProfileSchemaVersion;
     wavelengthNanometers: number;
     wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
     appliedFilterCount: number;
@@ -86,8 +114,10 @@ export interface ComposedFrontOfLensFilterTransmission {
     scientificStatus: FrontOfLensFilterScientificStatus;
     uncertaintyPropagation: "not-propagated";
     uncertaintyLimitation: string;
-    compositionModel: "independent-multiplicative-unpolarized-transmission-no-inter-filter-reflections";
-    polarizationModeled: false;
+    compositionModel: "independent-multiplicative-unpolarized-transmission-no-inter-filter-reflections" | "ordered-linear-stokes-mueller-no-inter-filter-reflections";
+    polarizationModeled: boolean;
+    incidentPolarization: LinearPolarizationState;
+    transmittedPolarization: LinearPolarizationState;
     wavelengthChangingBehaviorModeled: false;
     lensTransmissionIncluded: false;
     sensorOpticalStackIncluded: false;
@@ -97,18 +127,19 @@ export interface ComposedFrontOfLensFilterTransmission {
  * 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 declare function parseFrontOfLensFilterProfile(value: unknown): FrontOfLensFilterProfile;
 /**
- * Resolves one passive filter at one wavelength.
+ * 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 declare function resolveFrontOfLensFilterTransmission(input: ResolveFrontOfLensFilterTransmissionInput): ResolvedFrontOfLensFilterTransmission;
 /**
- * Composes multiple passive front-of-lens filters multiplicatively at one
- * wavelength while preserving each component's identity.
+ * 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 declare function composeFrontOfLensFilterTransmission(input: ComposeFrontOfLensFilterTransmissionInput): ComposedFrontOfLensFilterTransmission;
-//# sourceMappingURL=front-of-lens-filter.d.ts.map