@photivra/engine 2.18.0 → 2.19.0

package/dist/exposure/filtered-exposure-time.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shutter time that keeps the same exposure after neutral-density (or any passive) filters are put
+ * in front of the lens.
+ *
+ * Focal-plane exposure is H = 0.65·L·t/N² (CIPA DC-004-2020 §5.5 (4), free:
+ * https://www.cipa.jp/e/std/std-sec.html) and, more generally, the time integral of image-plane
+ * irradiance, H = E·t (EMVA Standard 1288 Release 4.0 Linear, §2, free). A front-of-lens filter
+ * with intensity transmittance T multiplies the light reaching the lens, and so E, by T. The same
+ * exposure at the same f-number therefore needs
+ *
+ *   t_filtered = t / T = t · 2^stops,  stops = −log2 T = OD / log10 2,
+ *
+ * exact under the linear (reciprocity) model of a digital sensor, whose collected charge is
+ * proportional to H. Film reciprocity failure is not modelled. T comes from the caller's
+ * front-of-lens filter profiles through `composeFrontOfLensFilterTransmission`, so nominal filter
+ * values (a "10-stop" filter, or OD 3.0 = 9.97 stops) are only as good as the profile: real filters
+ * vary from their nominal rating and with wavelength.
+ * @see docs/PHYSICS_FOUNDATION.md "Exposure time with an ND filter".
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import type { SpectralWavelengthBasis } from "../core/spectral.js";
+import { type ComposedFrontOfLensFilterTransmission, type FrontOfLensFilterProfile, type LinearPolarizationState } from "../optics/front-of-lens-filter.js";
+/** Wavelength used when the caller gives none: 550 nm, near the photopic peak. Neutral filters do not depend on it. */
+export declare const FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS: 550;
+export interface CalculateFilteredExposureTimeInput {
+    /** Shutter time without the filter, in seconds. */
+    shutterSeconds: number;
+    /**
+     * One front-of-lens filter profile, or several in light-path order (scene side first), as
+     * accepted by `composeFrontOfLensFilterTransmission`.
+     */
+    filter: FrontOfLensFilterProfile | readonly FrontOfLensFilterProfile[];
+    /**
+     * Optional shutter dial, in seconds (for example `GENERIC_THIRD_STOP_SHUTTER_SECONDS`). When
+     * given, the result also reports the nearest dial value (nearest in stops, the shorter on a tie).
+     */
+    shutterDialSeconds?: readonly number[];
+    /** Wavelength at which the filters are resolved. Defaults to 550 nm. Neutral filters do not depend on it. */
+    wavelengthNanometers?: number;
+    /** Wavelength basis; defaults to the first filter profile's basis and must match every profile. */
+    wavelengthBasis?: Exclude<SpectralWavelengthBasis, "unspecified">;
+    /** Incident polarization, which matters only when a polarizer is in the stack. Omitted means unpolarized. */
+    incidentPolarization?: LinearPolarizationState;
+}
+/** The dial value nearest the exact filtered shutter time. */
+export interface FilteredExposureDialSetting {
+    /** Nearest dial value in seconds. */
+    shutterSeconds: number;
+    /**
+     * log2(dial / exact filtered time): exposure of the dial setting relative to the unfiltered
+     * exposure, in stops. Positive is brighter (longer), negative darker.
+     */
+    exposureErrorStops: number;
+    /** `"maximum"` when the exact time is longer than every dial value (use bulb for the exact time), `"minimum"` when shorter than every one. */
+    clamped: false | "minimum" | "maximum";
+    /** How the dial value was chosen. */
+    quantizationPolicy: "nearest-log2-shorter-on-tie";
+}
+export interface FilteredExposureTime {
+    /** Shutter time without the filter, in seconds. */
+    shutterSeconds: number;
+    /** Shutter time that gives the same exposure with the filter: shutterSeconds / linearTransmissionFactor. */
+    filteredShutterSeconds: number;
+    /** Combined intensity transmittance T of the filter stack, in (0, 1]. */
+    linearTransmissionFactor: number;
+    /** Combined attenuation −log2 T, in stops. */
+    attenuationStops: number;
+    /** Shutter multiplier 1/T = 2^attenuationStops. */
+    exposureFactor: number;
+    /** Wavelength at which the filters were resolved, in nanometres. */
+    wavelengthNanometers: number;
+    /** The filter-stack transmission this result is based on, with each filter's identity and evidence. */
+    filterTransmission: ComposedFrontOfLensFilterTransmission;
+    /** Nearest shutter-dial value; present only when `shutterDialSeconds` was given. */
+    dial?: FilteredExposureDialSetting;
+}
+/**
+ * Shutter time that keeps the same exposure after adding front-of-lens filters, such as a
+ * neutral-density (ND) filter: t / T, with T the combined transmittance of the filter profiles.
+ * Aperture and ISO are unchanged.
+ *
+ * Exact under the linear sensor model (exposure H = E·t); film reciprocity failure is not modelled.
+ * Nominal filters vary: a "10-stop" or ND1000 (OD 3.0, 9.97 stops) filter transmits roughly, not
+ * exactly, its rating, so the result is only as good as the profile. The envelope is an
+ * approximation whenever any profile's `scientificStatus` is `"approximation"`.
+ *
+ * Example: 1/125 s with `GENERIC_ND_FILTER_PROFILES[10]` (exactly 2^-10) gives 1024/125 = 8.192 s;
+ * on a third-stop dial, 8 s.
+ *
+ * @param input Unfiltered shutter time, filter profile(s), optional dial, wavelength and polarization.
+ * @returns The filtered shutter time, the filter attenuation and, with a dial, the nearest dial value.
+ */
+export declare function calculateFilteredExposureTime(input: CalculateFilteredExposureTimeInput): CalculationResult<FilteredExposureTime>;

package/dist/exposure/filtered-exposure-time.js

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Shutter time that keeps the same exposure after neutral-density (or any passive) filters are put
+ * in front of the lens.
+ *
+ * Focal-plane exposure is H = 0.65·L·t/N² (CIPA DC-004-2020 §5.5 (4), free:
+ * https://www.cipa.jp/e/std/std-sec.html) and, more generally, the time integral of image-plane
+ * irradiance, H = E·t (EMVA Standard 1288 Release 4.0 Linear, §2, free). A front-of-lens filter
+ * with intensity transmittance T multiplies the light reaching the lens, and so E, by T. The same
+ * exposure at the same f-number therefore needs
+ *
+ *   t_filtered = t / T = t · 2^stops,  stops = −log2 T = OD / log10 2,
+ *
+ * exact under the linear (reciprocity) model of a digital sensor, whose collected charge is
+ * proportional to H. Film reciprocity failure is not modelled. T comes from the caller's
+ * front-of-lens filter profiles through `composeFrontOfLensFilterTransmission`, so nominal filter
+ * values (a "10-stop" filter, or OD 3.0 = 9.97 stops) are only as good as the profile: real filters
+ * vary from their nominal rating and with wavelength.
+ * @see docs/PHYSICS_FOUNDATION.md "Exposure time with an ND filter".
+ */
+import { approximationResult, calculatedResult } from "../core/calculation-result.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { portableLog2 } from "../core/portable-math.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidScientificResultError, requirePositiveFinite } from "../core/validation.js";
+import { composeFrontOfLensFilterTransmission } from "../optics/front-of-lens-filter.js";
+/** Wavelength used when the caller gives none: 550 nm, near the photopic peak. Neutral filters do not depend on it. */
+export const FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS = 550;
+function nearestDialValue(exactSeconds, dial) {
+    const values = [...dial].sort((a, b) => a - b);
+    const first = values[0], last = values[values.length - 1];
+    let selected = first;
+    let clamped = false;
+    if (exactSeconds < first) {
+        clamped = "minimum";
+    }
+    else if (exactSeconds > last) {
+        selected = last;
+        clamped = "maximum";
+    }
+    else {
+        let best = Math.abs(portableLog2(exactSeconds / first));
+        for (let index = 1; index < values.length; index += 1) {
+            const candidate = values[index];
+            const distance = Math.abs(portableLog2(exactSeconds / candidate));
+            // Ascending order: a later candidate wins only when strictly nearer, so a tie keeps the shorter time.
+            if (distance < best - 1e-12) {
+                selected = candidate;
+                best = distance;
+            }
+        }
+    }
+    return {
+        shutterSeconds: selected,
+        exposureErrorStops: portableLog2(selected / exactSeconds),
+        clamped,
+        quantizationPolicy: "nearest-log2-shorter-on-tie"
+    };
+}
+/**
+ * Shutter time that keeps the same exposure after adding front-of-lens filters, such as a
+ * neutral-density (ND) filter: t / T, with T the combined transmittance of the filter profiles.
+ * Aperture and ISO are unchanged.
+ *
+ * Exact under the linear sensor model (exposure H = E·t); film reciprocity failure is not modelled.
+ * Nominal filters vary: a "10-stop" or ND1000 (OD 3.0, 9.97 stops) filter transmits roughly, not
+ * exactly, its rating, so the result is only as good as the profile. The envelope is an
+ * approximation whenever any profile's `scientificStatus` is `"approximation"`.
+ *
+ * Example: 1/125 s with `GENERIC_ND_FILTER_PROFILES[10]` (exactly 2^-10) gives 1024/125 = 8.192 s;
+ * on a third-stop dial, 8 s.
+ *
+ * @param input Unfiltered shutter time, filter profile(s), optional dial, wavelength and polarization.
+ * @returns The filtered shutter time, the filter attenuation and, with a dial, the nearest dial value.
+ */
+export function calculateFilteredExposureTime(input) {
+    requireInputKeys(input, "calculateFilteredExposureTime", ["shutterSeconds", "filter", "shutterDialSeconds", "wavelengthNanometers", "wavelengthBasis", "incidentPolarization"]);
+    requirePositiveFinite("shutterSeconds", input.shutterSeconds);
+    const filters = Array.isArray(input.filter)
+        ? input.filter
+        : [input.filter];
+    const firstFilter = filters[0];
+    if (typeof firstFilter !== "object" || firstFilter === null) {
+        throw new InvalidConfigurationError("filter must be a front-of-lens filter profile or a non-empty array of them.");
+    }
+    const wavelengthNanometers = input.wavelengthNanometers ?? FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS;
+    const wavelengthBasis = input.wavelengthBasis ?? firstFilter.wavelengthBasis;
+    if (input.shutterDialSeconds !== undefined) {
+        if (!Array.isArray(input.shutterDialSeconds) || input.shutterDialSeconds.length === 0) {
+            throw new InvalidConfigurationError("shutterDialSeconds must be a non-empty array of shutter times in seconds.");
+        }
+        input.shutterDialSeconds.forEach((value, index) => {
+            requirePositiveFinite(`shutterDialSeconds[${index}]`, value);
+        });
+    }
+    const filterTransmission = composeFrontOfLensFilterTransmission({
+        filters,
+        wavelengthNanometers,
+        wavelengthBasis,
+        ...(input.incidentPolarization === undefined ? {} : { incidentPolarization: input.incidentPolarization })
+    });
+    const linearTransmissionFactor = filterTransmission.combinedLinearTransmissionFactor;
+    const exposureFactor = 1 / linearTransmissionFactor;
+    const filteredShutterSeconds = input.shutterSeconds / linearTransmissionFactor;
+    if (!Number.isFinite(exposureFactor) || !Number.isFinite(filteredShutterSeconds)) {
+        throw new InvalidScientificResultError("Filtered shutter time must remain finite.");
+    }
+    const value = {
+        shutterSeconds: input.shutterSeconds,
+        filteredShutterSeconds,
+        linearTransmissionFactor,
+        attenuationStops: filterTransmission.combinedAttenuationStops,
+        exposureFactor,
+        wavelengthNanometers: filterTransmission.wavelengthNanometers,
+        filterTransmission,
+        ...(input.shutterDialSeconds === undefined ? {} : { dial: nearestDialValue(filteredShutterSeconds, input.shutterDialSeconds) })
+    };
+    const assumptions = [
+        "Same exposure at the same f-number and ISO: filtered time = shutter time / T, from exposure H = E·t (linear sensor, CIPA DC-004-2020 §5.5; EMVA 1288 §2).",
+        "Reciprocity failure is not modelled: digital sensors respond linearly to exposure; film does not at long times.",
+        "T is the filter profiles' combined transmittance; nominal filters vary from their rating and with wavelength.",
+        `Filters resolved at ${filterTransmission.wavelengthNanometers} nm (${wavelengthBasis}); neutral filters do not depend on wavelength.`,
+        "Inter-filter reflections, flare, light leaks around the filter and through the viewfinder are not modelled."
+    ];
+    return filterTransmission.scientificStatus === "approximation"
+        ? approximationResult(value, "filtered-exposure-time", "1.0.0", assumptions)
+        : calculatedResult(value, "filtered-exposure-time", "1.0.0", assumptions);
+}
+//# sourceMappingURL=filtered-exposure-time.js.map

package/dist/exposure/filtered-exposure-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filtered-exposure-time.js","sourceRoot":"","sources":["../../src/exposure/filtered-exposure-time.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Shutter time that keeps the same exposure after neutral-density (or any passive) filters are put\n * in front of the lens.\n *\n * Focal-plane exposure is H = 0.65·L·t/N² (CIPA DC-004-2020 §5.5 (4), free:\n * https://www.cipa.jp/e/std/std-sec.html) and, more generally, the time integral of image-plane\n * irradiance, H = E·t (EMVA Standard 1288 Release 4.0 Linear, §2, free). A front-of-lens filter\n * with intensity transmittance T multiplies the light reaching the lens, and so E, by T. The same\n * exposure at the same f-number therefore needs\n *\n *   t_filtered = t / T = t · 2^stops,  stops = −log2 T = OD / log10 2,\n *\n * exact under the linear (reciprocity) model of a digital sensor, whose collected charge is\n * proportional to H. Film reciprocity failure is not modelled. T comes from the caller's\n * front-of-lens filter profiles through `composeFrontOfLensFilterTransmission`, so nominal filter\n * values (a \"10-stop\" filter, or OD 3.0 = 9.97 stops) are only as good as the profile: real filters\n * vary from their nominal rating and with wavelength.\n * @see docs/PHYSICS_FOUNDATION.md \"Exposure time with an ND filter\".\n */\n\nimport { approximationResult, calculatedResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { portableLog2 } from \"../core/portable-math.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport type { SpectralWavelengthBasis } from \"../core/spectral.js\";\nimport { InvalidScientificResultError, requirePositiveFinite } from \"../core/validation.js\";\nimport {\n  composeFrontOfLensFilterTransmission,\n  type ComposedFrontOfLensFilterTransmission,\n  type FrontOfLensFilterProfile,\n  type LinearPolarizationState\n} from \"../optics/front-of-lens-filter.js\";\n\n/** Wavelength used when the caller gives none: 550 nm, near the photopic peak. Neutral filters do not depend on it. */\nexport const FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS = 550 as const;\n\nexport interface CalculateFilteredExposureTimeInput {\n  /** Shutter time without the filter, in seconds. */\n  shutterSeconds: number;\n  /**\n   * One front-of-lens filter profile, or several in light-path order (scene side first), as\n   * accepted by `composeFrontOfLensFilterTransmission`.\n   */\n  filter: FrontOfLensFilterProfile | readonly FrontOfLensFilterProfile[];\n  /**\n   * Optional shutter dial, in seconds (for example `GENERIC_THIRD_STOP_SHUTTER_SECONDS`). When\n   * given, the result also reports the nearest dial value (nearest in stops, the shorter on a tie).\n   */\n  shutterDialSeconds?: readonly number[];\n  /** Wavelength at which the filters are resolved. Defaults to 550 nm. Neutral filters do not depend on it. */\n  wavelengthNanometers?: number;\n  /** Wavelength basis; defaults to the first filter profile's basis and must match every profile. */\n  wavelengthBasis?: Exclude<SpectralWavelengthBasis, \"unspecified\">;\n  /** Incident polarization, which matters only when a polarizer is in the stack. Omitted means unpolarized. */\n  incidentPolarization?: LinearPolarizationState;\n}\n\n/** The dial value nearest the exact filtered shutter time. */\nexport interface FilteredExposureDialSetting {\n  /** Nearest dial value in seconds. */\n  shutterSeconds: number;\n  /**\n   * log2(dial / exact filtered time): exposure of the dial setting relative to the unfiltered\n   * exposure, in stops. Positive is brighter (longer), negative darker.\n   */\n  exposureErrorStops: number;\n  /** `\"maximum\"` when the exact time is longer than every dial value (use bulb for the exact time), `\"minimum\"` when shorter than every one. */\n  clamped: false | \"minimum\" | \"maximum\";\n  /** How the dial value was chosen. */\n  quantizationPolicy: \"nearest-log2-shorter-on-tie\";\n}\n\nexport interface FilteredExposureTime {\n  /** Shutter time without the filter, in seconds. */\n  shutterSeconds: number;\n  /** Shutter time that gives the same exposure with the filter: shutterSeconds / linearTransmissionFactor. */\n  filteredShutterSeconds: number;\n  /** Combined intensity transmittance T of the filter stack, in (0, 1]. */\n  linearTransmissionFactor: number;\n  /** Combined attenuation −log2 T, in stops. */\n  attenuationStops: number;\n  /** Shutter multiplier 1/T = 2^attenuationStops. */\n  exposureFactor: number;\n  /** Wavelength at which the filters were resolved, in nanometres. */\n  wavelengthNanometers: number;\n  /** The filter-stack transmission this result is based on, with each filter's identity and evidence. */\n  filterTransmission: ComposedFrontOfLensFilterTransmission;\n  /** Nearest shutter-dial value; present only when `shutterDialSeconds` was given. */\n  dial?: FilteredExposureDialSetting;\n}\n\nfunction nearestDialValue(exactSeconds: number, dial: readonly number[]): FilteredExposureDialSetting {\n  const values = [...dial].sort((a, b) => a - b);\n  const first = values[0]!, last = values[values.length - 1]!;\n  let selected = first;\n  let clamped: FilteredExposureDialSetting[\"clamped\"] = false;\n  if (exactSeconds < first) {\n    clamped = \"minimum\";\n  } else if (exactSeconds > last) {\n    selected = last;\n    clamped = \"maximum\";\n  } else {\n    let best = Math.abs(portableLog2(exactSeconds / first));\n    for (let index = 1; index < values.length; index += 1) {\n      const candidate = values[index]!;\n      const distance = Math.abs(portableLog2(exactSeconds / candidate));\n      // Ascending order: a later candidate wins only when strictly nearer, so a tie keeps the shorter time.\n      if (distance < best - 1e-12) {\n        selected = candidate;\n        best = distance;\n      }\n    }\n  }\n  return {\n    shutterSeconds: selected,\n    exposureErrorStops: portableLog2(selected / exactSeconds),\n    clamped,\n    quantizationPolicy: \"nearest-log2-shorter-on-tie\"\n  };\n}\n\n/**\n * Shutter time that keeps the same exposure after adding front-of-lens filters, such as a\n * neutral-density (ND) filter: t / T, with T the combined transmittance of the filter profiles.\n * Aperture and ISO are unchanged.\n *\n * Exact under the linear sensor model (exposure H = E·t); film reciprocity failure is not modelled.\n * Nominal filters vary: a \"10-stop\" or ND1000 (OD 3.0, 9.97 stops) filter transmits roughly, not\n * exactly, its rating, so the result is only as good as the profile. The envelope is an\n * approximation whenever any profile's `scientificStatus` is `\"approximation\"`.\n *\n * Example: 1/125 s with `GENERIC_ND_FILTER_PROFILES[10]` (exactly 2^-10) gives 1024/125 = 8.192 s;\n * on a third-stop dial, 8 s.\n *\n * @param input Unfiltered shutter time, filter profile(s), optional dial, wavelength and polarization.\n * @returns The filtered shutter time, the filter attenuation and, with a dial, the nearest dial value.\n */\nexport function calculateFilteredExposureTime(\n  input: CalculateFilteredExposureTimeInput\n): CalculationResult<FilteredExposureTime> {\n  requireInputKeys(input, \"calculateFilteredExposureTime\",\n    [\"shutterSeconds\", \"filter\", \"shutterDialSeconds\", \"wavelengthNanometers\", \"wavelengthBasis\", \"incidentPolarization\"]);\n  requirePositiveFinite(\"shutterSeconds\", input.shutterSeconds);\n  const filters: readonly FrontOfLensFilterProfile[] = Array.isArray(input.filter)\n    ? input.filter\n    : [input.filter as FrontOfLensFilterProfile];\n  const firstFilter: unknown = filters[0];\n  if (typeof firstFilter !== \"object\" || firstFilter === null) {\n    throw new InvalidConfigurationError(\"filter must be a front-of-lens filter profile or a non-empty array of them.\");\n  }\n  const wavelengthNanometers = input.wavelengthNanometers ?? FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS;\n  const wavelengthBasis = input.wavelengthBasis ?? (firstFilter as FrontOfLensFilterProfile).wavelengthBasis;\n  if (input.shutterDialSeconds !== undefined) {\n    if (!Array.isArray(input.shutterDialSeconds) || input.shutterDialSeconds.length === 0) {\n      throw new InvalidConfigurationError(\"shutterDialSeconds must be a non-empty array of shutter times in seconds.\");\n    }\n    input.shutterDialSeconds.forEach((value: unknown, index) => {\n      requirePositiveFinite(`shutterDialSeconds[${index}]`, value as number);\n    });\n  }\n\n  const filterTransmission = composeFrontOfLensFilterTransmission({\n    filters,\n    wavelengthNanometers,\n    wavelengthBasis,\n    ...(input.incidentPolarization === undefined ? {} : { incidentPolarization: input.incidentPolarization })\n  });\n  const linearTransmissionFactor = filterTransmission.combinedLinearTransmissionFactor;\n  const exposureFactor = 1 / linearTransmissionFactor;\n  const filteredShutterSeconds = input.shutterSeconds / linearTransmissionFactor;\n  if (!Number.isFinite(exposureFactor) || !Number.isFinite(filteredShutterSeconds)) {\n    throw new InvalidScientificResultError(\"Filtered shutter time must remain finite.\");\n  }\n\n  const value: FilteredExposureTime = {\n    shutterSeconds: input.shutterSeconds,\n    filteredShutterSeconds,\n    linearTransmissionFactor,\n    attenuationStops: filterTransmission.combinedAttenuationStops,\n    exposureFactor,\n    wavelengthNanometers: filterTransmission.wavelengthNanometers,\n    filterTransmission,\n    ...(input.shutterDialSeconds === undefined ? {} : { dial: nearestDialValue(filteredShutterSeconds, input.shutterDialSeconds) })\n  };\n  const assumptions = [\n    \"Same exposure at the same f-number and ISO: filtered time = shutter time / T, from exposure H = E·t (linear sensor, CIPA DC-004-2020 §5.5; EMVA 1288 §2).\",\n    \"Reciprocity failure is not modelled: digital sensors respond linearly to exposure; film does not at long times.\",\n    \"T is the filter profiles' combined transmittance; nominal filters vary from their rating and with wavelength.\",\n    `Filters resolved at ${filterTransmission.wavelengthNanometers} nm (${wavelengthBasis}); neutral filters do not depend on wavelength.`,\n    \"Inter-filter reflections, flare, light leaks around the filter and through the viewfinder are not modelled.\"\n  ];\n  return filterTransmission.scientificStatus === \"approximation\"\n    ? approximationResult(value, \"filtered-exposure-time\", \"1.0.0\", assumptions)\n    : calculatedResult(value, \"filtered-exposure-time\", \"1.0.0\", assumptions);\n}\n"]}

package/dist/exposure/flash-ttl.d.ts

@@ -18,6 +18,7 @@ export declare const TTL_FLASH_MODEL: Readonly<{
     readonly id: "preflash-linear-ttl";
     readonly version: "1.0.0";
 }>;
+export declare function requirePositive(value: unknown, name: string): number;
 export interface FlashGuideNumberInput {
     /** Guide number at full power for ISO 100, in metres (GN = distance · f-number). */
     fullPowerGuideNumberMetersIso100: number;

package/dist/exposure/flash-ttl.js

@@ -19,7 +19,7 @@ import { rejectUnknownFields, requireInputKeys, requireInputObject } from "../co
 import { parseManualFlashProfile } from "./flash.js";
 import { meterRelativeExposure, parseExposureMeteringProfile } from "./metering.js";
 export const TTL_FLASH_MODEL = /* @__PURE__ */ Object.freeze({ id: "preflash-linear-ttl", version: "1.0.0" });
-function requirePositive(value, name) {
+export function requirePositive(value, name) {
     if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
         throw new InvalidScientificInputError(name + " must be a finite number greater than zero.");
     }

package/dist/exposure/flash-ttl.js.map

@@ -1 +1 @@
-{"version":3,"file":"flash-ttl.js","sourceRoot":"","sources":["../../src/exposure/flash-ttl.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Flash guide numbers, and through-the-lens (TTL) flash exposure with a pre-flash that does not\n * depend on any manufacturer.\n *\n * How TTL works here:\n * 1. The pre-flash is measured with the existing relative exposure meter.\n * 2. The solved power fraction is applied to a ManualFlashProfile.\n * 3. That pulse is placed by the existing front/rear-curtain sync (resolveManualFlashSync) or by\n *    high-speed sync (resolveHighSpeedFlashSync).\n * Flash metering stays separate from ambient metering. The ambient meter result is an input and is\n * not changed. No vendor's TTL algorithm, zone weighting table or flash protocol is copied.\n * @see docs/SCENE_SENSOR_TEMPORAL_EXPOSURE.md#flash-guide-number-ttl-and-high-speed-sync\n */\n\nimport { approximationResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { rejectUnknownFields, requireInputKeys, requireInputObject } from \"../core/record-validation.js\";\nimport { parseManualFlashProfile, type ManualFlashProfile } from \"./flash.js\";\nimport {\n  meterRelativeExposure,\n  parseExposureMeteringProfile,\n  type ExposureMeteringProfile,\n  type ExposureMeteringSampleSet\n} from \"./metering.js\";\n\nexport const TTL_FLASH_MODEL = /* @__PURE__ */ Object.freeze({ id: \"preflash-linear-ttl\", version: \"1.0.0\" } as const);\n\nfunction requirePositive(value: unknown, name: string): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0) {\n    throw new InvalidScientificInputError(name + \" must be a finite number greater than zero.\");\n  }\n  return value;\n}\n\nfunction requireFraction(value: unknown, name: string): number {\n  const parsed = requirePositive(value, name);\n  if (parsed > 1) throw new InvalidScientificInputError(name + \" must lie in (0, 1].\");\n  return parsed;\n}\n\nexport interface FlashGuideNumberInput {\n  /** Guide number at full power for ISO 100, in metres (GN = distance · f-number). */\n  fullPowerGuideNumberMetersIso100: number;\n  /** Output as a fraction of full power, (0, 1]. */\n  powerFraction: number;\n  iso: number;\n}\n\n/**\n * Effective guide number GN = GN_full · √p · √(ISO/100).\n *\n * The guide number relation GN = d·N follows from the inverse-square law. Light on the subject from a\n * point-like flash falls as 1/d², and sensor exposure falls as 1/N². So exposure stays correct while\n * d·N is constant (camera equation H = 0.65·L·t/N² and reference exposure H = 10/S, CIPA DC-004-2020,\n * free). Exposure grows linearly with emitted energy (power fraction p), and the exposure needed falls\n * inversely with ISO speed. So GN ∝ √p·√ISO. The engine does not model how a guide number is measured;\n * the caller supplies it.\n * @see docs/SCENE_SENSOR_TEMPORAL_EXPOSURE.md for the full derivation.\n */\nexport function calculateFlashGuideNumber(input: FlashGuideNumberInput): number {\n  requireInputKeys(input, \"calculateFlashGuideNumber\", [\"fullPowerGuideNumberMetersIso100\", \"powerFraction\", \"iso\"]);\n  return requirePositive(input.fullPowerGuideNumberMetersIso100, \"fullPowerGuideNumberMetersIso100\") *\n    Math.sqrt(requireFraction(input.powerFraction, \"powerFraction\")) *\n    Math.sqrt(requirePositive(input.iso, \"iso\") / 100);\n}\n\nexport interface FlashPowerForDistanceInput {\n  fullPowerGuideNumberMetersIso100: number;\n  subjectDistanceM: number;\n  apertureFNumber: number;\n  iso: number;\n  /** Lowest available power fraction, (0, 1]. */\n  minimumPowerFraction: number;\n}\n\nexport interface FlashPowerForDistance {\n  /** p = (d·N / (GN_full·√(ISO/100)))², before clamping. */\n  requiredPowerFraction: number;\n  powerFraction: number;\n  status: \"within-range\" | \"clamped-at-minimum-power\" | \"clamped-at-full-power\";\n  /** log2(delivered / required) flash exposure; positive is overexposure. */\n  flashExposureErrorStops: number;\n  /** GN_full·√(ISO/100)/N: the farthest correctly exposed distance at full power. */\n  maximumDistanceM: number;\n}\n\n/** Manual guide-number exposure: the power fraction that exposes a subject at distance d correctly. */\nexport function calculateFlashPowerForDistance(input: FlashPowerForDistanceInput): FlashPowerForDistance {\n  requireInputKeys(input, \"calculateFlashPowerForDistance\", [\"fullPowerGuideNumberMetersIso100\", \"subjectDistanceM\",\n    \"apertureFNumber\", \"iso\", \"minimumPowerFraction\"]);\n  const gnIso = calculateFlashGuideNumber({ fullPowerGuideNumberMetersIso100: input.fullPowerGuideNumberMetersIso100,\n    powerFraction: 1, iso: input.iso });\n  const distance = requirePositive(input.subjectDistanceM, \"subjectDistanceM\");\n  const aperture = requirePositive(input.apertureFNumber, \"apertureFNumber\");\n  const minimum = requireFraction(input.minimumPowerFraction, \"minimumPowerFraction\");\n  const required = (distance * aperture / gnIso) ** 2;\n  const power = Math.min(1, Math.max(minimum, required));\n  return { requiredPowerFraction: required, powerFraction: power,\n    status: required < minimum ? \"clamped-at-minimum-power\" : required > 1 ? \"clamped-at-full-power\" : \"within-range\",\n    flashExposureErrorStops: Math.log2(power / required), maximumDistanceM: gnIso / aperture };\n}\n\nexport interface ResolveTtlFlashExposureInput {\n  /** Spatially linear metering profile (multi-zone-uniform, center-weighted-radial or spot). */\n  meteringProfile: ExposureMeteringProfile;\n  /** Measurement-window samples with the flash off. */\n  ambientSampleSet: ExposureMeteringSampleSet;\n  /** The same zones and settings with the pre-flash fired. */\n  preFlashSampleSet: ExposureMeteringSampleSet;\n  /** Pre-flash output as a fraction of full power, (0, 1]. */\n  preFlashPowerFraction: number;\n  /**\n   * Ratio of ambient light collected in the main exposure to that in the measurement window, at the\n   * same aperture and ISO (for example t_main/t_measure). Must be ≥ 0. The flash pulse falls inside\n   * both windows, so it is not scaled.\n   */\n  ambientScaleToMainExposure: number;\n  /** Flash exposure compensation applied to the TTL target, in stops. */\n  flashExposureCompensationStops: number;\n  /** Lowest available main-flash power fraction, (0, 1]. */\n  minimumPowerFraction: number;\n  /**\n   * Flash energy each line receives, relative to an ordinary pulse at the same power fraction. 1 for\n   * front/rear-curtain sync; η·t_e/D for high-speed sync (see resolveHighSpeedFlashSync). Defaults to 1.\n   */\n  syncEnergyFactor?: number;\n  /** Optional guide-number reporting. */\n  guideNumber?: { fullPowerGuideNumberMetersIso100: number; iso: number; apertureFNumber: number };\n}\n\nexport interface TtlFlashExposure {\n  modelId: typeof TTL_FLASH_MODEL.id;\n  modelVersion: typeof TTL_FLASH_MODEL.version;\n  status: \"resolved\" | \"clamped-at-minimum-power\" | \"clamped-at-full-power\" | \"no-flash-return\";\n  /** Metered ambient signal in the main exposure: k·M(ambient). */\n  ambientMainExposureMeteredSignal: number;\n  /** Metered flash-only signal per unit full power: M(preflash − ambient)/p_pre. */\n  flashMeteredSignalPerFullPower: number;\n  /** T·2^FEC. */\n  targetRelativeSignal: number;\n  /** Unclamped solution (T' − k·A)/(F·syncEnergyFactor); null with no flash return. */\n  requiredPowerFraction: number | null;\n  /** Commanded main-flash power fraction (clamped); null with no flash return. */\n  powerFraction: number | null;\n  ambientAloneReachesTarget: boolean;\n  predictedMeteredSignal: number;\n  /** log2(predicted / target); 0 when the solution is within range; null when nothing is predicted. */\n  predictedExposureErrorStops: number | null;\n  effectiveGuideNumberMetersAtIso: number | null;\n  flashRangeAtApertureM: number | null;\n  preFlashInsideMainExposure: false;\n  ambientMeteringModified: false;\n}\n\nconst LINEAR_POLICIES = new Set([\"multi-zone-uniform\", \"center-weighted-radial\", \"spot\"]);\n\nfunction sameZones(a: ExposureMeteringSampleSet, b: ExposureMeteringSampleSet): void {\n  if (a.sceneStateId !== b.sceneStateId || a.samples.length !== b.samples.length ||\n    JSON.stringify(a.captureGeometry) !== JSON.stringify(b.captureGeometry)) {\n    throw new InvalidScientificInputError(\"Ambient and pre-flash measurements must share scene state, geometry and zones.\");\n  }\n  a.samples.forEach((sample, index) => {\n    const other = b.samples[index]!;\n    requireInputObject(sample, \"ambientSampleSet.samples[\" + index + \"]\");\n    requireInputObject(other, \"preFlashSampleSet.samples[\" + index + \"]\");\n    requireInputObject(sample.positionOrientedCaptureUv, \"ambientSampleSet.samples[\" + index + \"].positionOrientedCaptureUv\");\n    requireInputObject(other.positionOrientedCaptureUv, \"preFlashSampleSet.samples[\" + index + \"].positionOrientedCaptureUv\");\n    if (sample.sampleId !== other.sampleId || sample.areaWeight !== other.areaWeight ||\n      sample.positionOrientedCaptureUv.u !== other.positionOrientedCaptureUv.u ||\n      sample.positionOrientedCaptureUv.v !== other.positionOrientedCaptureUv.v) {\n      throw new InvalidScientificInputError(\"Ambient and pre-flash zones must match exactly and in order.\");\n    }\n  });\n}\n\n/**\n * Solves the main-flash power from a pre-flash measurement (manufacturer-independent TTL).\n *\n * The meter is linear for the policies allowed here: M(a + b) = M(a) + M(b).\n * - The pre-flash at power p_pre adds a flash-only signal f_i = pre_i − ambient_i in each zone.\n * - Flash signal is proportional to emitted energy, so at main power p it adds (p/p_pre)·M(f).\n * - With ambient scaled to the main exposure by k, the metered total is k·A + p·F, where\n *   F = M(f)/p_pre.\n * - Setting this equal to the target T' = T·2^FEC gives p = (T' − k·A)/(F·s). Here s is the sync\n *   energy factor (1 for ordinary sync, η·t_e/D for high-speed sync).\n * - p is clamped to [p_min, 1], the guide-number range.\n * Highlight policies are rejected: their weights depend on the signal, so the total is no longer\n * linear in p.\n */\nexport function resolveTtlFlashExposure(input: ResolveTtlFlashExposureInput): CalculationResult<TtlFlashExposure> {\n  requireInputKeys(input, \"resolveTtlFlashExposure\", [\"meteringProfile\", \"ambientSampleSet\", \"preFlashSampleSet\", \"preFlashPowerFraction\", \"ambientScaleToMainExposure\", \"flashExposureCompensationStops\", \"minimumPowerFraction\", \"syncEnergyFactor\", \"guideNumber\"]);\n  requireInputObject(input.ambientSampleSet, \"resolveTtlFlashExposure ambientSampleSet\");\n  requireInputObject(input.preFlashSampleSet, \"resolveTtlFlashExposure preFlashSampleSet\");\n  if (input.guideNumber !== undefined) {\n    requireInputObject(input.guideNumber, \"resolveTtlFlashExposure guideNumber\");\n    rejectUnknownFields(input.guideNumber, [\"fullPowerGuideNumberMetersIso100\", \"iso\", \"apertureFNumber\"], \"resolveTtlFlashExposure guideNumber\");\n  }\n  if (!Array.isArray(input.ambientSampleSet.samples) || !Array.isArray(input.preFlashSampleSet.samples)) {\n    throw new InvalidConfigurationError(\"TTL sample sets must contain sample arrays.\");\n  }\n  const profile = parseExposureMeteringProfile(input.meteringProfile);\n  if (!LINEAR_POLICIES.has(profile.policy.kind)) {\n    throw new InvalidScientificInputError(\n      \"TTL flash requires a spatially linear metering policy (multi-zone-uniform, center-weighted-radial or spot).\"\n    );\n  }\n  sameZones(input.ambientSampleSet, input.preFlashSampleSet);\n  const preFlash = requireFraction(input.preFlashPowerFraction, \"preFlashPowerFraction\");\n  const minimum = requireFraction(input.minimumPowerFraction, \"minimumPowerFraction\");\n  const k = input.ambientScaleToMainExposure;\n  if (typeof k !== \"number\" || !Number.isFinite(k) || k < 0) {\n    throw new InvalidScientificInputError(\"ambientScaleToMainExposure must be a finite number greater than or equal to zero.\");\n  }\n  const fec = input.flashExposureCompensationStops;\n  if (typeof fec !== \"number\" || !Number.isFinite(fec)) {\n    throw new InvalidScientificInputError(\"flashExposureCompensationStops must be finite.\");\n  }\n  const syncFactor = input.syncEnergyFactor === undefined ? 1 : requireFraction(input.syncEnergyFactor, \"syncEnergyFactor\");\n  const flashOnly: ExposureMeteringSampleSet = { ...input.preFlashSampleSet,\n    measurementId: input.preFlashSampleSet.measurementId + \":flash-only\",\n    samples: input.preFlashSampleSet.samples.map((sample, index) => {\n      const difference = sample.relativeLinearSignal - input.ambientSampleSet.samples[index]!.relativeLinearSignal;\n      if (!(difference >= 0)) {\n        throw new InvalidScientificInputError(\"Pre-flash signal must not be below the ambient signal in any zone.\");\n      }\n      return { ...sample, relativeLinearSignal: difference };\n    }) };\n  const ambient = meterRelativeExposure({ profile, sampleSet: input.ambientSampleSet }).value.meteredRelativeSignal;\n  const flashPerFull = meterRelativeExposure({ profile, sampleSet: flashOnly }).value.meteredRelativeSignal / preFlash;\n  const ambientMain = k * ambient;\n  const target = profile.target.targetRelativeSignal * Math.pow(2, fec);\n  const deliveredPerFull = flashPerFull * syncFactor;\n  let status: TtlFlashExposure[\"status\"], required: number | null, power: number | null;\n  if (deliveredPerFull === 0) {\n    status = \"no-flash-return\"; required = null; power = null;\n  } else {\n    required = (target - ambientMain) / deliveredPerFull;\n    power = Math.min(1, Math.max(minimum, required));\n    status = required < minimum ? \"clamped-at-minimum-power\" : required > 1 ? \"clamped-at-full-power\" : \"resolved\";\n  }\n  const predicted = ambientMain + (power ?? 0) * deliveredPerFull;\n  const gn = input.guideNumber;\n  const effectiveGn = gn === undefined || power === null ? null : calculateFlashGuideNumber({\n    fullPowerGuideNumberMetersIso100: gn.fullPowerGuideNumberMetersIso100, powerFraction: power, iso: gn.iso }) * Math.sqrt(syncFactor);\n  return approximationResult({\n    modelId: TTL_FLASH_MODEL.id,\n    modelVersion: TTL_FLASH_MODEL.version,\n    status,\n    ambientMainExposureMeteredSignal: ambientMain,\n    flashMeteredSignalPerFullPower: flashPerFull,\n    targetRelativeSignal: target,\n    requiredPowerFraction: required,\n    powerFraction: power,\n    ambientAloneReachesTarget: ambientMain >= target,\n    predictedMeteredSignal: predicted,\n    predictedExposureErrorStops: predicted > 0 ? Math.log2(predicted / target) : null,\n    effectiveGuideNumberMetersAtIso: effectiveGn,\n    flashRangeAtApertureM: effectiveGn === null || gn === undefined ? null : effectiveGn / requirePositive(gn.apertureFNumber, \"apertureFNumber\"),\n    preFlashInsideMainExposure: false,\n    ambientMeteringModified: false\n  }, TTL_FLASH_MODEL.id, TTL_FLASH_MODEL.version, [\n    \"Relative pre-exposure meter signals only; no calibrated flash energy, subject reflectance or distance is inferred.\",\n    \"Flash signal is assumed proportional to emitted energy and fully inside the main exposure (pulse) or each line's slit (HSS factor).\",\n    \"The pre-flash precedes the main exposure; subject motion and ambient change between pre-flash and exposure are not modeled.\",\n    \"This is a generic linear pre-flash solution, not any manufacturer's TTL algorithm, zone weighting or flash protocol.\"\n  ]);\n}\n\n/**\n * Returns a copy of a manual flash profile with its relative output scaled by a resolved TTL power\n * fraction, ready for resolveManualFlashSync (front/rear curtain). For high-speed sync, instead pass\n * the unscaled profile, and pass `ttl.powerFraction` as resolveHighSpeedFlashSync's powerFraction.\n * That way power is applied only once.\n */\nexport function createTtlScaledFlashProfile(flashProfile: ManualFlashProfile, ttl: TtlFlashExposure): ManualFlashProfile {\n  const flash = parseManualFlashProfile(flashProfile);\n  requireInputObject(ttl, \"createTtlScaledFlashProfile ttl\");\n  if (ttl.powerFraction === null || typeof ttl.powerFraction !== \"number\") {\n    throw new InvalidScientificInputError(\"TTL found no flash return; there is no power fraction to apply.\");\n  }\n  return { ...flash, outputControl: { ...flash.outputControl, scale: flash.outputControl.scale * ttl.powerFraction } };\n}\n"]}
+{"version":3,"file":"flash-ttl.js","sourceRoot":"","sources":["../../src/exposure/flash-ttl.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Flash guide numbers, and through-the-lens (TTL) flash exposure with a pre-flash that does not\n * depend on any manufacturer.\n *\n * How TTL works here:\n * 1. The pre-flash is measured with the existing relative exposure meter.\n * 2. The solved power fraction is applied to a ManualFlashProfile.\n * 3. That pulse is placed by the existing front/rear-curtain sync (resolveManualFlashSync) or by\n *    high-speed sync (resolveHighSpeedFlashSync).\n * Flash metering stays separate from ambient metering. The ambient meter result is an input and is\n * not changed. No vendor's TTL algorithm, zone weighting table or flash protocol is copied.\n * @see docs/SCENE_SENSOR_TEMPORAL_EXPOSURE.md#flash-guide-number-ttl-and-high-speed-sync\n */\n\nimport { approximationResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { rejectUnknownFields, requireInputKeys, requireInputObject } from \"../core/record-validation.js\";\nimport { parseManualFlashProfile, type ManualFlashProfile } from \"./flash.js\";\nimport {\n  meterRelativeExposure,\n  parseExposureMeteringProfile,\n  type ExposureMeteringProfile,\n  type ExposureMeteringSampleSet\n} from \"./metering.js\";\n\nexport const TTL_FLASH_MODEL = /* @__PURE__ */ Object.freeze({ id: \"preflash-linear-ttl\", version: \"1.0.0\" } as const);\n\nexport function requirePositive(value: unknown, name: string): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0) {\n    throw new InvalidScientificInputError(name + \" must be a finite number greater than zero.\");\n  }\n  return value;\n}\n\nfunction requireFraction(value: unknown, name: string): number {\n  const parsed = requirePositive(value, name);\n  if (parsed > 1) throw new InvalidScientificInputError(name + \" must lie in (0, 1].\");\n  return parsed;\n}\n\nexport interface FlashGuideNumberInput {\n  /** Guide number at full power for ISO 100, in metres (GN = distance · f-number). */\n  fullPowerGuideNumberMetersIso100: number;\n  /** Output as a fraction of full power, (0, 1]. */\n  powerFraction: number;\n  iso: number;\n}\n\n/**\n * Effective guide number GN = GN_full · √p · √(ISO/100).\n *\n * The guide number relation GN = d·N follows from the inverse-square law. Light on the subject from a\n * point-like flash falls as 1/d², and sensor exposure falls as 1/N². So exposure stays correct while\n * d·N is constant (camera equation H = 0.65·L·t/N² and reference exposure H = 10/S, CIPA DC-004-2020,\n * free). Exposure grows linearly with emitted energy (power fraction p), and the exposure needed falls\n * inversely with ISO speed. So GN ∝ √p·√ISO. The engine does not model how a guide number is measured;\n * the caller supplies it.\n * @see docs/SCENE_SENSOR_TEMPORAL_EXPOSURE.md for the full derivation.\n */\nexport function calculateFlashGuideNumber(input: FlashGuideNumberInput): number {\n  requireInputKeys(input, \"calculateFlashGuideNumber\", [\"fullPowerGuideNumberMetersIso100\", \"powerFraction\", \"iso\"]);\n  return requirePositive(input.fullPowerGuideNumberMetersIso100, \"fullPowerGuideNumberMetersIso100\") *\n    Math.sqrt(requireFraction(input.powerFraction, \"powerFraction\")) *\n    Math.sqrt(requirePositive(input.iso, \"iso\") / 100);\n}\n\nexport interface FlashPowerForDistanceInput {\n  fullPowerGuideNumberMetersIso100: number;\n  subjectDistanceM: number;\n  apertureFNumber: number;\n  iso: number;\n  /** Lowest available power fraction, (0, 1]. */\n  minimumPowerFraction: number;\n}\n\nexport interface FlashPowerForDistance {\n  /** p = (d·N / (GN_full·√(ISO/100)))², before clamping. */\n  requiredPowerFraction: number;\n  powerFraction: number;\n  status: \"within-range\" | \"clamped-at-minimum-power\" | \"clamped-at-full-power\";\n  /** log2(delivered / required) flash exposure; positive is overexposure. */\n  flashExposureErrorStops: number;\n  /** GN_full·√(ISO/100)/N: the farthest correctly exposed distance at full power. */\n  maximumDistanceM: number;\n}\n\n/** Manual guide-number exposure: the power fraction that exposes a subject at distance d correctly. */\nexport function calculateFlashPowerForDistance(input: FlashPowerForDistanceInput): FlashPowerForDistance {\n  requireInputKeys(input, \"calculateFlashPowerForDistance\", [\"fullPowerGuideNumberMetersIso100\", \"subjectDistanceM\",\n    \"apertureFNumber\", \"iso\", \"minimumPowerFraction\"]);\n  const gnIso = calculateFlashGuideNumber({ fullPowerGuideNumberMetersIso100: input.fullPowerGuideNumberMetersIso100,\n    powerFraction: 1, iso: input.iso });\n  const distance = requirePositive(input.subjectDistanceM, \"subjectDistanceM\");\n  const aperture = requirePositive(input.apertureFNumber, \"apertureFNumber\");\n  const minimum = requireFraction(input.minimumPowerFraction, \"minimumPowerFraction\");\n  const required = (distance * aperture / gnIso) ** 2;\n  const power = Math.min(1, Math.max(minimum, required));\n  return { requiredPowerFraction: required, powerFraction: power,\n    status: required < minimum ? \"clamped-at-minimum-power\" : required > 1 ? \"clamped-at-full-power\" : \"within-range\",\n    flashExposureErrorStops: Math.log2(power / required), maximumDistanceM: gnIso / aperture };\n}\n\nexport interface ResolveTtlFlashExposureInput {\n  /** Spatially linear metering profile (multi-zone-uniform, center-weighted-radial or spot). */\n  meteringProfile: ExposureMeteringProfile;\n  /** Measurement-window samples with the flash off. */\n  ambientSampleSet: ExposureMeteringSampleSet;\n  /** The same zones and settings with the pre-flash fired. */\n  preFlashSampleSet: ExposureMeteringSampleSet;\n  /** Pre-flash output as a fraction of full power, (0, 1]. */\n  preFlashPowerFraction: number;\n  /**\n   * Ratio of ambient light collected in the main exposure to that in the measurement window, at the\n   * same aperture and ISO (for example t_main/t_measure). Must be ≥ 0. The flash pulse falls inside\n   * both windows, so it is not scaled.\n   */\n  ambientScaleToMainExposure: number;\n  /** Flash exposure compensation applied to the TTL target, in stops. */\n  flashExposureCompensationStops: number;\n  /** Lowest available main-flash power fraction, (0, 1]. */\n  minimumPowerFraction: number;\n  /**\n   * Flash energy each line receives, relative to an ordinary pulse at the same power fraction. 1 for\n   * front/rear-curtain sync; η·t_e/D for high-speed sync (see resolveHighSpeedFlashSync). Defaults to 1.\n   */\n  syncEnergyFactor?: number;\n  /** Optional guide-number reporting. */\n  guideNumber?: { fullPowerGuideNumberMetersIso100: number; iso: number; apertureFNumber: number };\n}\n\nexport interface TtlFlashExposure {\n  modelId: typeof TTL_FLASH_MODEL.id;\n  modelVersion: typeof TTL_FLASH_MODEL.version;\n  status: \"resolved\" | \"clamped-at-minimum-power\" | \"clamped-at-full-power\" | \"no-flash-return\";\n  /** Metered ambient signal in the main exposure: k·M(ambient). */\n  ambientMainExposureMeteredSignal: number;\n  /** Metered flash-only signal per unit full power: M(preflash − ambient)/p_pre. */\n  flashMeteredSignalPerFullPower: number;\n  /** T·2^FEC. */\n  targetRelativeSignal: number;\n  /** Unclamped solution (T' − k·A)/(F·syncEnergyFactor); null with no flash return. */\n  requiredPowerFraction: number | null;\n  /** Commanded main-flash power fraction (clamped); null with no flash return. */\n  powerFraction: number | null;\n  ambientAloneReachesTarget: boolean;\n  predictedMeteredSignal: number;\n  /** log2(predicted / target); 0 when the solution is within range; null when nothing is predicted. */\n  predictedExposureErrorStops: number | null;\n  effectiveGuideNumberMetersAtIso: number | null;\n  flashRangeAtApertureM: number | null;\n  preFlashInsideMainExposure: false;\n  ambientMeteringModified: false;\n}\n\nconst LINEAR_POLICIES = new Set([\"multi-zone-uniform\", \"center-weighted-radial\", \"spot\"]);\n\nfunction sameZones(a: ExposureMeteringSampleSet, b: ExposureMeteringSampleSet): void {\n  if (a.sceneStateId !== b.sceneStateId || a.samples.length !== b.samples.length ||\n    JSON.stringify(a.captureGeometry) !== JSON.stringify(b.captureGeometry)) {\n    throw new InvalidScientificInputError(\"Ambient and pre-flash measurements must share scene state, geometry and zones.\");\n  }\n  a.samples.forEach((sample, index) => {\n    const other = b.samples[index]!;\n    requireInputObject(sample, \"ambientSampleSet.samples[\" + index + \"]\");\n    requireInputObject(other, \"preFlashSampleSet.samples[\" + index + \"]\");\n    requireInputObject(sample.positionOrientedCaptureUv, \"ambientSampleSet.samples[\" + index + \"].positionOrientedCaptureUv\");\n    requireInputObject(other.positionOrientedCaptureUv, \"preFlashSampleSet.samples[\" + index + \"].positionOrientedCaptureUv\");\n    if (sample.sampleId !== other.sampleId || sample.areaWeight !== other.areaWeight ||\n      sample.positionOrientedCaptureUv.u !== other.positionOrientedCaptureUv.u ||\n      sample.positionOrientedCaptureUv.v !== other.positionOrientedCaptureUv.v) {\n      throw new InvalidScientificInputError(\"Ambient and pre-flash zones must match exactly and in order.\");\n    }\n  });\n}\n\n/**\n * Solves the main-flash power from a pre-flash measurement (manufacturer-independent TTL).\n *\n * The meter is linear for the policies allowed here: M(a + b) = M(a) + M(b).\n * - The pre-flash at power p_pre adds a flash-only signal f_i = pre_i − ambient_i in each zone.\n * - Flash signal is proportional to emitted energy, so at main power p it adds (p/p_pre)·M(f).\n * - With ambient scaled to the main exposure by k, the metered total is k·A + p·F, where\n *   F = M(f)/p_pre.\n * - Setting this equal to the target T' = T·2^FEC gives p = (T' − k·A)/(F·s). Here s is the sync\n *   energy factor (1 for ordinary sync, η·t_e/D for high-speed sync).\n * - p is clamped to [p_min, 1], the guide-number range.\n * Highlight policies are rejected: their weights depend on the signal, so the total is no longer\n * linear in p.\n */\nexport function resolveTtlFlashExposure(input: ResolveTtlFlashExposureInput): CalculationResult<TtlFlashExposure> {\n  requireInputKeys(input, \"resolveTtlFlashExposure\", [\"meteringProfile\", \"ambientSampleSet\", \"preFlashSampleSet\", \"preFlashPowerFraction\", \"ambientScaleToMainExposure\", \"flashExposureCompensationStops\", \"minimumPowerFraction\", \"syncEnergyFactor\", \"guideNumber\"]);\n  requireInputObject(input.ambientSampleSet, \"resolveTtlFlashExposure ambientSampleSet\");\n  requireInputObject(input.preFlashSampleSet, \"resolveTtlFlashExposure preFlashSampleSet\");\n  if (input.guideNumber !== undefined) {\n    requireInputObject(input.guideNumber, \"resolveTtlFlashExposure guideNumber\");\n    rejectUnknownFields(input.guideNumber, [\"fullPowerGuideNumberMetersIso100\", \"iso\", \"apertureFNumber\"], \"resolveTtlFlashExposure guideNumber\");\n  }\n  if (!Array.isArray(input.ambientSampleSet.samples) || !Array.isArray(input.preFlashSampleSet.samples)) {\n    throw new InvalidConfigurationError(\"TTL sample sets must contain sample arrays.\");\n  }\n  const profile = parseExposureMeteringProfile(input.meteringProfile);\n  if (!LINEAR_POLICIES.has(profile.policy.kind)) {\n    throw new InvalidScientificInputError(\n      \"TTL flash requires a spatially linear metering policy (multi-zone-uniform, center-weighted-radial or spot).\"\n    );\n  }\n  sameZones(input.ambientSampleSet, input.preFlashSampleSet);\n  const preFlash = requireFraction(input.preFlashPowerFraction, \"preFlashPowerFraction\");\n  const minimum = requireFraction(input.minimumPowerFraction, \"minimumPowerFraction\");\n  const k = input.ambientScaleToMainExposure;\n  if (typeof k !== \"number\" || !Number.isFinite(k) || k < 0) {\n    throw new InvalidScientificInputError(\"ambientScaleToMainExposure must be a finite number greater than or equal to zero.\");\n  }\n  const fec = input.flashExposureCompensationStops;\n  if (typeof fec !== \"number\" || !Number.isFinite(fec)) {\n    throw new InvalidScientificInputError(\"flashExposureCompensationStops must be finite.\");\n  }\n  const syncFactor = input.syncEnergyFactor === undefined ? 1 : requireFraction(input.syncEnergyFactor, \"syncEnergyFactor\");\n  const flashOnly: ExposureMeteringSampleSet = { ...input.preFlashSampleSet,\n    measurementId: input.preFlashSampleSet.measurementId + \":flash-only\",\n    samples: input.preFlashSampleSet.samples.map((sample, index) => {\n      const difference = sample.relativeLinearSignal - input.ambientSampleSet.samples[index]!.relativeLinearSignal;\n      if (!(difference >= 0)) {\n        throw new InvalidScientificInputError(\"Pre-flash signal must not be below the ambient signal in any zone.\");\n      }\n      return { ...sample, relativeLinearSignal: difference };\n    }) };\n  const ambient = meterRelativeExposure({ profile, sampleSet: input.ambientSampleSet }).value.meteredRelativeSignal;\n  const flashPerFull = meterRelativeExposure({ profile, sampleSet: flashOnly }).value.meteredRelativeSignal / preFlash;\n  const ambientMain = k * ambient;\n  const target = profile.target.targetRelativeSignal * Math.pow(2, fec);\n  const deliveredPerFull = flashPerFull * syncFactor;\n  let status: TtlFlashExposure[\"status\"], required: number | null, power: number | null;\n  if (deliveredPerFull === 0) {\n    status = \"no-flash-return\"; required = null; power = null;\n  } else {\n    required = (target - ambientMain) / deliveredPerFull;\n    power = Math.min(1, Math.max(minimum, required));\n    status = required < minimum ? \"clamped-at-minimum-power\" : required > 1 ? \"clamped-at-full-power\" : \"resolved\";\n  }\n  const predicted = ambientMain + (power ?? 0) * deliveredPerFull;\n  const gn = input.guideNumber;\n  const effectiveGn = gn === undefined || power === null ? null : calculateFlashGuideNumber({\n    fullPowerGuideNumberMetersIso100: gn.fullPowerGuideNumberMetersIso100, powerFraction: power, iso: gn.iso }) * Math.sqrt(syncFactor);\n  return approximationResult({\n    modelId: TTL_FLASH_MODEL.id,\n    modelVersion: TTL_FLASH_MODEL.version,\n    status,\n    ambientMainExposureMeteredSignal: ambientMain,\n    flashMeteredSignalPerFullPower: flashPerFull,\n    targetRelativeSignal: target,\n    requiredPowerFraction: required,\n    powerFraction: power,\n    ambientAloneReachesTarget: ambientMain >= target,\n    predictedMeteredSignal: predicted,\n    predictedExposureErrorStops: predicted > 0 ? Math.log2(predicted / target) : null,\n    effectiveGuideNumberMetersAtIso: effectiveGn,\n    flashRangeAtApertureM: effectiveGn === null || gn === undefined ? null : effectiveGn / requirePositive(gn.apertureFNumber, \"apertureFNumber\"),\n    preFlashInsideMainExposure: false,\n    ambientMeteringModified: false\n  }, TTL_FLASH_MODEL.id, TTL_FLASH_MODEL.version, [\n    \"Relative pre-exposure meter signals only; no calibrated flash energy, subject reflectance or distance is inferred.\",\n    \"Flash signal is assumed proportional to emitted energy and fully inside the main exposure (pulse) or each line's slit (HSS factor).\",\n    \"The pre-flash precedes the main exposure; subject motion and ambient change between pre-flash and exposure are not modeled.\",\n    \"This is a generic linear pre-flash solution, not any manufacturer's TTL algorithm, zone weighting or flash protocol.\"\n  ]);\n}\n\n/**\n * Returns a copy of a manual flash profile with its relative output scaled by a resolved TTL power\n * fraction, ready for resolveManualFlashSync (front/rear curtain). For high-speed sync, instead pass\n * the unscaled profile, and pass `ttl.powerFraction` as resolveHighSpeedFlashSync's powerFraction.\n * That way power is applied only once.\n */\nexport function createTtlScaledFlashProfile(flashProfile: ManualFlashProfile, ttl: TtlFlashExposure): ManualFlashProfile {\n  const flash = parseManualFlashProfile(flashProfile);\n  requireInputObject(ttl, \"createTtlScaledFlashProfile ttl\");\n  if (ttl.powerFraction === null || typeof ttl.powerFraction !== \"number\") {\n    throw new InvalidScientificInputError(\"TTL found no flash return; there is no power fraction to apply.\");\n  }\n  return { ...flash, outputControl: { ...flash.outputControl, scale: flash.outputControl.scale * ttl.powerFraction } };\n}\n"]}

package/dist/exposure/flash.js

@@ -20,7 +20,7 @@ import { parseEvidenceList } from "../core/evidence-provenance.js";
 import { InvalidScientificInputError } from "../core/validation.js";
 import { parseSceneIlluminationProfile } from "../schema/illumination.js";
 import { parseSceneIlluminationTemporalProfile } from "../schema/illumination-temporal.js";
-import { requireInputObject, requireInputKeys, rejectUnknownFields } from "../core/record-validation.js";
+import { requireInputObject, requireInputKeys, requireConfigRecord as requireRecord, requireTrimmedConfigString as requireNonEmptyString, requireConfigFinite as requireFinite, parseConfigLimitations as parseLimitations, requireConfigFiniteAboveZero as requirePositiveFinite } from "../core/record-validation.js";
 export const MANUAL_FLASH_PROFILE_SCHEMA_VERSION = "0.1.0";
 export const FLASH_SYNC_CAPABILITY_SCHEMA_VERSION = "0.1.0";
 /** Sync-capability schema that may declare high-speed sync (a fast pulse train that acts as continuous light). */
@@ -34,54 +34,6 @@ const ORDINARY_SYNC_MODES = new Set([
     "front-curtain",
     "rear-curtain"
 ]);
-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) {
-    if (typeof value !== "string" ||
-        value.trim().length === 0) {
-        throw new InvalidConfigurationError(path +
-            " must be a non-empty string.");
-    }
-    return value.trim();
-}
-function requireFinite(value, path) {
-    if (typeof value !== "number" ||
-        !Number.isFinite(value)) {
-        throw new InvalidConfigurationError(path + " must be finite.");
-    }
-    return value;
-}
-function requirePositiveFinite(value, path) {
-    const parsed = requireFinite(value, path);
-    if (parsed <= 0) {
-        throw new InvalidConfigurationError(path +
-            " must be greater than zero.");
-    }
-    return parsed;
-}
-function parseLimitations(value, path) {
-    if (!Array.isArray(value)) {
-        throw new InvalidConfigurationError(path + " must be an array.");
-    }
-    const parsed = value.map((entry, index) => requireNonEmptyString(entry, path +
-        "[" +
-        index +
-        "]"));
-    if (new Set(parsed).size !==
-        parsed.length) {
-        throw new InvalidConfigurationError(path +
-            " must not contain duplicates.");
-    }
-    return parsed;
-}
 function parsePulseSamples(value, supportDurationSeconds, path) {
     if (!Array.isArray(value) ||
         value.length < 2) {