@cornerstonejs/core 1.32.2 → 1.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cornerstonejs/core",
-  "version": "1.32.2",
+  "version": "1.33.0",
   "description": "",
   "main": "src/index.ts",
   "types": "dist/types/index.d.ts",
@@ -47,5 +47,5 @@
     "type": "individual",
     "url": "https://ohif.org/donate"
   },
-  "gitHead": "c6c2dfdee7f3b1137fae77d9154809267076dc87"
+  "gitHead": "bcfcf24cacbc6d230a3ddc722823d5ecc05cbb6d"
 }

package/src/RenderingEngine/StackViewport.ts

@@ -21,6 +21,7 @@ import {
   isImageActor,
   actorIsA,
   colormap as colormapUtils,
+  updateVTKImageDataWithCornerstoneImage,
   imageRetrieveMetadataProvider,
 } from '../utilities';
 import type {
@@ -44,6 +45,7 @@ import type {
   Mat3,
   ColormapPublic,
   IImageCalibration,
+  IStackInput,
   IImagesLoader,
   ImageLoadListener,
 } from '../types';
@@ -1489,7 +1491,7 @@ class StackViewport extends Viewport implements IStackViewport, IImagesLoader {
    * @returns image metadata: bitsAllocated, number of components, origin,
    *  direction, dimensions, spacing, number of voxels.
    */
-  private _getImageDataMetadata(image: IImage): ImageDataMetaData {
+  public getImageDataMetadata(image: IImage): ImageDataMetaData {
     // TODO: Creating a single image should probably not require a metadata provider.
     // We should define the minimum we need to display an image and it should live on
     // the Image object itself. Additional stuff (e.g. pixel spacing, direction, origin, etc)
@@ -1582,21 +1584,14 @@ class StackViewport extends Viewport implements IStackViewport, IImagesLoader {
     };
   }
 
-  /**
-   * Creates vtkImagedata based on the image object, it creates
-   * and empty scalar data for the image based on the metadata
-   * tags (e.g., bitsAllocated)
-   *
-   * @param image - cornerstone Image object
-   */
-  private _createVTKImageData({
+  createVTKImageData({
     origin,
     direction,
     dimensions,
     spacing,
     numComps,
     pixelArray,
-  }): void {
+  }) {
     const values = new pixelArray.constructor(pixelArray.length);
 
     // Todo: I guess nothing should be done for use16bit?
@@ -1606,13 +1601,39 @@ class StackViewport extends Viewport implements IStackViewport, IImagesLoader {
       values: values,
     });
 
-    this._imageData = vtkImageData.newInstance();
+    const imageData = vtkImageData.newInstance();
 
-    this._imageData.setDimensions(dimensions);
-    this._imageData.setSpacing(spacing);
-    this._imageData.setDirection(direction);
-    this._imageData.setOrigin(origin);
-    this._imageData.getPointData().setScalars(scalarArray);
+    imageData.setDimensions(dimensions);
+    imageData.setSpacing(spacing);
+    imageData.setDirection(direction);
+    imageData.setOrigin(origin);
+    imageData.getPointData().setScalars(scalarArray);
+
+    return imageData;
+  }
+  /**
+   * Creates vtkImagedata based on the image object, it creates
+   * empty scalar data for the image based on the metadata
+   * tags (e.g., bitsAllocated)
+   *
+   * @param image - cornerstone Image object
+   */
+  private _createVTKImageData({
+    origin,
+    direction,
+    dimensions,
+    spacing,
+    numComps,
+    pixelArray,
+  }): void {
+    this._imageData = this.createVTKImageData({
+      origin,
+      direction,
+      dimensions,
+      spacing,
+      numComps,
+      pixelArray,
+    });
   }
 
   /**
@@ -1750,40 +1771,7 @@ class StackViewport extends Viewport implements IStackViewport, IImagesLoader {
 
     // Update the pixel data in the vtkImageData object with the pixelData
     // from the loaded Cornerstone image
-    this._updatePixelData(image);
-  }
-
-  private _updatePixelData(image: IImage) {
-    const pixelData = image.getPixelData();
-    const scalars = this._imageData.getPointData().getScalars();
-    const scalarData = scalars.getData() as
-      | Uint8Array
-      | Float32Array
-      | Uint16Array
-      | Int16Array;
-
-    // if the color image is loaded with CPU previously, it loads it
-    // with RGBA, and here we need to remove the A channel from the
-    // pixel data.
-    if (image.color && image.rgba) {
-      const newPixelData = new Uint8Array(image.columns * image.rows * 3);
-      for (let i = 0; i < image.columns * image.rows; i++) {
-        newPixelData[i * 3] = pixelData[i * 4];
-        newPixelData[i * 3 + 1] = pixelData[i * 4 + 1];
-        newPixelData[i * 3 + 2] = pixelData[i * 4 + 2];
-      }
-      // modify the image object to have the correct pixel data for later
-      // use.
-      image.rgba = false;
-      image.getPixelData = () => newPixelData;
-      scalarData.set(newPixelData);
-    } else {
-      scalarData.set(pixelData);
-    }
-
-    // Trigger modified on the VTK Object so the texture is updated
-    // TODO: evaluate directly changing things with texSubImage3D later
-    this._imageData.modified();
+    updateVTKImageDataWithCornerstoneImage(this._imageData, image);
   }
 
   /**
@@ -2117,7 +2105,7 @@ class StackViewport extends Viewport implements IStackViewport, IImagesLoader {
   };
 
   private _updateToDisplayImageCPU(image: IImage) {
-    const metadata = this._getImageDataMetadata(image) as ImageDataMetaData;
+    const metadata = this.getImageDataMetadata(image) as ImageDataMetaData;
 
     const viewport = getDefaultViewport(
       this.canvas,
@@ -2159,6 +2147,43 @@ class StackViewport extends Viewport implements IStackViewport, IImagesLoader {
     );
   }
 
+  /**
+   * This method is used to add images to the stack viewport.
+   * It takes an array of stack inputs, each containing an imageId and an actor UID.
+   * For each stack input, it retrieves the image from the cache and creates a VTK image data object.
+   * It then creates an actor mapper for the image data and adds it to the list of actors.
+   * Finally, it sets the actors for the stack viewport.
+   *
+   * @param  stackInputs - An array of stack inputs, each containing an image ID and an actor UID.
+   */
+  public async addImages(stackInputs: Array<IStackInput>): Promise<void> {
+    const actors = this.getActors();
+    stackInputs.forEach((stackInput) => {
+      const image = cache.getImage(stackInput.imageId);
+
+      const { origin, dimensions, direction, spacing, numComps } =
+        this.getImageDataMetadata(image);
+
+      const imagedata = this.createVTKImageData({
+        origin,
+        dimensions,
+        direction,
+        spacing,
+        numComps,
+        pixelArray: image.getPixelData(),
+      });
+
+      const imageActor = this.createActorMapper(imagedata);
+      if (imageActor) {
+        actors.push({ uid: stackInput.actorUID, actor: imageActor });
+        if (stackInput.callback) {
+          stackInput.callback({ imageActor, imageId: stackInput.imageId });
+        }
+      }
+    });
+    this.setActors(actors);
+  }
+
   /**
    * It updates the volume actor with the retrieved cornerstone image.
    * It first checks if the new image has the same dimensions, spacings, and
@@ -2245,7 +2270,7 @@ class StackViewport extends Viewport implements IStackViewport, IImagesLoader {
       spacing,
       numComps,
       imagePixelModule,
-    } = this._getImageDataMetadata(image);
+    } = this.getImageDataMetadata(image);
 
     // 3b. If we cannot reuse the vtkImageData object (either the first render
     // or the size has changed), create a new one

package/src/RenderingEngine/helpers/addImageSlicesToViewports.ts

@@ -0,0 +1,54 @@
+import { StackViewport } from '..';
+import type {
+  IStackViewport,
+  IStackInput,
+  IRenderingEngine,
+} from '../../types';
+
+/**
+ * For each provided viewport it adds a volume to the viewport using the
+ * provided renderingEngine
+ *
+ *
+ * @param renderingEngine - The rendering engine to use to get viewports from
+ * @param volumeInputs - Array of volume inputs including volumeId. Other properties
+ * such as visibility, callback, blendMode, slabThickness are optional
+ * @param viewportIds - Array of viewport IDs to add the volume to
+ * @param immediateRender - If true, the volumes will be rendered immediately
+ * @returns A promise that resolves when all volumes have been added
+ */
+async function addImageSlicesToViewports(
+  renderingEngine: IRenderingEngine,
+  stackInputs: Array<IStackInput>,
+  viewportIds: Array<string>,
+  immediateRender = false,
+  suppressEvents = false
+): Promise<void> {
+  // Check if all viewports are volumeViewports
+  for (const viewportId of viewportIds) {
+    const viewport = renderingEngine.getViewport(viewportId);
+
+    if (!viewport) {
+      throw new Error(`Viewport with Id ${viewportId} does not exist`);
+    }
+
+    // if not instance of BaseVolumeViewport, throw
+    if (!(viewport instanceof StackViewport)) {
+      console.warn(
+        `Viewport with Id ${viewportId} is not a StackViewport. Cannot add image segmentation to this viewport.`
+      );
+
+      return;
+    }
+  }
+
+  const addStackPromises = viewportIds.map(async (viewportId) => {
+    const viewport = renderingEngine.getViewport(viewportId) as IStackViewport;
+
+    return viewport.addImages(stackInputs, immediateRender, suppressEvents);
+  });
+
+  await Promise.all(addStackPromises);
+}
+
+export default addImageSlicesToViewports;

package/src/RenderingEngine/helpers/index.ts

@@ -4,6 +4,7 @@ import getOrCreateCanvas from './getOrCreateCanvas';
 import setVolumesForViewports from './setVolumesForViewports';
 import addVolumesToViewports from './addVolumesToViewports';
 import volumeNewImageEventDispatcher from './volumeNewImageEventDispatcher';
+import addImageSlicesToViewports from './addImageSlicesToViewports';
 
 export {
   createVolumeActor,
@@ -11,5 +12,6 @@ export {
   getOrCreateCanvas,
   setVolumesForViewports,
   addVolumesToViewports,
+  addImageSlicesToViewports,
   volumeNewImageEventDispatcher,
 };

package/src/cache/cache.ts

@@ -655,6 +655,28 @@ class Cache implements ICache {
     return cachedGeometry.geometry;
   };
 
+  /**
+   * Returns the image associated with the imageId
+   *
+   * @param imageId - image ID
+   * @returns Image
+   */
+  public getImage = (imageId: string): IImage => {
+    if (imageId === undefined) {
+      throw new Error('getImage: imageId must not be undefined');
+    }
+    const cachedImage = this._imageCache.get(imageId);
+
+    if (cachedImage === undefined) {
+      return;
+    }
+
+    // Bump time stamp for cached volume (not used for anything for now)
+    cachedImage.timeStamp = Date.now();
+
+    return cachedImage.image;
+  };
+
   /**
    * Returns the volume associated with the volumeId
    *

package/src/index.ts

@@ -67,6 +67,7 @@ import triggerEvent from './utilities/triggerEvent';
 import {
   setVolumesForViewports,
   addVolumesToViewports,
+  addImageSlicesToViewports,
 } from './RenderingEngine/helpers';
 
 // Add new types here so that they can be imported singly as required.
@@ -127,6 +128,7 @@ export {
   utilities,
   setVolumesForViewports,
   addVolumesToViewports,
+  addImageSlicesToViewports,
   //
   imageLoadPoolManager as requestPoolManager,
   imageRetrievalPoolManager,

package/src/loaders/imageLoader.ts

@@ -1,15 +1,51 @@
 import cache from '../cache/cache';
 import Events from '../enums/Events';
 import eventTarget from '../eventTarget';
-import { triggerEvent } from '../utilities';
-import { IImage, ImageLoaderFn, IImageLoadObject, EventTypes } from '../types';
+import {
+  genericMetadataProvider,
+  getBufferConfiguration,
+  triggerEvent,
+  uuidv4,
+} from '../utilities';
+import {
+  IImage,
+  ImageLoaderFn,
+  IImageLoadObject,
+  EventTypes,
+  Point2,
+  Point3,
+  Mat3,
+  PixelDataTypedArrayString,
+  PixelDataTypedArray,
+} from '../types';
 import imageLoadPoolManager from '../requestPool/imageLoadPoolManager';
+import { metaData } from '../';
 
 export interface ImageLoaderOptions {
   priority: number;
   requestType: string;
   additionalDetails?: Record<string, unknown>;
 }
+
+interface DerivedImageOptions {
+  imageId?: string;
+  targetBufferType?: PixelDataTypedArrayString;
+}
+
+interface DerivedImages {
+  imageIds: Array<string>;
+  promises: Array<Promise<IImage>>;
+}
+
+interface LocalImageOptions {
+  scalarData?: PixelDataTypedArray;
+  targetBufferType?: PixelDataTypedArrayString;
+  dimensions?: Point2;
+  spacing?: Point3;
+  origin?: Point3;
+  direction?: Mat3;
+}
+
 /**
  * This module deals with ImageLoaders, loading images and caching images
  */
@@ -183,6 +219,170 @@ export function loadAndCacheImages(
   return allPromises;
 }
 
+/**
+ * Loads an image given an imageId and optional priority and returns a promise
+ * which will resolve to the loaded image object or fail if an error occurred.
+ * The image is stored in the cache.
+ *
+ * @param referencedImageId -  A Cornerstone Image Object's imageId
+ * @param options - Options to be passed to the Image Loader
+ *
+ * @returns Image Loader Object
+ */
+export function createAndCacheDerivedImage(
+  referencedImageId: string,
+  options: DerivedImageOptions = {},
+  preventCache = false
+): Promise<IImage> {
+  if (referencedImageId === undefined) {
+    throw new Error(
+      'createAndCacheDerivedImage: parameter imageId must not be undefined'
+    );
+  }
+
+  if (options.imageId === undefined) {
+    options.imageId = `derived:${uuidv4()}`;
+  }
+
+  const imagePlaneModule = metaData.get('imagePlaneModule', referencedImageId);
+
+  const length = imagePlaneModule.rows * imagePlaneModule.columns;
+
+  const { TypedArrayConstructor } = getBufferConfiguration(
+    options.targetBufferType,
+    length
+  );
+
+  const imageScalarData = new TypedArrayConstructor(length);
+  const derivedImageId = options.imageId;
+
+  ['imagePixelModule', 'imagePlaneModule', 'generalSeriesModule'].forEach(
+    (type) => {
+      genericMetadataProvider.add(derivedImageId, {
+        type,
+        metadata: metaData.get(type, referencedImageId),
+      });
+    }
+  );
+
+  const localImage = createAndCacheLocalImage(
+    { scalarData: imageScalarData },
+    options.imageId,
+    true
+  );
+
+  const imageLoadObject = {
+    promise: Promise.resolve(localImage),
+  };
+
+  if (!preventCache) {
+    cache.putImageLoadObject(derivedImageId, imageLoadObject);
+  }
+  return imageLoadObject.promise;
+}
+
+/**
+ * Load and cache a list of imageIds
+ *
+ * @param referencedImageIds - list of imageIds
+ * @param getDerivedImageId - optional function to generate derived imageId name however you want
+ */
+export function createAndCacheDerivedImages(
+  referencedImageIds: Array<string>,
+  getDerivedImageId?: (referencedImageId: string) => string
+): DerivedImages {
+  if (referencedImageIds?.length === 0) {
+    throw new Error(
+      'createAndCacheDerivedImages: parameter imageIds must be list of image Ids'
+    );
+  }
+
+  const derivedImageIds = [];
+  const allPromises = referencedImageIds.map((referencedImageId, index) => {
+    const options: DerivedImageOptions = {
+      imageId: getDerivedImageId
+        ? getDerivedImageId(referencedImageId)
+        : `derived:${uuidv4()}`,
+    };
+    derivedImageIds.push(options.imageId);
+    return createAndCacheDerivedImage(referencedImageId, options);
+  });
+
+  return { imageIds: derivedImageIds, promises: allPromises };
+}
+
+export function createAndCacheLocalImage(
+  options: LocalImageOptions,
+  imageId: string,
+  preventCache = false
+): IImage {
+  const imagePlaneModule = metaData.get('imagePlaneModule', imageId);
+
+  const length = imagePlaneModule.rows * imagePlaneModule.columns;
+
+  const image = {
+    imageId: imageId,
+    intercept: 0,
+    windowCenter: 0,
+    windowWidth: 0,
+    color: false,
+    numComps: 1,
+    slope: 1,
+    minPixelValue: 0,
+    maxPixelValue: 255,
+    voiLUTFunction: undefined,
+    rows: imagePlaneModule.rows,
+    columns: imagePlaneModule.columns,
+    getCanvas: undefined, // todo: which canvas?
+    height: imagePlaneModule.rows,
+    width: imagePlaneModule.columns,
+    rgba: undefined, // todo: how
+    columnPixelSpacing: imagePlaneModule.columnPixelSpacing,
+    rowPixelSpacing: imagePlaneModule.rowPixelSpacing,
+    invert: false,
+  } as IImage;
+
+  if (options.scalarData) {
+    const imageScalarData = options.scalarData;
+
+    if (
+      !(
+        imageScalarData instanceof Uint8Array ||
+        imageScalarData instanceof Float32Array ||
+        imageScalarData instanceof Uint16Array ||
+        imageScalarData instanceof Int16Array
+      )
+    ) {
+      throw new Error(
+        'To use createLocalVolume you should pass scalarData of type Uint8Array, Uint16Array, Int16Array or Float32Array'
+      );
+    }
+
+    image.sizeInBytes = imageScalarData.byteLength;
+    image.getPixelData = () => imageScalarData;
+  } else {
+    const { numBytes, TypedArrayConstructor } = getBufferConfiguration(
+      options.targetBufferType,
+      length
+    );
+
+    const imageScalarData = new TypedArrayConstructor(length);
+
+    image.sizeInBytes = numBytes;
+    image.getPixelData = () => imageScalarData;
+  }
+
+  const imageLoadObject = {
+    promise: Promise.resolve(image),
+  };
+
+  if (!preventCache) {
+    cache.putImageLoadObject(image.imageId, imageLoadObject);
+  }
+
+  return image;
+}
+
 /**
  * Removes the imageId from the request pool manager and executes the `cancel`
  * function if it exists.

package/src/loaders/volumeLoader.ts

@@ -11,8 +11,14 @@ 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 { getBufferConfiguration, uuidv4 } from '../utilities';
+import {
+  Point3,
+  Metadata,
+  EventTypes,
+  Mat3,
+  PixelDataTypedArray,
+} from '../types';
 import { getConfiguration } from '../init';
 
 interface VolumeLoaderOptions {
@@ -27,7 +33,7 @@ interface DerivedVolumeOptions {
   };
 }
 interface LocalVolumeOptions {
-  scalarData: Float32Array | Uint8Array | Uint16Array | Int16Array;
+  scalarData: PixelDataTypedArray;
   metadata: Metadata;
   dimensions: Point3;
   spacing: Point3;
@@ -272,32 +278,17 @@ 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');
+  const { TypedArrayConstructor, numBytes } = getBufferConfiguration(
+    targetBuffer?.type,
+    scalarLength,
+    {
+      use16BitTexture: useNorm16Texture,
+      isVolumeBuffer: true,
     }
-  } 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);
@@ -308,9 +299,9 @@ export async function createAndCacheDerivedVolume(
   let volumeScalarData;
   if (targetBuffer?.sharedArrayBuffer) {
     const buffer = new SharedArrayBuffer(numBytes);
-    volumeScalarData = new TypedArray(buffer);
+    volumeScalarData = new TypedArrayConstructor(buffer);
   } else {
-    volumeScalarData = new TypedArray(scalarLength);
+    volumeScalarData = new TypedArrayConstructor(scalarLength);
   }
 
   // Todo: handle more than one component for segmentation (RGB)

package/src/types/IImage.ts

@@ -10,6 +10,8 @@ import { ImageQualityStatus } from '../enums';
 interface IImage {
   /** Image Id */
   imageId: string;
+  /** referenced imageId if this image is derived from */
+  referencedImageId?: string;
   sharedCacheKey?: string;
   /** Whether the image is Pre-scaled during loading */
   isPreScaled?: boolean;

package/src/types/IStackInput.ts

@@ -0,0 +1,30 @@
+import { ImageActor } from './IActor';
+
+/**
+ * Stack input callback type, used to perform operations on the image data
+ * after it has been loaded.
+ */
+type StackInputCallback = (params: {
+  /** vtk image actor */
+  imageActor: ImageActor;
+  /** unique image Id in the cache */
+  imageId: string;
+}) => unknown;
+
+/**
+ * StackInput that can be used to add an image actor  to a viewport. It includes
+ * mandatory `imageId` but other options such as `visibility` and `callback`
+ * can also be provided
+ */
+interface IStackInput {
+  /** imageId of the image in the cache */
+  imageId: string;
+  // actorUID of the imageActor being added
+  actorUID?: string;
+  /** Visibility of the image actor - by default it is true */
+  visibility?: boolean;
+  /** Callback to be called when the image is added to the viewport */
+  callback?: StackInputCallback;
+}
+
+export type { IStackInput, StackInputCallback };