@cornerstonejs/core 1.69.0 → 1.70.0

package/src/loaders/volumeLoader.ts

@@ -3,13 +3,14 @@ import '@kitware/vtk.js/Rendering/Profiles/Volume';
 import vtkImageData from '@kitware/vtk.js/Common/DataModel/ImageData';
 import type { vtkImageData as vtkImageDataType } from '@kitware/vtk.js/Common/DataModel/ImageData';
 import vtkDataArray from '@kitware/vtk.js/Common/Core/DataArray';
-import cloneDeep from 'lodash.clonedeep';
 
 import { ImageVolume } from '../cache/classes/ImageVolume';
 import cache from '../cache/cache';
 import Events from '../enums/Events';
 import eventTarget from '../eventTarget';
 import triggerEvent from '../utilities/triggerEvent';
+import cloneDeep from 'lodash.clonedeep';
+
 import {
   generateVolumePropsFromImageIds,
   getBufferConfiguration,

package/src/types/IViewport.ts

@@ -11,8 +11,8 @@ import BoundsLPS from './BoundsLPS';
 /**
  * Specifies what view to get a reference for.
  * This set of options allows a Viewport to return a reference for an image
- * not currently in view, such as for a different slice, or for a given set of
- * points.
+ * not currently in view, such as for a different slice, or containing a given
+ * set of points.
  */
 export type ViewReferenceSpecifier = {
   /** The slice index within the current viewport camera to get a reference for */
@@ -31,9 +31,12 @@ export type ViewReferenceSpecifier = {
 };
 
 /**
- * These are the options arguments to determine whether a view reference
- * is compatible with a viewport, that is, could be or is shown in a viewport.
- * That specifies whether a view could be shown in a given viewport or not.
+ * It is often important to decide if a given view can display a specific
+ * view reference.  For example, annotations need to know if they are
+ * shown on a view.  Some operations need to know if the view COULD show
+ * the given object if certain changes were made to the view.  This object
+ * allows specifying what changes are permitted in order to determine if the
+ * view could show the image.
  */
 export type ReferenceCompatibleOptions = {
   /**
@@ -61,9 +64,10 @@ export type ReferenceCompatibleOptions = {
 };
 
 /**
- * A view reference references the image/location of an image.  It
- * basically says would this viewport show this view, or can direct a viewport
- * to show a specific view.
+ * A view reference references the image/location of an image.  Typical use
+ * cases include remembering the current position of a viewport to allow returning
+ * to it later, as well as determining whether specific views should show annotations
+ * or other overlay information.
  */
 export type ViewReference = {
   /**
@@ -105,6 +109,82 @@ export type ViewReference = {
   bounds?: BoundsLPS;
 };
 
+/**
+ * A view presentation stores information about how the view is presented to the
+ * user, such as rotation, the displayed area, pan/zoom etc.  This is represented
+ * as values which are independent of the view type or size as much as possible,
+ * by normalizing the values to the type of view presented.  This allows
+ * remember or synchronizing values in a much wider variety of places than
+ * using the raw/underlying view data such as camera position.
+ */
+export type ViewPresentation = {
+  /**
+   * The slice thickness - in frames(true/default) it will be 1 for a frame distance of
+   * 1 pixel thickness, while for mm will be in mm distance.
+   */
+  slabThickness?: number;
+
+  /**
+   * The rotation of the view - this is related to cameraViewUp, but is relative
+   * to the viewNormal and the default viewUp for that viewNormal.
+   */
+  rotation?: number;
+
+  /**
+   * The display area being shown.  This is more consistent than applying a set
+   * of boundary areas.
+   */
+  displayArea?: DisplayArea;
+
+  /**
+   * The zoom value is a zoom factor relative either to fit to canvas or relative
+   * to the display area.
+   * The default true units are relative to the initial camera
+   * scale to fit is used to get units relative to the scale to fit camera.
+   */
+  zoom?: number;
+
+  /**
+   * The pan value is how far the pan has moved relative to the fit to canvas
+   * or relative to the display area initial position/sizing.
+   * true is the default units, which is relative to the initial canvas setting,
+   * in zoom relative units.
+   */
+  pan?: Point2;
+};
+
+/**
+ * A view presentation selector allows choosing what view attributes should be
+ * returned by a call to getViewPresentation.  This allows a shared selection
+ * object to be used to specify which presentation attributes are to be used.
+ *
+ * For example, a synchronizer might choose to use a presentation selector
+ * so that multiple viewports could specify to synchronizer, say slabThickness
+ * and windowLevel across one set, while a different synchronizer would choose
+ * to apply zoom and pan.
+ * Then, a resize operation might choose to synchronize display area, zoom and pan, but
+ * not window level or slab thickness.
+ * A store/remember state of viewport might choose to synchronize everything
+ * Individual tools might choose to use synchronization of the specific attribute
+ * which they are modifying (such as rotation) for history undo/redo, but use the
+ * same re-apply function to undo the remembered history.
+ *
+ * It is certainly possible to implement each of these with their own selectors
+ * which call the particular get/set functions, but that makes it more work to
+ * share particular sets for different uses.
+ */
+export type ViewPresentationSelector = {
+  slabThickness?: boolean;
+  // Camera relative parameters
+  rotation?: boolean;
+  displayArea?: boolean;
+  zoom?: boolean;
+  pan?: boolean;
+  // Transfer function relative parameters
+  windowLevel?: boolean;
+  paletteLut?: boolean;
+};
+
 /**
  * Viewport interface for cornerstone viewports
  */
@@ -210,8 +290,13 @@ interface IViewport {
   /** Gets a referenced image url of some sort - could be a real image id, or could be a URL with parameters */
   getReferenceId(viewRefSpecifier?: ViewReferenceSpecifier): string;
   /**
-   * Gets a view target, allowing comparison between view positions as well
-   * as restoring views later.
+   * Gets a view target specifying WHAT a view is displaying,
+   * allowing for checking if a given image is displayed or could be displayed
+   * in a given viewport.
+   * See getViewPresentation for HOW a view is displayed.
+   *
+   * @param viewRefSpecifier - choose an alternate view to be specified, typically
+   *      a different slice index in the same set of images.
    */
   getViewReference(viewRefSpecifier?: ViewReferenceSpecifier): ViewReference;
   /**
@@ -225,6 +310,41 @@ interface IViewport {
     viewRef: ViewReference,
     options?: ReferenceCompatibleOptions
   ): boolean;
+  /**
+   * Gets a view presentation information specifying HOW a viewport displays
+   * something, but not what is being displayed.
+   * See getViewReference to get information on WHAT is being displayed.
+   *
+   * This is intended to have information on how an image is presented to the user, without
+   * specifying what image s displayed.  All of this information is available
+   * externally, but this method combines the parts of this that are appropriate
+   * for remember or applying to other views, without necessarily needing to know
+   * what all the atributes are.  That differs from methods like getCamera which
+   * fetch exact view details that are not likely to be identical between viewports
+   * as they change sizes or apply to different images.
+   *
+   * Note that the results of this can be used on different viewports, for example,
+   * the pan values can be applied to a volume viewport showing a CT, and a
+   * stack viewport showing an ultrasound.
+   *
+   * The selector allows choosing which view presentation attributes to return.
+   * Some default values are available from `Viewport.CameraViewPresentation` and
+   * `Viewport.TransferViewPresentation`
+   *
+   * @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)
+   */
+  setView(viewRef?: ViewReference, viewPres?: ViewPresentation);
 
   /** whether the viewport has custom rendering */
   customRenderViewportToCanvas: () => unknown;

package/src/types/ViewportProperties.ts

@@ -5,7 +5,7 @@ import { ColormapPublic } from './Colormap';
 /**
  * Shared Viewport Properties between Stack and Volume Viewports
  */
-type ViewportProperties = {
+export type ViewportProperties = {
   /** voi range (upper, lower) for the viewport */
   voiRange?: VOIRange;
   /** VOILUTFunction type which is LINEAR or SAMPLED_SIGMOID */
@@ -19,5 +19,3 @@ type ViewportProperties = {
   /**Rotation of the camera */
   rotation?: number;
 };
-
-export type { ViewportProperties };

package/src/types/displayArea.ts

@@ -1,8 +1,13 @@
+import InterpolationType from '../enums/InterpolationType';
+
 type DisplayArea = {
+  type?: 'SCALE' | 'FIT';
+  scale?: number;
+  interpolationType?: InterpolationType;
   imageArea?: [number, number]; // areaX, areaY
   imageCanvasPoint?: {
     imagePoint: [number, number]; // imageX, imageY
-    canvasPoint: [number, number]; // canvasX, canvasY
+    canvasPoint?: [number, number]; // canvasX, canvasY
   };
   storeAsInitialCamera?: boolean;
 };

package/src/types/index.ts

@@ -19,6 +19,8 @@ import type {
   ViewReferenceSpecifier,
   ReferenceCompatibleOptions,
   ViewReference,
+  ViewPresentation,
+  ViewPresentationSelector,
 } from './IViewport';
 import type {
   VolumeActor,
@@ -161,6 +163,8 @@ export type {
   IStreamingVolumeProperties,
   IViewport,
   ViewReference,
+  ViewPresentation,
+  ViewPresentationSelector,
   ReferenceCompatibleOptions,
   ViewReferenceSpecifier,
   StackViewportProperties,

package/src/utilities/index.ts

@@ -78,6 +78,7 @@ import * as windowLevel from './windowLevel';
 import * as colormap from './colormap';
 import * as transferFunctionUtils from './transferFunctionUtils';
 import * as cacheUtils from './cacheUtils';
+import * as color from './color';
 
 export {
   eventListener,
@@ -160,4 +161,5 @@ export {
   getViewportImageIds,
   getRandomSampleFromArray,
   getVolumeId,
+  color,
 };

package/src/utilities/loadImageToCanvas.ts

@@ -1,4 +1,4 @@
-import { IImage } from '../types';
+import type { IImage, ViewportInputOptions } from '../types';
 
 import { loadAndCacheImage } from '../loaders/imageLoader';
 import * as metaData from '../metaData';
@@ -8,13 +8,22 @@ import renderToCanvasGPU from './renderToCanvasGPU';
 import renderToCanvasCPU from './renderToCanvasCPU';
 import { getConfiguration } from '../init';
 
-interface LoadImageOptions {
+export interface LoadImageOptions {
   canvas: HTMLCanvasElement;
   imageId: string;
   requestType?: RequestType;
   priority?: number;
   renderingEngineId?: string;
   useCPURendering?: boolean;
+  // Render a thumbnail in a 256x256 viewport
+  // Also set imageAspect to render thumbnail in an aspect ratio width viewport
+  thumbnail?: boolean;
+  // Sets the CSS width to the image aspect ratio
+  imageAspect?: boolean;
+  // Sets the canvas pixel size to the physical pixel size of the image area
+  physicalPixels?: boolean;
+  // Sets the viewport input options  Defaults to scale to fit 110%
+  viewportOptions?: ViewportInputOptions;
 }
 
 /**
@@ -35,6 +44,9 @@ interface LoadImageOptions {
  * the order of loading for the pool manager is interaction, thumbnail, prefetch
  * @param priority - The priority of the request within the request type (lower is higher priority)
  * @param useCPURendering - Force the use of the CPU rendering pipeline (default to false)
+ * @param thumbnail - Render a thumbnail image
+ * @param imageAspect - assign the width based on the aspect ratio of the image
+ * @param physicalPixels - set the width/height to the physical pixel size
  * @returns - A promise that resolves when the image has been rendered with the imageId
  */
 export default function loadImageToCanvas(
@@ -47,8 +59,13 @@ export default function loadImageToCanvas(
     priority = -5,
     renderingEngineId = '_thumbnails',
     useCPURendering = false,
+    thumbnail = false,
+    imageAspect = false,
+    physicalPixels = false,
+    viewportOptions,
   } = options;
 
+  const devicePixelRatio = window.devicePixelRatio || 1;
   const renderFn = useCPURendering ? renderToCanvasCPU : renderToCanvasGPU;
 
   return new Promise((resolve, reject) => {
@@ -57,7 +74,25 @@ export default function loadImageToCanvas(
 
       image.isPreScaled = image.isPreScaled || image.preScale?.scaled;
 
-      renderFn(canvas, image, modality, renderingEngineId).then(() => {
+      if (thumbnail) {
+        canvas.height = 256;
+        canvas.width = 256;
+      }
+      if (physicalPixels) {
+        canvas.width = canvas.offsetWidth * devicePixelRatio;
+        canvas.height = canvas.offsetHeight * devicePixelRatio;
+      }
+      if (imageAspect) {
+        canvas.width = (canvas.height * image.width) / image.height;
+      }
+
+      renderFn(
+        canvas,
+        image,
+        modality,
+        renderingEngineId,
+        viewportOptions
+      ).then(() => {
         resolve(imageId);
       });
     }

package/src/utilities/renderToCanvasCPU.ts

@@ -1,4 +1,8 @@
-import { IImage, CPUFallbackEnabledElement } from '../types';
+import {
+  IImage,
+  CPUFallbackEnabledElement,
+  ViewportInputOptions,
+} from '../types';
 
 import getDefaultViewport from '../RenderingEngine/helpers/cpuFallback/rendering/getDefaultViewport';
 import calculateTransform from '../RenderingEngine/helpers/cpuFallback/rendering/calculateTransform';
@@ -15,7 +19,8 @@ export default function renderToCanvasCPU(
   canvas: HTMLCanvasElement,
   image: IImage,
   modality?: string,
-  renderingEngineId?: string
+  _renderingEngineId?: string,
+  _viewportOptions?: ViewportInputOptions
 ): Promise<string> {
   const viewport = getDefaultViewport(canvas, image, modality);
 

package/src/utilities/renderToCanvasGPU.ts

@@ -1,7 +1,9 @@
-import getOrCreateCanvas from '../RenderingEngine/helpers/getOrCreateCanvas';
+import getOrCreateCanvas, {
+  EPSILON,
+} from '../RenderingEngine/helpers/getOrCreateCanvas';
 import { ViewportType, Events } from '../enums';
 import StackViewport from '../RenderingEngine/StackViewport';
-import { IImage } from '../types';
+import { IImage, ViewportInputOptions } from '../types';
 import { getRenderingEngine } from '../RenderingEngine/getRenderingEngine';
 import RenderingEngine from '../RenderingEngine';
 import isPTPrescaledWithSUV from './isPTPrescaledWithSUV';
@@ -29,7 +31,8 @@ export default function renderToCanvasGPU(
   canvas: HTMLCanvasElement,
   image: IImage,
   modality = undefined,
-  renderingEngineId = '_thumbnails'
+  renderingEngineId = '_thumbnails',
+  viewportOptions: ViewportInputOptions = { displayArea: { imageArea: [1, 1] } }
 ): Promise<string> {
   if (!canvas || !(canvas instanceof HTMLCanvasElement)) {
     throw new Error('canvas element is required');
@@ -39,21 +42,24 @@ export default function renderToCanvasGPU(
   const viewportId = `renderGPUViewport-${imageIdToPrint}`;
   const imageId = image.imageId;
   const element = document.createElement('div');
-  element.style.width = `${canvas.width}px`;
-  element.style.height = `${canvas.height}px`;
+  const devicePixelRatio = window.devicePixelRatio || 1;
+  const originalWidth = canvas.width;
+  const originalHeight = canvas.height;
+  // The canvas width/height are set by flooring the CSS size converted
+  // into physical pixels, but because these are float values, the conversion
+  // isn't exact, and using the exact value sometimes leads to an off by 1
+  // in the actual size, so adding EPSILON to the size resolves
+  // the problem.
+  element.style.width = `${originalWidth + EPSILON}px`;
+  element.style.height = `${originalHeight + EPSILON}px`;
   element.style.visibility = 'hidden';
   element.style.position = 'absolute';
 
   // Up-sampling the provided canvas to match the device pixel ratio
   // since we use device pixel ratio to determine the size of the canvas
   // inside the rendering engine.
-  const devicePixelRatio = window.devicePixelRatio || 1;
-  const originalWidth = canvas.width;
-  const originalHeight = canvas.height;
   canvas.width = originalWidth * devicePixelRatio;
   canvas.height = originalHeight * devicePixelRatio;
-  canvas.style.width = `${originalWidth}px`;
-  canvas.style.height = `${originalHeight}px`;
 
   document.body.appendChild(element);
 
@@ -61,6 +67,8 @@ export default function renderToCanvasGPU(
   const uniqueId = viewportId.split(':').join('-');
   element.setAttribute('viewport-id-for-remove', uniqueId);
 
+  // get the canvas element that is the child of the div
+  const temporaryCanvas = getOrCreateCanvas(element);
   const renderingEngine =
     (getRenderingEngine(renderingEngineId) as RenderingEngine) ||
     new RenderingEngine(renderingEngineId);
@@ -73,6 +81,7 @@ export default function renderToCanvasGPU(
       type: ViewportType.STACK,
       element,
       defaultOptions: {
+        ...viewportOptions,
         suppressEvents: true,
       },
     };
@@ -91,9 +100,6 @@ export default function renderToCanvasGPU(
         return;
       }
 
-      // get the canvas element that is the child of the div
-      const temporaryCanvas = getOrCreateCanvas(element);
-
       // Copy the temporary canvas to the given canvas
       const context = canvas.getContext('2d');
       context.drawImage(
@@ -135,7 +141,7 @@ export default function renderToCanvasGPU(
     element.addEventListener(Events.IMAGE_RENDERED, onImageRendered);
     viewport.renderImageObject(image);
 
-    // force a reset camera to center the image
+    // force a reset camera to center the image and undo the small scaling
     viewport.resetCamera();
 
     if (modality === 'PT' && !isPTPrescaledWithSUV(image)) {