@cornerstonejs/core 1.71.3 → 1.71.5

package/src/RenderingEngine/VolumeViewport.ts

@@ -1,8 +1,6 @@
 import vtkPlane from '@kitware/vtk.js/Common/DataModel/Plane';
 import vtkVolume from '@kitware/vtk.js/Rendering/Core/Volume';
 
-import { vec3 } from 'gl-matrix';
-
 import cache from '../cache';
 import { MPR_CAMERA_VALUES, RENDERING_DEFAULTS } from '../constants';
 import { BlendModes, OrientationAxis, Events } from '../enums';
@@ -12,6 +10,9 @@ import type {
   IVolumeInput,
   OrientationVectors,
   Point3,
+  EventTypes,
+  ViewReference,
+  ViewReferenceSpecifier,
 } from '../types';
 import type { ViewportInput } from '../types/IViewport';
 import {
@@ -28,6 +29,7 @@ import setDefaultVolumeVOI from './helpers/setDefaultVolumeVOI';
 import { setTransferFunctionNodes } from '../utilities/transferFunctionUtils';
 import { ImageActor } from '../types/IActor';
 import getImageSliceDataForVolumeViewport from '../utilities/getImageSliceDataForVolumeViewport';
+import getVolumeViewportScrollInfo from '../utilities/getVolumeViewportScrollInfo';
 
 /**
  * An object representing a VolumeViewport. VolumeViewports are used to render
@@ -253,15 +255,19 @@ class VolumeViewport extends BaseVolumeViewport {
     resetPan = true,
     resetZoom = true,
     resetToCenter = true,
-    resetRotation = false
+    resetRotation = false,
+    supressEvents = false
   ): boolean {
+    const { orientation } = this.viewportProperties;
+    if (orientation) {
+      this.applyViewOrientation(orientation, false);
+    }
     super.resetCamera(resetPan, resetZoom, resetToCenter);
 
     this.resetVolumeViewportClippingRange();
 
     const activeCamera = this.getVtkActiveCamera();
     const viewPlaneNormal = <Point3>activeCamera.getViewPlaneNormal();
-    const viewUp = <Point3>activeCamera.getViewUp();
     const focalPoint = <Point3>activeCamera.getFocalPoint();
 
     // always add clipping planes for the volume viewport. If a use case
@@ -310,6 +316,16 @@ class VolumeViewport extends BaseVolumeViewport {
       });
     }
 
+    if (!supressEvents) {
+      const eventDetail: EventTypes.CameraResetEventDetail = {
+        viewportId: this.id,
+        camera: this.getCamera(),
+        renderingEngineId: this.renderingEngineId,
+        element: this.element,
+      };
+
+      triggerEvent(this.element, Events.CAMERA_RESET, eventDetail);
+    }
     return true;
   }
 
@@ -350,31 +366,44 @@ class VolumeViewport extends BaseVolumeViewport {
 
   /**
    * Uses the origin and focalPoint to calculate the slice index.
-   *
-   * @returns The slice index in the direction of the view
-   */
-  public getCurrentImageIdIndex = (volumeId?: string): number => {
-    const { viewPlaneNormal, focalPoint } = this.getCamera();
 
-    const imageData = this.getImageData(volumeId);
 
-    if (!imageData) {
-      return;
-    }
 
-    const { origin, direction, spacing } = imageData;
+   * Resets the slab thickness of the actors of the viewport to the default value.
+   */
+  public resetSlabThickness(): void {
+    const actorEntries = this.getActors();
 
-    const spacingInNormal = getSpacingInNormalDirection(
-      { direction, spacing },
-      viewPlaneNormal
-    );
-    const sub = vec3.create();
-    vec3.sub(sub, focalPoint, origin);
-    const distance = vec3.dot(sub, viewPlaneNormal);
+    actorEntries.forEach((actorEntry) => {
+      if (actorIsA(actorEntry, 'vtkVolume')) {
+        actorEntry.slabThickness = RENDERING_DEFAULTS.MINIMUM_SLAB_THICKNESS;
+      }
+    });
 
-    // divide by the spacing in the normal direction to get the
-    // number of steps, and subtract 1 to get the index
-    return Math.round(Math.abs(distance) / spacingInNormal);
+    const currentCamera = this.getCamera();
+    this.updateClippingPlanesForActors(currentCamera);
+    this.triggerCameraModifiedEventIfNecessary(currentCamera, currentCamera);
+    this.viewportProperties.slabThickness = undefined;
+  }
+
+  /**
+   * Uses the slice range information to compute the current image id index.
+   * Note that this may be offset from the origin location, or opposite in
+   * direction to the distance from the origin location, as the index is a
+   * complete index from minimum to maximum.
+   *
+   * @returns The slice index in the direction of the view
+   */
+  public getCurrentImageIdIndex = (
+    volumeId?: string,
+    useSlabThickness = true
+  ): number => {
+    const { currentStepIndex } = getVolumeViewportScrollInfo(
+      this,
+      volumeId || this.getVolumeId(),
+      useSlabThickness
+    );
+    return currentStepIndex;
   };
 
   /**
@@ -404,6 +433,26 @@ class VolumeViewport extends BaseVolumeViewport {
     return getClosestImageId(volume, focalPoint, viewPlaneNormal);
   };
 
+  /**
+   * Gets a view target, allowing comparison between view positions as well
+   * as restoring views later.
+   * Add the referenced image id.
+   */
+  public getViewReference(
+    viewRefSpecifier: ViewReferenceSpecifier = {}
+  ): ViewReference {
+    const viewRef = super.getViewReference(viewRefSpecifier);
+    if (!viewRef?.volumeId) {
+      return;
+    }
+    const volume = cache.getVolume(viewRef.volumeId);
+    viewRef.referencedImageId = getClosestImageId(
+      volume,
+      viewRef.cameraFocalPoint,
+      viewRef.viewPlaneNormal
+    );
+    return viewRef;
+  }
   /**
    * Reset the viewport properties to the default values
    *

package/src/RenderingEngine/VolumeViewport3D.ts

@@ -64,6 +64,10 @@ class VolumeViewport3D extends BaseVolumeViewport {
   resetProperties(volumeId?: string): void {
     return null;
   }
+
+  resetSlabThickness(): void {
+    return null;
+  }
 }
 
 export default VolumeViewport3D;

package/src/types/EventTypes.ts

@@ -31,6 +31,23 @@ type CameraModifiedEventDetail = {
   rotation?: number;
 };
 
+/**
+ * CAMERA_RESET Event's data
+ */
+
+type CameraResetEventDetail = {
+  /** Viewport HTML element in the DOM */
+  element: HTMLDivElement;
+  /** Viewport Unique ID in the renderingEngine */
+  viewportId: string;
+  /** Unique ID for the renderingEngine */
+  renderingEngineId: string;
+  /** Camera properties */
+  camera: ICamera;
+};
+
+type CameraResetEvent = CustomEventType<CameraResetEventDetail>;
+
 /**
  * VOI_MODIFIED Event's data
  */
@@ -461,4 +478,6 @@ export type {
   StackViewportNewStackEventDetail,
   StackViewportScrollEvent,
   StackViewportScrollEventDetail,
+  CameraResetEvent,
+  CameraResetEventDetail,
 };

package/src/types/IViewport.ts

@@ -15,7 +15,12 @@ import BoundsLPS from './BoundsLPS';
  * set of points.
  */
 export type ViewReferenceSpecifier = {
-  /** The slice index within the current viewport camera to get a reference for */
+  /**
+   * The slice index within the current viewport camera to get a reference for.
+   * Note that slice indexes are dependent on the particular view being shown
+   * and cannot be shared across different view types such as stacks and
+   * volumes, or two viewports showing different orientations or slab thicknesses.
+   */
   sliceIndex?: number | [number, number];
   /**
    * Specifies to get a view reference that refers to the generic frame of
@@ -47,12 +52,15 @@ export type ReferenceCompatibleOptions = {
   withNavigation?: boolean;
   /**
    * For a stack viewport, return true if this viewport could show the given
-   * view if it were converted into a volume viewport, while for a volume,
-   * could it be shown if the camera/orientation were changed.
-   * That is, is the specified view showing an image in the stack but with a
-   * different orientation than acquisition.
+   * view if it were converted into a volume viewport.  Has no affect on volume
+   * viewports.
    */
   asVolume?: boolean;
+  /**
+   * For volume viewports, return true if this viewport could show the given view
+   * if the orientation was changed.
+   */
+  withOrientation?: boolean;
   /**
    * Use this imageURI for testing - may or may not be the current one.
    * Should be a straight contains URI for the set of imageIds in any of
@@ -86,15 +94,39 @@ export type ViewReference = {
   referencedImageId?: string;
 
   /**
-   * The focal point of the camera in world space
+   * The focal point of the camera in world space.
+   * The focal point is used for to define the stack positioning, but not the
+   * zoom/pan (which is defined by the view presentation
+   * object.)
+   *
+   * Single point objects (probe etc) should use the probe point as the camera
+   * focal point as that allows omitting the view plane normal and showing the probe
+   * in any orientation.
    */
   cameraFocalPoint?: Point3;
   /**
-   * The normal for the current view
+   * The normal for the current view.  This defines the plane used to show the
+   * 2d annotation.  This should be omitted if the annotation is a point to
+   * allows for single-point annotations.
    */
   viewPlaneNormal?: Point3;
   /**
-   * The slice index or range for this view
+   * The view up - this is only used for resetting orientation
+   */
+  viewUp?: Point3;
+  /**
+   * The slice index or range for this view.
+   * <b>NOTE</b> The slice index is relative to the volume or stack of images.
+   * You cannot apply a slice index from one volume to another as they do NOT
+   * apply.   The referencedImageId should belong to the volume you are trying
+   * to apply to, the viewPlane normal should be identical, and then you can
+   * apply the sliceIndex.
+   *
+   * For stack viewports, the referencedImageId should occur at the given slice index.
+   *
+   * <b>Note 2</b>slice indices don't necessarily indicate anything positionally
+   * within the stack of images - subsequent slice indexes can be at opposite
+   * ends or can be co-incident but separate types of images.
    */
   sliceIndex?: number | [number, number];
 
@@ -292,11 +324,22 @@ interface IViewport {
   setPan(pan: Point2, storeAsInitialCamera?: boolean);
   /** sets the camera */
   setCamera(cameraInterface: ICamera, storeAsInitialCamera?: boolean): void;
+  /** Resets the camera */
+  resetCamera(
+    resetPan?: boolean,
+    resetZoom?: boolean,
+    resetToCenter?: boolean,
+    storeAsInitialCamera?: boolean
+  ): boolean;
   /** Gets the number of slices in the current camera orientation */
   getNumberOfSlices(): number;
   /** Gets the current slice in the current camera orientation */
   getCurrentImageIdIndex(): number;
-  /** Gets a referenced image url of some sort - could be a real image id, or could be a URL with parameters */
+  /**
+   * Gets a referenced image url of some sort - could be a real image id, or
+   * could be a URL with parameters. Regardless it refers to the currently displaying
+   * image as a string value.
+   */
   getReferenceId(viewRefSpecifier?: ViewReferenceSpecifier): string;
   /**
    * Gets a view target specifying WHAT a view is displaying,
@@ -343,20 +386,23 @@ interface IViewport {
    * @param viewPresSel - select which attributes to display.
    */
   getViewPresentation(viewPresSel?: ViewPresentationSelector): ViewPresentation;
+
   /**
-   * Selects both what a viewport is showing (which image/slice) as well as how it
-   * is being presented.  If only one or the other values is provided, the
-   * currently applied view for the other attribute is preserved, allowing for
-   * remember specific sets of attributes.
-   *
-   * @param viewRef - the basic positioning in terms of what image id/slice index/orientation to display
-   *        * The viewRef must be applicable to the current stack or volume, otherwise an exception will be thrown
-   * @param viewPres - the presentation information to apply to the current image (as chosen above)
+   * Navigates this viewport to the specified viewRef.
+   * Throws an exception if that isn't possible on this viewport.
+   * Returns immediately if viewRef isn't defined.
    */
-  setView(viewRef?: ViewReference, viewPres?: ViewPresentation);
+  setViewReference(viewRef: ViewReference);
+
+  /**
+   * Sets the presentation parameters from the specified viewPres object.
+   * Sets display area, zoom, pan, rotation, voi LUT
+   */
+  setViewPresentation(viewPres: ViewPresentation);
 
   /** whether the viewport has custom rendering */
   customRenderViewportToCanvas: () => unknown;
+
   _getCorners(bounds: Array<number>): Array<number>[];
   updateRenderingPipeline: () => void;
 }

package/src/types/IVolumeViewport.ts

@@ -137,8 +137,13 @@ export default interface IVolumeViewport extends IViewport {
     resetPan?: boolean,
     resetZoom?: boolean,
     resetToCenter?: boolean,
-    resetRotation?: boolean
+    resetRotation?: boolean,
+    supressEvents?: boolean
   ): boolean;
+  /**
+   * Reset the slab thickness for actors of the viewport.
+   */
+  resetSlabThickness(): void;
   /**
    * Sets the blendMode for actors of the viewport.
    */

package/src/types/displayArea.ts

@@ -1,14 +1,41 @@
 import InterpolationType from '../enums/InterpolationType';
 
+/**
+ * The display area type allows specifying or updating the image position and
+ * size based on the display area that it is shown in and based on the image
+ * size.
+ *
+ * Two types are currently defined, the default 'FIT', specifies scaling
+ * to fit the given image area.  For this type, the area  that is scaled to
+ * fit is the imageArea times the image size.  For example, an imageArea of
+ * `[0.5,2]` with a 512 square image will try to fit 0.5*512 = 256 pixels width wise,
+ * and 2*512 = 1024 height wise.
+ *
+ * The type 'SCALE' means to use a scale factor, such as 1.0, which means to make
+ * every image pixel fit one physical display pixel.
+ *
+ * Then, the image is positioned such that the image fractional position imagePoint
+ * is located at the canvas fractional point canvasPoint.  Using fractional
+ * points allows being independent of image size.
+ *
+ * Finally, the store as initial camera allows the zoom and pan values to be
+ * set to 1 and [0,0] respectively for the initially displayed position, as well
+ * as having the reset camera reset to the specified display area.
+ */
 type DisplayArea = {
   type?: 'SCALE' | 'FIT';
   scale?: number;
   interpolationType?: InterpolationType;
   imageArea?: [number, number]; // areaX, areaY
   imageCanvasPoint?: {
+    /** Use the fractional imagePoint as the target image point to position */
     imagePoint: [number, number]; // imageX, imageY
+    /** Pan the image such that the target imagePoint is located at the
+     * canvas point fraction of the canvas.
+     */
     canvasPoint?: [number, number]; // canvasX, canvasY
   };
+  /** Make this display area the default and reset/navigate will reapply this */
   storeAsInitialCamera?: boolean;
 };
 

package/src/utilities/index.ts

@@ -11,7 +11,7 @@ import getRuntimeId from './getRuntimeId';
 import imageIdToURI from './imageIdToURI';
 import calibratedPixelSpacingMetadataProvider from './calibratedPixelSpacingMetadataProvider';
 import clamp from './clamp';
-import isEqual from './isEqual';
+import { isEqual, isEqualAbs, isEqualNegative } from './isEqual';
 import isOpposite from './isOpposite';
 import createUint8SharedArray from './createUint8SharedArray';
 import createFloat32SharedArray from './createFloat32SharedArray';
@@ -66,6 +66,7 @@ import { generateVolumePropsFromImageIds } from './generateVolumePropsFromImageI
 import { convertStackToVolumeViewport } from './convertStackToVolumeViewport';
 import { convertVolumeToStackViewport } from './convertVolumeToStackViewport';
 import VoxelManager from './VoxelManager';
+import RLEVoxelMap from './RLEVoxelMap';
 import roundNumber, { roundToPrecision } from './roundNumber';
 import convertToGrayscale from './convertToGrayscale';
 import getViewportImageIds from './getViewportImageIds';
@@ -97,6 +98,8 @@ export {
   getMinMax,
   getRuntimeId,
   isEqual,
+  isEqualAbs,
+  isEqualNegative,
   isOpposite,
   createFloat32SharedArray,
   createUint8SharedArray,
@@ -151,9 +154,10 @@ export {
   isValidVolume,
   genericMetadataProvider,
   isVideoTransferSyntax,
+  generateVolumePropsFromImageIds,
   getBufferConfiguration,
   VoxelManager,
-  generateVolumePropsFromImageIds,
+  RLEVoxelMap,
   convertStackToVolumeViewport,
   convertVolumeToStackViewport,
   cacheUtils,

package/src/utilities/isEqual.ts

@@ -63,3 +63,30 @@ export default function isEqual<ValueType>(
 
   return false;
 }
+
+const negative = (v) =>
+  typeof v === 'number' ? -v : v?.map ? v.map(negative) : !v;
+
+const abs = (v) =>
+  typeof v === 'number' ? Math.abs(v) : v?.map ? v.map(abs) : v;
+
+/**
+ *  Compare negative values of both single numbers and vectors
+ */
+const isEqualNegative = <ValueType>(
+  v1: ValueType,
+  v2: ValueType,
+  tolerance = undefined
+) => isEqual(v1, negative(v2) as unknown as ValueType, tolerance);
+
+/**
+ * Compare absolute values for single numbers and vectors.
+ * Not recommended for large vectors as this creates a copy
+ */
+const isEqualAbs = <ValueType>(
+  v1: ValueType,
+  v2: ValueType,
+  tolerance = undefined
+) => isEqual(abs(v1), abs(v2) as unknown as ValueType, tolerance);
+
+export { isEqualNegative, isEqual, isEqualAbs };