@cornerstonejs/core 1.41.0 → 1.42.1

package/src/loaders/volumeLoader.ts

@@ -6,20 +6,32 @@ import vtkDataArray from '@kitware/vtk.js/Common/Core/DataArray';
 import cloneDeep from 'lodash.clonedeep';
 
 import { ImageVolume } from '../cache/classes/ImageVolume';
-import type * as Types from '../types';
 import cache from '../cache/cache';
 import Events from '../enums/Events';
 import eventTarget from '../eventTarget';
 import triggerEvent from '../utilities/triggerEvent';
-import { getBufferConfiguration, uuidv4 } from '../utilities';
+import {
+  generateVolumePropsFromImageIds,
+  getBufferConfiguration,
+  uuidv4,
+} from '../utilities';
 import {
   Point3,
   Metadata,
   EventTypes,
   Mat3,
+  IImageVolume,
+  VolumeLoaderFn,
+  IDynamicImageVolume,
   PixelDataTypedArray,
+  IVolumeLoadObject,
+  PixelDataTypedArrayString,
 } from '../types';
 import { getConfiguration } from '../init';
+import {
+  performCacheOptimizationForVolume,
+  setupCacheOptimizationEventListener,
+} from '../utilities/cacheUtils';
 
 interface VolumeLoaderOptions {
   imageIds: Array<string>;
@@ -28,7 +40,7 @@ interface VolumeLoaderOptions {
 interface DerivedVolumeOptions {
   volumeId: string;
   targetBuffer?: {
-    type: 'Float32Array' | 'Uint8Array' | 'Uint16Array' | 'Int16Array';
+    type: PixelDataTypedArrayString;
     sharedArrayBuffer?: boolean;
   };
 }
@@ -46,7 +58,7 @@ interface LocalVolumeOptions {
  */
 function addScalarDataToImageData(
   imageData: vtkImageDataType,
-  scalarData: Types.VolumeScalarData,
+  scalarData: PixelDataTypedArray,
   dataArrayAttrs
 ) {
   const scalarArray = vtkDataArray.newInstance({
@@ -63,7 +75,7 @@ function addScalarDataToImageData(
  */
 function addScalarDataArraysToImageData(
   imageData: vtkImageDataType,
-  scalarDataArrays: Types.VolumeScalarData[],
+  scalarDataArrays: PixelDataTypedArray[],
   dataArrayAttrs
 ) {
   scalarDataArrays.forEach((scalarData, i) => {
@@ -81,7 +93,7 @@ function addScalarDataArraysToImageData(
 }
 
 function createInternalVTKRepresentation(
-  volume: Types.IImageVolume
+  volume: IImageVolume
 ): vtkImageDataType {
   const { dimensions, metadata, spacing, direction, origin } = volume;
   const { PhotometricInterpretation } = metadata;
@@ -101,7 +113,7 @@ function createInternalVTKRepresentation(
 
   // Add scalar data to 3D or 4D volume
   if (volume.isDynamicVolume()) {
-    const scalarDataArrays = (<Types.IDynamicImageVolume>(
+    const scalarDataArrays = (<IDynamicImageVolume>(
       volume
     )).getScalarDataArrays();
 
@@ -139,23 +151,28 @@ let unknownVolumeLoader;
 function loadVolumeFromVolumeLoader(
   volumeId: string,
   options?: VolumeLoaderOptions
-): Types.IVolumeLoadObject {
+): IVolumeLoadObject {
   const colonIndex = volumeId.indexOf(':');
   const scheme = volumeId.substring(0, colonIndex);
-  const loader = volumeLoaders[scheme];
+  let loader = volumeLoaders[scheme];
 
   if (loader === undefined || loader === null) {
-    if (unknownVolumeLoader !== undefined) {
-      return unknownVolumeLoader(volumeId, options);
+    if (
+      unknownVolumeLoader == null ||
+      typeof unknownVolumeLoader !== 'function'
+    ) {
+      throw new Error(
+        `No volume loader for scheme ${scheme} has been registered`
+      );
     }
 
-    throw new Error(
-      'loadVolumeFromVolumeLoader: no volume loader for volumeId'
-    );
+    loader = unknownVolumeLoader;
   }
 
   const volumeLoadObject = loader(volumeId, options);
 
+  setupCacheOptimizationEventListener(volumeId);
+
   // Broadcast a volume loaded event once the image is loaded
   volumeLoadObject.promise.then(
     function (volume) {
@@ -186,7 +203,7 @@ function loadVolumeFromVolumeLoader(
 export function loadVolume(
   volumeId: string,
   options: VolumeLoaderOptions = { imageIds: [] }
-): Promise<Types.IImageVolume> {
+): Promise<IImageVolume> {
   if (volumeId === undefined) {
     throw new Error('loadVolume: parameter volumeId must not be undefined');
   }
@@ -199,7 +216,7 @@ export function loadVolume(
 
   volumeLoadObject = loadVolumeFromVolumeLoader(volumeId, options);
 
-  return volumeLoadObject.promise.then((volume: Types.IImageVolume) => {
+  return volumeLoadObject.promise.then((volume: IImageVolume) => {
     volume.imageData = createInternalVTKRepresentation(volume);
     return volume;
   });
@@ -232,7 +249,7 @@ export async function createAndCacheVolume(
 
   volumeLoadObject = loadVolumeFromVolumeLoader(volumeId, options);
 
-  volumeLoadObject.promise.then((volume: Types.IImageVolume) => {
+  volumeLoadObject.promise.then((volume: IImageVolume) => {
     volume.imageData = createInternalVTKRepresentation(volume);
   });
 
@@ -258,7 +275,7 @@ export async function createAndCacheVolume(
 export async function createAndCacheDerivedVolume(
   referencedVolumeId: string,
   options: DerivedVolumeOptions
-): Promise<ImageVolume> {
+): Promise<IImageVolume> {
   const referencedVolume = cache.getVolume(referencedVolumeId);
 
   if (!referencedVolume) {
@@ -330,6 +347,7 @@ export async function createAndCacheDerivedVolume(
     scalarData: volumeScalarData,
     sizeInBytes: numBytes,
     referencedVolumeId,
+    imageIds: [],
   });
 
   const volumeLoadObject = {
@@ -355,7 +373,7 @@ export function createLocalVolume(
   options: LocalVolumeOptions,
   volumeId: string,
   preventCache = false
-): ImageVolume {
+): IImageVolume {
   const { scalarData, metadata, dimensions, spacing, origin, direction } =
     options;
 
@@ -381,7 +399,7 @@ export function createLocalVolume(
   const cachedVolume = cache.getVolume(volumeId);
 
   if (cachedVolume) {
-    return cachedVolume as ImageVolume;
+    return cachedVolume as IImageVolume;
   }
 
   const scalarLength = dimensions[0] * dimensions[1] * dimensions[2];
@@ -418,6 +436,7 @@ export function createLocalVolume(
     imageData: imageData,
     scalarData,
     sizeInBytes: numBytes,
+    imageIds: [],
   });
 
   if (preventCache) {
@@ -432,6 +451,78 @@ export function createLocalVolume(
   return derivedVolume;
 }
 
+export async function createAndCacheVolumeFromImages(
+  volumeId: string,
+  imageIds: string[],
+  options: {
+    preventCache?: boolean;
+    additionalDetails?: Record<string, any>;
+  } = {}
+): Promise<IImageVolume> {
+  const { preventCache = false } = options;
+
+  if (imageIds === undefined) {
+    throw new Error(
+      'createAndCacheVolumeFromImages: parameter imageIds must not be undefined'
+    );
+  }
+
+  if (volumeId === undefined) {
+    throw new Error(
+      'createAndCacheVolumeFromImages: parameter volumeId must not be undefined'
+    );
+  }
+
+  const cachedVolume = cache.getVolume(volumeId);
+
+  if (cachedVolume) {
+    return Promise.resolve(cachedVolume);
+  }
+
+  const volumeProps = generateVolumePropsFromImageIds(imageIds, volumeId);
+
+  // volume is an empty volume, we need to load the data from the imageIds
+  // into the volume scalarData
+
+  // it is important to get the imageIds from the volumeProps
+  // since they are sorted
+  const imagePromises = volumeProps.imageIds.map((imageId, imageIdIndex) => {
+    const imageLoadObject = cache.getImageLoadObject(imageId);
+
+    return imageLoadObject.promise.then((image) => {
+      const pixelData = image.getPixelData();
+      const offset = imageIdIndex * image.rows * image.columns;
+
+      (volumeProps.scalarData as PixelDataTypedArray).set(pixelData, offset);
+    });
+  });
+
+  await Promise.all(imagePromises);
+
+  const volume = new ImageVolume({
+    ...volumeProps,
+    referencedImageIds: imageIds,
+    ...options,
+  });
+
+  // since we generated the volume from images, we can optimize the cache
+  // by replacing the pixelData of the images with a view of the volume's
+  // scalarData
+  performCacheOptimizationForVolume(volume);
+
+  const volumeLoadObject = {
+    promise: Promise.resolve(volume),
+  };
+
+  if (preventCache) {
+    return volumeLoadObject.promise;
+  }
+
+  cache.putVolumeLoadObject(volumeId, volumeLoadObject);
+
+  return volumeLoadObject.promise;
+}
+
 /**
  * Registers an volumeLoader plugin with cornerstone for the specified scheme
  *
@@ -440,7 +531,7 @@ export function createLocalVolume(
  */
 export function registerVolumeLoader(
   scheme: string,
-  volumeLoader: Types.VolumeLoaderFn
+  volumeLoader: VolumeLoaderFn
 ): void {
   volumeLoaders[scheme] = volumeLoader;
 }
@@ -458,11 +549,15 @@ export function getVolumeLoaderSchemes(): string[] {
  * @returns The previous Unknown Volume Loader
  */
 export function registerUnknownVolumeLoader(
-  volumeLoader: Types.VolumeLoaderFn
-): Types.VolumeLoaderFn | undefined {
+  volumeLoader: VolumeLoaderFn
+): VolumeLoaderFn | undefined {
   const oldVolumeLoader = unknownVolumeLoader;
 
   unknownVolumeLoader = volumeLoader;
 
   return oldVolumeLoader;
 }
+
+export function getUnknownVolumeLoaderSchema(): string {
+  return unknownVolumeLoader.name;
+}

package/src/types/Cornerstone3DConfig.ts

@@ -51,6 +51,18 @@ type Cornerstone3DConfig = {
      */
     strictZSpacingForVolumeViewport: boolean;
   };
+  /**
+   * This flag controls whether to enable cache optimization or not. Basically,
+   * when we have a stack viewport (image stack) and we convert it to a volume
+   * the volume will be cached as well as the stack. However, if we can optimize this
+   * by going back to the image cache and create a view at the correct offset
+   * of the bigger volume array buffer, this will save memory. This will get enabled
+   * if cornerstone3D is configured to use SharedArrayBuffer, the reason is that
+   * when we modify the image cache then the images are referring to a different
+   * buffer (SharedArrayBuffer) and some systems don't support shared array
+   * buffers.
+   */
+  enableCacheOptimization: boolean;
 };
 
 export default Cornerstone3DConfig;

package/src/types/IDynamicImageVolume.ts

@@ -1,4 +1,4 @@
-import { IImageVolume, VolumeScalarData } from '../types';
+import { IImageVolume, PixelDataTypedArray } from '../types';
 
 /**
  * Cornerstone ImageVolume interface. Todo: we should define new IVolume class
@@ -12,7 +12,7 @@ interface IDynamicImageVolume extends IImageVolume {
   /** Returns the number of time points */
   get numTimePoints(): number;
   /** return scalar data arrays (one per timepoint) */
-  getScalarDataArrays(): VolumeScalarData[];
+  getScalarDataArrays(): PixelDataTypedArray[];
 }
 
 export default IDynamicImageVolume;

package/src/types/IImage.ts

@@ -120,6 +120,12 @@ interface IImage {
 
   imageQualityStatus?: ImageQualityStatus;
   calibration?: IImageCalibration;
+  imageFrame?: any;
+
+  bufferView?: {
+    buffer: ArrayBuffer;
+    offset: number;
+  };
 }
 
 export default IImage;

package/src/types/IImageVolume.ts

@@ -1,7 +1,7 @@
 import type { vtkImageData } from '@kitware/vtk.js/Common/DataModel/ImageData';
 import {
   Metadata,
-  VolumeScalarData,
+  PixelDataTypedArray,
   Point3,
   IImageLoadObject,
   Mat3,
@@ -49,8 +49,12 @@ interface IImageVolume {
   imageIds: Array<string>;
   /** volume referencedVolumeId (if it is derived from another volume) */
   referencedVolumeId?: string; // if volume is derived from another volume
+  /** volume referencedImageIds (if it is derived from set of images in the image cache) */
+  referencedImageIds?: Array<string>;
   /** whether the metadata for the pixel spacing is not undefined  */
   hasPixelSpacing: boolean;
+  /** Property to store additional information */
+  additionalDetails?: Record<string, any>;
   /** return true if it is a 4D volume or false if it is 3D volume */
   isDynamicVolume(): boolean;
   /** method to convert the volume data in the volume cache, to separate images in the image cache */
@@ -63,7 +67,9 @@ interface IImageVolume {
   cancelLoading?: () => void;
 
   /** return the volume scalar data */
-  getScalarData(): VolumeScalarData;
+  getScalarData(): PixelDataTypedArray;
+
+  convertToImageSlicesAndCache(): string[];
 
   /** return the index of a given imageId */
   getImageIdIndex(imageId: string): number;
@@ -73,6 +79,12 @@ interface IImageVolume {
 
   /** destroy the volume and make it unusable */
   destroy(): void;
+
+  /** decache */
+  decache?: () => void;
+
+  /** */
+  get imageCacheOffsetMap(): Map<string, any>;
 }
 
 export default IImageVolume;

package/src/types/ILoadObject.ts

@@ -1,6 +1,6 @@
-import { ImageVolume } from './../cache/classes/ImageVolume';
 import IGeometry from './IGeometry';
 import IImage from './IImage';
+import IImageVolume from './IImageVolume';
 
 /**
  * ImageLoadObject interface which any imageLoader should return
@@ -19,7 +19,7 @@ export interface IImageLoadObject {
  */
 export interface IVolumeLoadObject {
   /** promise that resolves to an ImageVolume */
-  promise: Promise<ImageVolume>;
+  promise: Promise<IImageVolume>;
   /** optional cancel function for loading*/
   cancelFn?: () => void;
   /** optional decache function */

package/src/types/IVolume.ts

@@ -1,45 +1,8 @@
-import type { vtkImageData } from '@kitware/vtk.js/Common/DataModel/ImageData';
-import type Point3 from './Point3';
-import type Metadata from './Metadata';
-import Mat3 from './Mat3';
-
-type VolumeScalarData = Float32Array | Uint8Array | Uint16Array | Int16Array;
+import { ImageVolumeProps } from './ImageVolumeProps';
 
 /**
- * Cornerstone ImageVolume interface.
+ * Backwards compatibility for IVolume
  */
-interface IVolume {
-  /** unique identifier for the volume in the cache */
-  volumeId: string;
-  /** volume metadata */
-  metadata: Metadata;
-  /** volume dimensions */
-  dimensions: Point3;
-  /** volume spacing */
-  spacing: Point3;
-  /** volume origin */
-  origin: Point3;
-  /** volume direction */
-  direction: Mat3;
-  /** volume scalarData */
-  scalarData: VolumeScalarData | Array<VolumeScalarData>;
-  /** volume size in bytes */
-  sizeInBytes?: number;
-  /** volume image data as vtkImageData */
-  imageData?: vtkImageData;
-  /** referencedVolumeId if volume is derived from another volume */
-  referencedVolumeId?: string;
-  /** volume scaling metadata */
-  scaling?: {
-    PT?: {
-      // @TODO: Do these values exist?
-      SUVlbmFactor?: number;
-      SUVbsaFactor?: number;
-      // accessed in ProbeTool
-      suvbwToSuvlbm?: number;
-      suvbwToSuvbsa?: number;
-    };
-  };
-}
+type IVolume = ImageVolumeProps;
 
-export { IVolume as default, IVolume, VolumeScalarData };
+export { IVolume };

package/src/types/ImageVolumeProps.ts

@@ -0,0 +1,15 @@
+import { VolumeProps } from '.';
+
+/**
+ * ImageVolume which is considered a special case of a Volume, which is
+ * constructed out of set of images (imageIds). Unlike Volume which can be
+ * constructed from any type of volumetric data, such as nifti or nrrd,
+ */
+interface ImageVolumeProps extends VolumeProps {
+  /** imageIds of the volume (if it is built of separate imageIds) */
+  imageIds: Array<string>;
+  /** if the volume is created from a stack, the imageIds of the stack */
+  referencedImageIds?: Array<string>;
+}
+
+export { ImageVolumeProps };

package/src/types/VolumeProps.ts

@@ -0,0 +1,57 @@
+import type { vtkImageData } from '@kitware/vtk.js/Common/DataModel/ImageData';
+import type Point3 from './Point3';
+import type Metadata from './Metadata';
+import Mat3 from './Mat3';
+import { PixelDataTypedArray } from './PixelDataTypedArray';
+
+/**
+ * Properties required to instantiate a Volume object.
+ * This includes all the necessary data and metadata to define
+ * a volume in 3D/4D space.
+ */
+interface VolumeProps {
+  /** Unique identifier for the volume */
+  volumeId: string;
+
+  /** Metadata describing the volume */
+  metadata: Metadata;
+
+  /** Dimensions of the volume (width, height, depth) */
+  dimensions: Point3;
+
+  /** Spacing between volume points in 3D world space */
+  spacing: Point3;
+
+  /** Origin point of the volume in world space */
+  origin: Point3;
+
+  /** Direction of the volume in world space */
+  direction: Mat3;
+
+  /** Image data representing the volume */
+  imageData?: vtkImageData;
+
+  /** Scalar data representing the volume's intensity values */
+  scalarData: PixelDataTypedArray | Array<PixelDataTypedArray>;
+
+  /** Size of the volume data in bytes (optional) */
+  sizeInBytes?: number;
+
+  /** Property to store additional information */
+  additionalDetails?: Record<string, any>;
+
+  /** Scaling parameters if the volume contains scaled data (optional) */
+  scaling?: {
+    PT?: {
+      SUVlbmFactor?: number;
+      SUVbsaFactor?: number;
+      suvbwToSuvlbm?: number;
+      suvbwToSuvbsa?: number;
+    };
+  };
+
+  /** Optional ID of a referenced volume if this volume is derived from another */
+  referencedVolumeId?: string;
+}
+
+export { VolumeProps };

package/src/types/index.ts

@@ -3,7 +3,7 @@ import type Cornerstone3DConfig from './Cornerstone3DConfig';
 import type ICamera from './ICamera';
 import type IEnabledElement from './IEnabledElement';
 import type ICache from './ICache';
-import type { IVolume, VolumeScalarData } from './IVolume';
+import type { IVolume } from './IVolume';
 import type { VOI, VOIRange } from './voi';
 import type DisplayArea from './displayArea';
 import type ImageLoaderFn from './ImageLoaderFn';
@@ -106,6 +106,8 @@ import type {
   VideoViewportInput,
 } from './VideoViewportTypes';
 import type BoundsIJK from './BoundsIJK';
+import type { ImageVolumeProps } from './ImageVolumeProps';
+import type { VolumeProps } from './VolumeProps';
 
 export type {
   // config
@@ -118,9 +120,9 @@ export type {
   IEnabledElement,
   ICache,
   IVolume,
-  VolumeScalarData,
   IViewportId,
   IImageVolume,
+  ImageVolumeProps,
   IDynamicImageVolume,
   IRenderingEngine,
   ScalingParameters,
@@ -216,4 +218,5 @@ export type {
   BoundsIJK,
   Color,
   ColorLUT,
+  VolumeProps,
 };

package/src/utilities/VoxelManager.ts

@@ -1,4 +1,4 @@
-import type { BoundsIJK, Point3, VolumeScalarData } from '../types';
+import type { BoundsIJK, Point3, PixelDataTypedArray } from '../types';
 
 /**
  * This is a simple, standard interface to values associated with a voxel.
@@ -12,7 +12,7 @@ export default class VoxelManager<T> {
   ] as BoundsIJK;
 
   // Provide direct access to the underlying data, if any
-  public scalarData: VolumeScalarData;
+  public scalarData: PixelDataTypedArray;
   public map: Map<number, T>;
   public sourceVoxelManager: VoxelManager<T>;
   public isInObject: (pointIPS, pointIJK) => boolean;

package/src/utilities/cacheUtils.ts

@@ -0,0 +1,121 @@
+import cache, { ImageVolume } from '../cache';
+import { Events } from '../enums';
+import eventTarget from '../eventTarget';
+import { getConfiguration, getShouldUseSharedArrayBuffer } from '../init';
+
+/**
+ * This function will check if the cache optimization is enabled and if it is
+ * it will check if the created volume was derived from an already cached stack
+ * of images, if so it will go back to the image cache and create a view at the
+ * correct offset of the bigger volume array buffer, this will save memory.
+ *
+ * @param volumeId - The volumeId that will be checked for cache optimization
+ */
+export function setupCacheOptimizationEventListener(volumeId) {
+  const { enableCacheOptimization } = getConfiguration();
+  const shouldUseSAB = getShouldUseSharedArrayBuffer();
+
+  const performOptimization = enableCacheOptimization && shouldUseSAB;
+  if (!performOptimization) {
+    return;
+  }
+
+  eventTarget.addEventListenerOnce(
+    Events.IMAGE_VOLUME_LOADING_COMPLETED,
+    (evt) => {
+      if (evt.detail.volumeId !== volumeId) {
+        return;
+      }
+
+      const volume = cache.getVolume(volumeId);
+
+      performCacheOptimizationForVolume(volume);
+    }
+  );
+}
+
+/**
+ * Performs cache optimization for a volume by replacing the pixel data of each image
+ * in the image cache (if found) with a view of the volume's scalar data.
+ * @param options - The options for cache optimization.
+ * @param options.volumeId - The ID of the volume.
+ */
+export function performCacheOptimizationForVolume(volume) {
+  if (!(volume instanceof ImageVolume)) {
+    return;
+  }
+
+  const scalarData = volume.getScalarData();
+
+  volume.imageCacheOffsetMap.size > 0
+    ? _processImageCacheOffsetMap(volume, scalarData)
+    : _processVolumeImages(volume, scalarData);
+}
+
+/**
+ * This function will process the volume images and replace the pixel data of each
+ * image in the image cache (if found) with a view of the volume's scalar data.
+ * This function is used when the volume is derived from an already cached stack
+ * of images.
+ *
+ * @param volume - The volume to process.
+ * @param scalarData - The scalar data to use for the volume.
+ */
+function _processImageCacheOffsetMap(volume, scalarData) {
+  volume.imageCacheOffsetMap.forEach(({ offset }, imageId) => {
+    const image = cache.getImage(imageId);
+    if (!image) {
+      return;
+    }
+
+    _updateImageWithScalarDataView(image, scalarData, offset);
+    cache.decrementImageCacheSize(image.sizeInBytes);
+  });
+}
+
+/**
+ * This function will process the volume images and replace the pixel data of each
+ * image in the image cache (if found) with a view of the volume's scalar data.
+ * This function is used when the volume is not derived from an already cached stack
+ * of images.
+ *
+ * @param volume - The volume to process.
+ * @param scalarData - The scalar data to use for the volume.
+ */
+function _processVolumeImages(volume, scalarData) {
+  volume.imageIds.forEach((imageId) => {
+    const image = cache.getImage(imageId);
+    if (!image) {
+      return;
+    }
+
+    const index = volume.getImageIdIndex(imageId);
+    const offset = index * image.getPixelData().byteLength;
+
+    _updateImageWithScalarDataView(image, scalarData, offset);
+    cache.decrementImageCacheSize(image.sizeInBytes);
+  });
+}
+
+function _updateImageWithScalarDataView(image, scalarData, offset) {
+  const pixelData = image.imageFrame
+    ? image.imageFrame.pixelData
+    : image.getPixelData();
+
+  const view = new pixelData.constructor(
+    scalarData.buffer,
+    offset,
+    pixelData.length
+  );
+
+  image.getPixelData = () => view;
+
+  if (image.imageFrame) {
+    image.imageFrame.pixelData = view;
+  }
+
+  image.bufferView = {
+    buffer: scalarData.buffer,
+    offset,
+  };
+}