@photivra/engine 1.5.0 → 2.1.0

package/dist/exposure/exposure.js

@@ -1,14 +1,17 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Calculates EV100 from aperture and shutter duration.
- * Compares image-plane optical exposure using the proportional relation shutterSeconds / aperture^2.
- * This does not include scene light, lens transmission, vignetting, or sensor response and therefore
- * must not be interpreted as a photon-count result.
- * @see docs/USAGE.md for equations, coordinate/unit conventions, blockers and support limits.
+ * Basic exposure relations.
+ * - EV100: exposure value from aperture and shutter duration.
+ * - Relative optical exposure at the image plane, from shutterSeconds / aperture^2.
+ * - Relative rendering exposure, which also includes nominal ISO gain.
+ * These do not include scene light, lens transmission, vignetting or sensor response. Do not read
+ * them as photon counts.
+ * @see docs/USAGE.md for the equations, units, coordinate conventions, known blockers and support
+ * limits.
  */
 import { calculatedResult } from "../core/calculation-result.js";
 import { requirePositiveFinite } from "../core/validation.js";
+import { requireInputKeys } from "../core/record-validation.js";
 /**
  * Calculates EV100 from aperture and shutter duration.
  *
@@ -16,6 +19,7 @@ import { requirePositiveFinite } from "../core/validation.js";
  * @returns EV100 value.
  */
 export function calculateExposureValue100(input) {
+    requireInputKeys(input, "calculateExposureValue100", ["aperture", "shutterSeconds"]);
     requirePositiveFinite("aperture", input.aperture);
     requirePositiveFinite("shutterSeconds", input.shutterSeconds);
     return calculatedResult(Math.log2((input.aperture * input.aperture) / input.shutterSeconds), "exposure-value-100", "1.0.0", ["Lens transmission (T-stop) is not modeled"]);
@@ -24,10 +28,11 @@ export function calculateExposureValue100(input) {
  * Compares image-plane optical exposure using the proportional relation
  * shutterSeconds / aperture^2.
  *
- * This does not include scene light, lens transmission, vignetting, or sensor
- * response and therefore must not be interpreted as a photon-count result.
+ * This does not include scene light, lens transmission, vignetting or sensor
+ * response. Do not read it as a photon count.
  */
 export function calculateRelativeOpticalExposure(input) {
+    requireInputKeys(input, "calculateRelativeOpticalExposure", ["aperture", "shutterSeconds", "referenceAperture", "referenceShutterSeconds"]);
     requirePositiveFinite("aperture", input.aperture);
     requirePositiveFinite("shutterSeconds", input.shutterSeconds);
     requirePositiveFinite("referenceAperture", input.referenceAperture);
@@ -49,15 +54,16 @@ export function calculateRelativeOpticalExposure(input) {
  * Calculates a relative linear rendering exposure from aperture, shutter, and
  * nominal ISO gain.
  *
- * This relation is intended for deterministic educational rendering relative to
- * a declared reference exposure. ISO is treated as a brightness/gain control;
- * it does not create photons and this function does not model sensor noise,
- * clipping, tone mapping, lens transmission, or absolute scene luminance.
+ * This relation is for deterministic educational rendering, relative to a
+ * declared reference exposure. ISO is treated as a brightness (gain) control;
+ * it does not create photons. This function does not model sensor noise,
+ * clipping, tone mapping, lens transmission or absolute scene luminance.
  *
  * @param input Current and reference aperture/shutter/ISO settings.
  * @returns Relative rendering factor and stop difference.
  */
 export function calculateRelativeRenderedExposure(input) {
+    requireInputKeys(input, "calculateRelativeRenderedExposure", ["aperture", "shutterSeconds", "iso", "referenceAperture", "referenceShutterSeconds", "referenceIso"]);
     requirePositiveFinite("iso", input.iso);
     requirePositiveFinite("referenceIso", input.referenceIso);
     const optical = calculateRelativeOpticalExposure({
@@ -81,13 +87,14 @@ export function calculateRelativeRenderedExposure(input) {
     ]);
 }
 /**
- * Calculates the ISO/gain setting that preserves nominal rendered exposure
- * after changing aperture and/or shutter, assuming all other factors remain
- * constant.
+ * Calculates the ISO (gain) setting that keeps the nominal rendered exposure
+ * the same after aperture, shutter or both change. Assumes nothing else
+ * changes.
  *
  * This is an exposure-compensation relation, not a sensor-noise model.
  */
 export function calculateEquivalentIso(input) {
+    requireInputKeys(input, "calculateEquivalentIso", ["baseIso", "baseAperture", "baseShutterSeconds", "aperture", "shutterSeconds"]);
     requirePositiveFinite("baseIso", input.baseIso);
     requirePositiveFinite("baseAperture", input.baseAperture);
     requirePositiveFinite("baseShutterSeconds", input.baseShutterSeconds);

package/dist/exposure/exposure.js.map

@@ -1 +1 @@
-{"version":3,"file":"exposure.js","sourceRoot":"","sources":["../../src/exposure/exposure.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"exposure.js","sourceRoot":"","sources":["../../src/exposure/exposure.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Basic exposure relations.\n * - EV100: exposure value from aperture and shutter duration.\n * - Relative optical exposure at the image plane, from shutterSeconds / aperture^2.\n * - Relative rendering exposure, which also includes nominal ISO gain.\n * These do not include scene light, lens transmission, vignetting or sensor response. Do not read\n * them as photon counts.\n * @see docs/USAGE.md for the equations, units, coordinate conventions, known blockers and support\n * limits.\n */\n\nimport {\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport { requirePositiveFinite } from \"../core/validation.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\nexport interface CalculateExposureValue100Input {\n  /** F-number. */\n  aperture: number;\n  /** Shutter duration in seconds. */\n  shutterSeconds: number;\n}\n\n/**\n * Calculates EV100 from aperture and shutter duration.\n *\n * @param input Aperture and shutter duration.\n * @returns EV100 value.\n */\nexport function calculateExposureValue100(\n  input: CalculateExposureValue100Input\n): CalculationResult<number> {\n  requireInputKeys(input, \"calculateExposureValue100\", [\"aperture\", \"shutterSeconds\"]);\n  requirePositiveFinite(\"aperture\", input.aperture);\n  requirePositiveFinite(\"shutterSeconds\", input.shutterSeconds);\n\n  return calculatedResult(\n    Math.log2((input.aperture * input.aperture) / input.shutterSeconds),\n    \"exposure-value-100\",\n    \"1.0.0\",\n    [\"Lens transmission (T-stop) is not modeled\"]\n  );\n}\n\nexport interface CalculateRelativeOpticalExposureInput {\n  aperture: number;\n  shutterSeconds: number;\n  referenceAperture: number;\n  referenceShutterSeconds: number;\n}\n\nexport interface RelativeOpticalExposure {\n  /** Relative light exposure at the image plane; 1 equals the reference. */\n  factor: number;\n  /** Difference from the reference in stops. Positive means more light exposure. */\n  stops: number;\n}\n\n/**\n * Compares image-plane optical exposure using the proportional relation\n * shutterSeconds / aperture^2.\n *\n * This does not include scene light, lens transmission, vignetting or sensor\n * response. Do not read it as a photon count.\n */\nexport function calculateRelativeOpticalExposure(\n  input: CalculateRelativeOpticalExposureInput\n): CalculationResult<RelativeOpticalExposure> {\n  requireInputKeys(input, \"calculateRelativeOpticalExposure\", [\"aperture\", \"shutterSeconds\", \"referenceAperture\", \"referenceShutterSeconds\"]);\n  requirePositiveFinite(\"aperture\", input.aperture);\n  requirePositiveFinite(\"shutterSeconds\", input.shutterSeconds);\n  requirePositiveFinite(\"referenceAperture\", input.referenceAperture);\n  requirePositiveFinite(\n    \"referenceShutterSeconds\",\n    input.referenceShutterSeconds\n  );\n\n  const current =\n    input.shutterSeconds / (input.aperture * input.aperture);\n  const reference =\n    input.referenceShutterSeconds /\n    (input.referenceAperture * input.referenceAperture);\n  const factor = current / reference;\n\n  return calculatedResult(\n    {\n      factor,\n      stops: Math.log2(factor)\n    },\n    \"relative-optical-exposure\",\n    \"1.0.0\",\n    [\n      \"Constant scene illumination\",\n      \"Lens transmission is not modeled\",\n      \"Sensor response is not modeled\"\n    ]\n  );\n}\n\nexport interface CalculateRelativeRenderedExposureInput {\n  aperture: number;\n  shutterSeconds: number;\n  iso: number;\n  referenceAperture: number;\n  referenceShutterSeconds: number;\n  referenceIso: number;\n}\n\nexport interface RelativeRenderedExposure {\n  /** Nominal linear rendering multiplier; 1 equals the reference settings. */\n  factor: number;\n  /** Difference from the reference in stops. Positive means a brighter rendering. */\n  stops: number;\n  /** Image-plane optical exposure ratio before nominal ISO gain. */\n  opticalFactor: number;\n  /** Nominal ISO gain ratio relative to the reference ISO. */\n  isoGainFactor: number;\n}\n\n/**\n * Calculates a relative linear rendering exposure from aperture, shutter, and\n * nominal ISO gain.\n *\n * This relation is for deterministic educational rendering, relative to a\n * declared reference exposure. ISO is treated as a brightness (gain) control;\n * it does not create photons. This function does not model sensor noise,\n * clipping, tone mapping, lens transmission or absolute scene luminance.\n *\n * @param input Current and reference aperture/shutter/ISO settings.\n * @returns Relative rendering factor and stop difference.\n */\nexport function calculateRelativeRenderedExposure(\n  input: CalculateRelativeRenderedExposureInput\n): CalculationResult<RelativeRenderedExposure> {\n  requireInputKeys(input, \"calculateRelativeRenderedExposure\", [\"aperture\", \"shutterSeconds\", \"iso\", \"referenceAperture\", \"referenceShutterSeconds\", \"referenceIso\"]);\n  requirePositiveFinite(\"iso\", input.iso);\n  requirePositiveFinite(\"referenceIso\", input.referenceIso);\n\n  const optical = calculateRelativeOpticalExposure({\n    aperture: input.aperture,\n    shutterSeconds: input.shutterSeconds,\n    referenceAperture: input.referenceAperture,\n    referenceShutterSeconds: input.referenceShutterSeconds\n  });\n  const isoGainFactor = input.iso / input.referenceIso;\n  const factor = optical.value.factor * isoGainFactor;\n\n  return calculatedResult(\n    {\n      factor,\n      stops: Math.log2(factor),\n      opticalFactor: optical.value.factor,\n      isoGainFactor\n    },\n    \"relative-rendered-exposure\",\n    \"1.0.0\",\n    [\n      \"Constant scene illumination\",\n      \"ISO is treated as nominal rendering gain, not photon creation\",\n      \"Lens transmission and sensor-specific gain behavior are not modeled\",\n      \"Clipping and display tone mapping are not modeled\"\n    ]\n  );\n}\n\nexport interface CalculateEquivalentIsoInput {\n  baseIso: number;\n  baseAperture: number;\n  baseShutterSeconds: number;\n  aperture: number;\n  shutterSeconds: number;\n}\n\n/**\n * Calculates the ISO (gain) setting that keeps the nominal rendered exposure\n * the same after aperture, shutter or both change. Assumes nothing else\n * changes.\n *\n * This is an exposure-compensation relation, not a sensor-noise model.\n */\nexport function calculateEquivalentIso(\n  input: CalculateEquivalentIsoInput\n): CalculationResult<number> {\n  requireInputKeys(input, \"calculateEquivalentIso\", [\"baseIso\", \"baseAperture\", \"baseShutterSeconds\", \"aperture\", \"shutterSeconds\"]);\n  requirePositiveFinite(\"baseIso\", input.baseIso);\n  requirePositiveFinite(\"baseAperture\", input.baseAperture);\n  requirePositiveFinite(\"baseShutterSeconds\", input.baseShutterSeconds);\n  requirePositiveFinite(\"aperture\", input.aperture);\n  requirePositiveFinite(\"shutterSeconds\", input.shutterSeconds);\n\n  const baseLight =\n    input.baseShutterSeconds /\n    (input.baseAperture * input.baseAperture);\n  const newLight =\n    input.shutterSeconds / (input.aperture * input.aperture);\n\n  return calculatedResult(\n    input.baseIso * (baseLight / newLight),\n    \"equivalent-iso-compensation\",\n    \"1.0.0\",\n    [\n      \"Constant scene illumination\",\n      \"ISO is treated as gain/brightness compensation, not photon creation\",\n      \"Lens transmission and sensor-specific gain behavior are not modeled\"\n    ]\n  );\n}\n"]}

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

@@ -0,0 +1,135 @@
+/**
+ * Flash guide numbers, and through-the-lens (TTL) flash exposure with a pre-flash that does not
+ * depend on any manufacturer.
+ *
+ * How TTL works here:
+ * 1. The pre-flash is measured with the existing relative exposure meter.
+ * 2. The solved power fraction is applied to a ManualFlashProfile.
+ * 3. That pulse is placed by the existing front/rear-curtain sync (resolveManualFlashSync) or by
+ *    high-speed sync (resolveHighSpeedFlashSync).
+ * Flash metering stays separate from ambient metering. The ambient meter result is an input and is
+ * not changed. No vendor's TTL algorithm, zone weighting table or flash protocol is copied.
+ * @see docs/SCENE_SENSOR_TEMPORAL_EXPOSURE.md#flash-guide-number-ttl-and-high-speed-sync
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type ManualFlashProfile } from "./flash.js";
+import { type ExposureMeteringProfile, type ExposureMeteringSampleSet } from "./metering.js";
+export declare const TTL_FLASH_MODEL: Readonly<{
+    readonly id: "preflash-linear-ttl";
+    readonly version: "1.0.0";
+}>;
+export interface FlashGuideNumberInput {
+    /** Guide number at full power for ISO 100, in metres (GN = distance · f-number). */
+    fullPowerGuideNumberMetersIso100: number;
+    /** Output as a fraction of full power, (0, 1]. */
+    powerFraction: number;
+    iso: number;
+}
+/**
+ * Effective guide number GN = GN_full · √p · √(ISO/100).
+ *
+ * The guide number relation GN = d·N follows from the inverse-square law. Light on the subject from a
+ * point-like flash falls as 1/d², and sensor exposure falls as 1/N². So exposure stays correct while
+ * d·N is constant (camera equation H = 0.65·L·t/N² and reference exposure H = 10/S, CIPA DC-004-2020,
+ * free). Exposure grows linearly with emitted energy (power fraction p), and the exposure needed falls
+ * inversely with ISO speed. So GN ∝ √p·√ISO. The engine does not model how a guide number is measured;
+ * the caller supplies it.
+ * @see docs/SCENE_SENSOR_TEMPORAL_EXPOSURE.md for the full derivation.
+ */
+export declare function calculateFlashGuideNumber(input: FlashGuideNumberInput): number;
+export interface FlashPowerForDistanceInput {
+    fullPowerGuideNumberMetersIso100: number;
+    subjectDistanceM: number;
+    apertureFNumber: number;
+    iso: number;
+    /** Lowest available power fraction, (0, 1]. */
+    minimumPowerFraction: number;
+}
+export interface FlashPowerForDistance {
+    /** p = (d·N / (GN_full·√(ISO/100)))², before clamping. */
+    requiredPowerFraction: number;
+    powerFraction: number;
+    status: "within-range" | "clamped-at-minimum-power" | "clamped-at-full-power";
+    /** log2(delivered / required) flash exposure; positive is overexposure. */
+    flashExposureErrorStops: number;
+    /** GN_full·√(ISO/100)/N: the farthest correctly exposed distance at full power. */
+    maximumDistanceM: number;
+}
+/** Manual guide-number exposure: the power fraction that exposes a subject at distance d correctly. */
+export declare function calculateFlashPowerForDistance(input: FlashPowerForDistanceInput): FlashPowerForDistance;
+export interface ResolveTtlFlashExposureInput {
+    /** Spatially linear metering profile (multi-zone-uniform, center-weighted-radial or spot). */
+    meteringProfile: ExposureMeteringProfile;
+    /** Measurement-window samples with the flash off. */
+    ambientSampleSet: ExposureMeteringSampleSet;
+    /** The same zones and settings with the pre-flash fired. */
+    preFlashSampleSet: ExposureMeteringSampleSet;
+    /** Pre-flash output as a fraction of full power, (0, 1]. */
+    preFlashPowerFraction: number;
+    /**
+     * Ratio of ambient light collected in the main exposure to that in the measurement window, at the
+     * same aperture and ISO (for example t_main/t_measure). Must be ≥ 0. The flash pulse falls inside
+     * both windows, so it is not scaled.
+     */
+    ambientScaleToMainExposure: number;
+    /** Flash exposure compensation applied to the TTL target, in stops. */
+    flashExposureCompensationStops: number;
+    /** Lowest available main-flash power fraction, (0, 1]. */
+    minimumPowerFraction: number;
+    /**
+     * Flash energy each line receives, relative to an ordinary pulse at the same power fraction. 1 for
+     * front/rear-curtain sync; η·t_e/D for high-speed sync (see resolveHighSpeedFlashSync). Defaults to 1.
+     */
+    syncEnergyFactor?: number;
+    /** Optional guide-number reporting. */
+    guideNumber?: {
+        fullPowerGuideNumberMetersIso100: number;
+        iso: number;
+        apertureFNumber: number;
+    };
+}
+export interface TtlFlashExposure {
+    modelId: typeof TTL_FLASH_MODEL.id;
+    modelVersion: typeof TTL_FLASH_MODEL.version;
+    status: "resolved" | "clamped-at-minimum-power" | "clamped-at-full-power" | "no-flash-return";
+    /** Metered ambient signal in the main exposure: k·M(ambient). */
+    ambientMainExposureMeteredSignal: number;
+    /** Metered flash-only signal per unit full power: M(preflash − ambient)/p_pre. */
+    flashMeteredSignalPerFullPower: number;
+    /** T·2^FEC. */
+    targetRelativeSignal: number;
+    /** Unclamped solution (T' − k·A)/(F·syncEnergyFactor); null with no flash return. */
+    requiredPowerFraction: number | null;
+    /** Commanded main-flash power fraction (clamped); null with no flash return. */
+    powerFraction: number | null;
+    ambientAloneReachesTarget: boolean;
+    predictedMeteredSignal: number;
+    /** log2(predicted / target); 0 when the solution is within range; null when nothing is predicted. */
+    predictedExposureErrorStops: number | null;
+    effectiveGuideNumberMetersAtIso: number | null;
+    flashRangeAtApertureM: number | null;
+    preFlashInsideMainExposure: false;
+    ambientMeteringModified: false;
+}
+/**
+ * Solves the main-flash power from a pre-flash measurement (manufacturer-independent TTL).
+ *
+ * The meter is linear for the policies allowed here: M(a + b) = M(a) + M(b).
+ * - The pre-flash at power p_pre adds a flash-only signal f_i = pre_i − ambient_i in each zone.
+ * - Flash signal is proportional to emitted energy, so at main power p it adds (p/p_pre)·M(f).
+ * - With ambient scaled to the main exposure by k, the metered total is k·A + p·F, where
+ *   F = M(f)/p_pre.
+ * - Setting this equal to the target T' = T·2^FEC gives p = (T' − k·A)/(F·s). Here s is the sync
+ *   energy factor (1 for ordinary sync, η·t_e/D for high-speed sync).
+ * - p is clamped to [p_min, 1], the guide-number range.
+ * Highlight policies are rejected: their weights depend on the signal, so the total is no longer
+ * linear in p.
+ */
+export declare function resolveTtlFlashExposure(input: ResolveTtlFlashExposureInput): CalculationResult<TtlFlashExposure>;
+/**
+ * Returns a copy of a manual flash profile with its relative output scaled by a resolved TTL power
+ * fraction, ready for resolveManualFlashSync (front/rear curtain). For high-speed sync, instead pass
+ * the unscaled profile, and pass `ttl.powerFraction` as resolveHighSpeedFlashSync's powerFraction.
+ * That way power is applied only once.
+ */
+export declare function createTtlScaledFlashProfile(flashProfile: ManualFlashProfile, ttl: TtlFlashExposure): ManualFlashProfile;

package/dist/exposure/flash-ttl.js

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

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

@@ -0,0 +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 = 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"]}