@photivra/engine 1.4.0 → 2.0.0

package/dist/exposure/flash.d.ts

@@ -5,6 +5,13 @@ import { type SceneIlluminationTemporalProfile, type SceneIlluminationTemporalWa
 import type { ResolvedCaptureModeTiming } from "../sensor/capture-mode-timing.js";
 export declare const MANUAL_FLASH_PROFILE_SCHEMA_VERSION: "0.1.0";
 export declare 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). */
+export declare const FLASH_SYNC_CAPABILITY_HSS_SCHEMA_VERSION: "0.2.0";
+/** Model identity of the pulsed quasi-continuous high-speed-sync burst. */
+export declare const HIGH_SPEED_SYNC_MODEL: Readonly<{
+    readonly id: "flash-hss-quasi-continuous-burst";
+    readonly version: "1.0.0";
+}>;
 export type ManualFlashSyncMode = "front-curtain" | "rear-curtain";
 export type RequestedFlashSyncMode = ManualFlashSyncMode | "high-speed-sync";
 export interface ManualFlashPulseProfile {
@@ -38,13 +45,24 @@ export interface ManualFlashProfile {
     limitations: readonly string[];
 }
 export interface FlashSyncCapabilityProfile {
-    schemaVersion: typeof FLASH_SYNC_CAPABILITY_SCHEMA_VERSION;
+    schemaVersion: typeof FLASH_SYNC_CAPABILITY_SCHEMA_VERSION | typeof FLASH_SYNC_CAPABILITY_HSS_SCHEMA_VERSION;
     profileId: string;
     profileVersion: string;
     captureModeId: string;
     timingProfileId: string;
     supportedOrdinarySyncModes: readonly ManualFlashSyncMode[];
-    highSpeedSyncSupported: false;
+    /** Schema 0.1.0 is always false; schema 0.2.0 may declare HSS with {@link highSpeedSync}. */
+    highSpeedSyncSupported: boolean;
+    /** Present exactly when highSpeedSyncSupported is true (schema 0.2.0). */
+    highSpeedSync?: {
+        /**
+         * η: energy of one full-power high-speed-sync burst, as a fraction of one full-power ordinary
+         * pulse, in (0, 1]. The caller declares it from evidence (capacitor and thermal limits). It is
+         * never inferred.
+         */
+        burstEnergyFractionOfFullPulse: number;
+        evidence: readonly EvidenceProvenance[];
+    };
     ordinarySyncRequiresWholeActiveFrameSimultaneouslyExposed: true;
     evidence: readonly EvidenceProvenance[];
     limitations: readonly string[];
@@ -95,11 +113,13 @@ export interface ResolvedManualFlashSync {
     evidence: readonly EvidenceProvenance[];
     limitations: readonly string[];
 }
+/** Fields of a resolved sync (ordinary or HSS) needed to register a flash overlay. */
+export type FlashOverlaySyncRegistration = Pick<ResolvedManualFlashSync, "flashEnabled" | "flashProfileId" | "flashProfileVersion" | "sourceId" | "waveformTimeZeroSecondsFromCaptureReference" | "evidence">;
 export interface CreateManualFlashIlluminationOverlayInput {
     baseIlluminationProfile: SceneIlluminationProfile;
     baseTemporalProfile?: SceneIlluminationTemporalProfile;
     flashProfile: ManualFlashProfile;
-    resolvedSync: ResolvedManualFlashSync;
+    resolvedSync: FlashOverlaySyncRegistration;
     illuminationProfileId: string;
     temporalProfileId: string;
 }
@@ -121,59 +141,147 @@ export interface ManualFlashIlluminationOverlay {
     ambientTemporalBehaviorPreserved: true;
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
- * Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
- * are unsupported here; source magnitude, optical transport and sensor integration retain their own
- * contracts.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns ManualFlashProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+ * opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+ * frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+ * brightness, optical transport and sensor integration have their own contracts.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns ManualFlashProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function parseManualFlashProfile(value: unknown): ManualFlashProfile;
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
- * Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
- * are unsupported here; source magnitude, optical transport and sensor integration retain their own
- * contracts.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns FlashSyncCapabilityProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+ * opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+ * frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+ * brightness, optical transport and sensor integration have their own contracts.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns FlashSyncCapabilityProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function parseFlashSyncCapabilityProfile(value: unknown): FlashSyncCapabilityProfile;
 /**
- * Place a declared ordinary flash pulse into the actual whole-frame exposure opening interval for
- * front or rear sync, or return structured incompatibility.
+ * Places a declared ordinary flash pulse inside the actual interval when the whole frame is open, for
+ * front- or rear-curtain sync. Otherwise returns a structured incompatibility.
  *
- * Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
- * Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
- * are unsupported here; source magnitude, optical transport and sensor integration retain their own
- * contracts.
- * @param input - ResolveManualFlashSyncInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ResolvedManualFlashSync. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+ * opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+ * frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+ * brightness, optical transport and sensor integration have their own contracts.
+ * @param input - ResolveManualFlashSyncInput. See that type for coordinates, units and profile binding.
+ * @returns ResolvedManualFlashSync. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function resolveManualFlashSync(input: ResolveManualFlashSyncInput): ResolvedManualFlashSync;
 /**
- * Construct an owned registered temporal illumination overlay from the resolved manual pulse while
- * preserving base ambient source identity.
+ * Builds a temporal illumination overlay from the resolved manual pulse. The identity of the base
+ * ambient light source is kept.
  *
- * Manual flash is a registered relative pulse/source overlay on the capture opening-reference clock.
- * Ordinary front/rear sync requires a real whole-frame opening interval. HSS/TTL and flash metering
- * are unsupported here; source magnitude, optical transport and sensor integration retain their own
- * contracts.
- * @param input - CreateManualFlashIlluminationOverlayInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ManualFlashIlluminationOverlay. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * Manual flash is a relative light pulse added on top of the scene light, timed on the capture's
+ * opening-reference clock. Ordinary front- or rear-curtain sync needs a real interval when the whole
+ * frame is open at once. High-speed sync (HSS), TTL and flash metering are not handled here. Source
+ * brightness, optical transport and sensor integration have their own contracts.
+ * @param input - CreateManualFlashIlluminationOverlayInput. See that type for coordinates, units and profile binding.
+ * @returns ManualFlashIlluminationOverlay. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function createManualFlashIlluminationOverlay(input: CreateManualFlashIlluminationOverlayInput): ManualFlashIlluminationOverlay;
-//# sourceMappingURL=flash.d.ts.map
+export interface ResolveHighSpeedFlashSyncInput {
+    flashEnabled: boolean;
+    /** Ordinary full-power pulse definition; its integral defines the full-power pulse energy. */
+    flashProfile: ManualFlashProfile;
+    /** Schema 0.2.0 profile with highSpeedSyncSupported true. */
+    syncCapabilities: FlashSyncCapabilityProfile;
+    timing: ResolvedCaptureModeTiming;
+    /** Commanded output as a fraction of full power, (0, 1]. */
+    powerFraction: number;
+    releaseFrame?: ResolvedReleaseFrame;
+}
+export interface ResolvedHighSpeedFlashSync extends FlashOverlaySyncRegistration {
+    modelId: typeof HIGH_SPEED_SYNC_MODEL.id;
+    modelVersion: typeof HIGH_SPEED_SYNC_MODEL.version;
+    syncMode: "high-speed-sync";
+    syncStatus: "disabled" | "high-speed-sync-resolved";
+    captureModeId: string;
+    timingProfileId: string;
+    syncCapabilityProfileId: string;
+    timeReference: "first-opening-boundary-phase";
+    powerFraction: number;
+    /** η from the sync capability profile. */
+    burstEnergyFractionOfFullPulse: number;
+    /** ∫ pulse(t) dt of the declared ordinary pulse, whose relative peak is 1 (relative multiplier · s). */
+    singlePulseIntegratedRelativeSeconds: number;
+    /** D: burst support covering the first line opening to the last line closing. */
+    burstStartSecondsFromCaptureReference: number;
+    burstEndSecondsFromCaptureReference: number;
+    burstDurationSeconds: number;
+    /** Local (slit) exposure durations t_e over the active frame. */
+    localExposureDurationRangeSeconds: {
+        minimum: number;
+        maximum: number;
+    };
+    /** Flash energy each line receives relative to one ordinary pulse at the same power: η·t_e/D. */
+    energyFractionOfSinglePulseRange: {
+        minimum: number;
+        maximum: number;
+    };
+    /** Effective guide-number factor relative to the same-power ordinary pulse: √(η·t_e/D). */
+    guideNumberFactorRange: {
+        minimum: number;
+        maximum: number;
+    };
+    uniformAcrossActiveFrame: boolean;
+    /** The rectangular high-speed-sync burst, written as a manual pulse profile for the illumination overlay. */
+    burstFlashProfile: ManualFlashProfile | null;
+    releaseFrameBinding: {
+        sequenceId: string;
+        releaseFrameId: string;
+        frameIndex: number;
+        sceneTimeSecondsFromSequenceStartAtBurstStart: number;
+        sceneTimeSecondsFromSequenceStartAtBurstEnd: number;
+    } | null;
+    hssModeled: true;
+    ttlModeled: false;
+    sensorReadoutTimingUsedAsExposureTiming: false;
+    limitations: readonly string[];
+}
+/**
+ * Resolves high-speed (focal-plane) sync (HSS): a fast pulse train that acts as continuous light and
+ * covers the whole travelling-slit exposure.
+ *
+ * At shutter speeds faster than the ordinary sync limit, the shutter's opening and closing edges
+ * cross the frame as a slit, and the whole frame is never open at once. A single short pulse would
+ * light only a band.
+ *
+ * HSS instead fires a rapid pulse train. It behaves like constant output P over the burst D, from
+ * the first line opening to the last line closing. Each line collects P·t_e over its slit time t_e.
+ * - The burst energy is E_burst = η·p·E_pulse. η comes from the sync profile, p is the power
+ *   fraction and E_pulse is the energy of an ordinary full-power pulse.
+ * - So P = E_burst/D, and each line receives η·p·E_pulse·t_e/D.
+ * - Exposure ∝ GN² (inverse-square law, GN = d·N). So, relative to an ordinary pulse at the same
+ *   power, the effective guide number is GN_HSS/GN = √(η·t_e/D).
+ * Shortening t_e by one stop therefore costs half a stop of guide number.
+ *
+ * Approximations: the pulse train is treated as continuous (pulse period ≪ t_e). Recycle and thermal
+ * limits are folded into η. Front/rear-curtain placement does not apply, because the burst covers
+ * the whole exposure.
+ * @see docs/SCENE_SENSOR_TEMPORAL_EXPOSURE.md#high-speed-sync
+ */
+export declare function resolveHighSpeedFlashSync(input: ResolveHighSpeedFlashSyncInput): ResolvedHighSpeedFlashSync;
+/**
+ * Registers a resolved high-speed-sync burst as a temporal illumination overlay: a rectangular
+ * waveform over [0, D]. Each line then collects the burst over its own local exposure window.
+ */
+export declare function createHighSpeedSyncIlluminationOverlay(input: Omit<CreateManualFlashIlluminationOverlayInput, "resolvedSync"> & {
+    resolvedSync: ResolvedHighSpeedFlashSync;
+}): ManualFlashIlluminationOverlay;