nmr-processing 22.5.1 → 22.6.0

package/dist/nmr-processing.d.ts

@@ -1216,6 +1216,7 @@ export declare interface NMRZone {
     x: FromTo;
     y: FromTo;
     integration?: number;
+    absolute?: number;
     id?: string;
     signals: NMRSignal2D[];
 }
@@ -2845,12 +2846,46 @@ export declare interface XYZAutoZonesPickingOptions {
 
 export declare function xyzPhaseCorrection(data: NmrData2DFt, options: PhaseCorrectionTwoDOptions): NmrData2DFt;
 
+/**
+ * Integrates a zone in 2D spectra data assuming the delta X/Y is constant.
+ * the integration and absolute values are the same.
+ */
 export declare function xyzZoneIntegration<T extends NMRZone>(spectraData: NmrData2DContent, zone: T): T & {
     integration: number;
 };
 
-export declare function xyzZonesIntegration<T extends NMRZone>(spectraData: NmrData2DContent, zones: T[]): Array<T & {
+/**
+ * Integrates zones over a 2D NMR spectrum grid.
+ *
+ * This function computes the absolute integrated area for each provided zone
+ * by summing the matrix values inside the zone bounds and multiplying by
+ * the area element (|deltaX * deltaY|). If `options.maxIntegrationValue`
+ * is provided and is not 0, the function normalizes all zone integrations so
+ * that the sum of `integration` values equals `maxIntegrationValue`.
+ *
+ * Assumptions:
+ * - `spectraData.z` is a regular 2D matrix of numbers with dimensions
+ *   `[rows][columns]` corresponding to Y and X axis points respectively.
+ * - X and Y axes are uniformly spaced between `minX..maxX` and `minY..maxY`.
+ *
+ * Behavior details:
+ * - The zone coordinates are specified as `FromTo` ranges for `x` and `y`.
+ * - Matrix indices are calculated by rounding the coordinate-to-index mapping
+ *   and clamped to the matrix bounds.
+ * - `absolute` is the raw area (sum * |dx * dy|) and `integration` is
+ *   either equal to `absolute` or a normalized value depending on options.
+ *
+ * @param spectraData - 2D spectrum content.
+ * @param zones - Array of zones to integrate. Each zone must expose `x` and `y` ranges.
+ * @returns A new array where each zone is extended with numeric properties
+ *   `absolute` (raw area) and `integration` (possibly normalized).
+ *
+ * @example
+ * const integrated = xyzZonesIntegration(spectra, zones, { maxIntegrationValue: 100 });
+ */
+export declare function xyzZonesIntegration<T extends NMRZone>(spectraData: NmrData2DContent, zones: T[], options?: ZonesIntegrationOptions): Array<T & {
     integration: number;
+    absolute: number;
 }>;
 
 declare type ZeroFilling = FilterFactory<Entry1D, ZeroFillingOptions> & Pick<ZeroFillingFilterOptions, 'name'>;
@@ -2868,6 +2903,16 @@ declare type ZoneForMapping = Pick<Zone, 'id' | 'kind' | 'x' | 'y'> & {
     signals: SignalForMapping[];
 };
 
+export declare interface ZonesIntegrationOptions {
+    /**
+     * If provided and non-zero, the integrations
+     *   are scaled so that their max value would be qual this value.
+     *   Set to `0` to skip rescaling.
+     * @default 100
+     */
+    maxIntegrationValue?: number;
+}
+
 
 export * from "gyromagnetic-ratio";