@cornerstonejs/core 1.42.0 → 1.43.0

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,9 @@ import type {
   VideoViewportInput,
 } from './VideoViewportTypes';
 import type BoundsIJK from './BoundsIJK';
+import type { ImageVolumeProps } from './ImageVolumeProps';
+import type { VolumeProps } from './VolumeProps';
+import type BoundsLPS from './BoundsLPS';
 
 export type {
   // config
@@ -118,9 +121,9 @@ export type {
   IEnabledElement,
   ICache,
   IVolume,
-  VolumeScalarData,
   IViewportId,
   IImageVolume,
+  ImageVolumeProps,
   IDynamicImageVolume,
   IRenderingEngine,
   ScalingParameters,
@@ -214,6 +217,8 @@ export type {
   InternalVideoCamera,
   VideoViewportInput,
   BoundsIJK,
+  BoundsLPS,
   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;
@@ -216,10 +216,21 @@ export default class VoxelManager<T> {
    * Extends the bounds of this object to include the specified point
    */
   public static addBounds(bounds: BoundsIJK, point: Point3) {
-    bounds.forEach((bound, index) => {
-      bound[0] = Math.min(point[index], bound[0]);
-      bound[1] = Math.max(point[index], bound[1]);
-    });
+    if (!bounds) {
+      bounds = [
+        [Infinity, -Infinity],
+        [Infinity, -Infinity],
+        [Infinity, -Infinity],
+      ];
+    }
+
+    // Directly update the bounds for each axis
+    bounds[0][0] = Math.min(point[0], bounds[0][0]);
+    bounds[0][1] = Math.max(point[0], bounds[0][1]);
+    bounds[1][0] = Math.min(point[1], bounds[1][0]);
+    bounds[1][1] = Math.max(point[1], bounds[1][1]);
+    bounds[2][0] = Math.min(point[2], bounds[2][0]);
+    bounds[2][1] = Math.max(point[2], bounds[2][1]);
   }
 
   /**

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

package/src/utilities/convertStackToVolumeViewport.ts

@@ -0,0 +1,115 @@
+import { IStackViewport, IVolumeViewport, Point3 } from '../types';
+import { setVolumesForViewports } from '../RenderingEngine/helpers';
+import {
+  createAndCacheVolume,
+  getUnknownVolumeLoaderSchema,
+} from '../loaders/volumeLoader';
+import { Events, OrientationAxis, ViewportType } from '../enums';
+
+/**
+ * Converts a stack viewport to a volume viewport.
+ *
+ * @param params - The parameters for the conversion.
+ * @param params.viewport - The stack viewport to convert.
+ * @param params.options - The options for the conversion.
+ * @param [params.options.volumeId] - The volumeId that will get generated, it should have the volume loader schema defined if not we will use the default one.
+ * @param [params.options.viewportId] - The viewportId that will get used for new viewport. If not provided, the stack viewport id will be used.
+ * @param [params.options.background] - The background color of the volume viewport.
+ * @returns The converted volume viewport.
+ */
+async function convertStackToVolumeViewport({
+  viewport,
+  options,
+}: {
+  viewport: IStackViewport;
+  options: {
+    volumeId: string;
+    viewportId?: string;
+    background?: Point3;
+    orientation?: OrientationAxis;
+  };
+}): Promise<IVolumeViewport> {
+  const renderingEngine = viewport.getRenderingEngine();
+
+  let { volumeId } = options;
+
+  // if there is no loader schema for the volume Id, we will use the default one
+  // which we can get from the volume loader
+  if (volumeId.split(':').length === 1) {
+    const schema = getUnknownVolumeLoaderSchema();
+    volumeId = `${schema}:${volumeId}`;
+  }
+
+  const { id, element } = viewport;
+  const viewportId = options.viewportId || id;
+
+  const imageIds = viewport.getImageIds();
+
+  // It is important to keep the camera before enabling the viewport
+  const prevCamera = viewport.getCamera();
+
+  // this will disable the stack viewport and remove it from the toolGroup
+  renderingEngine.enableElement({
+    viewportId,
+    type: ViewportType.ORTHOGRAPHIC,
+    element,
+    defaultOptions: {
+      background: options.background,
+      orientation: options.orientation,
+    },
+  });
+
+  // Ideally here we should be able to just create a local volume and not use the
+  //  volume louder but we don't know if the stack is already pre-cached for all its
+  // imageIds or not so we just let the loader handle it and we have cache
+  // optimizations in place to avoid fetching the same imageId if it is already
+  // cached
+  const volume = await createAndCacheVolume(volumeId, {
+    imageIds,
+  });
+
+  volume.load();
+
+  // we should get the new viewport from the renderingEngine since the stack viewport
+  // was disabled and replaced with a volume viewport of the same id
+  const volumeViewport = <IVolumeViewport>(
+    renderingEngine.getViewport(viewportId)
+  );
+
+  setVolumesForViewports(
+    renderingEngine,
+    [
+      {
+        volumeId,
+      },
+    ],
+    [viewportId]
+  );
+
+  const volumeViewportNewVolumeHandler = () => {
+    volumeViewport.setCamera({
+      ...prevCamera,
+    });
+    volumeViewport.render();
+
+    element.removeEventListener(
+      Events.VOLUME_VIEWPORT_NEW_VOLUME,
+      volumeViewportNewVolumeHandler
+    );
+  };
+
+  const addVolumeViewportNewVolumeListener = () => {
+    element.addEventListener(
+      Events.VOLUME_VIEWPORT_NEW_VOLUME,
+      volumeViewportNewVolumeHandler
+    );
+  };
+
+  addVolumeViewportNewVolumeListener();
+
+  volumeViewport.render();
+
+  return volumeViewport;
+}
+
+export { convertStackToVolumeViewport };

package/src/utilities/convertVolumeToStackViewport.ts

@@ -0,0 +1,125 @@
+import * as Types from '../types';
+import cache, { ImageVolume } from '../cache';
+import { ViewportType } from '../enums';
+
+/**
+ * Converts a volume viewport to a stack viewport.
+ *
+ * @param params - The parameters for the conversion.
+ * @param params.viewport - The volume viewport to convert.
+ * @param params.options - The conversion options.
+ * @param [params.options.viewportId] - The new stackViewportId, If not provided, the volume viewport id will be used.
+ * @param [params.options.background] - The background color of the stack viewport.
+ * @param [params.options.decache] - Whether to decache the volume. Defaults to false.
+ *
+ * @returns The converted stack viewport.
+ */
+async function convertVolumeToStackViewport({
+  viewport,
+  options,
+}: {
+  viewport: Types.IVolumeViewport;
+  options: {
+    viewportId?: string;
+    background?: Types.Point3;
+  };
+}): Promise<Types.IStackViewport> {
+  const volumeViewport = viewport;
+  const { id, element } = volumeViewport;
+  const renderingEngine = viewport.getRenderingEngine();
+  const imageIdIndex = viewport.getCurrentImageIdIndex();
+
+  const { background } = options;
+  const viewportId = options.viewportId || id;
+
+  const actorEntry = volumeViewport.getDefaultActor();
+  const { uid: volumeId } = actorEntry;
+  const volume = cache.getVolume(volumeId) as Types.IImageVolume;
+
+  if (!(volume instanceof ImageVolume)) {
+    throw new Error(
+      'Currently, you cannot decache a volume that is not an ImageVolume. So, unfortunately, volumes such as nifti  (which are basic Volume, without imageIds) cannot be decached.'
+    );
+  }
+
+  const viewportInput = {
+    viewportId,
+    type: ViewportType.STACK,
+    element,
+    defaultOptions: {
+      background,
+    },
+  };
+
+  renderingEngine.enableElement(viewportInput);
+
+  // Get the stack viewport that was created
+  const stackViewport = <Types.IStackViewport>(
+    renderingEngine.getViewport(viewportId)
+  );
+
+  // So here we have two scenarios that we need to handle:
+  // 1. the volume was derived from a stack and we need to decache it, this is easy
+  // since we just need purge the volume from the cache and those images will get
+  // their copy of the image back
+  // 2. It was actually a native volume and we need to decache it, this is a bit more
+  // complicated since then we need to decide on the imageIds for it to get
+  // decached to
+  const hasCachedImages = volume.imageCacheOffsetMap.size > 0;
+  // Initialize the variable to hold the final result
+  let isAllImagesCached = false;
+
+  if (hasCachedImages) {
+    // Check if every imageId in the volume is in the _imageCache
+    isAllImagesCached = volume.imageIds.every((imageId) =>
+      cache.getImage(imageId)
+    );
+  }
+
+  const volumeUsedInOtherViewports = renderingEngine
+    .getVolumeViewports()
+    .find((vp) => vp.hasVolumeId(volumeId));
+
+  volume.decache(!volumeUsedInOtherViewports && isAllImagesCached);
+
+  const stack = [...volume.imageIds].reverse();
+
+  let imageIdIndexToJump = Math.max(
+    volume.imageIds.length - imageIdIndex - 1,
+    0
+  );
+
+  // Check to see if the image is already cached or not. If it's not, we will use another
+  // nearby imageId for the first image to jump to. There seem to be a lot of side effects
+  // if we jump to an image that is not cached in stack viewport while we convert
+  // from a volume viewport. For example, if we switch back and forth between stack and volume,
+  // and then try to jump to an image that is not cached, the image will not render at
+  // all when the full volume is filled. I'm not sure why yet.
+  const imageToJump = cache.getImage(stack[imageIdIndexToJump]);
+  if (!imageToJump) {
+    let minDistance = Infinity;
+    let minDistanceIndex = null;
+
+    stack.forEach((imageId, index) => {
+      const image = cache.getImage(imageId);
+      if (image) {
+        const distance = Math.abs(imageIdIndexToJump - index);
+        if (distance < minDistance) {
+          minDistance = distance;
+          minDistanceIndex = index;
+        }
+      }
+    });
+
+    imageIdIndexToJump = minDistanceIndex;
+  }
+
+  await stackViewport.setStack(stack, imageIdIndexToJump);
+
+  // Render the image
+  stackViewport.render();
+
+  return stackViewport;
+}
+
+export { convertVolumeToStackViewport };

package/src/utilities/generateVolumePropsFromImageIds.ts

@@ -0,0 +1,183 @@
+import { vec3 } from 'gl-matrix';
+import { getConfiguration, getShouldUseSharedArrayBuffer } from '../init';
+import createFloat32SharedArray from './createFloat32SharedArray';
+import createInt16SharedArray from './createInt16SharedArray';
+import createUint16SharedArray from './createUInt16SharedArray';
+import createUint8SharedArray from './createUint8SharedArray';
+import getScalingParameters from './getScalingParameters';
+import makeVolumeMetadata from './makeVolumeMetadata';
+import sortImageIdsAndGetSpacing from './sortImageIdsAndGetSpacing';
+import { ImageVolumeProps, Mat3, Point3 } from '../types';
+import cache from '../cache';
+import { Events } from '../enums';
+
+function generateVolumePropsFromImageIds(
+  imageIds: string[],
+  volumeId: string
+): ImageVolumeProps {
+  const { useNorm16Texture, preferSizeOverAccuracy } =
+    getConfiguration().rendering;
+
+  const use16BitDataType = useNorm16Texture || preferSizeOverAccuracy;
+
+  const volumeMetadata = makeVolumeMetadata(imageIds);
+
+  // For a streaming volume, the data type cannot rely on cswil to load
+  // the proper array buffer type. This is because the target buffer container
+  // must be decided ahead of time.
+  // TODO: move this logic into CSWIL to avoid logic duplication.
+  // We check if scaling parameters are negative we choose Int16 instead of
+  // Uint16 for cases where BitsAllocated is 16.
+  const imageIdIndex = Math.floor(imageIds.length / 2);
+  const imageId = imageIds[imageIdIndex];
+  const scalingParameters = getScalingParameters(imageId);
+  const hasNegativeRescale =
+    scalingParameters.rescaleIntercept < 0 ||
+    scalingParameters.rescaleSlope < 0;
+
+  // The prescale is ALWAYS used with modality LUT, so we can assume that
+  // if the rescale slope is not an integer, we need to use Float32
+  const hasFloatRescale =
+    scalingParameters.rescaleIntercept % 1 !== 0 ||
+    scalingParameters.rescaleSlope % 1 !== 0;
+
+  const {
+    BitsAllocated,
+    PixelRepresentation,
+    PhotometricInterpretation,
+    ImageOrientationPatient,
+    PixelSpacing,
+    Columns,
+    Rows,
+  } = volumeMetadata;
+
+  const rowCosineVec = vec3.fromValues(
+    ImageOrientationPatient[0],
+    ImageOrientationPatient[1],
+    ImageOrientationPatient[2]
+  );
+  const colCosineVec = vec3.fromValues(
+    ImageOrientationPatient[3],
+    ImageOrientationPatient[4],
+    ImageOrientationPatient[5]
+  );
+
+  const scanAxisNormal = vec3.create();
+
+  vec3.cross(scanAxisNormal, rowCosineVec, colCosineVec);
+
+  const { zSpacing, origin, sortedImageIds } = sortImageIdsAndGetSpacing(
+    imageIds,
+    scanAxisNormal
+  );
+
+  const numFrames = imageIds.length;
+
+  // Spacing goes [1] then [0], as [1] is column spacing (x) and [0] is row spacing (y)
+  const spacing = <Point3>[PixelSpacing[1], PixelSpacing[0], zSpacing];
+  const dimensions = <Point3>[Columns, Rows, numFrames];
+  const direction = [
+    ...rowCosineVec,
+    ...colCosineVec,
+    ...scanAxisNormal,
+  ] as Mat3;
+  const signed = PixelRepresentation === 1;
+  const numComponents = PhotometricInterpretation === 'RGB' ? 3 : 1;
+  const useSharedArrayBuffer = getShouldUseSharedArrayBuffer();
+  const length = dimensions[0] * dimensions[1] * dimensions[2];
+  const handleCache = (sizeInBytes) => {
+    if (!cache.isCacheable(sizeInBytes)) {
+      throw new Error(Events.CACHE_SIZE_EXCEEDED);
+    }
+    cache.decacheIfNecessaryUntilBytesAvailable(sizeInBytes);
+  };
+
+  let scalarData, sizeInBytes;
+  switch (BitsAllocated) {
+    case 8:
+      if (signed) {
+        throw new Error(
+          '8 Bit signed images are not yet supported by this plugin.'
+        );
+      }
+      sizeInBytes = length * numComponents;
+      handleCache(sizeInBytes);
+      scalarData = useSharedArrayBuffer
+        ? createUint8SharedArray(length * numComponents)
+        : new Uint8Array(length * numComponents);
+      break;
+
+    case 16:
+      // Temporary fix for 16 bit images to use Float32
+      // until the new dicom image loader handler the conversion
+      // correctly
+      if (!use16BitDataType || hasFloatRescale) {
+        sizeInBytes = length * 4;
+        scalarData = useSharedArrayBuffer
+          ? createFloat32SharedArray(length)
+          : new Float32Array(length);
+
+        break;
+      }
+
+      sizeInBytes = length * 2;
+      if (signed || hasNegativeRescale) {
+        handleCache(sizeInBytes);
+        scalarData = useSharedArrayBuffer
+          ? createInt16SharedArray(length)
+          : new Int16Array(length);
+        break;
+      }
+
+      if (!signed && !hasNegativeRescale) {
+        handleCache(sizeInBytes);
+        scalarData = useSharedArrayBuffer
+          ? createUint16SharedArray(length)
+          : new Uint16Array(length);
+        break;
+      }
+
+      // Default to Float32 again
+      sizeInBytes = length * 4;
+      handleCache(sizeInBytes);
+      scalarData = useSharedArrayBuffer
+        ? createFloat32SharedArray(length)
+        : new Float32Array(length);
+      break;
+
+    case 24:
+      sizeInBytes = length * numComponents;
+      handleCache(sizeInBytes);
+
+      // hacky because we don't support alpha channel in dicom
+      scalarData = useSharedArrayBuffer
+        ? createUint8SharedArray(length * numComponents)
+        : new Uint8Array(length * numComponents);
+      break;
+    case 32:
+      sizeInBytes = length * 4;
+      handleCache(sizeInBytes);
+      scalarData = useSharedArrayBuffer
+        ? createFloat32SharedArray(length)
+        : new Float32Array(length);
+      break;
+    default:
+      throw new Error(
+        `Bits allocated of ${BitsAllocated} is not defined to generate scalarData for the volume.`
+      );
+  }
+
+  return {
+    dimensions,
+    spacing,
+    origin,
+    direction,
+    scalarData,
+    sizeInBytes,
+    metadata: volumeMetadata,
+    imageIds: sortedImageIds,
+    volumeId,
+  };
+}
+
+export { generateVolumePropsFromImageIds };

package/src/utilities/index.ts

@@ -61,13 +61,18 @@ import decimate from './decimate';
 import imageRetrieveMetadataProvider from './imageRetrieveMetadataProvider';
 import isVideoTransferSyntax from './isVideoTransferSyntax';
 import { getBufferConfiguration } from './getBufferConfiguration';
+import { generateVolumePropsFromImageIds } from './generateVolumePropsFromImageIds';
+import { convertStackToVolumeViewport } from './convertStackToVolumeViewport';
+import { convertVolumeToStackViewport } from './convertVolumeToStackViewport';
 import VoxelManager from './VoxelManager';
+import roundNumber, { roundToPrecision } from './roundNumber';
 
 // name spaces
 import * as planar from './planar';
 import * as windowLevel from './windowLevel';
 import * as colormap from './colormap';
 import * as transferFunctionUtils from './transferFunctionUtils';
+import * as cacheUtils from './cacheUtils';
 
 export {
   eventListener,
@@ -139,4 +144,10 @@ export {
   isVideoTransferSyntax,
   getBufferConfiguration,
   VoxelManager,
+  generateVolumePropsFromImageIds,
+  convertStackToVolumeViewport,
+  convertVolumeToStackViewport,
+  cacheUtils,
+  roundNumber,
+  roundToPrecision,
 };

package/src/utilities/planar.ts

@@ -28,11 +28,22 @@ function linePlaneIntersection(p0: Point3, p1: Point3, plane: Plane): Point3 {
  * It returns the plane equation defined by a point and a normal vector.
  * @param normal - normal vector
  * @param point - a point on the plane
+ * @param normalized - if true, the values of the plane equation will be normalized
  * @returns - [A, B,C, D] of plane equation A*X + B*Y + C*Z = D
  */
-function planeEquation(normal: Point3, point: Point3 | vec3): Plane {
+function planeEquation(
+  normal: Point3,
+  point: Point3 | vec3,
+  normalized = false
+): Plane {
   const [A, B, C] = normal;
   const D = A * point[0] + B * point[1] + C * point[2];
+
+  if (normalized) {
+    const length = Math.sqrt(A * A + B * B + C * C);
+    return [A / length, B / length, C / length, D / length];
+  }
+
   return [A, B, C, D];
 }