DWVv0.37.0
tests/dicom/dicomVolume.test.jsjavascript
import {describe, test, assert, vi} from 'vitest';
import {
  defaultVolumeIdCandidates,
  getVolumeId,
  getVolumeIdTagValue,
  getVolumeIndices,
  getVolumeValues,
  guessVolumeIndices
} from '../../src/dicom/dicomVolume.js';
import {getFrameElements} from '../../src/dicom/dicomFunctionalGroup.js';
import {custom} from '../../src/app/custom.js';
import {logger} from '../../src/utils/logger.js';
import {DataElement} from '../../src/dicom/dataElement.js';
import {DicomParser} from '../../src/dicom/dicomParser.js';
import {transferSyntaxKeywords} from '../../src/dicom/dictionary.js';
import {
  getStructureBuffers,
  singleSliceStructure
} from '../../dev/dicom/dataStructures.js';

import syntheticData from '/tests/data/synthetic-img.json';

/**
 * Tests for the 'dicom/dicomVolume.js' file.
 */

/**
 * Related DICOM tag keys.
 */
const TagKeys = {
  SOPClassUID: '00080016',
  AcquisitionDate: '00080022',
  AcquisitionTime: '00080032',
  ContentTime: '00080033',
  Manufacturer: '00080070',
  DiffusionBValue: '00189087',
  SiemensBValue: '0019100C',
  GEBValue: '00431039',
  HitachiBValue: '00291030',
  TemporalPositionIdentifier: '00200100',
  TemporalPositionIndex: '00209128',
  TemporalPositionSequence: '00209310',
  TemporalPositionTimeOffset: '0020930D',
  PerFrameFunctionalGroupsSequence: '52009230',
  MRDiffusionSequence: '00189117',
  FrameContentSequence: '00209111',
  DimensionIndexSequence: '00209222',
  DimensionIndexPointer: '00209165',
  DimensionIndexValues: '00209157',
  EchoTime: '00180081',
  TriggerTime: '00181060',
  InversionTime: '00180082'
};

/**
 * Create DICOM elements for a multi-frame file whose frames all
 * share the given TemporalPositionIndex.
 *
 * @param {number} temporalPositionIndex The per-frame temporal
 *   position index value.
 * @param {number} [numberOfFrames] Optional number of frames
 *   (defaults to 2).
 * @returns {Record<string, DataElement>} The DICOM elements.
 */
function makeMultiFrameElements(temporalPositionIndex, numberOfFrames) {
  numberOfFrames = typeof numberOfFrames === 'undefined' ? 2 : numberOfFrames;
  const frameContentItem = {
    [TagKeys.TemporalPositionIndex]:
      makeDataElement('US', [temporalPositionIndex.toString()])
  };
  const perFrameGroupItem = {
    [TagKeys.FrameContentSequence]: makeDataElement('SQ', [frameContentItem])
  };
  const perFrameGroups = [];
  for (let i = 0; i < numberOfFrames; ++i) {
    perFrameGroups.push(perFrameGroupItem);
  }
  return {
    [TagKeys.PerFrameFunctionalGroupsSequence]:
      makeDataElement('SQ', perFrameGroups)
  };
}

/**
 * Create DICOM elements for an enhanced MR multi-frame file with
 * per-frame diffusion b-values.
 *
 * @param {number[]} bValues The per-frame b-values.
 * @returns {Record<string, DataElement>} The DICOM elements.
 */
function makeEnhancedMRElements(bValues) {
  const perFrameGroups = bValues.map(bValue => ({
    [TagKeys.MRDiffusionSequence]: makeDataElement('SQ', [{
      [TagKeys.DiffusionBValue]: makeDataElement('FD', [bValue])
    }])
  }));
  return {
    [TagKeys.SOPClassUID]: makeDataElement(
      'UI', ['1.2.840.10008.5.1.4.1.1.4.1']),
    [TagKeys.PerFrameFunctionalGroupsSequence]:
      makeDataElement('SQ', perFrameGroups)
  };
}

/**
 * Create DICOM elements for a multi-frame file with per-frame
 * TemporalPositionIndex and/or diffusion b-values.
 *
 * @param {object} frameValues The per-frame values: optional
 *   `temporalPositions`, `bValues` and `dimensionIndexValues` arrays.
 * @param {Record<string, DataElement>} [extraElements] Optional
 *   root elements.
 * @returns {Record<string, DataElement>} The DICOM elements.
 */
function makePerFrameElements(frameValues, extraElements) {
  const lists = Object.values(frameValues);
  const numberOfFrames = lists[0].length;
  const perFrameGroups = [];
  for (let i = 0; i < numberOfFrames; ++i) {
    const group = {};
    const frameContentItem = {};
    if (typeof frameValues.temporalPositions !== 'undefined') {
      frameContentItem[TagKeys.TemporalPositionIndex] =
        makeDataElement('US', [frameValues.temporalPositions[i]]);
    }
    if (typeof frameValues.dimensionIndexValues !== 'undefined') {
      frameContentItem[TagKeys.DimensionIndexValues] =
        makeDataElement('UL', frameValues.dimensionIndexValues[i]);
    }
    group[TagKeys.FrameContentSequence] =
      makeDataElement('SQ', [frameContentItem]);
    if (typeof frameValues.bValues !== 'undefined') {
      group[TagKeys.MRDiffusionSequence] = makeDataElement('SQ', [{
        [TagKeys.DiffusionBValue]:
          makeDataElement('FD', [frameValues.bValues[i]])
      }]);
    }
    perFrameGroups.push(group);
  }
  return {
    ...extraElements,
    [TagKeys.PerFrameFunctionalGroupsSequence]:
      makeDataElement('SQ', perFrameGroups)
  };
}

/**
 * Create a data element with a given VR and value.
 *
 * @param {string} vr The value representation.
 * @param {Array} value The element value.
 * @returns {DataElement} The data element.
 */
function makeDataElement(vr, value) {
  const de = new DataElement(vr);
  de.value = value;
  return de;
}

/**
 * Get a candidate getter by name.
 *
 * @param {string} name The candidate name.
 * @returns {Function} The getter.
 */
function getCandidate(name) {
  const candidate = defaultVolumeIdCandidates.find(
    item => item.name === name);
  return candidate.getter;
}

describe('dicom', () => {

  describe('defaultVolumeIdCandidates', () => {

    test('has AcquisitionTime last', () => {
      const names = defaultVolumeIdCandidates.map(item => item.name);
      assert.equal(names[names.length - 1], 'AcquisitionTime');
    });

    test('TemporalPositionIdentifier getter', () => {
      const getter = getCandidate('TemporalPositionIdentifier');
      const elements = {
        [TagKeys.TemporalPositionIdentifier]: makeDataElement('IS', ['3'])
      };
      assert.equal(getter(elements)?.value, 3);
    });

    test('TemporalPositionIdentifier getter is an index', () => {
      const getter = getCandidate('TemporalPositionIdentifier');
      const elements = {
        [TagKeys.TemporalPositionIdentifier]: makeDataElement('IS', ['3']),
        [TagKeys.TriggerTime]: makeDataElement('DS', ['120'])
      };
      // no unit: an index
      assert.deepEqual(getter(elements),
        {value: 3, tagKey: TagKeys.TemporalPositionIdentifier});
    });

    test('TemporalPositionIdentifier getter with no tag', () => {
      const getter = getCandidate('TemporalPositionIdentifier');
      assert.equal(getter({}), undefined);
    });

    test('EchoTime getter', () => {
      const getter = getCandidate('EchoTime');
      const elements = {
        [TagKeys.EchoTime]: makeDataElement('DS', ['35.5'])
      };
      // a value: no associated value
      assert.deepEqual(getter(elements),
        {value: 35.5, tagKey: TagKeys.EchoTime, unit: 'unit.ms'});
    });

    test('EchoTime getter with no tag', () => {
      const getter = getCandidate('EchoTime');
      assert.equal(getter({}), undefined);
    });

    test('EchoTime getter with non numeric value', () => {
      const getter = getCandidate('EchoTime');
      const elements = {
        [TagKeys.EchoTime]: makeDataElement('DS', ['abc'])
      };
      assert.equal(getter(elements)?.value, undefined);
    });

    test('TemporalPositionIdentifier getter with non numeric value', () => {
      const getter = getCandidate('TemporalPositionIdentifier');
      const elements = {
        [TagKeys.TemporalPositionIdentifier]: makeDataElement('IS', ['abc'])
      };
      assert.equal(getter(elements)?.value, undefined);
    });

    test('TriggerTime getter', () => {
      const getter = getCandidate('TriggerTime');
      const elements = {
        [TagKeys.TriggerTime]: makeDataElement('DS', ['120'])
      };
      assert.equal(getter(elements)?.value, 120);
    });

    test('InversionTime getter', () => {
      const getter = getCandidate('InversionTime');
      const elements = {
        [TagKeys.InversionTime]: makeDataElement('DS', ['800'])
      };
      assert.equal(getter(elements)?.value, 800);
    });

    test('AcquisitionTime getter', () => {
      const getter = getCandidate('AcquisitionTime');
      const elements = {
        [TagKeys.AcquisitionTime]: makeDataElement('TM', ['101112'])
      };
      // seconds since midnight
      assert.equal(getter(elements)?.value, 10 * 3600 + 11 * 60 + 12);
    });

    test('AcquisitionTime getter orders across midnight', () => {
      const getter = getCandidate('AcquisitionTime');
      const before = getter({
        [TagKeys.AcquisitionDate]: makeDataElement('DA', ['20260101']),
        [TagKeys.AcquisitionTime]: makeDataElement('TM', ['235959'])
      })?.value;
      const after = getter({
        [TagKeys.AcquisitionDate]: makeDataElement('DA', ['20260102']),
        [TagKeys.AcquisitionTime]: makeDataElement('TM', ['000001'])
      })?.value;
      assert.isBelow(before, after);
      assert.equal(after - before, 2);
    });

    test('DiffusionBValue getter uses root level tag for MR', () => {
      const getter = getCandidate('DiffusionBValue');
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.4']),
        [TagKeys.DiffusionBValue]: makeDataElement('FD', [800])
      };
      assert.equal(getter(elements)?.value, 800);
    });

    test('DiffusionBValue getter returns undefined for non MR', () => {
      const getter = getCandidate('DiffusionBValue');
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.2']),
        [TagKeys.DiffusionBValue]: makeDataElement('FD', [800])
      };
      assert.equal(getter(elements)?.value, undefined);
    });

    test('TemporalPositionIndex getter', () => {
      const getter = getCandidate('TemporalPositionIndex');
      const elements = makeMultiFrameElements(2);
      assert.equal(getter(elements)?.value, 2);
    });

    test('TemporalPositionIndex getter with no tag', () => {
      const getter = getCandidate('TemporalPositionIndex');
      assert.equal(getter({}), undefined);
    });

    test('TemporalPositionIndex getter with varying value', () => {
      const getter = getCandidate('TemporalPositionIndex');
      const elements = makeMultiFrameElements(2);
      // second frame has a different temporal position: inconsistent,
      // candidate should not be usable for this file
      elements[TagKeys.PerFrameFunctionalGroupsSequence].value[1] = {
        [TagKeys.FrameContentSequence]: makeDataElement('SQ', [{
          [TagKeys.TemporalPositionIndex]: makeDataElement('US', ['3'])
        }])
      };
      assert.equal(getter(elements)?.value, undefined);
    });

    test('TemporalPositionIndex getter with non numeric value', () => {
      const getter = getCandidate('TemporalPositionIndex');
      const elements = makeMultiFrameElements('abc');
      assert.equal(getter(elements)?.value, undefined);
    });

    test('TemporalPositionIndex getter ignores non numeric frame', () => {
      const getter = getCandidate('TemporalPositionIndex');
      const elements = makeMultiFrameElements(2);
      elements[TagKeys.PerFrameFunctionalGroupsSequence].value[1] = {
        [TagKeys.FrameContentSequence]: makeDataElement('SQ', [{
          [TagKeys.TemporalPositionIndex]: makeDataElement('US', ['abc'])
        }])
      };
      assert.equal(getter(elements)?.value, 2);
    });

    test('DiffusionBValue getter with per-frame enhanced MR value', () => {
      const getter = getCandidate('DiffusionBValue');
      const elements = makeEnhancedMRElements([500, 500]);
      assert.equal(getter(elements)?.value, 500);
    });

    test('DiffusionBValue getter with varying per-frame value', () => {
      const getter = getCandidate('DiffusionBValue');
      // multiple b-values in one file: not a single volume
      const elements = makeEnhancedMRElements([0, 500, 1000]);
      assert.equal(getter(elements)?.value, undefined);
    });

    test('DiffusionBValue getter keeps fractional value', () => {
      const getter = getCandidate('DiffusionBValue');
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.4']),
        [TagKeys.DiffusionBValue]: makeDataElement('FD', [50.5])
      };
      assert.equal(getter(elements)?.value, 50.5);
    });

    test('DiffusionBValue getter with small exponent value', () => {
      const getter = getCandidate('DiffusionBValue');
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.4']),
        // parseInt would give 1
        [TagKeys.DiffusionBValue]: makeDataElement('FD', [1e-7])
      };
      assert.equal(getter(elements)?.value, 1e-7);
    });

    test('DiffusionBValue getter with non numeric value', () => {
      const getter = getCandidate('DiffusionBValue');
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.4']),
        [TagKeys.DiffusionBValue]: makeDataElement('FD', ['abc'])
      };
      assert.equal(getter(elements)?.value, undefined);
    });

  });

  describe('getVolumeIdTagValue', () => {

    test('uses TemporalPositionIdentifier if present', () => {
      const elements = {
        [TagKeys.TemporalPositionIdentifier]: makeDataElement('IS', ['3'])
      };
      assert.equal(getVolumeIdTagValue(elements), 3);
    });

    test('prefers TemporalPositionIdentifier over TemporalPositionIndex',
      () => {
        const elements = makeMultiFrameElements(2);
        elements[TagKeys.TemporalPositionIdentifier] =
          makeDataElement('IS', ['5']);
        assert.equal(getVolumeIdTagValue(elements), 5);
      });

    test('uses TemporalPositionIndex for multi-frame files', () => {
      const elements = makeMultiFrameElements(2);
      assert.equal(getVolumeIdTagValue(elements), 2);
    });

    test('falls back to MR diffusion b-value with no frame tag', () => {
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.4']),
        [TagKeys.DiffusionBValue]: makeDataElement('FD', [800])
      };
      assert.equal(getVolumeIdTagValue(elements), 800);
    });

    test('uses explicit VR private b-value', () => {
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.4']),
        [TagKeys.Manufacturer]: makeDataElement('LO', ['SIEMENS']),
        [TagKeys.SiemensBValue]: makeDataElement('IS', ['1000'])
      };
      assert.equal(getVolumeIdTagValue(elements), 1000);
    });

    test('decodes implicit VR (UN) private b-value', () => {
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.4']),
        [TagKeys.Manufacturer]: makeDataElement('LO', ['SIEMENS']),
        // '1500'
        [TagKeys.SiemensBValue]: makeDataElement(
          'UN', new Uint8Array([0x31, 0x35, 0x30, 0x30]))
      };
      assert.equal(getVolumeIdTagValue(elements), 1500);
    });

    test('decodes multi-valued padded UN private b-value', () => {
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.4']),
        [TagKeys.Manufacturer]: makeDataElement('LO', ['GE MEDICAL SYSTEMS']),
        // '500\8 '
        [TagKeys.GEBValue]: makeDataElement(
          'UN', new Uint8Array([0x35, 0x30, 0x30, 0x5C, 0x38, 0x20]))
      };
      assert.equal(getVolumeIdTagValue(elements), 500);
    });

    test('uses Hitachi private b-value', () => {
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.4']),
        [TagKeys.Manufacturer]: makeDataElement(
          'LO', ['Hitachi Medical Corporation']),
        [TagKeys.HitachiBValue]: makeDataElement('DS', ['1000'])
      };
      assert.equal(getVolumeIdTagValue(elements), 1000);
    });

    test('falls back to standard b-value on invalid private one', () => {
      const elements = {
        [TagKeys.SOPClassUID]: makeDataElement(
          'UI', ['1.2.840.10008.5.1.4.1.1.4']),
        [TagKeys.Manufacturer]: makeDataElement('LO', ['SIEMENS']),
        [TagKeys.SiemensBValue]: makeDataElement(
          'UN', new Uint8Array([0x00, 0x00])),
        [TagKeys.DiffusionBValue]: makeDataElement('FD', [800])
      };
      assert.equal(getVolumeIdTagValue(elements), 800);
    });

    test('reads padded UN private b-value from generated data', () => {
      // private tag declared as UN to simulate a reader without the
      // vendor dictionary (else the parser fixes the VR)
      const config = structuredClone(syntheticData[0]);
      config.tags.Manufacturer = 'SIEMENS';
      // '500\0'
      config.tags.SiemensBValue = [0x35, 0x30, 0x30, 0x00];
      config.privateDictionary = {
        '0019': {
          '100C': ['UN', '1', 'SiemensBValue']
        }
      };
      const syntaxes = [
        transferSyntaxKeywords.ImplicitVRLittleEndian,
        transferSyntaxKeywords.ExplicitVRLittleEndian
      ];
      for (const syntax of syntaxes) {
        const buffer = getStructureBuffers(
          config, syntax, singleSliceStructure)[0];
        const parser = new DicomParser();
        parser.parse(buffer);
        const elements = parser.getDicomElements();
        assert.equal(elements[TagKeys.SiemensBValue].vr, 'UN',
          `UN vr for ${syntax}`);
        assert.equal(getVolumeIdTagValue(elements), 500,
          `b-value for ${syntax}`);
      }
    });

    test('returns undefined with no usable tag', () => {
      assert.equal(getVolumeIdTagValue({}), undefined);
    });

  });

  describe('getVolumeIdTagValue pre load candidates', () => {

    test('flags the explicit candidates', () => {
      const names = defaultVolumeIdCandidates
        .filter(item => item.preLoad === true)
        .map(item => item.name);
      assert.deepEqual(names, [
        'TemporalPositionIdentifier',
        'TemporalPositionIndex',
        'DiffusionBValue'
      ]);
    });

    test('ignores non pre load candidates', () => {
      const elements = {
        [TagKeys.EchoTime]: makeDataElement('DS', ['90'])
      };
      assert.isUndefined(getVolumeIdTagValue(elements));
    });

    test('uses custom pre load candidates', () => {
      const elements = {
        [TagKeys.EchoTime]: makeDataElement('DS', ['90']),
        [TagKeys.TemporalPositionIdentifier]: makeDataElement('IS', ['3'])
      };
      custom.volumeIdCandidates = [
        {
          name: 'EchoTime',
          getter: getCandidate('EchoTime'),
          preLoad: true
        },
        {
          name: 'TemporalPositionIdentifier',
          getter: getCandidate('TemporalPositionIdentifier')
        }
      ];
      try {
        assert.equal(getVolumeIdTagValue(elements), 90);
      } finally {
        custom.volumeIdCandidates = undefined;
      }
    });

  });

  describe('getVolumeIndices', () => {

    test('volume-major items', () => {
      assert.deepEqual(
        getVolumeIndices([1, 1, 2, 2], [0, 1, 0, 1], 2),
        [0, 0, 1, 1]);
    });

    test('slice-major items', () => {
      assert.deepEqual(
        getVolumeIndices([1, 2, 1, 2], [0, 0, 1, 1], 2),
        [0, 1, 0, 1]);
    });

    test('scrambled items', () => {
      assert.deepEqual(
        getVolumeIndices([2, 1, 1, 2], [1, 0, 1, 0], 2),
        [1, 0, 0, 1]);
    });

    test('sorts values as numbers', () => {
      assert.deepEqual(
        getVolumeIndices([1000, 50, 0], [0, 0, 0], 1),
        [2, 1, 0]);
    });

    test('accepts fractional values', () => {
      assert.deepEqual(
        getVolumeIndices([0.5, 1.5, 0.5, 1.5], [0, 0, 1, 1], 2),
        [0, 1, 0, 1]);
    });

    test('undefined for invalid groupings', () => {
      // length mismatch
      assert.isUndefined(getVolumeIndices([1, 2], [0, 0, 1], 2));
      // missing value
      assert.isUndefined(
        getVolumeIndices([1, undefined, 2, 2], [0, 1, 0, 1], 2));
      // non number value
      assert.isUndefined(
        getVolumeIndices(['1', '1', '2', '2'], [0, 1, 0, 1], 2));
      assert.isUndefined(
        getVolumeIndices([1, NaN, 2, 2], [0, 1, 0, 1], 2));
      // single value
      assert.isUndefined(
        getVolumeIndices([1, 1, 1, 1], [0, 1, 0, 1], 2));
      // volumes x slices !== items
      assert.isUndefined(
        getVolumeIndices([1, 1, 2, 3], [0, 1, 0, 1], 2));
      // duplicate (slice, volume) pair
      assert.isUndefined(
        getVolumeIndices([1, 1, 2, 2], [0, 0, 1, 1], 2));
    });

  });

  describe('getVolumeId', () => {

    const mrSopClass = makeDataElement('UI', ['1.2.840.10008.5.1.4.1.1.4']);

    test('returns the volume id of the pre load candidates', () => {
      const cases = [
        {
          name: 'TemporalPositionIdentifier',
          elements: {
            [TagKeys.TemporalPositionIdentifier]: makeDataElement('IS', ['3'])
          },
          id: 3,
          info: {
            source: 'TemporalPositionIdentifier',
            tagKey: TagKeys.TemporalPositionIdentifier
          }
        },
        {
          name: 'TemporalPositionIndex',
          elements: makeMultiFrameElements(2),
          id: 2,
          info: {
            source: 'TemporalPositionIndex',
            tagKey: TagKeys.TemporalPositionIndex
          }
        },
        {
          name: 'standard b-value',
          elements: {
            [TagKeys.SOPClassUID]: mrSopClass,
            [TagKeys.DiffusionBValue]: makeDataElement('FD', [800.5])
          },
          id: 800.5,
          info: {
            source: 'DiffusionBValue',
            tagKey: TagKeys.DiffusionBValue,
            unit: 'unit.smm2'
          }
        },
        {
          name: 'Siemens b-value',
          elements: {
            [TagKeys.SOPClassUID]: mrSopClass,
            [TagKeys.Manufacturer]: makeDataElement('LO', ['SIEMENS']),
            [TagKeys.SiemensBValue]: makeDataElement('IS', ['1000'])
          },
          id: 1000,
          info: {
            source: 'DiffusionBValue',
            tagKey: TagKeys.SiemensBValue,
            unit: 'unit.smm2'
          }
        },
        {
          name: 'GE b-value',
          elements: {
            [TagKeys.SOPClassUID]: mrSopClass,
            [TagKeys.Manufacturer]:
              makeDataElement('LO', ['GE MEDICAL SYSTEMS']),
            [TagKeys.GEBValue]: makeDataElement('IS', ['500'])
          },
          id: 500,
          info: {
            source: 'DiffusionBValue',
            tagKey: TagKeys.GEBValue,
            unit: 'unit.smm2'
          }
        },
        {
          name: 'Hitachi b-value',
          elements: {
            [TagKeys.SOPClassUID]: mrSopClass,
            [TagKeys.Manufacturer]: makeDataElement(
              'LO', ['Hitachi Medical Corporation']),
            [TagKeys.HitachiBValue]: makeDataElement('DS', ['1000'])
          },
          id: 1000,
          info: {
            source: 'DiffusionBValue',
            tagKey: TagKeys.HitachiBValue,
            unit: 'unit.smm2'
          }
        },
        {
          name: 'standard b-value after invalid private one',
          elements: {
            [TagKeys.SOPClassUID]: mrSopClass,
            [TagKeys.Manufacturer]: makeDataElement('LO', ['SIEMENS']),
            [TagKeys.SiemensBValue]: makeDataElement(
              'UN', new Uint8Array([0x00, 0x00])),
            [TagKeys.DiffusionBValue]: makeDataElement('FD', [800])
          },
          id: 800,
          info: {
            source: 'DiffusionBValue',
            tagKey: TagKeys.DiffusionBValue,
            unit: 'unit.smm2'
          }
        },
        {
          name: 'enhanced MR b-value',
          elements: makeEnhancedMRElements([1000, 1000]),
          id: 1000,
          info: {
            source: 'DiffusionBValue',
            tagKey: TagKeys.DiffusionBValue,
            unit: 'unit.smm2'
          }
        }
      ];
      for (const testCase of cases) {
        assert.deepEqual(getVolumeId(testCase.elements), {
          id: {...testCase.info, value: testCase.id}
        }, testCase.name);
      }
    });

    test('returns undefined with no usable tag', () => {
      assert.isUndefined(getVolumeId({}));
      // EchoTime is not a pre load candidate
      assert.isUndefined(getVolumeId({
        [TagKeys.EchoTime]: makeDataElement('DS', ['90'])
      }));
    });

    test('uses custom candidates volume id', () => {
      custom.volumeIdCandidates = [{
        name: 'custom',
        getter: () => ({value: 90, tagKey: 'key', source: 'other'}),
        preLoad: true
      }];
      try {
        // the candidate name is used as id source
        assert.deepEqual(getVolumeId({}),
          {id: {value: 90, tagKey: 'key', source: 'custom'}});
      } finally {
        custom.volumeIdCandidates = undefined;
      }
    });

    test('ignores custom candidates without number id', () => {
      for (const res of [{value: 'abc'}, 90, {}]) {
        custom.volumeIdCandidates = [{
          name: 'custom',
          getter: () => res,
          preLoad: true
        }];
        try {
          assert.isUndefined(getVolumeId({}), JSON.stringify(res));
        } finally {
          custom.volumeIdCandidates = undefined;
        }
      }
    });

  });

  describe('getVolumeValues', () => {

    /**
     * Get the volume ids of a guess, one per volume in volume order.
     *
     * @param {object} guess The guessVolumeIndices result.
     * @returns {object[]} The volume ids.
     */
    function getGuessVolumeIds(guess) {
      const res = [];
      for (let i = 0; i < guess.volumeIndices.length; ++i) {
        res[guess.volumeIndices[i]] = guess.volumeIds[i];
      }
      return res;
    }

    /**
     * Get the volume values of 2 slices times 2 volumes.
     *
     * @param {Array<Record<string, DataElement>>} elementsList The DICOM
     *   tags of each item.
     * @returns {object[]|undefined} The volume values.
     */
    function getValues(elementsList) {
      const guess = guessVolumeIndices(elementsList, [0, 1, 0, 1], 2);
      assert.deepEqual(guess.volumeIndices, [0, 0, 1, 1]);
      // no associated values before load is complete
      assert.isTrue(guess.volumeIds.every(
        volumeId => typeof volumeId.value === 'undefined'));
      return getVolumeValues(getGuessVolumeIds(guess), elementsList);
    }

    /**
     * Get the DICOM tags of 2 slices times 2 volumes with temporal
     * position identifiers and acquisition times.
     *
     * @param {string[]} acqTimes The acquisition time of each item.
     * @param {string[]} [contentTimes] The content time of each item.
     * @returns {Array<Record<string, DataElement>>} The DICOM tags.
     */
    function getElementsList(acqTimes, contentTimes) {
      const ids = ['1', '1', '2', '2'];
      return ids.map((id, i) => {
        const res = {
          [TagKeys.TemporalPositionIdentifier]: makeDataElement('IS', [id]),
          [TagKeys.AcquisitionTime]: makeDataElement('TM', [acqTimes[i]])
        };
        if (typeof contentTimes !== 'undefined') {
          res[TagKeys.ContentTime] = makeDataElement('TM', [contentTimes[i]]);
        }
        return res;
      });
    }

    test('relative candidate: id relative to the first one', () => {
      // 2 slices, 2 volumes acquired across midnight
      const elementsList = [];
      const dateTimes = [['20260101', '235930'], ['20260102', '000030']];
      for (const [date, time] of dateTimes) {
        for (let i = 0; i < 2; ++i) {
          elementsList.push({
            [TagKeys.AcquisitionDate]: makeDataElement('DA', [date]),
            [TagKeys.AcquisitionTime]: makeDataElement('TM', [time])
          });
        }
      }
      const guess = guessVolumeIndices(elementsList, [0, 1, 0, 1], 2);
      // the ids are not relative
      const id0 = Date.UTC(2026, 0, 1) / 1000 + 23 * 3600 + 59 * 60 + 30;
      const info = {
        source: 'AcquisitionTime',
        tagKey: TagKeys.AcquisitionTime,
        unit: 'unit.s'
      };
      assert.deepEqual(guess.volumeIds[2], {id: {...info, value: id0 + 60}});
      assert.equal(guess.getter(elementsList[0]), id0);
      assert.deepEqual(
        getVolumeValues(getGuessVolumeIds(guess), elementsList),
        [{...info, value: 0}, {...info, value: 60}]);
    });

    test('guesses the associated value of indices', () => {
      // acquisition time varies per slice: volume start times
      const info = {
        source: 'AcquisitionTime',
        tagKey: TagKeys.AcquisitionTime,
        unit: 'unit.s'
      };
      assert.deepEqual(
        getValues(getElementsList(['080000', '080001', '080010', '080011'])),
        [{...info, value: 0}, {...info, value: 10}]);
    });

    test('rejects overlapping or unordered values', () => {
      const cases = [
        // overlapping spans
        ['080000', '080010', '080005', '080015'],
        // reverse order
        ['080010', '080011', '080000', '080001'],
        // same time
        ['080000', '080000', '080000', '080000']
      ];
      for (const acqTimes of cases) {
        assert.isUndefined(
          getValues(getElementsList(acqTimes)), acqTimes.join(','));
      }
    });

    test('falls back to the next candidate', () => {
      const values = getValues(getElementsList(
        ['080000', '080000', '080000', '080000'],
        ['090000', '090000', '090100', '090100']));
      assert.deepEqual(values.map(value => [value.source, value.value]),
        [['ContentTime', 0], ['ContentTime', 60]]);
    });

    test('uses the temporal position time offset of frames', () => {
      // enhanced MR frames: temporal position index and time offset
      const groups = [[1, 0], [1, 0], [2, 2.5], [2, 2.5]].map(
        ([index, offset]) => ({
          [TagKeys.FrameContentSequence]: makeDataElement('SQ', [{
            [TagKeys.TemporalPositionIndex]: makeDataElement('US', [index])
          }]),
          [TagKeys.TemporalPositionSequence]: makeDataElement('SQ', [{
            [TagKeys.TemporalPositionTimeOffset]:
              makeDataElement('FD', [offset])
          }])
        }));
      const elements = {
        [TagKeys.PerFrameFunctionalGroupsSequence]:
          makeDataElement('SQ', groups)
      };
      const values = getValues(
        groups.map((_group, i) => getFrameElements(elements, i)));
      assert.deepEqual(values, [0, 2.5].map(value => ({
        value,
        tagKey: TagKeys.TemporalPositionTimeOffset,
        unit: 'unit.s',
        source: 'TemporalPositionTimeOffset'
      })));
    });

    test('undefined for values and unknown sources', () => {
      // EchoTime ids: no associated value
      const elementsList = ['10', '10', '20', '20'].map((echoTime, i) => ({
        [TagKeys.EchoTime]: makeDataElement('DS', [echoTime]),
        [TagKeys.AcquisitionTime]:
          makeDataElement('TM', [['080000', '080001', '080010', '080011'][i]])
      }));
      assert.isUndefined(getValues(elementsList), 'values');
      assert.isUndefined(getVolumeValues(
        [{id: {value: 1, source: 'unknown'}}], elementsList), 'unknown');
    });

  });

  describe('guessVolumeIndices on frames', () => {

    const enhancedMRElements = {
      [TagKeys.SOPClassUID]: makeDataElement(
        'UI', ['1.2.840.10008.5.1.4.1.1.4.1'])
    };

    /**
     * Get the per frame DICOM tags of a multi-frame file.
     *
     * @param {Record<string, DataElement>} elements The DICOM tags.
     * @returns {Array<Record<string, DataElement>>} The frames DICOM tags.
     */
    function getFramesElements(elements) {
      const numberOfFrames =
        elements[TagKeys.PerFrameFunctionalGroupsSequence].value.length;
      const res = [];
      for (let i = 0; i < numberOfFrames; ++i) {
        res.push(getFrameElements(elements, i));
      }
      return res;
    }

    test('uses varying TemporalPositionIndex first', () => {
      const elements = makePerFrameElements({
        temporalPositions: [2, 2, 1, 1],
        bValues: [0, 1000, 0, 1000]
      }, enhancedMRElements);
      const res = guessVolumeIndices(
        getFramesElements(elements), [0, 1, 0, 1], 2);
      assert.deepEqual(res.volumeIndices, [1, 1, 0, 0]);
      assert.deepEqual(
        res.volumeIds.map(volumeId => volumeId.id.value), [2, 2, 1, 1]);
      assert.deepEqual(res.volumeIds[0], {id: {
        source: 'TemporalPositionIndex',
        value: 2,
        tagKey: TagKeys.TemporalPositionIndex
      }});
      assert.equal(res.getter(getFramesElements(elements)[2]), 1);
    });

    test('falls back to b-value with constant TemporalPositionIndex', () => {
      const elements = makePerFrameElements({
        temporalPositions: [1, 1, 1, 1],
        bValues: [1000, 1000, 50, 50]
      }, enhancedMRElements);
      const res = guessVolumeIndices(
        getFramesElements(elements), [0, 1, 0, 1], 2);
      assert.deepEqual(res.volumeIndices, [1, 1, 0, 0]);
      assert.deepEqual(
        res.volumeIds.map(volumeId => volumeId.id.value),
        [1000, 1000, 50, 50]);
      assert.deepEqual(res.volumeIds[0], {id: {
        source: 'DiffusionBValue',
        value: 1000,
        tagKey: TagKeys.DiffusionBValue,
        unit: 'unit.smm2'
      }});
    });

    test('uses Philips dimension index b-value', () => {
      const dimensionIndexValues = [
        [1, 1, 1, 1], [1, 2, 1, 1], [1, 1, 2, 1], [1, 2, 2, 1]
      ];
      const philipsElements = {
        ...enhancedMRElements,
        [TagKeys.Manufacturer]:
          makeDataElement('LO', ['Philips Medical Systems']),
        [TagKeys.DimensionIndexSequence]: makeDataElement('SQ', [{
          [TagKeys.DimensionIndexPointer]:
            makeDataElement('AT', ['(0018,9087)'])
        }])
      };
      const elements = makePerFrameElements(
        {dimensionIndexValues}, philipsElements);
      const res = guessVolumeIndices(
        getFramesElements(elements), [0, 1, 0, 1], 2);
      assert.deepEqual(res.volumeIndices, [0, 0, 1, 1]);
      // dimension index: no b-value unit
      assert.deepEqual(res.volumeIds[0], {id: {
        source: 'DiffusionBValue',
        value: 1,
        tagKey: TagKeys.DimensionIndexValues
      }});

      // not without the Philips manufacturer
      const otherElements = makePerFrameElements({dimensionIndexValues}, {
        ...philipsElements,
        [TagKeys.Manufacturer]: makeDataElement('LO', ['SIEMENS'])
      });
      assert.isUndefined(guessVolumeIndices(
        getFramesElements(otherElements), [0, 1, 0, 1], 2));

      // not without the b-value pointer
      const noPointerElements = makePerFrameElements({dimensionIndexValues}, {
        ...enhancedMRElements,
        [TagKeys.Manufacturer]: philipsElements[TagKeys.Manufacturer]
      });
      assert.isUndefined(guessVolumeIndices(
        getFramesElements(noPointerElements), [0, 1, 0, 1], 2));
    });

    test('undefined without a valid candidate', () => {
      const elements = makePerFrameElements({
        temporalPositions: [1, 1, 1, 1]
      }, enhancedMRElements);
      assert.isUndefined(guessVolumeIndices(
        getFramesElements(elements), [0, 1, 0, 1], 2));
    });

    test('uses custom candidates', () => {
      const elements = makePerFrameElements({
        temporalPositions: [2, 2, 1, 1]
      });
      const framesElements = getFramesElements(elements);
      const values = [5, 6, 5, 6];
      const getter = frameElements => ({
        value: values[framesElements.indexOf(frameElements)]
      });
      custom.volumeIdCandidates = [{name: 'Custom', getter}];
      try {
        const res = guessVolumeIndices(framesElements, [0, 0, 1, 1], 2);
        assert.deepEqual(res.volumeIndices, [0, 1, 0, 1]);
        assert.equal(res.getter(framesElements[1]), 6);
      } finally {
        custom.volumeIdCandidates = undefined;
      }
    });

    test('uses custom candidates only', () => {
      const elements = makePerFrameElements({
        temporalPositions: [2, 2, 1, 1]
      });
      custom.volumeIdCandidates = [
        {name: 'Custom', getter: () => ({value: 1})}
      ];
      try {
        assert.isUndefined(guessVolumeIndices(
          getFramesElements(elements), [0, 1, 0, 1], 2));
      } finally {
        custom.volumeIdCandidates = undefined;
      }
    });

  });

  describe('deprecated custom getters', () => {

    test('getVolumeIdTagValue warns once', () => {
      const warnSpy = vi.spyOn(logger, 'warn').mockImplementation(() => {});
      custom.getVolumeIdTagValue = () => 1;
      try {
        getVolumeIdTagValue({});
        getVolumeIdTagValue({});
        assert.equal(warnSpy.mock.calls.length, 1, 'warn once');
        assert.include(
          warnSpy.mock.calls[0][0], 'custom.getVolumeIdTagValue');
        // no tag key
        assert.deepEqual(getVolumeId({}), {id: {source: 'custom', value: 1}});
      } finally {
        custom.getVolumeIdTagValue = undefined;
        warnSpy.mockRestore();
      }
    });

    test('getPostLoadVolumeIdTagValue warns once', () => {
      const warnSpy = vi.spyOn(logger, 'warn').mockImplementation(() => {});
      custom.getPostLoadVolumeIdTagValue = () => 1;
      try {
        guessVolumeIndices([{}, {}], [0, 1], 2);
        guessVolumeIndices([{}, {}], [0, 1], 2);
        assert.equal(warnSpy.mock.calls.length, 1, 'warn once');
        assert.include(
          warnSpy.mock.calls[0][0], 'custom.getPostLoadVolumeIdTagValue');
      } finally {
        custom.getPostLoadVolumeIdTagValue = undefined;
        warnSpy.mockRestore();
      }
    });

  });

});