@cornerstonejs/core 1.57.0 → 1.57.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cornerstonejs/core",
-  "version": "1.57.0",
+  "version": "1.57.1",
   "description": "",
   "main": "src/index.ts",
   "types": "dist/types/index.d.ts",
@@ -47,5 +47,5 @@
     "type": "individual",
     "url": "https://ohif.org/donate"
   },
-  "gitHead": "1699f915a5e7a5cf9295707fb5b62fe01d7e491b"
+  "gitHead": "f0b7bf4653169cad680753b9d79556b5998b5758"
 }

package/src/RenderingEngine/BaseVolumeViewport.ts

@@ -35,11 +35,13 @@ import type {
   VOIRange,
   EventTypes,
   VolumeViewportProperties,
-  TargetSpecifier,
+  ViewReferenceSpecifier,
+  ReferenceCompatibleOptions,
 } from '../types';
 import { VoiModifiedEventDetail } from '../types/EventTypes';
 import type { ViewportInput } from '../types/IViewport';
 import type IVolumeViewport from '../types/IVolumeViewport';
+import type { ViewReference } from '../types/IViewport';
 import {
   actorIsA,
   applyPreset,
@@ -49,6 +51,7 @@ import {
   invertRgbTransferFunction,
   triggerEvent,
   colormap as colormapUtils,
+  isEqual,
 } from '../utilities';
 import { createVolumeActor } from './helpers';
 import volumeNewImageEventDispatcher, {
@@ -534,6 +537,52 @@ abstract class BaseVolumeViewport extends Viewport implements IVolumeViewport {
     }
   }
 
+  /**
+   * Gets a view target, allowing comparison between view positions as well
+   * as restoring views later.
+   */
+  public getViewReference(
+    viewRefSpecifier: ViewReferenceSpecifier = {}
+  ): ViewReference {
+    const target = super.getViewReference(viewRefSpecifier);
+    if (viewRefSpecifier?.forFrameOfReference !== false) {
+      target.volumeId = this.getVolumeId(viewRefSpecifier);
+    }
+    // TODO - add referencedImageId as a base URL for an image to allow a generic
+    // method to specify which volumes this should apply to.
+    return {
+      ...target,
+      sliceIndex: this.getCurrentImageIdIndex(),
+    };
+  }
+
+  /**
+   * Find out if this viewport would show this view
+   *
+   * @param options - allows specifying whether the view COULD display this with
+   *                  some modification - either navigation or displaying as volume.
+   * @returns true if the target is compatible with this view
+   */
+  public isReferenceViewable(
+    viewRef: ViewReference,
+    options?: ReferenceCompatibleOptions
+  ): boolean {
+    if (!super.isReferenceViewable(viewRef, options)) {
+      return false;
+    }
+    if (options?.withNavigation) {
+      return true;
+    }
+    const currentSliceIndex = this.getCurrentImageIdIndex();
+    const { sliceIndex } = viewRef;
+    if (Array.isArray(sliceIndex)) {
+      return (
+        sliceIndex[0] <= currentSliceIndex && currentSliceIndex <= sliceIndex[1]
+      );
+    }
+    return sliceIndex === undefined || sliceIndex === currentSliceIndex;
+  }
+
   /**
    * Sets the properties for the volume viewport on the volume
    * and if setProperties is called for the first time, the properties will also become the default one.
@@ -1395,8 +1444,23 @@ abstract class BaseVolumeViewport extends Viewport implements IVolumeViewport {
 
   abstract getCurrentImageId(): string;
 
-  public getTargetId(specifier: TargetSpecifier = {}): string {
-    let { volumeId, sliceIndex } = specifier;
+  /** Gets the volumeId to use for references */
+  protected getVolumeId(specifier: ViewReferenceSpecifier) {
+    if (!specifier?.volumeId) {
+      const actorEntries = this.getActors();
+      if (!actorEntries) {
+        return;
+      }
+      // find the first image actor of instance type vtkVolume
+      return actorEntries.find(
+        (actorEntry) => actorEntry.actor.getClassName() === 'vtkVolume'
+      )?.uid;
+    }
+    return specifier.volumeId;
+  }
+
+  public getReferenceId(specifier: ViewReferenceSpecifier = {}): string {
+    let { volumeId, sliceIndex: sliceIndex } = specifier;
     if (!volumeId) {
       const actorEntries = this.getActors();
       if (!actorEntries) {

package/src/RenderingEngine/StackViewport.ts

@@ -33,9 +33,14 @@ import type {
   Scaling,
   StackViewportProperties,
   VOIRange,
+  ViewReference,
   VolumeActor,
 } from '../types';
-import { TargetSpecifier, ViewportInput } from '../types/IViewport';
+import {
+  ViewReferenceSpecifier,
+  ReferenceCompatibleOptions,
+  ViewportInput,
+} from '../types/IViewport';
 import {
   actorIsA,
   colormap as colormapUtils,
@@ -2827,9 +2832,61 @@ class StackViewport extends Viewport implements IStackViewport, IImagesLoader {
     return this.currentImageIdIndex;
   };
 
-  public getTargetId(specifier: TargetSpecifier = {}): string {
-    const { sliceIndex: imageIdIndex = this.currentImageIdIndex } = specifier;
-    return `imageId:${this.imageIds[imageIdIndex]}`;
+  /**
+   * Checks to see if this target is or could be shown in this viewport
+   */
+  public isReferenceViewable(
+    viewRef: ViewReference,
+    options: ReferenceCompatibleOptions = {}
+  ): boolean {
+    if (!super.isReferenceViewable(viewRef, options)) {
+      return false;
+    }
+
+    let { imageURI } = options;
+    const { referencedImageId, sliceIndex } = viewRef;
+
+    if (viewRef.volumeId && !referencedImageId) {
+      return options.asVolume === true;
+    }
+
+    let testIndex = this.getCurrentImageIdIndex();
+    if (options.withNavigation && typeof sliceIndex === 'number') {
+      testIndex = sliceIndex;
+    }
+    const imageId = this.imageIds[testIndex];
+    if (!imageId) {
+      return false;
+    }
+    if (!imageURI) {
+      // Remove the dataLoader scheme since that can change
+      const colonIndex = imageId.indexOf(':');
+      imageURI = imageId.substring(colonIndex + 1);
+    }
+    return referencedImageId.endsWith(imageURI);
+  }
+
+  /**
+   * Gets a standard target to show this image instance.
+   */
+  public getViewReference(
+    viewRefSpecifier: ViewReferenceSpecifier = {}
+  ): ViewReference {
+    const { sliceIndex: sliceIndex = this.currentImageIdIndex } =
+      viewRefSpecifier;
+    return {
+      ...super.getViewReference(viewRefSpecifier),
+      referencedImageId: `${this.imageIds[sliceIndex as number]}`,
+      sliceIndex: sliceIndex,
+    };
+  }
+
+  public getReferenceId(specifier: ViewReferenceSpecifier = {}): string {
+    const { sliceIndex: sliceIndex = this.currentImageIdIndex } = specifier;
+    if (Array.isArray(sliceIndex)) {
+      throw new Error('Use of slice ranges for stacks not supported');
+    }
+    return `imageId:${this.imageIds[sliceIndex]}`;
   }
 
   /**

package/src/RenderingEngine/VideoViewport.ts

@@ -15,7 +15,9 @@ import type {
   VOIRange,
   ICanvasActor,
   IImage,
-  TargetSpecifier,
+  ViewReferenceSpecifier,
+  ViewReference,
+  ReferenceCompatibleOptions,
 } from '../types';
 import * as metaData from '../metaData';
 import { Transform } from './helpers/cpuFallback/rendering/transform';
@@ -673,11 +675,20 @@ class VideoViewport extends Viewport implements IVideoViewport {
     return current;
   }
 
-  public getTargetId(specifier: TargetSpecifier = {}): string {
-    const { sliceIndex } = specifier;
+  /**
+   *  Gets a target id that can be used to specify how to show this
+   */
+  public getReferenceId(specifier: ViewReferenceSpecifier = {}): string {
+    const { sliceIndex: sliceIndex } = specifier;
     if (sliceIndex === undefined) {
       return `videoId:${this.getCurrentImageId()}`;
     }
+    if (Array.isArray(sliceIndex)) {
+      // Just remove the 1 from the end of the base URL - TODO, handle other types
+      return `videoId:${this.imageId.substring(0, this.imageId.length - 1)}${
+        sliceIndex[0] + 1
+      }-${sliceIndex[1] + 1}`;
+    }
     const baseTarget = this.imageId.replace(
       '/frames/1',
       `/frames/${1 + sliceIndex}`
@@ -685,6 +696,69 @@ class VideoViewport extends Viewport implements IVideoViewport {
     return `videoId:${baseTarget}`;
   }
 
+  /**
+   * Figure out if a given view can be shown in the current viewport.
+   */
+  public isReferenceViewable(
+    viewRef: ViewReference,
+    options: ReferenceCompatibleOptions = {}
+  ): boolean {
+    let { imageURI } = options;
+    const { referencedImageId, sliceIndex: sliceIndex } = viewRef;
+    if (!super.isReferenceViewable(viewRef)) {
+      return false;
+    }
+
+    const imageId = this.getCurrentImageId();
+    if (!imageURI) {
+      // Remove the dataLoader scheme and frame number
+      // TODO - handle more imageURI types.
+      const colonIndex = imageId.indexOf(':');
+      imageURI = imageId.substring(colonIndex + 1, imageId.length - 1);
+    }
+
+    if (options.withNavigation) {
+      return true;
+    }
+    const currentIndex = this.getCurrentImageIdIndex();
+    if (Array.isArray(sliceIndex)) {
+      return currentIndex >= sliceIndex[0] && currentIndex <= sliceIndex[1];
+    }
+    if (sliceIndex !== undefined) {
+      return currentIndex === sliceIndex;
+    }
+    if (!referencedImageId) {
+      return false;
+    }
+    const match = referencedImageId.match(VideoViewport.frameRangeExtractor);
+    if (!match || !match[2]) {
+      return true;
+    }
+    const range = match[2].split('-').map((it) => Number(it));
+    const frame = currentIndex + 1;
+    return range[0] <= frame && frame <= (range[1] ?? range[0]);
+  }
+
+  /**
+   * Gets a view target that species what type of view is required to show
+   * the current view, or the one specified in the forTarget modifiers.
+   */
+  public getViewReference(
+    viewRefSpecifier?: ViewReferenceSpecifier
+  ): ViewReference {
+    let sliceIndex = viewRefSpecifier?.sliceIndex;
+    if (!sliceIndex) {
+      sliceIndex = this.isPlaying
+        ? [this.frameRange[0] - 1, this.frameRange[1] - 1]
+        : this.getCurrentImageIdIndex();
+    }
+    return {
+      ...super.getViewReference(viewRefSpecifier),
+      referencedImageId: this.getReferenceId(viewRefSpecifier),
+      sliceIndex: sliceIndex,
+    };
+  }
+
   /**
    * Gets the 1 based frame number (ala DICOM value), eg `1+ currentImageIdIndex`
    */
@@ -962,6 +1036,14 @@ class VideoViewport extends Viewport implements IVideoViewport {
       time: this.videoElement.currentTime,
       duration: this.videoElement.duration,
     });
+    triggerEvent(this.element, EVENTS.IMAGE_RENDERED, {
+      element: this.element,
+      viewportId: this.id,
+      viewport: this,
+      renderingEngineId: this.renderingEngineId,
+      time: this.videoElement.currentTime,
+      duration: this.videoElement.duration,
+    });
 
     const frame = this.getFrameNumber();
     if (this.isPlaying) {

package/src/RenderingEngine/Viewport.ts

@@ -33,7 +33,9 @@ import type {
 import type {
   ViewportInput,
   IViewport,
-  TargetSpecifier,
+  ViewReferenceSpecifier,
+  ViewReference,
+  ReferenceCompatibleOptions,
 } from '../types/IViewport';
 import type { vtkSlabCamera } from './vtkClasses/vtkSlabCamera';
 import { getConfiguration } from '../init';
@@ -898,7 +900,7 @@ class Viewport implements IViewport {
     throw new Error('Not implemented');
   }
 
-  public getTargetId(specifier?: TargetSpecifier): string {
+  public getReferenceId(specifier?: ViewReferenceSpecifier): string {
     return null;
   }
 
@@ -1381,6 +1383,45 @@ class Viewport implements IViewport {
     return { widthWorld: maxX - minX, heightWorld: maxY - minY };
   }
 
+  public getViewReference(
+    viewRefSpecifier: ViewReferenceSpecifier = {}
+  ): ViewReference {
+    const { focalPoint: cameraFocalPoint, viewPlaneNormal } = this.getCamera();
+    const target: ViewReference = {
+      FrameOfReferenceUID: this.getFrameOfReferenceUID(),
+      cameraFocalPoint,
+      viewPlaneNormal,
+      sliceIndex: viewRefSpecifier.sliceIndex ?? this.getCurrentImageIdIndex(),
+    };
+    return target;
+  }
+
+  public isReferenceViewable(
+    viewRef: ViewReference,
+    options?: ReferenceCompatibleOptions
+  ): boolean {
+    if (
+      viewRef.FrameOfReferenceUID &&
+      viewRef.FrameOfReferenceUID !== this.getFrameOfReferenceUID()
+    ) {
+      return false;
+    }
+
+    const { viewPlaneNormal } = viewRef;
+    const camera = this.getCamera();
+    if (
+      !isEqual(viewPlaneNormal, camera.viewPlaneNormal) &&
+      !isEqual(
+        vec3.negate(camera.viewPlaneNormal, camera.viewPlaneNormal),
+        viewPlaneNormal
+      )
+    ) {
+      // Could navigate as a volume to the reference
+      return options?.asVolume === true;
+    }
+    return true;
+  }
+
   protected _shouldUseNativeDataType() {
     const { useNorm16Texture, preferSizeOverAccuracy } =
       getConfiguration().rendering;

package/src/types/IViewport.ts

@@ -6,14 +6,23 @@ import { ActorEntry } from './IActor';
 import ViewportType from '../enums/ViewportType';
 import ViewportStatus from '../enums/ViewportStatus';
 import DisplayArea from './displayArea';
+import BoundsLPS from './BoundsLPS';
 
 /**
- * Specifies what image to get a reference for.
+ * 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 for a given set of
+ * points.
  */
-export type TargetSpecifier = {
+export type ViewReferenceSpecifier = {
   /** The slice index within the current viewport camera to get a reference for */
-  sliceIndex?: number;
-  /** True to get a frame of reference UID reference instead of a regular image one */
+  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[];
@@ -21,6 +30,81 @@ export type TargetSpecifier = {
   volumeId?: string;
 };
 
+/**
+ * These are the options arguments to determine whether a view reference
+ * is compatible with a viewport, that is, could be or is shown in a viewport.
+ * That specifies whether a view could be shown in a given viewport or not.
+ */
+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, while for a volume,
+   * could it be shown if the camera/orientation were changed.
+   * That is, is the specified view showing an image in the stack but with a
+   * different orientation than acquisition.
+   */
+  asVolume?: 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.  It
+ * basically says would this viewport show this view, or can direct a viewport
+ * to show a specific view.
+ */
+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
+   */
+  cameraFocalPoint?: Point3;
+  /**
+   * The normal for the current view
+   */
+  viewPlaneNormal?: Point3;
+  /**
+   * The slice index or range for this view
+   */
+  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;
+};
+
 /**
  * Viewport interface for cornerstone viewports
  */
@@ -124,7 +208,24 @@ interface IViewport {
   /** Gets the current slice in the current camera orientation */
   getCurrentImageIdIndex(): number;
   /** Gets a referenced image url of some sort - could be a real image id, or could be a URL with parameters */
-  getTargetId(forTarget?: TargetSpecifier): string;
+  getReferenceId(viewRefSpecifier?: ViewReferenceSpecifier): string;
+  /**
+   * Gets a view target, allowing comparison between view positions as well
+   * as restoring views later.
+   */
+  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;
+
   /** whether the viewport has custom rendering */
   customRenderViewportToCanvas: () => unknown;
   _getCorners(bounds: Array<number>): Array<number>[];

package/src/types/index.ts

@@ -16,7 +16,9 @@ import type CustomEventType from './CustomEventType';
 import type {
   IViewport,
   PublicViewportInput,
-  TargetSpecifier,
+  ViewReferenceSpecifier,
+  ReferenceCompatibleOptions,
+  ViewReference,
 } from './IViewport';
 import type {
   VolumeActor,
@@ -157,7 +159,9 @@ export type {
   IRegisterImageLoader,
   IStreamingVolumeProperties,
   IViewport,
-  TargetSpecifier,
+  ViewReference,
+  ReferenceCompatibleOptions,
+  ViewReferenceSpecifier as ViewReferenceSpecifier,
   StackViewportProperties,
   VolumeViewportProperties,
   ViewportProperties,