DWVv0.37.0
src/image/imageContour.jsjavascript
/**
 * @import {Matrix33} from '../math/matrix.js';
 * @import {Size} from './size.js';
 */

/**
 * Maximum contour size in pixels.
 *
 * @type {number}
 */
export const MAX_CONTOUR_SIZE = 10;

/**
 * Image contour buffer manager.
 * Caches per-pixel distance-to-border values for contour rendering.
 * Stores 3 distance values per pixel (one per orientation: x, y, z).
 */
export class ImageContour {

  /**
   * Contour data buffer (3 values per image pixel).
   * Null when contour rendering is not enabled.
   *
   * @type {Uint8Array?}
   */
  #data = null;

  /**
   * Reference to the image data buffer.
   *
   * @type {Uint8Array?}
   */
  #imageBuffer = null;

  /**
   * Reference to the image size.
   *
   * @type {Size}
   */
  #imageSize = null;

  /**
   * Initialize the contour buffer.
   * Should be called on every segmentation image, or any image where
   * contour rendering needs to be supported.
   *
   * @param {Uint8Array} imageBuffer The image data buffer.
   * @param {Size} imageSize The image size.
   */
  initialize(imageBuffer, imageSize) {
    this.#imageBuffer = imageBuffer;
    this.#imageSize = imageSize;
    this.#data = new Uint8Array(imageBuffer.length * 3);
  }

  /**
   * Get whether or not the contour buffer has been initialized.
   *
   * @returns {boolean} True if buffer has been initialized.
   */
  isInitialized() {
    return this.#data !== null;
  }

  /**
   * Re-allocate contour buffer memory after an image buffer resize.
   * Updates the stored image buffer and size references.
   *
   * @param {Uint8Array} imageBuffer The new image data buffer.
   * @param {Size} imageSize The new image size.
   */
  realloc(imageBuffer, imageSize) {
    this.#imageBuffer = imageBuffer;
    this.#imageSize = imageSize;
    let tmpBuffer = this.#data;
    this.#data = new Uint8Array(imageBuffer.length * 3);
    this.#data.set(tmpBuffer);
    // force GC
    // eslint-disable-next-line no-useless-assignment
    tmpBuffer = null;
  }

  /**
   * Shift contour buffer content to make room for an inserted slice.
   *
   * @param {number} contourIndexOffset Start offset of the slice to shift.
   * @param {number} contourSliceSize Size of one contour slice.
   * @param {number} contourMaxOffset End offset of content to shift.
   */
  shiftSlice(contourIndexOffset, contourSliceSize, contourMaxOffset) {
    this.#data.set(
      this.#data.subarray(contourIndexOffset, contourMaxOffset),
      contourIndexOffset + contourSliceSize
    );
  }

  /**
   * Reset contour buffer values at a single offset (3 bytes: x, y, z).
   *
   * @param {number} offset The offset to reset.
   */
  #resetAtOffset(offset) {
    this.#data[offset * 3] = 0;
    this.#data[(offset * 3) + 1] = 0;
    this.#data[(offset * 3) + 2] = 0;
  }

  /**
   * Reset contour buffer for the values around an offset.
   * Prevents certain artifacts, especially at small brush sizes
   * and when erasing.
   *
   * @param {number} offset The offset to reset.
   */
  resetAroundOffset(offset) {
    if (!this.isInitialized()) {
      return;
    }
    this.#resetAtOffset(offset);

    const xOffset = this.#imageSize.getDimSize(0);
    const yOffset = this.#imageSize.getDimSize(1);
    const zOffset = this.#imageSize.getDimSize(2);

    const max = MAX_CONTOUR_SIZE / 2;
    const min = -max;
    for (let x = min; x < max; x++) {
      for (let y = min; y < max; y++) {
        for (let z = min; z < max; z++) {
          const p =
            offset +
            (xOffset * x) +
            (yOffset * y) +
            (zOffset * z);
          if (p >= 0 && p < this.#imageBuffer.length) {
            this.#resetAtOffset(p);
          }
        }
      }
    }
  }

  /**
   * Move cursor a step in the X direction to check for border pixels.
   *
   * @param {number} distance Accumulated distance travelled.
   * @param {number} index Current cursor index before moving.
   * @param {number} direction Offset to move cursor.
   * @param {number} dim The index of the current dimension.
   * @param {number} checkValue Initial pixel value.
   * @param {Function[]} queue Ordered queue of locations to check.
   * @returns {Function} A function that returns the distance to the nearest
   *  border pixel or 0.
   */
  #recursiveDistanceCheckX(distance, index, direction, dim, checkValue, queue) {
    return () => {
      const newIndex = index + direction;
      const newDistance = distance + 1;

      const borderCheck = this.#imageSize.offsetToIndex(newIndex);

      if (
        newIndex >= this.#imageBuffer.length ||
        newIndex < 0 ||
        borderCheck.get(dim) === 0 ||
        borderCheck.get(dim) === this.#imageSize.get(dim) - 1 ||
        newDistance === 255
      ) {
        return newDistance;
      }

      if (newDistance > MAX_CONTOUR_SIZE) {
        return 255;
      }

      if (this.#imageBuffer[newIndex] !== checkValue) {
        return newDistance;
      }

      queue.push(this.#recursiveDistanceCheckX(
        newDistance, newIndex, direction, dim, checkValue, queue
      ));

      return 0;
    };
  }

  /**
   * Move cursor a step in the Y direction to check for border pixels.
   * Also spawns two new cursors checking in the X directions to either side.
   *
   * @param {number} distance Accumulated distance travelled.
   * @param {number} index Current cursor index before moving.
   * @param {number} yDirection Offset to move cursor.
   * @param {number} xDirection Offset to move cursor.
   * @param {number} yDim The index of the y dimension.
   * @param {number} xDim The index of the x dimension.
   * @param {number} checkValue Initial pixel value.
   * @param {Function[]} queue Ordered queue of locations to check.
   * @returns {Function} A function that returns the distance to the nearest
   *  border pixel or 0.
   */
  #recursiveDistanceCheckY(
    distance, index, yDirection, xDirection, yDim, xDim, checkValue, queue
  ) {
    return () => {
      const newIndex = index + yDirection;
      const newDistance = distance + 1;

      const borderCheck = this.#imageSize.offsetToIndex(newIndex);

      if (
        newIndex >= this.#imageBuffer.length ||
        newIndex < 0 ||
        borderCheck.get(yDim) === 0 ||
        borderCheck.get(yDim) === this.#imageSize.get(yDim) - 1 ||
        newDistance === 255
      ) {
        return newDistance;
      }

      if (newDistance > MAX_CONTOUR_SIZE) {
        return 255;
      }

      if (this.#imageBuffer[newIndex] !== checkValue) {
        return newDistance;
      }

      queue.push(this.#recursiveDistanceCheckX(
        newDistance, newIndex, xDirection, xDim, checkValue, queue
      ));
      queue.push(this.#recursiveDistanceCheckX(
        newDistance, newIndex, -xDirection, xDim, checkValue, queue
      ));
      queue.push(this.#recursiveDistanceCheckY(
        newDistance, newIndex, yDirection, xDirection,
        yDim, xDim, checkValue, queue
      ));

      return 0;
    };
  }

  /**
   * Calculate the distance to the nearest border pixel
   * (or return the cached distance).
   * Returns 0 if the contour buffer is not initialized.
   *
   * @param {number} index Index/offset of the pixel to check.
   * @param {Matrix33} viewOrientation The orientation of the view.
   * @returns {number} The distance to the nearest border pixel or 0.
   */
  getDistance(index, viewOrientation) {
    if (!this.isInitialized()) {
      return 0;
    }

    const orientationIndex = viewOrientation.getThirdColMajorDirection();

    const xDim = (orientationIndex + 1) % 3;
    const yDim = (orientationIndex + 2) % 3;

    const contourIndex = index * 3 + orientationIndex;

    const bufferedDistance = this.#data[contourIndex];
    if (bufferedDistance > 0) {
      return bufferedDistance;
    }

    const checkValue = this.#imageBuffer[index];
    const operationQueue = [];

    const yDimSize = this.#imageSize.getDimSize(yDim);
    const xDimSize = this.#imageSize.getDimSize(xDim);

    operationQueue.push(this.#recursiveDistanceCheckY(
      0, index, yDimSize, xDimSize, yDim, xDim, checkValue, operationQueue
    ));
    operationQueue.push(this.#recursiveDistanceCheckX(
      0, index, xDimSize, xDim, checkValue, operationQueue
    ));
    operationQueue.push(this.#recursiveDistanceCheckX(
      0, index, -xDimSize, xDim, checkValue, operationQueue
    ));
    operationQueue.push(this.#recursiveDistanceCheckY(
      0, index, -yDimSize, xDimSize, yDim, xDim, checkValue, operationQueue
    ));

    let opCount = 0;
    // Enough to check every square up to MAX_CONTOUR_SIZE
    const maxOps = Math.pow(MAX_CONTOUR_SIZE, 2);
    while (operationQueue.length > 0) {
      opCount++;
      if (opCount > maxOps) {
        this.#data[contourIndex] = 255;
        return 255;
      }

      const operation = operationQueue.shift();
      const distanceCheck = operation();

      if (distanceCheck > 0) {
        // Return the first valid distance we find
        this.#data[contourIndex] = distanceCheck;
        return distanceCheck;
      }
    }

    // Something has gone wrong
    return Infinity;
  }

} // class ImageContour