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

package/src/types/IViewport.ts

@@ -6,7 +6,216 @@ import { ActorEntry } from './IActor';
 import ViewportType from '../enums/ViewportType';
 import ViewportStatus from '../enums/ViewportStatus';
 import DisplayArea from './displayArea';
-import { IRetrieveConfiguration } from './IRetrieveConfiguration';
+import BoundsLPS from './BoundsLPS';
+
+/**
+ * Specifies what view to get a reference for.
+ * This set of options allows a Viewport to return a reference for an image
+ * not currently in view, such as for a different slice, or containing a given
+ * set of points.
+ */
+export type ViewReferenceSpecifier = {
+  /**
+   * The slice index within the current viewport camera to get a reference for.
+   * Note that slice indexes are dependent on the particular view being shown
+   * and cannot be shared across different view types such as stacks and
+   * volumes, or two viewports showing different orientations or slab thicknesses.
+   */
+  sliceIndex?: number | [number, number];
+  /**
+   * Specifies to get a view reference that refers to the generic frame of
+   * reference rather than to a specific volume or stack.  Thus, the view
+   * reference would be compatible with any view showing the same frame of
+   * reference UID.
+   */
+  forFrameOfReference?: boolean;
+  /** Set of points to get a reference for, in world space */
+  points?: Point3[];
+  /** The volumeId to reference */
+  volumeId?: string;
+};
+
+/**
+ * It is often important to decide if a given view can display a specific
+ * view reference.  For example, annotations need to know if they are
+ * shown on a view.  Some operations need to know if the view COULD show
+ * the given object if certain changes were made to the view.  This object
+ * allows specifying what changes are permitted in order to determine if the
+ * view could show the image.
+ */
+export type ReferenceCompatibleOptions = {
+  /**
+   * Test whether the view could be shown if the viewport were navigated.
+   * That is, test is just changing the slice position and zoom/pan would
+   * allow showing the view.
+   */
+  withNavigation?: boolean;
+  /**
+   * For a stack viewport, return true if this viewport could show the given
+   * view if it were converted into a volume viewport.  Has no affect on volume
+   * viewports.
+   */
+  asVolume?: boolean;
+  /**
+   * For volume viewports, return true if this viewport could show the given view
+   * if the orientation was changed.
+   */
+  withOrientation?: boolean;
+  /**
+   * Use this imageURI for testing - may or may not be the current one.
+   * Should be a straight contains URI for the set of imageIds in any of
+   * the volumes or set of image ids.
+   * This is an optimization setting only that makes the test faster, and does
+   * not need to be provided.
+   */
+  imageURI?: string;
+};
+
+/**
+ * A view reference references the image/location of an image.  Typical use
+ * cases include remembering the current position of a viewport to allow returning
+ * to it later, as well as determining whether specific views should show annotations
+ * or other overlay information.
+ */
+export type ViewReference = {
+  /**
+   * The FrameOfReferenceUID
+   */
+  FrameOfReferenceUID: string;
+  /**
+   * An optional property used to specify the particular image that this view includes.
+   * For volumes, that will specify which image is closest to the requested
+   * point(s) in some fashion, or will be undefined when the reference applies
+   * to any volume with the same frame of reference.
+   *
+   * The naming of this particular attribute matches the DICOM SR naming for the
+   * referenced image, as well as historical naming in CS3D.
+   */
+  referencedImageId?: string;
+
+  /**
+   * The focal point of the camera in world space.
+   * The focal point is used for to define the stack positioning, but not the
+   * zoom/pan (which is defined by the view presentation
+   * object.)
+   *
+   * Single point objects (probe etc) should use the probe point as the camera
+   * focal point as that allows omitting the view plane normal and showing the probe
+   * in any orientation.
+   */
+  cameraFocalPoint?: Point3;
+  /**
+   * The normal for the current view.  This defines the plane used to show the
+   * 2d annotation.  This should be omitted if the annotation is a point to
+   * allows for single-point annotations.
+   */
+  viewPlaneNormal?: Point3;
+  /**
+   * The view up - this is only used for resetting orientation
+   */
+  viewUp?: Point3;
+  /**
+   * The slice index or range for this view.
+   * <b>NOTE</b> The slice index is relative to the volume or stack of images.
+   * You cannot apply a slice index from one volume to another as they do NOT
+   * apply.   The referencedImageId should belong to the volume you are trying
+   * to apply to, the viewPlane normal should be identical, and then you can
+   * apply the sliceIndex.
+   *
+   * For stack viewports, the referencedImageId should occur at the given slice index.
+   *
+   * <b>Note 2</b>slice indices don't necessarily indicate anything positionally
+   * within the stack of images - subsequent slice indexes can be at opposite
+   * ends or can be co-incident but separate types of images.
+   */
+  sliceIndex?: number | [number, number];
+
+  /**
+   * VolumeId that the referencedImageId was chosen from
+   */
+  volumeId?: string;
+  /**
+   * The bounds that are shown.  Allows specifying whether a view includes
+   * particular bounds or not.  This will be in world coordinates.
+   */
+  bounds?: BoundsLPS;
+};
+
+/**
+ * A view presentation stores information about how the view is presented to the
+ * user, such as rotation, the displayed area, pan/zoom etc.  This is represented
+ * as values which are independent of the view type or size as much as possible,
+ * by normalizing the values to the type of view presented.  This allows
+ * remember or synchronizing values in a much wider variety of places than
+ * using the raw/underlying view data such as camera position.
+ */
+export type ViewPresentation = {
+  /**
+   * The slice thickness - in frames(true/default) it will be 1 for a frame distance of
+   * 1 pixel thickness, while for mm will be in mm distance.
+   */
+  slabThickness?: number;
+
+  /**
+   * The rotation of the view - this is related to cameraViewUp, but is relative
+   * to the viewNormal and the default viewUp for that viewNormal.
+   */
+  rotation?: number;
+
+  /**
+   * The display area being shown.  This is more consistent than applying a set
+   * of boundary areas.
+   */
+  displayArea?: DisplayArea;
+
+  /**
+   * The zoom value is a zoom factor relative either to fit to canvas or relative
+   * to the display area.
+   * The default true units are relative to the initial camera
+   * scale to fit is used to get units relative to the scale to fit camera.
+   */
+  zoom?: number;
+
+  /**
+   * The pan value is how far the pan has moved relative to the fit to canvas
+   * or relative to the display area initial position/sizing.
+   * true is the default units, which is relative to the initial canvas setting,
+   * in zoom relative units.
+   */
+  pan?: Point2;
+};
+
+/**
+ * A view presentation selector allows choosing what view attributes should be
+ * returned by a call to getViewPresentation.  This allows a shared selection
+ * object to be used to specify which presentation attributes are to be used.
+ *
+ * For example, a synchronizer might choose to use a presentation selector
+ * so that multiple viewports could specify to synchronizer, say slabThickness
+ * and windowLevel across one set, while a different synchronizer would choose
+ * to apply zoom and pan.
+ * Then, a resize operation might choose to synchronize display area, zoom and pan, but
+ * not window level or slab thickness.
+ * A store/remember state of viewport might choose to synchronize everything
+ * Individual tools might choose to use synchronization of the specific attribute
+ * which they are modifying (such as rotation) for history undo/redo, but use the
+ * same re-apply function to undo the remembered history.
+ *
+ * It is certainly possible to implement each of these with their own selectors
+ * which call the particular get/set functions, but that makes it more work to
+ * share particular sets for different uses.
+ */
+export type ViewPresentationSelector = {
+  slabThickness?: boolean;
+  // Camera relative parameters
+  rotation?: boolean;
+  displayArea?: boolean;
+  zoom?: boolean;
+  pan?: boolean;
+  // Transfer function relative parameters
+  windowLevel?: boolean;
+  paletteLut?: boolean;
+};
 
 /**
  * Viewport interface for cornerstone viewports
@@ -14,6 +223,15 @@ import { IRetrieveConfiguration } from './IRetrieveConfiguration';
 interface IViewport {
   /** unique identifier of the viewport */
   id: string;
+
+  getWidget: (id: string) => any;
+
+  addWidget: (id: string, widget: any) => void;
+
+  getWidgets: () => any;
+
+  removeWidgets: () => void;
+
   /** renderingEngineId the viewport belongs to */
   renderingEngineId: string;
   /** viewport type, can be ORTHOGRAPHIC or STACK for now */
@@ -42,7 +260,7 @@ interface IViewport {
   isDisabled: boolean;
   /** The rendering state of this viewport */
   viewportStatus: ViewportStatus;
-  /** the rotation applied to the view */
+  /** get the rotation either from the camera provided or the viewport if not provided */
   getRotation: () => number;
   /** frameOfReferenceUID the viewport's default actor is rendering */
   getFrameOfReferenceUID: () => string;
@@ -66,6 +284,8 @@ interface IViewport {
   addActors(actors: Array<ActorEntry>): void;
   /** add one actor */
   addActor(actorEntry: ActorEntry): void;
+  /** get actor UIDs */
+  getActorUIDs(): Array<string>;
   /** remove all actors from the viewport */
   removeAllActors(): void;
   /** remove array of uids */
@@ -104,8 +324,87 @@ interface IViewport {
   setPan(pan: Point2, storeAsInitialCamera?: boolean);
   /** sets the camera */
   setCamera(cameraInterface: ICamera, storeAsInitialCamera?: boolean): void;
+  /** Resets the camera */
+  resetCamera(
+    resetPan?: boolean,
+    resetZoom?: boolean,
+    resetToCenter?: boolean,
+    storeAsInitialCamera?: boolean
+  ): boolean;
+  /** Gets the number of slices in the current camera orientation */
+  getNumberOfSlices(): number;
+  /** Gets the index of the current image, it is not guaranteed to be the slice index in the view, use getSliceIndex for positional information */
+  getCurrentImageIdIndex(): number;
+  /** gets the positional slice location in the view, similar to scrollbar, the top image is 0, the bottom is getNumberOfSlices - 1 */
+  getSliceIndex(): number;
+  /**
+   * Gets a referenced image url of some sort - could be a real image id, or
+   * could be a URL with parameters. Regardless it refers to the currently displaying
+   * image as a string value.
+   */
+  getReferenceId(viewRefSpecifier?: ViewReferenceSpecifier): string;
+  /**
+   * Gets a view target specifying WHAT a view is displaying,
+   * allowing for checking if a given image is displayed or could be displayed
+   * in a given viewport.
+   * See getViewPresentation for HOW a view is displayed.
+   *
+   * @param viewRefSpecifier - choose an alternate view to be specified, typically
+   *      a different slice index in the same set of images.
+   */
+  getViewReference(viewRefSpecifier?: ViewReferenceSpecifier): ViewReference;
+  /**
+   * Find out if this viewport does or could show this view reference.
+   *
+   * @param options - allows specifying whether the view COULD display this with
+   *                  some modification - either navigation or displaying as volume.
+   * @returns true if the viewport could show this view reference
+   */
+  isReferenceViewable(
+    viewRef: ViewReference,
+    options?: ReferenceCompatibleOptions
+  ): boolean;
+  /**
+   * Gets a view presentation information specifying HOW a viewport displays
+   * something, but not what is being displayed.
+   * See getViewReference to get information on WHAT is being displayed.
+   *
+   * This is intended to have information on how an image is presented to the user, without
+   * specifying what image s displayed.  All of this information is available
+   * externally, but this method combines the parts of this that are appropriate
+   * for remember or applying to other views, without necessarily needing to know
+   * what all the atributes are.  That differs from methods like getCamera which
+   * fetch exact view details that are not likely to be identical between viewports
+   * as they change sizes or apply to different images.
+   *
+   * Note that the results of this can be used on different viewports, for example,
+   * the pan values can be applied to a volume viewport showing a CT, and a
+   * stack viewport showing an ultrasound.
+   *
+   * The selector allows choosing which view presentation attributes to return.
+   * Some default values are available from `Viewport.CameraViewPresentation` and
+   * `Viewport.TransferViewPresentation`
+   *
+   * @param viewPresSel - select which attributes to display.
+   */
+  getViewPresentation(viewPresSel?: ViewPresentationSelector): ViewPresentation;
+
+  /**
+   * Navigates this viewport to the specified viewRef.
+   * Throws an exception if that isn't possible on this viewport.
+   * Returns immediately if viewRef isn't defined.
+   */
+  setViewReference(viewRef: ViewReference);
+
+  /**
+   * Sets the presentation parameters from the specified viewPres object.
+   * Sets display area, zoom, pan, rotation, voi LUT
+   */
+  setViewPresentation(viewPres: ViewPresentation);
+
   /** whether the viewport has custom rendering */
   customRenderViewportToCanvas: () => unknown;
+
   _getCorners(bounds: Array<number>): Array<number>[];
   updateRenderingPipeline: () => void;
 }

package/src/types/IVolume.ts

@@ -1,45 +1,8 @@
-import type { vtkImageData } from '@kitware/vtk.js/Common/DataModel/ImageData';
-import type Point3 from './Point3';
-import type Metadata from './Metadata';
-import Mat3 from './Mat3';
-
-type VolumeScalarData = Float32Array | Uint8Array | Uint16Array | Int16Array;
+import { ImageVolumeProps } from './ImageVolumeProps';
 
 /**
- * Cornerstone ImageVolume interface.
+ * Backwards compatibility for IVolume
  */
-interface IVolume {
-  /** unique identifier for the volume in the cache */
-  volumeId: string;
-  /** volume metadata */
-  metadata: Metadata;
-  /** volume dimensions */
-  dimensions: Point3;
-  /** volume spacing */
-  spacing: Point3;
-  /** volume origin */
-  origin: Point3;
-  /** volume direction */
-  direction: Mat3;
-  /** volume scalarData */
-  scalarData: VolumeScalarData | Array<VolumeScalarData>;
-  /** volume size in bytes */
-  sizeInBytes?: number;
-  /** volume image data as vtkImageData */
-  imageData?: vtkImageData;
-  /** referencedVolumeId if volume is derived from another volume */
-  referencedVolumeId?: string;
-  /** volume scaling metadata */
-  scaling?: {
-    PT?: {
-      // @TODO: Do these values exist?
-      SUVlbmFactor?: number;
-      SUVbsaFactor?: number;
-      // accessed in ProbeTool
-      suvbwToSuvlbm?: number;
-      suvbwToSuvbsa?: number;
-    };
-  };
-}
+type IVolume = ImageVolumeProps;
 
-export { IVolume as default, IVolume, VolumeScalarData };
+export { IVolume };

package/src/types/IVolumeViewport.ts

@@ -13,10 +13,18 @@ import { VolumeViewportProperties } from '.';
 export default interface IVolumeViewport extends IViewport {
   useCPURendering: boolean;
   getFrameOfReferenceUID: () => string;
+
+  /**
+   * Retrieve the viewport default properties
+   * If volumeId is given, we retrieve the default properties of a volumeId if it exists
+   * If not given,we return the global properties of the viewport
+   * default viewport properties including voi, invert, interpolation type, colormap
+   */
+  getDefaultProperties: (volumeId?: string) => VolumeViewportProperties;
   /**
    * Retrieve the viewport properties
    */
-  getProperties: () => VolumeViewportProperties;
+  getProperties: (volumeId?: string) => VolumeViewportProperties;
   /**
    * canvasToWorld Returns the world coordinates of the given `canvasPos`
    * projected onto the plane defined by the `Viewport`'s `vtkCamera`'s focal point
@@ -57,6 +65,20 @@ export default interface IVolumeViewport extends IViewport {
    * currently being viewed.
    */
   getCurrentImageId: () => string;
+  /**
+   * Sets the default properties for the viewport. If no volumeId is provided
+   * it applies the properties to the default volume actor (first volume)
+   */
+  setDefaultProperties(
+    ViewportProperties: VolumeViewportProperties,
+    volumeId?: string
+  ): void;
+  /**
+   * Remove the global default properties of the viewport or remove default properties for a volumeId if specified
+   * If volumeId is given, we remove the default properties only for this volumeId, if not
+   * the global default properties will be removed
+   */
+  clearDefaultProperties(volumeId?: string): void;
   /**
    * Sets the properties for the viewport. If no volumeId is provided
    * it applies the properties to the default volume actor (first volume)
@@ -66,6 +88,10 @@ export default interface IVolumeViewport extends IViewport {
     volumeId?: string,
     suppressEvents?: boolean
   ): void;
+  /**
+   * Reset the viewport properties to the default values
+   */
+  resetProperties(volumeId: string): void;
   /**
    * Creates volume actors for all volumes defined in the `volumeInputArray`.
    * For each entry, if a `callback` is supplied, it will be called with the new volume actor as input.
@@ -110,8 +136,14 @@ export default interface IVolumeViewport extends IViewport {
   resetCamera(
     resetPan?: boolean,
     resetZoom?: boolean,
-    resetToCenter?: boolean
+    resetToCenter?: boolean,
+    resetRotation?: boolean,
+    supressEvents?: boolean
   ): boolean;
+  /**
+   * Reset the slab thickness for actors of the viewport.
+   */
+  resetSlabThickness(): void;
   /**
    * Sets the blendMode for actors of the viewport.
    */
@@ -142,8 +174,4 @@ export default interface IVolumeViewport extends IViewport {
   getImageData(volumeId?: string): IImageData | undefined;
 
   setOrientation(orientation: OrientationAxis): void;
-  /**
-   * Reset the viewport properties to the default values
-   */
-  resetProperties(volumeId?: string): void;
 }

package/src/types/ImageVolumeProps.ts

@@ -0,0 +1,15 @@
+import { VolumeProps } from '.';
+
+/**
+ * ImageVolume which is considered a special case of a Volume, which is
+ * constructed out of set of images (imageIds). Unlike Volume which can be
+ * constructed from any type of volumetric data, such as nifti or nrrd,
+ */
+interface ImageVolumeProps extends VolumeProps {
+  /** imageIds of the volume (if it is built of separate imageIds) */
+  imageIds: Array<string>;
+  /** if the volume is created from a stack, the imageIds of the stack */
+  referencedImageIds?: Array<string>;
+}
+
+export { ImageVolumeProps };

package/src/types/PixelDataTypedArray.ts

@@ -5,3 +5,11 @@ export type PixelDataTypedArray =
   | Uint8Array
   | Int8Array
   | Uint8ClampedArray;
+
+export type PixelDataTypedArrayString =
+  | 'Float32Array'
+  | 'Int16Array'
+  | 'Uint16Array'
+  | 'Uint8Array'
+  | 'Int8Array'
+  | 'Uint8ClampedArray';

package/src/types/Point3.ts

@@ -1,6 +1,15 @@
 /**
  * This duplicates the typing established in gl-matrix for a vec3
  */
-type Point3 = [number, number, number];
+export type Point3 = [number, number, number];
+
+/**
+ * Some algorithms use separated values
+ */
+export type PointsXYZ = {
+  x: number[];
+  y: number[];
+  z: number[];
+};
 
 export default Point3;

package/src/types/SurfaceData.ts

@@ -0,0 +1,15 @@
+import Point3 from './Point3';
+
+type PublicSurfaceData = {
+  id: string;
+  data: SurfaceData;
+  frameOfReferenceUID: string;
+  color?: Point3;
+};
+
+type SurfaceData = {
+  points: number[];
+  polys: number[];
+};
+
+export type { PublicSurfaceData, SurfaceData };

package/src/types/VideoViewportProperties.ts

@@ -0,0 +1,15 @@
+import { ViewportProperties } from './ViewportProperties';
+import Point2 from './Point2';
+
+/**
+ * Stack Viewport Properties
+ */
+type VideoViewportProperties = ViewportProperties & {
+  loop?: boolean;
+  muted?: boolean;
+  pan?: Point2;
+  playbackRate?: number;
+  scrollSpeed?: number;
+};
+
+export default VideoViewportProperties;

package/src/types/VideoViewportTypes.ts

@@ -0,0 +1,20 @@
+import { ViewportType } from '../enums';
+import Point2 from './Point2';
+
+export type InternalVideoCamera = {
+  panWorld?: Point2;
+  parallelScale?: number;
+};
+
+export type VideoViewportInput = {
+  id: string;
+  renderingEngineId: string;
+  type: ViewportType;
+  element: HTMLDivElement;
+  sx: number;
+  sy: number;
+  sWidth: number;
+  sHeight: number;
+  defaultOptions: any;
+  canvas: HTMLCanvasElement;
+};

package/src/types/ViewportProperties.ts

@@ -1,18 +1,21 @@
 import { InterpolationType, VOILUTFunctionType } from '../enums';
 import { VOIRange } from './voi';
+import { ColormapPublic } from './Colormap';
 
 /**
  * Shared Viewport Properties between Stack and Volume Viewports
  */
-type ViewportProperties = {
+export type ViewportProperties = {
   /** voi range (upper, lower) for the viewport */
   voiRange?: VOIRange;
   /** VOILUTFunction type which is LINEAR or SAMPLED_SIGMOID */
   VOILUTFunction?: VOILUTFunctionType;
   /** invert flag - whether the image is inverted */
   invert?: boolean;
+  /** Colormap applied to the viewport*/
+  colormap?: ColormapPublic;
   /** interpolation type */
   interpolationType?: InterpolationType;
+  /**Rotation of the camera */
+  rotation?: number;
 };
-
-export type { ViewportProperties };

package/src/types/VolumeProps.ts

@@ -0,0 +1,57 @@
+import type { vtkImageData } from '@kitware/vtk.js/Common/DataModel/ImageData';
+import type Point3 from './Point3';
+import type Metadata from './Metadata';
+import Mat3 from './Mat3';
+import { PixelDataTypedArray } from './PixelDataTypedArray';
+
+/**
+ * Properties required to instantiate a Volume object.
+ * This includes all the necessary data and metadata to define
+ * a volume in 3D/4D space.
+ */
+interface VolumeProps {
+  /** Unique identifier for the volume */
+  volumeId: string;
+
+  /** Metadata describing the volume */
+  metadata: Metadata;
+
+  /** Dimensions of the volume (width, height, depth) */
+  dimensions: Point3;
+
+  /** Spacing between volume points in 3D world space */
+  spacing: Point3;
+
+  /** Origin point of the volume in world space */
+  origin: Point3;
+
+  /** Direction of the volume in world space */
+  direction: Mat3;
+
+  /** Image data representing the volume */
+  imageData?: vtkImageData;
+
+  /** Scalar data representing the volume's intensity values */
+  scalarData: PixelDataTypedArray | Array<PixelDataTypedArray>;
+
+  /** Size of the volume data in bytes (optional) */
+  sizeInBytes?: number;
+
+  /** Property to store additional information */
+  additionalDetails?: Record<string, any>;
+
+  /** Scaling parameters if the volume contains scaled data (optional) */
+  scaling?: {
+    PT?: {
+      SUVlbmFactor?: number;
+      SUVbsaFactor?: number;
+      suvbwToSuvlbm?: number;
+      suvbwToSuvbsa?: number;
+    };
+  };
+
+  /** Optional ID of a referenced volume if this volume is derived from another */
+  referencedVolumeId?: string;
+}
+
+export { VolumeProps };

package/src/types/VolumeViewportProperties.ts

@@ -1,14 +1,16 @@
-import { ColormapPublic } from './Colormap';
 import { ViewportProperties } from './ViewportProperties';
+import { OrientationAxis } from '../enums';
 
 /**
  * Stack Viewport Properties
  */
 type VolumeViewportProperties = ViewportProperties & {
-  /** color maps  */
-  colormap?: ColormapPublic;
   /** 3d preset */
   preset?: string;
+
+  slabThickness?: number;
+
+  orientation?: OrientationAxis;
 };
 
 export default VolumeViewportProperties;