@cornerstonejs/core 2.0.0-beta.6 → 2.0.0-beta.8

package/src/loaders/imageLoader.ts

@@ -1,15 +1,66 @@
 import cache from '../cache/cache';
+import { ImageVolume } from '../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>;
+  ignoreCache?: boolean;
 }
+
+interface DerivedImages {
+  imageIds: Array<string>;
+  promises: Array<Promise<IImage>>;
+}
+
+type LocalImageOptions = {
+  scalarData?: PixelDataTypedArray;
+  targetBufferType?: PixelDataTypedArrayString;
+  dimensions?: Point2;
+  spacing?: Point3;
+  origin?: Point3;
+  direction?: Mat3;
+  /**
+   * Skip creation of the actual buffer object.
+   * In fact, this creates a very short buffer, as there are lots of places
+   * assuming a buffer exists.
+   * This can be used when there are alternative representations of the image data.
+   */
+  skipCreateBuffer?: boolean;
+  /**
+   * A method to call to update the image object when it gets added to the cache.
+   * This can be used to create alternative representations of the image data,
+   * such as a VoxelManager.
+   */
+  onCacheAdd?: (image: IImage) => void;
+};
+
+type DerivedImageOptions = LocalImageOptions & {
+  imageId?: string;
+  targetBufferType?: PixelDataTypedArrayString;
+};
+
 /**
  * This module deals with ImageLoaders, loading images and caching images
  */
@@ -76,6 +127,10 @@ function loadImageFromCacheOrVolume(
   imageId: string,
   options: ImageLoaderOptions
 ): IImageLoadObject {
+  if (options.ignoreCache) {
+    return loadImageFromImageLoader(imageId, options);
+  }
+
   // 1. Check inside the image cache for imageId
   let imageLoadObject = cache.getImageLoadObject(imageId);
   if (imageLoadObject !== undefined) {
@@ -84,11 +139,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
@@ -183,6 +241,198 @@ 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 { imageId, skipCreateBuffer, onCacheAdd } = options;
+
+  const imagePlaneModule = metaData.get('imagePlaneModule', referencedImageId);
+
+  const length = imagePlaneModule.rows * imagePlaneModule.columns;
+
+  const { TypedArrayConstructor } = getBufferConfiguration(
+    options.targetBufferType,
+    length
+  );
+
+  // Use a buffer of size 1 for no data
+  const imageScalarData = new TypedArrayConstructor(
+    skipCreateBuffer ? 1 : length
+  );
+  const derivedImageId = imageId;
+
+  ['imagePlaneModule', 'generalSeriesModule'].forEach((type) => {
+    genericMetadataProvider.add(derivedImageId, {
+      type,
+      metadata: metaData.get(type, referencedImageId),
+    });
+  });
+
+  const imagePixelModule = metaData.get('imagePixelModule', referencedImageId);
+  // TODO - add a general way to specify this
+  genericMetadataProvider.add(derivedImageId, {
+    type: 'imagePixelModule',
+    metadata: {
+      ...imagePixelModule,
+      bitsAllocated: 8,
+      bitsStored: 8,
+      highBit: 7,
+      samplesPerPixel: 1,
+      pixelRepresentation: 0,
+    },
+  });
+
+  const localImage = createAndCacheLocalImage(
+    { scalarData: imageScalarData, onCacheAdd, skipCreateBuffer },
+    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 options
+ * @param options.getDerivedImageId - function to get the derived imageId
+ * @param options.targetBufferType - target buffer type
+ * @param options.skipBufferCreate - avoid creating the buffer
+ */
+export function createAndCacheDerivedImages(
+  referencedImageIds: Array<string>,
+  options: DerivedImageOptions & {
+    getDerivedImageId?: (referencedImageId: string) => string;
+    targetBufferType?: PixelDataTypedArrayString;
+  } = {}
+): DerivedImages {
+  if (referencedImageIds?.length === 0) {
+    throw new Error(
+      'createAndCacheDerivedImages: parameter imageIds must be list of image Ids'
+    );
+  }
+
+  const derivedImageIds = [];
+  const allPromises = referencedImageIds.map((referencedImageId) => {
+    const newOptions: DerivedImageOptions = {
+      imageId:
+        options.getDerivedImageId?.(referencedImageId) || `derived:${uuidv4()}`,
+      ...options,
+    };
+    derivedImageIds.push(newOptions.imageId);
+    return createAndCacheDerivedImage(referencedImageId, newOptions);
+  });
+
+  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 if (options.skipCreateBuffer !== true) {
+    const { numBytes, TypedArrayConstructor } = getBufferConfiguration(
+      options.targetBufferType,
+      length
+    );
+
+    const imageScalarData = new TypedArrayConstructor(length);
+
+    image.sizeInBytes = numBytes;
+    image.getPixelData = () => imageScalarData;
+  }
+
+  // The onCacheAdd may modify the size in bytes for this image, which is ok,
+  // as this is used after resolution for cache storage.  It may also do
+  // thinks like adding alternative representations such as VoxelManager
+  options.onCacheAdd?.(image);
+
+  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.
@@ -297,3 +547,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/utils/contourSet/createContourSet.ts

@@ -0,0 +1,29 @@
+import { IGeometry, PublicContourSetData } from '../../../types';
+import { GeometryType } from '../../../enums';
+import { validateContourSet } from './validateContourSet';
+import { ContourSet } from '../../../cache/classes/ContourSet';
+
+export function createContourSet(
+  geometryId: string,
+  contourSetData: PublicContourSetData
+) {
+  // validate the data to make sure it is a valid contour set
+  validateContourSet(contourSetData);
+
+  const contourSet = new ContourSet({
+    id: contourSetData.id,
+    data: contourSetData.data,
+    color: contourSetData.color,
+    frameOfReferenceUID: contourSetData.frameOfReferenceUID,
+    segmentIndex: contourSetData.segmentIndex ?? 1,
+  });
+
+  const geometry: IGeometry = {
+    id: geometryId,
+    type: GeometryType.CONTOUR,
+    data: contourSet,
+    sizeInBytes: contourSet.getSizeInBytes(),
+  };
+
+  return geometry;
+}

package/src/loaders/utils/contourSet/validateContourSet.ts

@@ -0,0 +1,38 @@
+import { PublicContourSetData } from '../../../types';
+
+export function validateContourSet(contourSetData: PublicContourSetData) {
+  if (!contourSetData || contourSetData.data.length === 0) {
+    throw new Error(
+      'Invalid contour set data, see publicContourSetData type for more info'
+    );
+  }
+
+  // make sure it each has id, and each has data of type Point3[]
+  if (!contourSetData.id) {
+    throw new Error(
+      'Invalid contour set data, each contour set must have an id'
+    );
+  }
+
+  if (!contourSetData.data || !Array.isArray(contourSetData.data)) {
+    throw new Error(
+      'Invalid contour set data, each contour set must have an array of contours'
+    );
+  }
+
+  contourSetData.data.forEach((contourData) => {
+    if (!contourData.points || !Array.isArray(contourData.points)) {
+      throw new Error(
+        'Invalid contour set data, each contour must have an array of points'
+      );
+    }
+
+    contourData.points.forEach((point) => {
+      if (!point || !Array.isArray(point) || point.length !== 3) {
+        throw new Error(
+          'Invalid contour set data, each point must be an array of length 3'
+        );
+      }
+    });
+  });
+}

package/src/loaders/utils/surface/createSurface.ts

@@ -0,0 +1,31 @@
+import { IGeometry, PublicSurfaceData } from '../../../types';
+import { GeometryType } from '../../../enums';
+import { validateSurface } from './validateSurface';
+import { Surface } from '../../../cache/classes/Surface';
+
+export function createSurface(
+  geometryId: string,
+  SurfaceData: PublicSurfaceData
+) {
+  // validate the data to make sure it is a valid contour set
+  validateSurface(SurfaceData);
+
+  const surface = new Surface({
+    id: SurfaceData.id,
+    color: SurfaceData.color,
+    frameOfReferenceUID: SurfaceData.frameOfReferenceUID,
+    data: {
+      points: SurfaceData.data.points,
+      polys: SurfaceData.data.polys,
+    },
+  });
+
+  const geometry: IGeometry = {
+    id: geometryId,
+    type: GeometryType.SURFACE,
+    data: surface,
+    sizeInBytes: surface.getSizeInBytes(),
+  };
+
+  return geometry;
+}

package/src/loaders/utils/surface/validateSurface.ts

@@ -0,0 +1,9 @@
+import { PublicSurfaceData } from '../../../types';
+
+export function validateSurface(contourSetData: PublicSurfaceData) {
+  const { data } = contourSetData;
+
+  if (!data.points || !data.polys) {
+    throw new Error('Invalid surface data');
+  }
+}