@cornerstonejs/core 2.0.0-beta.6 → 2.0.0-beta.7

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

package/src/utilities/isValidVolume.ts

@@ -0,0 +1,59 @@
+import { metaData } from '..';
+import isEqual from './isEqual';
+
+/**
+ * Checks if the given imageIds form a valid volume. A volume is considered valid if all imageIds
+ * have the same series instance UID, modality, columns, rows, image orientation patient, and pixel
+ * spacing.
+ *
+ * @param imageIds - The imageIds to check.
+ * @returns true if the imageIds form a valid volume, false otherwise.
+ */
+function isValidVolume(imageIds: string[]): boolean {
+  const imageId0 = imageIds[0];
+
+  const { modality, seriesInstanceUID } = metaData.get(
+    'generalSeriesModule',
+    imageId0
+  );
+
+  const {
+    imageOrientationPatient,
+    pixelSpacing,
+    frameOfReferenceUID,
+    columns,
+    rows,
+  } = metaData.get('imagePlaneModule', imageId0);
+
+  const baseMetadata = {
+    modality,
+    imageOrientationPatient,
+    pixelSpacing,
+    frameOfReferenceUID,
+    columns,
+    rows,
+    seriesInstanceUID,
+  };
+
+  const validVolume = imageIds.every((imageId) => {
+    const { modality, seriesInstanceUID } = metaData.get(
+      'generalSeriesModule',
+      imageId
+    );
+    const { imageOrientationPatient, pixelSpacing, columns, rows } =
+      metaData.get('imagePlaneModule', imageId);
+
+    return (
+      seriesInstanceUID === baseMetadata.seriesInstanceUID &&
+      modality === baseMetadata.modality &&
+      columns === baseMetadata.columns &&
+      rows === baseMetadata.rows &&
+      isEqual(imageOrientationPatient, baseMetadata.imageOrientationPatient) &&
+      isEqual(pixelSpacing, baseMetadata.pixelSpacing)
+    );
+  });
+
+  return validVolume;
+}
+
+export { isValidVolume };

package/src/utilities/isVideoTransferSyntax.ts

@@ -0,0 +1,26 @@
+export const videoUIDs = new Set<string>([
+  '1.2.840.10008.1.2.4.100',
+  '1.2.840.10008.1.2.4.100.1',
+  '1.2.840.10008.1.2.4.101',
+  '1.2.840.10008.1.2.4.101.1',
+  '1.2.840.10008.1.2.4.102',
+  '1.2.840.10008.1.2.4.102.1',
+  '1.2.840.10008.1.2.4.103',
+  '1.2.840.10008.1.2.4.103.1',
+  '1.2.840.10008.1.2.4.104',
+  '1.2.840.10008.1.2.4.104.1',
+  '1.2.840.10008.1.2.4.105',
+  '1.2.840.10008.1.2.4.105.1',
+  '1.2.840.10008.1.2.4.106',
+  '1.2.840.10008.1.2.4.106.1',
+  '1.2.840.10008.1.2.4.107',
+  '1.2.840.10008.1.2.4.108',
+]);
+
+export default function isVideoTransferSyntax(uidOrUids: string | string[]) {
+  if (!uidOrUids) {
+    return false;
+  }
+  const uids = Array.isArray(uidOrUids) ? uidOrUids : [uidOrUids];
+  return uids.find((uid) => videoUIDs.has(uid));
+}

package/src/utilities/loadImageToCanvas.ts

@@ -1,4 +1,11 @@
-import { IImage } from '../types';
+import type {
+  IImage,
+  ViewPresentation,
+  ViewReference,
+  ViewportInputOptions,
+  Point3,
+  IVolume,
+} from '../types';
 
 import { loadAndCacheImage } from '../loaders/imageLoader';
 import * as metaData from '../metaData';
@@ -7,15 +14,66 @@ import imageLoadPoolManager from '../requestPool/imageLoadPoolManager';
 import renderToCanvasGPU from './renderToCanvasGPU';
 import renderToCanvasCPU from './renderToCanvasCPU';
 import { getConfiguration } from '../init';
+import cache from '../cache';
 
-interface LoadImageOptions {
-  canvas: HTMLCanvasElement;
+/**
+ * The original load image options specified just an image id,  which is optimal
+ * for things like thumbnails rendering a single image.
+ */
+export type StackLoadImageOptions = {
   imageId: string;
+};
+
+/**
+ * The full image load options allows specifying more parameters for both the
+ * presentation and the view so that a specific view can be referenced/displayed.
+ */
+export type FullImageLoadOptions = {
+  viewReference: ViewReference;
+  viewPresentation: ViewPresentation;
+  imageId: undefined;
+};
+
+/**
+ * The canvas load position allows for determining the rendered position of
+ * image data within the canvas, and can be used to map loaded canvas points
+ * to and from other viewport positions for things like external computations
+ * on the load image to canvas view and the viewport view (which may contain
+ * extraneous data such as segmentation and thus not be usable for external
+ * computations.)
+ */
+export type CanvasLoadPosition = {
+  origin: Point3;
+  topRight: Point3;
+  bottomLeft: Point3;
+  thicknessMm: number;
+};
+
+/**
+ * The image canvas can be loaded/set with various view conditions to specify the initial
+ * view as well as how and where ot render the image.
+ */
+export type LoadImageOptions = {
+  canvas: HTMLCanvasElement;
+  // Define the view specification as optional here, and then incorporate specific
+  // requirements in mix in types.
+  imageId?: string;
+  viewReference?: ViewReference;
+  viewPresentation?: ViewPresentation;
   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;
+} & (StackLoadImageOptions | FullImageLoadOptions);
 
 /**
  * Loads and renders an imageId to a Canvas. It will use the GPU rendering pipeline
@@ -35,31 +93,63 @@ 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
  * @returns - A promise that resolves when the image has been rendered with the imageId
  */
 export default function loadImageToCanvas(
   options: LoadImageOptions
-): Promise<string> {
+): Promise<CanvasLoadPosition> {
   const {
     canvas,
     imageId,
+    viewReference,
     requestType = RequestType.Thumbnail,
     priority = -5,
     renderingEngineId = '_thumbnails',
     useCPURendering = false,
+    thumbnail = false,
+    imageAspect = false,
+    viewportOptions: baseViewportOptions,
   } = options;
+  const volumeId = viewReference?.volumeId;
+  const isVolume = volumeId && !imageId;
+  const viewportOptions =
+    viewReference && baseViewportOptions
+      ? { ...baseViewportOptions, viewReference }
+      : baseViewportOptions;
 
   const renderFn = useCPURendering ? renderToCanvasCPU : renderToCanvasGPU;
 
   return new Promise((resolve, reject) => {
-    function successCallback(image: IImage, imageId: string) {
+    function successCallback(imageOrVolume: IImage | IVolume, imageId: string) {
       const { modality } = metaData.get('generalSeriesModule', imageId) || {};
 
-      image.isPreScaled = image.isPreScaled || image.preScale?.scaled;
+      const image = !isVolume && (imageOrVolume as IImage);
+      const volume = isVolume && (imageOrVolume as IVolume);
+      if (image) {
+        image.isPreScaled = image.isPreScaled || image.preScale?.scaled;
+      }
 
-      renderFn(canvas, image, modality, renderingEngineId).then(() => {
-        resolve(imageId);
-      });
+      if (thumbnail) {
+        canvas.height = 256;
+        canvas.width = 256;
+      }
+      if (imageAspect && image) {
+        canvas.width = image && (canvas.height * image.width) / image.height;
+      }
+      canvas.style.width = `${canvas.width / devicePixelRatio}px`;
+      canvas.style.height = `${canvas.height / devicePixelRatio}px`;
+      if (volume && useCPURendering) {
+        reject(new Error('CPU rendering of volume not supported'));
+      }
+      renderFn(
+        canvas,
+        imageOrVolume,
+        modality,
+        renderingEngineId,
+        viewportOptions
+      ).then(resolve);
     }
 
     function errorCallback(error: Error, imageId: string) {
@@ -93,11 +183,20 @@ export default function loadImageToCanvas(
       requestType,
     };
 
-    imageLoadPoolManager.addRequest(
-      sendRequest.bind(null, imageId, null, options),
-      requestType,
-      { imageId },
-      priority
-    );
+    if (volumeId) {
+      const volume = cache.getVolume(volumeId) as unknown as IVolume;
+      if (!volume) {
+        reject(new Error(`Volume id ${volumeId} not found in cache`));
+      }
+      const useImageId = volume.imageIds[0];
+      successCallback(volume, useImageId);
+    } else {
+      imageLoadPoolManager.addRequest(
+        sendRequest.bind(null, imageId, null, options),
+        requestType,
+        { imageId },
+        priority
+      );
+    }
   });
 }

package/src/utilities/makeVolumeMetadata.ts

@@ -0,0 +1,87 @@
+import { metaData } from '../';
+import { Metadata } from '../types';
+
+/**
+ * It creates a metadata object for a volume given the imageIds that compose it.
+ * It uses the first imageId to get the metadata.
+ *
+ * @param imageIds - array of imageIds
+ * @returns The volume metadata
+ */
+export default function makeVolumeMetadata(imageIds: Array<string>): Metadata {
+  const imageId0 = imageIds[0];
+
+  const {
+    pixelRepresentation,
+    bitsAllocated,
+    bitsStored,
+    highBit,
+    photometricInterpretation,
+    samplesPerPixel,
+  } = metaData.get('imagePixelModule', imageId0);
+
+  // Add list of VOIs stored on the DICOM.
+  const voiLut = [];
+
+  const voiLutModule = metaData.get('voiLutModule', imageId0);
+
+  // voiLutModule is not always present
+  let voiLUTFunction;
+  if (voiLutModule) {
+    const { windowWidth, windowCenter } = voiLutModule;
+    voiLUTFunction = voiLutModule?.voiLUTFunction;
+
+    if (Array.isArray(windowWidth)) {
+      for (let i = 0; i < windowWidth.length; i++) {
+        voiLut.push({
+          windowWidth: windowWidth[i],
+          windowCenter: windowCenter[i],
+        });
+      }
+    } else {
+      voiLut.push({
+        windowWidth: windowWidth,
+        windowCenter: windowCenter,
+      });
+    }
+  } else {
+    voiLut.push({
+      windowWidth: undefined,
+      windowCenter: undefined,
+    });
+  }
+
+  const { modality, seriesInstanceUID } = metaData.get(
+    'generalSeriesModule',
+    imageId0
+  );
+
+  const {
+    imageOrientationPatient,
+    pixelSpacing,
+    frameOfReferenceUID,
+    columns,
+    rows,
+  } = metaData.get('imagePlaneModule', imageId0);
+
+  // Map to dcmjs-style keywords. This is becoming the standard and makes it
+  // Easier to swap out cornerstoneDICOMImageLoader at a later date.
+  return {
+    BitsAllocated: bitsAllocated,
+    BitsStored: bitsStored,
+    SamplesPerPixel: samplesPerPixel,
+    HighBit: highBit,
+    PhotometricInterpretation: photometricInterpretation,
+    PixelRepresentation: pixelRepresentation,
+    Modality: modality,
+    ImageOrientationPatient: imageOrientationPatient,
+    PixelSpacing: pixelSpacing,
+    FrameOfReferenceUID: frameOfReferenceUID,
+    Columns: columns,
+    Rows: rows,
+    // This is a reshaped object and not a dicom tag:
+    voiLut,
+    VOILUTFunction: voiLUTFunction,
+    SeriesInstanceUID: seriesInstanceUID,
+  };
+}

package/src/utilities/planar.ts

@@ -28,11 +28,22 @@ function linePlaneIntersection(p0: Point3, p1: Point3, plane: Plane): Point3 {
  * It returns the plane equation defined by a point and a normal vector.
  * @param normal - normal vector
  * @param point - a point on the plane
+ * @param normalized - if true, the values of the plane equation will be normalized
  * @returns - [A, B,C, D] of plane equation A*X + B*Y + C*Z = D
  */
-function planeEquation(normal: Point3, point: Point3 | vec3): Plane {
+function planeEquation(
+  normal: Point3,
+  point: Point3 | vec3,
+  normalized = false
+): Plane {
   const [A, B, C] = normal;
   const D = A * point[0] + B * point[1] + C * point[2];
+
+  if (normalized) {
+    const length = Math.sqrt(A * A + B * B + C * C);
+    return [A / length, B / length, C / length, D / length];
+  }
+
   return [A, B, C, D];
 }
 

package/src/utilities/renderToCanvasCPU.ts

@@ -1,8 +1,14 @@
-import { IImage, CPUFallbackEnabledElement } from '../types';
+import {
+  IImage,
+  CPUFallbackEnabledElement,
+  ViewportInputOptions,
+  IVolume,
+} from '../types';
 
 import getDefaultViewport from '../RenderingEngine/helpers/cpuFallback/rendering/getDefaultViewport';
 import calculateTransform from '../RenderingEngine/helpers/cpuFallback/rendering/calculateTransform';
 import drawImageSync from '../RenderingEngine/helpers/cpuFallback/drawImageSync';
+import type { CanvasLoadPosition } from './loadImageToCanvas';
 
 /**
  * Renders a cornerstone image object to a canvas.
@@ -13,10 +19,16 @@ import drawImageSync from '../RenderingEngine/helpers/cpuFallback/drawImageSync'
  */
 export default function renderToCanvasCPU(
   canvas: HTMLCanvasElement,
-  image: IImage,
+  imageOrVolume: IImage | IVolume,
   modality?: string,
-  renderingEngineId?: string
-): Promise<string> {
+  _renderingEngineId?: string,
+  _viewportOptions?: ViewportInputOptions
+): Promise<CanvasLoadPosition> {
+  const volume = imageOrVolume as IVolume;
+  if (volume.volumeId) {
+    throw new Error('Unsupported volume rendering for CPU');
+  }
+  const image = imageOrVolume as IImage;
   const viewport = getDefaultViewport(canvas, image, modality);
 
   const enabledElement: CPUFallbackEnabledElement = {
@@ -31,6 +43,6 @@ export default function renderToCanvasCPU(
   const invalidated = true;
   return new Promise((resolve, reject) => {
     drawImageSync(enabledElement, invalidated);
-    resolve(image.imageId);
+    resolve(null);
   });
 }

package/src/utilities/renderToCanvasGPU.ts

@@ -1,10 +1,19 @@
-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,
+  IStackViewport,
+  IVolume,
+  ViewportInputOptions,
+  IVolumeViewport,
+  ViewReference,
+} from '../types';
 import { getRenderingEngine } from '../RenderingEngine/getRenderingEngine';
 import RenderingEngine from '../RenderingEngine';
 import isPTPrescaledWithSUV from './isPTPrescaledWithSUV';
+import { CanvasLoadPosition } from './loadImageToCanvas';
 
 /**
  * Renders an cornerstone image to a Canvas. This method will handle creation
@@ -21,39 +30,45 @@ import isPTPrescaledWithSUV from './isPTPrescaledWithSUV';
  * renderToCanvasGPU(canvas, image)
  * ```
  * @param canvas - Canvas element to render to
- * @param image - The image to render
+ * @param imageOrVolume - The image to render
  * @param modality - [Default = undefined] The modality of the image
  * @returns - A promise that resolves when the image has been rendered with the imageId
  */
 export default function renderToCanvasGPU(
   canvas: HTMLCanvasElement,
-  image: IImage,
+  imageOrVolume: IImage | IVolume,
   modality = undefined,
-  renderingEngineId = '_thumbnails'
-): Promise<string> {
+  renderingEngineId = '_thumbnails',
+  viewportOptions: ViewportInputOptions & { viewReference?: ViewReference } = {
+    displayArea: { imageArea: [1, 1] },
+  }
+): Promise<CanvasLoadPosition> {
   if (!canvas || !(canvas instanceof HTMLCanvasElement)) {
     throw new Error('canvas element is required');
   }
 
-  const imageIdToPrint = image.imageId;
+  const isVolume = !(imageOrVolume as IImage).imageId;
+  const image = !isVolume && (imageOrVolume as IImage);
+  const volume = isVolume && (imageOrVolume as IVolume);
+  const imageIdToPrint = image?.imageId || volume?.volumeId;
   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`;
-  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;
+  if (!viewportOptions.displayArea) {
+    viewportOptions.displayArea = { imageArea: [1, 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`;
+  // 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.
+  // Don't touch the canvas size here as what we get out is a canvas at the right size
+  element.style.width = `${originalWidth / devicePixelRatio + EPSILON}px`;
+  element.style.height = `${originalHeight / devicePixelRatio + EPSILON}px`;
+  element.style.visibility = 'hidden';
+  element.style.position = 'absolute';
 
   document.body.appendChild(element);
 
@@ -61,23 +76,26 @@ 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);
 
-  let viewport = renderingEngine.getViewport(viewportId) as StackViewport;
+  let viewport = renderingEngine.getViewport(viewportId);
 
   if (!viewport) {
-    const stackViewportInput = {
+    const viewportInput = {
       viewportId,
-      type: ViewportType.STACK,
+      type: isVolume ? ViewportType.ORTHOGRAPHIC : ViewportType.STACK,
       element,
       defaultOptions: {
+        ...viewportOptions,
         suppressEvents: true,
       },
     };
-    renderingEngine.enableElement(stackViewportInput);
-    viewport = renderingEngine.getViewport(viewportId) as StackViewport;
+    renderingEngine.enableElement(viewportInput);
+    viewport = renderingEngine.getViewport(viewportId);
   }
 
   return new Promise((resolve) => {
@@ -85,14 +103,20 @@ export default function renderToCanvasGPU(
     // enable it and later disable it without losing the canvas context
     let elementRendered = false;
 
+    let { viewReference } = viewportOptions;
+
     // Create a named function to handle the event
     const onImageRendered = (eventDetail) => {
       if (elementRendered) {
         return;
       }
-
-      // get the canvas element that is the child of the div
-      const temporaryCanvas = getOrCreateCanvas(element);
+      if (viewReference) {
+        const useViewRef = viewReference;
+        viewReference = null;
+        viewport.setViewReference(useViewRef);
+        viewport.render();
+        return;
+      }
 
       // Copy the temporary canvas to the given canvas
       const context = canvas.getContext('2d');
@@ -108,6 +132,16 @@ export default function renderToCanvasGPU(
         canvas.height // destination dimensions
       );
 
+      const origin = viewport.canvasToWorld([0, 0]);
+      const topRight = viewport.canvasToWorld([
+        temporaryCanvas.width / devicePixelRatio,
+        0,
+      ]);
+      const bottomLeft = viewport.canvasToWorld([
+        0,
+        temporaryCanvas.height / devicePixelRatio,
+      ]);
+      const thicknessMm = 1;
       elementRendered = true;
 
       // remove based on id
@@ -129,17 +163,26 @@ export default function renderToCanvasGPU(
           element.remove();
         });
       }, 0);
-      resolve(imageId);
+      resolve({
+        origin,
+        bottomLeft,
+        topRight,
+        thicknessMm,
+      });
     };
 
     element.addEventListener(Events.IMAGE_RENDERED, onImageRendered);
-    viewport.renderImageObject(image);
+    if (isVolume) {
+      (viewport as IVolumeViewport).setVolumes([volume], false, true);
+    } else {
+      (viewport as IStackViewport).renderImageObject(imageOrVolume);
+    }
 
-    // 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)) {
-      viewport.setProperties({
+      (viewport as IStackViewport).setProperties({
         voiRange: {
           lower: image.minPixelValue,
           upper: image.maxPixelValue,