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

package/src/loaders/volumeLoader.ts

@@ -3,17 +3,39 @@ 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 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 { uuidv4 } from '../utilities';
-import { Point3, Metadata, EventTypes, Mat3 } from '../types';
-import { getConfiguration } from '../init';
+import cloneDeep from 'lodash.clonedeep';
+
+import {
+  createUint16SharedArray,
+  createUint8SharedArray,
+  createFloat32SharedArray,
+  generateVolumePropsFromImageIds,
+  getBufferConfiguration,
+  uuidv4,
+} from '../utilities';
+import {
+  Point3,
+  Metadata,
+  EventTypes,
+  Mat3,
+  IImageVolume,
+  VolumeLoaderFn,
+  IDynamicImageVolume,
+  PixelDataTypedArray,
+  IVolumeLoadObject,
+  PixelDataTypedArrayString,
+} from '../types';
+import { getConfiguration, getShouldUseSharedArrayBuffer } from '../init';
+import {
+  performCacheOptimizationForVolume,
+  setupCacheOptimizationEventListener,
+} from '../utilities/cacheUtils';
 
 interface VolumeLoaderOptions {
   imageIds: Array<string>;
@@ -22,17 +44,24 @@ interface VolumeLoaderOptions {
 interface DerivedVolumeOptions {
   volumeId: string;
   targetBuffer?: {
-    type: 'Float32Array' | 'Uint8Array' | 'Uint16Array' | 'Int16Array';
+    type: PixelDataTypedArrayString;
     sharedArrayBuffer?: boolean;
   };
 }
 interface LocalVolumeOptions {
-  scalarData: Float32Array | Uint8Array | Uint16Array | Int16Array;
   metadata: Metadata;
   dimensions: Point3;
   spacing: Point3;
   origin: Point3;
   direction: Mat3;
+  scalarData?: PixelDataTypedArray;
+  imageIds?: Array<string>;
+  referencedImageIds?: Array<string>;
+  referencedVolumeId?: string;
+  targetBuffer?: {
+    type: PixelDataTypedArrayString;
+    sharedArrayBuffer?: boolean;
+  };
 }
 
 /**
@@ -40,7 +69,7 @@ interface LocalVolumeOptions {
  */
 function addScalarDataToImageData(
   imageData: vtkImageDataType,
-  scalarData: Types.VolumeScalarData,
+  scalarData: PixelDataTypedArray,
   dataArrayAttrs
 ) {
   const scalarArray = vtkDataArray.newInstance({
@@ -57,7 +86,7 @@ function addScalarDataToImageData(
  */
 function addScalarDataArraysToImageData(
   imageData: vtkImageDataType,
-  scalarDataArrays: Types.VolumeScalarData[],
+  scalarDataArrays: PixelDataTypedArray[],
   dataArrayAttrs
 ) {
   scalarDataArrays.forEach((scalarData, i) => {
@@ -75,7 +104,7 @@ function addScalarDataArraysToImageData(
 }
 
 function createInternalVTKRepresentation(
-  volume: Types.IImageVolume
+  volume: IImageVolume
 ): vtkImageDataType {
   const { dimensions, metadata, spacing, direction, origin } = volume;
   const { PhotometricInterpretation } = metadata;
@@ -95,7 +124,7 @@ function createInternalVTKRepresentation(
 
   // Add scalar data to 3D or 4D volume
   if (volume.isDynamicVolume()) {
-    const scalarDataArrays = (<Types.IDynamicImageVolume>(
+    const scalarDataArrays = (<IDynamicImageVolume>(
       volume
     )).getScalarDataArrays();
 
@@ -132,24 +161,29 @@ let unknownVolumeLoader;
  */
 function loadVolumeFromVolumeLoader(
   volumeId: string,
-  options: VolumeLoaderOptions
-): Types.IVolumeLoadObject {
+  options?: VolumeLoaderOptions
+): 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) {
@@ -180,7 +214,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');
   }
@@ -193,7 +227,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;
   });
@@ -210,7 +244,7 @@ export function loadVolume(
  */
 export async function createAndCacheVolume(
   volumeId: string,
-  options: VolumeLoaderOptions
+  options?: VolumeLoaderOptions
 ): Promise<Record<string, any>> {
   if (volumeId === undefined) {
     throw new Error(
@@ -226,7 +260,7 @@ export async function createAndCacheVolume(
 
   volumeLoadObject = loadVolumeFromVolumeLoader(volumeId, options);
 
-  volumeLoadObject.promise.then((volume: Types.IImageVolume) => {
+  volumeLoadObject.promise.then((volume: IImageVolume) => {
     volume.imageData = createInternalVTKRepresentation(volume);
   });
 
@@ -252,9 +286,8 @@ export async function createAndCacheVolume(
 export async function createAndCacheDerivedVolume(
   referencedVolumeId: string,
   options: DerivedVolumeOptions
-): Promise<ImageVolume> {
+): Promise<IImageVolume> {
   const referencedVolume = cache.getVolume(referencedVolumeId);
-
   if (!referencedVolume) {
     throw new Error(
       `Cannot created derived volume: Referenced volume with id ${referencedVolumeId} does not exist.`
@@ -272,46 +305,10 @@ export async function createAndCacheDerivedVolume(
   const scalarData = referencedVolume.getScalarData();
   const scalarLength = scalarData.length;
 
-  let numBytes, TypedArray;
-
-  const { useNorm16Texture } = getConfiguration().rendering;
-
-  // If target buffer is provided
-  if (targetBuffer) {
-    if (targetBuffer.type === 'Float32Array') {
-      numBytes = scalarLength * 4;
-      TypedArray = Float32Array;
-    } else if (targetBuffer.type === 'Uint8Array') {
-      numBytes = scalarLength;
-      TypedArray = Uint8Array;
-    } else if (useNorm16Texture && targetBuffer.type === 'Uint16Array') {
-      numBytes = scalarLength * 2;
-      TypedArray = Uint16Array;
-    } else if (useNorm16Texture && targetBuffer.type === 'Int16Array') {
-      numBytes = scalarLength * 2;
-      TypedArray = Uint16Array;
-    } else {
-      throw new Error('TargetBuffer should be Float32Array or Uint8Array');
-    }
-  } else {
-    // Use float32 if no targetBuffer is provided
-    numBytes = scalarLength * 4;
-    TypedArray = Float32Array;
-  }
-
-  // check if there is enough space in unallocated + image Cache
-  const isCacheable = cache.isCacheable(numBytes);
-  if (!isCacheable) {
-    throw new Error(Events.CACHE_SIZE_EXCEEDED);
-  }
-
-  let volumeScalarData;
-  if (targetBuffer?.sharedArrayBuffer) {
-    const buffer = new SharedArrayBuffer(numBytes);
-    volumeScalarData = new TypedArray(buffer);
-  } else {
-    volumeScalarData = new TypedArray(scalarLength);
-  }
+  const { volumeScalarData, numBytes } = generateVolumeScalarData(
+    targetBuffer,
+    scalarLength
+  );
 
   // Todo: handle more than one component for segmentation (RGB)
   const scalarArray = vtkDataArray.newInstance({
@@ -330,7 +327,7 @@ export async function createAndCacheDerivedVolume(
 
   const derivedVolume = new ImageVolume({
     volumeId,
-    metadata: cloneDeep(metadata),
+    metadata: structuredClone(metadata),
     dimensions: [dimensions[0], dimensions[1], dimensions[2]],
     spacing,
     origin,
@@ -338,6 +335,7 @@ export async function createAndCacheDerivedVolume(
     imageData: derivedImageData,
     scalarData: volumeScalarData,
     sizeInBytes: numBytes,
+    imageIds: [],
     referencedVolumeId,
   });
 
@@ -364,22 +362,36 @@ export function createLocalVolume(
   options: LocalVolumeOptions,
   volumeId: string,
   preventCache = false
-): ImageVolume {
-  const { scalarData, metadata, dimensions, spacing, origin, direction } =
+): IImageVolume {
+  const { metadata, dimensions, spacing, origin, direction, targetBuffer } =
     options;
 
-  if (
-    !scalarData ||
-    !(
-      scalarData instanceof Uint8Array ||
-      scalarData instanceof Float32Array ||
-      scalarData instanceof Uint16Array ||
-      scalarData instanceof Int16Array
-    )
-  ) {
-    throw new Error(
-      'To use createLocalVolume you should pass scalarData of type Uint8Array, Uint16Array, Int16Array or Float32Array'
-    );
+  let { scalarData } = options;
+
+  // Define the valid data types for scalarData
+  const validDataTypes = [
+    'Uint8Array',
+    'Float32Array',
+    'Uint16Array',
+    'Int16Array',
+  ];
+
+  const scalarLength = dimensions[0] * dimensions[1] * dimensions[2];
+
+  // Check if scalarData is provided and is of a valid type
+  if (!scalarData || !validDataTypes.includes(scalarData.constructor.name)) {
+    // Check if targetBuffer is provided and has a valid type
+    if (!targetBuffer?.type || !validDataTypes.includes(targetBuffer.type)) {
+      throw new Error(
+        'createLocalVolume: parameter scalarData must be provided and must be either Uint8Array, Float32Array, Uint16Array or Int16Array'
+      );
+    }
+
+    // Generate volume scalar data if scalarData is not provided or invalid
+    ({ volumeScalarData: scalarData } = generateVolumeScalarData(
+      targetBuffer,
+      scalarLength
+    ));
   }
 
   // Todo: handle default values for spacing, origin, direction if not provided
@@ -390,11 +402,9 @@ 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];
-
   const numBytes = scalarData ? scalarData.buffer.byteLength : scalarLength * 4;
 
   // check if there is enough space in unallocated + image Cache
@@ -419,7 +429,7 @@ export function createLocalVolume(
 
   const derivedVolume = new ImageVolume({
     volumeId,
-    metadata: cloneDeep(metadata),
+    metadata: structuredClone(metadata),
     dimensions: [dimensions[0], dimensions[1], dimensions[2]],
     spacing,
     origin,
@@ -427,6 +437,9 @@ export function createLocalVolume(
     imageData: imageData,
     scalarData,
     sizeInBytes: numBytes,
+    referencedImageIds: options.referencedImageIds || [],
+    referencedVolumeId: options.referencedVolumeId,
+    imageIds: options.imageIds || [],
   });
 
   if (preventCache) {
@@ -441,6 +454,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
  *
@@ -449,7 +534,7 @@ export function createLocalVolume(
  */
 export function registerVolumeLoader(
   scheme: string,
-  volumeLoader: Types.VolumeLoaderFn
+  volumeLoader: VolumeLoaderFn
 ): void {
   volumeLoaders[scheme] = volumeLoader;
 }
@@ -467,11 +552,119 @@ 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 = {} as DerivedVolumeOptions
+): Promise<IImageVolume> {
+  return createAndCacheDerivedVolume(referencedVolumeId, {
+    ...options,
+    targetBuffer: {
+      type: 'Uint8Array',
+    },
+  });
+}
+
+/**
+ * Creates a local segmentation volume.
+ *
+ * @param options - The options for creating the volume.
+ * @param volumeId - The ID of the volume.
+ * @param preventCache - Whether to prevent caching the volume.
+ * @returns A promise that resolves to the created image volume.
+ */
+export async function createLocalSegmentationVolume(
+  options: LocalVolumeOptions,
+  volumeId: string,
+  preventCache = false
+): Promise<IImageVolume> {
+  if (!options.scalarData) {
+    options.scalarData = new Uint8Array(
+      options.dimensions[0] * options.dimensions[1] * options.dimensions[2]
+    );
+  }
+
+  return createLocalVolume(options, volumeId, preventCache);
+}
+
+/**
+ * This function generates volume scalar data based on the provided target buffer and scalar length.
+ * It checks if the cache can accommodate the data size and throws an error if it exceeds the cache size.
+ * If a shared array buffer is available in the target buffer, it uses that to create the typed array.
+ * Otherwise, it creates a typed array based on the scalar length.
+ *
+ * @param targetBuffer - The target buffer object which may contain a type and a shared array buffer.
+ * @param scalarLength - The scalar length for creating the typed array.
+ * @param useNorm16Texture - A flag to specify whether to use a 16-bit texture or not.
+ * @returns The volume scalar data as a typed array.
+ */
+function generateVolumeScalarData(
+  targetBuffer: {
+    type: PixelDataTypedArrayString;
+    sharedArrayBuffer?: boolean;
+  },
+  scalarLength: number
+) {
+  const { useNorm16Texture } = getConfiguration().rendering;
+
+  const { TypedArrayConstructor, numBytes } = getBufferConfiguration(
+    targetBuffer?.type,
+    scalarLength,
+    {
+      use16BitTexture: useNorm16Texture,
+      isVolumeBuffer: true,
+    }
+  );
+
+  const isCacheable = cache.isCacheable(numBytes);
+  if (!isCacheable) {
+    throw new Error(Events.CACHE_SIZE_EXCEEDED);
+  }
+
+  let volumeScalarData;
+  if (targetBuffer?.sharedArrayBuffer ?? getShouldUseSharedArrayBuffer()) {
+    switch (targetBuffer.type) {
+      case 'Float32Array':
+        volumeScalarData = createFloat32SharedArray(scalarLength);
+        break;
+      case 'Uint8Array':
+        volumeScalarData = createUint8SharedArray(scalarLength);
+        break;
+      case 'Uint16Array':
+        volumeScalarData = createUint16SharedArray(scalarLength);
+        break;
+      case 'Int16Array':
+        volumeScalarData = createUint16SharedArray(scalarLength);
+        break;
+      default:
+        throw new Error(
+          'generateVolumeScalarData: SharedArrayBuffer is not supported for the specified target buffer type'
+        );
+    }
+  } else {
+    volumeScalarData = new TypedArrayConstructor(scalarLength);
+  }
+
+  return { volumeScalarData, numBytes };
+}

package/src/metaData.ts

@@ -11,7 +11,7 @@ const providers = [];
  * @category MetaData
  */
 export function addProvider(
-  provider: (type: string, query: any) => any,
+  provider: (type: string, ...query: string[]) => any,
   priority = 0
 ): void {
   let i;
@@ -66,14 +66,16 @@ export function removeAllProviders(): void {
  *
  * @param type -  The type of metadata requested from the metadata store
  * @param query - The query for the metadata store, often imageId
+ *        Some metadata providers support multi-valued strings, which are interpretted
+ *        as the provider chooses.
  *
  * @returns The metadata retrieved from the metadata store
  * @category MetaData
  */
-function getMetaData(type: string, query: string): any {
+function getMetaData(type: string, ...queries): any {
   // Invoke each provider in priority order until one returns something
   for (let i = 0; i < providers.length; i++) {
-    const result = providers[i].provider(type, query);
+    const result = providers[i].provider(type, ...queries);
 
     if (result !== undefined) {
       return result;

package/src/requestPool/requestPoolManager.ts

@@ -78,12 +78,14 @@ class RequestPoolManager {
     interaction: 0,
     thumbnail: 0,
     prefetch: 0,
+    compute: 0,
   };
   /* maximum number of requests of each type. */
   public maxNumRequests: {
     interaction: number;
     thumbnail: number;
     prefetch: number;
+    compute: number;
   };
   /* A public property that is used to set the delay between requests. */
   public grabDelay: number;
@@ -101,6 +103,7 @@ class RequestPoolManager {
       interaction: { 0: [] },
       thumbnail: { 0: [] },
       prefetch: { 0: [] },
+      compute: { 0: [] },
     };
 
     this.grabDelay = 5;
@@ -110,12 +113,20 @@ class RequestPoolManager {
       interaction: 0,
       thumbnail: 0,
       prefetch: 0,
+      compute: 0,
     };
 
     this.maxNumRequests = {
       interaction: 6,
       thumbnail: 6,
       prefetch: 5,
+      // I believe there is a bug right now, where if there are two workers
+      // and one wants to run a compute job 6 times and the limit is just 5, then
+      // the other worker will never get a chance to run its compute job.
+      // we should probably have a separate limit for compute jobs per worker
+      // context as there is another layer of parallelism there. For this reason
+      // I'm setting the limit to 1000 for now.
+      compute: 1000,
     };
   }
 
@@ -185,15 +196,7 @@ class RequestPoolManager {
     // Adding the request to the correct priority group of the request type
     this.requestPool[type][priority].push(requestDetails);
 
-    // Wake up
-    if (!this.awake) {
-      this.awake = true;
-      this.startGrabbing();
-    } else if (type === RequestType.Interaction) {
-      // Todo: this is a hack for interaction right now, we should separate
-      // the grabbing from the adding requests
-      this.startGrabbing();
-    }
+    this.startGrabbing();
   }
 
   /**
@@ -233,6 +236,7 @@ class RequestPoolManager {
 
   private sendRequests(type) {
     const requestsToSend = this.maxNumRequests[type] - this.numRequests[type];
+    let syncImageCount = 0;
 
     for (let i = 0; i < requestsToSend; i++) {
       const requestDetails = this.getNextRequest(type);
@@ -242,12 +246,28 @@ class RequestPoolManager {
         this.numRequests[type]++;
         this.awake = true;
 
-        requestDetails.requestFn().finally(() => {
+        let requestResult;
+        try {
+          requestResult = requestDetails.requestFn();
+        } catch (e) {
+          // This is the only warning one will get, so need a warn message
+          console.warn('sendRequest failed', e);
+        }
+        if (requestResult?.finally) {
+          requestResult.finally(() => {
+            this.numRequests[type]--;
+            this.startAgain();
+          });
+        } else {
+          // Handle non-async request functions too - typically just short circuit ones
           this.numRequests[type]--;
-          this.startAgain();
-        });
+          syncImageCount++;
+        }
       }
     }
+    if (syncImageCount) {
+      this.startAgain();
+    }
 
     return true;
   }
@@ -273,11 +293,13 @@ class RequestPoolManager {
     const hasRemainingPrefetchRequests = this.sendRequests(
       RequestType.Prefetch
     );
+    const hasRemainingComputeRequests = this.sendRequests(RequestType.Compute);
 
     if (
       !hasRemainingInteractionRequests &&
       !hasRemainingThumbnailRequests &&
-      !hasRemainingPrefetchRequests
+      !hasRemainingPrefetchRequests &&
+      !hasRemainingComputeRequests
     ) {
       this.awake = false;
     }
@@ -307,7 +329,7 @@ class RequestPoolManager {
     const priorities = Object.keys(this.requestPool[type])
       .map(Number)
       .filter((priority) => this.requestPool[type][priority].length)
-      .sort();
+      .sort((a, b) => a - b);
     return priorities;
   }
 
@@ -323,7 +345,4 @@ class RequestPoolManager {
   }
 }
 
-const requestPoolManager = new RequestPoolManager();
-
 export { RequestPoolManager };
-export default requestPoolManager;