@cornerstonejs/core 1.28.2 → 1.29.0

package/src/types/EventTypes.ts

@@ -7,8 +7,8 @@ import type ICamera from './ICamera';
 import type IImage from './IImage';
 import type IImageVolume from './IImageVolume';
 import type { VOIRange } from './voi';
-import type VOILUTFunctionType from '../enums/VOILUTFunctionType';
-import type ViewportStatus from '../enums/ViewportStatus';
+import VOILUTFunctionType from '../enums/VOILUTFunctionType';
+import ViewportStatus from '../enums/ViewportStatus';
 import type DisplayArea from './displayArea';
 import IImageCalibration from './IImageCalibration';
 
@@ -129,6 +129,16 @@ type ImageLoadedEventDetail = {
   image: IImage;
 };
 
+export type ImageLoadStageEventDetail = {
+  stageId: string;
+  numberOfImages: number;
+  numberOfFailures: number;
+  // The duration of just this stage
+  stageDurationInMS: number;
+  // The overall duration
+  startDurationInMS: number;
+};
+
 /**
  * IMAGE_LOADED_FAILED Event's data
  */
@@ -245,22 +255,6 @@ type ImageSpacingCalibratedEventDetail = {
   worldToIndex: mat4;
 };
 
-/**
- * IMAGE_LOAD_PROGRESS Event's data. Note this is only for one image load and NOT volume load.
- */
-type ImageLoadProgressEventDetail = {
-  /** url we are loading from */
-  url: string;
-  /** loading image image id */
-  imageId: string;
-  /** the bytes browser receive */
-  loaded: number;
-  /** the total bytes settled by the header */
-  total: number;
-  /** loaded divided by total * 100 - shows the percentage of the image loaded */
-  percent: number;
-};
-
 /**
  * The STACK_VIEWPORT_NEW_STACK event's data, when a new stack is set on a StackViewport
  */
@@ -391,11 +385,6 @@ type PreStackNewImageEvent = CustomEventType<PreStackNewImageEventDetail>;
 type ImageSpacingCalibratedEvent =
   CustomEventType<ImageSpacingCalibratedEventDetail>;
 
-/**
- * IMAGE_LOAD_PROGRESS
- */
-type ImageLoadProgressEvent = CustomEventType<ImageLoadProgressEventDetail>;
-
 /**
  * STACK_VIEWPORT_NEW_STACK
  */
@@ -443,8 +432,6 @@ export type {
   PreStackNewImageEventDetail,
   ImageSpacingCalibratedEvent,
   ImageSpacingCalibratedEventDetail,
-  ImageLoadProgressEvent,
-  ImageLoadProgressEventDetail,
   VolumeNewImageEvent,
   VolumeNewImageEventDetail,
   StackViewportNewStackEvent,

package/src/types/ICache.ts

@@ -10,7 +10,8 @@ interface ICache {
   /** Stores the imageLoad Object inside the cache */
   putImageLoadObject: (
     imageId: string,
-    imageLoadObject: IImageLoadObject
+    imageLoadObject: IImageLoadObject,
+    updateCache?: boolean
   ) => Promise<any>;
   /** Retrieves the imageLoad Object from the cache */
   getImageLoadObject: (imageId: string) => IImageLoadObject | void;

package/src/types/IImage.ts

@@ -1,7 +1,8 @@
-import CPUFallbackLUT from './CPUFallbackLUT';
-import CPUFallbackColormap from './CPUFallbackColormap';
-import CPUFallbackEnabledElement from './CPUFallbackEnabledElement';
-import { PixelDataTypedArray } from './PixelDataTypedArray';
+import type CPUFallbackLUT from './CPUFallbackLUT';
+import type CPUFallbackColormap from './CPUFallbackColormap';
+import type CPUFallbackEnabledElement from './CPUFallbackEnabledElement';
+import type { PixelDataTypedArray } from './PixelDataTypedArray';
+import { ImageQualityStatus } from '../enums';
 
 /**
  * Cornerstone Image interface, it is used for both CPU and GPU rendering
@@ -113,6 +114,8 @@ interface IImage {
     modalityLUT?: unknown;
     voiLUT?: CPUFallbackLUT;
   };
+
+  imageQualityStatus?: ImageQualityStatus;
 }
 
 export default IImage;

package/src/types/IRetrieveConfiguration.ts

@@ -0,0 +1,194 @@
+import { ImageQualityStatus, RequestType } from '../enums';
+import { ImageLoadListener } from './ImageLoadListener';
+
+/**
+ * Retrieve stages are part of a retrieval of a set of image ids.
+ * Each retrieve stage defines which imageIds to include, as well as how
+ * that set should be handled.  An imageID can be retrieved multiple times,
+ * done in order, one after the other, so that it is first retrieved as a
+ * lossy/low quality image, followed by higher qualities.  The actual
+ * retrieve options used are abstracted out by the retrieve type, a simple
+ * string that defines what type of retrieve values are used.
+ *
+ * See Progressive Loading in the overall docs for information on retrieval
+ * stages.
+ */
+export interface RetrieveStage {
+  /**
+   * An id for the stage for use in the stage completion events
+   */
+  id: string;
+  /**
+   * Set of positions in a list of imageID's to select for this stage.
+   * Negative values are relative to the end, positive to
+   * the beginning, and fractional values between -1 and 1 are relative to frame count
+   */
+  positions?: number[];
+  /**
+   * Alternately to the positions, choose imageId's by decimating
+   * at the given interval decimate interval/offset.
+   */
+  decimate?: number;
+  /**
+   * Use the given offset.  For example, a decimate of 4 and offset of 1 will
+   * choose from the set `[0...12]`  the values `1,5,9`
+   */
+  offset?: number;
+  /**
+   * Use a specified retrieve type to specify the type of retrieve this stage
+   * uses.  There are four standard retrieve types, but others can be defined
+   * as required.  The four standard ones are:
+   *
+   * * singleFast - for a fast/low quality single image
+   * * singleFinal - for the final quality single image
+   * * multipleFast - for a fast/low quality image for multiples
+   * * multipleFinal - for a final image for multiple images
+   *
+   * The single/multiple split is done so that the single retrieve can be
+   * a streaming type retrieve, which doesn't work well for multiple images where
+   * an entire set of lower quality images is desireable before starting with the
+   * high quality set, but the streaming retrieve does work very well for single
+   * images.
+   */
+  retrieveType?: string;
+  /**
+   * The queue request type to use.
+   */
+  requestType?: RequestType;
+  /**
+   * The queue priority to use
+   */
+  priority?: number;
+  /**
+   * A set of frames which are nearby to replicate this frame to
+   * This allows defining how replication within the volume occurs.
+   */
+  nearbyFrames?: NearbyFrames[];
+}
+
+/**
+ * Nearby frames are used in a volume to fill the entire volume quickly without
+ * needing to have retrieved them from a remote/slow location.  This gives the
+ * appearance of a complete volume extremely quickly.
+ */
+export type NearbyFrames = {
+  /**
+   * The offset of the nearby frame to fill from the current position.
+   * For example, if the current image is index 32, and the offset is -1,
+   * then the frame at index 31 will be filled with 32's image data.
+   */
+  offset: number;
+  /**
+   *  The status to set a newly filled image from
+   */
+  imageQualityStatus?: ImageQualityStatus;
+};
+
+/**
+ * Base retrieves define some alternate path information, the decode level,
+ * whether the transfer syntax supports streaming decode, and the desired
+ * status and partial status used for retrieval.
+ */
+export type BaseRetrieveOptions = {
+  /**
+   * Additional arguments to add to the URL, in the format
+   * arg1=value1 ('&' arg2=value2)*
+   * For example: '&lossy=jhc' to use JHC lossy values
+   */
+  urlArguments?: string;
+  /**
+   * Alternate way to encode argument information by updating the frames path
+   */
+  framesPath?: string;
+  /**
+   * Decode level to attempt.  Currently only HTJ2K decoders support this.
+   * Value of 0 means decode full resolution,
+   * * 1 means 1/2 resolution in each dimension (eg 1/4 size)
+   * * i means 1/2^i resolution in each dimension, or 1/4^i size.
+   */
+  decodeLevel?: number;
+  /**
+   * Status to use when the full retrieve has been completed, defined as all
+   * the bytes for a given image.  Defaults to FULL_RESOLUTION, so if the
+   * complete image is lossy, this should be set to LOSSY.
+   */
+  imageQualityStatus?: ImageQualityStatus;
+};
+
+/**
+ * Range retrieves are used to retrieve part of an image, before the rest
+ * of the data is available.  This is different from streaming, below, in that
+ * the request itself uses a byte range to retrieve part of the data, and
+ * retrieves the entire request, but part of the image data.  That separates
+ * the timing for the retrieve, and is essential for fast retrieve for multiple
+ * images.
+ *
+ * Often the total size of the range is unknown due to cors issues, if so,
+ * the decodeLevel will need to be set manually here.
+ */
+export type RangeRetrieveOptions = BaseRetrieveOptions & {
+  /**
+   * Defines the rangeIndex to use.
+   * Stages do not need to use sequential ranges, the missing data
+   * will be fetched as a larger fetch as required.
+   * Terminate range requests with a rangeIndex: -1 to fetch remaining data.
+   */
+  rangeIndex: number;
+
+  /**
+   * byte range value to retrieve for initial decode
+   * Defaults to 64,000 bytes.
+   */
+  chunkSize?: number | ((metadata) => number);
+};
+
+/**
+ * Streaming retrieve is done when a request is decoded as it arrives.
+ * That is, if you receive the first 73k as the first part of the request,
+ * then that will attempt to be decoded.
+ */
+export type StreamingRetrieveOptions = BaseRetrieveOptions & {
+  /**
+   * Indicates to use streaming request.  Does NOT imply streaming decode,
+   * which is handled separately because the request may need to be streaming
+   * but the response might end up not being streaming.
+   */
+  streaming: boolean;
+};
+
+/**
+ * Retrieve options are Base, Range or Streaming RetrieveOptions.
+ */
+export type RetrieveOptions =
+  | BaseRetrieveOptions
+  | StreamingRetrieveOptions
+  | RangeRetrieveOptions;
+
+/**
+ * Defines how the retrieve configuration is handled for single and multi
+ * frame volumes.  Currently, the only configuration is a list of stages
+ * specify how sets of images ids get retrieved together or separately, and
+ * what type of retrieves and which queue is used for retrieving.
+ *
+ * The intent is to add other information on how to retrieve here in the future.
+ * This could include the specific retrieve options or could control queue
+ * strategy, prefetch etc.
+ */
+export interface IRetrieveConfiguration {
+  /**
+   * Creates an image loader, defaulting to ProgressiveRetrieveImages
+   */
+  create?: (IRetrieveConfiguration) => IImagesLoader;
+  retrieveOptions?: Record<string, RetrieveOptions>;
+  stages?: RetrieveStage[];
+}
+
+/**
+ * Provides a method to load a stack of images.
+ */
+export interface IImagesLoader {
+  loadImages: (
+    imageIds: string[],
+    listener: ImageLoadListener
+  ) => Promise<unknown>;
+}

package/src/types/IStackViewport.ts

@@ -8,7 +8,7 @@ import Point3 from './Point3';
 import { Scaling } from './ScalingParameters';
 import StackViewportProperties from './StackViewportProperties';
 import { ColormapPublic } from './Colormap';
-import IImage from './IImage';
+import type IImage from './IImage';
 
 /**
  * Interface for Stack Viewport
@@ -135,6 +135,9 @@ export default interface IStackViewport extends IViewport {
    * list of imageIds, the index of the first imageId to be viewed. It is a
    * asynchronous function that returns a promise resolving to imageId being
    * displayed in the stack viewport.
+   *
+   * @param retrieveConfiguration - Set this to a progressive retriever of your
+   *       choice for progressive retrieval, or leave empty for non-progressive.
    */
   setStack(
     imageIds: Array<string>,

package/src/types/IStreamingVolumeProperties.ts

@@ -1,3 +1,5 @@
+import { ImageQualityStatus } from '../enums';
+
 interface IStreamingVolumeProperties {
   /** imageIds of the volume  */
   imageIds: Array<string>;
@@ -7,7 +9,7 @@ interface IStreamingVolumeProperties {
     loaded: boolean;
     loading: boolean;
     cancelled: boolean;
-    cachedFrames: Array<boolean>;
+    cachedFrames: Array<ImageQualityStatus>;
     callbacks: Array<() => void>;
   };
 }

package/src/types/IViewport.ts

@@ -6,6 +6,7 @@ import { ActorEntry } from './IActor';
 import ViewportType from '../enums/ViewportType';
 import ViewportStatus from '../enums/ViewportStatus';
 import DisplayArea from './displayArea';
+import { IRetrieveConfiguration } from './IRetrieveConfiguration';
 
 /**
  * Viewport interface for cornerstone viewports

package/src/types/ImageLoadListener.ts

@@ -0,0 +1,20 @@
+export type ImageLoadListener = {
+  /**
+   * Called when an image is loaded.  May be called multiple times with increasing
+   * status values.
+   */
+  successCallback: (imageId, image) => void;
+  /**
+   * Called when an image fails to load.  A failure is permanent if no more attempts
+   * will be made.
+   */
+  errorCallback: (imageId, permanent, reason) => void;
+
+  /**
+   * Gets the target options for loading a given image, used by the image loader.
+   * @returns Loader image options to use when loading the image.  Note this
+   *          is often a DICOMLoaderImageOptions, but doesn't have to be.
+   * @throws exception to prevent further loading of this image
+   */
+  getLoaderImageOptions?: (imageId) => Record<string, unknown>;
+};

package/src/types/index.ts

@@ -83,6 +83,16 @@ import type { PixelDataTypedArray } from './PixelDataTypedArray';
 import type { ImagePixelModule } from './ImagePixelModule';
 import type { ImagePlaneModule } from './ImagePlaneModule';
 import type { AffineMatrix } from './AffineMatrix';
+export type {
+  RetrieveStage,
+  RetrieveOptions,
+  RangeRetrieveOptions,
+  StreamingRetrieveOptions,
+  NearbyFrames,
+  IRetrieveConfiguration,
+  IImagesLoader,
+} from './IRetrieveConfiguration';
+import type { ImageLoadListener } from './ImageLoadListener';
 import type VideoViewportProperties from './VideoViewportProperties';
 import type IVideoViewport from './IVideoViewport';
 import type {
@@ -188,6 +198,7 @@ export type {
   ImagePixelModule,
   ImagePlaneModule,
   AffineMatrix,
+  ImageLoadListener,
   // video
   InternalVideoCamera,
   VideoViewportInput,

package/src/utilities/ProgressiveIterator.ts

@@ -0,0 +1,190 @@
+export class PromiseIterator<T> extends Promise<T> {
+  iterator?: ProgressiveIterator<T>;
+}
+
+export type ErrorCallback = (message: string | Error) => void;
+
+/**
+ * A progressive iterator is an async iterator that can have data delivered
+ * to it, with newer ones replacing older iterations which have not yet been
+ * consume.  That allows iterating over sets of values and delivering updates,
+ * but always getting the most recent instance.
+ */
+export default class ProgressiveIterator<T> {
+  public done;
+  public name?: string;
+
+  private nextValue;
+  private waiting;
+  private rejectReason;
+
+  constructor(name?) {
+    this.name = name || 'unknown';
+  }
+
+  /** Casts a promise, progressive iterator or promise iterator to a
+   * progressive iterator, creating one if needed to resolve it.
+   */
+  public static as(promise) {
+    if (promise.iterator) {
+      return promise.iterator;
+    }
+    const iterator = new ProgressiveIterator('as iterator');
+    promise.then(
+      (v) => {
+        try {
+          iterator.add(v, true);
+        } catch (e) {
+          iterator.reject(e as Error);
+        }
+      },
+      (reason) => iterator.reject(reason)
+    );
+    return iterator;
+  }
+
+  /** Add a most recent result, indicating if the result is the final one */
+  public add(x: T, done = false) {
+    this.nextValue = x;
+    this.done ||= done;
+    if (this.waiting) {
+      this.waiting.resolve(x);
+      this.waiting = undefined;
+    }
+  }
+
+  public resolve() {
+    this.done = true;
+    if (this.waiting) {
+      this.waiting.resolve(this.nextValue);
+      this.waiting = undefined;
+    }
+  }
+
+  /** Reject the fetch.  This will prevent further iteration. */
+  public reject(reason: Error): void {
+    this.rejectReason = reason;
+    this.waiting?.reject(reason);
+  }
+
+  /** Gets the most recent value, without waiting */
+  public getRecent(): T {
+    if (this.rejectReason) {
+      throw this.rejectReason;
+    }
+    return this.nextValue;
+  }
+
+  /**
+   * Async iteration where the delivered values are the most recently available
+   * ones, so not necessarily all values are ever seen.
+   */
+  public async *[Symbol.asyncIterator]() {
+    while (!this.done) {
+      if (this.rejectReason) {
+        throw this.rejectReason;
+      }
+      if (this.nextValue !== undefined) {
+        // console.log('Yielding on', this.name, this.nextValue);
+        yield this.nextValue;
+        if (this.done) {
+          break;
+        }
+      }
+      if (!this.waiting) {
+        this.waiting = {};
+        this.waiting.promise = new Promise((resolve, reject) => {
+          this.waiting.resolve = resolve;
+          this.waiting.reject = reject;
+        });
+      }
+      // console.log('Awaiting on', this.name);
+      await this.waiting.promise;
+    }
+    // console.log('Final yield on', this.name);
+    yield this.nextValue;
+  }
+
+  /** Runs the forEach method on this filter */
+  public async forEach(callback, errorCallback) {
+    let index = 0;
+    // Need to catch basic iteration errors first
+    try {
+      for await (const value of this) {
+        const { done } = this;
+        // Separately catch errors in the callback function
+        try {
+          await callback(value, done, index);
+          index++;
+        } catch (e) {
+          if (!done) {
+            console.warn('Caught exception in intermediate value', e);
+            continue;
+          }
+          if (errorCallback) {
+            errorCallback(e, done);
+          } else {
+            throw e;
+          }
+        }
+      }
+    } catch (e) {
+      if (errorCallback) {
+        errorCallback(e, true);
+      } else {
+        throw e;
+      }
+    }
+  }
+
+  /** Calls an async function to generate the results on the iterator */
+  public generate(
+    processFunction,
+    errorCallback?: ErrorCallback
+  ): Promise<any> {
+    return processFunction(this, this.reject.bind(this)).then(
+      () => {
+        if (!this.done) {
+          // Set it to done
+          this.resolve();
+        }
+      },
+      (reason) => {
+        this.reject(reason);
+        if (errorCallback) {
+          errorCallback(reason);
+        } else {
+          console.warn("Couldn't process because", reason);
+        }
+      }
+    );
+  }
+
+  async nextPromise(): Promise<T> {
+    for await (const i of this) {
+      if (i) {
+        return i;
+      }
+    }
+    return this.nextValue;
+  }
+
+  async donePromise(): Promise<T> {
+    for await (const i of this) {
+      // No-op
+    }
+    return this.nextValue;
+  }
+
+  public getNextPromise() {
+    const promise = this.nextPromise() as PromiseIterator<T>;
+    promise.iterator = this;
+    return promise;
+  }
+
+  public getDonePromise() {
+    const promise = this.donePromise() as PromiseIterator<T>;
+    promise.iterator = this;
+    return promise;
+  }
+}

package/src/utilities/decimate.ts

@@ -0,0 +1,17 @@
+/**
+ * Return the decimated indices for the given list.
+ * @param list - to decimate the indices for
+ * @param interleave - the interleave interval for decimation
+ * @param offset - where to start the interleave from
+ */
+export default function decimate(
+  list: Array<unknown>,
+  interleave: number,
+  offset = 0
+): number[] {
+  const interleaveIndices = [];
+  for (let i = offset; i < list.length; i += interleave) {
+    interleaveIndices.push(i);
+  }
+  return interleaveIndices;
+}

package/src/utilities/imageRetrieveMetadataProvider.ts

@@ -0,0 +1,39 @@
+import { addProvider } from '../metaData';
+
+const retrieveConfigurationState = new Map<string, any>();
+
+const IMAGE_RETRIEVE_CONFIGURATION = 'imageRetrieveConfiguration';
+
+/**
+ * Simple metadataProvider object to store metadata for the image retrieval.
+ */
+const imageRetrieveMetadataProvider = {
+  IMAGE_RETRIEVE_CONFIGURATION,
+
+  /** Empty the metadata state */
+  clear: () => {
+    retrieveConfigurationState.clear();
+  },
+
+  /* Adding a new entry to the state object. */
+  add: (key: string, payload): void => {
+    retrieveConfigurationState.set(key, payload);
+  },
+
+  get: (type: string, queriesOrQuery: string | string[]) => {
+    const queries = Array.isArray(queriesOrQuery)
+      ? queriesOrQuery
+      : [queriesOrQuery];
+    if (type === IMAGE_RETRIEVE_CONFIGURATION) {
+      return queries
+        .map((query) => retrieveConfigurationState.get(query))
+        .find((it) => it !== undefined);
+    }
+  },
+};
+
+addProvider(
+  imageRetrieveMetadataProvider.get.bind(imageRetrieveMetadataProvider)
+);
+
+export default imageRetrieveMetadataProvider;

package/src/utilities/index.ts

@@ -49,6 +49,9 @@ import getScalingParameters from './getScalingParameters';
 import getScalarDataType from './getScalarDataType';
 import isPTPrescaledWithSUV from './isPTPrescaledWithSUV';
 import getImageLegacy from './getImageLegacy';
+import ProgressiveIterator from './ProgressiveIterator';
+import decimate from './decimate';
+import imageRetrieveMetadataProvider from './imageRetrieveMetadataProvider';
 
 // name spaces
 import * as planar from './planar';
@@ -112,5 +115,8 @@ export {
   getScalarDataType,
   colormap,
   getImageLegacy,
+  ProgressiveIterator,
+  decimate,
+  imageRetrieveMetadataProvider,
   transferFunctionUtils,
 };