@cornerstonejs/tools 2.0.0-beta.2 → 2.0.0-beta.4

package/src/types/ToolSpecificAnnotationTypes.ts

@@ -78,6 +78,18 @@ export interface LengthAnnotation extends Annotation {
   };
 }
 
+export interface AdvancedMagnifyAnnotation extends Annotation {
+  data: {
+    zoomFactor: number;
+    sourceViewportId: string;
+    magnifyViewportId: string;
+    handles: {
+      points: Types.Point3[]; // [top, right, bottom, left]
+      activeHandleIndex: number | null;
+    };
+  };
+}
+
 export interface CircleROIAnnotation extends Annotation {
   data: {
     handles: {
@@ -261,6 +273,7 @@ export interface ArrowAnnotation extends Annotation {
     };
   };
 }
+
 export interface AngleAnnotation extends Annotation {
   data: {
     handles: {
@@ -286,6 +299,51 @@ export interface AngleAnnotation extends Annotation {
   };
 }
 
+export interface CobbAngleAnnotation extends Annotation {
+  data: {
+    handles: {
+      points: Types.Point3[];
+      activeHandleIndex: number | null;
+      textBox: {
+        hasMoved: boolean;
+        worldPosition: Types.Point3;
+        worldBoundingBox: {
+          topLeft: Types.Point3;
+          topRight: Types.Point3;
+          bottomLeft: Types.Point3;
+          bottomRight: Types.Point3;
+        };
+      };
+    };
+    label: string;
+    cachedStats: {
+      [targetId: string]: {
+        angle: number;
+        arc1Angle: number;
+        arc2Angle: number;
+        points: {
+          world: {
+            arc1Start: Types.Point3;
+            arc1End: Types.Point3;
+            arc2Start: Types.Point3;
+            arc2End: Types.Point3;
+            arc1Angle: number;
+            arc2Angle: number;
+          };
+          canvas: {
+            arc1Start: Types.Point2;
+            arc1End: Types.Point2;
+            arc2Start: Types.Point2;
+            arc2End: Types.Point2;
+            arc1Angle: number;
+            arc2Angle: number;
+          };
+        };
+      };
+    };
+  };
+}
+
 export interface ReferenceCursor extends Annotation {
   data: {
     handles: {

package/src/types/index.ts

@@ -21,6 +21,7 @@ import type * as AnnotationStyle from './AnnotationStyle';
 import type ToolHandle from './ToolHandle';
 import type { AnnotationHandle, TextBoxHandle } from './ToolHandle';
 import type InteractionTypes from './InteractionTypes';
+import type ToolAction from './ToolAction';
 import type {
   ToolProps,
   PublicToolProps,
@@ -84,6 +85,7 @@ export type {
   SetToolBindingsType,
   ToolOptionsType,
   InteractionTypes,
+  ToolAction,
   //
   IToolGroup,
   IToolClassReference,

package/src/utilities/getModalityUnit.ts

@@ -28,8 +28,14 @@ function _handlePTModality(imageId: string, options: ModalityUnitOptions) {
     return 'SUV';
   }
 
-  const petSeriesModule = metaData.get('petSeriesModule', imageId);
-  return petSeriesModule?.units || 'unitless';
+  const generalSeriesModule = metaData.get('generalSeriesModule', imageId);
+
+  // it might be possible that the referenceImageId is not the one
+  // that is being displayed. So we need to get the modality from imageId again
+  if (generalSeriesModule?.modality === 'PT') {
+    const petSeriesModule = metaData.get('petSeriesModule', imageId);
+    return petSeriesModule?.units || 'unitless';
+  }
 }
 
 export { getModalityUnit, ModalityUnitOptions };

package/src/utilities/index.ts

@@ -29,7 +29,7 @@ import * as cine from './cine';
 import * as boundingBox from './boundingBox';
 import * as planarFreehandROITool from './planarFreehandROITool';
 import * as rectangleROITool from './rectangleROITool';
-import * as stackPrefetch from './stackPrefetch';
+import { stackPrefetch, stackContextPrefetch } from './stackPrefetch';
 import * as viewport from './viewport';
 import * as touch from './touch';
 import * as dynamicVolume from './dynamicVolume';
@@ -65,6 +65,7 @@ export {
   rectangleROITool,
   planarFreehandROITool,
   stackPrefetch,
+  stackContextPrefetch,
   scroll,
   roundNumber,
 };

package/src/utilities/math/angle/angleBetweenLines.ts

@@ -1,17 +1,14 @@
 import type { Types } from '@cornerstonejs/core';
-import { vec3 } from 'gl-matrix';
+import { vec2, vec3 } from 'gl-matrix';
 
-type Line = [Types.Point3, Types.Point3];
+type Line2D = [Types.Point2, Types.Point2];
+type Line3D = [Types.Point3, Types.Point3];
+type Line = Line2D | Line3D;
 
 /**
- * It returns the angle between two lines in degrees.
- * The angle measured is that between the vectors
- * line1[1]->line1[0] AND line2[0]->line2[1].
- * @param line1 - Line = [p1, p2]
- * @param line2 - Line = [p3, p4]
- * @returns The angle between two lines in degrees.
+ * Calculates the angle between two 3D lines.
  */
-export default function angleBetweenLines(line1: Line, line2: Line): number {
+function angleBetween3DLines(line1: Line3D, line2: Line3D): number {
   const [p1, p2] = line1;
   const [p3, p4] = line2;
 
@@ -29,3 +26,36 @@ export default function angleBetweenLines(line1: Line, line2: Line): number {
 
   return (radian * 180) / Math.PI;
 }
+
+/**
+ * Calculates the angle between two 2D lines.
+ */
+function angleBetween2DLines(line1: Line2D, line2: Line2D): number {
+  const [p1, p2] = line1;
+  const [p3, p4] = line2;
+
+  const v1 = vec2.sub(vec2.create(), p2, p1);
+  const v2 = vec2.sub(vec2.create(), p3, p4);
+
+  const dot = vec2.dot(v1, v2);
+  const v1Length = vec2.length(v1);
+  const v2Length = vec2.length(v2);
+
+  const cos = dot / (v1Length * v2Length);
+  return Math.acos(cos) * (180 / Math.PI);
+}
+
+/**
+ * Returns the angle between two lines in degrees.
+ * The angle measured is that between the vectors
+ * line1[1]->line1[0] AND line2[0]->line2[1].
+ * @param line1 - Line = [p1, p2]
+ * @param line2 - Line = [p3, p4]
+ * @returns The angle between two lines in degrees.
+ */
+export default function angleBetweenLines(line1: Line, line2: Line): number {
+  const is3D = line1[0].length === 3;
+  return is3D
+    ? angleBetween3DLines(line1 as Line3D, line2 as Line3D)
+    : angleBetween2DLines(line1 as Line2D, line2 as Line2D);
+}

package/src/utilities/segmentation/createLabelmapVolumeForViewport.ts

@@ -1,4 +1,3 @@
-import { _cloneDeep } from 'lodash.clonedeep';
 import {
   getEnabledElementByIds,
   volumeLoader,
@@ -23,16 +22,16 @@ export default async function createLabelmapVolumeForViewport(input: {
   renderingEngineId: string;
   segmentationId?: string;
   options?: {
-    volumeId?: string;
-    scalarData?: Float32Array | Uint8Array | Uint16Array | Int16Array;
-    targetBuffer?: {
+    volumeId: string;
+    scalarData: Float32Array | Uint8Array | Uint16Array | Int16Array;
+    targetBuffer: {
       type: 'Float32Array' | 'Uint8Array' | 'Uint16Array' | 'Int8Array';
     };
-    metadata?: any;
-    dimensions?: Types.Point3;
-    spacing?: Types.Point3;
-    origin?: Types.Point3;
-    direction?: Float32Array;
+    metadata: Types.Metadata;
+    dimensions: Types.Point3;
+    spacing: Types.Point3;
+    origin: Types.Point3;
+    direction: Types.Mat3;
   };
 }): Promise<string> {
   const { viewportId, renderingEngineId, options } = input;
@@ -60,7 +59,7 @@ export default async function createLabelmapVolumeForViewport(input: {
   if (options) {
     // create a new labelmap with its own properties
     // This allows creation of a higher resolution labelmap vs reference volume
-    const properties = _cloneDeep(options);
+    const properties = structuredClone(options);
     await volumeLoader.createLocalVolume(properties, segmentationId);
   } else {
     // create a labelmap from a reference volume

package/src/utilities/stackPrefetch/index.ts

@@ -1,8 +1,4 @@
-import {
-  enable,
-  disable,
-  setConfiguration,
-  getConfiguration,
-} from './stackPrefetch';
+import stackPrefetch from './stackPrefetch';
+import stackContextPrefetch from './stackContextPrefetch';
 
-export { enable, disable, setConfiguration, getConfiguration };
+export { stackPrefetch, stackContextPrefetch };

package/src/utilities/stackPrefetch/stackContextPrefetch.ts

@@ -0,0 +1,380 @@
+import {
+  imageLoader,
+  Enums,
+  eventTarget,
+  imageLoadPoolManager,
+  cache,
+  getConfiguration as getCoreConfiguration,
+} from '@cornerstonejs/core';
+import { addToolState, getToolState } from './state';
+import {
+  getStackData,
+  requestType,
+  priority,
+  clearFromImageIds,
+  getPromiseRemovedHandler,
+} from './stackPrefetchUtils';
+import roundNumber from '../roundNumber';
+
+let configuration = {
+  maxImagesToPrefetch: Infinity,
+  // Fetch up to 2 image before and after
+  minBefore: 2,
+  maxAfter: 2,
+  // Increment the cache size by 10 images
+  directionExtraImages: 10,
+  preserveExistingPool: false,
+};
+
+let resetPrefetchTimeout;
+// Starting the prefetch quickly isn't an issue as the main image is already being
+// loaded, so a 5 ms prefetch delay is fine
+const resetPrefetchDelay = 5;
+
+/**
+ * Call this to enable stack context sensitive prefetch.  Should be called
+ * before stack data is set in order to start prefetch after load first image.
+ * This will add a STACK_NEW_IMAGE to detect when a new image is displayed, and then
+ * update the prefetch stack.  The context sensitive prefetch reacts to the
+ * initial display, or significant moves, the already loaded images, the
+ * cache size and the direction of navigation.  The behaviour is:
+ *
+ * 1. On navigating to a new image initially, or one that is at a different position:
+ *  * Fetch the next/previous 2 images
+ * 2. If the user is navigating forward/backward by less than 5 images, then
+ *  * Prefetch additional images in the direction of navigation, up to 100
+ * 3. If all the images in a given prefetch have completed, then:
+ *  * Use the last prefetched image size as an image size for the stack
+ *  * Fetch up to 1/4 of the cache size images near the current image
+ *
+ * This is designed to:
+ *   * Get nearby images immediately so that they are available for navigation
+ *     * Under the assumption that users might click and view an image, then
+ *       navigate to next/previous image to see the exact image they want
+ *   * Not interfere with loading other viewports if they are still loading
+ *     * Load priority is prefetch, and minimal images are requested initially
+ *   * Load an entire series if it will fit in memory
+ *     * Allows navigating to other parts of the series and display images immediately
+ *   * Have images available for CINE/navigation in one direction even when
+ *     there is more image data than will fit in memory.
+ *     * Up to 100 images in the direction of travel will be prefetched
+ *
+ * @param element - to prefetch on
+ */
+const enable = (element): void => {
+  const stack = getStackData(element);
+
+  if (!stack || !stack.imageIds || stack.imageIds.length === 0) {
+    console.warn('CornerstoneTools.stackPrefetch: No images in stack.');
+    return;
+  }
+
+  updateToolState(element);
+
+  prefetch(element);
+
+  element.removeEventListener(Enums.Events.STACK_NEW_IMAGE, onImageUpdated);
+  element.addEventListener(Enums.Events.STACK_NEW_IMAGE, onImageUpdated);
+
+  const promiseRemovedHandler = getPromiseRemovedHandler(element);
+
+  eventTarget.removeEventListener(
+    Enums.Events.IMAGE_CACHE_IMAGE_REMOVED,
+    promiseRemovedHandler
+  );
+  eventTarget.addEventListener(
+    Enums.Events.IMAGE_CACHE_IMAGE_REMOVED,
+    promiseRemovedHandler
+  );
+};
+
+function prefetch(element) {
+  const stack = getStackData(element);
+  if (!stack?.imageIds?.length) {
+    console.warn('CornerstoneTools.stackPrefetch: No images in stack.');
+    return;
+  }
+
+  // Get the stackPrefetch tool data
+  const stackPrefetchData = getToolState(element);
+
+  if (!stackPrefetchData) {
+    return;
+  }
+
+  const stackPrefetch = stackPrefetchData || {};
+
+  // If all the requests are complete, disable the stackPrefetch tool
+  stackPrefetch.enabled &&= stackPrefetch.indicesToRequest?.length;
+
+  // Make sure the tool is still enabled
+  if (stackPrefetch.enabled === false) {
+    return;
+  }
+
+  // Remove an imageIdIndex from the list of indices to request
+  // This fires when the individual image loading deferred is resolved
+  function removeFromList(imageIdIndex) {
+    const index = stackPrefetch.indicesToRequest.indexOf(imageIdIndex);
+
+    if (index > -1) {
+      // Don't remove last element if imageIdIndex not found
+      stackPrefetch.indicesToRequest.splice(index, 1);
+    }
+  }
+
+  // Remove all already cached images from the
+  // IndicesToRequest array.
+  const indicesToRequestCopy = stackPrefetch.indicesToRequest.slice();
+  const { currentImageIdIndex } = stack;
+
+  indicesToRequestCopy.forEach((imageIdIndex) => {
+    const imageId = stack.imageIds[imageIdIndex];
+
+    if (!imageId) {
+      return;
+    }
+
+    const distance = Math.abs(currentImageIdIndex - imageIdIndex);
+    // For nearby objects, ensure the last accessed time is updated
+    // by using getImageLoadObject.
+    // For more distant objects, just check if available, but dont
+    // change the access time.
+    // This allows throwing data that hasn't been accessed and is not
+    // nearby.
+    const imageCached =
+      distance < 6
+        ? cache.getImageLoadObject(imageId)
+        : cache.isLoaded(imageId);
+
+    if (imageCached) {
+      // Already in cache
+      removeFromList(imageIdIndex);
+    }
+  });
+
+  // Stop here if there are no images left to request
+  // After those in the cache have been removed
+  if (!stackPrefetch.indicesToRequest.length) {
+    return;
+  }
+
+  // Clear the requestPool of prefetch requests, if needed.
+  if (!configuration.preserveExistingPool) {
+    imageLoadPoolManager.filterRequests(clearFromImageIds(stack));
+  }
+
+  function doneCallback(imageId) {
+    const imageIdIndex = stack.imageIds.indexOf(imageId);
+
+    removeFromList(imageIdIndex);
+    const image = cache.getCachedImageBasedOnImageURI(imageId);
+    const { stats } = stackPrefetch;
+    const decodeTimeInMS = image?.image?.decodeTimeInMS || 0;
+    if (decodeTimeInMS) {
+      stats.imageIds.set(imageId, decodeTimeInMS);
+      stats.decodeTimeInMS += decodeTimeInMS;
+      const loadTimeInMS = image?.image?.loadTimeInMS || 0;
+      stats.loadTimeInMS += loadTimeInMS;
+    }
+
+    if (!stackPrefetch.indicesToRequest.length) {
+      if (image?.sizeInBytes) {
+        const { sizeInBytes } = image;
+        const usage = cache.getMaxCacheSize() / 4 / sizeInBytes;
+        if (!stackPrefetch.cacheFill) {
+          stats.initialTime = Date.now() - stats.start;
+          stats.initialSize = stats.imageIds.size;
+          updateToolState(element, usage);
+          prefetch(element);
+        } else if (stats.imageIds.size) {
+          stats.fillTime = Date.now() - stats.start;
+          const { size } = stats.imageIds;
+          stats.fillSize = size;
+          console.log(
+            'Done cache fill',
+            stats.fillTime,
+            'ms',
+            size,
+            'items',
+            'average total time',
+            roundNumber(stats.fillTime / size),
+            'ms',
+            'average load',
+            roundNumber(stats.loadTimeInMS / size),
+            'ms',
+            'average decode',
+            roundNumber(stats.decodeTimeInMS / size),
+            'ms'
+          );
+        }
+      }
+    }
+  }
+
+  const requestFn = (imageId, options) =>
+    imageLoader
+      .loadAndCacheImage(imageId, options)
+      .then(() => doneCallback(imageId));
+
+  const { useNorm16Texture } = getCoreConfiguration().rendering;
+
+  indicesToRequestCopy.forEach((imageIdIndex) => {
+    const imageId = stack.imageIds[imageIdIndex];
+    // IMPORTANT: Request type should be passed if not the 'interaction'
+    // highest priority will be used for the request type in the imageRetrievalPool
+    const options = {
+      targetBuffer: {
+        type: useNorm16Texture ? undefined : 'Float32Array',
+      },
+      preScale: {
+        enabled: true,
+      },
+      requestType,
+    };
+
+    imageLoadPoolManager.addRequest(
+      requestFn.bind(null, imageId, options),
+      requestType,
+      // Additional details
+      {
+        imageId,
+      },
+      priority
+      // addToBeginning
+    );
+  });
+}
+
+function onImageUpdated(e) {
+  // Start prefetching again (after a delay)
+  // When the user has scrolled to a new image
+  clearTimeout(resetPrefetchTimeout);
+  resetPrefetchTimeout = setTimeout(function () {
+    const element = e.target;
+
+    // If playClip is enabled and the user loads a different series in the viewport
+    // An exception will be thrown because the element will not be enabled anymore
+    try {
+      updateToolState(element);
+      prefetch(element);
+    } catch (error) {
+      return;
+    }
+  }, resetPrefetchDelay);
+}
+
+// Not a full signum, but good enough for direction.
+const signum = (x) => (x < 0 ? -1 : 1);
+
+const updateToolState = (element, usage?: number) => {
+  const stack = getStackData(element);
+  if (!stack || !stack.imageIds || stack.imageIds.length === 0) {
+    console.warn('CornerstoneTools.stackPrefetch: No images in stack.');
+    return;
+  }
+
+  const { currentImageIdIndex } = stack;
+  let { maxAfter = 2, minBefore = 2 } = configuration;
+  const { directionExtraImages = 10 } = configuration;
+  // Use the currentImageIdIndex from the stack as the initialImageIdIndex
+  const stackPrefetchData = getToolState(element) || {
+    indicesToRequest: [],
+    currentImageIdIndex,
+    stackCount: 0,
+    enabled: true,
+    direction: 1,
+    stats: {
+      start: Date.now(),
+      imageIds: new Map(),
+      decodeTimeInMS: 0,
+      loadTimeInMS: 0,
+      totalBytes: 0,
+    },
+  };
+  const delta = currentImageIdIndex - stackPrefetchData.currentImageIdIndex;
+  stackPrefetchData.direction = signum(delta);
+  stackPrefetchData.currentImageIdIndex = currentImageIdIndex;
+  stackPrefetchData.enabled = true;
+
+  if (stackPrefetchData.stackCount < 100) {
+    stackPrefetchData.stackCount += directionExtraImages;
+  }
+
+  if (Math.abs(delta) > maxAfter || !delta) {
+    // Not incrementing by 1, so stop increasing the data size
+    // TODO - consider reversing the CINE playback
+    stackPrefetchData.stackCount = 0;
+    if (usage) {
+      // The usage of the cache that this stack can use
+      const positionFraction = currentImageIdIndex / stack.imageIds.length;
+      minBefore = Math.ceil(usage * positionFraction);
+      maxAfter = Math.ceil(usage * (1 - positionFraction));
+      stackPrefetchData.cacheFill = true;
+    } else {
+      stackPrefetchData.cacheFill = false;
+    }
+  } else if (delta < 0) {
+    minBefore += stackPrefetchData.stackCount;
+    maxAfter = 0;
+  } else {
+    maxAfter += stackPrefetchData.stackCount;
+    minBefore = 0;
+  }
+
+  const minIndex = Math.max(0, currentImageIdIndex - minBefore);
+
+  const maxIndex = Math.min(
+    stack.imageIds.length - 1,
+    currentImageIdIndex + maxAfter
+  );
+
+  // Order these correctly initially
+  const indicesToRequest = [];
+  for (let i = currentImageIdIndex + 1; i <= maxIndex; i++) {
+    indicesToRequest.push(i);
+  }
+  for (let i = currentImageIdIndex - 1; i >= minIndex; i--) {
+    indicesToRequest.push(i);
+  }
+  stackPrefetchData.indicesToRequest = indicesToRequest;
+
+  addToolState(element, stackPrefetchData);
+};
+
+function disable(element) {
+  clearTimeout(resetPrefetchTimeout);
+  element.removeEventListener(Enums.Events.STACK_NEW_IMAGE, onImageUpdated);
+
+  const promiseRemovedHandler = getPromiseRemovedHandler(element);
+
+  eventTarget.removeEventListener(
+    Enums.Events.IMAGE_CACHE_IMAGE_REMOVED,
+    promiseRemovedHandler
+  );
+
+  const stackPrefetchData = getToolState(element);
+  // If there is actually something to disable, disable it
+
+  if (stackPrefetchData && stackPrefetchData.data.length) {
+    stackPrefetchData.enabled = false;
+    // Don't worry about clearing the requests - there aren't that many too be bothersome
+  }
+}
+
+function getConfiguration() {
+  return configuration;
+}
+
+function setConfiguration(config) {
+  configuration = config;
+}
+
+const stackContextPrefetch = {
+  enable,
+  disable,
+  getConfiguration,
+  setConfiguration,
+};
+
+export default stackContextPrefetch;