@photivra/engine 0.5.1 → 1.0.0

package/dist/sensor/spectral-quadrature.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Module boundary and integration notes.
+ * Revalidate continuous spectral node identity, support and nanometre measures before reducing a
+ * supplied wavelength plan. Continuous spectral midpoint planning uses explicit nanometre measures and
+ * response-supported intervals. Knot/breakpoint alignment does not prove convergence. Discrete/delta
+ * lines require their own integrated measure and cannot be silently widened into continuous bins.
+ * Builds deterministic wavelength quadrature nodes for one exact sensor response channel without
+ * applying the response to a source spectrum. The requested wavelength range must lie fully inside the
+ * response channel's declared usable range. Response-curve knots and optional caller-provided
+ * continuous-spectrum/optics breakpoints partition that range. Each segment is then subdivided so no
+ * midpoint subinterval exceeds maximumSubintervalWidthNanometers. wavelengthMeasureNanometers is
+ * d-lambda in nanometres. It is not a dimensionless response weight. Future integration must use a
+ * source spectral density expressed per nanometre or explicitly convert units before multiplying by
+ * this measure. This function deliberately does not apply QE or A/W responsivity. Those
+ * representations have different compatible downstream signal domains: QE is photon-to-electron
+ * efficiency, while A/W responsivity relates incident radiant power to electrical current. A later
+ * versioned composition must also match responseScope to the source plane and collection-area
+ * semantics before integrating any signal.
+ * @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 { SpectralWavelengthBasis, SpectralWavelengthRangeNanometers } from "../core/spectral.js";
+import { type SensorColorSamplingProfile } from "./color-sampling.js";
+import { type SensorSpectralReferenceConditions, type SensorSpectralResponseProfile, type SensorSpectralResponseScientificStatus, type SensorSpectralResponseUncertainty } from "./spectral-response.js";
+export type SensorSpectralWavelengthRangeNanometers = SpectralWavelengthRangeNanometers;
+export interface CalculateSensorSpectralQuadratureInput {
+    colorSamplingProfile: SensorColorSamplingProfile;
+    spectralResponseProfile: SensorSpectralResponseProfile;
+    channelId: string;
+    wavelengthBasis: SpectralWavelengthBasis;
+    /**
+     * Explicit wavelength interval to sample. This API validates the interval
+     * against sensor-response support only; it does not establish scene-spectrum
+     * or optical-transmission coverage.
+     */
+    wavelengthRangeNanometers: SensorSpectralWavelengthRangeNanometers;
+    /**
+     * Hard upper bound on each midpoint subinterval width.
+     *
+     * Response knots and optional additional breakpoints split the requested
+     * range first; each resulting segment is then subdivided until every
+     * subinterval is no wider than this value.
+     */
+    maximumSubintervalWidthNanometers: number;
+    /**
+     * Optional strictly increasing wavelength breakpoints from other continuous
+     * spectral factors, such as scene spectral-density or optical-transmission
+     * interpolation knots. Values must lie strictly inside the requested range.
+     *
+     * These coordinates do not assert that those external factors are actually
+     * available or valid over the requested range.
+     */
+    additionalBreakpointsNanometers?: readonly number[];
+}
+export interface SensorSpectralQuadratureNode {
+    spectralSampleIndex: number;
+    segmentIndex: number;
+    subdivisionIndex: number;
+    segmentSubdivisionCount: number;
+    /**
+     * Midpoint wavelength for this subinterval. Units: nm in wavelengthBasis.
+     */
+    wavelengthNanometers: number;
+    /**
+     * d-lambda represented by this node. Units: nm.
+     *
+     * This is wavelength measure only. It is not response-weighted throughput,
+     * photon count, radiant energy, current, or a dimensionless probability.
+     */
+    wavelengthMeasureNanometers: number;
+    /**
+     * Dimensionless wavelength measure normalized by the requested range width.
+     *
+     * This may be useful for averages, but it is not a sensor-response weight.
+     */
+    normalizedWavelengthWeight: number;
+}
+export interface SensorSpectralQuadrature {
+    profileId: string;
+    colorSamplingProfileId: string;
+    channelId: string;
+    sourceResponseKind: SensorSpectralResponseProfile["channels"][number]["kind"];
+    responseScope: SensorSpectralResponseProfile["channels"][number]["responseScope"];
+    responseScientificStatus: SensorSpectralResponseScientificStatus;
+    responseUncertainty: SensorSpectralResponseUncertainty;
+    responseChannelBinding?: import("./spectral-response.js").SensorSpectralResponseChannelBinding;
+    responseReferenceConditions?: SensorSpectralReferenceConditions;
+    wavelengthBasis: SpectralWavelengthBasis;
+    wavelengthBasisResolved: boolean;
+    wavelengthRangeNanometers: SensorSpectralWavelengthRangeNanometers;
+    responseDeclaredWavelengthRangeNanometers: SensorSpectralWavelengthRangeNanometers;
+    quadratureScheme: "response-breakpoint-aware-bounded-midpoint";
+    segmentBoundarySource: "requested-range-plus-response-knots-plus-optional-additional-breakpoints";
+    /**
+     * Ordered unique segment boundaries, including requested range endpoints.
+     */
+    segmentBoundariesNanometers: readonly number[];
+    maximumSubintervalWidthNanometers: number;
+    segmentCount: number;
+    totalNodeCount: number;
+    normalizedWavelengthWeightSum: number;
+    wavelengthMeasureSumNanometers: number;
+    nodes: readonly SensorSpectralQuadratureNode[];
+    responseKnotAlignmentIncluded: true;
+    componentEvidence: {
+        colorSamplingProfile: readonly EvidenceProvenance[];
+        profile: readonly EvidenceProvenance[];
+        channel: readonly EvidenceProvenance[];
+        curves: readonly (readonly EvidenceProvenance[])[];
+    };
+    /**
+     * Hard scientific boundaries.
+     */
+    responseValuesIncluded: false;
+    responseApplicationPerformed: false;
+    sourceSpectralValuesIncluded: false;
+    spectralIrradianceIncluded: false;
+    spectralPhotonIrradianceIncluded: false;
+    commonSpectralCoverageValidated: false;
+    continuousSpectralDensityQuadratureOnly: true;
+    discreteLineSpectrumIncluded: false;
+    opticalTransmissionIncludedByQuadrature: false;
+    wavelengthIntegrationPerformed: false;
+    spatialIntegrationPerformed: false;
+    temporalIntegrationPerformed: false;
+    photonsCalculated: false;
+    electronsCalculated: false;
+    rawCodeValueProduced: false;
+    convergenceErrorEstimated: false;
+}
+/**
+ * Revalidate continuous spectral node identity, support and nanometre measures before reducing a
+ * supplied wavelength plan.
+ *
+ * Continuous spectral midpoint planning uses explicit nanometre measures and response-supported
+ * intervals. Knot/breakpoint alignment does not prove convergence. Discrete/delta lines require their
+ * own integrated measure and cannot be silently widened into continuous bins.
+ * @param quadrature - SensorSpectralQuadrature. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns Map<number, SensorSpectralQuadratureNode>. 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 validateSensorSpectralQuadrature(quadrature: SensorSpectralQuadrature): Map<number, SensorSpectralQuadratureNode>;
+/**
+ * Builds deterministic wavelength quadrature nodes for one exact sensor
+ * response channel without applying the response to a source spectrum.
+ *
+ * The requested wavelength range must lie fully inside the response channel's
+ * declared usable range. Response-curve knots and optional caller-provided
+ * continuous-spectrum/optics breakpoints partition that range. Each segment is
+ * then subdivided so no midpoint subinterval exceeds
+ * maximumSubintervalWidthNanometers.
+ *
+ * wavelengthMeasureNanometers is d-lambda in nanometres. It is not a
+ * dimensionless response weight. Future integration must use a source spectral
+ * density expressed per nanometre or explicitly convert units before
+ * multiplying by this measure.
+ *
+ * This function deliberately does not apply QE or A/W responsivity. Those
+ * representations have different compatible downstream signal domains: QE is
+ * photon-to-electron efficiency, while A/W responsivity relates incident
+ * radiant power to electrical current. A later versioned composition must also
+ * match responseScope to the source plane and collection-area semantics before
+ * integrating any signal.
+ */
+export declare function calculateSensorSpectralQuadrature(input: CalculateSensorSpectralQuadratureInput): CalculationResult<SensorSpectralQuadrature>;
+//# sourceMappingURL=spectral-quadrature.d.ts.map

package/dist/sensor/spectral-quadrature.d.ts.map

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