DWVv0.37.0
src/dicom/dicomGeometry.jsjavascript
import {Size} from '../image/size.js';
import {Spacing} from '../image/spacing.js';
import {
  Geometry,
  getSliceGeometrySpacing,
  getComparePoint3D
} from '../image/geometry.js';
import {safeGet, safeGetAll} from './dataElement.js';
import {
  getImage2DSize,
  getPixelSpacing,
  getPixelAspectRatio,
  getOrientationMatrix,
  getSpacingFromMeasure
} from './dicomImage.js';
import {
  getVolumeId,
  guessVolumeIndices
} from './dicomVolume.js';
import {getOrientationFromCosines} from '../math/orientation.js';
import {
  Point3D,
  point3DFromArray,
  includesPoint3D,
  getEqualPoint3DFunction
} from '../math/point.js';
import {Index} from '../math/index.js';
import {
  REAL_WORLD_EPSILON,
  isAboveEpsilon
} from '../math/number.js';
import {arraySortEquals} from '../utils/array.js';
import {logger} from '../utils/logger.js';
import {
  getPerFrameFunctionalGroups,
  getFrameElements
} from './dicomFunctionalGroup.js';

/**
 * @import {DataElement} from './dataElement.js';
 * @import {DicomFunctionalGroup} from './dicomFunctionalGroup.js';
 */

/**
 * @typedef {Record<string, DataElement>} DataElements
 */

/**
 * Related DICOM tag keys.
 */
const TagKeys = {
  NumberOfFrames: '00280008',
  ImagePositionPatient: '00200032',
  SharedFunctionalGroupsSequence: '52009229',
  PlaneOrientationSequence: '00209116',
  ImageOrientationPatient: '00200037',
  PixelMeasuresSequence: '00289110'
};

/**
 * Get the image geometry from root DICOM elements.
 *
 * @param {DataElements} dataElements The DICOM data elements.
 * @returns {Geometry} The image geometry.
 */
export function getRootGeometry(dataElements) {
  const size2D = getImage2DSize(dataElements);
  const sizeValues = [size2D[0], size2D[1], 1];

  // NumberOfFrames
  const numberOfFrames = safeGet(dataElements, TagKeys.NumberOfFrames);
  if (typeof numberOfFrames !== 'undefined') {
    const number = parseInt(numberOfFrames, 10);
    if (number > 1) {
      sizeValues.push(number);
    }
  }

  // image size
  const size = new Size(sizeValues);

  // image spacing
  let spacingValues = [1, 1, 1];
  const spacing2D = getPixelSpacing(dataElements);
  if (typeof spacing2D !== 'undefined') {
    spacingValues = [spacing2D[0], spacing2D[1], 1];
  } else {
    // try pixel aspect ratio
    const ratio = getPixelAspectRatio(dataElements);
    if (typeof ratio !== 'undefined') {
      spacingValues = [ratio[0], ratio[1], 1];
      logger.warn('Use pixel aspect ratio as spacing');
    }
  }
  const spacing = new Spacing(spacingValues);

  // ImagePositionPatient
  const imagePositionPatient =
    safeGetAll(dataElements, TagKeys.ImagePositionPatient);
  // slice position
  let slicePosition = new Array(0, 0, 0);
  if (typeof imagePositionPatient !== 'undefined') {
    slicePosition = [
      parseFloat(imagePositionPatient[0]),
      parseFloat(imagePositionPatient[1]),
      parseFloat(imagePositionPatient[2])
    ];
  }

  // Image orientation patient
  const orientationMatrix = getOrientationMatrix(dataElements);

  // geometry
  const origin = new Point3D(
    slicePosition[0], slicePosition[1], slicePosition[2]);
  const volumeId = getVolumeId(dataElements);

  return new Geometry([origin], size, spacing, orientationMatrix, volumeId);
}

/**
 * Check the distance between a frame origin and a reference origin.
 *
 * @param {Point3D} frameOrigin The frame origin to check.
 * @param {Point3D} refOrigin The reference origin to check against.
 * @param {number} index The frame index, used for error message.
 * @throws {Error} If distance is too high.
 */
function checkDistance(frameOrigin, refOrigin, index) {
  const dist = frameOrigin.getDistance(refOrigin);
  // warn is bigger than epsilon, error if bigger than 100*epsilon
  if (dist > REAL_WORLD_EPSILON) {
    if (dist < REAL_WORLD_EPSILON * 100) {
      logger.warn(
        `Frame origin ${index} is far from reference origin (${dist}).`
      );
    } else {
      throw new Error(`No reference origin for frame origin ${index}`);
    }
  }
}

/**
 * Complete origins using reference origins if with gaps.
 *
 * `frameOrigins` are not assumed to be in reference (ascending) order:
 * a DICOM file's `PerFrameFunctionalGroupsSequence` frame order is not
 * guaranteed to be spatially sorted for any writer. Match each frame
 * to its closest reference origin first, then rebuild the continuous
 * run in ascending reference order, filling any true gaps
 * from `refOrigins`.
 *
 * @param {Point3D[]} frameOrigins The frame origins.
 * @param {Point3D[]} refOrigins The reference image origins.
 * @returns {Point3D[]} The continous origins, in ascending reference order.
 */
function completeOriginsFromReference(
  frameOrigins,
  refOrigins) {
  // match each frame to its closest reference index, keeping the frame's
  // own (authoritative) origin rather than the reference one
  const frameByRefIndex = new Map();
  for (let i = 0; i < frameOrigins.length; ++i) {
    const frameOrigin = frameOrigins[i];
    const refIndex = frameOrigin.getClosest(refOrigins);
    checkDistance(frameOrigin, refOrigins[refIndex], i);
    frameByRefIndex.set(refIndex, frameOrigin);
  }

  const refIndices = [...frameByRefIndex.keys()];
  const minRefIndex = Math.min(...refIndices);
  const maxRefIndex = Math.max(...refIndices);

  // result, in ascending reference order, filling gaps from refOrigins
  const resOrigins = [];
  for (let j = minRefIndex; j <= maxRefIndex; ++j) {
    resOrigins.push(
      frameByRefIndex.has(j) ? frameByRefIndex.get(j) : refOrigins[j]);
  }

  return resOrigins;
}

/**
 * Complete origins using a base geometry if with gaps.
 *
 * @param {Point3D[]} frameOrigins The frame origins.
 * @param {Geometry} baseGeometry The base geometry.
 * @returns {Point3D[]} The continous origins.
 */
function completeOriginsFromGeometry(
  frameOrigins,
  baseGeometry) {
  // result
  const resOrigins = [];

  resOrigins.push(frameOrigins[0]);
  let sliceIndex = 0;
  for (let g = 1; g < frameOrigins.length; ++g) {
    ++sliceIndex;
    let index = new Index([0, 0, sliceIndex]);
    let point = baseGeometry.indexToWorld(index).get3D();
    const frameOrigin = frameOrigins[g];
    // check if more pos pats are needed
    let dist = frameOrigin.getDistance(point);
    const distPrevious = dist;
    // TODO: good threshold?
    while (isAboveEpsilon(dist)) {
      logger.debug(`Adding intermediate pos pats at ${
        point.toString() }`);
      resOrigins.push(point);
      ++sliceIndex;
      index = new Index([0, 0, sliceIndex]);
      point = baseGeometry.indexToWorld(index).get3D();
      dist = frameOrigin.getDistance(point);
      if (dist > distPrevious) {
        throw new Error(
          'Test distance is increasing when adding intermediate pos pats');
      }
    }
    // add frame pos pat
    resOrigins.push(frameOrigin);
  }

  return resOrigins;
}

/**
 * Get the frames geometry from root DICOM elements and per-frame infos.
 *
 * @param {DataElements} dataElements The DICOM data elements.
 * @param {DicomFunctionalGroup[]} perFrameFuncGroups The per-frame
 *   functional groups.
 * @param {boolean} [completeOrigins] Flag to complete origins if gaps,
 *   defaults to false.
 * @param {Point3D[]} [refOrigins] Reference origins used to complete
 *   gaps, if not present the code will calculate them if completeOrigins
 *   is true.
 * @returns {Geometry} The geometry.
 * @throws {Error} Error for missing or wrong data.
 */
export function getFramesGeometry(
  dataElements,
  perFrameFuncGroups,
  completeOrigins,
  refOrigins) {
  // image size
  const size2D = getImage2DSize(dataElements);
  const size = new Size([size2D[0], size2D[1], 1]);

  // Shared Functional Groups Sequence
  let spacing;
  let imageOrientationPatient;
  const sharedFunctionalGroupsSeq =
    safeGetAll(dataElements, TagKeys.SharedFunctionalGroupsSequence);
  if (typeof sharedFunctionalGroupsSeq !== 'undefined') {
    // should be only one
    const funcGroup0 = sharedFunctionalGroupsSeq[0];
    // Plane Orientation Sequence
    if (typeof funcGroup0[TagKeys.PlaneOrientationSequence] !== 'undefined') {
      const planeOrientationSeq =
        funcGroup0[TagKeys.PlaneOrientationSequence];
      if (planeOrientationSeq.value.length !== 0) {
        // should be only one
        imageOrientationPatient =
          planeOrientationSeq.value[0][TagKeys.ImageOrientationPatient].value;
      } else {
        logger.warn(
          'No shared functional group plane orientation sequence items.');
      }
    }
    // Pixel Measures Sequence
    if (typeof funcGroup0[TagKeys.PixelMeasuresSequence] !== 'undefined') {
      const pixelMeasuresSeq = funcGroup0[TagKeys.PixelMeasuresSequence];
      if (pixelMeasuresSeq.value.length !== 0) {
        // should be only one
        spacing = getSpacingFromMeasure(pixelMeasuresSeq.value[0]);
      } else {
        logger.warn(
          'No shared functional group pixel measure sequence items.');
      }
    }
  }

  // check frame infos
  const frameOrigins = [];
  for (let ii = 0; ii < perFrameFuncGroups.length; ++ii) {
    // populate frame origins
    const frameOrigin = point3DFromArray(perFrameFuncGroups[ii].imagePosPat);
    if (!includesPoint3D(frameOrigins, frameOrigin)) {
      frameOrigins.push(frameOrigin);
    }
    // store orientation if needed, avoid multi
    if (typeof perFrameFuncGroups[ii].imageOrientationPatient !== 'undefined') {
      if (typeof imageOrientationPatient === 'undefined') {
        imageOrientationPatient =
          perFrameFuncGroups[ii].imageOrientationPatient;
      } else if (!arraySortEquals(
        imageOrientationPatient,
        perFrameFuncGroups[ii].imageOrientationPatient)) {
        throw new Error('Unsupported multi orientation frames geometry.');
      }
    }
    // store spacing if needed, avoid multi
    if (typeof perFrameFuncGroups[ii].spacing !== 'undefined') {
      if (typeof spacing === 'undefined') {
        spacing = perFrameFuncGroups[ii].spacing;
      } else if (!spacing.equals(perFrameFuncGroups[ii].spacing)) {
        throw new Error('Unsupported multi resolution frames geometry.');
      }
    }
  }

  // check spacing and orientation
  if (typeof spacing === 'undefined') {
    throw new Error('No spacing found for frames geometry');
  }
  if (typeof imageOrientationPatient === 'undefined') {
    throw new Error('No imageOrientationPatient found for frames geometry');
  }
  // orientation
  const orientationMatrix = getOrientationFromCosines(
    imageOrientationPatient.map((item) => parseFloat(item))
  );
  if (typeof orientationMatrix === 'undefined') {
    throw new Error(
      'Invalid imageOrientationPatient found for frames geometry');
  }

  let origins;
  if (typeof completeOrigins === 'undefined' ||
    completeOrigins === false) {
    origins = frameOrigins;
    // frames can be in any order: compute spacing on sorted origins
    const sortedOrigins = origins.slice().sort(
      getComparePoint3D(orientationMatrix));
    const geoSpacing = getSliceGeometrySpacing(sortedOrigins);
    if (spacing.length() === 2) {
      spacing = new Spacing([spacing.get(0), spacing.get(1), geoSpacing]);
    } else if (spacing.get(2) !== geoSpacing) {
      logger.debug(`Different tag spacing from geo spacing: ${
        spacing.get(2)} - ${geoSpacing}`);
    }
  } else if (typeof refOrigins !== 'undefined') {
    origins = completeOriginsFromReference(frameOrigins, refOrigins);
  } else {
    // tmp geometry with correct spacing but only one slice
    const baseGeometry = new Geometry(
      [frameOrigins[0]], size, spacing, orientationMatrix);

    origins = completeOriginsFromGeometry(frameOrigins, baseGeometry);
  }

  if (spacing.length() !== 3) {
    throw new Error('Incomplete spacing found for frames geometry');
  }

  // final geometry
  const geometry = new Geometry(
    [origins[0]], size, spacing, orientationMatrix);
  // append origins
  for (let m = 1; m < origins.length; ++m) {
    geometry.appendOrigin(origins[m], m);
  }

  // stamp a tag-derived time (for example TemporalPositionIndex), so
  // the frames of a multi-frame file are appended to their timepoint
  // (see ImageFactory getFrameGeometry)
  const volumeId = getVolumeId(dataElements);
  if (typeof volumeId !== 'undefined') {
    geometry.setInitialTime(volumeId);
  }

  return geometry;
}

/**
 * Get the geometry of each frame from the per-frame functional groups:
 *   a one slice geometry with the frame position and the frame time.
 *   The frame time is the data volume id (if any) if the frame positions
 *   are unique. If frames share positions (several volumes in one
 *   file), the frame time is the frame volume id (see dicomVolume
 *   guessVolumeIndices).
 *
 * @param {DataElements} dataElements The DICOM data elements.
 * @returns {Geometry[]|undefined} The list of geometries indexed by
 *   frame (encoding order) number. Undefined if there are no per-frame
 *   functional groups or if their positions are not unique and cannot
 *   be grouped into volumes.
 * @throws {Error} Error for missing or wrong data.
 */
export function getSortedFramesGeometry(dataElements) {
  const funcGroups = getPerFrameFunctionalGroups(dataElements);
  if (typeof funcGroups === 'undefined') {
    return;
  }
  // a group can be undefined if its required sequences are missing
  if (funcGroups.some(funcGroup => typeof funcGroup === 'undefined')) {
    logger.warn('Incomplete per-frame functional groups, ' +
      'not using them for geometry');
    return;
  }

  // frame origins and index in the list of unique origins
  const frameOrigins = [];
  const uniqueOrigins = [];
  const frameUniqueIndices = [];
  for (const funcGroup of funcGroups) {
    const frameOrigin = point3DFromArray(funcGroup.imagePosPat);
    let uniqueIndex = uniqueOrigins.findIndex(
      getEqualPoint3DFunction(frameOrigin));
    if (uniqueIndex === -1) {
      uniqueIndex = uniqueOrigins.length;
      uniqueOrigins.push(frameOrigin);
    }
    frameOrigins.push(frameOrigin);
    frameUniqueIndices.push(uniqueIndex);
  }

  // duplicate origins: group frames into volumes
  let frameTimes;
  if (uniqueOrigins.length !== frameOrigins.length) {
    const frameElementsList = [];
    for (let i = 0; i < frameOrigins.length; ++i) {
      frameElementsList.push(getFrameElements(dataElements, i));
    }
    const guess = guessVolumeIndices(
      frameElementsList, frameUniqueIndices, uniqueOrigins.length);
    if (typeof guess === 'undefined') {
      logger.warn('Duplicate frame origins without volume ids, ' +
        'not using them for geometry');
      return;
    }
    frameTimes = guess.volumeIds;
  }

  // common geometry (spacing, orientation, time)
  const geometry = getFramesGeometry(dataElements, funcGroups);
  const geoSize = geometry.getSize();
  const frameSize = new Size([geoSize.get(0), geoSize.get(1), 1]);

  const res = [];
  for (let i = 0; i < frameOrigins.length; ++i) {
    res.push(new Geometry(
      [frameOrigins[i]],
      frameSize,
      geometry.getSpacing(),
      geometry.getOrientation(),
      typeof frameTimes !== 'undefined'
        ? frameTimes[i] : geometry.getInitialTime()
    ));
  }
  return res;
}