DWVv0.37.0
src/dicom/dicomFunctionalGroup.jsjavascript
import {getSpacingFromMeasure} from './dicomImage.js';
import {logger} from '../utils/logger.js';
import {arrayEquals} from '../utils/array.js';
import {
  getDicomCodeItem,
  DcmCodes,
  getDcmDicomCode
} from './dicomCode.js';
import {
  DataElement,
  safeGetAll
} from './dataElement.js';

/**
 * @import {Spacing} from '../image/spacing.js';
 * @import {SimpleTagValues} from './types.js';
 */

/**
 * Related DICOM tag keys.
 */
const TagKeys = {
  DerivationImageSequence: '00089124',
  SourceImageSequence: '00082112',
  ReferencedSOPClassUID: '00081150',
  ReferencedSOPInstanceUID: '00081155',
  FrameContentSequence: '00209111',
  DimensionIndexValue: '00209157',
  DimensionOrganizationSequence: '00209221',
  DimensionOrganizationUID: '00209164',
  DimensionIndexSequence: '00209222',
  DimensionIndexPointer: '00209165',
  DimensionDescriptionLabel: '00209421',
  SegmentIdentificationSequence: '0062000A',
  ReferencedSegmentNumber: '0062000B',
  PlanePositionSequence: '00209113',
  ImagePosition: '00200032',
  PlaneOrientationSequence: '00209116',
  ImageOrientation: '00200037',
  PixelMeasuresSequence: '00289110',
  PerFrameFunctionalGroupsSequence: '52009230'
};

/**
 * Check the dimension organization from a dicom element.
 *
 * @param {Record<string, DataElement>} dataElements The root dicom element.
 * @returns {object} The dimension organizations and indices.
 */
export function getDimensionOrganization(dataElements) {
  // Dimension Organization Sequence (required)
  const orgSq = dataElements[TagKeys.DimensionOrganizationSequence];
  if (typeof orgSq === 'undefined' || orgSq.value.length !== 1) {
    throw new Error('Unsupported dimension organization sequence length');
  }
  // Dimension Organization UID
  const orgUID = orgSq.value[0][TagKeys.DimensionOrganizationUID].value[0];

  // Dimension Index Sequence (conditionally required)
  const indices = [];
  const indexSqElem = dataElements[TagKeys.DimensionIndexSequence];
  if (typeof indexSqElem !== 'undefined') {
    const indexSq = indexSqElem.value;
    // expecting 2D index
    if (indexSq.length !== 2) {
      throw new Error('Unsupported dimension index sequence length');
    }
    let indexPointer;
    for (let i = 0; i < indexSq.length; ++i) {
      // Dimension Organization UID (required)
      const indexOrg = indexSq[i][TagKeys.DimensionOrganizationUID].value[0];
      if (indexOrg !== orgUID) {
        throw new Error(
          'Dimension Index Sequence contains a unknown Dimension Organization');
      }
      // Dimension Index Pointer (required)
      indexPointer = indexSq[i][TagKeys.DimensionIndexPointer].value[0];

      const index = {
        DimensionOrganizationUID: indexOrg,
        DimensionIndexPointer: indexPointer
      };
      // Dimension Description Label (optional)
      const descriptionLabelEl =
        indexSq[i][TagKeys.DimensionDescriptionLabel];
      if (typeof descriptionLabelEl !== 'undefined') {
        index.DimensionDescriptionLabel = descriptionLabelEl.value[0];
      }
      // store
      indices.push(index);
    }
    // expecting Image Position at last position
    if (indexPointer !== '(0020,0032)') {
      throw new Error('Unsupported non image position as last index');
    }
  }

  return {
    organizations: {
      value: [
        {
          DimensionOrganizationUID: orgUID
        }
      ]
    },
    indices: {
      value: indices
    }
  };
}

/**
 * DICOM functional group: item of a
 *  SharedFunctionalGroupsSequence (5200,9229) or
 *  PerframeFunctionalGroupsSequence (5200,9230).
 *
 * Ref: {@link https://dicom.nema.org/medical/dicom/2024a/output/chtml/part03/sect_C.7.6.16.html}.
 */
export class DicomFunctionalGroup {
  /**
   * The dimension index.
   *
   * @type {number[]}
   */
  dimIndex;
  /**
   * The frame image position patient.
   *
   * @type {number[]}
   */
  imagePosPat;
  /**
   * List of derivation images.
   *
   * @type {Array}
   */
  derivationImages;
  /**
   * The reference segment number.
   *
   * @type {number}
   */
  refSegmentNumber;

  /**
   * The frame image orientation.
   *
   * @type {number[]|undefined}
   */
  imageOrientationPatient;
  /**
   * The frame spacing.
   *
   * @type {Spacing|undefined}
   */
  spacing;

  /**
   * @param {number[]} dimIndex The dimension index.
   * @param {number[]} imagePosPat The frame image position patient.
   * @param {Array} derivationImages List of derivation images.
   * @param {number} refSegmentNumber The reference segment number.
   */
  constructor(dimIndex, imagePosPat, derivationImages, refSegmentNumber) {
    this.dimIndex = dimIndex;
    this.imagePosPat = imagePosPat;
    this.derivationImages = derivationImages;
    this.refSegmentNumber = refSegmentNumber;
  }
}

/**
 * Get a functional group object from a dicom element.
 *
 * @param {Record<string, DataElement>} dataElements The dicom element.
 * @returns {DicomFunctionalGroup|undefined} A functional group object.
 */
export function getFunctionalGroup(dataElements) {
  // Derivation Image Sequence
  const derivationImages = [];
  if (typeof dataElements[TagKeys.DerivationImageSequence] !== 'undefined') {
    const derivationImageSq =
      dataElements[TagKeys.DerivationImageSequence].value;
    // Source Image Sequence
    for (let i = 0; i < derivationImageSq.length; ++i) {
      const sourceImages = [];
      if (typeof derivationImageSq[i][TagKeys.SourceImageSequence] !==
        'undefined') {
        const sourceImageSq =
          derivationImageSq[i][TagKeys.SourceImageSequence].value;
        for (let j = 0; j < sourceImageSq.length; ++j) {
          const sourceImage = {};
          // Referenced SOP Class UID
          if (typeof sourceImageSq[j][TagKeys.ReferencedSOPClassUID] !==
            'undefined') {
            sourceImage.referencedSOPClassUID =
              sourceImageSq[j][TagKeys.ReferencedSOPClassUID].value[0];
          }
          // Referenced SOP Instance UID
          if (typeof sourceImageSq[j][TagKeys.ReferencedSOPInstanceUID] !==
            'undefined') {
            sourceImage.referencedSOPInstanceUID =
              sourceImageSq[j][TagKeys.ReferencedSOPInstanceUID].value[0];
          }
          sourceImages.push(sourceImage);
        }
      }
      derivationImages.push({
        sourceImages
      });
    }
  }
  // Frame Content Sequence (required, only one)
  if (typeof dataElements[TagKeys.FrameContentSequence] === 'undefined') {
    logger.info('Missing frame content sequence');
    return;
  }
  const frameContentSq = dataElements[TagKeys.FrameContentSequence].value;
  if (frameContentSq.length === 0) {
    logger.info('Empty frame content sequence');
    return;
  }
  // Dimension Index Value
  const dimIndex = frameContentSq[0][TagKeys.DimensionIndexValue].value;
  // Referenced Segment Number (can be undefined for non SEG)
  let refSegmentNumber;
  // Segment Identification Sequence (required for SEG, only one)
  const segmentIdSq = dataElements[TagKeys.SegmentIdentificationSequence];
  if (typeof segmentIdSq !== 'undefined') {
    const item0 = segmentIdSq.value[0];
    refSegmentNumber =
      parseInt(item0[TagKeys.ReferencedSegmentNumber].value[0], 10);
  }
  // Plane Position Sequence (required, only one)
  if (typeof dataElements[TagKeys.PlanePositionSequence] === 'undefined') {
    logger.info('Missing plane position sequence');
    return;
  }
  const planePosSq = dataElements[TagKeys.PlanePositionSequence].value;
  if (planePosSq.length === 0) {
    logger.info('Empty plane position sequence');
    return;
  }
  // Image Position (Patient) (conditionally required)
  const imagePosPat = planePosSq[0][TagKeys.ImagePosition].value;
  for (let p = 0; p < imagePosPat.length; ++p) {
    imagePosPat[p] = parseFloat(imagePosPat[p]);
  }
  const funcGroup = new DicomFunctionalGroup(
    dimIndex,
    imagePosPat,
    derivationImages,
    refSegmentNumber
  );
  // Plane Orientation Sequence
  if (typeof dataElements[TagKeys.PlaneOrientationSequence] !== 'undefined') {
    const framePlaneOrientationSeq =
      dataElements[TagKeys.PlaneOrientationSequence];
    if (framePlaneOrientationSeq.value.length !== 0) {
      // should only be one Image Orientation (Patient)
      const frameImageOrientation =
        framePlaneOrientationSeq.value[0][TagKeys.ImageOrientation].value;
      if (typeof frameImageOrientation !== 'undefined') {
        funcGroup.imageOrientationPatient = frameImageOrientation;
      }
    }
  }
  // Pixel Measures Sequence
  if (typeof dataElements[TagKeys.PixelMeasuresSequence] !== 'undefined') {
    const framePixelMeasuresSeq = dataElements[TagKeys.PixelMeasuresSequence];
    if (framePixelMeasuresSeq.value.length !== 0) {
      // should only be one
      const frameSpacing =
        getSpacingFromMeasure(framePixelMeasuresSeq.value[0]);
      if (typeof frameSpacing !== 'undefined') {
        funcGroup.spacing = frameSpacing;
      }
    } else {
      logger.warn(
        'No shared functional group pixel measure sequence items.');
    }
  }

  return funcGroup;
}

/**
 * Get the list of per frame DicomFunctionalGroup from the root list
 * of data elements.
 *
 * @param {Record<string, DataElement>} dataElements The root dicom element.
 * @param {number} [numberOfFrames] Optional number of frames to compare
 *   with per frame sequence size.
 * @returns {DicomFunctionalGroup[]|undefined} The list of frame
 *   information object.
 */
export function getPerFrameFunctionalGroups(dataElements, numberOfFrames) {
  // Per-frame Functional Groups Sequence
  const perFrameFuncGroupSequence =
    safeGetAll(dataElements, TagKeys.PerFrameFunctionalGroupsSequence);

  let funcGroups;
  if (typeof perFrameFuncGroupSequence !== 'undefined') {
    // check size
    if (typeof numberOfFrames !== 'undefined' &&
      numberOfFrames !== perFrameFuncGroupSequence.length) {
      throw new Error(
        'perFrameFuncGroupSequence meta and numberOfFrames are not equal.');
    }
    // create frame info object from per frame func
    funcGroups = [];
    for (const item of perFrameFuncGroupSequence) {
      funcGroups.push(getFunctionalGroup(item));
    }
  }

  return funcGroups;
}

/**
 * Check if two functional group objects are equal.
 *
 * @param {DicomFunctionalGroup} group1 The first frame info.
 * @param {DicomFunctionalGroup} group2 The second frame info.
 * @returns {boolean} True if both groups are equal.
 */
export function isEqualFunctionalGroup(group1, group2) {
  // basics
  if (typeof group1 === 'undefined' ||
    typeof group2 === 'undefined' ||
    group1 === null ||
    group2 === null) {
    return false;
  }
  let isEqual =
    arrayEquals(group1.dimIndex, group2.dimIndex) &&
    arrayEquals(group1.imagePosPat, group2.imagePosPat) &&
    group1.refSegmentNumber === group2.refSegmentNumber;

  isEqual = isEqual &&
    group1.derivationImages.length === group2.derivationImages.length;
  for (let i = 0; i < group1.derivationImages.length; ++i) {
    const derivationImage1 = group1.derivationImages[i];
    const derivationImage2 = group2.derivationImages[i];
    isEqual = isEqual &&
      derivationImage1.sourceImages.length ===
      derivationImage2.sourceImages.length;
    for (let j = 0; j < derivationImage1.length; ++j) {
      const sourceImage1 = derivationImage1.sourceImages[j];
      const sourceImage2 = derivationImage2.sourceImages[j];
      isEqual = isEqual &&
        sourceImage1.referencedSOPClassUID ===
        sourceImage2.referencedSOPClassUID &&
        sourceImage1.referencedSOPInstanceUID ===
        sourceImage2.referencedSOPInstanceUID;
    }
  }

  return isEqual;
}

/**
 * Get a dicom item from a functional group object.
 *
 * @param {DicomFunctionalGroup} funcGroup The functional group object.
 * @returns {SimpleTagValues} The item as a list of (key, value) pairs.
 */
export function getDicomFunctionalGroupItem(funcGroup) {
  const item = {
    FrameContentSequence: {
      value: [
        {
          DimensionIndexValues: funcGroup.dimIndex
        }
      ]
    },
    PlanePositionSequence: {
      value: [
        {
          ImagePositionPatient: funcGroup.imagePosPat
        }
      ]
    },
    SegmentIdentificationSequence: {
      value: [
        {
          ReferencedSegmentNumber: funcGroup.refSegmentNumber
        }
      ]
    }
  };
  // optional DerivationImageSequence
  if (funcGroup.derivationImages !== undefined) {
    const sourceImgPurposeOfReferenceCode =
      getDicomCodeItem(
        getDcmDicomCode(DcmCodes.SourceImageForImageProcessingOperation)
      );
    const segDerivationCode =
      getDicomCodeItem(getDcmDicomCode(DcmCodes.Segmentation));

    const derivationImageItems = [];
    for (const derivationImage of funcGroup.derivationImages) {
      const sourceImages = [];
      for (const sourceImage of derivationImage.sourceImages) {
        sourceImages.push({
          PurposeOfReferenceCodeSequence: {
            value: [sourceImgPurposeOfReferenceCode]
          },
          ReferencedSOPClassUID: sourceImage.referencedSOPClassUID,
          ReferencedSOPInstanceUID: sourceImage.referencedSOPInstanceUID
        });
      }

      derivationImageItems.push({
        DerivationCodeSequence: {
          value: [segDerivationCode]
        },
        SourceImageSequence: {
          value: sourceImages
        }
      });
    }

    item.DerivationImageSequence = {
      value: derivationImageItems
    };
  }

  return item;
}

/**
 * Get a value that is constant across the frames of a multi-frame file.
 * Frames without the value are ignored.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @param {Function} valueGetter The per frame functional group value getter.
 * @param {string} name The value name, used for logging.
 * @returns {any|undefined} The value, or undefined if absent or if it
 *   varies across frames: the file then does not represent a single
 *   volume and the value cannot be used as a volume id.
 */
export function getConstantPerFrameValue(elements, valueGetter, name) {
  let res;
  const perFrameGroupSeq =
    safeGetAll(elements, TagKeys.PerFrameFunctionalGroupsSequence);
  if (typeof perFrameGroupSeq === 'undefined') {
    return undefined;
  }
  for (const group of perFrameGroupSeq) {
    const value = valueGetter(group);
    if (typeof value !== 'undefined') {
      if (typeof res === 'undefined') {
        res = value;
      } else if (res !== value) {
        logger.debug(`Unhandled varying ${name}`);
        return undefined;
      }
    }
  }
  return res;
}

/**
 * Get the DICOM tags of one frame of a multi-frame file: the root tags
 * with a per frame functional groups sequence that only contains the
 * frame item. Getters written for the root tags (for example using
 * getConstantPerFrameValue) then return the frame value.
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @param {number} frameNumber The frame number.
 * @returns {Record<string, DataElement>} The frame DICOM tags.
 */
export function getFrameElements(elements, frameNumber) {
  const perFrameGroupSeq =
    safeGetAll(elements, TagKeys.PerFrameFunctionalGroupsSequence);
  const frameGroupSeq = new DataElement('SQ');
  frameGroupSeq.value = [perFrameGroupSeq[frameNumber]];
  return {
    ...elements,
    [TagKeys.PerFrameFunctionalGroupsSequence]: frameGroupSeq
  };
}

/**
 * Get the DICOM tags of each frame of a multi-frame file (see
 * getFrameElements).
 *
 * @param {Record<string, DataElement>} elements The DICOM tags.
 * @returns {Array<Record<string, DataElement>>} The DICOM tags of each
 *   frame, the input tags if there are no per frame functional groups.
 */
export function getFramesElements(elements) {
  const perFrameGroupSeq =
    safeGetAll(elements, TagKeys.PerFrameFunctionalGroupsSequence);
  if (typeof perFrameGroupSeq === 'undefined') {
    return [elements];
  }
  return perFrameGroupSeq.map((_group, i) => getFrameElements(elements, i));
}