@cornerstonejs/core 2.0.0-beta.1 → 2.0.0-beta.10

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

@@ -0,0 +1,30 @@
+import { ImageActor } from './IActor';
+
+/**
+ * Stack input callback type, used to perform operations on the image data
+ * after it has been loaded.
+ */
+type StackInputCallback = (params: {
+  /** vtk image actor */
+  imageActor: ImageActor;
+  /** unique image Id in the cache */
+  imageId: string;
+}) => unknown;
+
+/**
+ * StackInput that can be used to add an image actor  to a viewport. It includes
+ * mandatory `imageId` but other options such as `visibility` and `callback`
+ * can also be provided
+ */
+interface IStackInput {
+  /** imageId of the image in the cache */
+  imageId: string;
+  // actorUID of the imageActor being added
+  actorUID?: string;
+  /** Visibility of the image actor - by default it is true */
+  visibility?: boolean;
+  /** Callback to be called when the image is added to the viewport */
+  callback?: StackInputCallback;
+}
+
+export type { IStackInput, StackInputCallback };

package/src/types/IStackViewport.ts

@@ -1,144 +1,3 @@
-import CPUFallbackColormapData from './CPUFallbackColormapData';
-import CPUIImageData from './CPUIImageData';
-import ICamera from './ICamera';
-import IImageData from './IImageData';
-import { IViewport } from './IViewport';
-import Point2 from './Point2';
-import Point3 from './Point3';
-import { Scaling } from './ScalingParameters';
-import StackViewportProperties from './StackViewportProperties';
-import { ColormapRegistration } from './Colormap';
-import IImage from './IImage';
+import type IStackViewport from '../RenderingEngine/StackViewport';
 
-/**
- * Interface for Stack Viewport
- */
-export default interface IStackViewport extends IViewport {
-  modality: string;
-  /** Scaling parameters */
-  scaling: Scaling;
-  /**
-   * Resizes the viewport - only used in CPU fallback for StackViewport. The
-   * GPU resizing happens inside the RenderingEngine.
-   */
-  resize: () => void;
-  /**
-   * Returns the frame of reference UID, if the image doesn't have imagePlaneModule
-   * metadata, it returns undefined, otherwise, frameOfReferenceUID is returned.
-   */
-  getFrameOfReferenceUID: () => string;
-  /**
-   * Sets the properties for the viewport on the default actor. Properties include
-   * setting the VOI, inverting the colors and setting the interpolation type, rotation
-   */
-  setProperties(
-    { voiRange, invert, interpolationType, rotation }: StackViewportProperties,
-    suppressEvents?: boolean
-  ): void;
-  /**
-   * Retrieve the viewport properties
-   */
-  getProperties: () => StackViewportProperties;
-  /**
-   * canvasToWorld Returns the world coordinates of the given `canvasPos`
-   * projected onto the plane defined by the `Viewport`'s camera.
-   */
-  canvasToWorld: (canvasPos: Point2) => Point3;
-  /**
-   * Returns the canvas coordinates of the given `worldPos`
-   * projected onto the `Viewport`'s `canvas`.
-   */
-  worldToCanvas: (worldPos: Point3) => Point2;
-  /**
-   * Returns the index of the imageId being renderer
-   */
-  getCurrentImageIdIndex: () => number;
-  /**
-   * Returns the list of image Ids for the current viewport
-   */
-  getImageIds: () => string[];
-  /**
-   * Returns true if the viewport contains the imageId
-   */
-  hasImageId: (imageId: string) => boolean;
-  /**
-   * Returns true if the viewport contains the imageURI
-   */
-  hasImageURI: (imageURI: string) => boolean;
-  /**
-   * Returns the currently rendered imageId
-   */
-  getCurrentImageId: () => string;
-
-  /**
-   * Custom rendering pipeline for the rendering for the CPU fallback
-   */
-  customRenderViewportToCanvas: () => {
-    canvas: HTMLCanvasElement;
-    element: HTMLDivElement;
-    viewportId: string;
-    renderingEngineId: string;
-  };
-  /**
-   * Returns the image and its properties that is being shown inside the
-   * stack viewport. It returns, the image dimensions, image direction,
-   * image scalar data, vtkImageData object, metadata, and scaling (e.g., PET suvbw)
-   */
-  getImageData(): IImageData | CPUIImageData;
-  /**
-   * Returns the raw/loaded image being shown inside the stack viewport.
-   */
-  getCornerstoneImage: () => IImage;
-  /**
-   * Reset the viewport properties to the default values
-   */
-  resetProperties(): void;
-  /**
-   * If the user has selected CPU rendering, return the CPU camera, otherwise
-   * return the default camera
-   */
-  getCamera(): ICamera;
-  /**
-   * Set the camera based on the provided camera object.
-   */
-  setCamera(cameraInterface: ICamera): void;
-  /**
-   * Sets the imageIds to be visualized inside the stack viewport. It accepts
-   * 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.
-   */
-  setStack(
-    imageIds: Array<string>,
-    currentImageIdIndex?: number
-  ): Promise<string>;
-  /**
-   * Centers Pan and resets the zoom for stack viewport.
-   */
-  resetCamera(resetPan?: boolean, resetZoom?: boolean): boolean;
-  /**
-   * Loads the image based on the provided imageIdIndex. It is an Async function which
-   * returns a promise that resolves to the imageId.
-   */
-  setImageIdIndex(imageIdIndex: number): Promise<string>;
-  /**
-   * Calibrates the image with new metadata that has been added for imageId. To calibrate
-   * a viewport, you should add your calibration data manually to
-   * calibratedPixelSpacingMetadataProvider and call viewport.calibrateSpacing
-   * for it get applied.
-   */
-  calibrateSpacing(imageId: string): void;
-  /**
-   * If the renderer is CPU based, throw an error. Otherwise, returns the `vtkRenderer` responsible for rendering the `Viewport`.
-   */
-  getRenderer(): any;
-  /**
-   * Sets the colormap for the current viewport.
-   * @param colormap - The colormap data to use.
-   */
-  setColormap(colormap: CPUFallbackColormapData | ColormapRegistration): void;
-  /**
-   * It sets the colormap to the default colormap.
-   */
-  unsetColormap(): void;
-}
+export default IStackViewport;

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

@@ -0,0 +1,14 @@
+import Point3 from './Point3';
+
+export interface ISurface {
+  readonly id: string;
+  readonly sizeInBytes: number;
+  readonly frameOfReferenceUID: string;
+  getColor(): Point3;
+  setColor(color: Point3): void;
+  getPoints(): number[];
+  getPolys(): number[];
+  getSizeInBytes(): number;
+  setPoints(points: number[]): void;
+  setPolys(polys: number[]): void;
+}

package/src/types/IVideoViewport.ts

@@ -0,0 +1,87 @@
+import { IViewport } from './IViewport';
+import VideoViewportProperties from './VideoViewportProperties';
+
+/**
+ * Interface for Stack Viewport
+ */
+export default interface IVideoViewport extends IViewport {
+  /**
+   * Resizes the viewport - only used in CPU fallback for StackViewport. The
+   * GPU resizing happens inside the RenderingEngine.
+   */
+  resize: () => void;
+  /**
+   * Sets the properties for the viewport on the default actor.
+   */
+  setProperties(props: VideoViewportProperties, suppressEvents?: boolean): void;
+  /**
+   * Retrieve the viewport properties
+   */
+  getProperties: () => VideoViewportProperties;
+
+  /**
+   * Sets the video to play.
+   * The video should have at least some metadata in the metadata provider,
+   * including:
+   *   * study/series/sop common module for UIDs
+   *   * `cineModule` for information on number of frames and playback rate
+   *   * `imageUrlModule` - to get the URL for the image under the `rendered` attribute
+   *
+   * Without these, other tools requiring metadata wont work, although basic
+   * playback does work if the setVideoURL is used instead.
+   */
+  setVideo: (imageIds: string, imageIdIndex?: number) => Promise<unknown>;
+
+  /**
+   * Displays a raw video, without any metadata associated with it.  Plays back,
+   * but does not permit tools to apply to the viewport, which requires providing
+   * additional metadata for the study.
+   *
+   * @param url - to display
+   */
+  setVideoURL: (url: string) => void;
+
+  play: () => void;
+
+  pause: () => void;
+
+  /**
+   * Reset the viewport properties to the default values
+   */
+  resetProperties(): void;
+
+  /**
+   * Gets the current image id, including frame selction or frameless.
+   */
+  getCurrentImageId(): string;
+
+  /**
+   * Gets the current frame, 1 based
+   */
+  getFrameNumber(): number;
+
+  /**
+   * Sets the current frame
+   */
+  setFrameNumber(frameNo: number);
+
+  /**
+   * Sets the current video time, in seconds
+   */
+  setTime(time: number);
+
+  /**
+   * Sets the range of frames for displaying.  This is the range of frames
+   * that are shown/looped over when the video is playing.
+   * Note that ability to playback a frame range depends on the server
+   * implementing byte range requests, OR the video being easily cached in memory.
+   */
+  setFrameRange(range?: [number, number]);
+
+  getFrameRange(): [number, number];
+
+  /**
+   * Centers Pan and resets the zoom for stack viewport.
+   */
+  resetCamera(resetPan?: boolean, resetZoom?: boolean): boolean;
+}