DWVv0.37.0
src/image/maskImage.jsjavascript
import {Index} from '../math/index.js';
import {REAL_WORLD_EPSILON} from '../math/number.js';
import {Size} from './size.js';
import {valueRange} from './iterator.js';
import {LabelingThread} from './labelingThread.js';
import {SegmentCollection} from './segmentCollection.js';
import {ImageContour} from './imageContour.js';
import {Image} from './image.js';
import {logger} from '../utils/logger.js';
import {MaskSegmentHelper} from './maskSegmentHelper.js';
import {ImageHistogram} from './imageHistogram.js';

/**
 * @import {Geometry} from './geometry.js';
 * @import {RGB} from '../utils/colour.js';
 * @import {Label} from './label.js';
 * @import {MaskSegment} from '../dicom/dicomSegment.js';
 * @import {SegmentHistogram} from './types.js';
 */

const ML_PER_MM = 0.001; // ml/mm^3

/**
 * Mask (segmentation) image class.
 * Extends {@link Image} with a {@link SegmentCollection} and the
 * segment-aware behavior built on top of it: per-segment/per-slice
 * bookkeeping, the brush tool's offset-editing methods, and per-segment
 * labeling statistics (volume/centroid/diameter).
 */
export class MaskImage extends Image {

  /**
   * @type {SegmentCollection}
   */
  #segmentCollection;

  /**
   * Mask contour, used for outline-style rendering.
   *
   * @type {ImageContour}
   */
  #contour = new ImageContour();

  /**
   * The labeling thread.
   *
   * @type {LabelingThread}
   */
  #labelingThread = null;

  /**
   * The labels from the last labeling, sorted by id then volume.
   *
   * @type {Label[]|undefined}
   */
  #labels;

  /**
   * @param {Geometry} geometry The geometry of the image.
   * @param {Uint8Array} buffer The mask data as a one dimensional buffer:
   *   one byte per voxel, 0 for background, the segment number otherwise.
   * @param {string[]} [imageUids] An array of Uids indexed to slice number.
   * @param {SegmentCollection} [segmentCollection] The segment collection,
   *   for a mask already parsed from DICOM (its own label map already
   *   aliases `buffer`). When omitted (brush-created masks), a fresh
   *   collection is created and its label map is aliased to `buffer`.
   */
  constructor(geometry, buffer, imageUids, segmentCollection) {
    super(geometry, buffer, imageUids);
    if (typeof segmentCollection === 'undefined') {
      segmentCollection = new SegmentCollection(geometry);
      segmentCollection.setLabelMap(buffer);
    }
    this.#segmentCollection = segmentCollection;

    // keep the segment collection's label map and the contour buffer
    // (both alias the buffer directly) pointing at it after a reallocation
    this.addEventListener('imagebufferrealloc', () => {
      this.#segmentCollection?.setLabelMap(
        /** @type {Uint8Array} */ (this.getBuffer()));
      if (this.#contour.isInitialized()) {
        this.#contour.realloc(
          /** @type {Uint8Array} */ (this.getBuffer()),
          this.getGeometry().getSize()
        );
      }
    });

    // replicate a buffer slice shift (from appendSlice) onto
    // the segment collection's per-slice indexing and the contour buffer
    this.addEventListener('imagesliceshift', (event) => {
      const {indexOffset, insertSize, maxOffset} =
        /** @type {CustomEvent} */ (event).detail;

      // #segments is keyed by slice index (not buffer offset), so it
      // needs re-indexing explicitly -- it isn't just an alias of the
      // (already correctly shifted) image buffer like the label map is
      const dimSliceSize = this.getGeometry().getSize().getDimSize(2);
      this.#segmentCollection?.shiftSlices(
        indexOffset / dimSliceSize, insertSize / dimSliceSize
      );

      if (this.#contour.isInitialized()) {
        // the contour buffer always tracks 3 values per voxel, while the
        // image buffer tracks getNumberOfComponents() (1 for a mask)
        const factor = 3 / this.getNumberOfComponents();
        this.#contour.shiftSlice(
          indexOffset * factor, insertSize * factor, maxOffset * factor
        );
      }
    });
  }

  /**
   * Initialize the contour buffer.
   * Should be called on every segmentation image, or any image where
   * contour rendering needs to be supported.
   */
  initializeContour() {
    this.#contour.initialize(
      /** @type {Uint8Array} */ (this.getBuffer()),
      this.getGeometry().getSize()
    );
  }

  /**
   * Get the image contour. Should only be available
   * for segmentation images, but can be initialized
   * for any Uint8Array image.
   *
   * @returns {ImageContour} The image contour.
   */
  getContour() {
    return this.#contour;
  }

  /**
   * Get the segment collection.
   *
   * @returns {SegmentCollection} The segment collection.
   */
  getSegmentCollection() {
    return this.#segmentCollection;
  }

  /**
   * Check whether the mask has overlapping segments.
   *
   * @returns {boolean} True if any two segments share at least one voxel.
   */
  getHasOverlap() {
    return this.#segmentCollection?.getHasOverlap() ?? false;
  }

  /**
   * Get the UID of the series referenced by the mask, if any.
   *
   * @returns {string|undefined} The UID.
   */
  getMaskReferencedSeriesUID() {
    return this.getMeta().custom.referencedSeriesUID;
  }

  /**
   * Check is the image is a mask.
   *
   * @returns {boolean} True.
   * @deprecated Since v0.37, please use `instanceof MaskImage` instead.
   */
  isMask() {
    return true;
  }

  /**
   * Get the numbers of the segments present at an index.
   * When segments overlap, all the segments at the index are returned,
   * not only the one stored in the buffer (first wins).
   *
   * @param {Index} index The index, no bounds check.
   * @returns {number[]} The sorted list of segment numbers,
   *   empty for background.
   */
  getSegmentNumbersAtIndex(index) {
    const numbers = new Set();
    const value = this.getValueAtIndex(index);
    if (value !== 0) {
      numbers.add(value);
    }
    if (this.getHasOverlap()) {
      const size = this.getGeometry().getSize();
      const sliceOffset = index.get(0) + index.get(1) * size.get(0);
      const segments = this.#segmentCollection.getAll();
      for (const [segNumber, sliceMap] of segments) {
        const sliceBuf = sliceMap.get(index.get(2));
        if (typeof sliceBuf !== 'undefined' && sliceBuf[sliceOffset] !== 0) {
          numbers.add(segNumber);
        }
      }
    }
    return [...numbers].sort((a, b) => a - b);
  }

  /**
   * Get the offsets where the buffer equals the input value.
   * Loops through the whole volume, can get long for big data...
   *
   * @param {number|RGB} value The value to check.
   * @returns {number[]} The list of offsets.
   */
  getOffsets(value) {
    const buffer = this.getBuffer();
    const numberOfComponents = this.getNumberOfComponents();
    // value to array
    let bufferValue;
    if (typeof value === 'number') {
      if (numberOfComponents !== 1) {
        throw new Error(
          'Number of components is not 1 for getting single value.');
      }
      bufferValue = [value];
    } else if (typeof value.r !== 'undefined' &&
      typeof value.g !== 'undefined' &&
      typeof value.b !== 'undefined') {
      if (numberOfComponents !== 3) {
        throw new Error(
          'Number of components is not 3 for getting RGB value.');
      }
      bufferValue = [value.r, value.g, value.b];
    }

    // main loop
    const offsets = [];
    let equal;
    for (let i = 0; i < buffer.length; i = i + numberOfComponents) {
      equal = true;
      for (let j = 0; j < numberOfComponents; ++j) {
        if (buffer[i + j] !== bufferValue[j]) {
          equal = false;
          break;
        }
      }
      if (equal) {
        offsets.push(i);
      }
    }
    return offsets;
  }

  /**
   * Set the inner buffer values at given offsets.
   *
   * @param {number[]} offsets List of offsets where to set the data.
   * @param {number|RGB} value The value to set at the given offsets.
   * @fires Image#imagecontentchange
   */
  setAtOffsets(offsets, value) {
    const buffer = this.getBuffer();
    const numberOfComponents = this.getNumberOfComponents();
    // value to array
    let bufferValue;
    if (typeof value === 'number') {
      if (numberOfComponents !== 1) {
        throw new Error(
          'Number of components is not 1 for setting single value.');
      }
      bufferValue = [value];
    } else if (typeof value.r !== 'undefined' &&
      typeof value.g !== 'undefined' &&
      typeof value.b !== 'undefined') {
      if (numberOfComponents !== 3) {
        throw new Error(
          'Number of components is not 3 for setting RGB value.');
      }
      bufferValue = [value.r, value.g, value.b];
    }

    let offset;
    for (let i = 0, leni = offsets.length; i < leni; ++i) {
      offset = offsets[i];
      if (numberOfComponents === 1) {
        const previousValue = buffer[offset];
        buffer[offset] = bufferValue[0];
        this.#segmentCollection?.updateAtOffset(
          offset, previousValue, bufferValue[0]);
      } else {
        for (let j = 0; j < numberOfComponents; ++j) {
          buffer[offset + j] = bufferValue[j];
        }
      }
    }
    // fire imagecontentchange
    this.dispatchEvent(new CustomEvent('imagecontentchange'));
  }

  /**
   * Set the inner buffer values at given offsets, each to its own value.
   * Used when a single uniform value cannot be used across all offsets,
   * for example restoring the segment still present at a voxel that used
   * to be hidden by an overlapping, now deleted, segment.
   *
   * @param {number[]} offsets List of offsets where to set the data.
   * @param {number[]} values Per-offset values, same length as offsets.
   * @fires Image#imagecontentchange
   */
  setAtOffsetsWithValues(offsets, values) {
    const buffer = this.getBuffer();
    for (let i = 0; i < offsets.length; ++i) {
      const offset = offsets[i];
      const value = values[i];
      const previousValue = buffer[offset];
      buffer[offset] = value;
      this.getContour().resetAroundOffset(offset);
      this.#segmentCollection?.updateAtOffset(offset, previousValue, value);
    }
    // fire imagecontentchange
    this.dispatchEvent(new CustomEvent('imagecontentchange'));
  }

  /**
   * Set the inner buffer values at given offsets.
   *
   * @param {number[][]} offsetsLists List of offset lists where
   *   to set the data.
   * @param {number} value The value to set at the given offsets.
   * @returns {Array} A list of objects representing the original values before
   *  replacing them.
   * @fires Image#imagecontentchange
   */
  setAtOffsetsAndGetOriginals(offsetsLists, value) {
    const buffer = this.getBuffer();
    const originalValuesLists = [];

    // update and store
    for (let j = 0; j < offsetsLists.length; ++j) {
      const offsets = offsetsLists[j];
      // first value
      let offset = offsets[0];
      let previousValue = buffer[offset];
      // original value storage
      const originalValues = [];
      originalValues.push({
        index: 0,
        value: previousValue
      });
      for (let i = 0; i < offsets.length; ++i) {
        offset = offsets[i];
        const currentValue = buffer[offset];
        // check if new value
        if (previousValue !== currentValue) {
          // store new value
          originalValues.push({
            index: i,
            value: currentValue
          });
          previousValue = currentValue;
        }
        // write update value
        buffer[offset] = value;
        this.getContour().resetAroundOffset(offset);
        this.#segmentCollection?.updateAtOffset(offset, currentValue, value);
      }
      originalValuesLists.push(originalValues);
    }
    // fire imagecontentchange
    this.dispatchEvent(new CustomEvent('imagecontentchange'));
    return originalValuesLists;
  }

  /**
   * Set the inner buffer values at given offsets.
   *
   * @param {number[][]} offsetsLists List of offset lists
   *   where to set the data.
   * @param {number|Array} value The value to set at the given offsets.
   * @fires Image#imagecontentchange
   */
  setAtOffsetsWithIterator(offsetsLists, value) {
    const buffer = this.getBuffer();
    const isValueArray = Array.isArray(value);

    for (let j = 0; j < offsetsLists.length; ++j) {
      const offsets = offsetsLists[j];
      let iterator;
      if (isValueArray) {
        // input value is a list of iterators
        // created by setAtOffsetsAndGetOriginals
        iterator = valueRange(
          value[j], offsets.length);
      } else {
        // input value is a simple color
        iterator = valueRange(
          [{index: 0, value}], offsets.length);
      }

      // set values
      let ival = iterator.next();
      while (!ival.done) {
        const offset = offsets[ival.index];
        const previousValue = buffer[offset];
        buffer[offset] = ival.value;
        this.getContour().resetAroundOffset(offset);
        this.#segmentCollection?.updateAtOffset(
          offset, previousValue, ival.value);
        ival = iterator.next();
      }
    }
    /**
     * Image content change event.
     *
     * @event Image#imagecontentchange
     * @type {CustomEvent}
     * @property {object} detail The event detail.
     */
    this.dispatchEvent(new CustomEvent('imagecontentchange'));
  }

  /**
   * Post-process labels after labeling thread is done.
   *
   * @param {any} labels The labels to update.
   * @fires Image#labelschanged
   */
  #postProcessLabels(labels) {
    const geometry = this.getGeometry();
    const spacing = geometry.getSpacing();
    const lengthUnit = this.getMeta().lengthUnit;
    let pixelVolume = 1;
    let volumeUnit = 'unit.pixel';
    if (lengthUnit === 'unit.mm') {
      pixelVolume =
        spacing.get(0) *
        spacing.get(1) *
        spacing.get(2) *
        ML_PER_MM;
      volumeUnit = 'unit.ml';
    }

    for (const label of labels) {
      // add centroid point
      label.centroid = geometry.indexToWorld(
        new Index(label.centroidIndex));
      // add volume
      label.volume = {
        value: label.count * pixelVolume,
        unit: volumeUnit
      };
      // add unit to values
      let majorDiameter;
      let minorDiameter;
      if (typeof label.diameters !== 'undefined') {
        if (typeof label.diameters.major !== 'undefined') {
          majorDiameter = label.diameters.major.diameter;
        }
        if (typeof label.diameters.minor !== 'undefined') {
          minorDiameter = label.diameters.minor.diameter;
        }
      }
      label.diameters = {
        major: {
          diameter: {
            value: majorDiameter,
            unit: lengthUnit
          }
        },
        minor: {
          diameter: {
            value: minorDiameter,
            unit: lengthUnit
          }
        }
      };
      label.height = {
        value: label.height,
        unit: lengthUnit
      };
    }
    // sort by volume then by id
    /** @type {Label[]} */
    const labelsSorted =
      labels.sort((v1, v2) => {
        return v2.volume.value - v1.volume.value;
      }).sort((v1, v2) => {
        return v1.id - v2.id;
      });

    this.#labels = labelsSorted;

    this.dispatchEvent(new CustomEvent('labelschanged', {
      detail: {
        labels: /** @type {Label[]} */ (labelsSorted)
      }
    }));
  }

  /**
   * Label segments with overlap.
   * The merged labelmap uses first-wins at overlap positions, so voxels
   * shared by two segments are attributed only to the first segment.
   * Run the filter once per segment on a clean per-segment buffer so
   * every segment gets its correct voxels counted.
   */
  #labelOverlapSegments() {
    const geometry = this.getGeometry();
    const imageSize = geometry.getSize();
    const nx = imageSize.get(0);
    const ny = imageSize.get(1);
    const segments = [];
    for (const [segNumber, sliceMap] of this.#segmentCollection.getAll()) {
      const sliceIndices = [...sliceMap.keys()];
      const minSlice = Math.min(...sliceIndices);
      const size = new Size([nx, ny, Math.max(...sliceIndices) - minSlice + 1]);
      const slices = [];
      for (const [sliceIndex, sliceBuf] of sliceMap) {
        slices.push({
          sliceIndex: sliceIndex - minSlice,
          data: new Uint8Array(sliceBuf)
        });
      }
      segments.push({segNumber, size, slices, minSlice});
    }

    this.#labelingThread.runOverlap(segments, geometry);
  }

  /**
   * Get the labels from the last labeling (see
   * {@link MaskImage#recalculateLabels}).
   *
   * @returns {Label[]|undefined} The labels, undefined if not calculated.
   */
  getLabels() {
    return this.#labels;
  }

  /**
   * Recalculate labels.
   *
   * @fires Image#labelingstart
   * @fires Image#labelschanged
   */
  recalculateLabels() {
    this.dispatchEvent(new CustomEvent('labelingstart'));

    // create thread if not done yet
    if (this.#labelingThread === null) {
      this.#labelingThread = new LabelingThread();

      this.#labelingThread.ondone = (event) => {
        this.#postProcessLabels(event.data.labels);
        //TODO: This is temporary until a proper method of displaying
        // diameters is implmented.
        // ------
        if (event.data.buffer) {
          this.replaceBuffer(event.data.buffer);
        }
        // ------
      };
    }

    const collection = this.#segmentCollection;
    if (collection?.getHasOverlap() && collection.getAll().size > 0) {
      this.#labelOverlapSegments();
    } else {
      this.#labelingThread.run(this.getBuffer(), this.getGeometry());
    }
  }

  /**
   * Clone the mask image.
   *
   * @returns {MaskImage} A clone of this mask image.
   */
  clone() {
    const copy = /** @type {MaskImage} */ (super.clone());
    // deep-copy the per-segment/per-slice data, then re-point its label
    // map to the copy's own (already pixel-cloned) buffer -- the fresh
    // SegmentCollection that MaskImage's constructor gave `copy` aliased
    // it correctly already, but only for an empty collection
    const clonedCollection = this.#segmentCollection.clone();
    clonedCollection.setLabelMap(
      /** @type {Uint8Array} */ (copy.getBuffer()));
    copy.#segmentCollection = clonedCollection;
    return copy;
  }

  /**
   * Get per-volume histograms of reference-image intensities for one segment.
   *
   * For each volume of `image`, counts how often each intensity
   * appears in voxels belonging to the given segment of this mask.
   * Segmentations are 3D: the same mask is applied to every volume.
   * Raw values are counted per rescale slope and intercept and rescaled
   * when read from the {@link ImageHistogram}.
   *
   * If labels are available (see {@link MaskImage#getLabels}), each entry
   * also has `labelHistograms`: one histogram per label of the segment, made of
   * the segment voxels between the label min and max Z. Since labels
   * of the same segment that share slices cannot be separated this way,
   * `labelHistograms` is not provided in that case.
   *
   * @param {Image} image The reference image (intensities).
   * @param {string} segmentId Segment tracking UID, or segment number as
   *   string.
   * @returns {SegmentHistogram[]} One entry per volume.
   */
  getHistogramBySegment(image, segmentId) {
    const segment = this.#findSegmentById(segmentId);
    if (typeof segment === 'undefined') {
      logger.warn(
        `getHistogramBySegment: unknown segment id: ${segmentId}`);
      return [];
    }

    const imageGeometry = image.getGeometry();
    if (!this.#isCompatibleGeometry(imageGeometry)) {
      throw new Error(
        'getHistogramBySegment: mask and image geometries are not compatible.');
    }
    const imageSize = imageGeometry.getSize();

    // image slice index of each mask slice
    const imageOrigins = imageGeometry.getOrigins();
    const sliceIndices = this.getGeometry().getOrigins().map(
      (maskOrigin) => imageOrigins.findIndex(
        (imageOrigin) => maskOrigin.isSimilar(imageOrigin, REAL_WORLD_EPSILON)
      )
    );

    const segmentValue = typeof segment.displayValue !== 'undefined'
      ? segment.displayValue
      : segment.number;

    const numberOfVolumes = imageSize.length() === 4
      ? imageSize.get(3)
      : 1;
    const volumeSize = imageSize.getDimSize(3);
    const sliceSize = imageSize.getDimSize(2);

    const maskBuffer = this.getBuffer();
    // histogram values are reference image values
    const unit = image.getMeta().pixelUnit;

    /**
     * Add the image values of the segment voxels of a slice range
     * to a histogram.
     *
     * @param {ImageHistogram} histogram The histogram to fill.
     * @param {number} v The volume index.
     * @param {number} kMin The first mask slice index.
     * @param {number} kMax The last mask slice index (inclusive).
     */
    const fillHistogram = (histogram, v, kMin, kMax) => {
      for (let k = kMin; k <= kMax; ++k) {
        const maskStart = k * sliceSize;
        const imageStart = v * volumeSize + sliceIndices[k] * sliceSize;

        // rsi of this image slice (index ignored for constant rsi)
        const rsi = image.getRescaleSlopeAndIntercept(
          imageSize.offsetToIndex(imageStart));
        // one lookup per slice, not per voxel
        const sliceHistogram = histogram.getHistogram(rsi);

        for (let i = 0; i < sliceSize; ++i) {
          if (maskBuffer[maskStart + i] !== segmentValue) {
            continue;
          }
          sliceHistogram.add(image.getValueAtOffset(imageStart + i));
        }
      }
    };

    // labels of this segment, if calculated
    let segmentLabels = this.#labels?.filter(
      (label) => label.id === segmentValue);
    // a label histogram uses all the segment voxels of the label slices:
    // only possible if labels do not share slices
    if (typeof segmentLabels !== 'undefined' &&
      this.#haveSharedSlices(segmentLabels)) {
      logger.debug(
        'getHistogramBySegment: labels share slices, ' +
        'no label histograms.');
      segmentLabels = undefined;
    }

    const result = [];
    for (let v = 0; v < numberOfVolumes; ++v) {
      // mask is always 3D spatial: reuse it for each volume
      const histogram = new ImageHistogram(unit);
      fillHistogram(histogram, v, 0, sliceIndices.length - 1);

      /** @type {SegmentHistogram} */
      const item = {volume: v, histogram};
      if (typeof segmentLabels !== 'undefined') {
        item.labelHistograms = segmentLabels.map((label) => {
          const labelHistogram = new ImageHistogram(unit);
          fillHistogram(labelHistogram, v, label.minZ, label.maxZ);
          return {label, histogram: labelHistogram};
        });
      }
      result.push(item);
    }

    return result;
  }

  /**
   * Check if some labels share slices (overlapping min/max Z ranges).
   *
   * @param {Label[]} labels The labels.
   * @returns {boolean} True if at least two labels share a slice.
   */
  #haveSharedSlices(labels) {
    const sorted = labels.slice().sort((a, b) => a.minZ - b.minZ);
    for (let i = 1; i < sorted.length; ++i) {
      if (sorted[i].minZ <= sorted[i - 1].maxZ) {
        return true;
      }
    }
    return false;
  }

  /**
   * Find a segment by tracking UID or by number as string.
   *
   * @param {string} segmentId The segment id.
   * @returns {MaskSegment|undefined} The segment, or undefined if not found.
   */
  #findSegmentById(segmentId) {
    const helper = new MaskSegmentHelper(this);
    const segments = this.getMeta()?.custom?.segments ?? [];

    for (const segment of segments) {
      if (segment.trackingUid === segmentId) {
        return segment;
      }
    }
    for (const segment of segments) {
      if (String(segment.number) === segmentId) {
        return segment;
      }
    }
    // also allow lookup when segments are only known via the helper
    // (e.g. freshly added) using the same number-as-string rule
    const asNumber = Number(segmentId);
    if (!Number.isNaN(asNumber) && helper.hasSegment(asNumber)) {
      return helper.getSegment(asNumber);
    }
    return undefined;
  }

  /**
   * Check if this mask and the image share slice size (dims 0-1) and
   * orientation, and that each mask origin is one of the image origins.
   * The mask can have fewer slices than the image. Segmentations are
   * 3D; dim 3 of a 4D reference image is ignored here.
   *
   * @param {Geometry} imageGeometry The reference image geometry.
   * @returns {boolean} True if the geometries are compatible.
   */
  #isCompatibleGeometry(imageGeometry) {
    const maskGeometry = this.getGeometry();
    const maskSize = maskGeometry.getSize();
    const imageSize = imageGeometry.getSize();
    for (let i = 0; i < 2; ++i) {
      if (maskSize.get(i) !== imageSize.get(i)) {
        return false;
      }
    }
    if (!maskGeometry.getOrientation().isSimilar(
      imageGeometry.getOrientation(), REAL_WORLD_EPSILON)) {
      return false;
    }
    const imageOrigins = imageGeometry.getOrigins();
    return maskGeometry.getOrigins().every(
      (maskOrigin) => imageOrigins.some(
        (imageOrigin) => maskOrigin.isSimilar(imageOrigin, REAL_WORLD_EPSILON)
      )
    );
  }

} // MaskImage class