@photivra/engine 1.5.0 → 2.0.0

package/dist/exposure/exposure-duration-control.js

@@ -1,16 +1,21 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Resolves shutter-duration control semantics to a concrete positive elapsed duration before physical
- * exposure integration. Bulb and Time are control behaviors only. Neither implies a shutter mechanism,
- * exposure-boundary topology, tripod, stabilization state, long exposure NR, or temperature model.
- * Binds a resolved duration into the authoritative #12 exposure-window input. The existing shutter
- * mechanism/opening/closing schedules remain untouched. Only the seconds-valued nominal duration is
- * supplied here.
- * @see docs/USAGE.md for equations, coordinate/unit conventions, blockers and support limits.
+ * Shutter-duration control. Turns a control setting (a timed value, Bulb or Time) into a concrete,
+ * positive elapsed duration, before the physical exposure is integrated.
+ *
+ * Bulb and Time are only control behaviours. Neither implies a shutter mechanism, an exposure-boundary
+ * layout, a tripod, a stabilization state, long-exposure noise reduction (NR) or a temperature model.
+ *
+ * The binding function puts a resolved duration into the capture exposure-window input. The existing
+ * shutter mechanism and opening/closing schedules are left as they are. Only the nominal duration, in
+ * seconds, is supplied.
+ * @see docs/USAGE.md for the equations, units, coordinate conventions, known blockers and support
+ * limits.
  */
 import { parseEvidenceList } from "../core/evidence-provenance.js";
 import { InvalidScientificInputError } from "../core/validation.js";
+import { requireInputObject, requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 export const EXPOSURE_DURATION_CONTROL_VERSION = "0.1.0";
 function requireFiniteSeconds(value, path) {
     if (typeof value !== "number" ||
@@ -61,18 +66,15 @@ function active(kind) {
     };
 }
 /**
- * Resolves shutter-duration control semantics to a concrete positive elapsed
- * duration before physical exposure integration.
+ * Turns a shutter-duration control setting into a concrete, positive elapsed
+ * duration, before the physical exposure is integrated.
  *
- * Bulb and Time are control behaviors only. Neither implies a shutter
- * mechanism, exposure-boundary topology, tripod, stabilization state, long
- * exposure NR, or temperature model.
+ * Bulb and Time are only control behaviours. Neither implies a shutter
+ * mechanism, an exposure-boundary layout, a tripod, a stabilization state,
+ * long-exposure noise reduction (NR) or a temperature model.
  */
 export function resolveExposureDurationControl(control) {
-    if (typeof control !== "object" ||
-        control === null) {
-        throw new InvalidScientificInputError("control must be an object.");
-    }
+    requireInputKeys(control, "resolveExposureDurationControl", ["kind", "durationSeconds", "timeReference", "pressSeconds", "releaseSeconds", "startSeconds", "stopSeconds"]);
     if (control.kind ===
         "fixed-duration") {
         return resolved("fixed-duration", requirePositiveSeconds(control.durationSeconds, "control.durationSeconds"));
@@ -80,7 +82,7 @@ export function resolveExposureDurationControl(control) {
     if (control.kind === "bulb") {
         if (control.timeReference !==
             "control-monotonic-seconds") {
-            throw new InvalidScientificInputError('Bulb control timeReference must be "control-monotonic-seconds".');
+            throw new InvalidConfigurationError('Bulb control timeReference must be "control-monotonic-seconds".');
         }
         const start = requireFiniteSeconds(control.pressSeconds, "control.pressSeconds");
         if (control.releaseSeconds ===
@@ -97,7 +99,7 @@ export function resolveExposureDurationControl(control) {
     if (control.kind === "time") {
         if (control.timeReference !==
             "control-monotonic-seconds") {
-            throw new InvalidScientificInputError('Time control timeReference must be "control-monotonic-seconds".');
+            throw new InvalidConfigurationError('Time control timeReference must be "control-monotonic-seconds".');
         }
         const start = requireFiniteSeconds(control.startSeconds, "control.startSeconds");
         if (control.stopSeconds ===
@@ -111,16 +113,18 @@ export function resolveExposureDurationControl(control) {
         }
         return resolved("time", duration);
     }
-    throw new InvalidScientificInputError("control.kind is invalid.");
+    throw new InvalidConfigurationError("control.kind is invalid.");
 }
 /**
- * Binds a resolved duration into the authoritative #12 exposure-window input.
+ * Puts a resolved duration into the capture exposure-window input.
  *
- * The existing shutter mechanism/opening/closing schedules remain untouched.
- * Only the seconds-valued nominal duration is supplied here.
+ * The existing shutter mechanism and opening/closing schedules are left as
+ * they are. Only the nominal duration, in seconds, is supplied.
  */
 export function bindResolvedExposureDurationToCaptureExposureInput(input) {
+    requireInputKeys(input, "bindResolvedExposureDurationToCaptureExposureInput", ["resolution", "durationEvidence", "exposureWindowInput"]);
     const resolution = input.resolution;
+    requireInputObject(resolution, "resolution input");
     if (resolution.version !==
         EXPOSURE_DURATION_CONTROL_VERSION ||
         resolution.status !==

package/dist/exposure/exposure-duration-control.js.map

@@ -1 +1 @@
-{"version":3,"file":"exposure-duration-control.js","sourceRoot":"","sources":["../../src/exposure/exposure-duration-control.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"exposure-duration-control.js","sourceRoot":"","sources":["../../src/exposure/exposure-duration-control.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Shutter-duration control. Turns a control setting (a timed value, Bulb or Time) into a concrete,\n * positive elapsed duration, before the physical exposure is integrated.\n *\n * Bulb and Time are only control behaviours. Neither implies a shutter mechanism, an exposure-boundary\n * layout, a tripod, a stabilization state, long-exposure noise reduction (NR) or a temperature model.\n *\n * The binding function puts a resolved duration into the capture exposure-window input. The existing\n * shutter mechanism and opening/closing schedules are left as they are. Only the nominal duration, in\n * seconds, is supplied.\n * @see docs/USAGE.md for the equations, units, coordinate conventions, known blockers and support\n * limits.\n */\n\nimport {\n  parseEvidenceList,\n  type EvidenceProvenance\n} from \"../core/evidence-provenance.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport type {\n  CalculateCaptureExposureWindowsInput\n} from \"../sensor/exposure-window.js\";\nimport { requireInputObject, requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport const EXPOSURE_DURATION_CONTROL_VERSION =\n  \"0.1.0\" as const;\n\nexport type ExposureDurationControl =\n  | {\n      kind: \"fixed-duration\";\n      durationSeconds: number;\n    }\n  | {\n      kind: \"bulb\";\n      timeReference:\n        \"control-monotonic-seconds\";\n      pressSeconds: number;\n      releaseSeconds?: number;\n    }\n  | {\n      kind: \"time\";\n      timeReference:\n        \"control-monotonic-seconds\";\n      startSeconds: number;\n      stopSeconds?: number;\n    };\n\ninterface ExposureDurationControlResolutionBase {\n  version:\n    typeof EXPOSURE_DURATION_CONTROL_VERSION;\n  controlKind:\n    ExposureDurationControl[\"kind\"];\n  shutterMechanismInferred: false;\n  exposureBoundaryTopologyInferred:\n    false;\n  tripodSupportInferred: false;\n  stabilizationStateInferred: false;\n  longExposureNoiseReductionInferred:\n    false;\n  sensorTemperatureBehaviorInferred:\n    false;\n}\n\nexport type ExposureDurationControlResolution =\n  | (ExposureDurationControlResolutionBase & {\n      status: \"resolved\";\n      durationSeconds: number;\n      physicalExposureIntegrationAuthorized:\n        true;\n    })\n  | (ExposureDurationControlResolutionBase & {\n      status: \"active\";\n      durationSeconds: null;\n      physicalExposureIntegrationAuthorized:\n        false;\n      waitingFor:\n        | \"bulb-release\"\n        | \"time-stop\";\n    });\n\nexport interface BindResolvedExposureDurationToCaptureExposureInput {\n  resolution:\n    Extract<\n      ExposureDurationControlResolution,\n      { status: \"resolved\" }\n    >;\n  durationEvidence:\n    readonly EvidenceProvenance[];\n  exposureWindowInput:\n    Omit<\n      CalculateCaptureExposureWindowsInput,\n      \"nominalExposureDurationSeconds\"\n    >;\n}\n\nfunction requireFiniteSeconds(\n  value: unknown,\n  path: string\n): number {\n  if (\n    typeof value !== \"number\" ||\n    !Number.isFinite(value)\n  ) {\n    throw new InvalidScientificInputError(\n      path + \" must be finite.\"\n    );\n  }\n  return value;\n}\n\nfunction requirePositiveSeconds(\n  value: unknown,\n  path: string\n): number {\n  const parsed =\n    requireFiniteSeconds(\n      value,\n      path\n    );\n  if (parsed <= 0) {\n    throw new InvalidScientificInputError(\n      path +\n        \" must be greater than zero.\"\n    );\n  }\n  return parsed;\n}\n\nfunction resolved(\n  kind: ExposureDurationControl[\"kind\"],\n  durationSeconds: number\n): Extract<\n  ExposureDurationControlResolution,\n  { status: \"resolved\" }\n> {\n  return {\n    version:\n      EXPOSURE_DURATION_CONTROL_VERSION,\n    controlKind: kind,\n    status: \"resolved\",\n    durationSeconds,\n    physicalExposureIntegrationAuthorized:\n      true,\n    shutterMechanismInferred: false,\n    exposureBoundaryTopologyInferred:\n      false,\n    tripodSupportInferred: false,\n    stabilizationStateInferred: false,\n    longExposureNoiseReductionInferred:\n      false,\n    sensorTemperatureBehaviorInferred:\n      false\n  };\n}\n\nfunction active(\n  kind: \"bulb\" | \"time\"\n): Extract<\n  ExposureDurationControlResolution,\n  { status: \"active\" }\n> {\n  return {\n    version:\n      EXPOSURE_DURATION_CONTROL_VERSION,\n    controlKind: kind,\n    status: \"active\",\n    durationSeconds: null,\n    physicalExposureIntegrationAuthorized:\n      false,\n    waitingFor:\n      kind === \"bulb\"\n        ? \"bulb-release\"\n        : \"time-stop\",\n    shutterMechanismInferred: false,\n    exposureBoundaryTopologyInferred:\n      false,\n    tripodSupportInferred: false,\n    stabilizationStateInferred: false,\n    longExposureNoiseReductionInferred:\n      false,\n    sensorTemperatureBehaviorInferred:\n      false\n  };\n}\n\n/**\n * Turns a shutter-duration control setting into a concrete, positive elapsed\n * duration, before the physical exposure is integrated.\n *\n * Bulb and Time are only control behaviours. Neither implies a shutter\n * mechanism, an exposure-boundary layout, a tripod, a stabilization state,\n * long-exposure noise reduction (NR) or a temperature model.\n */\nexport function resolveExposureDurationControl(\n  control: ExposureDurationControl\n): ExposureDurationControlResolution {\n  requireInputKeys(control, \"resolveExposureDurationControl\", [\"kind\", \"durationSeconds\", \"timeReference\", \"pressSeconds\", \"releaseSeconds\", \"startSeconds\", \"stopSeconds\"]);\n\n  if (\n    control.kind ===\n    \"fixed-duration\"\n  ) {\n    return resolved(\n      \"fixed-duration\",\n      requirePositiveSeconds(\n        control.durationSeconds,\n        \"control.durationSeconds\"\n      )\n    );\n  }\n\n  if (\n    control.kind === \"bulb\"\n  ) {\n    if (\n      control.timeReference !==\n      \"control-monotonic-seconds\"\n    ) {\n      throw new InvalidConfigurationError(\n        'Bulb control timeReference must be \"control-monotonic-seconds\".'\n      );\n    }\n    const start =\n      requireFiniteSeconds(\n        control.pressSeconds,\n        \"control.pressSeconds\"\n      );\n    if (\n      control.releaseSeconds ===\n      undefined\n    ) {\n      return active(\"bulb\");\n    }\n    const stop =\n      requireFiniteSeconds(\n        control.releaseSeconds,\n        \"control.releaseSeconds\"\n      );\n    const duration = stop - start;\n    if (duration <= 0) {\n      throw new InvalidScientificInputError(\n        \"Bulb releaseSeconds must be greater than pressSeconds.\"\n      );\n    }\n    return resolved(\n      \"bulb\",\n      duration\n    );\n  }\n\n  if (\n    control.kind === \"time\"\n  ) {\n    if (\n      control.timeReference !==\n      \"control-monotonic-seconds\"\n    ) {\n      throw new InvalidConfigurationError(\n        'Time control timeReference must be \"control-monotonic-seconds\".'\n      );\n    }\n    const start =\n      requireFiniteSeconds(\n        control.startSeconds,\n        \"control.startSeconds\"\n      );\n    if (\n      control.stopSeconds ===\n      undefined\n    ) {\n      return active(\"time\");\n    }\n    const stop =\n      requireFiniteSeconds(\n        control.stopSeconds,\n        \"control.stopSeconds\"\n      );\n    const duration = stop - start;\n    if (duration <= 0) {\n      throw new InvalidScientificInputError(\n        \"Time stopSeconds must be greater than startSeconds.\"\n      );\n    }\n    return resolved(\n      \"time\",\n      duration\n    );\n  }\n\n  throw new InvalidConfigurationError(\n    \"control.kind is invalid.\"\n  );\n}\n\n/**\n * Puts a resolved duration into the capture exposure-window input.\n *\n * The existing shutter mechanism and opening/closing schedules are left as\n * they are. Only the nominal duration, in seconds, is supplied.\n */\nexport function bindResolvedExposureDurationToCaptureExposureInput(\n  input:\n    BindResolvedExposureDurationToCaptureExposureInput\n): CalculateCaptureExposureWindowsInput {\n  requireInputKeys(input, \"bindResolvedExposureDurationToCaptureExposureInput\", [\"resolution\", \"durationEvidence\", \"exposureWindowInput\"]);\n  const resolution =\n    input.resolution;\n\n  requireInputObject(resolution, \"resolution input\");\n  if (\n    resolution.version !==\n      EXPOSURE_DURATION_CONTROL_VERSION ||\n    resolution.status !==\n      \"resolved\" ||\n    resolution\n      .physicalExposureIntegrationAuthorized !==\n      true\n  ) {\n    throw new InvalidScientificInputError(\n      \"resolution must be a resolved exposure-duration control result authorized for physical integration.\"\n    );\n  }\n\n  const durationSeconds =\n    requirePositiveSeconds(\n      resolution.durationSeconds,\n      \"resolution.durationSeconds\"\n    );\n\n  if (\n    resolution.shutterMechanismInferred !==\n      false ||\n    resolution\n      .exposureBoundaryTopologyInferred !==\n      false ||\n    resolution.tripodSupportInferred !==\n      false ||\n    resolution\n      .stabilizationStateInferred !==\n      false ||\n    resolution\n      .longExposureNoiseReductionInferred !==\n      false ||\n    resolution\n      .sensorTemperatureBehaviorInferred !==\n      false\n  ) {\n    throw new InvalidScientificInputError(\n      \"Resolved exposure duration must not carry inferred downstream camera/long-exposure state.\"\n    );\n  }\n\n  return {\n    ...input.exposureWindowInput,\n    nominalExposureDurationSeconds: {\n      value: durationSeconds,\n      unit: \"s\",\n      evidence: parseEvidenceList(\n        input.durationEvidence,\n        \"durationEvidence\"\n      )\n    }\n  };\n}\n"]}

package/dist/exposure/exposure-mode-resolver.d.ts

@@ -564,74 +564,77 @@ export type FullAutoExposureModeResolution = (ProgramExposureResolutionBase & {
 /**
  * Resolves Manual exposure with either manual ISO or Auto ISO.
  *
- * Aperture and shutter are always caller-owned and are never changed.
- * The relative meter target is normalized by an explicit reference exposure
- * anchor; no ISO-100 or other hidden absolute calibration is assumed.
+ * The caller sets aperture and shutter; they are never changed. The relative
+ * meter target is normalized by an explicit reference exposure anchor. No
+ * ISO 100 or other hidden absolute calibration is assumed.
  */
 export declare function resolveManualExposureMode(input: ResolveManualExposureModeInput): ManualExposureModeResolution;
 /**
  * Resolves Aperture Priority with manual ISO.
  *
- * Aperture and ISO remain caller-owned. Shutter is the only automatic axis.
- * The target/reference relationship is the same relative exposure model used
- * by Manual + Auto ISO; no new mode-specific exposure equation is introduced.
+ * The caller sets aperture and ISO. Only the shutter is automatic. The target
+ * and reference use the same relative exposure model as Manual + Auto ISO; no
+ * new exposure equation is added for this mode.
  */
 export declare function resolveAperturePriorityExposureMode(input: ResolveAperturePriorityExposureModeInput): AperturePriorityExposureModeResolution;
 /**
- * Hold aperture fixed, follow the declared minimum-shutter policy and use bounded Auto ISO to absorb
- * remaining target residual.
+ * Aperture Priority with Auto ISO. Keeps the aperture fixed, follows the declared minimum-shutter
+ * policy, and uses Auto ISO (within its limits) to make up the rest of the exposure.
  *
- * Exposure modes apply control policy to one shared relative exposure equation and an explicit
- * reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
- * unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
- * diagnostics. A zero-signal target cannot authorize an invented exposure.
- * @param input - ResolveAperturePriorityAutoIsoExposureModeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns AperturePriorityAutoIsoExposureModeResolution. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Every exposure mode applies its control policy to one shared relative exposure equation, with an
+ * explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+ * settings are never changed. Automatic settings snap to the declared setting grids, and the result
+ * reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+ * be used to make up an exposure.
+ * @param input - ResolveAperturePriorityAutoIsoExposureModeInput. See that type for coordinates, units and profile binding.
+ * @returns AperturePriorityAutoIsoExposureModeResolution. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function resolveAperturePriorityAutoIsoExposureMode(input: ResolveAperturePriorityAutoIsoExposureModeInput): AperturePriorityAutoIsoExposureModeResolution;
 /**
- * Hold shutter fixed and resolve aperture plus optional Auto ISO against the exact capability
- * envelope.
+ * Shutter Priority. Keeps the shutter fixed and chooses the aperture, plus optional Auto ISO, within
+ * exactly what the equipment can do.
  *
- * Exposure modes apply control policy to one shared relative exposure equation and an explicit
- * reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
- * unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
- * diagnostics. A zero-signal target cannot authorize an invented exposure.
- * @param input - ResolveShutterPriorityExposureModeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ShutterPriorityExposureModeResolution. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Every exposure mode applies its control policy to one shared relative exposure equation, with an
+ * explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+ * settings are never changed. Automatic settings snap to the declared setting grids, and the result
+ * reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+ * be used to make up an exposure.
+ * @param input - ResolveShutterPriorityExposureModeInput. See that type for coordinates, units and profile binding.
+ * @returns ShutterPriorityExposureModeResolution. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function resolveShutterPriorityExposureMode(input: ResolveShutterPriorityExposureModeInput): ShutterPriorityExposureModeResolution;
 /**
- * Evaluate the declared generic program line in log2 exposure space, quantize aperture/shutter and
- * optionally use Auto ISO for residual exposure.
+ * Program auto exposure. Follows the declared generic program line in log2 exposure space, snaps
+ * aperture and shutter to their grids, and can use Auto ISO for any exposure left over.
  *
- * Exposure modes apply control policy to one shared relative exposure equation and an explicit
- * reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
- * unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
- * diagnostics. A zero-signal target cannot authorize an invented exposure.
- * @param input - ResolveProgramAutoExposureModeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ProgramAutoExposureModeResolution. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Every exposure mode applies its control policy to one shared relative exposure equation, with an
+ * explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+ * settings are never changed. Automatic settings snap to the declared setting grids, and the result
+ * reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+ * be used to make up an exposure.
+ * @param input - ResolveProgramAutoExposureModeInput. See that type for coordinates, units and profile binding.
+ * @returns ProgramAutoExposureModeResolution. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function resolveProgramAutoExposureMode(input: ResolveProgramAutoExposureModeInput): ProgramAutoExposureModeResolution;
 /**
- * Resolve aperture, shutter and ISO under an explicit generic Full Auto exposure policy. Autofocus,
- * WB, flash, drive and scene recognition remain unresolved.
+ * Full Auto. Chooses aperture, shutter and ISO under an explicit generic Full Auto exposure policy.
+ * Autofocus, white balance (WB), flash, drive mode and scene recognition are not resolved.
  *
- * Exposure modes apply control policy to one shared relative exposure equation and an explicit
- * reference anchor. Compensation is already included in the immutable meter target. Manual axes remain
- * unchanged; automatic axes use declared setting grids and expose signed residual stops and limit
- * diagnostics. A zero-signal target cannot authorize an invented exposure.
- * @param input - ResolveFullAutoExposureModeInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns FullAutoExposureModeResolution. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Every exposure mode applies its control policy to one shared relative exposure equation, with an
+ * explicit reference anchor. Exposure compensation is already part of the frozen meter target. Manual
+ * settings are never changed. Automatic settings snap to the declared setting grids, and the result
+ * reports the signed leftover (residual) stops and any limits hit. A target with zero signal cannot
+ * be used to make up an exposure.
+ * @param input - ResolveFullAutoExposureModeInput. See that type for coordinates, units and profile binding.
+ * @returns FullAutoExposureModeResolution. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function resolveFullAutoExposureMode(input: ResolveFullAutoExposureModeInput): FullAutoExposureModeResolution;
 export {};
-//# sourceMappingURL=exposure-mode-resolver.d.ts.map