DWVv0.37.0
src/dicom/dicomVolume.jsjavascript
import {custom} from '../app/custom.js';
import {
  safeGet,
  safeGetAll
} from '../dicom/dataElement.js';
import {
  NormalisedManufacturers,
  getNormalisedManufacturer
} from './dicomManufacturer.js';
import {cleanString} from './dicomParser.js';
import {getDateObj, getTimeInSeconds} from './dicomDate.js';
import {getConstantPerFrameValue} from './dicomFunctionalGroup.js';
import {logger} from '../utils/logger.js';

/**
 * @import {DataElement} from '../dicom/dataElement.js';
 * @import {
 *   PrivateBValueRule,
 *   VolumeIdCandidate
 * } from './types.js';
 * @import {SourcedNumberValue} from '../math/types.js';
 * @import {VolumeId} from '../image/types.js';
 */

/**
 * Related DICOM tag keys.
 */
const TagKeys = {
  SOPClassUID: '00080016',
  SOPInstanceUID: '00080018',
  Manufacturer: '00080070',
  AcquisitionDate: '00080022',
  AcquisitionTime: '00080032',
  ContentDate: '00080023',
  ContentTime: '00080033',
  DimensionIndexSequence: '00209222',
  DimensionIndexPointer: '00209165',
  SharedFunctionalGroupsSequence: '52009229',
  MRDiffusionSequence: '00189117',
  DiffusionBValue: '00189087',
  DiffusionBValueAT: '(0018,9087)',
  FrameContentSequence: '00209111',
  DimensionIndexValues: '00209157',
  TemporalPositionIdentifier: '00200100',
  TemporalPositionIndex: '00209128',
  TemporalPositionSequence: '00209310',
  TemporalPositionTimeOffset: '0020930D',
  EchoTime: '00180081',
  TriggerTime: '00181060',
  InversionTime: '00180082'
};

/**
 * Related SOP class UIDs.
 */
const SOPClassUIDs = {
  MR: '1.2.840.10008.5.1.4.1.1.4',
  EnhancedMR: '1.2.840.10008.5.1.4.1.1.4.1',
  EnhancedMRColorImage: '1.2.840.10008.5.1.4.1.1.4.3',
  LegacyConvertedEnhancedMRImageStorage: '1.2.840.10008.5.1.4.1.1.4.4'
};

/**
 * Default private b-value tag rules. Tested in order.
 * Rules are either `{manufacturer, key}` or `{uidPrefix, key}`.
 * Can be used to extend `custom.privateBValueRules`.
 *
 * @type {PrivateBValueRule[]}
 */
export const defaultPrivateBValueRules = [
  {
    manufacturer: NormalisedManufacturers.SIEMENS,
    key: '0019100C'
  },
  {
    manufacturer: NormalisedManufacturers.GE,
    key: '00431039'
  },
  {
    manufacturer: NormalisedManufacturers.HITACHI,
    key: '00291030'
  }
];

/**
 * Ordered list of candidate volume id getters. Since the tag that
 * actually discriminates volumes is not known until the full data
 * is loaded, `guessVolumeIndices` tries these in order and keeps the
 * first one that produces a valid, consistent per-volume grouping.
 * It is used for the files of a series (see `DicomSliceDataList`)
 * and for the frames of a multi-frame file (see
 * `getSortedFramesGeometry`).
 * Most explicit/reliable discriminators come first, AcquisitionTime
 * (the historical default) comes last.
 * Candidates flagged with `preLoad` are also used while loading
 * (see `getVolumeIdTagValue`): they must not vary between the
 * slices of a single volume.
 * Candidates either read an index (an id without unit, for example
 * TemporalPositionIdentifier) or a value (for example EchoTime).
 * The associated value of indices is guessed once all data is loaded
 * (see `getVolumeValues`), values have none.
 *
 * @type {VolumeIdCandidate[]}
 */
export const defaultVolumeIdCandidates = [
  {
    name: 'TemporalPositionIdentifier',
    getter: makeNumericTagGetter(
      TagKeys.TemporalPositionIdentifier, value => parseInt(value, 10)),
    preLoad: true
  },
  {
    name: 'TemporalPositionIndex',
    getter: getTemporalPositionIndex,
    preLoad: true
  },
  {
    name: 'DiffusionBValue',
    getter: getMRVolumeId,
    preLoad: true
  },
  {
    name: 'EchoTime',
    getter: makeNumericTagGetter(TagKeys.EchoTime, parseFloat, 'unit.ms')
  },
  {
    name: 'TriggerTime',
    getter: makeNumericTagGetter(TagKeys.TriggerTime, parseFloat, 'unit.ms')
  },
  {
    name: 'InversionTime',
    getter: makeNumericTagGetter(
      TagKeys.InversionTime, parseFloat, 'unit.ms')
  },
  {
    // seconds since the first acquisition
    name: 'AcquisitionTime',
    getter: getAcquisitionTime,
    relative: true
  }
];

/**
 * Ordered list of candidate volume associated value getters, used for
 * volume ids that are indices (without unit, for example
 * TemporalPositionIdentifier) once all data is loaded: the first one
 * that gives each volume a time span, the spans not overlapping and
 * following the volume ids order, is kept (see `guessVolumeValues`).
 * The associated value of a volume is its smallest value, relative to
 * the one of the first volume for `relative` candidates. Same shape
 * as volume id candidates (`preLoad` is not used).
 *
 * @type {VolumeIdCandidate[]}
 */
const volumeValueCandidates = [
  {
    name: 'TemporalPositionTimeOffset',
    getter: getTemporalPositionTimeOffset
  },
  {
    // seconds since the first acquisition
    name: 'AcquisitionTime',
    getter: getAcquisitionTime,
    relative: true
  },
  {
    // seconds since the first content
    name: 'ContentTime',
    getter: getContentTime,
    relative: true
  }
];

/**
 * Create a sourced number value.
 *
 * @param {number|undefined} value The value.
 * @param {string} tagKey The key of the tag the value is read from.
 * @param {string} [unit] The value unit as an i18n key.
 * @returns {SourcedNumberValue|undefined} The sourced value, undefined
 *   if the value is undefined.
 */
function createSourcedValue(value, tagKey, unit) {
  if (typeof value === 'undefined') {
    return undefined;
  }
  /** @type {SourcedNumberValue} */
  const res = {value, tagKey};
  if (typeof unit !== 'undefined') {
    res.unit = unit;
  }
  return res;
}

/**
 * Get the diffusion b-value from a functional DICOM sequence.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {string|undefined} The value, if present.
 */
function getDiffusionBValueFromFunctionalSeq(elements) {
  let res;
  const diffSeq = safeGetAll(elements, TagKeys.MRDiffusionSequence);
  if (typeof diffSeq !== 'undefined') {
    // should only contain one item
    res = safeGet(diffSeq[0], TagKeys.DiffusionBValue);
  }
  return res;
}

/**
 * Get the diffusion b-value from standard DICOM tag.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {string|undefined} The value, if present.
 */
function getStandardDiffusionBValueFromEMR(elements) {
  let res;
  // from Shared Functional Groups Sequence
  const sharedGroupSeq =
    safeGetAll(elements, TagKeys.SharedFunctionalGroupsSequence);
  if (typeof sharedGroupSeq !== 'undefined') {
    // should only contain one item
    res = getDiffusionBValueFromFunctionalSeq(sharedGroupSeq[0]);
  }
  // from Per Frame Functional Groups Sequence
  if (typeof res === 'undefined') {
    res = getConstantPerFrameValue(
      elements, getDiffusionBValueFromFunctionalSeq, 'DiffusionBValue');
  }
  return res;
}

/**
 * Get the first value of a private tag. Private tags read from
 * implicit VR data are not in the dictionary and are parsed as 'UN',
 * their value is then the raw bytes: decode them as an ASCII string.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @param {string} key The tag key.
 * @returns {string|undefined} The value, if present.
 */
function getPrivateTagValue(elements, key) {
  const element = elements[key];
  if (typeof element !== 'undefined' &&
    element.vr === 'UN' &&
    typeof element.value !== 'undefined') {
    const str = cleanString(String.fromCharCode(...element.value));
    // first of multiple values
    return str.length !== 0 ? str.split('\\')[0] : undefined;
  }
  return safeGet(elements, key);
}

/**
 * Get the diffusion b-value from MR from non standard
 *   and/or private DICOM tags.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {{value: string, key: string}|undefined} The value and
 *   the key of the tag it was read from, if present.
 */
function getNonStandardDiffusionBValueFromMR(elements) {
  let res;

  // manufacturers private tag
  const manufacturer = getNormalisedManufacturer(elements);
  const sopInstanceUID = safeGet(elements, TagKeys.SOPInstanceUID);

  let rules;
  if (typeof custom.privateBValueRules !== 'undefined') {
    rules = custom.privateBValueRules;
  } else {
    rules = defaultPrivateBValueRules;
  }

  for (const rule of rules) {
    let value;
    if (typeof rule.uidPrefix !== 'undefined' &&
      typeof sopInstanceUID !== 'undefined' &&
      sopInstanceUID.startsWith(rule.uidPrefix)) {
      value = getPrivateTagValue(elements, rule.key);
    } else if (typeof rule.manufacturer !== 'undefined' &&
      typeof manufacturer !== 'undefined' &&
      rule.manufacturer === manufacturer) {
      value = getPrivateTagValue(elements, rule.key);
    }
    // keep first valid result
    if (typeof value !== 'undefined' &&
      !isNaN(parseFloat(value))) {
      res = {value, key: rule.key};
      break;
    }
  }

  // b-value at root level
  if (typeof res === 'undefined') {
    const value = safeGet(elements, TagKeys.DiffusionBValue);
    if (typeof value !== 'undefined') {
      res = {value, key: TagKeys.DiffusionBValue};
    }
  }

  return res;
}

/**
 * Check if the dimension index sequence has a pointer to the b-value.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {boolean} True if a b-value pointer is present.
 */
function hasBValueDimensionPointer(elements) {
  const indexSeq = safeGetAll(elements, TagKeys.DimensionIndexSequence);
  return typeof indexSeq !== 'undefined' &&
    indexSeq.some(dimIndex =>
      safeGet(dimIndex, TagKeys.DimensionIndexPointer) ===
      TagKeys.DiffusionBValueAT);
}

/**
 * Get the b-value dimension index value of a frame.
 * Hard coded logic based on real cases...
 *
 * @param {Record<string, DataElement>} group The per frame
 *   functional group.
 * @returns {number|undefined} The value, if present.
 */
function getPhilipsFrameBValueIndex(group) {
  let res;
  const frameContentSeq = safeGetAll(group, TagKeys.FrameContentSequence);
  if (typeof frameContentSeq !== 'undefined') {
    // should be only one
    const dimValues =
      safeGetAll(frameContentSeq[0], TagKeys.DimensionIndexValues);
    if (typeof dimValues !== 'undefined' &&
      dimValues.length === 4) {
      // does not follow order set in DimensionIndexSequence...
      res = parseNumber(dimValues[2], parseFloat);
    }
  }
  return res;
}

/**
 * Get the b-value from the frame content sequence if
 * the dimension index sequence has a pointer to the b-value.
 * Note: the value is a dimension index, not the b-value itself.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {number|undefined} The value, if present.
 */
function getPhilipsDiffusionBValueFromEMR(elements) {
  let res;
  if (hasBValueDimensionPointer(elements)) {
    res = getConstantPerFrameValue(
      elements, getPhilipsFrameBValueIndex, 'DimensionIndexValues b-value');
  }
  return res;
}

/**
 * Get the diffusion b-value from Enhanced MR from non standard
 *   and/or private DICOM tags.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {number|undefined} The value, if present.
 */
function getNonStandardDiffusionBValueFromEMR(elements) {
  let res;

  // philips can use frame content
  if (getNormalisedManufacturer(elements) ===
    NormalisedManufacturers.PHILIPS) {
    res = getPhilipsDiffusionBValueFromEMR(elements);
  }

  return res;
}

/**
 * Parse a tag value to a number.
 *
 * @param {any} value The value to parse.
 * @param {Function} parse The string to number parser to use.
 * @returns {number|undefined} The number, or undefined if the value
 *   is absent or not a number.
 */
function parseNumber(value, parse) {
  let res;
  if (typeof value !== 'undefined') {
    const number = parse(value);
    if (!isNaN(number)) {
      res = number;
    }
  }
  return res;
}

/**
 * Get the diffusion b-value as a volume id: with the key of the tag
 * it was read from and its unit (no unit if the value is not
 * a b-value, for example a dimension index).
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {SourcedNumberValue|undefined} The volume id, if present.
 */
function getDiffusionBValueVolumeId(elements) {
  let res;
  // SOP class UID
  const sopClassUID = safeGet(elements, TagKeys.SOPClassUID);

  const bValueUnit = 'unit.smm2';
  if (sopClassUID === SOPClassUIDs.EnhancedMR ||
    sopClassUID === SOPClassUIDs.EnhancedMRColorImage ||
    sopClassUID === SOPClassUIDs.LegacyConvertedEnhancedMRImageStorage
  ) {
    // standard tag
    const value = getStandardDiffusionBValueFromEMR(elements);
    if (typeof value !== 'undefined') {
      res = {value, tagKey: TagKeys.DiffusionBValue};
    } else {
      // if not found, check non standard tag
      // (a dimension index, not a b-value)
      const index = getNonStandardDiffusionBValueFromEMR(elements);
      if (typeof index !== 'undefined') {
        logger.debug('Got b-value for enhanced MR from non standard tag');
        res = {value: index, tagKey: TagKeys.DimensionIndexValues};
      }
    }
  } else if (sopClassUID === SOPClassUIDs.MR) {
    // non standard for MR
    const nonStandard = getNonStandardDiffusionBValueFromMR(elements);
    if (typeof nonStandard !== 'undefined') {
      res = {value: nonStandard.value, tagKey: nonStandard.key};
    } else {
      // if not found, check standard EMR tag
      const value = getStandardDiffusionBValueFromEMR(elements);
      if (typeof value !== 'undefined') {
        res = {value, tagKey: TagKeys.DiffusionBValue};
      }
    }
  }

  if (typeof res === 'undefined') {
    return undefined;
  }
  // cast to number (FD/DS b-values can be fractional)
  const value = parseNumber(res.value, parseFloat);
  const unit = res.tagKey !== TagKeys.DimensionIndexValues
    ? bValueUnit : undefined;
  return createSourcedValue(value, res.tagKey, unit);
}

/**
 * Get the volume id for MR images (can be time, b-value...).
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {SourcedNumberValue|undefined} The volume id, if present.
 */
function getMRVolumeId(elements) {
  let res;

  // filter by SOP class UID
  const sopClassUID = safeGet(elements, TagKeys.SOPClassUID);
  if (sopClassUID === SOPClassUIDs.MR ||
    sopClassUID === SOPClassUIDs.EnhancedMR ||
    sopClassUID === SOPClassUIDs.EnhancedMRColorImage ||
    sopClassUID === SOPClassUIDs.LegacyConvertedEnhancedMRImageStorage
  ) {
    // diffusion b-value
    res = getDiffusionBValueVolumeId(elements);
  }

  return res;
}

/**
 * Get the temporal position index of a frame.
 *
 * @param {Record<string, DataElement>} group The per frame
 *   functional group.
 * @returns {number|undefined} The value, if present.
 */
function getFrameTemporalPositionIndex(group) {
  let res;
  const frameContentSeq = safeGetAll(group, TagKeys.FrameContentSequence);
  if (typeof frameContentSeq !== 'undefined') {
    // should be only one
    res = parseNumber(
      safeGet(frameContentSeq[0], TagKeys.TemporalPositionIndex),
      value => parseInt(value, 10));
  }
  return res;
}

/**
 * Get the temporal position index for enhanced multi-frame images.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {SourcedNumberValue|undefined} The volume id, if present.
 */
function getTemporalPositionIndex(elements) {
  return createSourcedValue(
    getConstantPerFrameValue(
      elements, getFrameTemporalPositionIndex, 'TemporalPositionIndex'),
    TagKeys.TemporalPositionIndex);
}

/**
 * Get the temporal position time offset of a frame.
 *
 * @param {Record<string, DataElement>} group The per frame
 *   functional group.
 * @returns {number|undefined} The value, if present.
 */
function getFrameTemporalPositionTimeOffset(group) {
  let res;
  const temporalSeq = safeGetAll(group, TagKeys.TemporalPositionSequence);
  if (typeof temporalSeq !== 'undefined') {
    // should be only one
    res = parseNumber(
      safeGet(temporalSeq[0], TagKeys.TemporalPositionTimeOffset),
      parseFloat);
  }
  return res;
}

/**
 * Get the temporal position time offset (in seconds) for enhanced
 * multi-frame images.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {SourcedNumberValue|undefined} The value, if present.
 */
function getTemporalPositionTimeOffset(elements) {
  return createSourcedValue(
    getConstantPerFrameValue(
      elements, getFrameTemporalPositionTimeOffset,
      'TemporalPositionTimeOffset'),
    TagKeys.TemporalPositionTimeOffset, 'unit.s');
}

/**
 * Create a getter that reads a numeric value from a single tag.
 *
 * @param {string} key The tag key.
 * @param {Function} parse The string to number parser to use.
 * @param {string} [unit] The value unit as an i18n key.
 * @returns {Function} The getter, returns undefined if the tag is absent
 *   or not a number.
 */
function makeNumericTagGetter(key, parse, unit) {
  return function (elements) {
    return createSourcedValue(
      parseNumber(safeGet(elements, key), parse), key, unit);
  };
}

/**
 * List of already logged deprecation messages.
 *
 * @type {string[]}
 */
const loggedDeprecations = [];

/**
 * Log a deprecation warning, only once per message.
 *
 * @param {string} message The deprecation message.
 */
function warnDeprecatedOnce(message) {
  if (!loggedDeprecations.includes(message)) {
    loggedDeprecations.push(message);
    logger.warn(message);
  }
}

/**
 * Get the volume id of a candidate, its id named after the candidate.
 *
 * @param {VolumeIdCandidate} candidate The candidate.
 * @param {Record<string, DataElement>} elements The DICOM elements.
 * @returns {VolumeId|undefined} The volume id, if present with
 *   a number id.
 */
function getCandidateVolumeId(candidate, elements) {
  const id = candidate.getter(elements);
  if (typeof id?.value !== 'number') {
    return undefined;
  }
  return {id: {...id, source: candidate.name}};
}

/**
 * Get a deprecated custom volume id getter as a candidate: its
 * getter returns a number.
 *
 * @param {Function} getter The deprecated getter.
 * @returns {VolumeIdCandidate} The candidate.
 */
function getDeprecatedCandidate(getter) {
  return {
    name: 'custom',
    getter(elements) {
      const value = getter(elements);
      return typeof value !== 'undefined' ? {value} : undefined;
    }
  };
}

/**
 * Get the volume id from a list of tags, used while loading (before
 * the full data is known): the first defined volume id of the
 * candidates flagged with `preLoad` (see defaultVolumeIdCandidates).
 *
 * @param {Record<string, DataElement>} elements The DICOM elements.
 * @returns {VolumeId|undefined} The volume id if available.
 */
export function getVolumeId(elements) {
  if (typeof custom.getVolumeIdTagValue !== 'undefined') {
    warnDeprecatedOnce(
      'custom.getVolumeIdTagValue: deprecated since v0.37,' +
      ' please use custom.volumeIdCandidates with a preLoad candidate.'
    );
    return getCandidateVolumeId(
      getDeprecatedCandidate(custom.getVolumeIdTagValue), elements);
  }
  for (const candidate of getVolumeIdCandidates()) {
    if (candidate.preLoad === true) {
      const volumeId = getCandidateVolumeId(candidate, elements);
      if (typeof volumeId !== 'undefined') {
        return volumeId;
      }
    }
  }
  return undefined;
}

/**
 * Get the volume id number from a list of tags, used while loading
 * (see getVolumeId).
 *
 * @param {Record<string, DataElement>} elements The DICOM elements.
 * @returns {number|undefined} The id if available.
 */
export function getVolumeIdTagValue(elements) {
  return getVolumeId(elements)?.id.value;
}

/**
 * Get a time as a number of seconds. If the date is available, it is
 * included so that times spanning midnight are correctly ordered.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @param {string} dateKey The date tag key.
 * @param {string} timeKey The time tag key.
 * @returns {SourcedNumberValue|undefined} The time, if present.
 */
function getDateTimeInSeconds(elements, dateKey, timeKey) {
  if (typeof safeGet(elements, timeKey) === 'undefined') {
    return undefined;
  }
  let res = getTimeInSeconds(elements[timeKey]);
  if (typeof res !== 'undefined' &&
    typeof safeGet(elements, dateKey) !== 'undefined') {
    const date = getDateObj(elements[dateKey]);
    const dateMs = Date.UTC(date.year, date.monthIndex, date.day);
    if (!isNaN(dateMs)) {
      res += dateMs / 1000;
    }
  }
  return createSourcedValue(res, timeKey, 'unit.s');
}

/**
 * Get the acquisition time as a number of seconds (see
 * getDateTimeInSeconds).
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {SourcedNumberValue|undefined} The time, if present.
 */
function getAcquisitionTime(elements) {
  return getDateTimeInSeconds(
    elements, TagKeys.AcquisitionDate, TagKeys.AcquisitionTime);
}

/**
 * Get the content time as a number of seconds (see
 * getDateTimeInSeconds).
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {SourcedNumberValue|undefined} The time, if present.
 */
function getContentTime(elements) {
  return getDateTimeInSeconds(
    elements, TagKeys.ContentDate, TagKeys.ContentTime);
}

/**
 * Get the list of volume id candidates: the custom one if defined,
 * the default one otherwise.
 *
 * @returns {VolumeIdCandidate[]}
 *   The candidates.
 */
function getVolumeIdCandidates() {
  return typeof custom.volumeIdCandidates !== 'undefined'
    ? custom.volumeIdCandidates
    : defaultVolumeIdCandidates;
}

/**
 * Get a volume id candidate from its name, including the deprecated
 * custom getters (named 'custom').
 *
 * @param {string} name The candidate name.
 * @returns {VolumeIdCandidate|undefined} The candidate, if found.
 */
function getVolumeIdCandidate(name) {
  const candidates = [...getVolumeIdCandidates()];
  // post load first, as in guessVolumeIndices
  for (const getter of [
    custom.getVolumeIdTagValue,
    custom.getPostLoadVolumeIdTagValue
  ]) {
    if (typeof getter !== 'undefined') {
      candidates.unshift(getDeprecatedCandidate(getter));
    }
  }
  return candidates.find(candidate => candidate.name === name);
}

/**
 * Get the volume index of each item (file or frame) from its volume
 * id. The grouping is valid if all items have a numeric id,
 * there are at least two distinct ids and each (slice, volume)
 * pair is unique with a total of slices times volumes items: every
 * volume then contains every slice.
 *
 * @param {any[]} values The volume id of each item.
 * @param {number[]} sliceIndices The slice index of each item.
 * @param {number} numberOfSlices The number of distinct slices.
 * @returns {number[]|undefined} The volume index of each item (volumes
 *   ordered by ascending id), undefined if the grouping is not valid.
 */
export function getVolumeIndices(values, sliceIndices, numberOfSlices) {
  if (values.length !== sliceIndices.length) {
    return undefined;
  }
  // distinct values
  const volValues = [];
  for (const value of values) {
    if (typeof value !== 'number' || isNaN(value)) {
      return undefined;
    }
    if (!volValues.includes(value)) {
      volValues.push(value);
    }
  }
  if (volValues.length < 2 ||
    volValues.length * numberOfSlices !== values.length) {
    return undefined;
  }
  // sort as numbers
  volValues.sort((a, b) => a - b);
  // volume index per item, check unique (slice, volume) pairs
  const res = [];
  const seen = new Set();
  for (let i = 0; i < values.length; ++i) {
    const volIndex = volValues.indexOf(values[i]);
    const key = volIndex * numberOfSlices + sliceIndices[i];
    if (seen.has(key)) {
      return undefined;
    }
    seen.add(key);
    res.push(volIndex);
  }
  return res;
}

/**
 * Get the associated value of each volume from a value candidate: the
 * smallest value of the volume (relative to the one of the first
 * volume for `relative` candidates). Each volume spans from its
 * smallest to its largest value, the spans must not overlap and
 * must follow the volume order.
 *
 * @param {VolumeIdCandidate} candidate The candidate.
 * @param {Array<Record<string, DataElement>>} elementsList The DICOM
 *   tags of each item.
 * @param {number[]} volumeIndices The volume index of each item.
 * @returns {SourcedNumberValue[]|undefined} The associated value of each
 *   volume, undefined if the candidate is not valid.
 */
function getCandidateVolumeValues(candidate, elementsList, volumeIndices) {
  const mins = [];
  const maxs = [];
  for (let i = 0; i < elementsList.length; ++i) {
    const value = candidate.getter(elementsList[i]);
    const volIndex = volumeIndices[i];
    if (typeof value?.value !== 'number' || isNaN(value.value) ||
      volIndex < 0) {
      return undefined;
    }
    if (typeof mins[volIndex] === 'undefined' ||
      value.value < mins[volIndex].value) {
      mins[volIndex] = value;
    }
    if (typeof maxs[volIndex] === 'undefined' ||
      value.value > maxs[volIndex]) {
      maxs[volIndex] = value.value;
    }
  }
  // spans must not overlap and follow the volume order
  for (let v = 0; v < mins.length; ++v) {
    if (typeof mins[v] === 'undefined' ||
      (v > 0 && maxs[v - 1] >= mins[v].value)) {
      return undefined;
    }
  }
  const offset = candidate.relative === true ? mins[0].value : 0;
  return mins.map(min => ({
    ...min,
    value: min.value - offset,
    source: candidate.name
  }));
}

/**
 * Guess the associated value of each volume: value candidates are tried
 * in order, the first valid one is kept (see volumeValueCandidates).
 *
 * @param {Array<Record<string, DataElement>>} elementsList The DICOM
 *   tags of each item.
 * @param {number[]} volumeIndices The volume index of each item.
 * @returns {SourcedNumberValue[]|undefined} The associated value of each
 *   volume, undefined if no candidate is valid.
 */
function guessVolumeValues(elementsList, volumeIndices) {
  for (const candidate of volumeValueCandidates) {
    const values =
      getCandidateVolumeValues(candidate, elementsList, volumeIndices);
    if (typeof values !== 'undefined') {
      logger.debug(`Using '${candidate.name}' as volume value`);
      return values;
    }
  }
  return undefined;
}

/**
 * Get the associated value of each volume, once all data is loaded:
 * the id relative to the first one for `relative` candidates
 * (for example AcquisitionTime), guessed for indices (ids without
 * unit, for example TemporalPositionIdentifier, see
 * volumeValueCandidates). Other ids have none.
 *
 * @param {VolumeId[]} volumeIds The volume ids, sorted by id (as
 *   returned by Geometry.getVolumeIds).
 * @param {Array<Record<string, DataElement>>} elementsList The DICOM
 *   tags of each item (file or frame).
 * @returns {SourcedNumberValue[]|undefined} The associated value of each
 *   volume, undefined if not available.
 */
export function getVolumeValues(volumeIds, elementsList) {
  const candidate = getVolumeIdCandidate(volumeIds[0].id.source);
  if (typeof candidate === 'undefined') {
    return undefined;
  }
  if (candidate.relative === true) {
    const first = volumeIds[0].id.value;
    return volumeIds.map(volumeId =>
      ({...volumeId.id, value: volumeId.id.value - first}));
  }
  if (typeof volumeIds[0].id.unit !== 'undefined') {
    return undefined;
  }
  const ids = volumeIds.map(volumeId => volumeId.id.value);
  return guessVolumeValues(
    elementsList,
    elementsList.map(elements =>
      ids.indexOf(getCandidateVolumeId(candidate, elements)?.id.value)));
}

/**
 * Guess the volume index of items (files or frames) that share slice
 * positions: volume id candidates are tried in order, the first one
 * that produces a valid grouping is kept (see getVolumeIndices).
 * If the deprecated `custom.getPostLoadVolumeIdTagValue` is defined,
 * it is used as the only candidate.
 *
 * @param {Array<Record<string, DataElement>>} elementsList The DICOM tags
 *   of each item.
 * @param {number[]} sliceIndices The slice index of each item.
 * @param {number} numberOfSlices The number of distinct slices.
 * @returns {{
 *   volumeIndices: number[],
 *   volumeIds: VolumeId[],
 *   getter: Function
 * }|undefined}
 *   The volume index and volume id of each item (without associated
 *   value, see getVolumeValues) and the volume id getter
 *   (`(elements) => number|undefined`) that produced them, undefined
 *   if no candidate produces a valid grouping.
 */
export function guessVolumeIndices(
  elementsList, sliceIndices, numberOfSlices) {
  let candidates;
  if (typeof custom.getPostLoadVolumeIdTagValue !== 'undefined') {
    warnDeprecatedOnce(
      'custom.getPostLoadVolumeIdTagValue: deprecated since v0.37,' +
      ' please use custom.volumeIdCandidates.'
    );
    candidates = [
      getDeprecatedCandidate(custom.getPostLoadVolumeIdTagValue)
    ];
  } else {
    candidates = getVolumeIdCandidates();
  }
  for (const candidate of candidates) {
    const volumeIds = elementsList.map(
      elements => getCandidateVolumeId(candidate, elements));
    const volumeIndices = getVolumeIndices(
      volumeIds.map(volumeId => volumeId?.id.value),
      sliceIndices, numberOfSlices);
    if (typeof volumeIndices !== 'undefined') {
      logger.debug(`Using '${candidate.name}' as volume id`);
      return {
        volumeIndices,
        volumeIds,
        getter: elements =>
          getCandidateVolumeId(candidate, elements)?.id.value
      };
    }
  }
  return undefined;
}