@photivra/engine 0.5.1 → 1.0.0

package/dist/exposure/metering-temporal.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Module boundary and integration notes.
+ * Meters a declared weighted time-average of scene-radiance-derived relative pre-exposure samples.
+ * Every temporal sample must already be explicitly bound to one #85 temporal illumination profile and
+ * one capture time in the first-opening-boundary-phase reference. Spatial metering is performed first
+ * in the same declared profile, then those scalar pre-exposure measurements are combined linearly by
+ * caller-declared normalized time weights.
+ * @see docs/USAGE.md for equations, coordinate/unit conventions, blockers and support limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type ExposureMeteringPolicy, type ExposureMeteringProfile } from "./metering.js";
+import type { SceneRadianceDerivedExposureMeteringSampleSet } from "./metering-scene-radiance.js";
+export interface SceneRadianceTemporalMeteringSample {
+    normalizedTimeWeight: number;
+    sampleSet: SceneRadianceDerivedExposureMeteringSampleSet;
+}
+export interface MeterSceneRadianceTemporalExposureInput {
+    temporalMeasurementId: string;
+    profile: ExposureMeteringProfile;
+    policy: {
+        kind: "weighted-time-average";
+        timeReference: "first-opening-boundary-phase";
+    };
+    temporalSamples: readonly SceneRadianceTemporalMeteringSample[];
+}
+interface SceneRadianceTemporalExposureMeteringResultBase {
+    temporalMeasurementId: string;
+    sceneStateId: string;
+    profileId: string;
+    scientificStatus: "approximation";
+    inputDomain: "relative-pre-exposure-linear-signal";
+    captureRegion: "oriented-active-capture";
+    spatialPolicyKind: ExposureMeteringPolicy["kind"];
+    temporalPolicyKind: "weighted-time-average";
+    timeReference: "first-opening-boundary-phase";
+    temporalSampleCount: number;
+    normalizedTimeWeightSum: number;
+    captureTimeRangeSecondsFromReference: {
+        minimum: number;
+        maximum: number;
+    };
+    targetRelativeSignal: number;
+    meteredRelativeSignal: number;
+    outputCropUsedForMetering: false;
+    exposureCompensationApplied: false;
+    finalToneMappingUsed: false;
+    displayGammaUsed: false;
+    calibratedLuminanceClaimAuthorized: false;
+    calibratedSceneRadianceClaimAuthorized: false;
+    automaticExposureResolved: false;
+    resultReusableForAeLock: true;
+    temporalAveragingExplicit: true;
+    flashTtlMeteringPerformed: false;
+}
+export type SceneRadianceTemporalExposureMeteringResult = (SceneRadianceTemporalExposureMeteringResultBase & {
+    status: "resolved";
+    requiredExposureScaleToTarget: number;
+    exposureOffsetStopsToTarget: number;
+}) | (SceneRadianceTemporalExposureMeteringResultBase & {
+    status: "no-signal";
+    requiredExposureScaleResolved: false;
+    exposureOffsetStopsResolved: false;
+});
+/**
+ * Meters a declared weighted time-average of scene-radiance-derived relative
+ * pre-exposure samples.
+ *
+ * Every temporal sample must already be explicitly bound to one #85 temporal
+ * illumination profile and one capture time in the
+ * first-opening-boundary-phase reference. Spatial metering is performed first
+ * in the same declared profile, then those scalar pre-exposure measurements are
+ * combined linearly by caller-declared normalized time weights.
+ */
+export declare function meterSceneRadianceTemporalExposure(input: MeterSceneRadianceTemporalExposureInput): CalculationResult<SceneRadianceTemporalExposureMeteringResult>;
+export {};
+//# sourceMappingURL=metering-temporal.d.ts.map

package/dist/exposure/metering-temporal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metering-temporal.d.ts","sourceRoot":"","sources":["../../src/exposure/metering-temporal.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC7B,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EACV,6CAA6C,EAC9C,MAAM,8BAA8B,CAAC;AAKtC,MAAM,WAAW,mCAAmC;IAClD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,SAAS,EACP,6CAA6C,CAAC;CACjD;AAED,MAAM,WAAW,uCAAuC;IACtD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE;QACN,IAAI,EAAE,uBAAuB,CAAC;QAC9B,aAAa,EACX,8BAA8B,CAAC;KAClC,CAAC;IACF,eAAe,EACb,SAAS,mCAAmC,EAAE,CAAC;CAClD;AAED,UAAU,+CAA+C;IACvD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,eAAe,CAAC;IAClC,WAAW,EACT,qCAAqC,CAAC;IACxC,aAAa,EACX,yBAAyB,CAAC;IAC5B,iBAAiB,EACf,sBAAsB,CAAC,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAChB,uBAAuB,CAAC;IAC1B,aAAa,EACX,8BAA8B,CAAC;IACjC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uBAAuB,EAAE,MAAM,CAAC;IAChC,oCAAoC,EAAE;QACpC,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,yBAAyB,EAAE,KAAK,CAAC;IACjC,2BAA2B,EAAE,KAAK,CAAC;IACnC,oBAAoB,EAAE,KAAK,CAAC;IAC5B,gBAAgB,EAAE,KAAK,CAAC;IACxB,kCAAkC,EAChC,KAAK,CAAC;IACR,sCAAsC,EACpC,KAAK,CAAC;IACR,yBAAyB,EAAE,KAAK,CAAC;IACjC,uBAAuB,EAAE,IAAI,CAAC;IAC9B,yBAAyB,EAAE,IAAI,CAAC;IAChC,yBAAyB,EAAE,KAAK,CAAC;CAClC;AAED,MAAM,MAAM,2CAA2C,GACnD,CAAC,+CAA+C,GAAG;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,6BAA6B,EAC3B,MAAM,CAAC;IACT,2BAA2B,EACzB,MAAM,CAAC;CACV,CAAC,GACF,CAAC,+CAA+C,GAAG;IACjD,MAAM,EAAE,WAAW,CAAC;IACpB,6BAA6B,EAC3B,KAAK,CAAC;IACR,2BAA2B,EACzB,KAAK,CAAC;CACT,CAAC,CAAC;AAsEP;;;;;;;;;GASG;AACH,wBAAgB,kCAAkC,CAChD,KAAK,EACH,uCAAuC,GACxC,iBAAiB,CAClB,2CAA2C,CAC5C,CAwRA"}

package/dist/exposure/metering-temporal.js

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Module boundary and integration notes.
+ * Meters a declared weighted time-average of scene-radiance-derived relative pre-exposure samples.
+ * Every temporal sample must already be explicitly bound to one #85 temporal illumination profile and
+ * one capture time in the first-opening-boundary-phase reference. Spatial metering is performed first
+ * in the same declared profile, then those scalar pre-exposure measurements are combined linearly by
+ * caller-declared normalized time weights.
+ * @see docs/USAGE.md for equations, coordinate/unit conventions, blockers and support limits.
+ */
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { meterRelativeExposure, parseExposureMeteringProfile } from "./metering.js";
+const NORMALIZED_WEIGHT_TOLERANCE = 1e-9;
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0) {
+        throw new InvalidScientificInputError(path + " must be a non-empty string.");
+    }
+    return value.trim();
+}
+function requireNormalizedWeight(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        value <= 0 ||
+        value > 1) {
+        throw new InvalidScientificInputError(path +
+            " must be finite and in (0, 1].");
+    }
+    return value;
+}
+function contextKey(sampleSet) {
+    const context = sampleSet.sourceContext;
+    const geometry = sampleSet.captureGeometry;
+    return JSON.stringify({
+        sceneId: context.sceneId,
+        sceneStateId: context.sceneStateId,
+        providerProfileId: context.providerProfileId,
+        illuminationProfileId: context.illuminationProfileId,
+        materialResponseProfileId: context.materialResponseProfileId,
+        derivationProfileId: context.derivationProfileId,
+        materialResponseFidelity: context.materialResponseFidelity,
+        orientation: geometry.orientedCapture
+            .orientation,
+        activeNativeRect: geometry.activeCapture.nativeRect,
+        activeImagingArea: geometry.activeCapture.imagingArea,
+        orientedImagingArea: geometry.orientedCapture
+            .imagingArea
+    });
+}
+/**
+ * Meters a declared weighted time-average of scene-radiance-derived relative
+ * pre-exposure samples.
+ *
+ * Every temporal sample must already be explicitly bound to one #85 temporal
+ * illumination profile and one capture time in the
+ * first-opening-boundary-phase reference. Spatial metering is performed first
+ * in the same declared profile, then those scalar pre-exposure measurements are
+ * combined linearly by caller-declared normalized time weights.
+ */
+export function meterSceneRadianceTemporalExposure(input) {
+    const temporalMeasurementId = requireNonEmptyString(input.temporalMeasurementId, "temporalMeasurementId");
+    const profile = parseExposureMeteringProfile(input.profile);
+    if (input.policy.kind !==
+        "weighted-time-average") {
+        throw new InvalidScientificInputError('policy.kind must be "weighted-time-average".');
+    }
+    if (input.policy.timeReference !==
+        "first-opening-boundary-phase") {
+        throw new InvalidScientificInputError('policy.timeReference must be "first-opening-boundary-phase".');
+    }
+    if (!Array.isArray(input.temporalSamples) ||
+        input.temporalSamples.length === 0) {
+        throw new InvalidScientificInputError("temporalSamples must be a non-empty array.");
+    }
+    const firstSampleSet = input.temporalSamples[0]
+        .sampleSet;
+    const firstContext = firstSampleSet.sourceContext;
+    if (firstContext.temporal.kind !==
+        "registered-time-varying") {
+        throw new InvalidScientificInputError("Temporal metering requires scene-radiance sample sets with registered-time-varying source context.");
+    }
+    const expectedContextKey = contextKey(firstSampleSet);
+    const sceneStateId = firstSampleSet.sceneStateId;
+    const temporalProfileId = firstContext.temporal
+        .illuminationTemporalProfileId;
+    let weightSum = 0;
+    let meteredRelativeSignal = 0;
+    let previousTime = Number.NEGATIVE_INFINITY;
+    let minimumTime = Number.POSITIVE_INFINITY;
+    let maximumTime = Number.NEGATIVE_INFINITY;
+    for (let index = 0; index <
+        input.temporalSamples.length; index += 1) {
+        const entry = input.temporalSamples[index];
+        const path = "temporalSamples[" +
+            index +
+            "]";
+        const weight = requireNormalizedWeight(entry.normalizedTimeWeight, path +
+            ".normalizedTimeWeight");
+        const sampleSet = entry.sampleSet;
+        const context = sampleSet.sourceContext;
+        if (context.temporal.kind !==
+            "registered-time-varying") {
+            throw new InvalidScientificInputError(path +
+                ".sampleSet must use registered-time-varying source context.");
+        }
+        if (context.temporal
+            .illuminationTemporalProfileId !==
+            temporalProfileId) {
+            throw new InvalidScientificInputError("All temporal metering samples must bind the same illuminationTemporalProfileId.");
+        }
+        if (sampleSet.sceneStateId !==
+            sceneStateId ||
+            context.sceneStateId !==
+                sceneStateId) {
+            throw new InvalidScientificInputError("All temporal metering samples must bind the same sceneStateId.");
+        }
+        if (contextKey(sampleSet) !==
+            expectedContextKey) {
+            throw new InvalidScientificInputError("All temporal metering samples must share the same scene/provider/material/derivation/capture-geometry context.");
+        }
+        const captureTime = context.temporal
+            .captureTimeSecondsFromReference;
+        if (!Number.isFinite(captureTime)) {
+            throw new InvalidScientificInputError(path +
+                " capture time must be finite.");
+        }
+        if (captureTime <= previousTime) {
+            throw new InvalidScientificInputError("Temporal metering capture times must be strictly increasing.");
+        }
+        previousTime = captureTime;
+        minimumTime = Math.min(minimumTime, captureTime);
+        maximumTime = Math.max(maximumTime, captureTime);
+        const spatialMeter = meterRelativeExposure({
+            profile,
+            sampleSet
+        });
+        meteredRelativeSignal +=
+            spatialMeter.value
+                .meteredRelativeSignal *
+                weight;
+        weightSum += weight;
+    }
+    if (!Number.isFinite(weightSum) ||
+        Math.abs(weightSum - 1) >
+            NORMALIZED_WEIGHT_TOLERANCE) {
+        throw new InvalidScientificInputError("temporalSamples normalizedTimeWeight values must sum to 1.");
+    }
+    if (!Number.isFinite(meteredRelativeSignal) ||
+        meteredRelativeSignal < 0) {
+        throw new InvalidScientificInputError("Temporal metered relative signal must remain finite and non-negative.");
+    }
+    const base = {
+        temporalMeasurementId,
+        sceneStateId,
+        profileId: profile.profileId,
+        scientificStatus: "approximation",
+        inputDomain: "relative-pre-exposure-linear-signal",
+        captureRegion: "oriented-active-capture",
+        spatialPolicyKind: profile.policy.kind,
+        temporalPolicyKind: "weighted-time-average",
+        timeReference: "first-opening-boundary-phase",
+        temporalSampleCount: input.temporalSamples.length,
+        normalizedTimeWeightSum: 1,
+        captureTimeRangeSecondsFromReference: {
+            minimum: minimumTime,
+            maximum: maximumTime
+        },
+        targetRelativeSignal: profile.target
+            .targetRelativeSignal,
+        meteredRelativeSignal,
+        outputCropUsedForMetering: false,
+        exposureCompensationApplied: false,
+        finalToneMappingUsed: false,
+        displayGammaUsed: false,
+        calibratedLuminanceClaimAuthorized: false,
+        calibratedSceneRadianceClaimAuthorized: false,
+        automaticExposureResolved: false,
+        resultReusableForAeLock: true,
+        temporalAveragingExplicit: true,
+        flashTtlMeteringPerformed: false
+    };
+    const result = meteredRelativeSignal === 0
+        ? {
+            ...base,
+            status: "no-signal",
+            requiredExposureScaleResolved: false,
+            exposureOffsetStopsResolved: false
+        }
+        : {
+            ...base,
+            status: "resolved",
+            requiredExposureScaleToTarget: profile.target
+                .targetRelativeSignal /
+                meteredRelativeSignal,
+            exposureOffsetStopsToTarget: Math.log2(profile.target
+                .targetRelativeSignal /
+                meteredRelativeSignal)
+        };
+    return approximationResult(result, "scene-radiance-relative-temporal-metering", "1.0.0", [
+        "Each temporal sample is a renderer/provider-supplied relative pre-exposure reduction bound to the same #85 scene-radiance context.",
+        "Spectral radiance is not converted to calibrated luminance or a camera spectral-meter response by this model.",
+        "Time averaging is explicit and linear in the declared relative pre-exposure signal domain.",
+        "Temporal sample weights are caller-declared, positive, normalized to one, and are not inferred from source waveform frequency or sensor readout timing.",
+        "All temporal samples share one committed sceneStateId and one provider/material/derivation/capture-geometry context.",
+        "Exposure compensation and automatic aperture/shutter/ISO resolution remain downstream.",
+        "This ambient meter does not implement flash/TTL metering."
+    ]);
+}
+//# sourceMappingURL=metering-temporal.js.map

package/dist/exposure/metering-temporal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metering-temporal.js","sourceRoot":"","sources":["../../src/exposure/metering-temporal.ts"],"names":[],"mappings":"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"}

package/dist/exposure/metering.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Module boundary and integration notes.
+ * Parses one generic relative exposure-metering profile. Schema 0.1.0 is approximation-only and
+ * consumes relative pre-exposure linear signal. It deliberately does not claim luminance, spectral
+ * radiance, sensor-plane irradiance, or a specific manufacturer's meter calibration.
+ * Meters relative pre-exposure linear signal over the actual oriented active capture frame. The first
+ * contract is an educational/relative approximation. It is intentionally independent of final output
+ * crop, display/tone mapping, exposure compensation, and automatic exposure setting resolution.
+ * @see docs/USAGE.md for equations, coordinate/unit conventions, blockers and support limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type EvidenceProvenance } from "../core/evidence-provenance.js";
+import type { NormalizedRasterUv, ResolvedCaptureGeometry } from "../output/capture-geometry.js";
+export declare const EXPOSURE_METERING_PROFILE_SCHEMA_VERSION: "0.1.0";
+export type ExposureMeteringPolicy = {
+    kind: "multi-zone-uniform";
+} | {
+    kind: "center-weighted-radial";
+    edgeWeight: number;
+    exponent: number;
+} | {
+    kind: "spot";
+    centerOrientedCaptureUv: NormalizedRasterUv;
+    radiusFractionOfCaptureDiagonal: number;
+} | {
+    kind: "highlight-weighted";
+    minimumWeightFraction: number;
+    exponent: number;
+};
+export interface ExposureMeteringProfile {
+    schemaVersion: typeof EXPOSURE_METERING_PROFILE_SCHEMA_VERSION;
+    profileId: string;
+    scientificStatus: "approximation";
+    inputDomain: "relative-pre-exposure-linear-signal";
+    captureRegion: "oriented-active-capture";
+    policy: ExposureMeteringPolicy;
+    target: {
+        kind: "relative-signal-reference";
+        targetRelativeSignal: number;
+        evidence: readonly EvidenceProvenance[];
+    };
+    evidence: readonly EvidenceProvenance[];
+    limitations: readonly string[];
+}
+export interface ExposureMeteringZoneSample {
+    sampleId: string;
+    positionOrientedCaptureUv: NormalizedRasterUv;
+    relativeLinearSignal: number;
+    areaWeight: number;
+}
+export interface ExposureMeteringSampleSet {
+    measurementId: string;
+    sceneStateId: string;
+    inputDomain: "relative-pre-exposure-linear-signal";
+    captureRegion: "oriented-active-capture";
+    captureGeometry: ResolvedCaptureGeometry;
+    processingState: {
+        exposureSettingsApplied: false;
+        whiteBalanceApplied: false;
+        toneMappingApplied: false;
+        displayGammaApplied: false;
+        sharpeningApplied: false;
+    };
+    samples: readonly ExposureMeteringZoneSample[];
+}
+interface ExposureMeteringResultBase {
+    measurementId: string;
+    sceneStateId: string;
+    profileId: string;
+    scientificStatus: "approximation";
+    inputDomain: "relative-pre-exposure-linear-signal";
+    captureRegion: "oriented-active-capture";
+    orientation: ResolvedCaptureGeometry["orientedCapture"]["orientation"];
+    activeCaptureImagingAreaMm: {
+        width: number;
+        height: number;
+    };
+    policyKind: ExposureMeteringPolicy["kind"];
+    targetRelativeSignal: number;
+    meteredRelativeSignal: number;
+    totalSampleCount: number;
+    selectedSampleCount: number;
+    normalizedWeightSum: number;
+    outputCropUsedForMetering: false;
+    exposureCompensationApplied: false;
+    finalToneMappingUsed: false;
+    displayGammaUsed: false;
+    calibratedLuminanceClaimAuthorized: false;
+    calibratedSceneRadianceClaimAuthorized: false;
+    automaticExposureResolved: false;
+    resultReusableForAeLock: true;
+}
+export type ExposureMeteringResult = (ExposureMeteringResultBase & {
+    status: "resolved";
+    requiredExposureScaleToTarget: number;
+    exposureOffsetStopsToTarget: number;
+}) | (ExposureMeteringResultBase & {
+    status: "no-signal";
+    requiredExposureScaleResolved: false;
+    exposureOffsetStopsResolved: false;
+});
+export interface MeterRelativeExposureInput {
+    profile: ExposureMeteringProfile;
+    sampleSet: ExposureMeteringSampleSet;
+}
+/**
+ * Parses one generic relative exposure-metering profile.
+ *
+ * Schema 0.1.0 is approximation-only and consumes relative pre-exposure
+ * linear signal. It deliberately does not claim luminance, spectral radiance,
+ * sensor-plane irradiance, or a specific manufacturer's meter calibration.
+ */
+export declare function parseExposureMeteringProfile(value: unknown): ExposureMeteringProfile;
+/**
+ * Meters relative pre-exposure linear signal over the actual oriented active
+ * capture frame.
+ *
+ * The first contract is an educational/relative approximation. It is
+ * intentionally independent of final output crop, display/tone mapping,
+ * exposure compensation, and automatic exposure setting resolution.
+ */
+export declare function meterRelativeExposure(input: MeterRelativeExposureInput): CalculationResult<ExposureMeteringResult>;
+export {};
+//# sourceMappingURL=metering.d.ts.map

package/dist/exposure/metering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metering.d.ts","sourceRoot":"","sources":["../../src/exposure/metering.ts"],"names":[],"mappings":"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"}