@cornerstonejs/core 0.36.3 → 0.36.4

package/src/requestPool/requestPoolManager.ts

@@ -0,0 +1,329 @@
+import RequestType from '../enums/RequestType';
+import { IImage } from '../types';
+import { uuidv4 } from '../utilities';
+
+type AdditionalDetails = {
+  imageId?: string;
+  volumeId?: string;
+};
+
+type RequestDetailsInterface = {
+  requestFn: () => Promise<IImage | void>;
+  type: RequestType;
+  additionalDetails: AdditionalDetails;
+};
+
+type RequestPool = {
+  [name in RequestType]: { [key: number]: RequestDetailsInterface[] };
+};
+
+/**
+ * RequestPool manager class is a base class that manages the request pools.
+ * It is used imageRetrievalPoolManager, and imageLoadPoolManager to retrieve and load images.
+ * Previously requestPoolManager was used to manage the retrieval and loading and decoding
+ * of the images in a way that new requests were sent after the image was both loaded and decoded
+ * which was not performant since it was waiting for the image to be loaded and decoded before
+ * sending the next request which is a network request and can be done in parallel.
+ * Now, we use separate imageRetrievalPoolManager and imageLoadPoolManager
+ * to improve performance and both are extending the RequestPoolManager class which
+ * is a basic queueing pool.
+ *
+ * A new requestPool can be created by instantiating a new RequestPoolManager class.
+ *
+ * ```javascript
+ * const requestPoolManager = new RequestPoolManager()
+ * ```
+ *
+ * ## ImageLoadPoolManager
+ *
+ * You can use the imageLoadPoolManager to load images, by providing a `requestFn`
+ * that returns a promise for the image. You can provide a `type` to specify the type of
+ * request (interaction, thumbnail, prefetch), and you can provide additional details
+ * that will be passed to the requestFn. Below is an example of a requestFn that loads
+ * an image from an imageId:
+ *
+ * ```javascript
+ *
+ * const priority = -5
+ * const requestType = RequestType.Interaction
+ * const additionalDetails = { imageId }
+ * const options = {
+ *   targetBuffer: {
+ *     type: 'Float32Array',
+ *     offset: null,
+ *     length: null,
+ *   },
+ *   preScale: {
+ *      enabled: true,
+ *    },
+ * }
+ *
+ * imageLoadPoolManager.addRequest(
+ *   loadAndCacheImage(imageId, options).then(() => { // set on viewport}),
+ *   requestType,
+ *   additionalDetails,
+ *   priority
+ * )
+ * ```
+ * ### ImageRetrievalPoolManager
+ * You don't need to directly use the imageRetrievalPoolManager to load images
+ * since the imageLoadPoolManager will automatically use it for retrieval. However,
+ * maximum number of concurrent requests can be set by calling `setMaxConcurrentRequests`.
+ */
+class RequestPoolManager {
+  private id: string;
+  private awake: boolean;
+  private requestPool: RequestPool;
+  private numRequests = {
+    interaction: 0,
+    thumbnail: 0,
+    prefetch: 0,
+  };
+  /* maximum number of requests of each type. */
+  public maxNumRequests: {
+    interaction: number;
+    thumbnail: number;
+    prefetch: number;
+  };
+  /* A public property that is used to set the delay between requests. */
+  public grabDelay: number;
+  private timeoutHandle: number;
+
+  /**
+   * By default a request pool containing three priority groups, one for each
+   * of the request types, is created. Maximum number of requests of each type
+   * is set to 6.
+   */
+  constructor(id?: string) {
+    this.id = id ? id : uuidv4();
+
+    this.requestPool = {
+      interaction: { 0: [] },
+      thumbnail: { 0: [] },
+      prefetch: { 0: [] },
+    };
+
+    this.grabDelay = 5;
+    this.awake = false;
+
+    this.numRequests = {
+      interaction: 0,
+      thumbnail: 0,
+      prefetch: 0,
+    };
+
+    this.maxNumRequests = {
+      interaction: 6,
+      thumbnail: 6,
+      prefetch: 5,
+    };
+  }
+
+  /**
+   * This function sets the maximum number of requests for a given request type.
+   * @param type - The type of request you want to set the max number
+   * of requests for it can be either of interaction, prefetch, or thumbnail.
+   * @param maxNumRequests - The maximum number of requests that can be
+   * made at a time.
+   */
+  public setMaxSimultaneousRequests(
+    type: RequestType,
+    maxNumRequests: number
+  ): void {
+    this.maxNumRequests[type] = maxNumRequests;
+  }
+
+  /**
+   * It returns the maximum number of requests of a given type that can be made
+   * @param type - The type of request.
+   * @returns The maximum number of requests of a given type.
+   */
+  public getMaxSimultaneousRequests(type: RequestType): number {
+    return this.maxNumRequests[type];
+  }
+
+  /**
+   * Stops further fetching of the requests, all the ongoing requests will still
+   * be retrieved
+   */
+  public destroy(): void {
+    if (this.timeoutHandle) {
+      window.clearTimeout(this.timeoutHandle);
+    }
+  }
+
+  /**
+   * Adds the requests to the pool of requests.
+   *
+   * @param requestFn - A function that returns a promise which resolves in the image
+   * @param type - Priority category, it can be either of interaction, prefetch,
+   * or thumbnail.
+   * @param additionalDetails - Additional details that requests can contain.
+   * For instance the volumeId for the volume requests
+   * @param priority - Priority number for each category of requests. Its default
+   * value is priority 0. The lower the priority number, the higher the priority number
+   *
+   */
+  public addRequest(
+    requestFn: () => Promise<IImage | void>,
+    type: RequestType,
+    additionalDetails: Record<string, unknown>,
+    priority = 0
+  ): void {
+    // Describe the request
+    const requestDetails: RequestDetailsInterface = {
+      requestFn,
+      type,
+      additionalDetails,
+    };
+
+    // Check if the priority group exists on the request type
+    if (this.requestPool[type][priority] === undefined) {
+      this.requestPool[type][priority] = [];
+    }
+
+    // Adding the request to the correct priority group of the request type
+    this.requestPool[type][priority].push(requestDetails);
+
+    // Wake up
+    if (!this.awake) {
+      this.awake = true;
+      this.startGrabbing();
+    } else if (type === RequestType.Interaction) {
+      // Todo: this is a hack for interaction right now, we should separate
+      // the grabbing from the adding requests
+      this.startGrabbing();
+    }
+  }
+
+  /**
+   * Filter the requestPoolManager's pool of request based on the result of
+   * provided filter function. The provided filter function needs to return false or true
+   *
+   * @param filterFunction - The filter function for filtering of the requests to keep
+   */
+  public filterRequests(
+    filterFunction: (requestDetails: RequestDetailsInterface) => boolean
+  ): void {
+    Object.keys(this.requestPool).forEach((type: string) => {
+      const requestType = this.requestPool[type];
+      Object.keys(requestType).forEach((priority) => {
+        requestType[priority] = requestType[priority].filter(
+          (requestDetails: RequestDetailsInterface) => {
+            return filterFunction(requestDetails);
+          }
+        );
+      });
+    });
+  }
+
+  /**
+   * Clears the requests specific to the provided type. For instance, the
+   * pool of requests of type 'interaction' can be cleared via this function.
+   *
+   *
+   * @param type - category of the request (either interaction, prefetch or thumbnail)
+   */
+  public clearRequestStack(type: string): void {
+    if (!this.requestPool[type]) {
+      throw new Error(`No category for the type ${type} found`);
+    }
+    this.requestPool[type] = { 0: [] };
+  }
+
+  private sendRequests(type) {
+    const requestsToSend = this.maxNumRequests[type] - this.numRequests[type];
+
+    for (let i = 0; i < requestsToSend; i++) {
+      const requestDetails = this.getNextRequest(type);
+      if (requestDetails === null) {
+        return false;
+      } else if (requestDetails) {
+        this.numRequests[type]++;
+        this.awake = true;
+
+        requestDetails.requestFn().finally(() => {
+          this.numRequests[type]--;
+          this.startAgain();
+        });
+      }
+    }
+
+    return true;
+  }
+
+  private getNextRequest(type): RequestDetailsInterface | null {
+    const interactionPriorities = this.getSortedPriorityGroups(type);
+    for (const priority of interactionPriorities) {
+      if (this.requestPool[type][priority].length) {
+        return this.requestPool[type][priority].shift();
+      }
+    }
+
+    return null;
+  }
+
+  protected startGrabbing(): void {
+    const hasRemainingInteractionRequests = this.sendRequests(
+      RequestType.Interaction
+    );
+    const hasRemainingThumbnailRequests = this.sendRequests(
+      RequestType.Thumbnail
+    );
+    const hasRemainingPrefetchRequests = this.sendRequests(
+      RequestType.Prefetch
+    );
+
+    if (
+      !hasRemainingInteractionRequests &&
+      !hasRemainingThumbnailRequests &&
+      !hasRemainingPrefetchRequests
+    ) {
+      this.awake = false;
+    }
+  }
+
+  protected startAgain(): void {
+    if (!this.awake) {
+      return;
+    }
+
+    if (this.grabDelay !== undefined) {
+      // Prevents calling setTimeout hundreds of times when hundreds of requests
+      // are added which make it slower and works in an unexpected way when
+      // destroy/clearTimeout is called because only the last handle is stored.
+      if (!this.timeoutHandle) {
+        this.timeoutHandle = window.setTimeout(() => {
+          this.timeoutHandle = null;
+          this.startGrabbing();
+        }, this.grabDelay);
+      }
+    } else {
+      this.startGrabbing();
+    }
+  }
+
+  protected getSortedPriorityGroups(type: string): Array<number> {
+    const priorities = Object.keys(this.requestPool[type])
+      .map(Number)
+      .filter((priority) => this.requestPool[type][priority].length)
+      .sort();
+    return priorities;
+  }
+
+  /**
+   * Returns the request pool containing different categories, their priority and
+   * the added request details.
+   *
+   * @returns the request pool which contains different categories, their priority and
+   * the added request details
+   */
+  getRequestPool(): RequestPool {
+    return this.requestPool;
+  }
+}
+
+const requestPoolManager = new RequestPoolManager();
+
+export { RequestPoolManager };
+export default requestPoolManager;

package/src/types/ActorSliceRange.ts

@@ -0,0 +1,17 @@
+import { VolumeActor } from './IActor';
+import Point3 from './Point3';
+
+/**
+ * Object containing the min, max and current position in the normal direction
+ * for the actor
+ */
+type ActorSliceRange = {
+  actor: VolumeActor;
+  viewPlaneNormal: Point3;
+  focalPoint: Point3;
+  min: number;
+  max: number;
+  current: number;
+};
+
+export default ActorSliceRange;

package/src/types/CPUFallbackColormap.ts

@@ -0,0 +1,23 @@
+import Point4 from './Point4';
+import CPUFallbackLookupTable from './CPUFallbackLookupTable';
+
+interface CPUFallbackColormap {
+  /** Get id of colormap */
+  getId: () => string;
+  getColorSchemeName: () => string;
+  setColorSchemeName: (name: string) => void;
+  getNumberOfColors: () => number;
+  setNumberOfColors: (numColors: number) => void;
+  getColor: (index: number) => Point4;
+  getColorRepeating: (index: number) => Point4;
+  setColor: (index: number, rgba: Point4) => void;
+  addColor: (rgba: Point4) => void;
+  insertColor: (index: number, rgba: Point4) => void;
+  removeColor: (index: number) => void;
+  clearColors: () => void;
+  buildLookupTable: (lut: CPUFallbackLookupTable) => void;
+  createLookupTable: () => CPUFallbackLookupTable;
+  isValidIndex: (index: number) => boolean;
+}
+
+export default CPUFallbackColormap;

package/src/types/CPUFallbackColormapData.ts

@@ -0,0 +1,12 @@
+import Point4 from './Point4';
+
+type CPUFallbackColormapData = {
+  name: string;
+  numOfColors?: number;
+  colors?: Point4[];
+  segmentedData?: unknown;
+  numColors?: number;
+  gamma?: number;
+};
+
+export default CPUFallbackColormapData;

package/src/types/CPUFallbackColormapsData.ts

@@ -0,0 +1,7 @@
+import CPUFallbackColormapData from './CPUFallbackColormapData';
+
+type CPUFallbackColormapsData = {
+  [key: string]: CPUFallbackColormapData;
+};
+
+export default CPUFallbackColormapsData;

package/src/types/CPUFallbackEnabledElement.ts

@@ -0,0 +1,71 @@
+import Point2 from './Point2';
+import Point3 from './Point3';
+import Mat3 from './Mat3';
+import IImage from './IImage';
+import CPUFallbackViewport from './CPUFallbackViewport';
+import CPUFallbackTransform from './CPUFallbackTransform';
+import CPUFallbackColormap from './CPUFallbackColormap';
+import CPUFallbackRenderingTools from './CPUFallbackRenderingTools';
+
+interface CPUFallbackEnabledElement {
+  scale?: number;
+  pan?: Point2;
+  zoom?: number;
+  rotation?: number;
+  image?: IImage;
+  canvas?: HTMLCanvasElement;
+  viewport?: CPUFallbackViewport;
+  colormap?: CPUFallbackColormap;
+  options?: {
+    [key: string]: unknown;
+    colormap?: CPUFallbackColormap;
+  };
+  renderingTools?: CPUFallbackRenderingTools;
+  transform?: CPUFallbackTransform;
+  invalid?: boolean;
+  needsRedraw?: boolean;
+  metadata?: {
+    direction?: Mat3;
+    /** Last index is always 1 for CPU */
+    dimensions?: Point3;
+    /** Last spacing is always EPSILON for CPU */
+    spacing?: Point3;
+    origin?: Point3;
+    imagePlaneModule?: {
+      frameOfReferenceUID: string;
+      rows: number;
+      columns: number;
+      imageOrientationPatient: number[];
+      rowCosines: Point3;
+      columnCosines: Point3;
+      imagePositionPatient: number[];
+      sliceThickness?: number;
+      sliceLocation?: number;
+      pixelSpacing: Point2;
+      rowPixelSpacing: number;
+      columnPixelSpacing: number;
+    };
+    imagePixelModule?: {
+      samplesPerPixel: number;
+      photometricInterpretation: string;
+      rows: number;
+      columns: number;
+      bitsAllocated: number;
+      bitsStored: number;
+      highBit: number;
+      pixelRepresentation: number;
+      planarConfiguration?: number;
+      pixelAspectRatio?: number;
+      smallestPixelValue?: number;
+      largestPixelValue?: number;
+      redPaletteColorLookupTableDescriptor?: number[];
+      greenPaletteColorLookupTableDescriptor?: number[];
+      bluePaletteColorLookupTableDescriptor?: number[];
+      redPaletteColorLookupTableData: number[];
+      greenPaletteColorLookupTableData: number[];
+      bluePaletteColorLookupTableData: number[];
+    };
+  };
+}
+
+export default CPUFallbackEnabledElement;

package/src/types/CPUFallbackLUT.ts

@@ -0,0 +1,5 @@
+type CPUFallbackLUT = {
+  lut: number[];
+};
+
+export default CPUFallbackLUT;

package/src/types/CPUFallbackLookupTable.ts

@@ -0,0 +1,17 @@
+import Point4 from './Point4';
+
+interface CPUFallbackLookupTable {
+  setNumberOfTableValues: (number: number) => void;
+  setRamp: (ramp: string) => void;
+  setTableRange: (start: number, end: number) => void;
+  setHueRange: (start: number, end: number) => void;
+  setSaturationRange: (start: number, end: number) => void;
+  setValueRange: (start: number, end: number) => void;
+  setRange: (start: number, end: number) => void;
+  setAlphaRange: (start: number, end: number) => void;
+  getColor: (scalar: number) => Point4;
+  build: (force: boolean) => void;
+  setTableValue(index: number, rgba: Point4);
+}
+
+export default CPUFallbackLookupTable;

package/src/types/CPUFallbackRenderingTools.ts

@@ -0,0 +1,25 @@
+import CPUFallbackLookupTable from './CPUFallbackLookupTable';
+import CPUFallbackLUT from './CPUFallbackLUT';
+
+type CPUFallbackRenderingTools = {
+  renderCanvas?: HTMLCanvasElement;
+  lastRenderedIsColor?: boolean;
+  lastRenderedImageId?: string;
+  lastRenderedViewport?: {
+    windowWidth: number | number[];
+    windowCenter: number | number[];
+    invert: boolean;
+    rotation: number;
+    hflip: boolean;
+    vflip: boolean;
+    modalityLUT: CPUFallbackLUT;
+    voiLUT: CPUFallbackLUT;
+    colormap: unknown;
+  };
+  renderCanvasContext?: CanvasRenderingContext2D;
+  colormapId?: string;
+  colorLUT?: CPUFallbackLookupTable;
+  renderCanvasData?: ImageData;
+};
+
+export default CPUFallbackRenderingTools;

package/src/types/CPUFallbackTransform.ts

@@ -0,0 +1,16 @@
+import Point2 from './Point2';
+import TransformMatrix2D from './TransformMatrix2D';
+
+interface CPUFallbackTransform {
+  reset: () => void;
+  clone: () => CPUFallbackTransform;
+  multiply: (matrix: TransformMatrix2D) => void;
+  getMatrix: () => TransformMatrix2D;
+  invert: () => void;
+  rotate: (rad: number) => void;
+  translate: (x: number, y: number) => void;
+  scale: (sx: number, sy: number) => void;
+  transformPoint: (point: Point2) => Point2;
+}
+
+export default CPUFallbackTransform;

package/src/types/CPUFallbackViewport.ts

@@ -0,0 +1,29 @@
+import CPUFallbackViewportDisplayedArea from './CPUFallbackViewportDisplayedArea';
+import CPUFallbackColormap from './CPUFallbackColormap';
+import CPUFallbackLUT from './CPUFallbackLUT';
+
+type CPUFallbackViewport = {
+  scale?: number;
+  parallelScale?: number;
+  focalPoint?: number[];
+  translation?: {
+    x: number;
+    y: number;
+  };
+  voi?: {
+    windowWidth: number;
+    windowCenter: number;
+  };
+  invert?: boolean;
+  pixelReplication?: boolean;
+  rotation?: number;
+  hflip?: boolean;
+  vflip?: boolean;
+  modalityLUT?: CPUFallbackLUT;
+  voiLUT?: CPUFallbackLUT;
+  colormap?: CPUFallbackColormap;
+  displayedArea?: CPUFallbackViewportDisplayedArea;
+  modality?: string;
+};
+
+export default CPUFallbackViewport;

package/src/types/CPUFallbackViewportDisplayedArea.ts

@@ -0,0 +1,15 @@
+type CPUFallbackViewportDisplayedArea = {
+  tlhc: {
+    x: number;
+    y: number;
+  };
+  brhc: {
+    x: number;
+    y: number;
+  };
+  rowPixelSpacing: number;
+  columnPixelSpacing: number;
+  presentationSizeMode: string;
+};
+
+export default CPUFallbackViewportDisplayedArea;

package/src/types/CPUIImageData.ts

@@ -0,0 +1,47 @@
+import { Point3, Scaling, Mat3 } from '../types';
+
+type CPUImageData = {
+  worldToIndex?: (point: Point3) => Point3;
+  indexToWorld?: (point: Point3) => Point3;
+  getWorldToIndex?: () => Point3;
+  getIndexToWorld?: () => Point3;
+  /** Last spacing is always EPSILON */
+  getSpacing?: () => Point3;
+  getDirection?: () => Mat3;
+  getScalarData?: () => number[];
+  /** Last index is always 1 */
+  getDimensions?: () => Point3;
+};
+
+type CPUIImageData = {
+  dimensions: Point3;
+  direction: Mat3;
+  spacing: Point3;
+  origin: Point3;
+  imageData: CPUImageData;
+  metadata: { Modality: string };
+  scalarData: number[];
+  scaling: Scaling;
+  /** whether the image has pixel spacing and it is not undefined */
+  hasPixelSpacing?: boolean;
+  /** preScale object */
+  preScale?: {
+    /** boolean flag to indicate whether the image has been scaled */
+    scaled?: boolean;
+    /** scaling parameters */
+    scalingParameters?: {
+      /** modality of the image */
+      modality?: string;
+      /** rescale slop */
+      rescaleSlope?: number;
+      /** rescale intercept */
+      rescaleIntercept?: number;
+      /** PT suvbw */
+      suvbw?: number;
+    };
+  };
+};
+
+export default CPUIImageData;
+
+export { CPUImageData };

package/src/types/ContourData.ts

@@ -0,0 +1,19 @@
+import { ContourType } from '../enums';
+import Point3 from './Point3';
+
+type PublicContourSetData = ContourSetData;
+
+type ContourSetData = {
+  id: string;
+  data: ContourData[];
+  frameOfReferenceUID: string;
+  color?: Point3;
+};
+
+type ContourData = {
+  points: Point3[];
+  type: ContourType;
+  color?: Point3;
+};
+
+export type { PublicContourSetData, ContourSetData, ContourData };

package/src/types/Cornerstone3DConfig.ts

@@ -0,0 +1,31 @@
+type Cornerstone3DConfig = {
+  detectGPU: any;
+  rendering: {
+    // vtk.js supports 8bit integer textures and 32bit float textures.
+    // However, if the client has norm16 textures (it can be seen by visiting
+    // the webGl report at https://webglreport.com/?v=2), vtk will be default
+    // to use it to improve memory usage. However, if the client don't have
+    // it still another level of optimization can happen by setting the
+    // preferSizeOverAccuracy since it will reduce the size of the texture to half
+    // float at the cost of accuracy in rendering. This is a tradeoff that the
+    // client can decide.
+    //
+    // Read more in the following Pull Request:
+    // 1. HalfFloat: https://github.com/Kitware/vtk-js/pull/2046
+    // 2. Norm16: https://github.com/Kitware/vtk-js/pull/2058
+    preferSizeOverAccuracy: boolean;
+    // Whether the EXT_texture_norm16 extension is supported by the browser.
+    // WebGL 2 report (link: https://webglreport.com/?v=2) can be used to check
+    // if the browser supports this extension.
+    // In case the browser supports this extension, instead of using 32bit float
+    // textures, 16bit float textures will be used to reduce the memory usage where
+    // possible.
+    // Norm16 may not work currently due to the two active bugs in chrome + safari
+    // https://bugs.chromium.org/p/chromium/issues/detail?id=1408247
+    // https://bugs.webkit.org/show_bug.cgi?id=252039
+    useNorm16Texture: boolean;
+    useCPURendering: boolean;
+  };
+};
+
+export default Cornerstone3DConfig;

package/src/types/CustomEventType.ts

@@ -0,0 +1,14 @@
+interface CustomEvent<T = any> extends Event {
+  /**
+   * Returns any custom data event was created with. Typically used for synthetic events.
+   */
+  readonly detail: T;
+  initCustomEvent(
+    typeArg: string,
+    canBubbleArg: boolean,
+    cancelableArg: boolean,
+    detailArg: T
+  ): void;
+}
+
+export default CustomEvent;