@photivra/engine 0.5.1 → 1.0.0

package/dist/capture/export-tiff.js

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Module boundary and integration notes.
+ * Pack validated unsigned integer tag values into little-endian BYTE, SHORT or LONG payloads; reject
+ * values outside the selected storage range.
+ * Describe an internal BYTE/UNDEFINED tag using the supplied byte array. The payload is borrowed here;
+ * the final TIFF packer copies it into its owned output buffer.
+ * @see docs/SIMULATED_CAPTURE.md for equations, coordinate/unit conventions, blockers and support
+ * limits.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+/**
+ * Pack validated unsigned integer tag values into little-endian BYTE, SHORT or LONG payloads; reject
+ * values outside the selected storage range.
+ * @param id - number. See the linked contract for coordinate, unit and profile binding semantics.
+ * @param type - 1 | 3 | 4. See the linked contract for coordinate, unit and profile binding semantics.
+ * @param values - readonly number[]. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns ExportTiffTag. 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 function exportTiffNumbers(id, type, values) {
+    const size = type === 1 ? 1 : type === 3 ? 2 : 4, data = new Uint8Array(values.length * size), view = new DataView(data.buffer);
+    values.forEach((v, i) => {
+        if (!Number.isSafeInteger(v) || v < 0 || v > (type === 1 ? 255 : type === 3 ? 65535 : 4294967295))
+            throw new InvalidConfigurationError("TIFF integer is out of range.");
+        if (size === 1)
+            view.setUint8(i, v);
+        else if (size === 2)
+            view.setUint16(i * size, v, true);
+        else
+            view.setUint32(i * size, v, true);
+    });
+    return { id, type, count: values.length, data };
+}
+/**
+ * Describe an internal BYTE/UNDEFINED tag using the supplied byte array. The payload is borrowed here;
+ * the final TIFF packer copies it into its owned output buffer.
+ * @param id - number. See the linked contract for coordinate, unit and profile binding semantics.
+ * @param type - 1 | 7. See the linked contract for coordinate, unit and profile binding semantics.
+ * @param data - Uint8Array. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns ExportTiffTag. 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 function exportTiffBytes(id, type, data) {
+    return { id, type, count: data.length, data };
+}
+/**
+ * Encode printable ASCII with the required NUL terminator; reject unsupported characters instead of
+ * silent lossy replacement.
+ * @param id - number. See the linked contract for coordinate, unit and profile binding semantics.
+ * @param value - string. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns ExportTiffTag. 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 function exportTiffAscii(id, value) {
+    if (!/^[\x20-\x7e]*$/.test(value))
+        throw new InvalidConfigurationError("TIFF text requires printable ASCII.");
+    const data = new TextEncoder().encode(value + "\0");
+    return { id, type: 2, count: data.length, data };
+}
+/** Bounded rational approximation; matrix/metadata precision is explicit, never silent overflow. */
+export function exportTiffRationals(id, signed, values) {
+    const data = new Uint8Array(values.length * 8), view = new DataView(data.buffer);
+    values.forEach((v, i) => {
+        const limit = signed ? 2147483647 : 4294967295;
+        const denominator = Math.min(1000000000, 10 ** Math.floor(Math.log10(limit / Math.max(1, Math.abs(v))))), numerator = Math.round(v * denominator);
+        if (!Number.isFinite(v) || denominator < 1 || (!signed && v < 0) || Math.abs(numerator) > limit ||
+            (v !== 0 && numerator === 0))
+            throw new InvalidConfigurationError("TIFF rational exceeds supported precision/range.");
+        if (signed)
+            view.setInt32(i * 8, numerator, true);
+        else
+            view.setUint32(i * 8, numerator, true);
+        view.setUint32(i * 8 + 4, denominator, true);
+    });
+    return { id, type: signed ? 10 : 5, count: values.length, data };
+}
+/** Independently authored little-endian TIFF6 IFD0 + EXIF IFD, with optional uncompressed strip. */
+export function packExportTiff(main, exif, pixels = new Uint8Array()) {
+    const pointer = { ...exportTiffNumbers(34665, 4, [0]), pointer: "exif" };
+    const lists = [[...main, pointer].sort((a, b) => a.id - b.id), [...exif].sort((a, b) => a.id - b.id)];
+    for (const tags of lists) {
+        if (tags.length > 128 || new Set(tags.map((t) => t.id)).size !== tags.length)
+            throw new InvalidConfigurationError("Duplicate/oversized TIFF directory.");
+    }
+    /**
+     * Directories precede their out-of-line payloads. Four-byte alignment applies to
+     * payload addresses; values up to four bytes stay in the directory slot. Pointer
+     * placeholders are resolved only against this newly owned buffer, preventing a
+     * caller-supplied address from becoming an external file/memory reference.
+     */
+    const exifOffset = 8 + 2 + lists[0].length * 12 + 4;
+    let cursor = exifOffset + 2 + lists[1].length * 12 + 4;
+    const offsets = new Map();
+    for (const tags of lists)
+        for (const t of tags) {
+            if (t.data.length > 4) {
+                cursor = (cursor + 3) & ~3;
+                offsets.set(t, cursor);
+                cursor += t.data.length;
+            }
+        }
+    const pixelOffset = (cursor + 3) & ~3, result = new Uint8Array(pixelOffset + pixels.length), view = new DataView(result.buffer);
+    result.set([73, 73, 42, 0, 8, 0, 0, 0]);
+    lists.forEach((tags, directory) => {
+        const base = directory === 0 ? 8 : exifOffset;
+        view.setUint16(base, tags.length, true);
+        tags.forEach((t, i) => {
+            const p = base + 2 + i * 12;
+            view.setUint16(p, t.id, true);
+            view.setUint16(p + 2, t.type, true);
+            view.setUint32(p + 4, t.count, true);
+            if (t.pointer)
+                view.setUint32(p + 8, t.pointer === "exif" ? exifOffset : pixelOffset, true);
+            else if (t.data.length <= 4)
+                result.set(t.data, p + 8);
+            else {
+                view.setUint32(p + 8, offsets.get(t), true);
+                result.set(t.data, offsets.get(t));
+            }
+        });
+    });
+    result.set(pixels, pixelOffset);
+    return result;
+}
+//# sourceMappingURL=export-tiff.js.map

package/dist/capture/export-tiff.js.map

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

package/dist/capture/focus-control.d.ts

@@ -0,0 +1,210 @@
+import { type EvidenceProvenance } from "../core/evidence-provenance.js";
+import { type FocusPlane } from "../optics/focus-state.js";
+export declare const FOCUS_CONTROL_PROFILE_SCHEMA_VERSION: "0.1.0";
+export declare const FOCUS_CONTROL_STATE_VERSION: "0.1.0";
+export type FocusControlMode = "manual" | "single-af" | "continuous-af";
+export type FocusAcquisitionState = "idle" | "acquiring" | "acquired" | "target-lost" | "locked";
+export type FocusReleasePriority = "focus-priority" | "release-priority" | "balanced";
+export type FocusTargetLossReason = "occluded" | "out-of-frame" | "identity-lost" | "outside-focus-area";
+export interface FocusControlProfile {
+    schemaVersion: typeof FOCUS_CONTROL_PROFILE_SCHEMA_VERSION;
+    profileId: string;
+    profileVersion: string;
+    scientificStatus: "approximation";
+    supportedModes: readonly FocusControlMode[];
+    actuator: {
+        kind: "ideal-instantaneous";
+        evidence: readonly EvidenceProvenance[];
+    };
+    continuousTargetLossPolicy: "hold-last-focus-require-explicit-reacquisition";
+    supportedReleasePriorities: readonly FocusReleasePriority[];
+    evidence: readonly EvidenceProvenance[];
+    limitations: readonly string[];
+}
+interface FocusTargetObservationBase {
+    targetId: string;
+    focusAreaId?: string;
+    observedAtSeconds: number;
+}
+export type FocusTargetObservation = (FocusTargetObservationBase & {
+    kind: "finite-surface";
+    /**
+     * Longitudinal camera-space/conjugate distance from #103, not renderer
+     * ray length.
+     */
+    longitudinalDistanceM: number;
+}) | (FocusTargetObservationBase & {
+    kind: "infinity-environment";
+}) | (FocusTargetObservationBase & {
+    kind: "unavailable";
+    reason: FocusTargetLossReason;
+});
+/**
+ * Immutable logical MF/single-AF/continuous-AF state. Resolved focus remains a
+ * finite longitudinal distance in metres or explicit infinity. Acquisition, loss,
+ * reacquisition and lock records explain why a target is usable; a focus-release
+ * gate remains separate from shutter sequencing. The ideal actuator does not model
+ * commercial AF measurement accuracy or physical acquisition time.
+ */
+export interface FocusControlState {
+    version: typeof FOCUS_CONTROL_STATE_VERSION;
+    stateId: string;
+    sourceProfile: {
+        profileId: string;
+        profileVersion: string;
+    };
+    profileLimitations: readonly string[];
+    mode: FocusControlMode;
+    acquisitionState: FocusAcquisitionState;
+    focus: FocusPlane;
+    activeTargetId?: string;
+    activeFocusAreaId?: string;
+    lastEventTimeSeconds: number;
+    focusResolvedAtSeconds: number;
+    locked: boolean;
+    lock?: {
+        lockedAtSeconds: number;
+        resumeAcquisitionState: Exclude<FocusAcquisitionState, "locked">;
+    };
+    actuatorModel: "ideal-instantaneous";
+    continuousTargetLossPolicy: "hold-last-focus-require-explicit-reacquisition";
+    exposureModified: false;
+    meteringModified: false;
+    whiteBalanceModified: false;
+    subjectTrackingRecognitionModeled: false;
+    rendererCoordinatesConsumed: false;
+    limitations: readonly string[];
+}
+export interface CreateFocusControlStateInput {
+    stateId: string;
+    profile: FocusControlProfile;
+    mode: FocusControlMode;
+    initialFocus: FocusPlane;
+    initialTimeSeconds?: number;
+}
+export interface SetManualFocusStateInput {
+    state: FocusControlState;
+    stateId: string;
+    focus: FocusPlane;
+    eventTimeSeconds: number;
+    commandId?: string;
+}
+export type FocusTargetControlEvent = "acquire" | "update";
+export interface ResolveFocusTargetObservationInput {
+    state: FocusControlState;
+    stateId: string;
+    event: FocusTargetControlEvent;
+    observation: FocusTargetObservation;
+}
+export interface FocusTargetResolution {
+    state: FocusControlState;
+    targetObservationApplied: boolean;
+    focusChanged: boolean;
+    acquisitionEvent: FocusTargetControlEvent;
+    actuatorModel: "ideal-instantaneous";
+    silentRetargetingPerformed: false;
+}
+export interface SetFocusLockInput {
+    state: FocusControlState;
+    stateId: string;
+    locked: boolean;
+    eventTimeSeconds: number;
+}
+export interface AssessFocusReleaseGateInput {
+    state: FocusControlState;
+    profile: FocusControlProfile;
+    priority: FocusReleasePriority;
+}
+export interface FocusReleaseGateAssessment {
+    priority: FocusReleasePriority;
+    releaseAuthorized: boolean;
+    reason: "manual-focus-state" | "focus-acquired" | "focus-locked" | "release-priority-bypasses-focus-gate" | "focus-not-acquired" | "balanced-policy-not-modeled";
+    requiresProfileSpecificBalancedPolicy: boolean;
+    opticalFocusModified: false;
+    exposureModified: false;
+}
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns FocusControlProfile. 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 parseFocusControlProfile(value: unknown): FocusControlProfile;
+/**
+ * Create the initial ideal focus-controller state from an explicit profile, focus plane and public
+ * state identity.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param input - CreateFocusControlStateInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns FocusControlState. 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 createFocusControlState(input: CreateFocusControlStateInput): FocusControlState;
+/**
+ * Return a manual focus transition to the supplied finite/infinity plane without inventing a lens
+ * actuator or focus-ring conversion.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param input - SetManualFocusStateInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns FocusControlState. 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 setManualFocusState(input: SetManualFocusStateInput): FocusControlState;
+/**
+ * Resolve an explicit available/lost target observation under the selected single/continuous AF
+ * policy, retaining acquisition and reacquisition disposition.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param input - ResolveFocusTargetObservationInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns FocusTargetResolution. 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 resolveFocusTargetObservation(input: ResolveFocusTargetObservationInput): FocusTargetResolution;
+/**
+ * Return an explicit lock/unlock transition without changing the underlying physical focus plane.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param input - SetFocusLockInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns FocusControlState. 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 setFocusLock(input: SetFocusLockInput): FocusControlState;
+/**
+ * Report whether release may proceed under focus-priority or release-priority policy; this does not
+ * operate a shutter.
+ *
+ * Focus is a longitudinal plane or explicit infinity state, never a screen-space distance. The ideal
+ * actuator resolves supplied target observations; it does not infer a commercial AF sensor, focus-ring
+ * scale or acquisition latency. Target loss, reacquisition, focus lock and release priority remain
+ * separate state transitions.
+ * @param input - AssessFocusReleaseGateInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns FocusReleaseGateAssessment. Read structured blockers before consuming an authorization.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export declare function assessFocusReleaseGate(input: AssessFocusReleaseGateInput): FocusReleaseGateAssessment;
+export {};
+//# sourceMappingURL=focus-control.d.ts.map

package/dist/capture/focus-control.d.ts.map

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