@cornerstonejs/core 1.42.0 → 1.43.0

package/src/loaders/imageLoader.ts

@@ -1,4 +1,5 @@
 import cache from '../cache/cache';
+import { ImageVolume } from '../cache';
 import Events from '../enums/Events';
 import eventTarget from '../eventTarget';
 import {
@@ -120,11 +121,14 @@ function loadImageFromCacheOrVolume(
   // 2. Check if there exists a volume in the cache containing the imageId,
   // we copy the pixelData over.
   const cachedVolumeInfo = cache.getVolumeContainingImageId(imageId);
-  if (cachedVolumeInfo && cachedVolumeInfo.volume.loadStatus.loaded) {
+  if (cachedVolumeInfo?.volume?.loadStatus?.loaded) {
     // 2.1 Convert the volume at the specific slice to a cornerstoneImage object.
     // this will copy the pixel data over.
     const { volume, imageIdIndex } = cachedVolumeInfo;
-    imageLoadObject = volume.convertToCornerstoneImage(imageId, imageIdIndex);
+
+    if (volume instanceof ImageVolume) {
+      imageLoadObject = volume.convertToCornerstoneImage(imageId, imageIdIndex);
+    }
     return imageLoadObject;
   }
   // 3. If no volume found, we search inside the imageCache for the imageId
@@ -285,11 +289,16 @@ export function createAndCacheDerivedImage(
  * Load and cache a list of imageIds
  *
  * @param referencedImageIds - list of imageIds
- * @param getDerivedImageId - optional function to generate derived imageId name however you want
+ * @param options
+ * @param options.getDerivedImageId - function to get the derived imageId
+ * @param options.targetBufferType - target buffer type
  */
 export function createAndCacheDerivedImages(
   referencedImageIds: Array<string>,
-  getDerivedImageId?: (referencedImageId: string) => string
+  options: {
+    getDerivedImageId?: (referencedImageId: string) => string;
+    targetBufferType?: PixelDataTypedArrayString;
+  } = {}
 ): DerivedImages {
   if (referencedImageIds?.length === 0) {
     throw new Error(
@@ -298,14 +307,15 @@ export function createAndCacheDerivedImages(
   }
 
   const derivedImageIds = [];
-  const allPromises = referencedImageIds.map((referencedImageId, index) => {
-    const options: DerivedImageOptions = {
-      imageId: getDerivedImageId
-        ? getDerivedImageId(referencedImageId)
+  const allPromises = referencedImageIds.map((referencedImageId) => {
+    const newOptions: DerivedImageOptions = {
+      imageId: options.getDerivedImageId
+        ? options.getDerivedImageId(referencedImageId)
         : `derived:${uuidv4()}`,
+      ...options,
     };
-    derivedImageIds.push(options.imageId);
-    return createAndCacheDerivedImage(referencedImageId, options);
+    derivedImageIds.push(newOptions.imageId);
+    return createAndCacheDerivedImage(referencedImageId, newOptions);
   });
 
   return { imageIds: derivedImageIds, promises: allPromises };
@@ -497,3 +507,41 @@ export function unregisterAllImageLoaders(): void {
   );
   unknownImageLoader = undefined;
 }
+
+/**
+ * Creates and caches derived segmentation images based on the referenced imageIds, this
+ * is a helper function, we don't have segmentation concept in the cornerstone core; however,
+ * this helper would make it clear that the segmentation images SHOULD be Uint8Array type
+ * always until we have a better solution.
+ *
+ * @param referencedImageIds - An array of referenced image IDs.
+ * @param options - The options for creating the derived images (default: { targetBufferType: 'Uint8Array' }).
+ * @returns The derived images.
+ */
+export function createAndCacheDerivedSegmentationImages(
+  referencedImageIds: Array<string>,
+  options: DerivedImageOptions = {
+    targetBufferType: 'Uint8Array',
+  }
+): DerivedImages {
+  return createAndCacheDerivedImages(referencedImageIds, options);
+}
+
+/**
+ * Creates and caches a derived segmentation image based on the referenced image ID.
+ * this is a helper function, we don't have segmentation concept in the cornerstone core; however,
+ * this helper would make it clear that the segmentation images SHOULD be Uint8Array type
+ * always until we have a better solution.
+ *
+ * @param referencedImageId The ID of the referenced image.
+ * @param options The options for creating the derived image (default: { targetBufferType: 'Uint8Array' }).
+ * @returns A promise that resolves to the created derived segmentation image.
+ */
+export function createAndCacheDerivedSegmentationImage(
+  referencedImageId: string,
+  options: DerivedImageOptions = {
+    targetBufferType: 'Uint8Array',
+  }
+): Promise<IImage> {
+  return createAndCacheDerivedImage(referencedImageId, options);
+}

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,36 @@ 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;
+}
+
+/**
+ * Creates and caches a derived segmentation volume based on a referenced volume.
+ * This is basically a utility method since for the segmentations we have to specify
+ * Uint8Array as the targetBuffer type for now until we support other types.
+ *
+ * @param referencedVolumeId - The ID of the referenced volume.
+ * @param options - The options for creating the derived volume.
+ * @returns A promise that resolves to the created derived segmentation volume.
+ */
+export async function createAndCacheDerivedSegmentationVolume(
+  referencedVolumeId: string,
+  options: DerivedVolumeOptions
+): Promise<IImageVolume> {
+  return createAndCacheDerivedVolume(referencedVolumeId, {
+    ...options,
+    targetBuffer: {
+      type: 'Uint8Array',
+    },
+  });
+}

package/src/types/BoundsLPS.ts

@@ -0,0 +1,5 @@
+import type Point2 from './Point3';
+
+type BoundsLPS = [Point2, Point2, Point2];
+
+export default BoundsLPS;

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/IViewport.ts

@@ -6,7 +6,6 @@ import { ActorEntry } from './IActor';
 import ViewportType from '../enums/ViewportType';
 import ViewportStatus from '../enums/ViewportStatus';
 import DisplayArea from './displayArea';
-import { IRetrieveConfiguration } from './IRetrieveConfiguration';
 
 /**
  * Viewport interface for cornerstone viewports
@@ -66,6 +65,8 @@ interface IViewport {
   addActors(actors: Array<ActorEntry>): void;
   /** add one actor */
   addActor(actorEntry: ActorEntry): void;
+  /** get actor UIDs */
+  getActorUIDs(): Array<string>;
   /** remove all actors from the viewport */
   removeAllActors(): void;
   /** remove array of uids */

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