@cornerstonejs/core 1.32.2 → 1.33.0

package/src/types/IStackViewport.ts

@@ -1,4 +1,3 @@
-import CPUFallbackColormapData from './CPUFallbackColormapData';
 import CPUIImageData from './CPUIImageData';
 import ICamera from './ICamera';
 import IImageData from './IImageData';
@@ -7,9 +6,8 @@ import Point2 from './Point2';
 import Point3 from './Point3';
 import { Scaling } from './ScalingParameters';
 import StackViewportProperties from './StackViewportProperties';
-import { ColormapPublic } from './Colormap';
 import type IImage from './IImage';
-
+import { IStackInput } from './IStackInput';
 /**
  * Interface for Stack Viewport
  */
@@ -93,7 +91,16 @@ export default interface IStackViewport extends IViewport {
    * Returns the currently rendered imageId
    */
   getCurrentImageId: () => string;
+  /**
+   * Add Image Slices actors to the viewport
+   */
+  addImages(
+    stackInputs: Array<IStackInput>,
+    immediateRender: boolean,
+    suppressEvents: boolean
+  );
 
+  getImageDataMetadata(image: IImage): any;
   /**
    * Custom rendering pipeline for the rendering for the CPU fallback
    */

package/src/types/PixelDataTypedArray.ts

@@ -5,3 +5,11 @@ export type PixelDataTypedArray =
   | Uint8Array
   | Int8Array
   | Uint8ClampedArray;
+
+export type PixelDataTypedArrayString =
+  | 'Float32Array'
+  | 'Int16Array'
+  | 'Uint16Array'
+  | 'Uint8Array'
+  | 'Int8Array'
+  | 'Uint8ClampedArray';

package/src/types/index.ts

@@ -62,6 +62,7 @@ import type CPUFallbackLookupTable from './CPUFallbackLookupTable';
 import type CPUFallbackLUT from './CPUFallbackLUT';
 import type CPUFallbackRenderingTools from './CPUFallbackRenderingTools';
 import type { IVolumeInput, VolumeInputCallback } from './IVolumeInput';
+import type { IStackInput, StackInputCallback } from './IStackInput';
 import type * as EventTypes from './EventTypes';
 import type IRenderingEngine from './IRenderingEngine';
 import type ActorSliceRange from './ActorSliceRange';
@@ -79,7 +80,10 @@ import type { IContour } from './IContour';
 import type RGB from './RGB';
 import { ColormapPublic, ColormapRegistration } from './Colormap';
 import type { ViewportProperties } from './ViewportProperties';
-import type { PixelDataTypedArray } from './PixelDataTypedArray';
+import type {
+  PixelDataTypedArray,
+  PixelDataTypedArrayString,
+} from './PixelDataTypedArray';
 import type { ImagePixelModule } from './ImagePixelModule';
 import type { ImagePlaneModule } from './ImagePlaneModule';
 import type { AffineMatrix } from './AffineMatrix';
@@ -143,6 +147,8 @@ export type {
   IVolumeLoadObject,
   IVolumeInput,
   VolumeInputCallback,
+  IStackInput,
+  StackInputCallback,
   ViewportPreset,
   //
   Metadata,
@@ -195,6 +201,7 @@ export type {
   ColormapRegistration,
   // PixelData
   PixelDataTypedArray,
+  PixelDataTypedArrayString,
   ImagePixelModule,
   ImagePlaneModule,
   AffineMatrix,

package/src/utilities/genericMetadataProvider.ts

@@ -0,0 +1,43 @@
+import { metaData } from '..';
+
+let state: Record<string, any> = {}; // Calibrated pixel spacing per imageId
+/**
+ * Simple metadata provider that stores some sort of meta data for each imageId.
+ */
+const metadataProvider = {
+  /**
+   * Adds metadata for an imageId.
+   * @param imageId - the imageId for the metadata to store
+   * @param payload - the payload
+   */
+  add: (imageId: string, payload: any): void => {
+    const type = payload.type;
+
+    if (!state[imageId]) {
+      state[imageId] = {};
+    }
+
+    // Create a deep copy of payload.metadata
+    state[imageId][type] = JSON.parse(JSON.stringify(payload.metadata));
+  },
+
+  /**
+   * Returns the metadata for an imageId if it exists.
+   * @param type - the type of metadata to enquire about
+   * @param imageId - the imageId to enquire about
+   */
+  get: (type: string, imageId: string): any => {
+    return state[imageId]?.[type];
+  },
+
+  /**
+   * Clears all metadata.
+   */
+  clear: (): void => {
+    state = {};
+  },
+};
+
+metaData.addProvider(metadataProvider.get);
+
+export default metadataProvider;

package/src/utilities/getBufferConfiguration.ts

@@ -0,0 +1,69 @@
+import { PixelDataTypedArray, PixelDataTypedArrayString } from '../types';
+
+/**
+ * Creates a target buffer based on the provided options.
+ *
+ * @param targetBufferType - The type of the target buffer.
+ * @param length - The length of the target buffer.
+ * @param options - Options for the target buffer. Currently supports
+ * `use16BitTexture` and `isVolumeBuffer`.
+ * @returns Returns an object containing the number of bytes and the type array
+ * constructor of the target buffer, which you then use to create the target buffer
+ * with new TypedArrayConstructor(length).
+ */
+function getBufferConfiguration(
+  targetBufferType: PixelDataTypedArrayString,
+  length: number,
+  options: { use16BitTexture?: boolean; isVolumeBuffer?: boolean } = {}
+): {
+  numBytes: number;
+  TypedArrayConstructor: new (
+    length: number | SharedArrayBuffer
+  ) => PixelDataTypedArray;
+} {
+  const { use16BitTexture = false, isVolumeBuffer = false } = options;
+
+  switch (targetBufferType) {
+    case 'Float32Array':
+      return { numBytes: length * 4, TypedArrayConstructor: Float32Array };
+    case 'Uint8Array':
+      return { numBytes: length, TypedArrayConstructor: Uint8Array };
+    case 'Uint16Array':
+      if (!isVolumeBuffer) {
+        return { numBytes: length * 2, TypedArrayConstructor: Uint16Array };
+      } else {
+        if (use16BitTexture) {
+          return { numBytes: length * 2, TypedArrayConstructor: Uint16Array };
+        } else {
+          console.warn(
+            'Uint16Array is not supported for volume rendering, switching back to Float32Array'
+          );
+          return { numBytes: length * 4, TypedArrayConstructor: Float32Array };
+        }
+      }
+    case 'Int16Array':
+      if (!isVolumeBuffer) {
+        return { numBytes: length * 2, TypedArrayConstructor: Int16Array };
+      } else {
+        if (use16BitTexture) {
+          return { numBytes: length * 2, TypedArrayConstructor: Int16Array };
+        } else {
+          console.warn(
+            'Int16Array is not supported for volume rendering, switching back to Float32Array'
+          );
+          return { numBytes: length * 4, TypedArrayConstructor: Float32Array };
+        }
+      }
+    default:
+      if (targetBufferType) {
+        throw new Error(
+          'TargetBuffer should be Float32Array, Uint8Array, Uint16Array, or Int16Array'
+        );
+      } else {
+        // Use Float32Array if no targetBuffer is provided
+        return { numBytes: length * 4, TypedArrayConstructor: Float32Array };
+      }
+  }
+}
+
+export { getBufferConfiguration };

package/src/utilities/getTargetVolumeAndSpacingInNormalDir.ts

@@ -30,14 +30,16 @@ const isPrimaryVolume = (volume): boolean =>
  * @param camera - current camera
  * @param targetVolumeId - If a target volumeId is given that volume
  * is forced to be used.
- *
+ * @param useSlabThickness - If true, the number of steps will be calculated
+ * based on the slab thickness instead of the spacing in the normal direction
  * @returns An object containing the imageVolume and spacingInNormalDirection.
  *
  */
 export default function getTargetVolumeAndSpacingInNormalDir(
   viewport: IVolumeViewport,
   camera: ICamera,
-  targetVolumeId?: string
+  targetVolumeId?: string,
+  useSlabThickness = false
 ): {
   imageVolume: IImageVolume;
   spacingInNormalDirection: number;
@@ -75,7 +77,8 @@ export default function getTargetVolumeAndSpacingInNormalDir(
     const spacingInNormalDirection = getSpacingInNormal(
       imageVolume,
       viewPlaneNormal,
-      viewport
+      viewport,
+      useSlabThickness
     );
 
     return { imageVolume, spacingInNormalDirection, actorUID };
@@ -131,11 +134,12 @@ export default function getTargetVolumeAndSpacingInNormalDir(
 function getSpacingInNormal(
   imageVolume: IImageVolume,
   viewPlaneNormal: Point3,
-  viewport: IVolumeViewport
+  viewport: IVolumeViewport,
+  useSlabThickness = false
 ): number {
   const { slabThickness } = viewport.getProperties();
   let spacingInNormalDirection = slabThickness;
-  if (!slabThickness) {
+  if (!slabThickness || useSlabThickness === false) {
     spacingInNormalDirection = getSpacingInNormalDirection(
       imageVolume,
       viewPlaneNormal

package/src/utilities/getVolumeSliceRangeInfo.ts

@@ -11,11 +11,14 @@ import {
  * Calculates the slice range for the given volume based on its orientation
  * @param viewport - Volume viewport
  * @param volumeId - Id of one of the volumes loaded on the given viewport
+ * @param useSlabThickness - If true, the slice range will be calculated
+ * based on the slab thickness instead of the spacing in the normal direction
  * @returns slice range information
  */
 function getVolumeSliceRangeInfo(
   viewport: IVolumeViewport,
-  volumeId: string
+  volumeId: string,
+  useSlabThickness = false
 ): {
   sliceRange: ActorSliceRange;
   spacingInNormalDirection: number;
@@ -24,7 +27,12 @@ function getVolumeSliceRangeInfo(
   const camera = viewport.getCamera();
   const { focalPoint, viewPlaneNormal } = camera;
   const { spacingInNormalDirection, actorUID } =
-    getTargetVolumeAndSpacingInNormalDir(viewport, camera, volumeId);
+    getTargetVolumeAndSpacingInNormalDir(
+      viewport,
+      camera,
+      volumeId,
+      useSlabThickness
+    );
 
   if (!actorUID) {
     throw new Error(

package/src/utilities/getVolumeViewportScrollInfo.ts

@@ -5,14 +5,17 @@ import getVolumeSliceRangeInfo from './getVolumeSliceRangeInfo';
  * Calculates the number os steps the volume can scroll based on its orientation
  * @param viewport - Volume viewport
  * @param volumeId - Id of one of the volumes loaded on the given viewport
+ * @param useSlabThickness - If true, the number of steps will be calculated
+ * based on the slab thickness instead of the spacing in the normal direction
  * @returns number of steps the volume can scroll and its current position
  */
 function getVolumeViewportScrollInfo(
   viewport: IVolumeViewport,
-  volumeId: string
+  volumeId: string,
+  useSlabThickness = false
 ) {
   const { sliceRange, spacingInNormalDirection, camera } =
-    getVolumeSliceRangeInfo(viewport, volumeId);
+    getVolumeSliceRangeInfo(viewport, volumeId, useSlabThickness);
 
   const { min, max, current } = sliceRange;
 

package/src/utilities/index.ts

@@ -49,10 +49,16 @@ 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';
 
 // name spaces
 import * as planar from './planar';
@@ -120,5 +126,11 @@ export {
   decimate,
   imageRetrieveMetadataProvider,
   transferFunctionUtils,
+  updateVTKImageDataWithCornerstoneImage,
+  sortImageIdsAndGetSpacing,
+  makeVolumeMetadata,
+  isValidVolume,
+  genericMetadataProvider,
   isVideoTransferSyntax,
+  getBufferConfiguration,
 };

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

@@ -0,0 +1,174 @@
+import { vec3 } from 'gl-matrix';
+import { metaData, getConfiguration } from '../';
+import { Point3 } from '../types';
+
+type SortedImageIdsItem = {
+  zSpacing: number;
+  origin: Point3;
+  sortedImageIds: Array<string>;
+};
+/**
+ * Given an array of imageIds, sort them based on their imagePositionPatient, and
+ * also returns the spacing between images and the origin of the reference image
+ *
+ * @param imageIds - array of imageIds
+ * @param scanAxisNormal - [x, y, z] array or gl-matrix vec3
+ *
+ * @returns The sortedImageIds, zSpacing, and origin of the first image in the series.
+ */
+export default function sortImageIdsAndGetSpacing(
+  imageIds: Array<string>,
+  scanAxisNormal?: vec3
+): SortedImageIdsItem {
+  const {
+    imagePositionPatient: referenceImagePositionPatient,
+    imageOrientationPatient,
+  } = metaData.get('imagePlaneModule', imageIds[0]);
+
+  if (!scanAxisNormal) {
+    const rowCosineVec = vec3.fromValues(
+      imageOrientationPatient[0],
+      imageOrientationPatient[1],
+      imageOrientationPatient[2]
+    );
+    const colCosineVec = vec3.fromValues(
+      imageOrientationPatient[3],
+      imageOrientationPatient[4],
+      imageOrientationPatient[5]
+    );
+
+    scanAxisNormal = vec3.create();
+    vec3.cross(scanAxisNormal, rowCosineVec, colCosineVec);
+  }
+
+  const refIppVec = vec3.create();
+
+  // Check if we are using wadouri scheme
+  const usingWadoUri = imageIds[0].split(':')[0] === 'wadouri';
+
+  vec3.set(
+    refIppVec,
+    referenceImagePositionPatient[0],
+    referenceImagePositionPatient[1],
+    referenceImagePositionPatient[2]
+  );
+
+  let sortedImageIds: string[];
+  let zSpacing: number;
+
+  function getDistance(imageId: string) {
+    const { imagePositionPatient } = metaData.get('imagePlaneModule', imageId);
+
+    const positionVector = vec3.create();
+
+    vec3.sub(
+      positionVector,
+      referenceImagePositionPatient,
+      imagePositionPatient
+    );
+
+    return vec3.dot(positionVector, scanAxisNormal);
+  }
+
+  /**
+   * If we are using wadors and so have all image metadata cached ahead of time,
+   * then sort by image position in 3D space, and calculate average slice
+   * spacing from the entire volume. If not, then use the sampled images (1st
+   * and middle) to calculate slice spacing, and use the provided imageId order.
+   * Correct sorting must be done ahead of time.
+   */
+  if (!usingWadoUri) {
+    const distanceImagePairs = imageIds.map((imageId) => {
+      const distance = getDistance(imageId);
+
+      return {
+        distance,
+        imageId,
+      };
+    });
+
+    distanceImagePairs.sort((a, b) => b.distance - a.distance);
+
+    sortedImageIds = distanceImagePairs.map((a) => a.imageId);
+    const numImages = distanceImagePairs.length;
+
+    // Calculated average spacing.
+    // We would need to resample if these are not similar.
+    // It should be up to the host app to do this if it needed to.
+    zSpacing =
+      Math.abs(
+        distanceImagePairs[numImages - 1].distance -
+          distanceImagePairs[0].distance
+      ) /
+      (numImages - 1);
+  } else {
+    // Using wadouri, so we have only prefetched the first, middle, and last
+    // images for metadata. Assume initial imageId array order is pre-sorted,
+    // but check orientation.
+    const prefetchedImageIds = [
+      imageIds[0],
+      imageIds[Math.floor(imageIds.length / 2)],
+    ];
+    sortedImageIds = imageIds;
+    const firstImageDistance = getDistance(prefetchedImageIds[0]);
+    const middleImageDistance = getDistance(prefetchedImageIds[1]);
+    if (firstImageDistance - middleImageDistance < 0) {
+      sortedImageIds.reverse();
+    }
+
+    // Calculate average spacing between the first and middle prefetched images,
+    // otherwise fall back to DICOM `spacingBetweenSlices`
+    const metadataForMiddleImage = metaData.get(
+      'imagePlaneModule',
+      prefetchedImageIds[1]
+    );
+    if (!metadataForMiddleImage) {
+      throw new Error('Incomplete metadata required for volume construction.');
+    }
+
+    const positionVector = vec3.create();
+
+    vec3.sub(
+      positionVector,
+      referenceImagePositionPatient,
+      metadataForMiddleImage.imagePositionPatient
+    );
+    const distanceBetweenFirstAndMiddleImages = vec3.dot(
+      positionVector,
+      scanAxisNormal
+    );
+    zSpacing =
+      Math.abs(distanceBetweenFirstAndMiddleImages) /
+      Math.floor(imageIds.length / 2);
+  }
+
+  const { imagePositionPatient: origin, sliceThickness } = metaData.get(
+    'imagePlaneModule',
+    sortedImageIds[0]
+  );
+
+  const { strictZSpacingForVolumeViewport } = getConfiguration().rendering;
+
+  // We implemented these lines for multiframe dicom files that does not have
+  // position for each frame, leading to incorrect calculation of zSpacing = 0
+  // If possible, we use the sliceThickness, but we warn about this dicom file
+  // weirdness. If sliceThickness is not available, we set to 1 just to render
+  if (zSpacing === 0 && !strictZSpacingForVolumeViewport) {
+    if (sliceThickness) {
+      console.log('Could not calculate zSpacing. Using sliceThickness');
+      zSpacing = sliceThickness;
+    } else {
+      console.log(
+        'Could not calculate zSpacing. The VolumeViewport visualization is compromised. Setting zSpacing to 1 to render'
+      );
+      zSpacing = 1;
+    }
+  }
+  const result: SortedImageIdsItem = {
+    zSpacing,
+    origin,
+    sortedImageIds,
+  };
+
+  return result;
+}

package/src/utilities/updateVTKImageDataWithCornerstoneImage.ts

@@ -0,0 +1,38 @@
+import vtkImageData from '@kitware/vtk.js/Common/DataModel/ImageData';
+import { IImage, PixelDataTypedArray } from '../types';
+
+function updateVTKImageDataWithCornerstoneImage(
+  sourceImageData: vtkImageData,
+  image: IImage
+) {
+  const pixelData = image.getPixelData();
+  const scalarData = sourceImageData
+    .getPointData()
+    .getScalars()
+    .getData() as PixelDataTypedArray;
+
+  // 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
+  sourceImageData.modified();
+}
+
+export { updateVTKImageDataWithCornerstoneImage };