@cornerstonejs/tools 1.31.0 → 1.32.1

package/src/tools/annotation/ProbeTool.ts

@@ -7,7 +7,6 @@ import {
   triggerEvent,
   eventTarget,
   utilities as csUtils,
-  utilities,
 } from '@cornerstonejs/core';
 import type { Types } from '@cornerstonejs/core';
 
@@ -24,6 +23,7 @@ import {
 import { state } from '../../store';
 import { Events } from '../../enums';
 import { getViewportIdsWithToolToRender } from '../../utilities/viewportFilters';
+import roundNumber from '../../utilities/roundNumber';
 import {
   resetElementCursor,
   hideElementCursor,
@@ -578,20 +578,33 @@ class ProbeTool extends AnnotationTool {
       index[1] = Math.round(index[1]);
       index[2] = Math.round(index[2]);
 
+      const samplesPerPixel =
+        scalarData.length / dimensions[2] / dimensions[1] / dimensions[0];
+
       if (csUtils.indexWithinDimensions(index, dimensions)) {
         this.isHandleOutsideImage = false;
-        const yMultiple = dimensions[0];
-        const zMultiple = dimensions[0] * dimensions[1];
+        const yMultiple = dimensions[0] * samplesPerPixel;
+        const zMultiple = dimensions[0] * dimensions[1] * samplesPerPixel;
 
+        const baseIndex =
+          index[2] * zMultiple +
+          index[1] * yMultiple +
+          index[0] * samplesPerPixel;
         const value =
-          scalarData[index[2] * zMultiple + index[1] * yMultiple + index[0]];
+          samplesPerPixel > 2
+            ? [
+                scalarData[baseIndex],
+                scalarData[baseIndex + 1],
+                scalarData[baseIndex + 2],
+              ]
+            : scalarData[baseIndex];
 
         // Index[2] for stackViewport is always 0, but for visualization
         // we reset it to be imageId index
         if (targetId.startsWith('imageId:')) {
           const imageId = targetId.split('imageId:')[1];
           const imageURI = csUtils.imageIdToURI(imageId);
-          const viewports = utilities.getViewportsWithImageURI(
+          const viewports = csUtils.getViewportsWithImageURI(
             imageURI,
             renderingEngineId
           );
@@ -651,7 +664,7 @@ function defaultGetTextLines(data, targetId): string[] {
 
   textLines.push(`(${index[0]}, ${index[1]}, ${index[2]})`);
 
-  textLines.push(`${value.toFixed(2)} ${modalityUnit}`);
+  textLines.push(`${roundNumber(value)} ${modalityUnit}`);
 
   return textLines;
 }

package/src/tools/annotation/VideoRedactionTool.ts

@@ -73,6 +73,15 @@ class VideoRedactionTool extends AnnotationTool {
 
     this.isDrawing = true;
 
+    const camera = viewport.getCamera();
+    const { viewPlaneNormal, viewUp } = camera;
+    const referencedImageId = this.getReferencedImageId(
+      viewport,
+      worldPos,
+      viewPlaneNormal,
+      viewUp
+    );
+
     const annotation = {
       metadata: {
         // We probably just want a different type of data here, hacking this
@@ -80,7 +89,7 @@ class VideoRedactionTool extends AnnotationTool {
         viewPlaneNormal: <Types.Point3>[0, 0, 1],
         viewUp: <Types.Point3>[0, 1, 0],
         FrameOfReferenceUID: viewport.getFrameOfReferenceUID(),
-        referencedImageId: viewport.getFrameOfReferenceUID(),
+        referencedImageId,
         toolName: this.getToolName(),
       },
       data: {

package/src/tools/base/AnnotationDisplayTool.ts

@@ -132,11 +132,10 @@ abstract class AnnotationDisplayTool extends BaseTool {
 
     let referencedImageId;
 
-    if (
-      viewport instanceof StackViewport ||
-      viewport instanceof VideoViewport
-    ) {
+    if (viewport instanceof StackViewport) {
       referencedImageId = targetId.split('imageId:')[1];
+    } else if (viewport instanceof VideoViewport) {
+      referencedImageId = targetId.split('videoId:')[1];
     } else {
       const volumeId = targetId.split('volumeId:')[1];
       const imageVolume = cache.getVolume(volumeId);

package/src/tools/base/AnnotationTool.ts

@@ -305,13 +305,10 @@ abstract class AnnotationTool extends AnnotationDisplayTool {
       const volumeId = targetId.split('volumeId:')[1];
       const volume = cache.getVolume(volumeId);
       return volume.scaling?.PT !== undefined;
-    } else if (viewport instanceof StackViewport) {
-      const scalingModule: Types.ScalingParameters | undefined =
-        imageId && metaData.get('scalingModule', imageId);
-      return typeof scalingModule?.suvbw === 'number';
-    } else {
-      throw new Error('Viewport is not a valid type');
     }
+    const scalingModule: Types.ScalingParameters | undefined =
+      imageId && metaData.get('scalingModule', imageId);
+    return typeof scalingModule?.suvbw === 'number';
   }
 
   /**

package/src/tools/base/BaseTool.ts

@@ -141,7 +141,10 @@ abstract class BaseTool implements IBaseTool {
 
   /**
    * Get the image that is displayed for the targetId in the cachedStats
-   * which can be either imageId:<imageId> or volumeId:<volumeId>
+   * which can be
+   * * imageId:<imageId>
+   * * volumeId:<volumeId>
+   * * videoId:<basePathForVideo>/frames/<frameSpecifier>
    *
    * @param targetId - annotation targetId stored in the cached stats
    * @param renderingEngine - The rendering engine
@@ -183,6 +186,19 @@ abstract class BaseTool implements IBaseTool {
         return;
       }
 
+      return viewports[0].getImageData();
+    } else if (targetId.startsWith('videoId:')) {
+      // Video id can be multi-valued for the frame information
+      const imageURI = utilities.imageIdToURI(targetId);
+      const viewports = utilities.getViewportsWithImageURI(
+        imageURI,
+        renderingEngine.id
+      );
+
+      if (!viewports || !viewports.length) {
+        return;
+      }
+
       return viewports[0].getImageData();
     } else {
       throw new Error(
@@ -207,7 +223,7 @@ abstract class BaseTool implements IBaseTool {
     } else if (viewport instanceof BaseVolumeViewport) {
       return `volumeId:${this.getTargetVolumeId(viewport)}`;
     } else if (viewport instanceof VideoViewport) {
-      return '';
+      return `videoId:${viewport.getCurrentImageId()}`;
     } else {
       throw new Error(
         'getTargetId: viewport must be a StackViewport or VolumeViewport'

package/src/tools/index.ts

@@ -14,7 +14,11 @@ import AdvancedMagnifyTool from './AdvancedMagnifyTool';
 import ReferenceLinesTool from './ReferenceLinesTool';
 import OverlayGridTool from './OverlayGridTool';
 import SegmentationIntersectionTool from './SegmentationIntersectionTool';
-//
+import ReferenceCursors from './ReferenceCursors';
+import ReferenceLines from './ReferenceLinesTool';
+import ScaleOverlayTool from './ScaleOverlayTool';
+
+// Annotation tools
 import BidirectionalTool from './annotation/BidirectionalTool';
 import LengthTool from './annotation/LengthTool';
 import ProbeTool from './annotation/ProbeTool';
@@ -26,9 +30,7 @@ import PlanarFreehandROITool from './annotation/PlanarFreehandROITool';
 import ArrowAnnotateTool from './annotation/ArrowAnnotateTool';
 import AngleTool from './annotation/AngleTool';
 import CobbAngleTool from './annotation/CobbAngleTool';
-import ReferenceCursors from './ReferenceCursors';
-import ReferenceLines from './ReferenceLinesTool';
-import ScaleOverlayTool from './ScaleOverlayTool';
+import KeyImageTool from './annotation/KeyImageTool';
 
 // Segmentation DisplayTool
 import SegmentationDisplayTool from './displayTools/SegmentationDisplayTool';
@@ -59,6 +61,7 @@ export {
   ZoomTool,
   VolumeRotateMouseWheelTool,
   MIPJumpToClickTool,
+  ReferenceCursors,
   // Annotation Tools
   CrosshairsTool,
   ReferenceLinesTool,
@@ -74,7 +77,7 @@ export {
   ArrowAnnotateTool,
   AngleTool,
   CobbAngleTool,
-  ReferenceCursors,
+  KeyImageTool,
   // Segmentations Display
   SegmentationDisplayTool,
   // Segmentations Tools

package/src/types/CalculatorTypes.ts

@@ -1,6 +1,6 @@
 type Statistics = {
   name: string;
-  value: number;
+  value: number | number[];
   unit: null | string;
 };
 

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/index.ts

@@ -20,6 +20,7 @@ import pointInSurroundingSphereCallback from './pointInSurroundingSphereCallback
 import scroll from './scroll';
 import roundNumber from './roundNumber';
 import { pointToString } from './pointToString';
+import annotationFrameRange from './annotationFrameRange';
 
 // name spaces
 import * as segmentation from './segmentation';
@@ -78,4 +79,5 @@ export {
   pointToString,
   polyDataUtils,
   voi,
+  annotationFrameRange,
 };

package/src/utilities/math/basic/BasicStatsCalculator.ts

@@ -2,11 +2,10 @@ import { Statistics } from '../../../types';
 import Calculator from './Calculator';
 
 export default class BasicStatsCalculator extends Calculator {
-  private static max = -Infinity;
-  private static currentMax = 0;
-  private static sum = 0;
-  private static sumSquares = 0;
-  private static squaredDiffSum = 0;
+  private static max = [-Infinity];
+  private static sum = [0];
+  private static sumSquares = [0];
+  private static squaredDiffSum = [0];
   private static count = 0;
 
   /**
@@ -15,16 +14,34 @@ export default class BasicStatsCalculator extends Calculator {
    * @param value of the point in the shape of the annotation
    */
   static statsCallback = ({ value: newValue }): void => {
-    if (newValue > this.max) {
-      this.max = newValue;
-      this.currentMax = newValue;
+    if (
+      Array.isArray(newValue) &&
+      newValue.length > 1 &&
+      this.max.length === 1
+    ) {
+      this.max.push(this.max[0], this.max[0]);
+      this.sum.push(this.sum[0], this.sum[0]);
+      this.sumSquares.push(this.sumSquares[0], this.sumSquares[0]);
+      this.squaredDiffSum.push(this.squaredDiffSum[0], this.squaredDiffSum[0]);
     }
 
+    const newArray = Array.isArray(newValue) ? newValue : [newValue];
     this.count += 1;
 
-    this.sum += newValue;
-    this.sumSquares += newValue ** 2;
-    this.squaredDiffSum += Math.pow(newValue - this.sum / this.count, 2);
+    this.max.forEach(
+      (it, idx) => (this.max[idx] = Math.max(it, newArray[idx]))
+    );
+    this.sum.map((it, idx) => (this.sum[idx] += newArray[idx]));
+    this.sumSquares.map(
+      (it, idx) => (this.sumSquares[idx] += newArray[idx] ** 2)
+    );
+    this.squaredDiffSum.map(
+      (it, idx) =>
+        (this.squaredDiffSum[idx] += Math.pow(
+          newArray[idx] - this.sum[idx] / this.count,
+          2
+        ))
+    );
   };
 
   /**
@@ -38,23 +55,34 @@ export default class BasicStatsCalculator extends Calculator {
    */
 
   static getStatistics = (): Statistics[] => {
-    const mean = this.sum / this.count;
-    const stdDev = Math.sqrt(this.squaredDiffSum / this.count);
-    const stdDevWithSumSquare = Math.sqrt(
-      this.sumSquares / this.count - mean ** 2
+    const mean = this.sum.map((sum) => sum / this.count);
+    const stdDev = this.squaredDiffSum.map((squaredDiffSum) =>
+      Math.sqrt(squaredDiffSum / this.count)
     );
+    const stdDevWithSumSquare = this.sumSquares.map((it, idx) =>
+      Math.sqrt(this.sumSquares[idx] / this.count - mean[idx] ** 2)
+    );
+    const currentMax = this.max;
 
-    this.max = -Infinity;
-    this.sum = 0;
-    this.sumSquares = 0;
-    this.squaredDiffSum = 0;
+    this.max = [-Infinity];
+    this.sum = [0];
+    this.sumSquares = [0];
+    this.squaredDiffSum = [0];
     this.count = 0;
 
     return [
-      { name: 'max', value: this.currentMax, unit: null },
-      { name: 'mean', value: mean, unit: null },
-      { name: 'stdDev', value: stdDev, unit: null },
-      { name: 'stdDevWithSumSquare', value: stdDevWithSumSquare, unit: null },
+      { name: 'max', value: singleArrayAsNumber(currentMax), unit: null },
+      { name: 'mean', value: singleArrayAsNumber(mean), unit: null },
+      { name: 'stdDev', value: singleArrayAsNumber(stdDev), unit: null },
+      {
+        name: 'stdDevWithSumSquare',
+        value: singleArrayAsNumber(stdDevWithSumSquare),
+        unit: null,
+      },
     ];
   };
 }
+
+function singleArrayAsNumber(val: number[]) {
+  return val.length === 1 ? val[0] : val;
+}

package/src/utilities/math/ellipse/pointInEllipse.ts

@@ -1,4 +1,5 @@
 import type { Types } from '@cornerstonejs/core';
+import { vec3 } from 'gl-matrix';
 
 type Ellipse = {
   center: Types.Point3;
@@ -15,7 +16,7 @@ type Ellipse = {
  */
 export default function pointInEllipse(
   ellipse: Ellipse,
-  pointLPS: Types.Point3
+  pointLPS: vec3
 ): boolean {
   const { center: circleCenterWorld, xRadius, yRadius, zRadius } = ellipse;
   const [x, y, z] = pointLPS;

package/src/utilities/math/sphere/pointInSphere.ts

@@ -16,16 +16,13 @@ type Sphere = {
  * @param pointLPS - the point to check in world coordinates
  * @returns boolean
  */
-export default function pointInSphere(
-  sphere: Sphere,
-  pointLPS: Types.Point3
-): boolean {
+export default function pointInSphere(sphere: Sphere, pointLPS: vec3): boolean {
   const { center, radius } = sphere;
 
   return (
-    (pointLPS[0] - center[0]) ** 2 +
-      (pointLPS[1] - center[1]) ** 2 +
-      (pointLPS[2] - center[2]) ** 2 <=
+    (pointLPS[0] - center[0]) * (pointLPS[0] - center[0]) +
+      (pointLPS[1] - center[1]) * (pointLPS[1] - center[1]) +
+      (pointLPS[2] - center[2]) * (pointLPS[2] - center[2]) <=
     radius ** 2
   );
 }

package/src/utilities/planar/filterAnnotationsForDisplay.ts

@@ -8,6 +8,9 @@ import {
 
 import filterAnnotationsWithinSlice from './filterAnnotationsWithinSlice';
 import { Annotations } from '../../types';
+import { annotationFrameRange } from '..';
+
+const baseUrlExtractor = /(videoId:|imageId:|volumeId:)([a-zA-Z]*:)/;
 
 /**
  * Given the viewport and the annotations, it filters the annotations array and only
@@ -43,7 +46,7 @@ export default function filterAnnotationsForDisplay(
 
       if (imageId === undefined) {
         // This annotation was not drawn on a non-coplanar reformat, and such does
-        // note have a referenced imageId.
+        // not have a referenced imageId.
         return false;
       }
 
@@ -54,8 +57,31 @@ export default function filterAnnotationsForDisplay(
   } else if (viewport instanceof VideoViewport) {
     const frameOfReferenceUID: string = viewport.getFrameOfReferenceUID();
 
-    return annotations.filter((toolData) => {
-      return toolData.metadata.FrameOfReferenceUID === frameOfReferenceUID;
+    return annotations.filter((annotation) => {
+      if (!annotation.isVisible) {
+        return false;
+      }
+      if (annotation.metadata.FrameOfReferenceUID !== frameOfReferenceUID) {
+        return false;
+      }
+      const testURI = annotation.metadata.referencedImageId.replace(
+        baseUrlExtractor,
+        ''
+      );
+
+      if (!viewport.hasImageURI(testURI)) {
+        return false;
+      }
+      const range = annotationFrameRange.getFrameRange(annotation);
+      const frameNumber = viewport.getFrameNumber();
+      if (Array.isArray(range)) {
+        return frameNumber >= range[0] && frameNumber <= range[1];
+      }
+      // Arbitrary 5 frames of slop on the video for matching single frame
+      // number to position - this allows the annotation to display  when
+      // the video element is not exactly the same timing as expected or when
+      // playing video back.
+      return Math.abs(frameNumber - range) <= 5;
     });
   } else if (viewport instanceof VolumeViewport) {
     const camera = viewport.getCamera();

package/src/utilities/pointInShapeCallback.ts

@@ -6,8 +6,8 @@ import BoundsIJK from '../types/BoundsIJK';
 export type PointInShape = {
   value: number;
   index: number;
-  pointIJK: Types.Point3;
-  pointLPS: Types.Point3;
+  pointIJK: vec3;
+  pointLPS: vec3;
 };
 
 export type PointInShapeCallback = ({
@@ -18,14 +18,11 @@ export type PointInShapeCallback = ({
 }: {
   value: number;
   index: number;
-  pointIJK: Types.Point3;
-  pointLPS: Types.Point3;
+  pointIJK: vec3;
+  pointLPS: vec3;
 }) => void;
 
-export type ShapeFnCriteria = (
-  pointIJK: Types.Point3,
-  pointLPS: Types.Point3
-) => boolean;
+export type ShapeFnCriteria = (pointIJK: vec3, pointLPS: vec3) => boolean;
 
 /**
  * For each point in the image (If boundsIJK is not provided, otherwise, for each
@@ -105,46 +102,57 @@ export default function pointInShapeCallback(
     scanAxisNormal[2] * scanAxisSpacing
   );
 
-  const yMultiple = dimensions[0];
-  const zMultiple = dimensions[0] * dimensions[1];
+  const xMultiple =
+    scalarData.length / dimensions[2] / dimensions[1] / dimensions[0];
+  const yMultiple = dimensions[0] * xMultiple;
+  const zMultiple = dimensions[1] * yMultiple;
 
   const pointsInShape: Array<PointInShape> = [];
+
+  const currentPos = vec3.clone(worldPosStart);
+
   for (let k = kMin; k <= kMax; k++) {
+    const startPosJ = vec3.clone(currentPos);
+
     for (let j = jMin; j <= jMax; j++) {
+      const startPosI = vec3.clone(currentPos);
+
       for (let i = iMin; i <= iMax; i++) {
         const pointIJK: Types.Point3 = [i, j, k];
-        const dI = i - iMin;
-        const dJ = j - jMin;
-        const dK = k - kMin;
-
-        const startWorld = worldPosStart;
-
-        const pointLPS: Types.Point3 = [
-          startWorld[0] +
-            dI * rowStep[0] +
-            dJ * columnStep[0] +
-            dK * scanAxisStep[0],
-          startWorld[1] +
-            dI * rowStep[1] +
-            dJ * columnStep[1] +
-            dK * scanAxisStep[1],
-          startWorld[2] +
-            dI * rowStep[2] +
-            dJ * columnStep[2] +
-            dK * scanAxisStep[2],
-        ];
-
-        if (pointInShapeFn(pointLPS, pointIJK)) {
-          const index = k * zMultiple + j * yMultiple + i;
-          const value = scalarData[index];
-
-          pointsInShape.push({ value, index, pointIJK, pointLPS });
-          if (callback !== null) {
-            callback({ value, index, pointIJK, pointLPS });
+
+        // The current world position (pointLPS) is now in currentPos
+        if (pointInShapeFn(currentPos as Types.Point3, currentPos)) {
+          const index = k * zMultiple + j * yMultiple + i * xMultiple;
+          let value;
+          if (xMultiple > 2) {
+            value = [
+              scalarData[index],
+              scalarData[index + 1],
+              scalarData[index + 2],
+            ];
+          } else {
+            value = scalarData[index];
+          }
+
+          pointsInShape.push({ value, index, pointIJK, pointLPS: currentPos });
+          if (callback) {
+            callback({ value, index, pointIJK, pointLPS: currentPos });
           }
         }
+
+        // Increment currentPos by rowStep for the next iteration
+        vec3.add(currentPos, currentPos, rowStep);
       }
+
+      // Reset currentPos to the start of the next J line and increment by columnStep
+      vec3.copy(currentPos, startPosI);
+      vec3.add(currentPos, currentPos, columnStep);
     }
+
+    // Reset currentPos to the start of the next K slice and increment by scanAxisStep
+    vec3.copy(currentPos, startPosJ);
+    vec3.add(currentPos, currentPos, scanAxisStep);
   }
+
   return pointsInShape;
 }

package/src/utilities/roundNumber.ts

@@ -10,7 +10,13 @@
  * @param value - to return a fixed measurement value from
  * @param precision - defining how many digits after 1..9 are desired
  */
-function roundNumber(value: string | number, precision = 2): string {
+function roundNumber(
+  value: string | number | (string | number)[],
+  precision = 2
+): string {
+  if (Array.isArray(value)) {
+    return value.map((v) => roundNumber(v, precision)).join(', ');
+  }
   if (value === undefined || value === null || value === '') {
     return 'NaN';
   }

package/src/utilities/viewport/isViewportPreScaled.ts

@@ -19,7 +19,7 @@ function isViewportPreScaled(
     const { preScale } = viewport.getImageData() || {};
     return !!preScale?.scaled;
   } else {
-    throw new Error('Viewport is not a valid type');
+    return false;
   }
 }