@photivra/engine 0.5.1 → 1.0.0

package/dist/sensor/capture-mode-timing.js

@@ -0,0 +1,270 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Module boundary and integration notes.
+ * Parses timing facts that are explicitly bound to one exact capture mode. Schema 0.1.0 intentionally
+ * admits only the timing schedule families already owned by #12: simultaneous/global or uniform-linear
+ * native scans. Unsupported non-uniform/segmented schedules fail closed instead of being approximated.
+ * Resolves the authoritative exposure/readout timing for one exact capture mode and timing-profile
+ * identity. Readout timing remains distinct from exposure-boundary timing. No absolute
+ * readout/exposure synchronization is inferred.
+ * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
+ * limits.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { calculateCaptureExposureWindows } from "./exposure-window.js";
+import { calculateSensorReadoutTiming } from "./readout-timing.js";
+export const CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION = "0.1.0";
+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"
+]);
+function requireRecord(value, path) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value)) {
+        throw new InvalidConfigurationError(path + " must be an object.");
+    }
+    return value;
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0) {
+        throw new InvalidConfigurationError(path + " must be a non-empty string.");
+    }
+    return value.trim();
+}
+function requireNonNegativeFinite(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        value < 0) {
+        throw new InvalidConfigurationError(path +
+            " must be finite and greater than or equal to zero.");
+    }
+    return value;
+}
+function parseLimitations(value, path) {
+    if (!Array.isArray(value)) {
+        throw new InvalidConfigurationError(path + " must be an array.");
+    }
+    const parsed = value.map((entry, index) => requireNonEmptyString(entry, path + "[" + index + "]"));
+    if (new Set(parsed).size !==
+        parsed.length) {
+        throw new InvalidConfigurationError(path +
+            " must not contain duplicates.");
+    }
+    return parsed;
+}
+function parseSecondsFact(value, path) {
+    const record = requireRecord(value, path);
+    if (record.unit !== "s") {
+        throw new InvalidConfigurationError(path + '.unit must be "s".');
+    }
+    return {
+        value: requireNonNegativeFinite(record.value, path + ".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 InvalidConfigurationError(path + ".value is invalid.");
+    }
+    return {
+        value: record.value,
+        evidence: parseEvidenceList(record.evidence, path + ".evidence")
+    };
+}
+function parseBoundarySchedule(value, path) {
+    const record = requireRecord(value, path);
+    if (record.kind === "simultaneous") {
+        if (record.directionNative !==
+            undefined ||
+            record.traversalDurationSeconds !==
+                undefined) {
+            throw new InvalidConfigurationError(path +
+                " simultaneous schedule must not include scan-only fields.");
+        }
+        return {
+            kind: "simultaneous"
+        };
+    }
+    if (record.kind ===
+        "uniform-linear-native-scan") {
+        return {
+            kind: "uniform-linear-native-scan",
+            directionNative: parseDirectionFact(record.directionNative, path + ".directionNative"),
+            traversalDurationSeconds: parseSecondsFact(record.traversalDurationSeconds, path +
+                ".traversalDurationSeconds")
+        };
+    }
+    throw new InvalidConfigurationError(path +
+        '.kind must be "simultaneous" or "uniform-linear-native-scan"; non-uniform schedules are not modeled.');
+}
+function parseReadout(value, path) {
+    const record = requireRecord(value, path);
+    const duration = parseSecondsFact(record.captureReadoutDurationSeconds, path +
+        ".captureReadoutDurationSeconds");
+    if (record.readoutMode === "global") {
+        if (record.scanDirectionNative !==
+            undefined ||
+            record.spatialSamplingSkewSeconds !==
+                undefined) {
+            throw new InvalidConfigurationError(path +
+                " global readout must not include rolling-scan fields.");
+        }
+        return {
+            readoutMode: "global",
+            captureReadoutDurationSeconds: duration
+        };
+    }
+    if (record.readoutMode === "rolling") {
+        return {
+            readoutMode: "rolling",
+            captureReadoutDurationSeconds: duration,
+            scanDirectionNative: parseDirectionFact(record.scanDirectionNative, path +
+                ".scanDirectionNative"),
+            spatialSamplingSkewSeconds: parseSecondsFact(record.spatialSamplingSkewSeconds, path +
+                ".spatialSamplingSkewSeconds")
+        };
+    }
+    throw new InvalidConfigurationError(path +
+        '.readoutMode must be "global" or "rolling".');
+}
+/**
+ * Parses timing facts that are explicitly bound to one exact capture mode.
+ *
+ * Schema 0.1.0 intentionally admits only the timing schedule families already
+ * owned by #12: simultaneous/global or uniform-linear native scans. Unsupported
+ * non-uniform/segmented schedules fail closed instead of being approximated.
+ */
+export function parseCaptureModeTimingProfile(value) {
+    const record = requireRecord(value, "captureModeTimingProfile");
+    if (record.schemaVersion !==
+        CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION) {
+        throw new InvalidConfigurationError('captureModeTimingProfile.schemaVersion must be "' +
+            CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION +
+            '".');
+    }
+    if (record.scientificStatus !==
+        "approximation") {
+        throw new InvalidConfigurationError('captureModeTimingProfile.scientificStatus must be "approximation".');
+    }
+    if (record.scheduleFamily !==
+        "global-or-uniform-linear-native-scan") {
+        throw new InvalidConfigurationError('captureModeTimingProfile.scheduleFamily must be "global-or-uniform-linear-native-scan"; unsupported schedule families fail closed.');
+    }
+    if (typeof record.shutterMechanism !==
+        "string" ||
+        !SHUTTER_MECHANISMS.has(record.shutterMechanism)) {
+        throw new InvalidConfigurationError("captureModeTimingProfile.shutterMechanism is invalid.");
+    }
+    if (record.nonUniformScheduleModeled !==
+        false) {
+        throw new InvalidConfigurationError("captureModeTimingProfile.nonUniformScheduleModeled must be false in schema 0.1.0.");
+    }
+    return {
+        schemaVersion: CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION,
+        profileId: requireNonEmptyString(record.profileId, "captureModeTimingProfile.profileId"),
+        profileVersion: requireNonEmptyString(record.profileVersion, "captureModeTimingProfile.profileVersion"),
+        captureModeId: requireNonEmptyString(record.captureModeId, "captureModeTimingProfile.captureModeId"),
+        scientificStatus: "approximation",
+        scheduleFamily: "global-or-uniform-linear-native-scan",
+        shutterMechanism: record.shutterMechanism,
+        opening: parseBoundarySchedule(record.opening, "captureModeTimingProfile.opening"),
+        closing: parseBoundarySchedule(record.closing, "captureModeTimingProfile.closing"),
+        readout: parseReadout(record.readout, "captureModeTimingProfile.readout"),
+        nonUniformScheduleModeled: false,
+        evidence: parseEvidenceList(record.evidence, "captureModeTimingProfile.evidence"),
+        limitations: parseLimitations(record.limitations, "captureModeTimingProfile.limitations")
+    };
+}
+/**
+ * Resolves the authoritative exposure/readout timing for one exact capture
+ * mode and timing-profile identity.
+ *
+ * Readout timing remains distinct from exposure-boundary timing. No absolute
+ * readout/exposure synchronization is inferred.
+ */
+export function resolveCaptureModeTiming(input) {
+    const profile = parseCaptureModeTimingProfile(input.timingProfile);
+    if (profile.captureModeId !==
+        input.captureMode.modeId) {
+        throw new InvalidScientificInputError("captureModeTimingProfile.captureModeId must exactly match the resolved capture mode.");
+    }
+    const exposureWindows = calculateCaptureExposureWindows({
+        nativeRaster: input.captureMode.nativeRaster,
+        ...(input.activeCaptureRect ===
+            undefined
+            ? {}
+            : {
+                activeCaptureRect: input.activeCaptureRect
+            }),
+        shutterMechanism: profile.shutterMechanism,
+        nominalExposureDurationSeconds: input
+            .nominalExposureDurationSeconds,
+        opening: profile.opening,
+        closing: profile.closing,
+        ...(input.samplePointsNative ===
+            undefined
+            ? {}
+            : {
+                samplePointsNative: input.samplePointsNative
+            })
+    }).value;
+    const readoutTiming = calculateSensorReadoutTiming({
+        nativeRaster: input.captureMode.nativeRaster,
+        ...(input.activeCaptureRect ===
+            undefined
+            ? {}
+            : {
+                activeCaptureRect: input.activeCaptureRect
+            }),
+        shutterMechanism: profile.shutterMechanism,
+        readout: profile.readout,
+        ...(input.samplePointsNative ===
+            undefined
+            ? {}
+            : {
+                samplePointsNative: input.samplePointsNative
+            })
+    }).value;
+    return {
+        schemaVersion: CAPTURE_MODE_TIMING_PROFILE_SCHEMA_VERSION,
+        timingProfileId: profile.profileId,
+        timingProfileVersion: profile.profileVersion,
+        captureModeId: input.captureMode.modeId,
+        captureModeTimingIdentity: "exact-mode-and-profile",
+        nativeRaster: {
+            ...input.captureMode.nativeRaster
+        },
+        modeDeclaresTimingDependency: input.captureMode
+            .dependencies.includes("mode-specific-readout-timing"),
+        scheduleFamily: profile.scheduleFamily,
+        exposureWindows,
+        readoutTiming,
+        timeReference: "first-opening-boundary-phase",
+        readoutExposureSynchronization: "not-assumed",
+        nonUniformScheduleModeled: false,
+        evidence: [
+            ...input.captureMode.modeEvidence,
+            ...profile.evidence
+        ],
+        limitations: [
+            ...profile.limitations,
+            "Sensor data readout timing and exposure-boundary timing remain independent unless a separate linkage/synchronization contract establishes a relationship.",
+            "Capture-mode identity does not infer timing from CMOS/CCD, marketing labels, output raster size, or generic readout-speed names."
+        ]
+    };
+}
+//# sourceMappingURL=capture-mode-timing.js.map

package/dist/sensor/capture-mode-timing.js.map

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

package/dist/sensor/capture-mode.d.ts

@@ -0,0 +1,157 @@
+import { type EvidenceBackedFact, type EvidenceProvenance } from "../core/evidence-provenance.js";
+import type { NativeImageRaster, RasterDimensions } from "./sensor-geometry.js";
+export type CaptureModeSampleCombinationDomain = "charge-domain" | "pre-conversion-analog" | "post-conversion-digital";
+export type CaptureModeReconstructionStage = "remosaic" | "pixel-shift-combination" | "multi-frame-computational-combination";
+export type CaptureModeDependency = "color-sampling-model" | "mode-specific-readout-timing" | "radiometric-calibration" | "inter-frame-registration";
+export interface CaptureModeSensorOffsetNativeSamples {
+    /**
+     * Horizontal sensor displacement in units of the native effective sampling
+     * pitch. This is not a claim about physical photodiode pitch.
+     */
+    x: number;
+    /**
+     * Vertical sensor displacement in units of the native effective sampling
+     * pitch. This is not a claim about physical photodiode pitch.
+     */
+    y: number;
+}
+export type SourcedCaptureModeFact<T> = EvidenceBackedFact<T>;
+export interface SingleFrameCaptureAcquisition {
+    kind: "single-frame";
+}
+export interface FixedMultiFrameCaptureAcquisition {
+    kind: "fixed-multi-frame";
+    frameCount: SourcedCaptureModeFact<number>;
+}
+export interface VariableMultiFrameCaptureAcquisition {
+    kind: "variable-multi-frame";
+    /**
+     * Evidence that the mode is variable/multi-frame, even when exact count
+     * bounds are not published.
+     */
+    evidence: readonly EvidenceProvenance[];
+    minimumFrameCount?: SourcedCaptureModeFact<number>;
+    maximumFrameCount?: SourcedCaptureModeFact<number>;
+}
+export type CaptureModeAcquisition = SingleFrameCaptureAcquisition | FixedMultiFrameCaptureAcquisition | VariableMultiFrameCaptureAcquisition;
+export interface NativeEffectiveCaptureSampling {
+    kind: "native-effective-raster";
+}
+export interface GroupedNativeCaptureSampling {
+    kind: "grouped-native-samples";
+    groupWidthSamples: SourcedCaptureModeFact<number>;
+    groupHeightSamples: SourcedCaptureModeFact<number>;
+    /**
+     * Omitted means unknown/unasserted. Do not infer where combination occurs
+     * from the word "binning" or from the raster ratio.
+     */
+    combinationDomain?: SourcedCaptureModeFact<CaptureModeSampleCombinationDomain>;
+}
+export interface DeclaredEffectiveCaptureSampling {
+    kind: "declared-effective-raster";
+    /**
+     * Per-frame effective sampling raster for a mode whose sampling relationship
+     * to the native grid is not safely expressible as simple integer grouping.
+     */
+    raster: SourcedCaptureModeFact<RasterDimensions>;
+}
+export type CaptureModePerFrameSampling = NativeEffectiveCaptureSampling | GroupedNativeCaptureSampling | DeclaredEffectiveCaptureSampling;
+export interface CaptureModeDefinition {
+    modeId: string;
+    /**
+     * Evidence supporting the existence/overall acquisition behavior of this
+     * mode. Field-level facts below retain their own evidence when needed.
+     */
+    evidence: readonly EvidenceProvenance[];
+    acquisition: CaptureModeAcquisition;
+    perFrameSampling: CaptureModePerFrameSampling;
+    /**
+     * Optional ordered sensor-displacement sequence for fixed multi-frame modes.
+     * The whole sequence is one evidence-backed fact because published mode
+     * documentation commonly describes the sequence as a unit.
+     */
+    interFrameSensorOffsetsNativeSamples?: SourcedCaptureModeFact<readonly CaptureModeSensorOffsetNativeSamples[]>;
+    /**
+     * Ordered reconstruction/combination stages owned by later reconstruction
+     * work. These labels reserve semantics; they do not implement algorithms.
+     */
+    reconstructionStages?: readonly SourcedCaptureModeFact<CaptureModeReconstructionStage>[];
+    /**
+     * Image raster produced by the capture-mode/reconstruction pipeline before
+     * final output crop/resampling.
+     *
+     * This raster does not redefine physical sensor geometry or field of view.
+     */
+    processedImageRaster: SourcedCaptureModeFact<RasterDimensions>;
+    /**
+     * Explicit downstream scientific/model dependencies for this mode.
+     */
+    dependencies?: readonly CaptureModeDependency[];
+}
+export interface CaptureModeProfile {
+    schemaVersion: "0.1.0";
+    modes: readonly CaptureModeDefinition[];
+}
+export interface ResolveCaptureModeInput {
+    nativeRaster: NativeImageRaster;
+    profile: CaptureModeProfile;
+    modeId: string;
+}
+export interface ResolvedCaptureMode {
+    modeId: string;
+    modeEvidence: readonly EvidenceProvenance[];
+    nativeRaster: NativeImageRaster;
+    nativeRasterSemantic: "effective-image-sampling-grid-not-photosite-count";
+    acquisition: {
+        kind: "single-frame";
+        frameCount: 1;
+    } | {
+        kind: "fixed-multi-frame";
+        frameCount: SourcedCaptureModeFact<number>;
+    } | {
+        kind: "variable-multi-frame";
+        evidence: readonly EvidenceProvenance[];
+        minimumFrameCount?: SourcedCaptureModeFact<number>;
+        maximumFrameCount?: SourcedCaptureModeFact<number>;
+    };
+    perFrameSampling: {
+        kind: "native-effective-raster";
+        raster: NativeImageRaster;
+    } | {
+        kind: "grouped-native-samples";
+        raster: RasterDimensions;
+        groupWidthSamples: SourcedCaptureModeFact<number>;
+        groupHeightSamples: SourcedCaptureModeFact<number>;
+        combinationDomain?: SourcedCaptureModeFact<CaptureModeSampleCombinationDomain>;
+    } | {
+        kind: "declared-effective-raster";
+        raster: SourcedCaptureModeFact<RasterDimensions>;
+    };
+    interFrameSensorOffsetsNativeSamples?: SourcedCaptureModeFact<readonly CaptureModeSensorOffsetNativeSamples[]>;
+    reconstructionStages: readonly SourcedCaptureModeFact<CaptureModeReconstructionStage>[];
+    processedImageRaster: SourcedCaptureModeFact<RasterDimensions>;
+    processedImageMegapixels: number;
+    dependencies: readonly CaptureModeDependency[];
+    physicalSensorGeometryMutation: false;
+    photositeCountInference: "not-permitted-from-native-or-processed-raster";
+    finalOutputRasterOwnership: "downstream-capture-output-geometry";
+}
+/**
+ * Parses a capture-mode profile without inferring sensor physics from output
+ * resolution or marketing mode names.
+ *
+ * The profile is intentionally orthogonal: acquisition frame sequence,
+ * per-frame sampling, optional inter-frame sensor shift, reconstruction stages,
+ * processed raster and downstream dependencies are independent axes.
+ */
+export declare function parseCaptureModeProfile(value: unknown): CaptureModeProfile;
+/**
+ * Resolves one capture mode against the selected sensor's native effective
+ * image-sampling raster.
+ *
+ * Resolution changes do not mutate physical sensor geometry. The returned
+ * processed raster is pre-output geometry and must not be used to infer crop
+ * factor, field of view or physical photosite count.
+ */
+export declare function resolveCaptureMode(input: ResolveCaptureModeInput): ResolvedCaptureMode;
+//# sourceMappingURL=capture-mode.d.ts.map

package/dist/sensor/capture-mode.d.ts.map

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