@cornerstonejs/core 1.71.4 → 1.71.6

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/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 };