@photivra/engine 0.1.0

package/dist/core/calculation-result.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Scientific provenance labels used throughout the public API.
+ */
+export type ProvenanceKind = "calculated" | "calibrated" | "estimated" | "approximation";
+/**
+ * Metadata describing how a numerical result was produced.
+ */
+export interface CalculationProvenance {
+    /** Classification of the result's scientific origin. */
+    kind: ProvenanceKind;
+    /** Stable identifier for the model or equation set. */
+    model: string;
+    /** Version of the model, independent of the package version. */
+    modelVersion: string;
+    /** Concise assumptions that materially affect interpretation. */
+    assumptions?: readonly string[];
+}
+/**
+ * Source category for a quantified uncertainty estimate.
+ */
+export type UncertaintySource = "measurement" | "model-approximation" | "calibration";
+/**
+ * Optional confidence metadata for a quantified uncertainty estimate.
+ *
+ * A confidence level is only meaningful when the basis can be stated. It must
+ * not be used as a generic subjective confidence score.
+ */
+export interface UncertaintyConfidence {
+    /** Confidence/coverage level as a fraction in the interval (0, 1]. */
+    level: number;
+    /** Concise description of the statistical/empirical basis. */
+    basis: string;
+}
+interface UncertaintyEstimateBase {
+    /** JSON-style path to the affected result quantity, e.g. value.distanceM. */
+    quantityPath: string;
+    /** Physical/statistical origin of this uncertainty component. */
+    source: UncertaintySource;
+    /** Optional confidence/coverage metadata when scientifically meaningful. */
+    confidence?: UncertaintyConfidence;
+    /** Concise interpretation note, if needed. */
+    note?: string;
+}
+/**
+ * Absolute symmetric uncertainty around a result quantity.
+ */
+export interface AbsoluteUncertaintyEstimate extends UncertaintyEstimateBase {
+    kind: "absolute";
+    /** Symmetric ± magnitude in the explicitly named unit. */
+    plusMinus: number;
+    /** Explicit unit such as mm, m, px, or "1" for dimensionless values. */
+    unit: string;
+}
+/**
+ * Relative symmetric uncertainty around a result quantity.
+ */
+export interface RelativeUncertaintyEstimate extends UncertaintyEstimateBase {
+    kind: "relative";
+    /** Symmetric ± fractional magnitude; 0.05 means ±5%. */
+    fraction: number;
+}
+export type UncertaintyEstimate = AbsoluteUncertaintyEstimate | RelativeUncertaintyEstimate;
+/**
+ * Documented parameter range over which a model/calibration is considered
+ * valid. This is model applicability metadata, not a statistical interval.
+ */
+export interface CalculationValidRange {
+    /** JSON-style input/model parameter path, e.g. input.focusDistanceM. */
+    parameterPath: string;
+    /** Explicit unit such as m, mm, ISO, or "1" for dimensionless values. */
+    unit: string;
+    minimum?: number;
+    maximum?: number;
+    note?: string;
+}
+/**
+ * Optional quality metadata for a calculation result.
+ *
+ * Components remain separate by default. Callers must not add, combine in
+ * quadrature, or otherwise collapse uncertainty components unless a
+ * scientifically justified composition method explicitly documents
+ * independence/correlation assumptions.
+ */
+export interface CalculationQuality {
+    uncertainty?: readonly UncertaintyEstimate[];
+    validRanges?: readonly CalculationValidRange[];
+    notes?: readonly string[];
+}
+/**
+ * Standard result envelope for public scientific calculations.
+ *
+ * Deterministic analytical results remain lightweight: quality is omitted when
+ * there is no defensible uncertainty/accuracy metadata to report.
+ *
+ * @typeParam T Serializable value returned by the calculation.
+ */
+export interface CalculationResult<T> {
+    value: T;
+    provenance: CalculationProvenance;
+    quality?: CalculationQuality;
+}
+/**
+ * Validates result-quality metadata before it enters a public result envelope.
+ *
+ * @param quality Optional calculation quality metadata.
+ */
+export declare function validateCalculationQuality(quality: CalculationQuality | undefined): void;
+/**
+ * Creates a deterministic calculated-result envelope.
+ */
+export declare function calculatedResult<T>(value: T, model: string, modelVersion: string, assumptions?: readonly string[], quality?: CalculationQuality): CalculationResult<T>;
+/**
+ * Creates an approximation-result envelope.
+ */
+export declare function approximationResult<T>(value: T, model: string, modelVersion: string, assumptions: readonly string[], quality?: CalculationQuality): CalculationResult<T>;
+/**
+ * Creates an estimated-result envelope with explicit quality metadata.
+ */
+export declare function estimatedResult<T>(value: T, model: string, modelVersion: string, assumptions: readonly string[], quality: CalculationQuality): CalculationResult<T>;
+/**
+ * Creates a calibrated-result envelope with explicit quality metadata.
+ */
+export declare function calibratedResult<T>(value: T, model: string, modelVersion: string, assumptions: readonly string[], quality: CalculationQuality): CalculationResult<T>;
+export {};
+//# sourceMappingURL=calculation-result.d.ts.map

package/dist/core/calculation-result.d.ts.map

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

package/dist/core/calculation-result.js

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: Apache-2.0
+import { InvalidScientificResultError } from "./validation.js";
+function requireNonEmptyString(path, value) {
+    if (value.trim().length === 0) {
+        throw new InvalidScientificResultError(`Calculation quality field ${path} must not be empty.`);
+    }
+}
+function requireNonNegativeFinite(path, value) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new InvalidScientificResultError(`Calculation quality field ${path} must be finite and greater than or equal to zero.`);
+    }
+}
+function validateConfidence(confidence, path) {
+    if (confidence === undefined) {
+        return;
+    }
+    if (!Number.isFinite(confidence.level) ||
+        confidence.level <= 0 ||
+        confidence.level > 1) {
+        throw new InvalidScientificResultError(`Calculation quality field ${path}.level must be in (0, 1].`);
+    }
+    requireNonEmptyString(`${path}.basis`, confidence.basis);
+}
+function validateUncertaintyEstimate(estimate, index) {
+    const path = `uncertainty[${index}]`;
+    requireNonEmptyString(`${path}.quantityPath`, estimate.quantityPath);
+    validateConfidence(estimate.confidence, `${path}.confidence`);
+    if (estimate.note !== undefined) {
+        requireNonEmptyString(`${path}.note`, estimate.note);
+    }
+    if (estimate.kind === "absolute") {
+        requireNonNegativeFinite(`${path}.plusMinus`, estimate.plusMinus);
+        requireNonEmptyString(`${path}.unit`, estimate.unit);
+        return;
+    }
+    requireNonNegativeFinite(`${path}.fraction`, estimate.fraction);
+}
+function validateValidRange(range, index) {
+    const path = `validRanges[${index}]`;
+    requireNonEmptyString(`${path}.parameterPath`, range.parameterPath);
+    requireNonEmptyString(`${path}.unit`, range.unit);
+    if (range.minimum === undefined && range.maximum === undefined) {
+        throw new InvalidScientificResultError(`Calculation quality field ${path} must include minimum or maximum.`);
+    }
+    if (range.minimum !== undefined && !Number.isFinite(range.minimum)) {
+        throw new InvalidScientificResultError(`Calculation quality field ${path}.minimum must be finite.`);
+    }
+    if (range.maximum !== undefined && !Number.isFinite(range.maximum)) {
+        throw new InvalidScientificResultError(`Calculation quality field ${path}.maximum must be finite.`);
+    }
+    if (range.minimum !== undefined &&
+        range.maximum !== undefined &&
+        range.minimum > range.maximum) {
+        throw new InvalidScientificResultError(`Calculation quality field ${path} minimum must not exceed maximum.`);
+    }
+    if (range.note !== undefined) {
+        requireNonEmptyString(`${path}.note`, range.note);
+    }
+}
+/**
+ * Validates result-quality metadata before it enters a public result envelope.
+ *
+ * @param quality Optional calculation quality metadata.
+ */
+export function validateCalculationQuality(quality) {
+    if (quality === undefined) {
+        return;
+    }
+    if (quality.uncertainty !== undefined) {
+        if (quality.uncertainty.length === 0) {
+            throw new InvalidScientificResultError("Calculation quality uncertainty must be omitted rather than empty.");
+        }
+        quality.uncertainty.forEach(validateUncertaintyEstimate);
+    }
+    if (quality.validRanges !== undefined) {
+        if (quality.validRanges.length === 0) {
+            throw new InvalidScientificResultError("Calculation quality validRanges must be omitted rather than empty.");
+        }
+        quality.validRanges.forEach(validateValidRange);
+    }
+    if (quality.notes !== undefined) {
+        if (quality.notes.length === 0) {
+            throw new InvalidScientificResultError("Calculation quality notes must be omitted rather than empty.");
+        }
+        quality.notes.forEach((note, index) => {
+            requireNonEmptyString(`notes[${index}]`, note);
+        });
+    }
+    if (quality.uncertainty === undefined &&
+        quality.validRanges === undefined &&
+        quality.notes === undefined) {
+        throw new InvalidScientificResultError("Calculation quality must contain uncertainty, validRanges, or notes.");
+    }
+}
+function assertFiniteNumbers(value, path, seen) {
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new InvalidScientificResultError(`Calculation produced a non-finite number at ${path}.`);
+        }
+        return;
+    }
+    if (typeof value !== "object" || value === null) {
+        return;
+    }
+    if (seen.has(value)) {
+        return;
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => {
+            assertFiniteNumbers(entry, `${path}[${index}]`, seen);
+        });
+        return;
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        assertFiniteNumbers(entry, `${path}.${key}`, seen);
+    }
+}
+function assertFiniteCalculationValue(value) {
+    assertFiniteNumbers(value, "value", new WeakSet());
+}
+function createResult(value, provenance, quality) {
+    assertFiniteCalculationValue(value);
+    validateCalculationQuality(quality);
+    return {
+        value,
+        provenance,
+        ...(quality === undefined ? {} : { quality })
+    };
+}
+/**
+ * Creates a deterministic calculated-result envelope.
+ */
+export function calculatedResult(value, model, modelVersion, assumptions, quality) {
+    return createResult(value, {
+        kind: "calculated",
+        model,
+        modelVersion,
+        ...(assumptions === undefined ? {} : { assumptions })
+    }, quality);
+}
+/**
+ * Creates an approximation-result envelope.
+ */
+export function approximationResult(value, model, modelVersion, assumptions, quality) {
+    return createResult(value, {
+        kind: "approximation",
+        model,
+        modelVersion,
+        assumptions
+    }, quality);
+}
+/**
+ * Creates an estimated-result envelope with explicit quality metadata.
+ */
+export function estimatedResult(value, model, modelVersion, assumptions, quality) {
+    return createResult(value, {
+        kind: "estimated",
+        model,
+        modelVersion,
+        assumptions
+    }, quality);
+}
+/**
+ * Creates a calibrated-result envelope with explicit quality metadata.
+ */
+export function calibratedResult(value, model, modelVersion, assumptions, quality) {
+    return createResult(value, {
+        kind: "calibrated",
+        model,
+        modelVersion,
+        assumptions
+    }, quality);
+}
+//# sourceMappingURL=calculation-result.js.map

package/dist/core/calculation-result.js.map

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

package/dist/core/validation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Error thrown when a public scientific calculation receives invalid input.
+ */
+export declare class InvalidScientificInputError extends RangeError {
+    readonly code = "INVALID_SCIENTIFIC_INPUT";
+    constructor(message: string);
+}
+/**
+ * Error thrown when a scientific calculation would return a non-finite
+ * numeric value that is unsafe for JSON and downstream consumers.
+ */
+export declare class InvalidScientificResultError extends RangeError {
+    readonly code = "INVALID_SCIENTIFIC_RESULT";
+    constructor(message: string);
+}
+/**
+ * Requires a finite number greater than zero.
+ *
+ * @param name Public parameter name.
+ * @param value Value to validate.
+ */
+export declare function requirePositiveFinite(name: string, value: number): void;
+/**
+ * Requires a positive safe integer.
+ *
+ * @param name Public parameter name.
+ * @param value Value to validate.
+ */
+export declare function requirePositiveInteger(name: string, value: number): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/core/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/core/validation.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,UAAU;IACzD,QAAQ,CAAC,IAAI,8BAA8B;gBAE/B,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,qBAAa,4BAA6B,SAAQ,UAAU;IAC1D,QAAQ,CAAC,IAAI,+BAA+B;gBAEhC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMvE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMxE"}

package/dist/core/validation.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Error thrown when a public scientific calculation receives invalid input.
+ */
+export class InvalidScientificInputError extends RangeError {
+    code = "INVALID_SCIENTIFIC_INPUT";
+    constructor(message) {
+        super(message);
+        this.name = "InvalidScientificInputError";
+    }
+}
+/**
+ * Error thrown when a scientific calculation would return a non-finite
+ * numeric value that is unsafe for JSON and downstream consumers.
+ */
+export class InvalidScientificResultError extends RangeError {
+    code = "INVALID_SCIENTIFIC_RESULT";
+    constructor(message) {
+        super(message);
+        this.name = "InvalidScientificResultError";
+    }
+}
+/**
+ * Requires a finite number greater than zero.
+ *
+ * @param name Public parameter name.
+ * @param value Value to validate.
+ */
+export function requirePositiveFinite(name, value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new InvalidScientificInputError(`${name} must be a finite number greater than zero.`);
+    }
+}
+/**
+ * Requires a positive safe integer.
+ *
+ * @param name Public parameter name.
+ * @param value Value to validate.
+ */
+export function requirePositiveInteger(name, value) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new InvalidScientificInputError(`${name} must be a positive safe integer.`);
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/core/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/core/validation.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;GAEG;AACH,MAAM,OAAO,2BAA4B,SAAQ,UAAU;IAChD,IAAI,GAAG,0BAA0B,CAAC;IAE3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,4BAA6B,SAAQ,UAAU;IACjD,IAAI,GAAG,2BAA2B,CAAC;IAE5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,KAAa;IAC/D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,2BAA2B,CACnC,GAAG,IAAI,6CAA6C,CACrD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY,EAAE,KAAa;IAChE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,2BAA2B,CACnC,GAAG,IAAI,mCAAmC,CAC3C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/exposure/exposure.d.ts

@@ -0,0 +1,50 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+export interface CalculateExposureValue100Input {
+    /** F-number. */
+    aperture: number;
+    /** Shutter duration in seconds. */
+    shutterSeconds: number;
+}
+/**
+ * Calculates EV100 from aperture and shutter duration.
+ *
+ * @param input Aperture and shutter duration.
+ * @returns EV100 value.
+ */
+export declare function calculateExposureValue100(input: CalculateExposureValue100Input): CalculationResult<number>;
+export interface CalculateRelativeOpticalExposureInput {
+    aperture: number;
+    shutterSeconds: number;
+    referenceAperture: number;
+    referenceShutterSeconds: number;
+}
+export interface RelativeOpticalExposure {
+    /** Relative light exposure at the image plane; 1 equals the reference. */
+    factor: number;
+    /** Difference from the reference in stops. Positive means more light exposure. */
+    stops: number;
+}
+/**
+ * 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.
+ */
+export declare function calculateRelativeOpticalExposure(input: CalculateRelativeOpticalExposureInput): CalculationResult<RelativeOpticalExposure>;
+export interface CalculateEquivalentIsoInput {
+    baseIso: number;
+    baseAperture: number;
+    baseShutterSeconds: number;
+    aperture: number;
+    shutterSeconds: number;
+}
+/**
+ * Calculates the ISO/gain setting that preserves nominal rendered exposure
+ * after changing aperture and/or shutter, assuming all other factors remain
+ * constant.
+ *
+ * This is an exposure-compensation relation, not a sensor-noise model.
+ */
+export declare function calculateEquivalentIso(input: CalculateEquivalentIsoInput): CalculationResult<number>;
+//# sourceMappingURL=exposure.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exposure.d.ts","sourceRoot":"","sources":["../../src/exposure/exposure.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAGvC,MAAM,WAAW,8BAA8B;IAC7C,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,8BAA8B,GACpC,iBAAiB,CAAC,MAAM,CAAC,CAU3B;AAED,MAAM,WAAW,qCAAqC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,qCAAqC,GAC3C,iBAAiB,CAAC,uBAAuB,CAAC,CA6B5C;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,iBAAiB,CAAC,MAAM,CAAC,CAuB3B"}

package/dist/exposure/exposure.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+import { calculatedResult } from "../core/calculation-result.js";
+import { requirePositiveFinite } from "../core/validation.js";
+/**
+ * Calculates EV100 from aperture and shutter duration.
+ *
+ * @param input Aperture and shutter duration.
+ * @returns EV100 value.
+ */
+export function calculateExposureValue100(input) {
+    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"]);
+}
+/**
+ * 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.
+ */
+export function calculateRelativeOpticalExposure(input) {
+    requirePositiveFinite("aperture", input.aperture);
+    requirePositiveFinite("shutterSeconds", input.shutterSeconds);
+    requirePositiveFinite("referenceAperture", input.referenceAperture);
+    requirePositiveFinite("referenceShutterSeconds", input.referenceShutterSeconds);
+    const current = input.shutterSeconds / (input.aperture * input.aperture);
+    const reference = input.referenceShutterSeconds /
+        (input.referenceAperture * input.referenceAperture);
+    const factor = current / reference;
+    return calculatedResult({
+        factor,
+        stops: Math.log2(factor)
+    }, "relative-optical-exposure", "1.0.0", [
+        "Constant scene illumination",
+        "Lens transmission is not modeled",
+        "Sensor response is not modeled"
+    ]);
+}
+/**
+ * Calculates the ISO/gain setting that preserves nominal rendered exposure
+ * after changing aperture and/or shutter, assuming all other factors remain
+ * constant.
+ *
+ * This is an exposure-compensation relation, not a sensor-noise model.
+ */
+export function calculateEquivalentIso(input) {
+    requirePositiveFinite("baseIso", input.baseIso);
+    requirePositiveFinite("baseAperture", input.baseAperture);
+    requirePositiveFinite("baseShutterSeconds", input.baseShutterSeconds);
+    requirePositiveFinite("aperture", input.aperture);
+    requirePositiveFinite("shutterSeconds", input.shutterSeconds);
+    const baseLight = input.baseShutterSeconds /
+        (input.baseAperture * input.baseAperture);
+    const newLight = input.shutterSeconds / (input.aperture * input.aperture);
+    return calculatedResult(input.baseIso * (baseLight / newLight), "equivalent-iso-compensation", "1.0.0", [
+        "Constant scene illumination",
+        "ISO is treated as gain/brightness compensation, not photon creation",
+        "Lens transmission and sensor-specific gain behavior are not modeled"
+    ]);
+}
+//# sourceMappingURL=exposure.js.map

package/dist/exposure/exposure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exposure.js","sourceRoot":"","sources":["../../src/exposure/exposure.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAS9D;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAqC;IAErC,qBAAqB,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAE9D,OAAO,gBAAgB,CACrB,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,cAAc,CAAC,EACnE,oBAAoB,EACpB,OAAO,EACP,CAAC,2CAA2C,CAAC,CAC9C,CAAC;AACJ,CAAC;AAgBD;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC,CAC9C,KAA4C;IAE5C,qBAAqB,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9D,qBAAqB,CAAC,mBAAmB,EAAE,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACpE,qBAAqB,CACnB,yBAAyB,EACzB,KAAK,CAAC,uBAAuB,CAC9B,CAAC;IAEF,MAAM,OAAO,GACX,KAAK,CAAC,cAAc,GAAG,CAAC,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC3D,MAAM,SAAS,GACb,KAAK,CAAC,uBAAuB;QAC7B,CAAC,KAAK,CAAC,iBAAiB,GAAG,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IAEnC,OAAO,gBAAgB,CACrB;QACE,MAAM;QACN,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;KACzB,EACD,2BAA2B,EAC3B,OAAO,EACP;QACE,6BAA6B;QAC7B,kCAAkC;QAClC,gCAAgC;KACjC,CACF,CAAC;AACJ,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAkC;IAElC,qBAAqB,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAChD,qBAAqB,CAAC,cAAc,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IAC1D,qBAAqB,CAAC,oBAAoB,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACtE,qBAAqB,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAE9D,MAAM,SAAS,GACb,KAAK,CAAC,kBAAkB;QACxB,CAAC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;IAC5C,MAAM,QAAQ,GACZ,KAAK,CAAC,cAAc,GAAG,CAAC,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;IAE3D,OAAO,gBAAgB,CACrB,KAAK,CAAC,OAAO,GAAG,CAAC,SAAS,GAAG,QAAQ,CAAC,EACtC,6BAA6B,EAC7B,OAAO,EACP;QACE,6BAA6B;QAC7B,qEAAqE;QACrE,qEAAqE;KACtE,CACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Current public API contract version for the Photivra engine.
+ *
+ * This constant is intentionally independent of the package version so
+ * schema/API compatibility can be discussed explicitly.
+ */
+export declare const ENGINE_API_VERSION: "0.17.0";
+export { approximationResult, calibratedResult, calculatedResult, estimatedResult, validateCalculationQuality, type AbsoluteUncertaintyEstimate, type CalculationProvenance, type CalculationQuality, type CalculationResult, type CalculationValidRange, type ProvenanceKind, type RelativeUncertaintyEstimate, type UncertaintyConfidence, type UncertaintyEstimate, type UncertaintySource } from "./core/calculation-result.js";
+export { InvalidScientificInputError, InvalidScientificResultError } from "./core/validation.js";
+export { calculateFieldOfView, type CalculateFieldOfViewInput, type FieldOfView } from "./camera/field-of-view.js";
+export { calculateProjectedObjectSize, type CalculateProjectedObjectSizeInput, type ProjectedObjectSize } from "./camera/projected-object-size.js";
+export { calculatePixelPitch, type CalculatePixelPitchInput, type PixelPitch } from "./sensor/pixel-pitch.js";
+export { calculateCenteredCrop, type CalculateCenteredCropInput, type CenteredCrop } from "./output/crop.js";
+export { calculateSubjectFramingCrop, type CalculateSubjectFramingCropInput, type SubjectFramingCrop } from "./output/subject-framing-crop.js";
+export { calculateIdealApertureGeometry, type ApertureVertex, type CalculateIdealApertureInput, type IdealApertureGeometry } from "./optics/aperture.js";
+export { calculateAiryDisk, type AiryDisk, type CalculateAiryDiskInput } from "./optics/diffraction.js";
+export { estimateEquivalentViewingCircleOfConfusion, type EquivalentViewingCircleOfConfusion, type EstimateEquivalentViewingCircleOfConfusionInput } from "./optics/circle-of-confusion.js";
+export { calculateThinLensImageDistance, type CalculateThinLensImageDistanceInput, type ThinLensImageDistance } from "./optics/thin-lens.js";
+export { calculateDefocusCircle, calculateDepthOfField, type CalculateDefocusCircleInput, type CalculateDepthOfFieldInput, type DefocusCircle, type DepthOfField } from "./optics/depth-of-field.js";
+export type { CameraConfiguration, CameraSupport, ExposureConfiguration, FocusConfiguration, LensConfiguration, SensorConfiguration, StabilizationConfiguration } from "./schema/camera.js";
+export type { SceneCapability, SceneDefinition, SceneMotion, SceneObject, SceneRadiometry, Vector3 } from "./schema/scene.js";
+export { calculateProjectedMotionBlur, type CalculateProjectedMotionBlurInput, type ProjectedMotionBlur } from "./motion/projected-motion.js";
+export { calculateEquivalentIso, calculateExposureValue100, calculateRelativeOpticalExposure, type CalculateEquivalentIsoInput, type CalculateExposureValue100Input, type CalculateRelativeOpticalExposureInput, type RelativeOpticalExposure } from "./exposure/exposure.js";
+export { estimateCameraShakeBlur, type CameraShakeBlurSample, type CameraShakeEstimate, type EstimateCameraShakeBlurInput } from "./stabilization/camera-shake.js";
+export { calculatePhotoelectrons, calculateSignalToNoise, type CalculatePhotoelectronsInput, type CalculateSignalToNoiseInput, type SignalToNoise } from "./sensor/signal-noise.js";
+export { simulatePocCamera, type PocSimulationRequest, type PocSimulationResponse } from "./simulation/poc-simulation.js";
+export { InvalidConfigurationError, parseCameraConfiguration, parseSceneDefinition } from "./schema/validation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Current public API contract version for the Photivra engine.
+ *
+ * This constant is intentionally independent of the package version so
+ * schema/API compatibility can be discussed explicitly.
+ */
+export const ENGINE_API_VERSION = "0.17.0";
+export { approximationResult, calibratedResult, calculatedResult, estimatedResult, validateCalculationQuality } from "./core/calculation-result.js";
+export { InvalidScientificInputError, InvalidScientificResultError } from "./core/validation.js";
+export { calculateFieldOfView } from "./camera/field-of-view.js";
+export { calculateProjectedObjectSize } from "./camera/projected-object-size.js";
+export { calculatePixelPitch } from "./sensor/pixel-pitch.js";
+export { calculateCenteredCrop } from "./output/crop.js";
+export { calculateSubjectFramingCrop } from "./output/subject-framing-crop.js";
+export { calculateIdealApertureGeometry } from "./optics/aperture.js";
+export { calculateAiryDisk } from "./optics/diffraction.js";
+export { estimateEquivalentViewingCircleOfConfusion } from "./optics/circle-of-confusion.js";
+export { calculateThinLensImageDistance } from "./optics/thin-lens.js";
+export { calculateDefocusCircle, calculateDepthOfField } from "./optics/depth-of-field.js";
+export { calculateProjectedMotionBlur } from "./motion/projected-motion.js";
+export { calculateEquivalentIso, calculateExposureValue100, calculateRelativeOpticalExposure } from "./exposure/exposure.js";
+export { estimateCameraShakeBlur } from "./stabilization/camera-shake.js";
+export { calculatePhotoelectrons, calculateSignalToNoise } from "./sensor/signal-noise.js";
+export { simulatePocCamera } from "./simulation/poc-simulation.js";
+export { InvalidConfigurationError, parseCameraConfiguration, parseSceneDefinition } from "./schema/validation.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAiB,CAAC;AAEpD,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,0BAA0B,EAW3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC7B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,oBAAoB,EAGrB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACL,4BAA4B,EAG7B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,mBAAmB,EAGpB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,qBAAqB,EAGtB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,2BAA2B,EAG5B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,8BAA8B,EAI/B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EAGlB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,0CAA0C,EAG3C,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,8BAA8B,EAG/B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EAKtB,MAAM,4BAA4B,CAAC;AAsBpC,OAAO,EACL,4BAA4B,EAG7B,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAKjC,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,uBAAuB,EAIxB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EAIvB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,iBAAiB,EAGlB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,wBAAwB,CAAC"}

package/dist/motion/projected-motion.d.ts

@@ -0,0 +1,41 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+import type { Vector3 } from "../schema/scene.js";
+export interface CalculateProjectedMotionBlurInput {
+    /** Lens focal length in millimetres. */
+    focalLengthMm: number;
+    /** Shutter-open duration in seconds. */
+    shutterSeconds: number;
+    /** Object position at shutter open, in camera-relative metres. +z is away from the camera. */
+    positionM: Vector3;
+    /** Constant world-space velocity during the exposure, in metres per second. */
+    velocityMps: Vector3;
+    /** Optional focus distance in metres for focus-aware sensor-plane projection. */
+    focusDistanceM?: number;
+    /** Optional sensor pixel pitch in micrometres for pixel-domain blur reporting. */
+    pixelPitchMicrometers?: number;
+}
+export interface ProjectedMotionBlur {
+    deltaXMm: number;
+    deltaYMm: number;
+    distanceMm: number;
+    projectionDistanceMm: number;
+    distancePixels?: number;
+}
+/**
+ * Calculates sensor-plane motion during an exposure using ideal rectilinear
+ * projection and constant linear object velocity.
+ *
+ * Without focusDistanceM, nominal focal length is the backwards-compatible
+ * pinhole projection distance. With focusDistanceM, the selected thin-lens
+ * sensor-plane image distance is used.
+ *
+ * The calculation projects the object's shutter-open and shutter-close
+ * positions onto the image plane and measures the displacement between them.
+ * It therefore handles lateral and depth-direction motion without relying on a
+ * generic "subject speed" category.
+ *
+ * @param input Camera, exposure, object-position, and velocity inputs.
+ * @returns Projected sensor-plane displacement.
+ */
+export declare function calculateProjectedMotionBlur(input: CalculateProjectedMotionBlurInput): CalculationResult<ProjectedMotionBlur>;
+//# sourceMappingURL=projected-motion.d.ts.map

package/dist/motion/projected-motion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projected-motion.d.ts","sourceRoot":"","sources":["../../src/motion/projected-motion.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAMvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,WAAW,iCAAiC;IAChD,wCAAwC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,8FAA8F;IAC9F,SAAS,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,WAAW,EAAE,OAAO,CAAC;IACrB,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,iCAAiC,GACvC,iBAAiB,CAAC,mBAAmB,CAAC,CAkFxC"}