@cornerstonejs/core 1.5.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cornerstonejs/core",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "",
   "main": "dist/umd/index.js",
   "types": "dist/esm/index.d.ts",
@@ -44,5 +44,5 @@
     "type": "individual",
     "url": "https://ohif.org/donate"
   },
-  "gitHead": "cbfe5342099f46b69109d34e09a0a733ca7c897d"
+  "gitHead": "757fe06aab211f0bd506c40f262264e90290b702"
 }

package/src/RenderingEngine/StackViewport.ts

@@ -10,7 +10,6 @@ import vtkColorTransferFunction from '@kitware/vtk.js/Rendering/Core/ColorTransf
 import * as metaData from '../metaData';
 import Viewport from './Viewport';
 import eventTarget from '../eventTarget';
-import Events from '../enums/Events';
 import {
   triggerEvent,
   isEqual,
@@ -41,6 +40,7 @@ import {
   VolumeActor,
   Mat3,
   ColormapRegistration,
+  IImageCalibration,
 } from '../types';
 import { ViewportInput } from '../types/IViewport';
 import drawImageSync from './helpers/cpuFallback/drawImageSync';
@@ -48,8 +48,13 @@ import { getColormap } from './helpers/cpuFallback/colors/index';
 
 import { loadAndCacheImage } from '../loaders/imageLoader';
 import imageLoadPoolManager from '../requestPool/imageLoadPoolManager';
-import InterpolationType from '../enums/InterpolationType';
-import VOILUTFunctionType from '../enums/VOILUTFunctionType';
+import {
+  InterpolationType,
+  RequestType,
+  Events,
+  CalibrationTypes,
+  VOILUTFunctionType,
+} from '../enums';
 import canvasToPixel from './helpers/cpuFallback/rendering/canvasToPixel';
 import pixelToCanvas from './helpers/cpuFallback/rendering/pixelToCanvas';
 import getDefaultViewport from './helpers/cpuFallback/rendering/getDefaultViewport';
@@ -59,7 +64,6 @@ import resize from './helpers/cpuFallback/rendering/resize';
 import resetCamera from './helpers/cpuFallback/rendering/resetCamera';
 import { Transform } from './helpers/cpuFallback/rendering/transform';
 import { getConfiguration, getShouldUseCPURendering } from '../init';
-import RequestType from '../enums/RequestType';
 import {
   StackViewportNewStackEventDetail,
   StackViewportScrollEventDetail,
@@ -91,8 +95,10 @@ interface ImageDataMetaData {
 }
 // TODO This needs to be exposed as its published to consumers.
 type CalibrationEvent = {
-  rowScale: number;
-  columnScale: number;
+  rowScale?: number;
+  columnScale?: number;
+  scale: number;
+  calibration: IImageCalibration;
 };
 
 type SetVOIOptions = {
@@ -411,6 +417,7 @@ class StackViewport extends Viewport implements IStackViewport {
       metadata: { Modality: this.modality },
       scaling: this.scaling,
       hasPixelSpacing: this.hasPixelSpacing,
+      calibration: this.calibration,
       preScale: {
         ...this.csImage.preScale,
       },
@@ -452,6 +459,7 @@ class StackViewport extends Viewport implements IStackViewport {
       },
       scalarData: this.cpuImagePixelData,
       hasPixelSpacing: this.hasPixelSpacing,
+      calibration: this.calibration,
       preScale: {
         ...this.csImage.preScale,
       },
@@ -558,6 +566,7 @@ class StackViewport extends Viewport implements IStackViewport {
     const voiLUTFunctionEnum = this._getValidVOILUTFunction(voiLUTFunction);
     this.VOILUTFunction = voiLUTFunctionEnum;
 
+    this.calibration = null;
     let imagePlaneModule = this._getImagePlaneModule(imageId);
 
     if (!this.useCPURendering) {
@@ -591,89 +600,19 @@ class StackViewport extends Viewport implements IStackViewport {
    * @returns modified imagePlaneModule with the calibrated spacings
    */
   private calibrateIfNecessary(imageId, imagePlaneModule) {
-    const calibratedPixelSpacing = metaData.get(
-      'calibratedPixelSpacing',
-      imageId
-    );
-
-    if (!calibratedPixelSpacing) {
-      return imagePlaneModule;
-    }
-
-    const {
-      rowPixelSpacing: calibratedRowSpacing,
-      columnPixelSpacing: calibratedColumnSpacing,
-    } = calibratedPixelSpacing;
+    const calibration = metaData.get('calibratedPixelSpacing', imageId);
+    const isUpdated = this.calibration !== calibration;
+    const { scale } = calibration || {};
+    this.hasPixelSpacing = scale > 0 || imagePlaneModule.rowPixelSpacing > 0;
+    imagePlaneModule.calibration = calibration;
 
-    // Todo: This is necessary in general, but breaks an edge case when an image
-    // is calibrated to some other spacing, and it gets calibrated BACK to the
-    // original spacing.
-    if (
-      imagePlaneModule.rowPixelSpacing === calibratedRowSpacing &&
-      imagePlaneModule.columnPixelSpacing === calibratedColumnSpacing
-    ) {
-      return imagePlaneModule;
-    }
+    if (!isUpdated) return imagePlaneModule;
 
-    // Check if there is already an actor
-    const imageDataMetadata = this.getImageData();
-
-    // If no actor (first load) and calibration matches the dicom header
-    if (
-      !imageDataMetadata &&
-      imagePlaneModule.rowPixelSpacing === calibratedRowSpacing &&
-      imagePlaneModule.columnPixelSpacing === calibratedColumnSpacing
-    ) {
-      return imagePlaneModule;
-    }
-
-    // If no actor (first load) and calibration doesn't match headers
-    // -> needs calibration
-    if (
-      !imageDataMetadata &&
-      (imagePlaneModule.rowPixelSpacing !== calibratedRowSpacing ||
-        imagePlaneModule.columnPixelSpacing !== calibratedColumnSpacing)
-    ) {
-      this._publishCalibratedEvent = true;
-
-      this._calibrationEvent = <CalibrationEvent>{
-        rowScale: calibratedRowSpacing / imagePlaneModule.rowPixelSpacing,
-        columnScale:
-          calibratedColumnSpacing / imagePlaneModule.columnPixelSpacing,
-      };
-
-      // modify the calibration object to store the actual updated values applied
-      calibratedPixelSpacing.appliedSpacing = calibratedPixelSpacing;
-      // This updates the render copy
-      imagePlaneModule.rowPixelSpacing = calibratedRowSpacing;
-      imagePlaneModule.columnPixelSpacing = calibratedColumnSpacing;
-      return imagePlaneModule;
-    }
-
-    // If there is already an actor, check if calibration is needed for the current actor
-    const { imageData } = imageDataMetadata;
-    const [columnPixelSpacing, rowPixelSpacing] = imageData.getSpacing();
-
-    // modify the calibration object to store the actual updated values applied
-    calibratedPixelSpacing.appliedSpacing = calibratedPixelSpacing;
-    imagePlaneModule.rowPixelSpacing = calibratedRowSpacing;
-    imagePlaneModule.columnPixelSpacing = calibratedColumnSpacing;
-
-    // If current actor spacing matches the calibrated spacing
-    if (
-      rowPixelSpacing === calibratedRowSpacing &&
-      columnPixelSpacing === calibratedPixelSpacing
-    ) {
-      // No calibration is required
-      return imagePlaneModule;
-    }
-
-    // Calibration is required
+    this.calibration = calibration;
     this._publishCalibratedEvent = true;
-
     this._calibrationEvent = <CalibrationEvent>{
-      rowScale: calibratedRowSpacing / rowPixelSpacing,
-      columnScale: calibratedColumnSpacing / columnPixelSpacing,
+      scale,
+      calibration,
     };
 
     return imagePlaneModule;
@@ -2717,28 +2656,20 @@ class StackViewport extends Viewport implements IStackViewport {
       imageId
     );
 
+    this.calibration ||= imagePlaneModule.calibration;
+
     const newImagePlaneModule: ImagePlaneModule = {
       ...imagePlaneModule,
     };
 
-    if (calibratedPixelSpacing?.appliedSpacing) {
-      // Over-ride the image plane module spacing, as the measurement data
-      // has already been created with the calibrated spacing provided from
-      // down below inside calibrateIfNecessary
-      const { rowPixelSpacing, columnPixelSpacing } =
-        calibratedPixelSpacing.appliedSpacing;
-      newImagePlaneModule.rowPixelSpacing = rowPixelSpacing;
-      newImagePlaneModule.columnPixelSpacing = columnPixelSpacing;
-    }
-
     if (!newImagePlaneModule.columnPixelSpacing) {
       newImagePlaneModule.columnPixelSpacing = 1;
-      this.hasPixelSpacing = false;
+      this.hasPixelSpacing = this.calibration?.scale > 0;
     }
 
     if (!newImagePlaneModule.rowPixelSpacing) {
       newImagePlaneModule.rowPixelSpacing = 1;
-      this.hasPixelSpacing = false;
+      this.hasPixelSpacing = this.calibration?.scale > 0;
     }
 
     if (!newImagePlaneModule.columnCosines) {

package/src/RenderingEngine/Viewport.ts

@@ -27,6 +27,7 @@ import type {
 import type { ViewportInput, IViewport } from '../types/IViewport';
 import type { vtkSlabCamera } from './vtkClasses/vtkSlabCamera';
 import { getConfiguration } from '../init';
+import IImageCalibration from '../types/IImageCalibration';
 
 /**
  * An object representing a single viewport, which is a camera
@@ -74,6 +75,7 @@ class Viewport implements IViewport {
   /** A flag representing if viewport methods should fire events or not */
   readonly suppressEvents: boolean;
   protected hasPixelSpacing = true;
+  protected calibration: IImageCalibration;
   /** The camera that is initially defined on the reset for
    * the relative pan/zoom
    */

package/src/enums/CalibrationTypes.ts

@@ -0,0 +1,55 @@
+/**
+ * Defines the calibration types available.  These define how the units
+ * for measurements are specified.
+ */
+export enum CalibrationTypes {
+  /**
+   * Not applicable means the units are directly defind by the underlying
+   * hardware, such as CT and MR volumetric displays, so no special handling
+   * or notification is required.
+   */
+  NOT_APPLICABLE = '',
+  /**
+   * ERMF is estimated radiographic magnification factor.  This defines how
+   * much the image is magnified at the detector as opposed to the location in
+   * the body of interest.  This occurs because the radiation beam is expanding
+   * and effectively magnifies the image on the detector compared to where the
+   * point of interest in the body is.
+   * This suggests that measurements can be partially trusted, but the user
+   * still needs to be aware that different depths within the body have differing
+   * ERMF values, so precise measurements would still need to be manually calibrated.
+   */
+  ERMF = 'ERMF',
+  /**
+   * User calibration means that the user has provided a custom calibration
+   * specifying how large the image data is.  This type can occur on
+   * volumetric images, eg for scout images that might have invalid spacing
+   * tags.
+   */
+  USER = 'User',
+  /**
+   * A projection calibration means the raw detector size, without any
+   * ERMF applied, meaning that the size in the body cannot be trusted and
+   * that a calibration should be applied.
+   * This is different from Error in that there is simply no magnification
+   * factor applied as opposed to having multiple, inconsistent magnification
+   * factors.
+   */
+  PROJECTION = 'Proj',
+  /**
+   * A region calibration is used for other types of images, typically
+   * ultrasouunds where the distance in the image may mean something other than
+   * physical distance, such as mV or Hz or some other measurement values.
+   */
+  REGION = 'Region',
+  /**
+   * Error is used to define mismatches between various units, such as when
+   * there are two different ERMF values specified.  This is an indication to
+   * NOT trust the measurement values but to manually calibrate.
+   */
+  ERROR = 'Error',
+  /** Uncalibrated image */
+  UNCALIBRATED = 'Uncalibrated',
+}
+
+export default CalibrationTypes;

package/src/enums/Events.ts

@@ -75,6 +75,15 @@ enum Events {
    * and see what event detail is included in {@link EventTypes.ImageVolumeModifiedEventDetail | ImageVolumeModified Event Detail }
    */
   IMAGE_VOLUME_MODIFIED = 'CORNERSTONE_IMAGE_VOLUME_MODIFIED',
+  /**
+   * Triggers on the eventTarget when the image volume loading is completed and all
+   * frames are loaded and inserted into a volume.
+   *
+   * Make use of {@link EventTypes.ImageVolumeLoadingCompletedEvent | ImageVolumeLoadingCompleted Event Type } for typing your
+   * event listeners for IMAGE_VOLUME_LOADING_COMPLETED event, and see what event detail is included
+   * in {@link EventTypes.ImageVolumeLoadingCompletedEventDetail | ImageVolumeLoadingCompleted Event Detail }
+   */
+  IMAGE_VOLUME_LOADING_COMPLETED = 'CORNERSTONE_IMAGE_VOLUME_LOADING_COMPLETED',
   /**
    * Triggers on the eventTarget when the image has successfully loaded by imageLoaders
    *

package/src/enums/index.ts

@@ -9,11 +9,13 @@ import GeometryType from './GeometryType';
 import ContourType from './ContourType';
 import VOILUTFunctionType from './VOILUTFunctionType';
 import DynamicOperatorType from './DynamicOperatorType';
+import CalibrationTypes from './CalibrationTypes';
 import ViewportStatus from './ViewportStatus';
 
 export {
   Events,
   BlendModes,
+  CalibrationTypes,
   InterpolationType,
   RequestType,
   ViewportType,

package/src/types/CPUIImageData.ts

@@ -1,4 +1,5 @@
 import { Point3, Scaling, Mat3, PixelDataTypedArray } from '../types';
+import IImageCalibration from './IImageCalibration';
 
 type CPUImageData = {
   worldToIndex?: (point: Point3) => Point3;
@@ -24,6 +25,8 @@ type CPUIImageData = {
   scaling: Scaling;
   /** whether the image has pixel spacing and it is not undefined */
   hasPixelSpacing?: boolean;
+  calibration?: IImageCalibration;
+
   /** preScale object */
   preScale?: {
     /** boolean flag to indicate whether the image has been scaled */

package/src/types/EventTypes.ts

@@ -10,6 +10,7 @@ import type { VOIRange } from './voi';
 import type VOILUTFunctionType from '../enums/VOILUTFunctionType';
 import type ViewportStatus from '../enums/ViewportStatus';
 import type DisplayArea from './displayArea';
+import IImageCalibration from './IImageCalibration';
 
 /**
  * CAMERA_MODIFIED Event's data
@@ -110,6 +111,16 @@ type ImageVolumeModifiedEventDetail = {
   FrameOfReferenceUID: string;
 };
 
+/**
+ * IMAGE_VOLUME_LOADING_COMPLETED Event's data
+ */
+type ImageVolumeLoadingCompletedEventDetail = {
+  /** the loaded volume */
+  volumeId: string;
+  /** FrameOfReferenceUID where the volume belongs to */
+  FrameOfReferenceUID: string;
+};
+
 /**
  * IMAGE_LOADED Event's data
  */
@@ -228,8 +239,8 @@ type ImageSpacingCalibratedEventDetail = {
   viewportId: string;
   renderingEngineId: string;
   imageId: string;
-  rowScale: number;
-  columnScale: number;
+  /** calibration contains the scaling information as well as other calibration info */
+  calibration: IImageCalibration;
   imageData: vtkImageData;
   worldToIndex: mat4;
 };
@@ -307,6 +318,14 @@ type ImageRenderedEvent = CustomEventType<ElementEnabledEventDetail>;
  */
 type ImageVolumeModifiedEvent = CustomEventType<ImageVolumeModifiedEventDetail>;
 
+/**
+ * IMAGE_VOLUME_LOADING_COMPLETED Event type
+ * This event is fired when a volume is fully loaded, means all the frames
+ * are loaded and cached.
+ */
+type ImageVolumeLoadingCompletedEvent =
+  CustomEventType<ImageVolumeLoadingCompletedEventDetail>;
+
 /**
  * IMAGE_LOADED Event type
  */
@@ -400,6 +419,8 @@ export type {
   ImageRenderedEvent,
   ImageVolumeModifiedEvent,
   ImageVolumeModifiedEventDetail,
+  ImageVolumeLoadingCompletedEvent,
+  ImageVolumeLoadingCompletedEventDetail,
   ImageLoadedEvent,
   ImageLoadedEventDetail,
   ImageLoadedFailedEventDetail,

package/src/types/IImageCalibration.ts

@@ -0,0 +1,41 @@
+import CalibrationTypes from '../enums/CalibrationTypes';
+
+/**
+ * IImageCalibration is an object that stores information about the type
+ * of image calibration.
+ */
+export interface IImageCalibration {
+  /**
+   * The pixel spacing for the image, in mm between pixel centers
+   * These are not required, and are deprecated in favour of getting the original
+   * image spacing and then applying the transforms.  The values here should
+   * be identical to original spacing.
+   */
+  rowPixelSpacing?: number;
+  columnPixelSpacing?: number;
+  /** The scaling of measurement values relative to the base pixel spacing (1 if not specified) */
+  scale?: number;
+  /**
+   * The calibration aspect ratio for non-square calibrations.
+   * This is the aspect ratio similar to the scale above that applies when
+   * the viewport is displaying non-square image pixels as square screen pixels.
+   *
+   * Defaults to 1 if not specified, and is also 1 if the Viewport has squared
+   * up the image pixels so that they are displayed as a square.
+   * Not well handled currently as this needs to be incorporated into
+   * tools when doing calculations.
+   */
+  aspect?: number;
+  /** The type of the pixel spacing, distinguishing between various
+   * types projection (CR/DX/MG) spacing and volumetric spacing (the type is
+   * an empty string as it doesn't get a suffix, but this distinguishes it
+   * from other types)
+   */
+  type: CalibrationTypes;
+  /** A tooltip which can be used to explain the calibration information */
+  tooltip?: string;
+  /** The DICOM defined ultrasound regions.  Used for non-distance spacing units. */
+  sequenceOfUltrasoundRegions?: Record<string, unknown>[];
+}
+
+export default IImageCalibration;

package/src/types/IImageData.ts

@@ -1,5 +1,6 @@
 import type { vtkImageData } from '@kitware/vtk.js/Common/DataModel/ImageData';
 import { Point3, Scaling, Mat3 } from '../types';
+import IImageCalibration from './IImageCalibration';
 
 /**
  * IImageData of an image, which stores actual scalarData and metaData about the image.
@@ -24,6 +25,9 @@ interface IImageData {
   scaling?: Scaling;
   /** whether the image has pixel spacing and it is not undefined */
   hasPixelSpacing?: boolean;
+
+  calibration?: IImageCalibration;
+
   /** preScale object */
   preScale?: {
     /** boolean flag to indicate whether the image has been scaled */

package/src/types/index.ts

@@ -30,6 +30,7 @@ import type Plane from './Plane';
 import type IStreamingImageVolume from './IStreamingImageVolume';
 import type ViewportInputOptions from './ViewportInputOptions';
 import type IImageData from './IImageData';
+import type IImageCalibration from './IImageCalibration';
 import type CPUIImageData from './CPUIImageData';
 import type { CPUImageData } from './CPUIImageData';
 import type IImage from './IImage';
@@ -102,6 +103,7 @@ export type {
   IStreamingImageVolume,
   IImage,
   IImageData,
+  IImageCalibration,
   CPUIImageData,
   CPUImageData,
   EventTypes,

package/src/utilities/calibratedPixelSpacingMetadataProvider.ts

@@ -1,13 +1,7 @@
 import imageIdToURI from './imageIdToURI';
+import { IImageCalibration } from '../types';
 
-export type CalibratedPixelValue = {
-  rowPixelSpacing: number;
-  columnPixelSpacing: number;
-  // These values get updated by the viewport after the change to record the applied value
-  appliedSpacing?: CalibratedPixelValue;
-};
-
-const state: Record<string, CalibratedPixelValue> = {}; // Calibrated pixel spacing per imageId
+const state: Record<string, IImageCalibration> = {}; // Calibrated pixel spacing per imageId
 
 /**
  * Simple metadataProvider object to store metadata for calibrated spacings.
@@ -20,7 +14,7 @@ const metadataProvider = {
    * @param imageId - the imageId for the metadata to store
    * @param payload - the payload composed of new calibrated pixel spacings
    */
-  add: (imageId: string, payload: CalibratedPixelValue): void => {
+  add: (imageId: string, payload: IImageCalibration): void => {
     const imageURI = imageIdToURI(imageId);
     state[imageURI] = payload;
   },
@@ -31,7 +25,7 @@ const metadataProvider = {
    * @param imageId - the imageId to enquire about
    * @returns the calibrated pixel spacings for the imageId if it exists, otherwise undefined
    */
-  get: (type: string, imageId: string): CalibratedPixelValue => {
+  get: (type: string, imageId: string): IImageCalibration => {
     if (type === 'calibratedPixelSpacing') {
       const imageURI = imageIdToURI(imageId);
       return state[imageURI];

package/src/utilities/imageToWorldCoords.ts

@@ -23,12 +23,15 @@ export default function imageToWorldCoords(
 
   const {
     columnCosines,
-    columnPixelSpacing,
     rowCosines,
-    rowPixelSpacing,
     imagePositionPatient: origin,
   } = imagePlaneModule;
 
+  let { columnPixelSpacing, rowPixelSpacing } = imagePlaneModule;
+  // Use ||= to convert null and 0 as well as undefined to 1
+  columnPixelSpacing ||= 1;
+  rowPixelSpacing ||= 1;
+
   // calculate the image coordinates in the world space
   const imageCoordsInWorld = vec3.create();
 

package/src/utilities/worldToImageCoords.ts

@@ -27,14 +27,15 @@ function worldToImageCoords(
 
   const {
     columnCosines,
-    columnPixelSpacing,
     rowCosines,
-    rowPixelSpacing,
     imagePositionPatient: origin,
-    rows,
-    columns,
   } = imagePlaneModule;
 
+  let { columnPixelSpacing, rowPixelSpacing } = imagePlaneModule;
+  // Use ||= to convert null and 0 as well as undefined to 1
+  columnPixelSpacing ||= 1;
+  rowPixelSpacing ||= 1;
+
   // The origin is the image position patient, but since image coordinates start
   // from [0,0] for the top left hand of the first pixel, and the origin is at the
   // center of the first pixel, we need to account for this.