@cornerstonejs/metadata 5.15.2 → 5.16.0

package/dist/esm/displayset/registerDisplaySetMetadata.js

@@ -1,7 +1,7 @@
 import { MetadataModules } from '../enums/index.js';
 import { addTyped } from '../metaData.js';
 export function registerDisplaySetMetadata(imageIds, displaySet, options = {}) {
-    const idsToRegister = new Set(imageIds);
+    const idsToRegister = new Set([displaySet.displaySetId, ...imageIds]);
     if (options.includeImageIds) {
         for (const frameId of displaySet.imageIds) {
             idsToRegister.add(frameId);

package/dist/esm/types/MetadataModuleTypes.d.ts

@@ -1,4 +1,5 @@
 import type { IDisplaySet } from '../displayset/IDisplaySet.js';
+import type { EcgWaveformAnnotation } from '../utilities/metadataProvider/ecgFromInstance.js';
 export interface DicomDateObject {
     year: number;
     month: number;
@@ -72,6 +73,7 @@ export interface EcgModuleMetadata {
     seriesTime?: string;
     seriesInstanceUID: string;
     studyInstanceUID: string;
+    waveformAnnotationSequence?: EcgWaveformAnnotation[];
 }
 export interface FrameMetadata extends SopCommonModuleMetadata {
     frameNumber: number;

package/dist/esm/types/index.d.ts

@@ -1,3 +1,4 @@
 export type { IListenerInfo, MetadataType, MetadataValueType, } from './DicomStreamTypes.js';
 export type { IImageCalibration } from './IImageCalibration.js';
 export type { DicomDateObject, DicomTimeObject, GeneralSeriesModuleMetadata, PatientStudyModuleMetadata, ImagePlaneModuleMetadata, ImagePixelModuleMetadata, SopCommonModuleMetadata, EcgModuleMetadata, FrameMetadata, TransferSyntaxMetadata, CompressedFrameDataMetadata, MetadataModuleType, } from './MetadataModuleTypes.js';
+export type { DicomCodeSequenceItem, DicomChannelDefinitionItem, DicomWaveformAnnotationItem, DicomWaveformData, DicomWaveformGroupItem, DicomEcgInstance, EcgWaveformAnnotation, EcgAnnotations, EcgNumericMetricKey, } from '../utilities/metadataProvider/ecgFromInstance.js';

package/dist/esm/utilities/decodeMultipartRelated.d.ts

@@ -0,0 +1 @@
+export declare function decodeMultipartRelated(response: ArrayBuffer, contentType?: string): ArrayBuffer[];

package/dist/esm/utilities/decodeMultipartRelated.js

@@ -0,0 +1,55 @@
+const CRLF = [13, 10];
+const HEADER_END = [13, 10, 13, 10];
+const DASH_DASH = [45, 45];
+export function decodeMultipartRelated(response, contentType) {
+    const message = new Uint8Array(response);
+    const boundary = getBoundaryFromContentType(contentType) ?? getBoundaryFromBody(message);
+    if (!boundary) {
+        return [response];
+    }
+    const delimiter = Array.from(new TextEncoder().encode(`--${boundary}`));
+    const parts = [];
+    let index = indexOf(message, delimiter, 0);
+    while (index !== -1) {
+        const afterDelimiter = index + delimiter.length;
+        if (startsWith(message, DASH_DASH, afterDelimiter)) {
+            break;
+        }
+        const headerEnd = indexOf(message, HEADER_END, afterDelimiter);
+        if (headerEnd === -1) {
+            break;
+        }
+        const dataStart = headerEnd + HEADER_END.length;
+        const next = indexOf(message, [...CRLF, ...delimiter], dataStart);
+        const dataEnd = next === -1 ? message.length : next;
+        parts.push(response.slice(dataStart, dataEnd));
+        index = next === -1 ? -1 : next + CRLF.length;
+    }
+    return parts.length ? parts : [response];
+}
+function getBoundaryFromContentType(contentType) {
+    const match = contentType?.match(/boundary=(?:"([^"]+)"|([^\s;]+))/i);
+    return match ? (match[1] ?? match[2]) : undefined;
+}
+function getBoundaryFromBody(message) {
+    if (!startsWith(message, DASH_DASH, 0)) {
+        return undefined;
+    }
+    const lineEnd = indexOf(message, CRLF, 0, 200);
+    if (lineEnd <= DASH_DASH.length) {
+        return undefined;
+    }
+    return new TextDecoder().decode(message.subarray(DASH_DASH.length, lineEnd));
+}
+function startsWith(message, token, at) {
+    return token.every((byte, i) => message[at + i] === byte);
+}
+function indexOf(message, token, from, maxLength = message.length) {
+    const end = Math.min(message.length, from + maxLength) - token.length;
+    for (let i = from; i <= end; i++) {
+        if (message[i] === token[0] && startsWith(message, token, i)) {
+            return i;
+        }
+    }
+    return -1;
+}

package/dist/esm/utilities/index.d.ts

@@ -1,4 +1,5 @@
 export { getSingleBufferFromArray } from './bulkDataFromArray.js';
+export { decodeMultipartRelated } from './decodeMultipartRelated.js';
 export { definedAttributesOf } from './definedAttributesOf.js';
 export { toNumber, toFiniteNumber, toFiniteFirst, toFiniteVector, } from './toNumber.js';
 export { default as toNumberDefault } from './toNumber.js';

package/dist/esm/utilities/index.js

@@ -1,4 +1,5 @@
 export { getSingleBufferFromArray } from './bulkDataFromArray.js';
+export { decodeMultipartRelated } from './decodeMultipartRelated.js';
 export { definedAttributesOf } from './definedAttributesOf.js';
 export { toNumber, toFiniteNumber, toFiniteFirst, toFiniteVector, } from './toNumber.js';
 export { default as toNumberDefault } from './toNumber.js';

package/dist/esm/utilities/metadataProvider/ecgFromInstance.d.ts

@@ -1,3 +1,76 @@
+export interface DicomCodeSequenceItem {
+    CodeValue?: string;
+    CodingSchemeDesignator?: string;
+    CodeMeaning?: string;
+}
+export interface DicomChannelDefinitionItem {
+    ChannelSourceSequence?: DicomCodeSequenceItem[] | ArrayLike<DicomCodeSequenceItem>;
+    ChannelSensitivity?: number | string;
+    ChannelSensitivityUnitsSequence?: DicomCodeSequenceItem[] | ArrayLike<DicomCodeSequenceItem>;
+    ChannelSensitivityCorrectionFactor?: number | string;
+    ChannelBaseline?: number | string;
+    ChannelSampleSkew?: number | string;
+    WaveformBitsStored?: number | string;
+}
+export interface DicomWaveformAnnotationItem {
+    ConceptNameCodeSequence?: DicomCodeSequenceItem[] | ArrayLike<DicomCodeSequenceItem>;
+    NumericValue?: number | number[] | string | string[];
+    MeasurementUnitsCodeSequence?: DicomCodeSequenceItem[] | ArrayLike<DicomCodeSequenceItem>;
+    ConceptCodeSequence?: DicomCodeSequenceItem[] | ArrayLike<DicomCodeSequenceItem>;
+    UnformattedTextValue?: string | string[];
+    TextValue?: string | string[];
+    ReferencedWaveformChannels?: number | number[];
+    TemporalRangeType?: string | string[];
+    ReferencedSamplePositions?: number | number[];
+    ReferencedTimeOffsets?: number | number[];
+    ReferencedDateTime?: string | string[];
+}
+export interface DicomWaveformData {
+    retrieveBulkData?: () => Promise<unknown>;
+    BulkDataURI?: string;
+    InlineBinary?: string;
+    Value?: ArrayBuffer | Uint8Array | Int16Array[] | string;
+}
+export interface DicomWaveformGroupItem {
+    NumberOfWaveformChannels?: number;
+    NumberOfWaveformSamples?: number;
+    SamplingFrequency?: number;
+    WaveformBitsAllocated?: number;
+    WaveformSampleInterpretation?: string;
+    MultiplexGroupLabel?: string;
+    ChannelDefinitionSequence?: DicomChannelDefinitionItem[] | ArrayLike<DicomChannelDefinitionItem>;
+    WaveformData?: DicomWaveformData;
+    waveformData?: DicomWaveformData;
+}
+export interface DicomEcgInstance {
+    [key: string]: unknown;
+    WaveformSequence?: DicomWaveformGroupItem[] | ArrayLike<DicomWaveformGroupItem>;
+    WaveformAnnotationSequence?: DicomWaveformAnnotationItem[] | ArrayLike<DicomWaveformAnnotationItem>;
+}
+export interface EcgWaveformAnnotation {
+    concept?: {
+        codeMeaning?: string;
+        codeValue?: string;
+        codingSchemeDesignator?: string;
+    };
+    numericValue?: number;
+    unit?: string;
+    textValue?: string;
+}
+export interface EcgAnnotations {
+    ventricularHeartRate?: number;
+    prInterval?: number;
+    qrsDuration?: number;
+    qtInterval?: number;
+    qtcInterval?: number;
+    rrInterval?: number;
+    pAxis?: number;
+    qrsAxis?: number;
+    tAxis?: number;
+    units?: Partial<Record<EcgNumericMetricKey, string>>;
+    interpretations?: string[];
+    all?: EcgWaveformAnnotation[];
+}
 export interface EcgModuleFull {
     numberOfWaveformChannels: number;
     numberOfWaveformSamples: number;
@@ -5,14 +78,50 @@ export interface EcgModuleFull {
     waveformBitsAllocated: number;
     waveformSampleInterpretation: string;
     multiplexGroupLabel: string;
+    multiplexGroupIndex?: number;
+    totalMultiplexGroups?: number;
     channelDefinitionSequence: Array<{
         channelSourceSequence?: {
             codeMeaning?: string;
+            codeValue?: string;
+            codingSchemeDesignator?: string;
         };
+        mvPerUnit: number;
     }>;
     waveformData: {
         retrieveBulkData: () => Promise<Int16Array[]>;
     };
+    annotations?: EcgAnnotations;
+}
+export declare const ECG_DEFAULT_MV_PER_UNIT = 0.001;
+export type EcgNumericMetricKey = 'ventricularHeartRate' | 'prInterval' | 'qrsDuration' | 'qtInterval' | 'qtcInterval' | 'rrInterval' | 'pAxis' | 'qrsAxis' | 'tAxis';
+export declare function parseEcgAnnotations(instance: Record<string, unknown> | DicomEcgInstance): EcgAnnotations | undefined;
+export interface BuildEcgModuleOptions {
+    getHeaders?: () => Record<string, string> | undefined;
+    multiplexGroupIndex?: number;
 }
-export declare function buildEcgModuleFromInstance(instance: Record<string, unknown>, imageId?: string): EcgModuleFull | null;
+export declare function getEcgMultiplexGroupIndex(options: unknown): number | undefined;
+export declare function findPrimaryWaveformGroup(groups: Record<string, unknown>[], preferredIndex?: number): {
+    group: Record<string, unknown>;
+    index: number;
+};
+export declare function buildEcgModuleFromInstance(instance: Record<string, unknown>, imageId?: string, options?: BuildEcgModuleOptions): EcgModuleFull | null;
+export declare const ECG_AMPLITUDE_INDEX_SIZE = 65536;
+export declare function buildEcgCalibrationFromInstance(instance: Record<string, unknown> | undefined, options?: {
+    multiplexGroupIndex?: number;
+}): {
+    sequenceOfUltrasoundRegions: {
+        regionLocationMinX0: number;
+        regionLocationMaxX1: number;
+        regionLocationMinY0: number;
+        regionLocationMaxY1: number;
+        referencePixelX0: number;
+        referencePixelY0: number;
+        physicalDeltaX: number;
+        physicalDeltaY: number;
+        physicalUnitsXDirection: number;
+        physicalUnitsYDirection: number;
+        regionDataType: number;
+    }[];
+};
 export declare function registerEcgFromInstanceProvider(): void;

package/dist/esm/utilities/metadataProvider/ecgFromInstance.js

@@ -1,7 +1,36 @@
 import { addTypedProvider } from '../../metaData.js';
 import { MetadataModules } from '../../enums/index.js';
-import { logging as cornerstoneLogging } from '@cornerstonejs/utils';
+import { asArrayFirst, logging as cornerstoneLogging, toFiniteFirst, } from '@cornerstonejs/utils';
+import { getSingleBufferFromArray } from '../bulkDataFromArray.js';
+import { decodeMultipartRelated } from '../decodeMultipartRelated.js';
 const cs3dLogger = cornerstoneLogging.metadataLog.getLogger('utilities.metadataProvider.ecgFromInstance');
+export const ECG_DEFAULT_MV_PER_UNIT = 0.001;
+const MV_PER_SENSITIVITY_UNIT = {
+    v: 1000,
+    mv: 1,
+    uv: 0.001,
+    µv: 0.001,
+    nv: 0.000001,
+};
+function getChannelMvPerUnit(channel) {
+    const sensitivity = toFiniteFirst(channel.ChannelSensitivity);
+    if (sensitivity === undefined || sensitivity === 0) {
+        return ECG_DEFAULT_MV_PER_UNIT;
+    }
+    const correction = toFiniteFirst(channel.ChannelSensitivityCorrectionFactor) || 1;
+    const unitsSeq = toArray(channel.ChannelSensitivityUnitsSequence);
+    const unitCode = (unitsSeq[0]?.CodeValue ??
+        unitsSeq[0]?.CodeMeaning ??
+        '')
+        .trim()
+        .toLowerCase();
+    const mvPerSensitivityUnit = MV_PER_SENSITIVITY_UNIT[unitCode];
+    if (mvPerSensitivityUnit === undefined) {
+        cs3dLogger.warn(`[ecgFromInstance] Unknown ChannelSensitivityUnits "${unitCode}". Using ${ECG_DEFAULT_MV_PER_UNIT} mV for each unit.`);
+        return ECG_DEFAULT_MV_PER_UNIT;
+    }
+    return sensitivity * correction * mvPerSensitivityUnit;
+}
 function base64ToUint8Array(base64) {
     const binaryString = atob(base64);
     const bytes = new Uint8Array(binaryString.length);
@@ -11,7 +40,9 @@ function base64ToUint8Array(base64) {
     return bytes;
 }
 function convertBuffer(dataSrc, numberOfChannels, numberOfSamples, bits, type) {
-    const data = new Uint8Array(dataSrc);
+    const data = ArrayBuffer.isView(dataSrc)
+        ? new Uint8Array(dataSrc.buffer, dataSrc.byteOffset, dataSrc.byteLength)
+        : new Uint8Array(dataSrc);
     if (bits === 16 && type === 'SS') {
         const ret = [];
         const bytesPerSample = 2;
@@ -34,52 +65,10 @@ function convertBuffer(dataSrc, numberOfChannels, numberOfSamples, bits, type) {
     }
     return [];
 }
-function multipartDecode(response) {
-    const message = new Uint8Array(response);
-    const separator = new TextEncoder().encode('\r\n\r\n');
-    let offset = 0;
-    const maxHeader = 1000;
-    let headerEnd = -1;
-    for (let i = 0; i < Math.min(message.length - separator.length, offset + maxHeader); i++) {
-        let found = true;
-        for (let j = 0; j < separator.length; j++) {
-            if (message[i + j] !== separator[j]) {
-                found = false;
-                break;
-            }
-        }
-        if (found) {
-            headerEnd = i;
-            break;
-        }
-    }
-    if (headerEnd === -1)
-        return [response];
-    const headerStr = new TextDecoder().decode(message.slice(0, headerEnd));
-    const boundaryMatch = headerStr.match(/boundary=([^\s;]+)/i);
-    const boundary = boundaryMatch
-        ? new TextEncoder().encode(`--${boundaryMatch[1].replace(/"/g, '').trim()}`)
-        : null;
-    if (!boundary)
-        return [response];
-    const dataStart = headerEnd + separator.length;
-    const components = [];
-    let idx = message.indexOf(boundary[0], dataStart);
-    while (idx !== -1) {
-        const nextSep = message.indexOf(separator[0], idx);
-        if (nextSep === -1)
-            break;
-        const partStart = nextSep + separator.length;
-        const nextBound = message.indexOf(boundary[0], partStart);
-        const partEnd = nextBound === -1 ? message.length : nextBound - 2;
-        if (partEnd > partStart) {
-            components.push(response.slice(partStart, partEnd));
-        }
-        if (nextBound === -1)
-            break;
-        idx = message.indexOf(boundary[0], nextBound + boundary.length);
-    }
-    return components.length > 0 ? components : [response];
+function isDecodedChannels(value, numberOfChannels, numberOfSamples) {
+    return (Array.isArray(value) &&
+        value.length === numberOfChannels &&
+        value.every((channel) => channel instanceof Int16Array && channel.length === numberOfSamples));
 }
 function parseWadoRsImageId(imageId) {
     const uri = imageId.replace(/^wadors:/i, '');
@@ -102,12 +91,162 @@ function toArray(seq) {
     }
     return [seq];
 }
-export function buildEcgModuleFromInstance(instance, imageId) {
+const ECG_CODE_MAP = new Map([
+    ['8867-4', 'ventricularHeartRate'],
+    ['2:1', 'ventricularHeartRate'],
+    ['8625-6', 'prInterval'],
+    ['8633-0', 'qrsDuration'],
+    ['8634-8', 'qtInterval'],
+    ['8636-3', 'qtcInterval'],
+    ['8637-1', 'rrInterval'],
+    ['8626-4', 'pAxis'],
+    ['8632-2', 'qrsAxis'],
+    ['8638-9', 'tAxis'],
+]);
+const ECG_MEANING_PATTERNS = [
+    [
+        /^(?!.*\batrial\b).*\b((ventricular\s+)?heart|ventricular)\s+rate\b|^hr$/i,
+        'ventricularHeartRate',
+    ],
+    [/(^|\b)p[- ]?r\s*(interval|int)\b|^p[- ]?r$/i, 'prInterval'],
+    [/(^|\b)qrs\s*(duration|width|interval)\b|^qrs$/i, 'qrsDuration'],
+    [/(^|\b)qtc(\s*(interval|calc|int))?\b|^qtc$/i, 'qtcInterval'],
+    [/(^|\b)qt\s*(interval|int)\b|^qt$/i, 'qtInterval'],
+    [/(^|\b)r[- ]?r\s*(interval|int)\b|^r[- ]?r$/i, 'rrInterval'],
+    [/(^|\b)p(\s+wave)?\s+axis\b|axis\s+p\b/i, 'pAxis'],
+    [/(^|\b)qrs\s+axis\b|axis\s+qrs\b/i, 'qrsAxis'],
+    [/(^|\b)t(\s+wave)?\s+axis\b|axis\s+t\b/i, 'tAxis'],
+];
+function matchEcgMetric(codeValue, codeMeaning) {
+    if (codeValue && ECG_CODE_MAP.has(codeValue)) {
+        return ECG_CODE_MAP.get(codeValue);
+    }
+    return codeMeaning
+        ? ECG_MEANING_PATTERNS.find(([pattern]) => pattern.test(codeMeaning))?.[1]
+        : undefined;
+}
+function firstText(raw) {
+    const text = asArrayFirst(raw)
+        ?.toString()
+        .trim();
+    return text || undefined;
+}
+function codeText(item) {
+    return firstText(item?.CodeMeaning) || firstText(item?.CodeValue);
+}
+export function parseEcgAnnotations(instance) {
+    const seq = toArray(instance.WaveformAnnotationSequence);
+    if (!seq.length) {
+        return undefined;
+    }
+    const annotations = {
+        units: {},
+        interpretations: [],
+        all: [],
+    };
+    for (const item of seq) {
+        if (!item) {
+            continue;
+        }
+        const concept = toArray(item.ConceptNameCodeSequence)[0];
+        const codeMeaning = firstText(concept?.CodeMeaning) ?? '';
+        const codeValue = firstText(concept?.CodeValue) ?? '';
+        const numericVal = toFiniteFirst(item.NumericValue);
+        const unitItem = toArray(item.MeasurementUnitsCodeSequence)[0];
+        const unit = codeText(unitItem);
+        const codedValue = codeText(toArray(item.ConceptCodeSequence)[0]);
+        const textVal = firstText(item.UnformattedTextValue ?? item.TextValue) ?? codedValue;
+        const channelPairs = [item.ReferencedWaveformChannels ?? []].flat();
+        const isGlobal = item.TemporalRangeType === undefined &&
+            item.ReferencedSamplePositions === undefined &&
+            item.ReferencedTimeOffsets === undefined &&
+            item.ReferencedDateTime === undefined &&
+            channelPairs.every((value, index) => index % 2 === 0 || value === 0);
+        if (codeMeaning || codeValue || numericVal !== undefined || textVal) {
+            annotations.all.push({
+                concept: codeMeaning || codeValue
+                    ? {
+                        codeMeaning,
+                        codeValue,
+                        codingSchemeDesignator: firstText(concept?.CodingSchemeDesignator) ?? '',
+                    }
+                    : undefined,
+                numericValue: numericVal,
+                unit,
+                textValue: textVal,
+            });
+        }
+        if (!isGlobal) {
+            continue;
+        }
+        const metric = numericVal !== undefined
+            ? matchEcgMetric(codeValue, codeMeaning)
+            : undefined;
+        if (metric) {
+            if (annotations[metric] === undefined) {
+                annotations[metric] = numericVal;
+                annotations.units[metric] = firstText(unitItem?.CodeValue) || unit;
+            }
+            continue;
+        }
+        const finding = textVal || (numericVal === undefined ? codeMeaning : undefined);
+        if (finding && !annotations.interpretations.includes(finding)) {
+            annotations.interpretations.push(finding);
+        }
+    }
+    if (annotations.ventricularHeartRate === undefined &&
+        annotations.rrInterval !== undefined &&
+        annotations.rrInterval > 0) {
+        const rrUnit = annotations.units.rrInterval;
+        const inSeconds = rrUnit === 's' || (rrUnit !== 'ms' && annotations.rrInterval < 5);
+        const rrMs = annotations.rrInterval * (inSeconds ? 1000 : 1);
+        annotations.ventricularHeartRate = Math.round(60000 / rrMs);
+        annotations.units.ventricularHeartRate = '/min';
+    }
+    return annotations;
+}
+export function getEcgMultiplexGroupIndex(options) {
+    const index = options
+        ?.multiplexGroupIndex;
+    return Number.isInteger(index) && index >= 0
+        ? index
+        : undefined;
+}
+export function findPrimaryWaveformGroup(groups, preferredIndex) {
+    if (!groups.length) {
+        throw new Error('[ecgFromInstance] WaveformSequence has no groups');
+    }
+    if (typeof preferredIndex === 'number' &&
+        preferredIndex >= 0 &&
+        preferredIndex < groups.length) {
+        return { group: groups[preferredIndex], index: preferredIndex };
+    }
+    const rhythmIndex = groups.findIndex((g) => {
+        const label = String(g.MultiplexGroupLabel || '').toUpperCase();
+        return label.includes('RHYTHM') || label.includes('CONTINUOUS');
+    });
+    if (rhythmIndex >= 0) {
+        return { group: groups[rhythmIndex], index: rhythmIndex };
+    }
+    let bestIndex = 0;
+    let maxDuration = -1;
+    groups.forEach((g, idx) => {
+        const samples = Number(g.NumberOfWaveformSamples) || 0;
+        const freq = Number(g.SamplingFrequency) || 1;
+        const duration = freq > 0 ? samples / freq : samples;
+        if (duration > maxDuration) {
+            maxDuration = duration;
+            bestIndex = idx;
+        }
+    });
+    return { group: groups[bestIndex], index: bestIndex };
+}
+export function buildEcgModuleFromInstance(instance, imageId, options = {}) {
     const raw = instance.WaveformSequence;
     const groups = toArray(raw);
     if (!groups.length)
         return null;
-    const group = groups[0];
+    const { group, index: multiplexGroupIndex } = findPrimaryWaveformGroup(groups, options.multiplexGroupIndex);
     const numberOfChannels = group.NumberOfWaveformChannels ?? 0;
     const numberOfSamples = group.NumberOfWaveformSamples ?? 0;
     const samplingFrequency = group.SamplingFrequency ?? 1;
@@ -119,36 +258,44 @@ export function buildEcgModuleFromInstance(instance, imageId) {
         const srcSeqArr = toArray(ch.ChannelSourceSequence);
         const srcSeq = srcSeqArr[0];
         const codeMeaning = srcSeq?.CodeMeaning ?? '';
+        const codeValue = srcSeq?.CodeValue;
+        const codingSchemeDesignator = srcSeq?.CodingSchemeDesignator;
         return {
-            channelSourceSequence: { codeMeaning },
+            channelSourceSequence: { codeMeaning, codeValue, codingSchemeDesignator },
+            mvPerUnit: getChannelMvPerUnit(ch),
         };
     });
-    let waveformDataRaw = (group.WaveformData ?? group.waveformData);
-    if (waveformDataRaw &&
-        typeof waveformDataRaw.length === 'number' &&
-        waveformDataRaw.length > 0) {
+    let waveformDataRaw = group.WaveformData ?? group.waveformData;
+    if (Array.isArray(waveformDataRaw) && waveformDataRaw.length > 0) {
         waveformDataRaw = waveformDataRaw[0];
     }
     const waveformData = waveformDataRaw ?? {};
     const { wadoRsRoot = undefined, studyUID = undefined } = imageId
         ? parseWadoRsImageId(imageId)
         : {};
+    const toChannels = (value) => {
+        if (isDecodedChannels(value, numberOfChannels, numberOfSamples)) {
+            return value;
+        }
+        const bytes = getSingleBufferFromArray(value);
+        return bytes
+            ? convertBuffer(bytes, numberOfChannels, numberOfSamples, bitsAllocated, sampleInterpretation)
+            : undefined;
+    };
     const retrieveBulkData = async () => {
-        const wd = waveformData;
-        if (wd instanceof ArrayBuffer ||
-            (typeof ArrayBuffer !== 'undefined' &&
-                ArrayBuffer.isView &&
-                ArrayBuffer.isView(wd))) {
-            return convertBuffer(wd, numberOfChannels, numberOfSamples, bitsAllocated, sampleInterpretation);
+        const channels = toChannels(waveformData) ?? toChannels(waveformData.Value);
+        if (channels) {
+            return channels;
         }
-        if (waveformData.Value)
-            return waveformData.Value;
         if (waveformData.InlineBinary) {
             const raw = base64ToUint8Array(waveformData.InlineBinary);
             return convertBuffer(raw, numberOfChannels, numberOfSamples, bitsAllocated, sampleInterpretation);
         }
         if (typeof waveformData.retrieveBulkData === 'function') {
-            return waveformData.retrieveBulkData();
+            const retrieved = toChannels(await waveformData.retrieveBulkData());
+            if (retrieved) {
+                return retrieved;
+            }
         }
         if (waveformData.BulkDataURI) {
             let url = waveformData.BulkDataURI;
@@ -157,17 +304,23 @@ export function buildEcgModuleFromInstance(instance, imageId) {
                     ? `${wadoRsRoot}/studies/${studyUID}/${url}`
                     : `${wadoRsRoot}/${url}`;
             }
-            const response = await fetch(url);
-            const buffer = await response.arrayBuffer();
-            const contentType = response.headers.get('content-type') || '';
-            const decoded = contentType.includes('multipart')
-                ? multipartDecode(buffer)[0]
-                : buffer;
-            return convertBuffer(decoded, numberOfChannels, numberOfSamples, bitsAllocated, sampleInterpretation);
+            const response = await fetch(url, {
+                headers: {
+                    Accept: 'multipart/related; type="application/octet-stream"',
+                    ...options.getHeaders?.(),
+                },
+            });
+            if (!response.ok) {
+                throw new Error(`[ecgFromInstance] Waveform bulkdata fetch failed: ${response.status}`);
+            }
+            const [part] = decodeMultipartRelated(await response.arrayBuffer(), response.headers.get('content-type') ?? undefined);
+            return convertBuffer(part, numberOfChannels, numberOfSamples, bitsAllocated, sampleInterpretation);
         }
-        cs3dLogger.warn('[ecgFromInstance] No waveform data source found. group keys:', Object.keys(group), 'waveformData keys:', Object.keys(waveformData));
+        const dataKeys = Object.keys(waveformData);
+        cs3dLogger.warn('[ecgFromInstance] No waveform data source found. waveformData keys:', dataKeys.slice(0, 10), `(${dataKeys.length} total)`);
         throw new Error('[ecgFromInstance] No waveform data source found');
     };
+    const annotations = parseEcgAnnotations(instance);
     return {
         numberOfWaveformChannels: numberOfChannels,
         numberOfWaveformSamples: numberOfSamples,
@@ -175,8 +328,11 @@ export function buildEcgModuleFromInstance(instance, imageId) {
         waveformBitsAllocated: bitsAllocated,
         waveformSampleInterpretation: sampleInterpretation,
         multiplexGroupLabel,
+        multiplexGroupIndex,
+        totalMultiplexGroups: groups.length,
         channelDefinitionSequence,
         waveformData: { retrieveBulkData },
+        annotations,
     };
 }
 const ECG_FROM_INSTANCE_PRIORITY = 4_000;
@@ -186,22 +342,26 @@ const ecgFromInstanceProvider = (next, query, data, options) => {
     if (!hasWaveform) {
         return next(query, data, options);
     }
-    const result = buildEcgModuleFromInstance(instance, query);
+    const result = buildEcgModuleFromInstance(instance, query, {
+        multiplexGroupIndex: getEcgMultiplexGroupIndex(options),
+    });
     return result ?? next(query, data, options);
 };
-const ECG_AMPLITUDE_INDEX_SIZE = 65536;
-const ECG_AMPLITUDE_OFFSET = 32768;
-const ecgCalibrationProvider = (next, query, data, options) => {
-    const instance = data;
+export const ECG_AMPLITUDE_INDEX_SIZE = 65536;
+const ECG_AMPLITUDE_OFFSET = ECG_AMPLITUDE_INDEX_SIZE / 2;
+export function buildEcgCalibrationFromInstance(instance, options) {
     const raw = instance?.WaveformSequence;
     const groups = toArray(raw);
     if (!groups.length)
-        return next(query, data, options);
-    const group = groups[0];
+        return undefined;
+    const { group } = findPrimaryWaveformGroup(groups, getEcgMultiplexGroupIndex(options));
     const numberOfWaveformSamples = group.NumberOfWaveformSamples ?? 0;
     const samplingFrequency = group.SamplingFrequency ?? 1;
     const physicalDeltaX = 1 / (samplingFrequency || 1);
-    const physicalDeltaY = 0.001;
+    const firstChannel = toArray(group.ChannelDefinitionSequence)[0];
+    const physicalDeltaY = firstChannel
+        ? getChannelMvPerUnit(firstChannel)
+        : ECG_DEFAULT_MV_PER_UNIT;
     return {
         sequenceOfUltrasoundRegions: [
             {
@@ -219,7 +379,8 @@ const ecgCalibrationProvider = (next, query, data, options) => {
             },
         ],
     };
-};
+}
+const ecgCalibrationProvider = (next, query, data, options) => buildEcgCalibrationFromInstance(data, options) ?? next(query, data, options);
 export function registerEcgFromInstanceProvider() {
     addTypedProvider(MetadataModules.ECG, ecgFromInstanceProvider, {
         priority: ECG_FROM_INSTANCE_PRIORITY,

package/dist/esm/utilities/modules/ecg.js

@@ -8,4 +8,5 @@ export const tags = [
     'Modality',
     'SOPInstanceUID',
     'SOPClassUID',
+    'WaveformAnnotationSequence',
 ];

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const version = "5.15.2";
+export declare const version = "5.16.0";

package/dist/esm/version.js

@@ -1 +1 @@
-export const version = '5.15.2';
+export const version = '5.16.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cornerstonejs/metadata",
-  "version": "5.15.2",
+  "version": "5.16.0",
   "description": "Cornerstone3D Metadata Foundation - Provider chain, DICOM stream parsing, tag modules, and series splitting",
   "module": "./dist/esm/index.js",
   "types": "./dist/esm/index.d.ts",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@cornerstonejs/calculate-suv": "1.0.3",
-    "@cornerstonejs/utils": "5.15.2",
+    "@cornerstonejs/utils": "5.16.0",
     "dcmjs": "0.52.0",
     "gl-matrix": "3.4.3"
   },