@cornerstonejs/core 2.0.0-beta.1 → 2.0.0-beta.10

package/src/utilities/index.ts

@@ -1,3 +1,4 @@
+import * as eventListener from './eventListener';
 import csUtils from './invertRgbTransferFunction';
 import createSigmoidRGBTransferFunction from './createSigmoidRGBTransferFunction';
 import getVoiFromSigmoidRGBTransferFunction from './getVoiFromSigmoidRGBTransferFunction';
@@ -9,12 +10,14 @@ import getMinMax from './getMinMax';
 import getRuntimeId from './getRuntimeId';
 import imageIdToURI from './imageIdToURI';
 import calibratedPixelSpacingMetadataProvider from './calibratedPixelSpacingMetadataProvider';
-import isEqual from './isEqual';
+import clamp from './clamp';
+import { isEqual, isEqualAbs, isEqualNegative } from './isEqual';
 import isOpposite from './isOpposite';
 import createUint8SharedArray from './createUint8SharedArray';
 import createFloat32SharedArray from './createFloat32SharedArray';
 import createUint16SharedArray from './createUInt16SharedArray';
 import createInt16SharedArray from './createInt16SharedArray';
+import getViewportModality from './getViewportModality';
 import getClosestImageId from './getClosestImageId';
 import getSpacingInNormalDirection from './getSpacingInNormalDirection';
 import getTargetVolumeAndSpacingInNormalDir from './getTargetVolumeAndSpacingInNormalDir';
@@ -23,6 +26,7 @@ import indexWithinDimensions from './indexWithinDimensions';
 import getVolumeViewportsContainingSameVolumes from './getVolumeViewportsContainingSameVolumes';
 import getViewportsWithVolumeId from './getViewportsWithVolumeId';
 import transformWorldToIndex from './transformWorldToIndex';
+import transformIndexToWorld from './transformIndexToWorld';
 import loadImageToCanvas from './loadImageToCanvas';
 import renderToCanvasCPU from './renderToCanvasCPU';
 import renderToCanvasGPU from './renderToCanvasGPU';
@@ -36,23 +40,50 @@ import getImageSliceDataForVolumeViewport from './getImageSliceDataForVolumeView
 import { isImageActor, actorIsA } from './actorCheck';
 import getViewportsWithImageURI from './getViewportsWithImageURI';
 import getClosestStackImageIndexForPoint from './getClosestStackImageIndexForPoint';
+import getCurrentVolumeViewportSlice from './getCurrentVolumeViewportSlice';
 import calculateViewportsSpatialRegistration from './calculateViewportsSpatialRegistration';
 import spatialRegistrationMetadataProvider from './spatialRegistrationMetadataProvider';
 import getViewportImageCornersInWorld from './getViewportImageCornersInWorld';
 import hasNaNValues from './hasNaNValues';
 import applyPreset from './applyPreset';
+import PointsManager from './PointsManager';
 import deepMerge from './deepMerge';
 import getScalingParameters from './getScalingParameters';
 import getScalarDataType from './getScalarDataType';
 import isPTPrescaledWithSUV from './isPTPrescaledWithSUV';
 import getImageLegacy from './getImageLegacy';
+import sortImageIdsAndGetSpacing from './sortImageIdsAndGetSpacing';
+import makeVolumeMetadata from './makeVolumeMetadata';
+import genericMetadataProvider from './genericMetadataProvider';
+import { isValidVolume } from './isValidVolume';
+import { updateVTKImageDataWithCornerstoneImage } from './updateVTKImageDataWithCornerstoneImage';
+import ProgressiveIterator from './ProgressiveIterator';
+import decimate from './decimate';
+import imageRetrieveMetadataProvider from './imageRetrieveMetadataProvider';
+import isVideoTransferSyntax from './isVideoTransferSyntax';
+import { getBufferConfiguration } from './getBufferConfiguration';
+import { generateVolumePropsFromImageIds } from './generateVolumePropsFromImageIds';
+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';
+import { getRandomSampleFromArray } from './getRandomSampleFromArray';
+import { getVolumeId } from './getVolumeId';
+import { hasFloatScalingParameters } from './hasFloatScalingParameters';
 
 // name spaces
 import * as planar from './planar';
 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,
   csUtils as invertRgbTransferFunction,
   createSigmoidRGBTransferFunction,
   getVoiFromSigmoidRGBTransferFunction,
@@ -61,17 +92,22 @@ export {
   triggerEvent,
   imageIdToURI,
   calibratedPixelSpacingMetadataProvider,
+  clamp,
   uuidv4,
   planar,
   getMinMax,
   getRuntimeId,
   isEqual,
+  isEqualAbs,
+  isEqualNegative,
   isOpposite,
   createFloat32SharedArray,
   createUint8SharedArray,
   createUint16SharedArray,
   createInt16SharedArray,
+  getViewportModality,
   windowLevel,
+  convertToGrayscale,
   getClosestImageId,
   getSpacingInNormalDirection,
   getTargetVolumeAndSpacingInNormalDir,
@@ -80,6 +116,7 @@ export {
   getVolumeViewportsContainingSameVolumes,
   getViewportsWithVolumeId,
   transformWorldToIndex,
+  transformIndexToWorld,
   loadImageToCanvas,
   renderToCanvasCPU,
   renderToCanvasGPU,
@@ -95,14 +132,40 @@ export {
   actorIsA,
   getViewportsWithImageURI,
   getClosestStackImageIndexForPoint,
+  getCurrentVolumeViewportSlice,
   calculateViewportsSpatialRegistration,
   spatialRegistrationMetadataProvider,
   getViewportImageCornersInWorld,
   hasNaNValues,
   applyPreset,
   deepMerge,
+  PointsManager,
   getScalingParameters,
   getScalarDataType,
   colormap,
   getImageLegacy,
+  ProgressiveIterator,
+  decimate,
+  imageRetrieveMetadataProvider,
+  transferFunctionUtils,
+  updateVTKImageDataWithCornerstoneImage,
+  sortImageIdsAndGetSpacing,
+  makeVolumeMetadata,
+  isValidVolume,
+  genericMetadataProvider,
+  isVideoTransferSyntax,
+  generateVolumePropsFromImageIds,
+  getBufferConfiguration,
+  VoxelManager,
+  RLEVoxelMap,
+  convertStackToVolumeViewport,
+  convertVolumeToStackViewport,
+  cacheUtils,
+  roundNumber,
+  roundToPrecision,
+  getViewportImageIds,
+  getRandomSampleFromArray,
+  getVolumeId,
+  color,
+  hasFloatScalingParameters,
 };

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