@photivra/engine 1.5.0 → 2.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"focus-breathing.js","sourceRoot":"","sources":["../../src/optics/focus-breathing.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,mBAAmB,EAEpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,8BAA8B,EAAE,MAAM,gBAAgB,CAAC;AAyDhE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iCAAiC,CAC/C,KAA6C;IAE7C,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9D,qBAAqB,CACnB,0BAA0B,EAC1B,KAAK,CAAC,wBAAwB,CAC/B,CAAC;IAEF,MAAM,QAAQ,GAAG,8BAA8B,CAAC;QAC9C,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,eAAe,EAAE,KAAK,CAAC,cAAc;KACtC,CAAC,CAAC;IACH,MAAM,yBAAyB,GAAG,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC;IACjE,MAAM,6BAA6B,GACjC,yBAAyB,GAAG,KAAK,CAAC,wBAAwB,CAAC;IAC7D,MAAM,gBAAgB,GAAG,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC;IAErD,OAAO,mBAAmB,CACxB;QACE,qBAAqB,EAAE,KAAK,CAAC,aAAa;QAC1C,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,yBAAyB;QACzB,6BAA6B;QAC7B,wBAAwB,EAAE,KAAK,CAAC,wBAAwB;QACxD,kBAAkB,EAAE,QAAQ,CAAC,KAAK,CAAC,aAAa;QAChD,sBAAsB,EACpB,6BAA6B,GAAG,gBAAgB;KACnD,EACD,2CAA2C,EAC3C,OAAO,EACP;QACE,gGAAgG;QAChG,+FAA+F;QAC/F,iEAAiE;QACjE,2DAA2D;QAC3D,2JAA2J;KAC5J,CACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kCAAkC,CAChD,KAA8C;IAE9C,qBAAqB,CAAC,mBAAmB,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;IAEpE,MAAM,UAAU,GAAG,iCAAiC,CAAC,KAAK,CAAC,CAAC;IAC5D,MAAM,YAAY,GAChB,CAAC;QACD,IAAI,CAAC,IAAI,CACP,KAAK,CAAC,iBAAiB;YACrB,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,yBAAyB,CAAC,CACnD,CAAC;IACJ,MAAM,gBAAgB,GACpB,CAAC;QACD,IAAI,CAAC,IAAI,CACP,KAAK,CAAC,iBAAiB;YACrB,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,6BAA6B,CAAC,CACvD,CAAC;IACJ,MAAM,YAAY,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;IACpD,MAAM,gBAAgB,GAAG,CAAC,gBAAgB,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;IAE5D,OAAO,mBAAmB,CACxB;QACE,qBAAqB,EAAE,KAAK,CAAC,aAAa;QAC1C,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,wBAAwB,EAAE,KAAK,CAAC,wBAAwB;QACxD,yBAAyB,EACvB,UAAU,CAAC,KAAK,CAAC,yBAAyB;QAC5C,6BAA6B,EAC3B,UAAU,CAAC,KAAK,CAAC,6BAA6B;QAChD,YAAY;QACZ,gBAAgB;QAChB,YAAY,EAAE,gBAAgB,GAAG,YAAY;KAC9C,EACD,8CAA8C,EAC9C,OAAO,EACP;QACE,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,WAAW,IAAI,EAAE,CAAC;QAC5C,sHAAsH;KACvH,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"focus-breathing.js","sourceRoot":"","sources":["../../src/optics/focus-breathing.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Focus breathing: the change in framing (magnification) as a lens focuses.\n *\n * The declared-scale model applies a caller-supplied projection scale to the ideal Gaussian thin-lens\n * projection for one focus state. Photivra does not guess the scale from focal length, focus\n * distance, lens identity or marketing data. A scale of 1 keeps the thin-lens projection exactly.\n * This is a generic approximation of how projection and magnification change with focus. It is not a\n * calibrated real-lens model. The physical focal length is never changed and stays authoritative.\n *\n * The field-of-view function gives the one-axis field of view (FOV) under this model, and the ideal\n * thin-lens FOV for comparison. A breathingProjectionScale of 1 reproduces the focus-aware thin-lens\n * FOV exactly.\n *\n * The geometric model derives breathing from ideal focusing geometry instead of a declared scale.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  approximationResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport { calculateThinLensImageDistance } from \"./thin-lens.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport interface CalculateFocusBreathingProjectionInput {\n  /** Physical lens focal length in millimetres. This value is never rewritten. */\n  focalLengthMm: number;\n  /** Selected focus distance in metres. */\n  focusDistanceM: number;\n  /**\n   * Caller-declared projection scale for this focus state, relative to the\n   * ideal thin-lens image distance.\n   *\n   * 1 means no breathing beyond the thin-lens model. Values above 1 narrow the\n   * framing (more magnification). Values below 1 widen it (less\n   * magnification).\n   */\n  breathingProjectionScale: number;\n}\n\nexport interface FocusBreathingProjection {\n  /** Authoritative physical focal length supplied by the caller. */\n  physicalFocalLengthMm: number;\n  focusDistanceM: number;\n  /** Ideal Gaussian thin-lens image distance before breathing adjustment. */\n  idealProjectionDistanceMm: number;\n  /**\n   * Effective projection distance used by the generic breathing model.\n   *\n   * This is a projection (magnification) parameter. It does not replace the\n   * physical focal length.\n   */\n  effectiveProjectionDistanceMm: number;\n  /** Caller-declared scale relative to ideal thin-lens projection. */\n  breathingProjectionScale: number;\n  /** Ideal Gaussian thin-lens magnification at the selected focus distance. */\n  idealMagnification: number;\n  /** Generic breathing-adjusted magnification. */\n  effectiveMagnification: number;\n}\n\nexport interface CalculateFocusBreathingFieldOfViewInput\n  extends CalculateFocusBreathingProjectionInput {\n  /** Sensor/capture dimension corresponding to the requested FOV, in millimetres. */\n  sensorDimensionMm: number;\n}\n\nexport interface FocusBreathingFieldOfView {\n  physicalFocalLengthMm: number;\n  focusDistanceM: number;\n  sensorDimensionMm: number;\n  breathingProjectionScale: number;\n  idealProjectionDistanceMm: number;\n  effectiveProjectionDistanceMm: number;\n  idealDegrees: number;\n  effectiveDegrees: number;\n  deltaDegrees: number;\n}\n\n/**\n * Applies a caller-declared focus-breathing projection scale to the ideal\n * Gaussian thin-lens projection for one focus state.\n *\n * Photivra does not guess the scale from focal length, focus distance, lens\n * identity or marketing data. A scale of 1 keeps the thin-lens projection\n * exactly.\n *\n * This is a generic approximation of how projection and magnification change\n * with focus. It is not a calibrated real-lens model. The physical focal\n * length is never changed and stays authoritative.\n */\nexport function calculateFocusBreathingProjection(\n  input: CalculateFocusBreathingProjectionInput\n): CalculationResult<FocusBreathingProjection> {\n  requireInputKeys(input, \"calculateFocusBreathingProjection\", [\"focalLengthMm\", \"focusDistanceM\", \"breathingProjectionScale\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"focusDistanceM\", input.focusDistanceM);\n  requirePositiveFinite(\n    \"breathingProjectionScale\",\n    input.breathingProjectionScale\n  );\n\n  const thinLens = calculateThinLensImageDistance({\n    focalLengthMm: input.focalLengthMm,\n    objectDistanceM: input.focusDistanceM\n  });\n  const idealProjectionDistanceMm = thinLens.value.imageDistanceMm;\n  const effectiveProjectionDistanceMm =\n    idealProjectionDistanceMm * input.breathingProjectionScale;\n  const objectDistanceMm = input.focusDistanceM * 1000;\n\n  return approximationResult(\n    {\n      physicalFocalLengthMm: input.focalLengthMm,\n      focusDistanceM: input.focusDistanceM,\n      idealProjectionDistanceMm,\n      effectiveProjectionDistanceMm,\n      breathingProjectionScale: input.breathingProjectionScale,\n      idealMagnification: thinLens.value.magnification,\n      effectiveMagnification:\n        effectiveProjectionDistanceMm / objectDistanceMm\n    },\n    \"declared-scale-focus-breathing-projection\",\n    \"1.0.0\",\n    [\n      \"Base projection is the ideal Gaussian thin-lens image distance for the selected focus distance\",\n      \"The focus-breathing projection scale is supplied explicitly by the caller and is not inferred\",\n      \"One declared scale applies uniformly to the current focus state\",\n      \"Physical focal length remains unchanged and authoritative\",\n      \"The model represents focus-dependent framing/magnification only; distortion, pupil magnification, aberrations, and named-lens calibration are not modeled\"\n    ]\n  );\n}\n\n/**\n * Calculates the one-axis field of view under the declared-scale\n * focus-breathing model, and reports the ideal thin-lens field of view for\n * comparison.\n *\n * A breathingProjectionScale of 1 reproduces the focus-aware thin-lens field\n * of view exactly.\n */\nexport function calculateFocusBreathingFieldOfView(\n  input: CalculateFocusBreathingFieldOfViewInput\n): CalculationResult<FocusBreathingFieldOfView> {\n  requireInputKeys(input, \"calculateFocusBreathingFieldOfView\", [\"sensorDimensionMm\", \"focalLengthMm\", \"focusDistanceM\", \"breathingProjectionScale\"]);\n  requirePositiveFinite(\"sensorDimensionMm\", input.sensorDimensionMm);\n\n  const projection = calculateFocusBreathingProjection({\n    focalLengthMm: input.focalLengthMm,\n    focusDistanceM: input.focusDistanceM,\n    breathingProjectionScale: input.breathingProjectionScale\n  });\n  const idealRadians =\n    2 *\n    Math.atan(\n      input.sensorDimensionMm /\n        (2 * projection.value.idealProjectionDistanceMm)\n    );\n  const effectiveRadians =\n    2 *\n    Math.atan(\n      input.sensorDimensionMm /\n        (2 * projection.value.effectiveProjectionDistanceMm)\n    );\n  const idealDegrees = (idealRadians * 180) / Math.PI;\n  const effectiveDegrees = (effectiveRadians * 180) / Math.PI;\n\n  return approximationResult(\n    {\n      physicalFocalLengthMm: input.focalLengthMm,\n      focusDistanceM: input.focusDistanceM,\n      sensorDimensionMm: input.sensorDimensionMm,\n      breathingProjectionScale: input.breathingProjectionScale,\n      idealProjectionDistanceMm:\n        projection.value.idealProjectionDistanceMm,\n      effectiveProjectionDistanceMm:\n        projection.value.effectiveProjectionDistanceMm,\n      idealDegrees,\n      effectiveDegrees,\n      deltaDegrees: effectiveDegrees - idealDegrees\n    },\n    \"declared-scale-focus-breathing-field-of-view\",\n    \"1.0.0\",\n    [\n      ...(projection.provenance.assumptions ?? []),\n      \"Rectilinear field of view is calculated from the declared sensor/capture dimension and effective projection distance\"\n    ]\n  );\n}\n\n/** Ideal focusing geometry for {@link calculateGeometricFocusBreathing}. */\nexport type GeometricFocusingMethod =\n  | \"unit-focus\"\n  | \"fixed-image-distance-internal-focus\";\n\nexport interface CalculateGeometricFocusBreathingInput {\n  /** Focal length at infinity focus, mm. */\n  focalLengthMm: number;\n  /**\n   * Photographic focus distance measured from the subject plane to the sensor (image) plane, in\n   * metres, as marked on lens distance scales.\n   */\n  subjectToSensorDistanceM: number;\n  /** Sensor/capture dimension along the axis of interest, mm. */\n  sensorDimensionMm: number;\n  focusingMethod: GeometricFocusingMethod;\n  /**\n   * Signed distance between the front and rear principal planes (the \"hiatus\"), in mm. Default 0\n   * (thin lens). The subject-to-sensor distance is u + hiatus + v.\n   */\n  principalPlaneSeparationMm?: number;\n}\n\nexport interface GeometricFocusBreathing {\n  focusingMethod: GeometricFocusingMethod;\n  infinityFocalLengthMm: number;\n  /** Focal length of the focused system (changes only for internal focus), mm. */\n  effectiveFocalLengthMm: number;\n  /** Subject distance from the front principal plane, mm. */\n  objectDistanceMm: number;\n  /** Rear principal plane to sensor distance (projection distance), mm. */\n  imageDistanceMm: number;\n  /** Lateral magnification v / u. */\n  magnification: number;\n  /** v / f_infinity: framing scale relative to infinity focus. */\n  projectionScaleRelativeToInfinity: number;\n  /**\n   * v divided by the ideal thin-lens image distance, at objectDistanceMm, of a lens with the same\n   * infinity focal length. Exactly 1 for unit focus. You can pass it as breathingProjectionScale to\n   * calculateFocusBreathingProjection() with focusDistanceM = objectDistanceMm / 1000.\n   */\n  equivalentBreathingProjectionScale: number;\n  fieldOfViewDegrees: number;\n  infinityFieldOfViewDegrees: number;\n  deltaDegrees: number;\n}\n\n/**\n * Focus breathing derived from ideal focusing geometry, instead of a declared scale.\n *\n * - unit-focus: the whole lens moves. u + v = L - hiatus and 1/u + 1/v = 1/f, so\n *   v = (T - sqrt(T^2 - 4 f T)) / 2, where T = L - hiatus >= 4 f. The field narrows as v grows.\n * - fixed-image-distance-internal-focus: an idealised internal-focus lens keeps the rear principal\n *   plane at v = f_infinity and shortens its focal length to f' = u v / (u + v). The angular field\n *   at the rear nodal point then stays the same, and the magnification is f_infinity / u.\n * Both use paraxial Gaussian optics with the nodal points at the principal planes (unit pupil\n * magnification; Greivenkamp, OPTI-502 course notes, University of Arizona, sec. 3 and 5, free. Also\n * see: Kingslake & Johnson, Lens Design Fundamentals, 2nd ed., ch. 3; Ray, Applied Photographic\n * Optics, 3rd ed., ch. 9 and 14). Real internal-focus lenses also move their pupils and\n * principal planes, so modelling their breathing needs a calibrated profile.\n */\nexport function calculateGeometricFocusBreathing(\n  input: CalculateGeometricFocusBreathingInput\n): CalculationResult<GeometricFocusBreathing> {\n  requireInputKeys(input, \"calculateGeometricFocusBreathing\", [\"focalLengthMm\", \"subjectToSensorDistanceM\", \"sensorDimensionMm\", \"focusingMethod\", \"principalPlaneSeparationMm\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"subjectToSensorDistanceM\", input.subjectToSensorDistanceM);\n  requirePositiveFinite(\"sensorDimensionMm\", input.sensorDimensionMm);\n  const hiatus = input.principalPlaneSeparationMm ?? 0;\n  if (typeof hiatus !== \"number\" || !Number.isFinite(hiatus)) {\n    throw new InvalidScientificInputError(\"principalPlaneSeparationMm must be finite.\");\n  }\n  const f = input.focalLengthMm;\n  const conjugateSum = input.subjectToSensorDistanceM * 1000 - hiatus;\n\n  let imageDistanceMm: number;\n  let objectDistanceMm: number;\n  let effectiveFocalLengthMm: number;\n  if (input.focusingMethod === \"unit-focus\") {\n    if (!(conjugateSum >= 4 * f)) {\n      throw new InvalidScientificInputError(\n        \"Unit focus requires subject-to-sensor distance minus hiatus of at least 4 x focal length (1:1 limit).\"\n      );\n    }\n    // Stable smaller root of v^2 - T v + f T = 0: v = 2 f T / (T + sqrt(T^2 - 4 f T)).\n    imageDistanceMm =\n      (2 * f * conjugateSum) /\n      (conjugateSum + Math.sqrt(conjugateSum * conjugateSum - 4 * f * conjugateSum));\n    objectDistanceMm = conjugateSum - imageDistanceMm;\n    effectiveFocalLengthMm = f;\n  } else if (input.focusingMethod === \"fixed-image-distance-internal-focus\") {\n    imageDistanceMm = f;\n    objectDistanceMm = conjugateSum - f;\n    if (!(objectDistanceMm > f)) {\n      throw new InvalidScientificInputError(\n        \"Internal focus requires the subject to lie more than one focal length in front of the lens.\"\n      );\n    }\n    effectiveFocalLengthMm = (objectDistanceMm * f) / (objectDistanceMm + f);\n  } else {\n    throw new InvalidConfigurationError(\n      \"focusingMethod must be unit-focus or fixed-image-distance-internal-focus.\"\n    );\n  }\n\n  const thinLens = calculateThinLensImageDistance({\n    focalLengthMm: f,\n    objectDistanceM: objectDistanceMm / 1000\n  }).value.imageDistanceMm;\n  const fov = (projection: number): number =>\n    (2 * Math.atan(input.sensorDimensionMm / (2 * projection)) * 180) / Math.PI;\n  const fieldOfViewDegrees = fov(imageDistanceMm);\n  const infinityFieldOfViewDegrees = fov(f);\n\n  return approximationResult(\n    {\n      focusingMethod: input.focusingMethod,\n      infinityFocalLengthMm: f,\n      effectiveFocalLengthMm,\n      objectDistanceMm,\n      imageDistanceMm,\n      magnification: imageDistanceMm / objectDistanceMm,\n      projectionScaleRelativeToInfinity: imageDistanceMm / f,\n      equivalentBreathingProjectionScale:\n        input.focusingMethod === \"unit-focus\" ? 1 : imageDistanceMm / thinLens,\n      fieldOfViewDegrees,\n      infinityFieldOfViewDegrees,\n      deltaDegrees: fieldOfViewDegrees - infinityFieldOfViewDegrees\n    },\n    \"geometric-focus-breathing\",\n    \"1.0.0\",\n    [\n      \"Paraxial Gaussian optics with nodal points at the principal planes (unit pupil magnification)\",\n      input.focusingMethod === \"unit-focus\"\n        ? \"Unit focus: the whole lens moves; focal length is constant\"\n        : \"Idealised internal focus: image distance fixed at the infinity focal length; focal length shortens\",\n      \"Subject-to-sensor distance = object distance + principal-plane separation + image distance\",\n      \"Rectilinear field of view from the rear-principal-plane projection distance; distortion, pupil shifts and named-lens behaviour are not modeled\"\n    ]\n  );\n}\n"]}

package/dist/optics/focus-state.d.ts

@@ -1,22 +1,23 @@
 /**
- * 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 { type CalculationResult } from "../core/calculation-result.js";
 import { type ThinLensImageDistance } from "./thin-lens.js";
 /**
  * Explicit ideal focus-plane state.
  *
- * Finite distance is the longitudinal object-plane distance from the ideal
- * lens principal plane along the camera optical axis. Infinity is a semantic
- * state and is never represented with JavaScript Infinity or a fabricated
- * large distance.
+ * A finite distance is measured along the camera's optical axis, from the
+ * ideal lens principal plane to the object plane. Infinity is a named state.
+ * It is never stored as JavaScript Infinity or as a made-up large distance.
  */
 export type FocusPlane = {
     kind: "finite";
@@ -31,17 +32,16 @@ export interface CalculateFocusPlaneImageDistanceInput {
     focus: FocusPlane;
 }
 /**
- * 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 declare function parseFocusPlane(value: unknown): FocusPlane;
 /**
  * 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 declare function calculateFocusPlaneImageDistance(input: CalculateFocusPlaneImageDistanceInput): CalculationResult<ThinLensImageDistance>;
-//# sourceMappingURL=focus-state.d.ts.map

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