@photivra/engine 0.5.1 → 1.0.0

package/dist/sensor/readout-timing.js

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Module boundary and integration notes.
+ * Resolves a capture-specific native sensor readout scan schedule. Rolling readout uses a
+ * uniform-linear single-axis approximation across the declared active capture. The caller supplies the
+ * spatial timing span explicitly; it is never inferred from total data-readout duration, active crop
+ * dimensions, native raster density, output resolution, sensor architecture metadata, or shutter
+ * mechanism. Global readout has no spatial phase skew in this model even when a non-zero data-readout
+ * duration is declared. This foundation does not define local exposure start/end times, mechanical
+ * curtain travel, EFCS curtain behavior, rolling-shutter image distortion, flash/flicker interactions,
+ * or motion integration.
+ * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
+ * limits.
+ */
+import { approximationResult } from "../core/calculation-result.js";
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { InvalidScientificInputError, requirePositiveInteger } from "../core/validation.js";
+const READOUT_MODES = new Set(["rolling", "global"]);
+const SCAN_DIRECTIONS = new Set([
+    "top-to-bottom",
+    "bottom-to-top",
+    "left-to-right",
+    "right-to-left"
+]);
+const SHUTTER_MECHANISMS = new Set([
+    "mechanical",
+    "electronic-first-curtain",
+    "electronic"
+]);
+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 requireNonNegativeFinite(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new InvalidScientificInputError(name + " must be a finite number greater than or equal to zero.");
+    }
+    return value;
+}
+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, positive) {
+    const record = requireRecord(value, path);
+    if (record.unit !== "s") {
+        throw new InvalidScientificInputError(path + '.unit must be "s".');
+    }
+    const seconds = positive
+        ? requirePositiveFinite(path + ".value", record.value)
+        : requireNonNegativeFinite(path + ".value", record.value);
+    return {
+        value: seconds,
+        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 parseReadoutDeclaration(value) {
+    const record = requireRecord(value, "readout");
+    if (typeof record.readoutMode !== "string" ||
+        !READOUT_MODES.has(record.readoutMode)) {
+        throw new InvalidScientificInputError("readout.readoutMode is invalid.");
+    }
+    const captureReadoutDurationSeconds = parseSecondsFact(record.captureReadoutDurationSeconds, "readout.captureReadoutDurationSeconds", false);
+    if (record.readoutMode === "global") {
+        if (record.scanDirectionNative !== undefined) {
+            throw new InvalidScientificInputError("readout.scanDirectionNative must be omitted for global readout.");
+        }
+        if (record.spatialSamplingSkewSeconds !== undefined) {
+            throw new InvalidScientificInputError("readout.spatialSamplingSkewSeconds must be omitted for global readout.");
+        }
+        return {
+            readoutMode: "global",
+            captureReadoutDurationSeconds
+        };
+    }
+    return {
+        readoutMode: "rolling",
+        captureReadoutDurationSeconds,
+        scanDirectionNative: parseDirectionFact(record.scanDirectionNative, "readout.scanDirectionNative"),
+        spatialSamplingSkewSeconds: parseSecondsFact(record.spatialSamplingSkewSeconds, "readout.spatialSamplingSkewSeconds", true)
+    };
+}
+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, index) {
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+        throw new InvalidScientificInputError("samplePointsNative[" + index + "] 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("samplePointsNative[" +
+            index +
+            "] 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;
+    }
+}
+/**
+ * Resolves a capture-specific native sensor readout scan schedule.
+ *
+ * Rolling readout uses a uniform-linear single-axis approximation across the
+ * declared active capture. The caller supplies the spatial timing span
+ * explicitly; it is never inferred from total data-readout duration, active
+ * crop dimensions, native raster density, output resolution, sensor
+ * architecture metadata, or shutter mechanism.
+ *
+ * Global readout has no spatial phase skew in this model even when a non-zero
+ * data-readout duration is declared.
+ *
+ * This foundation does not define local exposure start/end times, mechanical
+ * curtain travel, EFCS curtain behavior, rolling-shutter image distortion,
+ * flash/flicker interactions, or motion integration.
+ */
+export function calculateSensorReadoutTiming(input) {
+    validateNativeRaster(input.nativeRaster);
+    validateShutterMechanism(input.shutterMechanism);
+    const readout = parseReadoutDeclaration(input.readout);
+    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 scan = readout.readoutMode === "rolling"
+        ? {
+            pattern: "uniform-linear-single-axis",
+            directionNative: readout.scanDirectionNative,
+            unitVectorNative: scanVector(readout.scanDirectionNative.value),
+            spatialSamplingSkewSeconds: readout.spatialSamplingSkewSeconds
+        }
+        : null;
+    const samples = (input.samplePointsNative ?? []).map((point, index) => {
+        validatePointWithinActiveCapture(point, activeCaptureRect, index);
+        if (scan === null) {
+            return {
+                pointNative: { x: point.x, y: point.y },
+                normalizedScanPosition: null,
+                readoutPhaseOffsetSeconds: 0
+            };
+        }
+        const normalized = normalizedScanPosition(point, activeCaptureRect, scan.directionNative.value);
+        return {
+            pointNative: { x: point.x, y: point.y },
+            normalizedScanPosition: normalized,
+            readoutPhaseOffsetSeconds: normalized * scan.spatialSamplingSkewSeconds.value
+        };
+    });
+    return approximationResult({
+        readoutMode: readout.readoutMode,
+        shutterMechanism: input.shutterMechanism,
+        nativeRaster: { ...input.nativeRaster },
+        activeCaptureRect: { ...activeCaptureRect },
+        captureReadoutDurationSeconds: readout.captureReadoutDurationSeconds,
+        maximumSpatialSamplingSkewSeconds: readout.readoutMode === "rolling"
+            ? readout.spatialSamplingSkewSeconds.value
+            : 0,
+        scan,
+        samples
+    }, "native-sensor-readout-scan-timing", "1.0.0", [
+        "Native raster coordinates use top-left origin, +X right and +Y down and remain invariant under physical camera orientation.",
+        "Rolling timing uses a uniform-linear single-axis approximation over continuous effective native-raster coordinates.",
+        "NativeImageRaster is an effective image-sampling grid; the timing map does not assert one raster row or column equals one physical photodiode or hardware readout line.",
+        "Capture data-readout duration and spatial sampling skew are independently declared facts; no equality or ordering relationship is inferred between them.",
+        "Global readout has zero spatial sampling skew in this model even when capture data-readout duration is non-zero.",
+        "Active-capture timing is caller-declared and is not inferred by scaling full-frame timing by crop dimensions.",
+        "Physical orientation and digital output crop/resolution are downstream of this invariant native timing schedule.",
+        "Shutter mechanism is reported independently and does not alter the sensor scan schedule in this foundation.",
+        "The model does not represent segmented, center-out, interleaved, multi-tap or other non-uniform readout patterns.",
+        "The model does not define exposure windows, shutter-curtain travel, rolling-shutter geometry distortion, flash/flicker interaction or camera/subject motion integration."
+    ]);
+}
+//# sourceMappingURL=readout-timing.js.map

package/dist/sensor/readout-timing.js.map

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

package/dist/sensor/response-application-compatibility.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Module boundary and integration notes.
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary. Response application
+ * checks exact profile/channel, source plane, incident-area basis, spatial uniformity and reference
+ * conditions. Structural compatibility alone does not authorize signal conversion; per-bin
+ * operating-range validity and the typed EQE/A-W path are separate gates.
+ * Assess whether exact source-plane, area, profile/channel and reference-condition bindings permit the
+ * selected response application path. Response application checks exact profile/channel, source plane,
+ * incident-area basis, spatial uniformity and reference conditions. Structural compatibility alone
+ * does not authorize signal conversion; per-bin operating-range validity and the typed EQE/A-W path
+ * are separate gates.
+ * @see docs/MOTION_AND_SIGNAL.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 { SensorSpectralReferenceConditions, SensorSpectralResponseScientificStatus } from "./spectral-response.js";
+import type { SensorSpatioSpectralIrradianceReduction } from "./spatio-spectral-reduction.js";
+export type SensorResponseSourcePlane = "sensor-package-incident" | "site-incident";
+export type SensorResponseIncidentAreaBasis = {
+    kind: "geometric-sensitive-aperture";
+    areaSquareMicrometers: number;
+} | {
+    kind: "full-site-cell";
+    areaSquareMicrometers: number;
+} | {
+    kind: "effective-collection-area";
+    areaSquareMicrometers: number;
+};
+export type SensorResponseSpatialModel = {
+    kind: "uniform-over-geometric-sensitive-aperture";
+    scientificStatus: SensorSpectralResponseScientificStatus;
+    evidence: readonly EvidenceProvenance[];
+    limitation?: string;
+} | {
+    kind: "not-established";
+    limitation: string;
+};
+export type SensorResponseReferenceConditionPolicy = {
+    kind: "exact-match-required";
+} | {
+    kind: "assume-compatible";
+    limitation: string;
+    evidence: readonly EvidenceProvenance[];
+};
+export interface SensorResponseApplicationProfile {
+    schemaVersion: "0.1.0";
+    profileId: string;
+    spectralResponseProfileId: string;
+    colorSamplingProfileId: string;
+    channelId: string;
+    samplingApertureProfileId: string;
+    opticalStackProfileId: string;
+    evidence: readonly EvidenceProvenance[];
+    incidentAreaBasis: SensorResponseIncidentAreaBasis;
+    spatialResponseModel: SensorResponseSpatialModel;
+    referenceConditionPolicy: SensorResponseReferenceConditionPolicy;
+}
+export interface SourcedSensorResponseSourcePlane {
+    value: SensorResponseSourcePlane;
+    evidence: readonly EvidenceProvenance[];
+}
+export interface AssessSensorResponseApplicationCompatibilityInput {
+    reduction: SensorSpatioSpectralIrradianceReduction;
+    applicationProfile: SensorResponseApplicationProfile;
+    sourcePlane: SourcedSensorResponseSourcePlane;
+    operatingConditions?: SensorSpectralReferenceConditions;
+}
+export type SensorResponseApplicationCompatibilityBlocker = "spectral-response-profile-id-mismatch" | "color-sampling-profile-id-mismatch" | "channel-id-mismatch" | "sampling-aperture-profile-id-missing" | "sampling-aperture-profile-id-mismatch" | "optical-stack-profile-id-missing" | "optical-stack-profile-id-mismatch" | "source-plane-mismatch" | "wavelength-basis-unresolved" | "incident-area-basis-not-currently-integrated" | "incident-area-mismatch" | "spatial-response-uniformity-not-established" | "response-reference-conditions-not-declared" | "operating-conditions-not-declared" | "operating-conditions-mismatch";
+export type SensorResponseSignalPath = "photon-rate-to-electrons" | "radiant-power-to-current";
+export interface SensorResponseApplicationCompatibilityAssessment {
+    applicationProfileId: string;
+    spectralResponseProfileId: string;
+    colorSamplingProfileId: string;
+    channelId: string;
+    responseScope: SensorSpatioSpectralIrradianceReduction["responseScope"];
+    requiredSourcePlane: SensorResponseSourcePlane;
+    suppliedSourcePlane: SensorResponseSourcePlane;
+    sourcePlaneMatched: boolean;
+    responseIncidentAreaBasis: SensorResponseIncidentAreaBasis;
+    currentlyIntegratedAreaBasis: "geometric-sensitive-aperture";
+    geometricApertureAreaSquareMicrometers: number;
+    nominalSiteCellAreaSquareMicrometers?: number;
+    spatialResponseModel: SensorResponseSpatialModel;
+    referenceConditionPolicy: SensorResponseReferenceConditionPolicy;
+    responseReferenceConditions?: SensorSpectralReferenceConditions;
+    operatingConditions?: SensorSpectralReferenceConditions;
+    structuralCompatibilityEstablished: boolean;
+    compatibilityStatus: "compatible" | "compatible-approximation" | "blocked";
+    blockers: readonly SensorResponseApplicationCompatibilityBlocker[];
+    requiredSignalPath: SensorResponseSignalPath;
+    quantifiedResponseUncertaintyAvailable: boolean;
+    responseApplicationPerformed: false;
+    signalConversionAuthorized: false;
+    temporalIntegrationAuthorized: false;
+    photonConversionPerformed: false;
+    electronConversionPerformed: false;
+    currentConversionPerformed: false;
+    operatingRangeCompatibilityAssessed: false;
+    spatiallyVaryingResponseSupported: false;
+    componentEvidence: {
+        applicationProfile: readonly EvidenceProvenance[];
+        sourcePlane: readonly EvidenceProvenance[];
+        spatialResponse: readonly EvidenceProvenance[];
+        referenceConditionAssumption: readonly EvidenceProvenance[];
+        response: SensorSpatioSpectralIrradianceReduction["componentEvidence"]["spectral"];
+    };
+}
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Response application checks exact profile/channel, source plane, incident-area basis, spatial
+ * uniformity and reference conditions. Structural compatibility alone does not authorize signal
+ * conversion; per-bin operating-range validity and the typed EQE/A-W path are separate gates.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns SensorResponseApplicationProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export declare function parseSensorResponseApplicationProfile(value: unknown): SensorResponseApplicationProfile;
+/**
+ * Assess whether exact source-plane, area, profile/channel and reference-condition bindings permit the
+ * selected response application path.
+ *
+ * Response application checks exact profile/channel, source plane, incident-area basis, spatial
+ * uniformity and reference conditions. Structural compatibility alone does not authorize signal
+ * conversion; per-bin operating-range validity and the typed EQE/A-W path are separate gates.
+ * @param input - AssessSensorResponseApplicationCompatibilityInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<SensorResponseApplicationCompatibilityAssessment>. Read structured blockers before consuming an authorization.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export declare function assessSensorResponseApplicationCompatibility(input: AssessSensorResponseApplicationCompatibilityInput): CalculationResult<SensorResponseApplicationCompatibilityAssessment>;
+//# sourceMappingURL=response-application-compatibility.d.ts.map

package/dist/sensor/response-application-compatibility.d.ts.map

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