DWVv0.37.0
src/image/imageFactory.jsjavascript
import {RescaleSlopeAndIntercept} from './rsi.js';
import {WindowLevel} from './windowLevel.js';
import {WindowPreset} from './windowPreset.js';
import {Image} from './image.js';
import {Size} from './size.js';
import {Geometry} from './geometry.js';
import {ColourMap} from './luts.js';
import {safeGet, safeGetAll} from '../dicom/dataElement.js';
import {
  getImage2DSize,
  getPixelSpacing,
  getTagPixelUnit,
  getPhotometricInterpretation,
  isMonochrome,
  isSecondatyCapture
} from '../dicom/dicomImage.js';
import {hasAnyPixelDataElement} from '../dicom/dicomTag.js';
import {
  getRootGeometry,
  getSortedFramesGeometry
} from '../dicom/dicomGeometry.js';
import {getSuvFactor} from '../dicom/dicomPet.js';
import {logger} from '../utils/logger.js';

/**
 * @import {DataElement} from '../dicom/dataElement.js';
 * @import {TypedArray} from '../math/types.js';
 */

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

/**
 * Related DICOM tag keys.
 */
const TagKeys = {
  TransferSyntaxUID: '00020010',
  SOPClassUID: '00080016',
  SOPInstanceUID: '00080018',
  Modality: '00080060',
  SamplesPerPixel: '00280002',
  PlanarConfiguration: '00280006',
  NumberOfFrames: '00280008',
  RescaleSlope: '00281053',
  RescaleIntercept: '00281052',
  MediaStorageSOPClassUID: '00020002',
  ImageType: '00080008',
  PhotometricInterpretation: '00280004',
  PixelRepresentation: '00280103',
  BitsAllocated: '00280100',
  BitsStored: '00280101',
  HighBit: '00280102',
  ImageOrientationPatient: '00200037',
  WindowCenter: '00281050',
  WindowLevel: '00281051',
  WindowCenterWidthExplanation: '00281055',
  RedPaletteColorLookupTableDescriptor: '00281101',
  RedPaletteColorLookupTableData: '00281201',
  GreenPaletteColorLookupTableData: '00281202',
  BluePaletteColorLookupTableData: '00281203',
  RecommendedDisplayFrameRate: '00082144'
};

/**
 * Meta tag keys.
 */
const MetaTagKeys = {
  // patient
  PatientName: '00100010',
  PatientID: '00100020',
  PatientBirthDate: '00100030',
  PatientSex: '00100040',
  // general study
  StudyDate: '00080020',
  StudyTime: '00080030',
  StudyInstanceUID: '0020000D',
  StudyID: '00200010',
  StudyDescription: '00081030',
  ReferringPhysicianName: '00080090',
  // general series
  SeriesDate: '00080021',
  SeriesTime: '00080031',
  SeriesInstanceUID: '0020000E',
  SeriesNumber: '00200011',
  // frame of reference
  FrameOfReferenceUID: '00200052',
  // general equipment
  Manufacturer: '00080070',
  ManufacturerModelName: '00081090',
  DeviceSerialNumber: '00181000',
  SoftwareVersions: '00181020',
  // general image
  LossyImageCompression: '00282110',
  // voi lut
  VOILUTFunction: '00281056'
};

/**
 * Get the palette colour map.
 *
 * @param {Record<string, DataElement>} dataElements The data elements.
 * @returns {ColourMap|undefined} The palette colour map.
 */
function getPaletteColourMap(dataElements) {
  let colourMap;
  // check red palette descriptor (should all be equal)
  // Red Palette Color Lookup Table Descriptor
  // 0: number of entries in the lookup table
  // 1: first input value mapped
  // 2: number of bits for each entry in the Lookup Table Data (8 or 16)
  const descriptor =
    safeGetAll(dataElements, TagKeys.RedPaletteColorLookupTableDescriptor);
  if (typeof descriptor !== 'undefined' &&
    descriptor.length === 3) {
    let redLut;
    let greenLut;
    let blueLut;
    // Red Palette Color Lookup Table Data
    const redLutElement =
      dataElements[TagKeys.RedPaletteColorLookupTableData];
    // Green Palette Color Lookup Table Data
    const greenLutElement =
      dataElements[TagKeys.GreenPaletteColorLookupTableData];
    // Blue Palette Color Lookup Table Data
    const blueLutElement =
      dataElements[TagKeys.BluePaletteColorLookupTableData];

    if (descriptor[2] === 16) {
      let doScale = false;
      // (C.7.6.3.1.5 Palette Color Lookup Table Descriptor)
      // Some implementations have encoded 8 bit entries with 16 bits
      // allocated, padding the high bits;
      let descSize = descriptor[0];
      // (C.7.6.3.1.5 Palette Color Lookup Table Descriptor)
      // The first Palette Color Lookup Table Descriptor value is the
      // number of entries in the lookup table. When the number of table
      // entries is equal to 216 then this value shall be 0.
      if (descSize === 0) {
        descSize = 65536;
      }
      // red palette VL
      // TODO vl is undefined, find info elsewhere...
      const vlSize = redLutElement.vl;
      // check double size
      if (vlSize !== 2 * descSize) {
        doScale = true;
        logger.info(`16bits lut but size is not double. desc: ${
          descSize } vl: ${vlSize}`);
      }
      // (C.7.6.3.1.6 Palette Color Lookup Table Data)
      // Palette color values must always be scaled across the full
      // range of available intensities
      const bitsAllocated = parseInt(
        safeGet(dataElements, TagKeys.BitsAllocated), 10);
      if (bitsAllocated === 8) {
        doScale = true;
        logger.info(
          'Scaling 16bits color lut since bits allocated is 8.');
      }

      if (doScale) {
        const scaleTo8 = function (value) {
          return value >> 8;
        };

        redLut = redLutElement.value.map(scaleTo8);
        greenLut = greenLutElement.value.map(scaleTo8);
        blueLut = blueLutElement.value.map(scaleTo8);
      }
    } else if (descriptor[2] === 8) {
      // lut with vr=OW was read as Uint16, convert it to Uint8
      logger.info(
        'Scaling 16bits color lut since the lut descriptor is 8.');
      let clone = redLutElement.value.slice(0);
      // @ts-expect-error -- clone is a plain number[], it has no buffer
      redLut = Array.from(new Uint8Array(clone.buffer));
      clone = greenLutElement.value.slice(0);
      // @ts-expect-error -- clone is a plain number[], it has no buffer
      greenLut = Array.from(new Uint8Array(clone.buffer));
      clone = blueLutElement.value.slice(0);
      // @ts-expect-error -- clone is a plain number[], it has no buffer
      blueLut = Array.from(new Uint8Array(clone.buffer));
    }
    colourMap = new ColourMap(redLut, greenLut, blueLut);
  }
  // return
  return colourMap;
}

/**
 * Get the window level presets.
 *
 * @param {Record<string, DataElement>} dataElements The data elements.
 * @param {number} intensityFactor The intensity factor.
 * @returns {Record<string, WindowPreset>|undefined} The presets.
 */
function getWindowPresets(dataElements, intensityFactor) {
  let windowPresets;
  const windowCenter = safeGetAll(dataElements, TagKeys.WindowCenter);
  const windowWidth = safeGetAll(dataElements, TagKeys.WindowLevel);
  if (typeof windowCenter !== 'undefined' &&
    typeof windowWidth !== 'undefined') {
    windowPresets = {};
    const windowCWExplanation =
      safeGetAll(dataElements, TagKeys.WindowCenterWidthExplanation);
    let name;
    for (let j = 0; j < windowCenter.length; ++j) {
      const center = parseFloat(windowCenter[j]);
      let width = parseFloat(windowWidth[j]);
      if (!isNaN(center) && !isNaN(width) && width !== 0) {
        name = '';
        if (typeof windowCWExplanation !== 'undefined') {
          name = windowCWExplanation[j];
        }
        if (name === '') {
          name = `Default${j}`;
        }
        // the width minimum depends on the VOI LUT function:
        // it is applied by the view
        width *= intensityFactor;
        windowPresets[name] = new WindowPreset(
          name,
          [new WindowLevel(
            center * intensityFactor,
            width
          )]
        );
      }
      if (width === 0) {
        logger.warn('Zero window width found in DICOM.');
      }
    }
  }
  // return
  return windowPresets;
}

/**
 * Frames geometry cache: frames of a multi-frame data share
 * the same data elements, avoid calculating it for each frame.
 *
 * @type {WeakMap<DataElements, Geometry[]|undefined>}
 */
const framesGeometryCache = new WeakMap();

/**
 * Get the geometry of one frame of a multi-frame data.
 *
 * Frames with per-frame positions get their geometry from
 * getSortedFramesGeometry: the frame position and the data time,
 * or the volume index as time if frames share positions. Other
 * frames are time frames: the frame geometry has the root position
 * and the frame number as time. Once all frames are appended
 * (see Image.appendSlice), the image has the same layout as the one
 * created from the full buffer.
 *
 * @param {DataElements} dataElements The DICOM tags.
 * @param {number} frameNumber The frame number.
 * @returns {Geometry} The frame geometry.
 */
function getFrameGeometry(dataElements, frameNumber) {
  if (!framesGeometryCache.has(dataElements)) {
    framesGeometryCache.set(
      dataElements, getSortedFramesGeometry(dataElements));
  }
  const framesGeometry = framesGeometryCache.get(dataElements);

  let res;
  if (typeof framesGeometry !== 'undefined') {
    // clone: the geometry of the first frame is modified by appends
    res = framesGeometry[frameNumber].clone();
  } else {
    const geometry = getRootGeometry(dataElements);
    const size2D = getImage2DSize(dataElements);
    res = new Geometry(
      [geometry.getOrigin()],
      new Size([size2D[0], size2D[1], 1]),
      geometry.getSpacing(),
      geometry.getOrientation(),
      {id: {value: frameNumber}}
    );
  }
  return res;
}

/**
 * {@link Image} factory.
 */
export class ImageFactory {

  /**
   * Possible warning created by checkElements.
   *
   * @type {string|undefined}
   */
  #warning;

  /**
   * The PET SUV factor.
   *
   * @type {number|undefined}
   */
  #suvFactor;

  /**
   * Get a warning string if elements are not as expected.
   * Created by checkElements.
   *
   * @returns {string|undefined} The warning.
   */
  getWarning() {
    return this.#warning;
  }

  /**
   * Check dicom elements.
   *
   * @param {DataElements} dataElements The DICOM data elements.
   * @returns {string|undefined} A possible warning.
   * @throws {Error} Error for missing or wrong data.
   */
  checkElements(dataElements) {
    // reset
    this.#warning = undefined;
    // check image size
    if (typeof getImage2DSize(dataElements) === 'undefined') {
      throw new Error('No image rows or columns in DICOM file');
    };
    // check pixel data
    if (!hasAnyPixelDataElement(dataElements)) {
      throw new Error('No pixel data in DICOM file');
    }
    // check PET SUV
    const modality = safeGet(dataElements, TagKeys.Modality);
    if (typeof modality !== 'undefined' && modality === 'PT') {
      const photometricInterpretation =
        getPhotometricInterpretation(dataElements);
      const SOPClassUID = safeGet(dataElements, TagKeys.SOPClassUID);
      if (isSecondatyCapture(SOPClassUID) ||
        !isMonochrome(photometricInterpretation)) {
        return this.#warning;
      }
      const suvFactor = getSuvFactor(dataElements);
      this.#suvFactor = suvFactor.value;
      this.#warning = suvFactor.warning;
    }

    return this.#warning;
  }

  /**
   * Get an {@link Image} object from the read DICOM file.
   *
   * @param {DataElements} dataElements The DICOM tags.
   * @param {TypedArray} pixelBuffer The pixel buffer.
   * @param {number} numberOfItems The number of load items.
   * @param {number} [frameNumber] The frame number if the pixel buffer
   *   only contains one frame of a multi-frame data: the image is
   *   then one frame, the other ones are to be appended to it.
   * @returns {Image} A new Image.
   * @throws {Error} Error for missing or wrong data.
   */
  create(dataElements, pixelBuffer, numberOfItems, frameNumber) {
    // safe get shortcuts
    const safeGetLocal = function (key) {
      return safeGet(dataElements, key);
    };

    // Sample per pixels
    let samplesPerPixel = safeGetLocal(TagKeys.SamplesPerPixel);
    if (typeof samplesPerPixel === 'undefined') {
      samplesPerPixel = 1;
    }

    // geometry: frames of multi-frame data are created one by one
    // and assembled by the image (see Image.appendSlice)
    let geometry;
    if (typeof frameNumber !== 'undefined') {
      geometry = getFrameGeometry(dataElements, frameNumber);
    } else {
      geometry = getRootGeometry(dataElements);
    }

    // number of pixels
    const numberOfPixels = geometry.getSize().getTotalSize();
    // needed for unit
    const spacing2D = getPixelSpacing(dataElements);

    // SOP Instance UID
    const sopInstanceUid = safeGetLocal(TagKeys.SOPInstanceUID);

    // check buffer size
    const bufferSize = numberOfPixels * samplesPerPixel;
    if (bufferSize !== pixelBuffer.length) {
      logger.warn(`Badly sized pixel buffer: ${
        pixelBuffer.length } != ${bufferSize}`);
      if (bufferSize < pixelBuffer.length) {
        pixelBuffer = pixelBuffer.slice(0, numberOfPixels);
      } else {
        throw new Error('Underestimated buffer size, can\'t fix it...');
      }
    }

    // image
    const image = new Image(geometry, pixelBuffer, [sopInstanceUid]);

    // PhotometricInterpretation
    const photo = getPhotometricInterpretation(dataElements);
    if (typeof photo !== 'undefined') {
      image.setPhotometricInterpretation(photo);
    }
    // PlanarConfiguration
    const planarConfiguration =
      safeGetLocal(TagKeys.PlanarConfiguration);
    if (typeof planarConfiguration !== 'undefined') {
      image.setPlanarConfiguration(planarConfiguration);
    }

    // rescale slope and intercept
    let slope = 1;
    // RescaleSlope
    const rescaleSlope = safeGetLocal(TagKeys.RescaleSlope);
    if (typeof rescaleSlope !== 'undefined') {
      const value = parseFloat(rescaleSlope);
      if (!isNaN(value)) {
        slope = value;
      }
    }
    let intercept = 0;
    // RescaleIntercept
    const rescaleIntercept = safeGetLocal(TagKeys.RescaleIntercept);
    if (typeof rescaleIntercept !== 'undefined') {
      const value = parseFloat(rescaleIntercept);
      if (!isNaN(value)) {
        intercept = value;
      }
    }

    // PET SUV
    let isPetWithSuv = false;
    let intensityFactor = 1;
    if (typeof this.#suvFactor !== 'undefined') {
      isPetWithSuv = true;
      intensityFactor = this.#suvFactor;
      logger.info(`Applying PET SUV calibration: ${intensityFactor}`);
      slope *= intensityFactor;
      intercept *= intensityFactor;
    }
    const rsi = new RescaleSlopeAndIntercept(slope, intercept);
    image.setRescaleSlopeAndIntercept(rsi);

    // PALETTE COLOR lut
    if (image.getPhotometricInterpretation() === 'PALETTE COLOR') {
      const colourMap = getPaletteColourMap(dataElements);
      if (typeof colourMap !== 'undefined') {
        image.setPaletteColourMap(colourMap);
      }
    }

    // meta information
    // (slice capacity is used to allocate the full buffer
    // when appending slices, for frames: the total number of frames)
    const meta = {
      sliceCapacity: numberOfItems
    };
    if (typeof frameNumber !== 'undefined') {
      const numberOfFrames = parseInt(
        safeGetLocal(TagKeys.NumberOfFrames), 10);
      meta.sliceCapacity *= numberOfFrames;
    }

    // defaults
    meta.TransferSyntaxUID = safeGetLocal(TagKeys.TransferSyntaxUID);
    meta.MediaStorageSOPClassUID =
      safeGetLocal(TagKeys.MediaStorageSOPClassUID);
    meta.SOPClassUID = safeGetLocal(TagKeys.SOPClassUID);
    meta.Modality = safeGetLocal(TagKeys.Modality);
    meta.ImageType = safeGetLocal(TagKeys.ImageType);
    meta.SamplesPerPixel = safeGetLocal(TagKeys.SamplesPerPixel);
    meta.PhotometricInterpretation =
      safeGetLocal(TagKeys.PhotometricInterpretation);
    meta.PixelRepresentation = safeGetLocal(TagKeys.PixelRepresentation);
    meta.BitsAllocated = safeGetLocal(TagKeys.BitsAllocated);

    meta.BitsStored = safeGetLocal(TagKeys.BitsStored);
    meta.HighBit = safeGetLocal(TagKeys.HighBit);

    // meta tags
    const metaKeys = Object.keys(MetaTagKeys);
    for (const key of metaKeys) {
      meta[key] = safeGetLocal(MetaTagKeys[key]);
    }

    // local pixel unit
    if (isPetWithSuv) {
      meta.pixelUnit = 'SUV';
    } else {
      const pixelUnit = getTagPixelUnit(dataElements);
      if (typeof pixelUnit !== 'undefined') {
        meta.pixelUnit = pixelUnit;
      }
    }

    // length unit
    if (typeof spacing2D === 'undefined') {
      meta.lengthUnit = 'unit.pixel';
    } else {
      meta.lengthUnit = 'unit.mm';
    }

    // window level presets
    const presets = getWindowPresets(dataElements, intensityFactor);
    if (typeof presets !== 'undefined') {
      meta.windowPresets = presets;
    }

    // store the meta data
    image.setMeta(meta);

    return image;
  }

}

/**
 * Demo Image creation from DICOM elements: takes
 * elements and first element of the pixel buffer
 * to create an image.
 *
 * Warning: not to be used in production code.
 *
 * @param {Record<string, DataElement>} elements The DICOM elements.
 * @returns {Image} The Image object.
 */
export function demoCreateImage(elements) {
  const factory = new ImageFactory();
  return factory.create(
    elements,
    elements['7FE00010'].value[0],
    1
  );
}