@photivra/engine 0.5.1 → 1.0.0

package/dist/sensor/optical-stack.js

@@ -0,0 +1,303 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Module boundary and integration notes.
+ * 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.
+ * 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.
+ * @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";
+const COMPONENT_ROLES = new Set([
+    "cover-glass",
+    "infrared-cut",
+    "ultraviolet-cut",
+    "anti-reflection",
+    "birefringent-low-pass",
+    "wave-plate",
+    "other-optical-filter"
+]);
+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;
+}
+function parseComponentRoles(value, path) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new InvalidConfigurationError(path + " must be a non-empty array.");
+    }
+    const roles = value.map((entry, index) => {
+        if (typeof entry !== "string" ||
+            !COMPONENT_ROLES.has(entry)) {
+            throw new InvalidConfigurationError(path + "[" + index + "] is invalid.");
+        }
+        return entry;
+    });
+    if (new Set(roles).size !== roles.length) {
+        throw new InvalidConfigurationError(path + " must not contain duplicate roles.");
+    }
+    return roles;
+}
+function parseOrderedComponents(value, path) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new InvalidConfigurationError(path + " must be a non-empty array.");
+    }
+    const components = value.map((entry, index) => {
+        const record = requireRecord(entry, path + "[" + index + "]");
+        return {
+            componentId: requireNonEmptyString(record.componentId, path + "[" + index + "].componentId"),
+            roles: parseComponentRoles(record.roles, path + "[" + index + "].roles"),
+            evidence: parseEvidenceList(record.evidence, path + "[" + index + "].evidence")
+        };
+    });
+    const ids = components.map((component) => component.componentId);
+    if (new Set(ids).size !== ids.length) {
+        throw new InvalidConfigurationError(path + " must not contain duplicate componentId values.");
+    }
+    return components;
+}
+function requireFiniteNumber(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value)) {
+        throw new InvalidConfigurationError(path + " must be a finite number.");
+    }
+    return value;
+}
+function parsePointSplitComponents(value, path) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new InvalidConfigurationError(path + " must be a non-empty array.");
+    }
+    const components = value.map((entry, index) => {
+        const record = requireRecord(entry, path + "[" + index + "]");
+        const offset = requireRecord(record.offsetMicrometers, path + "[" + index + "].offsetMicrometers");
+        const normalizedWeight = requireFiniteNumber(record.normalizedWeight, path + "[" + index + "].normalizedWeight");
+        if (normalizedWeight <= 0) {
+            throw new InvalidConfigurationError(path +
+                "[" +
+                index +
+                "].normalizedWeight must be greater than zero.");
+        }
+        return {
+            offsetMicrometers: {
+                x: requireFiniteNumber(offset.x, path +
+                    "[" +
+                    index +
+                    "].offsetMicrometers.x"),
+                y: requireFiniteNumber(offset.y, path +
+                    "[" +
+                    index +
+                    "].offsetMicrometers.y")
+            },
+            normalizedWeight
+        };
+    });
+    const weightSum = components.reduce((sum, component) => sum + component.normalizedWeight, 0);
+    if (!Number.isFinite(weightSum) ||
+        Math.abs(weightSum - 1) > 1e-12) {
+        throw new InvalidConfigurationError(path +
+            " normalizedWeight values must sum to 1 within 1e-12.");
+    }
+    return components;
+}
+function parseAntiAliasingResponse(value, path) {
+    const record = requireRecord(value, path);
+    if (record.kind === "absent" ||
+        record.kind === "present-unresolved") {
+        if (record.coordinateSystem !== undefined ||
+            record.scope !== undefined ||
+            record.components !== undefined) {
+            throw new InvalidConfigurationError(path +
+                " absent/present-unresolved responses must omit kernel fields.");
+        }
+        return {
+            kind: record.kind,
+            evidence: parseEvidenceList(record.evidence, path + ".evidence")
+        };
+    }
+    if (record.kind ===
+        "normalized-point-splitting-kernel") {
+        if (record.coordinateSystem !==
+            "native-sensor-physical") {
+            throw new InvalidConfigurationError(path +
+                '.coordinateSystem must be "native-sensor-physical".');
+        }
+        if (record.scope !==
+            "field-wavelength-polarization-invariant-approximation") {
+            throw new InvalidConfigurationError(path + ".scope is invalid.");
+        }
+        return {
+            kind: "normalized-point-splitting-kernel",
+            evidence: parseEvidenceList(record.evidence, path + ".evidence"),
+            coordinateSystem: "native-sensor-physical",
+            scope: "field-wavelength-polarization-invariant-approximation",
+            components: parsePointSplitComponents(record.components, path + ".components")
+        };
+    }
+    throw new InvalidConfigurationError(path + ".kind is invalid.");
+}
+function parseMicrolens(value, path) {
+    const record = requireRecord(value, path);
+    if (record.presence !== "present" &&
+        record.presence !== "absent") {
+        throw new InvalidConfigurationError(path + ".presence is invalid.");
+    }
+    if (record.opticalEffectModel !== "unresolved") {
+        throw new InvalidConfigurationError(path +
+            '.opticalEffectModel must be "unresolved" in schema 0.1.0.');
+    }
+    return {
+        presence: record.presence,
+        evidence: parseEvidenceList(record.evidence, path + ".evidence"),
+        opticalEffectModel: "unresolved"
+    };
+}
+/**
+ * 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 function parseSensorOpticalStackProfile(value) {
+    const profile = requireRecord(value, "sensorOpticalStack");
+    if (profile.schemaVersion !== "0.1.0") {
+        throw new InvalidConfigurationError('sensorOpticalStack.schemaVersion must be "0.1.0".');
+    }
+    const orderedComponents = profile.orderedComponents === undefined
+        ? undefined
+        : parseOrderedComponents(profile.orderedComponents, "sensorOpticalStack.orderedComponents");
+    const effectiveAntiAliasingSpatialResponse = profile.effectiveAntiAliasingSpatialResponse ===
+        undefined
+        ? undefined
+        : parseAntiAliasingResponse(profile.effectiveAntiAliasingSpatialResponse, "sensorOpticalStack.effectiveAntiAliasingSpatialResponse");
+    const microlens = profile.microlens === undefined
+        ? undefined
+        : parseMicrolens(profile.microlens, "sensorOpticalStack.microlens");
+    if (orderedComponents === undefined &&
+        effectiveAntiAliasingSpatialResponse ===
+            undefined &&
+        microlens === undefined) {
+        throw new InvalidConfigurationError("sensorOpticalStack must assert at least one optical-stack fact.");
+    }
+    return {
+        schemaVersion: "0.1.0",
+        profileId: requireNonEmptyString(profile.profileId, "sensorOpticalStack.profileId"),
+        evidence: parseEvidenceList(profile.evidence, "sensorOpticalStack.evidence"),
+        ...(orderedComponents === undefined
+            ? {}
+            : { orderedComponents }),
+        ...(effectiveAntiAliasingSpatialResponse ===
+            undefined
+            ? {}
+            : {
+                effectiveAntiAliasingSpatialResponse
+            }),
+        ...(microlens === undefined
+            ? {}
+            : { microlens })
+    };
+}
+/**
+ * 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 function resolveAntiAliasingSpatialKernel(profileInput) {
+    const profile = parseSensorOpticalStackProfile(profileInput);
+    const response = profile.effectiveAntiAliasingSpatialResponse;
+    if (response === undefined) {
+        throw new InvalidScientificInputError("Effective anti-aliasing spatial response is unknown/unasserted for this optical-stack profile.");
+    }
+    if (response.kind === "present-unresolved") {
+        throw new InvalidScientificInputError("Effective anti-aliasing spatial response is present but unresolved; a spatial kernel cannot be produced.");
+    }
+    if (response.kind === "absent") {
+        return {
+            profileId: profile.profileId,
+            effectiveResponse: "absent",
+            coordinateSystem: "native-sensor-physical",
+            components: [
+                {
+                    offsetMicrometers: {
+                        x: 0,
+                        y: 0
+                    },
+                    normalizedWeight: 1
+                }
+            ],
+            normalizedWeightSum: 1,
+            throughputIncluded: false,
+            spectralTransmissionIncluded: false,
+            fieldDependenceIncluded: false,
+            wavelengthDependenceIncluded: false,
+            polarizationDependenceIncluded: false,
+            microlensResponseIncluded: false,
+            coverFilterStackEffectsIncluded: false,
+            wholeSensorOpticalStackResponse: false,
+            provenance: {
+                profile: profile.evidence,
+                antiAliasingResponse: response.evidence
+            }
+        };
+    }
+    const normalizedWeightSum = response.components.reduce((sum, component) => sum + component.normalizedWeight, 0);
+    return {
+        profileId: profile.profileId,
+        effectiveResponse: "normalized-point-splitting-kernel",
+        coordinateSystem: "native-sensor-physical",
+        components: response.components.map((component) => ({
+            offsetMicrometers: {
+                ...component.offsetMicrometers
+            },
+            normalizedWeight: component.normalizedWeight
+        })),
+        normalizedWeightSum,
+        throughputIncluded: false,
+        spectralTransmissionIncluded: false,
+        fieldDependenceIncluded: false,
+        wavelengthDependenceIncluded: false,
+        polarizationDependenceIncluded: false,
+        microlensResponseIncluded: false,
+        coverFilterStackEffectsIncluded: false,
+        wholeSensorOpticalStackResponse: false,
+        provenance: {
+            profile: profile.evidence,
+            antiAliasingResponse: response.evidence
+        }
+    };
+}
+//# sourceMappingURL=optical-stack.js.map

package/dist/sensor/optical-stack.js.map

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

package/dist/sensor/photon-energy.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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. Photon energy uses
+ * exact SI h and c with vacuum wavelength. Air wavelength requires an exact-wavelength sourced phase
+ * index and atmosphere compatibility; lambdaVacuum = n*lambdaAir. Retained refractive-index
+ * uncertainty is not an automatically propagated photon-energy uncertainty.
+ * Convert a valid vacuum wavelength, or explicitly atmosphere-bound air wavelength, into optical
+ * frequency and photon energy using exact SI constants. Photon energy uses exact SI h and c with
+ * vacuum wavelength. Air wavelength requires an exact-wavelength sourced phase index and atmosphere
+ * compatibility; lambdaVacuum = n*lambdaAir. Retained refractive-index uncertainty is not an
+ * automatically propagated photon-energy uncertainty.
+ * @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 { SensorSpectralResponseScientificStatus, SensorSpectralResponseUncertainty, SpectralWavelengthBasis } from "./spectral-response.js";
+export interface AirRefractiveIndexReferenceConditions {
+    temperatureC: number;
+    pressurePascal: number;
+    relativeHumidityFraction?: number;
+    carbonDioxideMoleFraction?: number;
+}
+export interface SourcedAirPhaseRefractiveIndex {
+    wavelengthNanometers: number;
+    wavelengthBasis: "air";
+    definition: "vacuum-wavelength-divided-by-air-wavelength";
+    phaseRefractiveIndex: number;
+    scientificStatus: SensorSpectralResponseScientificStatus;
+    uncertainty: SensorSpectralResponseUncertainty;
+    evidence: readonly EvidenceProvenance[];
+    referenceConditions?: AirRefractiveIndexReferenceConditions;
+}
+export type AirRefractiveIndexConditionPolicy = {
+    kind: "exact-match-required";
+} | {
+    kind: "assume-compatible";
+    limitation: string;
+    evidence: readonly EvidenceProvenance[];
+};
+export interface CalculatePhotonEnergyFromWavelengthInput {
+    wavelengthNanometers: number;
+    wavelengthBasis: SpectralWavelengthBasis;
+    airPhaseRefractiveIndex?: SourcedAirPhaseRefractiveIndex;
+    airOperatingConditions?: AirRefractiveIndexReferenceConditions;
+    airConditionPolicy?: AirRefractiveIndexConditionPolicy;
+}
+export interface PhotonEnergyFromWavelength {
+    inputWavelengthNanometers: number;
+    inputWavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+    vacuumWavelengthNanometers: number;
+    frequencyHertz: number;
+    photonEnergyJoules: number;
+    wavelengthConversion: "vacuum-identity" | "air-to-vacuum-via-phase-refractive-index";
+    exactSiConstants: {
+        planckConstantJouleSeconds: 6.62607015e-34;
+        speedOfLightMetersPerSecond: 299792458;
+    };
+    phaseRefractiveIndexUsed?: number;
+    airRefractiveIndexScientificStatus?: SensorSpectralResponseScientificStatus;
+    airRefractiveIndexUncertainty?: SensorSpectralResponseUncertainty;
+    airRefractiveIndexReferenceConditions?: AirRefractiveIndexReferenceConditions;
+    airRefractiveIndexEvidence?: readonly EvidenceProvenance[];
+    airOperatingConditions?: AirRefractiveIndexReferenceConditions;
+    airConditionPolicy?: AirRefractiveIndexConditionPolicy;
+    airConditionCompatibility?: "exact-match" | "assumed-compatible";
+    airConditionAssumptionEvidence?: readonly EvidenceProvenance[];
+    inputUncertaintyPropagated: 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.
+ *
+ * Photon energy uses exact SI h and c with vacuum wavelength. Air wavelength requires an
+ * exact-wavelength sourced phase index and atmosphere compatibility; lambdaVacuum = n*lambdaAir.
+ * Retained refractive-index uncertainty is not an automatically propagated photon-energy uncertainty.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns SourcedAirPhaseRefractiveIndex. 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 parseSourcedAirPhaseRefractiveIndex(value: unknown): SourcedAirPhaseRefractiveIndex;
+/**
+ * Convert a valid vacuum wavelength, or explicitly atmosphere-bound air wavelength, into optical
+ * frequency and photon energy using exact SI constants.
+ *
+ * Photon energy uses exact SI h and c with vacuum wavelength. Air wavelength requires an
+ * exact-wavelength sourced phase index and atmosphere compatibility; lambdaVacuum = n*lambdaAir.
+ * Retained refractive-index uncertainty is not an automatically propagated photon-energy uncertainty.
+ * @param input - CalculatePhotonEnergyFromWavelengthInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<PhotonEnergyFromWavelength>. 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 calculatePhotonEnergyFromWavelength(input: CalculatePhotonEnergyFromWavelengthInput): CalculationResult<PhotonEnergyFromWavelength>;
+//# sourceMappingURL=photon-energy.d.ts.map

package/dist/sensor/photon-energy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"photon-energy.d.ts","sourceRoot":"","sources":["../../src/sensor/photon-energy.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,gCAAgC,CAAC;AAExC,OAAO,KAAK,EACV,sCAAsC,EACtC,iCAAiC,EACjC,uBAAuB,EACxB,MAAM,wBAAwB,CAAC;AAUhC,MAAM,WAAW,qCAAqC;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,8BAA8B;IAC7C,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,KAAK,CAAC;IACvB,UAAU,EACR,6CAA6C,CAAC;IAChD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gBAAgB,EACd,sCAAsC,CAAC;IACzC,WAAW,EACT,iCAAiC,CAAC;IACpC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACxC,mBAAmB,CAAC,EAClB,qCAAqC,CAAC;CACzC;AAED,MAAM,MAAM,iCAAiC,GACzC;IACE,IAAI,EAAE,sBAAsB,CAAC;CAC9B,GACD;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACzC,CAAC;AAEN,MAAM,WAAW,wCAAwC;IACvD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EACb,uBAAuB,CAAC;IAC1B,uBAAuB,CAAC,EACtB,8BAA8B,CAAC;IACjC,sBAAsB,CAAC,EACrB,qCAAqC,CAAC;IACxC,kBAAkB,CAAC,EACjB,iCAAiC,CAAC;CACrC;AAED,MAAM,WAAW,0BAA0B;IACzC,yBAAyB,EAAE,MAAM,CAAC;IAClC,oBAAoB,EAClB,OAAO,CAAC,uBAAuB,EAAE,aAAa,CAAC,CAAC;IAClD,0BAA0B,EAAE,MAAM,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAChB,iBAAiB,GACjB,0CAA0C,CAAC;IAC/C,gBAAgB,EAAE;QAChB,0BAA0B,EACxB,cAAc,CAAC;QACjB,2BAA2B,EACzB,SAAS,CAAC;KACb,CAAC;IACF,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,kCAAkC,CAAC,EACjC,sCAAsC,CAAC;IACzC,6BAA6B,CAAC,EAC5B,iCAAiC,CAAC;IACpC,qCAAqC,CAAC,EACpC,qCAAqC,CAAC;IACxC,0BAA0B,CAAC,EACzB,SAAS,kBAAkB,EAAE,CAAC;IAChC,sBAAsB,CAAC,EACrB,qCAAqC,CAAC;IACxC,kBAAkB,CAAC,EACjB,iCAAiC,CAAC;IACpC,yBAAyB,CAAC,EACtB,aAAa,GACb,oBAAoB,CAAC;IACzB,8BAA8B,CAAC,EAC7B,SAAS,kBAAkB,EAAE,CAAC;IAChC,0BAA0B,EAAE,KAAK,CAAC;CACnC;AAkQD;;;;;;;;;;;GAWG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,OAAO,GACb,8BAA8B,CA4FhC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mCAAmC,CACjD,KAAK,EACH,wCAAwC,GACzC,iBAAiB,CAAC,0BAA0B,CAAC,CAuQ/C"}