@cornerstonejs/tools 2.0.0-beta.6 → 2.0.0-beta.8

package/src/utilities/BucketQueue.ts

@@ -0,0 +1,154 @@
+type BucketNode<T> = {
+  value: T;
+  next: BucketNode<T>;
+};
+
+/**
+ * Circular Bucket Queue.
+ *
+ * Returns input'd points in sorted order. All operations run in roughly O(1)
+ * time (for input with small cost values), but it has a strict requirement:
+ *
+ * If the most recent point had a cost of c, any points added should have a cost
+ * c' in the range c <= c' <= c + (capacity - 1).
+ */
+export class BucketQueue<T> {
+  private _bucketCount: number;
+  private _mask: number;
+  private _size: number;
+  private _currentBucketIndex: number;
+  private _getPriority: (item: T) => number;
+  private _areEqual: (itemA: T, itemB: T) => boolean;
+  private _buckets: BucketNode<T>[];
+
+  /**
+   * @param bits - Number of bits.
+   * @param getPriority - A function that returns the priority of an item
+   */
+  constructor({
+    numBits,
+    getPriority,
+    areEqual,
+  }: {
+    numBits: number;
+    getPriority?: (item: T) => number;
+    areEqual?: (itemA: T, itemB: T) => boolean;
+  }) {
+    this._bucketCount = 1 << numBits; // # of buckets = 2^numBits
+    this._mask = this._bucketCount - 1; // 2^numBits - 1 = index mask
+    this._size = 0;
+    this._currentBucketIndex = 0;
+    this._buckets = this._buildArray(this._bucketCount);
+
+    this._getPriority =
+      typeof getPriority !== 'undefined'
+        ? getPriority
+        : (item) => item as unknown as number;
+
+    this._areEqual =
+      typeof areEqual === 'function'
+        ? areEqual
+        : (itemA, itemB) => itemA === itemB;
+  }
+
+  /**
+   * Prepend item to the list in the appropriate bucket
+   * @param item - Item to be added to the queue based on its priority
+   */
+  public push(item: T) {
+    const bucketIndex = this._getBucketIndex(item);
+    const oldHead = this._buckets[bucketIndex];
+    const newHead: BucketNode<T> = {
+      value: item,
+      next: oldHead,
+    };
+
+    this._buckets[bucketIndex] = newHead;
+    this._size++;
+  }
+
+  public pop(): T {
+    if (this._size === 0) {
+      throw new Error('Cannot pop because the queue is empty.');
+    }
+
+    // Find first empty bucket
+    while (this._buckets[this._currentBucketIndex] === null) {
+      this._currentBucketIndex =
+        (this._currentBucketIndex + 1) % this._bucketCount;
+    }
+
+    // All items in bucket have same cost, return the first one
+    const ret = this._buckets[this._currentBucketIndex];
+
+    this._buckets[this._currentBucketIndex] = ret.next;
+    this._size--;
+
+    return ret.value;
+  }
+
+  /**
+   * Tries to remove item from queue.
+   * @param item - Item to be removed from the queue
+   * @returns True if the item is found and removed or false otherwise
+   */
+  public remove(item: T): boolean {
+    if (!item) {
+      return false;
+    }
+
+    // To find node, go to bucket and search through unsorted list.
+    const bucketIndex = this._getBucketIndex(item);
+    const firstBucketNode = this._buckets[bucketIndex];
+    let node = firstBucketNode;
+    let prevNode: BucketNode<T>;
+
+    while (node !== null) {
+      if (this._areEqual(item, node.value)) {
+        break;
+      }
+
+      prevNode = node;
+      node = node.next;
+    }
+
+    // Item not found
+    if (node === null) {
+      return false;
+    }
+
+    // Item found and it needs to be removed from the list
+    if (node === firstBucketNode) {
+      this._buckets[bucketIndex] = node.next;
+    } else {
+      prevNode.next = node.next;
+    }
+
+    this._size--;
+    return true;
+  }
+
+  public isEmpty(): boolean {
+    return this._size === 0;
+  }
+
+  /**
+   * Return the bucket index
+   * @param item - Item for which the bucket shall be returned
+   * @returns Bucket index for the item provided
+   */
+  private _getBucketIndex(item): number {
+    return this._getPriority(item) & this._mask;
+  }
+
+  /**
+   * Create array and initialze pointers to null
+   * @param size - Size of the new array
+   * @returns An array with `N` buckets pointing to null
+   */
+  private _buildArray(size) {
+    const buckets = new Array(size);
+    buckets.fill(null);
+    return buckets;
+  }
+}

package/src/utilities/annotationFrameRange.ts

@@ -0,0 +1,78 @@
+import { triggerEvent, eventTarget } from '@cornerstonejs/core';
+import Events from '../enums/Events';
+import { Annotation } from '../types';
+
+export type FramesRange = [number, number] | number;
+
+/**
+ * This class handles the annotation frame range values for multiframes.
+ * Mostly used for the Video viewport, it allows references to
+ * a range of frame values.
+ */
+export default class AnnotationFrameRange {
+  protected static frameRangeExtractor =
+    /(\/frames\/|[&?]frameNumber=)([^/&?]*)/i;
+
+  protected static imageIdToFrames(imageId: string): FramesRange {
+    const match = imageId.match(this.frameRangeExtractor);
+    if (!match || !match[2]) {
+      return null;
+    }
+    const range = match[2].split('-').map((it) => Number(it));
+    if (range.length === 1) {
+      return range[0];
+    }
+    return range as FramesRange;
+  }
+
+  public static framesToString(range) {
+    if (Array.isArray(range)) {
+      return `${range[0]}-${range[1]}`;
+    }
+    return String(range);
+  }
+
+  protected static framesToImageId(
+    imageId: string,
+    range: FramesRange | string
+  ): string {
+    const match = imageId.match(this.frameRangeExtractor);
+    if (!match || !match[2]) {
+      return null;
+    }
+    const newRangeString = this.framesToString(range);
+    return imageId.replace(
+      this.frameRangeExtractor,
+      `${match[1]}${newRangeString}`
+    );
+  }
+
+  /**
+   * Sets the range of frames to associate with the given annotation.
+   * The range can be a single frame number (1 based according to DICOM),
+   * or a range of values in the format `min-max` where min, max are inclusive
+   * Modifies the referencedImageID to specify the updated URL.
+   */
+  public static setFrameRange(
+    annotation: Annotation,
+    range: FramesRange | string,
+    eventBase?: { viewportId; renderingEngineId }
+  ) {
+    const { referencedImageId } = annotation.metadata;
+    annotation.metadata.referencedImageId = this.framesToImageId(
+      referencedImageId,
+      range
+    );
+    const eventDetail = {
+      ...eventBase,
+      annotation,
+    };
+    triggerEvent(eventTarget, Events.ANNOTATION_MODIFIED, eventDetail);
+  }
+
+  public static getFrameRange(
+    annotation: Annotation
+  ): number | [number, number] {
+    return this.imageIdToFrames(annotation.metadata.referencedImageId);
+  }
+}

package/src/utilities/annotationHydration.ts

@@ -0,0 +1,143 @@
+import {
+  Types,
+  utilities,
+  BaseVolumeViewport,
+  StackViewport,
+  cache,
+  metaData,
+} from '@cornerstonejs/core';
+import { Annotation } from '../types';
+import { addAnnotation } from '../stateManagement';
+import { vec3 } from 'gl-matrix';
+
+function annotationHydration(
+  viewport: Types.IViewport,
+  toolName: string,
+  worldPoints: Types.Point3[],
+  options?: {
+    FrameOfReferenceUID?: string;
+    annotationUID?: string;
+  }
+): Annotation {
+  const viewReference = viewport.getViewReference();
+  const { viewPlaneNormal, FrameOfReferenceUID } = viewReference;
+  const annotation = {
+    annotationUID: options?.annotationUID || utilities.uuidv4(),
+    data: {
+      handles: {
+        points: worldPoints,
+      },
+    },
+    highlighted: false,
+    autoGenerated: false,
+    invalidated: false,
+    isLocked: false,
+    isVisible: true,
+    metadata: {
+      toolName,
+      viewPlaneNormal,
+      FrameOfReferenceUID,
+      referencedImageId: getReferencedImageId(
+        viewport,
+        worldPoints[0],
+        viewPlaneNormal
+      ),
+      ...options,
+    },
+  };
+  addAnnotation(annotation, viewport.element);
+  return annotation;
+}
+
+function getReferencedImageId(
+  viewport: Types.IViewport,
+  worldPos: Types.Point3,
+  viewPlaneNormal: Types.Point3
+): string {
+  let referencedImageId;
+
+  if (viewport instanceof StackViewport) {
+    referencedImageId = getClosestImageIdForStackViewport(
+      viewport,
+      worldPos,
+      viewPlaneNormal
+    );
+  } else if (viewport instanceof BaseVolumeViewport) {
+    const targetId = getTargetId(viewport);
+    const volumeId = utilities.getVolumeId(targetId);
+    const imageVolume = cache.getVolume(volumeId);
+
+    referencedImageId = utilities.getClosestImageId(
+      imageVolume,
+      worldPos,
+      viewPlaneNormal
+    );
+  } else {
+    throw new Error(
+      'getReferencedImageId: viewport must be a StackViewport or BaseVolumeViewport'
+    );
+  }
+
+  return referencedImageId;
+}
+
+function getTargetId(viewport: Types.IViewport): string | undefined {
+  const targetId = viewport.getReferenceId?.();
+  if (targetId) {
+    return targetId;
+  }
+  if (viewport instanceof BaseVolumeViewport) {
+    return `volumeId:${getTargetVolumeId(viewport)}`;
+  }
+  throw new Error('getTargetId: viewport must have a getTargetId method');
+}
+
+function getTargetVolumeId(viewport: Types.IViewport): string | undefined {
+  const actorEntries = viewport.getActors();
+
+  if (!actorEntries) {
+    return;
+  }
+  return actorEntries.find(
+    (actorEntry) => actorEntry.actor.getClassName() === 'vtkVolume'
+  )?.uid;
+}
+
+function getClosestImageIdForStackViewport(
+  viewport: StackViewport,
+  worldPos: Types.Point3,
+  viewPlaneNormal: Types.Point3
+): string {
+  const imageIds = viewport.getImageIds();
+  if (!imageIds || !imageIds.length) {
+    return;
+  }
+
+  const distanceImagePairs = imageIds.map((imageId) => {
+    const { imagePositionPatient } = metaData.get('imagePlaneModule', imageId);
+    const distance = calculateDistanceToImage(
+      worldPos,
+      imagePositionPatient,
+      viewPlaneNormal
+    );
+    return { imageId, distance };
+  });
+
+  distanceImagePairs.sort((a, b) => a.distance - b.distance);
+
+  return distanceImagePairs[0].imageId;
+}
+
+function calculateDistanceToImage(
+  worldPos: Types.Point3,
+  ImagePositionPatient: Types.Point3,
+  viewPlaneNormal: Types.Point3
+): number {
+  const dir = vec3.create();
+  vec3.sub(dir, worldPos, ImagePositionPatient);
+
+  const dot = vec3.dot(dir, viewPlaneNormal);
+
+  return Math.abs(dot);
+}
+export { annotationHydration, getClosestImageIdForStackViewport };

package/src/utilities/boundingBox/getBoundingBoxAroundShape.ts

@@ -1,57 +1,110 @@
 import type { Types } from '@cornerstonejs/core';
+import { CONSTANTS } from '@cornerstonejs/core';
 
-/**
- * With a given vertices (points) coordinates in IJK, it calculates the minimum and maximum
- * coordinate in each axis, and returns them. If dimensions are provided it also
- * clip the min, max to the provided width, height and depth
- *
- * @param points - shape corner points coordinates (IJK)
- * @param dimensions - dimensions of the image
- * @returns [[xMin,xMax],[yMin,yMax], [zMin,zMax]]
- */
-function getBoundingBoxAroundShape(
-  points: Types.Point3[],
-  dimensions?: Types.Point3
-): [Types.Point2, Types.Point2, Types.Point2] {
+const { EPSILON } = CONSTANTS;
+
+/** Bounding box type */
+type BoundingBox =
+  | [Types.Point2, Types.Point2, null]
+  | [Types.Point2, Types.Point2, Types.Point2];
+
+function calculateBoundingBox(
+  points,
+  dimensions,
+  isWorld = false
+): BoundingBox {
   let xMin = Infinity;
-  let xMax = 0;
+  let xMax = isWorld ? -Infinity : 0;
   let yMin = Infinity;
-  let yMax = 0;
+  let yMax = isWorld ? -Infinity : 0;
   let zMin = Infinity;
-  let zMax = 0;
+  let zMax = isWorld ? -Infinity : 0;
+
+  const is3D = points[0]?.length === 3;
 
-  points.forEach((p) => {
+  // use for loop for performance
+  for (let i = 0; i < points.length; i++) {
+    const p = points[i];
     xMin = Math.min(p[0], xMin);
     xMax = Math.max(p[0], xMax);
     yMin = Math.min(p[1], yMin);
     yMax = Math.max(p[1], yMax);
-    zMin = Math.min(p[2], zMin);
-    zMax = Math.max(p[2], zMax);
-  });
 
-  xMin = Math.floor(xMin);
-  xMax = Math.floor(xMax);
-  yMin = Math.floor(yMin);
-  yMax = Math.floor(yMax);
-  zMin = Math.floor(zMin);
-  zMax = Math.floor(zMax);
+    if (is3D) {
+      zMin = Math.min(p[2] ?? zMin, zMin);
+      zMax = Math.max(p[2] ?? zMax, zMax);
+    }
+  }
 
   if (dimensions) {
-    // clip the min, max to the provided width, height and depth
-    const [width, height, depth] = dimensions;
+    xMin = Math.max(isWorld ? dimensions[0] + EPSILON : 0, xMin);
+    xMax = Math.min(
+      isWorld ? dimensions[0] - EPSILON : dimensions[0] - 1,
+      xMax
+    );
+    yMin = Math.max(isWorld ? dimensions[1] + EPSILON : 0, yMin);
+    yMax = Math.min(
+      isWorld ? dimensions[1] - EPSILON : dimensions[1] - 1,
+      yMax
+    );
+
+    if (is3D && dimensions.length === 3) {
+      zMin = Math.max(isWorld ? dimensions[2] + EPSILON : 0, zMin);
+      zMax = Math.min(
+        isWorld ? dimensions[2] - EPSILON : dimensions[2] - 1,
+        zMax
+      );
+    }
+  } else if (!isWorld) {
+    // still need to bound to 0 and Infinity if no dimensions are provided for ijk
     xMin = Math.max(0, xMin);
-    xMax = Math.min(width - 1, xMax);
+    xMax = Math.min(Infinity, xMax);
     yMin = Math.max(0, yMin);
-    yMax = Math.min(height - 1, yMax);
-    zMin = Math.max(0, zMin);
-    zMax = Math.min(depth - 1, zMax);
+    yMax = Math.min(Infinity, yMax);
+
+    if (is3D) {
+      zMin = Math.max(0, zMin);
+      zMax = Math.min(Infinity, zMax);
+    }
   }
 
-  return [
-    [xMin, xMax],
-    [yMin, yMax],
-    [zMin, zMax],
-  ];
+  return is3D
+    ? [
+        [xMin, xMax],
+        [yMin, yMax],
+        [zMin, zMax],
+      ]
+    : [[xMin, xMax], [yMin, yMax], null];
+}
+
+/**
+ * With a given vertices (points) coordinates in 2D or 3D in IJK, it calculates the minimum and maximum
+ * coordinate in each axis, and returns them. If clipBounds are provided it also
+ * clip the min, max to the provided width, height and depth
+ *
+ * @param points - shape corner points coordinates either in IJK (image coordinate)
+ * @param dimensions - bounds to clip the min, max
+ * @returns [[xMin,xMax],[yMin,yMax], [zMin,zMax]]
+ */
+export function getBoundingBoxAroundShapeIJK(
+  points: Types.Point2[] | Types.Point3[],
+  dimensions?: Types.Point2 | Types.Point3
+): BoundingBox {
+  return calculateBoundingBox(points, dimensions, false);
 }
 
-export default getBoundingBoxAroundShape;
+/**
+ * With a given vertices (points) coordinates in 2D or 3D in World Coordinates, it calculates the minimum and maximum
+ * coordinate in each axis, and returns them. If clipBounds are provided it also
+ * clip the min, max to the provided width, height and depth
+ *
+ * @param points - shape corner points coordinates either in IJK (image coordinate)
+ * @param clipBounds - bounds to clip the min, max
+ * @returns [[xMin,xMax],[yMin,yMax], [zMin,zMax]]
+ */
+export function getBoundingBoxAroundShapeWorld(
+  points: Types.Point2[] | Types.Point3[],
+  clipBounds?: Types.Point2 | Types.Point3
+): BoundingBox {
+  return calculateBoundingBox(points, clipBounds, true);
+}

package/src/utilities/boundingBox/index.ts

@@ -1,4 +1,13 @@
 import extend2DBoundingBoxInViewAxis from './extend2DBoundingBoxInViewAxis';
-import getBoundingBoxAroundShape from './getBoundingBoxAroundShape';
+import {
+  getBoundingBoxAroundShapeIJK,
+  getBoundingBoxAroundShapeWorld,
+} from './getBoundingBoxAroundShape';
 
-export { extend2DBoundingBoxInViewAxis, getBoundingBoxAroundShape };
+export {
+  extend2DBoundingBoxInViewAxis,
+  getBoundingBoxAroundShapeIJK,
+  getBoundingBoxAroundShapeWorld,
+  // backwards compatibility
+  getBoundingBoxAroundShapeIJK as getBoundingBoxAroundShape,
+};

package/src/utilities/cine/playClip.ts

@@ -11,7 +11,7 @@ import {
 
 import { Types } from '@cornerstonejs/core';
 import CINE_EVENTS from './events';
-import { addToolState, getToolState } from './state';
+import { addToolState, getToolState, getToolStateByViewportId } from './state';
 import { CINETypes } from '../../types';
 import scroll from '../scroll';
 
@@ -19,7 +19,6 @@ const { ViewportStatus } = Enums;
 const { triggerEvent } = csUtils;
 
 const debounced = true;
-const loop = true;
 const dynamicVolumesPlayingMap = new Map();
 
 /**
@@ -48,6 +47,10 @@ function playClip(
     );
   }
 
+  if (!playClipOptions) {
+    playClipOptions = {};
+  }
+
   // 4D Cine is enabled by default
   playClipOptions.dynamicCineEnabled =
     playClipOptions.dynamicCineEnabled ?? true;
@@ -83,7 +86,10 @@ function playClip(
     // Make sure the specified clip is not running before any property update.
     // If a 3D CINE was playing it passes isDynamicCinePlaying as FALSE to
     // prevent stopping a 4D CINE in case it is playing on another viewport.
-    _stopClip(element, isDynamicCinePlaying);
+    _stopClip(element, {
+      stopDynamicCine: !isDynamicCinePlaying,
+      viewportId: viewport.id,
+    });
   }
 
   playClipData.dynamicCineEnabled = playClipOptions.dynamicCineEnabled;
@@ -122,10 +128,13 @@ function playClip(
     const newStepIndexOutOfRange =
       newStepIndex < 0 || newStepIndex >= numScrollSteps;
 
-    if (!loop && newStepIndexOutOfRange) {
+    if (!playClipData.loop && newStepIndexOutOfRange) {
       // If a 3D CINE was playing it passes isDynamicCinePlaying as FALSE to
       // prevent stopping a 4D CINE in case it is playing on another viewport.
-      _stopClip(element, isDynamicCinePlaying);
+      _stopClip(element, {
+        stopDynamicCine: !isDynamicCinePlaying,
+        viewportId: viewport.id,
+      });
 
       const eventDetail = { element };
 
@@ -189,23 +198,40 @@ function playClip(
  * Stops an already playing clip.
  * @param element - HTML Element
  */
-function stopClip(element: HTMLDivElement): void {
-  _stopClip(element, true);
+function stopClip(element: HTMLDivElement, options = {} as any): void {
+  _stopClip(element, {
+    stopDynamicCine: true,
+    ...options,
+  });
 }
 
-function _stopClip(element: HTMLDivElement, stopDynamicCine: boolean): void {
+function _stopClip(
+  element: HTMLDivElement,
+  options = { stopDynamicCine: true, viewportId: undefined }
+) {
+  const { stopDynamicCine, viewportId } = options;
   const enabledElement = getEnabledElement(element);
+
+  let toolState;
   if (!enabledElement) {
-    return;
+    if (viewportId) {
+      toolState = getToolStateByViewportId(viewportId);
+    } else {
+      return;
+    }
+  } else {
+    const { viewport } = enabledElement;
+    toolState = getToolState(viewport.element);
   }
-  const { viewport } = enabledElement;
-  const cineToolData = getToolState(viewport.element);
 
-  if (cineToolData) {
-    _stopClipWithData(cineToolData);
+  if (toolState) {
+    _stopClipWithData(toolState);
   }
 
-  if (stopDynamicCine && viewport instanceof BaseVolumeViewport) {
+  if (
+    stopDynamicCine &&
+    enabledElement?.viewport instanceof BaseVolumeViewport
+  ) {
     _stopDynamicVolumeCine(element);
   }
 }

package/src/utilities/cine/state.ts

@@ -15,4 +15,10 @@ function getToolState(element: HTMLDivElement): CINETypes.ToolData | undefined {
   return state[viewportId];
 }
 
-export { addToolState, getToolState };
+function getToolStateByViewportId(
+  viewportId: string
+): CINETypes.ToolData | undefined {
+  return state[viewportId];
+}
+
+export { addToolState, getToolState, getToolStateByViewportId };

package/src/utilities/contourSegmentation/addContourSegmentationAnnotation.ts

@@ -0,0 +1,41 @@
+import { getSegmentation } from '../../stateManagement/segmentation/segmentationState';
+import { ContourSegmentationAnnotation } from '../../types';
+
+/**
+ * Adds a contour segmentation annotation to the specified segmentation.
+ * @param annotation - The contour segmentation annotation to add.
+ */
+export function addContourSegmentationAnnotation(
+  annotation: ContourSegmentationAnnotation
+) {
+  if (annotation.parentAnnotationUID) {
+    // Don't add it for parent annotations - this happens during interpolation
+    return;
+  }
+  if (!annotation.data.segmentation) {
+    throw new Error(
+      'addContourSegmentationAnnotation: annotation does not have a segmentation data'
+    );
+  }
+
+  const { segmentationId, segmentIndex } = annotation.data.segmentation;
+  const segmentation = getSegmentation(segmentationId);
+
+  if (!segmentation.representationData.CONTOUR) {
+    segmentation.representationData.CONTOUR = { annotationUIDsMap: new Map() };
+  }
+
+  const { annotationUIDsMap } = segmentation.representationData.CONTOUR;
+
+  let annotationsUIDsSet = annotationUIDsMap.get(segmentIndex);
+
+  if (!annotationsUIDsSet) {
+    annotationsUIDsSet = new Set();
+    annotationUIDsMap.set(segmentIndex, annotationsUIDsSet);
+  }
+
+  annotationUIDsMap.set(
+    segmentIndex,
+    annotationsUIDsSet.add(annotation.annotationUID)
+  );
+}