@photivra/engine 0.5.1 → 1.0.0

package/docs/api/sensor-responsivity-photocurrent.md

@@ -0,0 +1,245 @@
+# sensor/responsivity-photocurrent.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateSensorResponsivityPhotocurrent
+
+Integrate per-wavelength A/W times radiant-power contributions to steady-state current magnitude
+with explicit electrical applicability.
+
+A/W response converts per-bin radiant power to quasi-static detector-terminal current magnitude.
+Electrical bias/load applicability is explicit. This is not EQE, electron rate, transimpedance
+voltage or RAW; rapidly varying current requires a separate temporal detector-response model.
+
+```ts
+export function calculateSensorResponsivityPhotocurrent(
+  input:
+    CalculateSensorResponsivityPhotocurrentInput
+): CalculationResult<SensorResponsivityPhotocurrent>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorResponsivityPhotocurrentInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorResponsivityPhotocurrentInput {
+  reduction:
+    SensorSpatioSpectralIrradianceReduction;
+  compatibility:
+    SensorResponseApplicationCompatibilityAssessment;
+  operatingRange:
+    SensorResponseOperatingRangeAssessment;
+  colorSamplingProfile:
+    SensorColorSamplingProfile;
+  spectralResponseProfile:
+    SensorSpectralResponseProfile;
+  electricalApplicabilityProfile:
+    SensorResponsivityElectricalApplicabilityProfile;
+  operatingElectricalConditions:
+    SensorResponsivityElectricalConditions;
+}
+```
+
+## parseSensorResponsivityElectricalApplicabilityProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+A/W response converts per-bin radiant power to quasi-static detector-terminal current magnitude.
+Electrical bias/load applicability is explicit. This is not EQE, electron rate, transimpedance
+voltage or RAW; rapidly varying current requires a separate temporal detector-response model.
+
+```ts
+export function parseSensorResponsivityElectricalApplicabilityProfile(
+  value: unknown
+): SensorResponsivityElectricalApplicabilityProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SensorResponsivityBiasCondition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponsivityBiasCondition =
+  | {
+      kind: "zero-bias-photovoltaic";
+    }
+  | {
+      kind: "reverse-biased";
+      magnitudeVolts: number;
+    };
+```
+
+## SensorResponsivityElectricalApplicabilityProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponsivityElectricalApplicabilityProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  responseApplicationProfileId: string;
+  spectralResponseProfileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  outputMeaning:
+    "detector-terminal-photocurrent-magnitude";
+  referenceConditions:
+    SensorResponsivityElectricalConditions;
+  conditionPolicy:
+    SensorResponsivityElectricalConditionPolicy;
+  scientificStatus:
+    SensorSpectralResponseScientificStatus;
+  uncertainty:
+    SensorSpectralResponseUncertainty;
+  evidence: readonly EvidenceProvenance[];
+}
+```
+
+## SensorResponsivityElectricalConditionPolicy
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponsivityElectricalConditionPolicy =
+  | {
+      kind: "exact-match-required";
+    }
+  | {
+      kind: "assume-compatible";
+      limitation: string;
+      evidence: readonly EvidenceProvenance[];
+    };
+```
+
+## SensorResponsivityElectricalConditions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponsivityElectricalConditions {
+  bias: SensorResponsivityBiasCondition;
+  readoutLoad:
+    SensorResponsivityReadoutLoadCondition;
+}
+```
+
+## SensorResponsivityPhotocurrent
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponsivityPhotocurrent {
+  colorSamplingProfileId: string;
+  responseProfileId: string;
+  responseApplicationProfileId: string;
+  operatingRangeProfileId: string;
+  electricalApplicabilityProfileId:
+    string;
+  /** Engine-produced results populate the exact source color site. */
+  site?: {
+    x: number;
+    y: number;
+  };
+  channelId: string;
+  sourceResponseKind:
+    "effective-spectral-responsivity";
+  responseScope:
+    SensorSpatioSpectralIrradianceReduction["responseScope"];
+  responseReferencePlane:
+    SensorResponseApplicationCompatibilityAssessment["requiredSourcePlane"];
+  wavelengthBasis:
+    SensorSpatioSpectralIrradianceReduction["wavelengthBasis"];
+  wavelengthRangeNanometers:
+    SensorSpatioSpectralIrradianceReduction["wavelengthRangeNanometers"];
+  electricalReferenceConditions:
+    SensorResponsivityElectricalConditions;
+  operatingElectricalConditions:
+    SensorResponsivityElectricalConditions;
+  electricalConditionPolicy:
+    SensorResponsivityElectricalConditionPolicy;
+  electricalCompatibility:
+    | "exact-match"
+    | "assumed-compatible";
+  spectralNodeCount: number;
+  perWavelength:
+    readonly SensorResponsivityWavelengthCurrentContribution[];
+  photocurrentMagnitudeAmperes: number;
+  currentSignConvention:
+    "magnitude-only-no-circuit-polarity";
+  summationMethod:
+    "kahan-compensated";
+  responseApplicationPerformed: true;
+  spectralResponsivityApplied: true;
+  quantumEfficiencyApplied: false;
+  photonRateCalculated: false;
+  electronRateCalculated: false;
+  currentCalculated: true;
+  chargeCalculated: false;
+  temporalResponseModel:
+    "quasi-static-steady-state-only";
+  detectorBandwidthModeled: false;
+  transimpedanceGainApplied: false;
+  voltageCalculated: false;
+  temporalIntegrationApplied: false;
+  exposureDurationApplied: false;
+  saturationAssessed: false;
+  readoutElectronicsLinearityAssessed:
+    false;
+  shotNoiseApplied: false;
+  readNoiseApplied: false;
+  adcQuantizationApplied: false;
+  rawCodeValueProduced: false;
+  responseUncertaintyPropagated: false;
+  electricalApplicabilityUncertaintyPropagated:
+    false;
+  quadratureConvergenceErrorEstimated:
+    false;
+  componentEvidence: {
+    electricalApplicability:
+      readonly EvidenceProvenance[];
+    electricalConditionAssumption:
+      readonly EvidenceProvenance[];
+  };
+}
+```
+
+## SensorResponsivityReadoutLoadCondition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorResponsivityReadoutLoadCondition =
+  | {
+      kind: "virtual-ground-current-readout";
+    }
+  | {
+      kind: "finite-input-impedance";
+      inputImpedanceOhms: number;
+    };
+```
+
+## SensorResponsivityWavelengthCurrentContribution
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorResponsivityWavelengthCurrentContribution {
+  spectralSampleIndex: number;
+  wavelengthNanometers: number;
+  wavelengthMeasureNanometers: number;
+  geometricApertureIncidentSpectralFluxWattsPerNanometer:
+    number;
+  radiantPowerContributionWatts: number;
+  spectralResponsivityAmperesPerWatt:
+    number;
+  responseInterpolationUsed: boolean;
+  photocurrentMagnitudeContributionAmperes:
+    number;
+}
+```

package/docs/api/sensor-sampling-aperture.md

@@ -0,0 +1,221 @@
+# sensor/sampling-aperture.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## NativeSensorPhysicalBoundsMm
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeSensorPhysicalBoundsMm {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+}
+```
+
+## NativeSensorPhysicalPointMm
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NativeSensorPhysicalPointMm {
+  x: number;
+  y: number;
+}
+```
+
+## parseSensorSamplingApertureProfile
+
+Parses physical registration of the color-site lattice plus a first geometric
+photosensitive-aperture model.
+
+Site-center pitch/origin are explicit facts and are never derived from
+NativeImageRaster. The rectangle, when resolved, is a geometric sensitive
+region only. It does not include microlens redirection, charge diffusion,
+electrical crosstalk, QE, throughput, spectral response, or an effective
+radiometric collection area.
+
+```ts
+export function parseSensorSamplingApertureProfile(
+  value: unknown
+): SensorSamplingApertureProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedSensorSamplingAperture
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedSensorSamplingAperture {
+  profileId: string;
+  colorSamplingProfileId: string;
+  colorSamplingBindingId: string;
+  coordinateSystem: "native-sensor-physical";
+  site: NativeColorSamplingSiteIndex;
+  channelId: string;
+  siteGrid: {
+    widthSites: number;
+    heightSites: number;
+  };
+  lattice: {
+    pitchXMicrometers: number;
+    pitchYMicrometers: number;
+    firstSiteCenterFromImagingAreaTopLeftMicrometers: {
+      x: number;
+      y: number;
+    };
+    siteCenterFromImagingAreaTopLeftMicrometers: {
+      x: number;
+      y: number;
+    };
+    siteCenterFromOpticalAxisMm: NativeSensorPhysicalPointMm;
+    nominalCellAreaSquareMicrometers: number;
+  };
+  geometricSensitiveAperture: {
+    kind: "uniform-axis-aligned-rectangle";
+    widthMicrometers: number;
+    heightMicrometers: number;
+    centerOffsetFromSiteCenterMicrometers: {
+      x: number;
+      y: number;
+    };
+    centerFromOpticalAxisMm: NativeSensorPhysicalPointMm;
+    boundsFromOpticalAxisMm: NativeSensorPhysicalBoundsMm;
+    areaSquareMicrometers: number;
+    geometricSensitiveAreaFractionOfLatticeCell: number;
+    spatialWeighting:
+      "uniform-unit-area-average";
+    neighboringGeometricApertureOverlap:
+      "none-by-model";
+  };
+  /**
+   * Hard scientific boundaries.
+   */
+  sitePitchDerivedFromNativeImageRaster: false;
+  apertureDerivedFromSitePitch: false;
+  antiAliasingResponseIncluded: false;
+  microlensSpatialRedistributionIncluded: false;
+  chargeDiffusionIncluded: false;
+  electricalCrosstalkIncluded: false;
+  spectralResponseIncluded: false;
+  quantumEfficiencyIncluded: false;
+  opticalThroughputIncluded: false;
+  radiometricCollectionAreaEstablished: false;
+  physicalPhotodiodeGeometryEstablished: false;
+  provenance: {
+    profile: readonly EvidenceProvenance[];
+    lattice: readonly EvidenceProvenance[];
+    aperture: readonly EvidenceProvenance[];
+  };
+}
+```
+
+## resolveSensorSamplingAperture
+
+Resolves one geometric sampling aperture in native sensor physical space.
+
+The result provides a normalized uniform-area spatial averaging footprint for
+future image sampling, plus its geometric physical area/fill-fraction
+diagnostics. It deliberately does not promote that geometric area into
+radiometric collection efficiency or physical photodiode truth.
+
+```ts
+export function resolveSensorSamplingAperture(
+  input: ResolveSensorSamplingApertureInput
+): ResolvedSensorSamplingAperture;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveSensorSamplingApertureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveSensorSamplingApertureInput {
+  imagingArea: SensorImagingArea;
+  nativeRaster: NativeImageRaster;
+  colorSamplingProfile: SensorColorSamplingProfile;
+  colorSamplingBindingProfile: NativeEffectiveRasterColorSamplingBindingProfile;
+  samplingApertureProfile: SensorSamplingApertureProfile;
+  site: NativeColorSamplingSiteIndex;
+}
+```
+
+## SensorGeometricSensitiveAperture
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorGeometricSensitiveAperture =
+  | {
+      /**
+       * The physical/light-sensitive spatial aperture is known to matter but
+       * its geometry is not defensibly resolved.
+       */
+      kind: "unresolved";
+      evidence: readonly EvidenceProvenance[];
+    }
+  | {
+      /**
+       * First geometric sensitive-region approximation.
+       *
+       * This rectangle is constrained to remain inside one regular lattice
+       * cell, so neighboring geometric sensitive regions do not overlap in
+       * schema 0.1.0.
+       */
+      kind: "uniform-axis-aligned-rectangle";
+      widthMicrometers: number;
+      heightMicrometers: number;
+      centerOffsetFromSiteCenterMicrometers: {
+        x: number;
+        y: number;
+      };
+      evidence: readonly EvidenceProvenance[];
+    };
+```
+
+## SensorSamplingApertureProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSamplingApertureProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  colorSamplingProfileId: string;
+  colorSamplingBindingId: string;
+  evidence: readonly EvidenceProvenance[];
+  siteCenterLattice: SensorSiteCenterLatticeRegistration;
+  geometricSensitiveAperture: SensorGeometricSensitiveAperture;
+}
+```
+
+## SensorSiteCenterLatticeRegistration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorSiteCenterLatticeRegistration {
+  kind: "regular-rectangular-site-center-lattice";
+  coordinateSystem: "native-sensor-physical";
+  /** Horizontal site-center pitch in micrometres. */
+  pitchXMicrometers: number;
+  /** Vertical site-center pitch in micrometres. */
+  pitchYMicrometers: number;
+  /**
+   * First site center relative to the imaging area's physical top-left edge.
+   *
+   * +X right, +Y down. Units: micrometres.
+   */
+  firstSiteCenterFromImagingAreaTopLeftMicrometers: {
+    x: number;
+    y: number;
+  };
+  evidence: readonly EvidenceProvenance[];
+}
+```

package/docs/api/sensor-scene-eqe-temporal-exposure.md

@@ -0,0 +1,56 @@
+# sensor/scene-eqe-temporal-exposure.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateSceneSensorEqeTemporalExposure
+
+Compose declared scene radiance through paraxial optics and instantaneous EQE
+at every exact local shutter midpoint. Light is never averaged before response
+validity. No projection, renderer, PSF, charge/noise or production stage executes.
+
+```ts
+export function calculateSceneSensorEqeTemporalExposure(
+  input: CalculateSceneSensorEqeTemporalExposureInput
+): CalculationResult<SceneSensorEqeTemporalExposure>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSceneSensorEqeTemporalExposureInput
+
+Declared physical scene radiance at every spatial/wavelength/local-shutter midpoint.
+
+```ts
+export interface CalculateSceneSensorEqeTemporalExposureInput {
+  /** One destination site, response and local shutter event; no stationarity declaration. */
+  sensor: Omit<CalculateSensorEqeTemporalExposureInput, "samples">;
+  sceneBindings: CalculateSceneToSensorIrradianceQuadratureInput["sceneBindings"];
+  optics: CalculateSceneToSensorIrradianceQuadratureInput["optics"];
+  /** Explicitly binds scene query seconds to the shutter's first-opening boundary. */
+  timeReference: "first-opening-boundary-phase";
+  samples: readonly {
+    temporalSampleIndex: number;
+    timeSecondsFromOpeningReference: number;
+    sceneSamples: CalculateSceneToSensorIrradianceQuadratureInput["samples"];
+  }[];
+}
+```
+
+## SceneSensorEqeTemporalExposure
+
+Child optical and sensor envelopes retain approximation/evidence independently.
+
+```ts
+export interface SceneSensorEqeTemporalExposure {
+  sourcePlane: "sensor-package-incident";
+  sourceTargetProjectionVerified: false;
+  sceneProviderExecutionVerified: false;
+  psfRedistributionApplied: false;
+  opticalSamples: readonly {
+    temporalSampleIndex: number;
+    timeSecondsFromOpeningReference: number;
+    optics: ReturnType<typeof calculateSceneToSensorIrradianceQuadrature>;
+  }[];
+  exposure: ReturnType<typeof calculateSensorEqeTemporalExposure>;
+}
+```

package/docs/api/sensor-sensor-geometry.md

@@ -0,0 +1,143 @@
+# sensor/sensor-geometry.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## calculateImagingAreaMetrics
+
+Calculates physical imaging-area metrics independently from native raster
+density.
+
+Crop factor uses the diagonal ratio to a 36 × 24 mm reference frame.
+Digital/output crops are not part of this physical imaging-area quantity.
+
+```ts
+export function calculateImagingAreaMetrics(
+  imagingArea: SensorImagingArea
+): CalculationResult<ImagingAreaMetrics>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateSensorGeometryMetrics
+
+Calculates physical imaging-area, native-raster, and geometric sampling
+metrics without coupling sensor size to resolution.
+
+The supplied raster is assumed to span the supplied imaging area. Derived
+sampling pitch is geometric sample spacing only and must not be interpreted
+as photosite fill factor or photon-collection area.
+
+```ts
+export function calculateSensorGeometryMetrics(
+  input: CalculateSensorGeometryMetricsInput
+): CalculationResult<SensorGeometryMetrics>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorGeometryMetricsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorGeometryMetricsInput {
+  imagingArea: SensorImagingArea;
+  nativeRaster: NativeImageRaster;
+}
+```
+
+## ImagingAreaMetrics
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImagingAreaMetrics {
+  /** Physical imaging-area diagonal in millimetres. */
+  diagonalMm: number;
+  /** Physical width divided by physical height. */
+  aspectRatio: number;
+  /**
+   * Diagonal crop factor relative to a 36 × 24 mm reference frame.
+   *
+   * This is a physical imaging-area quantity and does not include later
+   * digital/output cropping.
+   */
+  cropFactor35Mm: number;
+}
+```
+
+## NativeImageRaster
+
+Native effective image-sampling raster associated with an imaging area.
+
+This alias identifies semantic role; generic active/output rasters should
+use RasterDimensions instead.
+
+```ts
+export type NativeImageRaster = RasterDimensions;
+```
+
+## RasterDimensions
+
+Native effective image-sampling raster associated with an imaging area.
+
+The raster describes effective image samples. It does not imply that each
+sample corresponds one-to-one with a physical photodiode/photosite.
+
+```ts
+export interface RasterDimensions {
+  /** Horizontal image-sample/pixel count. */
+  pixelWidth: number;
+  /** Vertical image-sample/pixel count. */
+  pixelHeight: number;
+}
+```
+
+## SensorGeometryMetrics
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorGeometryMetrics {
+  imagingArea: ImagingAreaMetrics;
+  nativeRaster: {
+    /** Exact product of native raster width and height. */
+    totalImageSamples: number;
+    /** Derived megapixels from the exact native raster. */
+    megapixels: number;
+    /** Native raster width divided by native raster height. */
+    aspectRatio: number;
+  };
+  sampling: {
+    /**
+     * Horizontal geometric sampling pitch in micrometres.
+     *
+     * This is image-sample spacing, not physical photodiode active area.
+     */
+    pitchXMicrometers: number;
+    /**
+     * Vertical geometric sampling pitch in micrometres.
+     *
+     * This is image-sample spacing, not physical photodiode active area.
+     */
+    pitchYMicrometers: number;
+    /** Horizontal sampling pitch divided by vertical sampling pitch. */
+    pitchAspectRatio: number;
+  };
+}
+```
+
+## SensorImagingArea
+
+Physical photosensitive imaging area used for image formation.
+
+This is deliberately not a sensor package/die dimension.
+
+```ts
+export interface SensorImagingArea {
+  /** Physical active imaging width in millimetres. */
+  widthMm: number;
+  /** Physical active imaging height in millimetres. */
+  heightMm: number;
+}
+```