@photivra/engine 0.5.0 → 0.6.0

package/dist/sensor/exposure-window.js

@@ -0,0 +1,291 @@
+// SPDX-License-Identifier: Apache-2.0
+import { approximationResult } from "../core/calculation-result.js";
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { InvalidScientificInputError, requirePositiveInteger } from "../core/validation.js";
+const SHUTTER_MECHANISMS = new Set([
+    "mechanical",
+    "electronic-first-curtain",
+    "electronic"
+]);
+const SCAN_DIRECTIONS = new Set([
+    "top-to-bottom",
+    "bottom-to-top",
+    "left-to-right",
+    "right-to-left"
+]);
+const BOUNDARY_KINDS = new Set([
+    "simultaneous",
+    "uniform-linear-native-scan"
+]);
+function requireRecord(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new InvalidScientificInputError(path + " must be an object.");
+    }
+    return value;
+}
+function requireNonNegativeInteger(name, value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new InvalidScientificInputError(name + " must be a non-negative safe integer.");
+    }
+}
+function requirePositiveFinite(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new InvalidScientificInputError(name + " must be a finite number greater than zero.");
+    }
+    return value;
+}
+function parseSecondsFact(value, path) {
+    const record = requireRecord(value, path);
+    if (record.unit !== "s") {
+        throw new InvalidScientificInputError(path + '.unit must be "s".');
+    }
+    return {
+        value: requirePositiveFinite(path + ".value", record.value),
+        unit: "s",
+        evidence: parseEvidenceList(record.evidence, path + ".evidence")
+    };
+}
+function parseDirectionFact(value, path) {
+    const record = requireRecord(value, path);
+    if (typeof record.value !== "string" ||
+        !SCAN_DIRECTIONS.has(record.value)) {
+        throw new InvalidScientificInputError(path + ".value is invalid.");
+    }
+    return {
+        value: record.value,
+        evidence: parseEvidenceList(record.evidence, path + ".evidence")
+    };
+}
+function parseBoundarySchedule(value, path) {
+    const record = requireRecord(value, path);
+    if (typeof record.kind !== "string" ||
+        !BOUNDARY_KINDS.has(record.kind)) {
+        throw new InvalidScientificInputError(path + ".kind is invalid.");
+    }
+    if (record.kind === "simultaneous") {
+        if (record.directionNative !== undefined) {
+            throw new InvalidScientificInputError(path + ".directionNative must be omitted for a simultaneous boundary.");
+        }
+        if (record.traversalDurationSeconds !== undefined) {
+            throw new InvalidScientificInputError(path +
+                ".traversalDurationSeconds must be omitted for a simultaneous boundary.");
+        }
+        return { kind: "simultaneous" };
+    }
+    return {
+        kind: "uniform-linear-native-scan",
+        directionNative: parseDirectionFact(record.directionNative, path + ".directionNative"),
+        traversalDurationSeconds: parseSecondsFact(record.traversalDurationSeconds, path + ".traversalDurationSeconds")
+    };
+}
+function validateNativeRaster(raster) {
+    requirePositiveInteger("nativeRaster.pixelWidth", raster.pixelWidth);
+    requirePositiveInteger("nativeRaster.pixelHeight", raster.pixelHeight);
+}
+function fullRect(raster) {
+    return {
+        x: 0,
+        y: 0,
+        width: raster.pixelWidth,
+        height: raster.pixelHeight
+    };
+}
+function validateActiveCaptureRect(rect, raster) {
+    requireNonNegativeInteger("activeCaptureRect.x", rect.x);
+    requireNonNegativeInteger("activeCaptureRect.y", rect.y);
+    requirePositiveInteger("activeCaptureRect.width", rect.width);
+    requirePositiveInteger("activeCaptureRect.height", rect.height);
+    if (rect.x + rect.width > raster.pixelWidth ||
+        rect.y + rect.height > raster.pixelHeight) {
+        throw new InvalidScientificInputError("activeCaptureRect must fit entirely within nativeRaster.");
+    }
+}
+function validateShutterMechanism(value) {
+    if (typeof value !== "string" ||
+        !SHUTTER_MECHANISMS.has(value)) {
+        throw new InvalidScientificInputError("shutterMechanism is invalid.");
+    }
+}
+function validatePointWithinActiveCapture(point, rect, path) {
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+        throw new InvalidScientificInputError(path + " coordinates must be finite.");
+    }
+    if (point.x < rect.x ||
+        point.x > rect.x + rect.width ||
+        point.y < rect.y ||
+        point.y > rect.y + rect.height) {
+        throw new InvalidScientificInputError(path + " must lie within activeCaptureRect edge-coordinate bounds.");
+    }
+}
+function scanVector(direction) {
+    switch (direction) {
+        case "top-to-bottom":
+            return { x: 0, y: 1 };
+        case "bottom-to-top":
+            return { x: 0, y: -1 };
+        case "left-to-right":
+            return { x: 1, y: 0 };
+        case "right-to-left":
+            return { x: -1, y: 0 };
+    }
+}
+function normalizedScanPosition(point, rect, direction) {
+    switch (direction) {
+        case "top-to-bottom":
+            return (point.y - rect.y) / rect.height;
+        case "bottom-to-top":
+            return 1 - (point.y - rect.y) / rect.height;
+        case "left-to-right":
+            return (point.x - rect.x) / rect.width;
+        case "right-to-left":
+            return 1 - (point.x - rect.x) / rect.width;
+    }
+}
+function boundaryPhase(point, rect, schedule) {
+    if (schedule.kind === "simultaneous") {
+        return {
+            normalizedScanPosition: null,
+            phaseOffsetSeconds: 0
+        };
+    }
+    const normalized = normalizedScanPosition(point, rect, schedule.directionNative.value);
+    return {
+        normalizedScanPosition: normalized,
+        phaseOffsetSeconds: normalized * schedule.traversalDurationSeconds.value
+    };
+}
+function resolveBoundaryActuators(mechanism) {
+    switch (mechanism) {
+        case "mechanical":
+            return {
+                opening: "mechanical",
+                closing: "mechanical"
+            };
+        case "electronic-first-curtain":
+            return {
+                opening: "electronic",
+                closing: "mechanical"
+            };
+        case "electronic":
+            return {
+                opening: "electronic",
+                closing: "electronic"
+            };
+    }
+}
+function resolveBoundary(actuator, schedule) {
+    if (schedule.kind === "simultaneous") {
+        return {
+            actuator,
+            schedule: {
+                kind: "simultaneous"
+            }
+        };
+    }
+    return {
+        actuator,
+        schedule: {
+            kind: "uniform-linear-native-scan",
+            directionNative: schedule.directionNative,
+            unitVectorNative: scanVector(schedule.directionNative.value),
+            traversalDurationSeconds: schedule.traversalDurationSeconds
+        }
+    };
+}
+function createWindowSample(point, rect, opening, closing, nominalExposureDurationSeconds) {
+    const openingPhase = boundaryPhase(point, rect, opening);
+    const closingPhase = boundaryPhase(point, rect, closing);
+    const startOffsetSecondsFromOpeningReference = openingPhase.phaseOffsetSeconds;
+    const endOffsetSecondsFromOpeningReference = nominalExposureDurationSeconds + closingPhase.phaseOffsetSeconds;
+    const localExposureDurationSeconds = endOffsetSecondsFromOpeningReference -
+        startOffsetSecondsFromOpeningReference;
+    return {
+        pointNative: { ...point },
+        openingNormalizedScanPosition: openingPhase.normalizedScanPosition,
+        closingNormalizedScanPosition: closingPhase.normalizedScanPosition,
+        startOffsetSecondsFromOpeningReference,
+        endOffsetSecondsFromOpeningReference,
+        localExposureDurationSeconds
+    };
+}
+function activeRectCorners(rect) {
+    return [
+        { x: rect.x, y: rect.y },
+        { x: rect.x + rect.width, y: rect.y },
+        { x: rect.x, y: rect.y + rect.height },
+        {
+            x: rect.x + rect.width,
+            y: rect.y + rect.height
+        }
+    ];
+}
+/**
+ * Resolves local capture exposure windows from independent opening and closing
+ * boundary schedules.
+ *
+ * The returned time basis is seconds from the first opening-boundary phase.
+ * This is intentionally not the existing camera-rotation API's global
+ * "exposure start" semantic; a later integration layer must bind those time
+ * bases explicitly.
+ *
+ * The mechanism identifies whether each boundary is mechanical or electronic,
+ * but does not supply any traversal duration or direction. Every non-simultaneous
+ * timing value and direction is caller-declared with evidence.
+ *
+ * The first model supports simultaneous boundaries and uniform-linear
+ * single-axis native-sensor scans only. It does not model curtain acceleration,
+ * segmented/nonlinear electronic schedules, flash/flicker, rolling-shutter
+ * image distortion, shutter shock, or EFCS-specific pupil/bokeh behavior.
+ */
+export function calculateCaptureExposureWindows(input) {
+    validateNativeRaster(input.nativeRaster);
+    validateShutterMechanism(input.shutterMechanism);
+    const nominalExposureDurationSeconds = parseSecondsFact(input.nominalExposureDurationSeconds, "nominalExposureDurationSeconds");
+    const opening = parseBoundarySchedule(input.opening, "opening");
+    const closing = parseBoundarySchedule(input.closing, "closing");
+    const activeCaptureRect = input.activeCaptureRect ?? fullRect(input.nativeRaster);
+    validateActiveCaptureRect(activeCaptureRect, input.nativeRaster);
+    if (input.samplePointsNative !== undefined &&
+        !Array.isArray(input.samplePointsNative)) {
+        throw new InvalidScientificInputError("samplePointsNative must be an array when supplied.");
+    }
+    const cornerSamples = activeRectCorners(activeCaptureRect).map((point) => createWindowSample(point, activeCaptureRect, opening, closing, nominalExposureDurationSeconds.value));
+    const localDurations = cornerSamples.map((sample) => sample.localExposureDurationSeconds);
+    const minimumLocalExposureDurationSeconds = Math.min(...localDurations);
+    const maximumLocalExposureDurationSeconds = Math.max(...localDurations);
+    if (!Number.isFinite(minimumLocalExposureDurationSeconds) ||
+        minimumLocalExposureDurationSeconds <= 0) {
+        throw new InvalidScientificInputError("The declared opening/closing schedules produce a zero or negative local exposure duration somewhere within activeCaptureRect.");
+    }
+    const samples = (input.samplePointsNative ?? []).map((point, index) => {
+        validatePointWithinActiveCapture(point, activeCaptureRect, "samplePointsNative[" + index + "]");
+        return createWindowSample(point, activeCaptureRect, opening, closing, nominalExposureDurationSeconds.value);
+    });
+    const actuators = resolveBoundaryActuators(input.shutterMechanism);
+    return approximationResult({
+        shutterMechanism: input.shutterMechanism,
+        timeReference: "first-opening-boundary-phase",
+        nativeRaster: { ...input.nativeRaster },
+        activeCaptureRect: { ...activeCaptureRect },
+        nominalExposureDurationSeconds,
+        opening: resolveBoundary(actuators.opening, opening),
+        closing: resolveBoundary(actuators.closing, closing),
+        localExposureDurationRangeSeconds: {
+            minimum: minimumLocalExposureDurationSeconds,
+            maximum: maximumLocalExposureDurationSeconds
+        },
+        samples
+    }, "capture-exposure-window-schedule", "1.0.0", [
+        "Time is reported in seconds from the first opening-boundary phase, not from a universal local exposure-start event.",
+        "Nominal exposure duration, opening traversal, and closing traversal are independent declared quantities.",
+        "Mechanical, electronic-first-curtain, and electronic mechanisms determine boundary actuator categories only; they do not supply timing or direction.",
+        "Uniform-linear scan boundaries are an explicit approximation over continuous effective native-raster coordinates and do not assert one raster row/column equals one physical curtain line, photodiode row, or hardware readout line.",
+        "Opening and closing directions and traversal durations are independent and may produce spatially varying local exposure duration.",
+        "The complete active rectangle is validated using the extrema of the affine boundary schedules, so unsampled invalid corners cannot pass.",
+        "Active-capture timing is caller-declared and is not inferred by scaling full-frame timing from crop dimensions.",
+        "Physical camera orientation and digital output crop/resolution remain downstream of the invariant native timing schedule.",
+        "Sensor readout timing remains a separate contract; this model does not automatically equate a sensor readout phase with an exposure boundary.",
+        "This model does not include curtain acceleration, segmented/nonlinear electronic timing, rolling-shutter image distortion, motion integration, flash/flicker interaction, shutter shock, or EFCS-specific pupil/bokeh behavior."
+    ]);
+}
+//# sourceMappingURL=exposure-window.js.map

package/dist/sensor/exposure-window.js.map

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

package/dist/sensor/optical-stack.d.ts

@@ -0,0 +1,132 @@
+import { type EvidenceProvenance } from "../core/evidence-provenance.js";
+export type SensorOpticalStackComponentRole = "cover-glass" | "infrared-cut" | "ultraviolet-cut" | "anti-reflection" | "birefringent-low-pass" | "wave-plate" | "other-optical-filter";
+export interface SensorOpticalStackComponent {
+    componentId: string;
+    /**
+     * Roles may be combined because one physical element can provide multiple
+     * optical/filter functions.
+     */
+    roles: readonly SensorOpticalStackComponentRole[];
+    evidence: readonly EvidenceProvenance[];
+}
+export interface SensorMicrolensDeclaration {
+    presence: "present" | "absent";
+    evidence: readonly EvidenceProvenance[];
+    /**
+     * Presence alone does not establish an angular, spectral, fill-factor, or
+     * collection-efficiency model.
+     */
+    opticalEffectModel: "unresolved";
+}
+export interface AntiAliasingPointSplitComponent {
+    /**
+     * Native sensor physical offset from the nominal landing point.
+     * +X right, +Y down. Units: micrometres.
+     */
+    offsetMicrometers: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Dimensionless normalized spatial weight. Point-splitting kernels describe
+     * spatial redistribution only; total stack throughput is outside this field.
+     */
+    normalizedWeight: number;
+}
+export type SensorEffectiveAntiAliasingSpatialResponse = {
+    /**
+     * Documented absence/cancellation of intentional anti-aliasing spatial
+     * splitting. This does not mean the whole sensor stack is optically
+     * identity.
+     */
+    kind: "absent";
+    evidence: readonly EvidenceProvenance[];
+} | {
+    /**
+     * An effective anti-aliasing response is known to exist, but its spatial
+     * response is not defensibly specified.
+     */
+    kind: "present-unresolved";
+    evidence: readonly EvidenceProvenance[];
+} | {
+    /**
+     * Generic normalized point-splitting approximation in native sensor
+     * physical coordinates.
+     */
+    kind: "normalized-point-splitting-kernel";
+    evidence: readonly EvidenceProvenance[];
+    coordinateSystem: "native-sensor-physical";
+    scope: "field-wavelength-polarization-invariant-approximation";
+    components: readonly AntiAliasingPointSplitComponent[];
+};
+export interface SensorOpticalStackProfile {
+    schemaVersion: "0.1.0";
+    profileId: string;
+    evidence: readonly EvidenceProvenance[];
+    /**
+     * Ordered from incident-light side toward the sensor.
+     *
+     * These components are descriptive metadata only. Their presence does not
+     * create transmission, focus-shift, aberration, or spectral effects.
+     */
+    orderedComponents?: readonly SensorOpticalStackComponent[];
+    /**
+     * Omitted means unknown/unasserted.
+     *
+     * This is intentionally separate from physical component presence so a
+     * stack can contain low-pass-related hardware while its net effective
+     * anti-aliasing response is absent/cancelled.
+     */
+    effectiveAntiAliasingSpatialResponse?: SensorEffectiveAntiAliasingSpatialResponse;
+    /**
+     * Omitted means unknown/unasserted.
+     */
+    microlens?: SensorMicrolensDeclaration;
+}
+export interface ResolvedAntiAliasingSpatialKernel {
+    profileId: string;
+    effectiveResponse: "absent" | "normalized-point-splitting-kernel";
+    coordinateSystem: "native-sensor-physical";
+    components: readonly AntiAliasingPointSplitComponent[];
+    normalizedWeightSum: number;
+    throughputIncluded: false;
+    spectralTransmissionIncluded: false;
+    fieldDependenceIncluded: false;
+    wavelengthDependenceIncluded: false;
+    polarizationDependenceIncluded: false;
+    microlensResponseIncluded: false;
+    coverFilterStackEffectsIncluded: false;
+    wholeSensorOpticalStackResponse: false;
+    provenance: {
+        profile: readonly EvidenceProvenance[];
+        antiAliasingResponse: readonly EvidenceProvenance[];
+    };
+}
+/**
+ * Parses descriptive sensor optical-stack metadata plus an optional explicitly
+ * declared effective anti-aliasing spatial response.
+ *
+ * Unknown facts are omitted instead of inferred. Physical component presence
+ * is intentionally separate from effective anti-aliasing response so the
+ * schema can represent cancellation/neutralization designs without claiming
+ * the physical assembly is absent.
+ *
+ * Cover/filter-stack and microlens presence do not create optical effects in
+ * schema 0.1.0. Thickness, refractive index, spectral transmission, angular
+ * acceptance, focus shift and microlens collection behavior require later
+ * explicit models/calibration.
+ */
+export declare function parseSensorOpticalStackProfile(value: unknown): SensorOpticalStackProfile;
+/**
+ * Resolves only the effective anti-aliasing spatial kernel.
+ *
+ * This is not a whole optical-stack PSF. Cover/filter transmission, refraction,
+ * microlens behavior, field/wavelength/polarization dependence, and total
+ * throughput remain excluded.
+ *
+ * A documented absent effective anti-aliasing response resolves to an identity
+ * component at zero offset. An unknown response (field omitted) or a
+ * present-but-unresolved response fails closed.
+ */
+export declare function resolveAntiAliasingSpatialKernel(profileInput: SensorOpticalStackProfile): ResolvedAntiAliasingSpatialKernel;
+//# sourceMappingURL=optical-stack.d.ts.map

package/dist/sensor/optical-stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optical-stack.d.ts","sourceRoot":"","sources":["../../src/sensor/optical-stack.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,gCAAgC,CAAC;AAKxC,MAAM,MAAM,+BAA+B,GACvC,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,iBAAiB,GACjB,uBAAuB,GACvB,YAAY,GACZ,sBAAsB,CAAC;AAE3B,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,EAAE,SAAS,+BAA+B,EAAE,CAAC;IAClD,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC/B,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACxC;;;OAGG;IACH,kBAAkB,EAAE,YAAY,CAAC;CAClC;AAED,MAAM,WAAW,+BAA+B;IAC9C;;;OAGG;IACH,iBAAiB,EAAE;QACjB,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;KACX,CAAC;IACF;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,0CAA0C,GAClD;IACE;;;;OAIG;IACH,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACzC,GACD;IACE;;;OAGG;IACH,IAAI,EAAE,oBAAoB,CAAC;IAC3B,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACzC,GACD;IACE;;;OAGG;IACH,IAAI,EAAE,mCAAmC,CAAC;IAC1C,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACxC,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,KAAK,EACH,uDAAuD,CAAC;IAC1D,UAAU,EAAE,SAAS,+BAA+B,EAAE,CAAC;CACxD,CAAC;AAEN,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACxC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAC3D;;;;;;OAMG;IACH,oCAAoC,CAAC,EAAE,0CAA0C,CAAC;IAClF;;OAEG;IACH,SAAS,CAAC,EAAE,0BAA0B,CAAC;CACxC;AAED,MAAM,WAAW,iCAAiC;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EACb,QAAQ,GACR,mCAAmC,CAAC;IACxC,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,UAAU,EAAE,SAAS,+BAA+B,EAAE,CAAC;IACvD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,KAAK,CAAC;IAC1B,4BAA4B,EAAE,KAAK,CAAC;IACpC,uBAAuB,EAAE,KAAK,CAAC;IAC/B,4BAA4B,EAAE,KAAK,CAAC;IACpC,8BAA8B,EAAE,KAAK,CAAC;IACtC,yBAAyB,EAAE,KAAK,CAAC;IACjC,+BAA+B,EAAE,KAAK,CAAC;IACvC,+BAA+B,EAAE,KAAK,CAAC;IACvC,UAAU,EAAE;QACV,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;QACvC,oBAAoB,EAAE,SAAS,kBAAkB,EAAE,CAAC;KACrD,CAAC;CACH;AA0TD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,GACb,yBAAyB,CAuE3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAC9C,YAAY,EAAE,yBAAyB,GACtC,iCAAiC,CAyFnC"}