@cornerstonejs/core 1.55.0 → 1.56.0

package/src/types/IActor.ts

@@ -6,6 +6,18 @@ export type Actor = vtkActor;
 export type VolumeActor = vtkVolume;
 export type ImageActor = vtkImageSlice;
 
+export interface ICanvasActor {
+  render(viewport, context): void;
+
+  getMapper();
+
+  getProperty();
+
+  isA(actorType): boolean;
+
+  getClassName(): string;
+}
+
 /**
  * Cornerstone Actor Entry including actor uid, actual Actor, and
  * slabThickness for the actor. ActorEntry is the object that
@@ -15,7 +27,7 @@ export type ActorEntry = {
   /** actor UID */
   uid: string;
   /** actual actor object */
-  actor: Actor | VolumeActor | ImageActor;
+  actor: Actor | VolumeActor | ImageActor | ICanvasActor;
   /** the id of the reference volume from which this actor is derived or created*/
   referenceId?: string;
   /** slab thickness for the actor */

package/src/types/IImage.ts

@@ -2,8 +2,10 @@ import type CPUFallbackLUT from './CPUFallbackLUT';
 import type CPUFallbackColormap from './CPUFallbackColormap';
 import type CPUFallbackEnabledElement from './CPUFallbackEnabledElement';
 import type { PixelDataTypedArray } from './PixelDataTypedArray';
+import type VoxelManager from '../utilities/VoxelManager';
 import { ImageQualityStatus } from '../enums';
 import IImageCalibration from './IImageCalibration';
+import RGB from './RGB';
 
 /**
  * Cornerstone Image interface, it is used for both CPU and GPU rendering
@@ -122,6 +124,8 @@ interface IImage {
   calibration?: IImageCalibration;
   imageFrame?: any;
 
+  voxelManager?: VoxelManager<number> | VoxelManager<RGB>;
+
   bufferView?: {
     buffer: ArrayBuffer;
     offset: number;

package/src/types/IImageVolume.ts

@@ -1,10 +1,12 @@
 import type { vtkImageData } from '@kitware/vtk.js/Common/DataModel/ImageData';
+import type { VoxelManager } from '../utilities';
 import {
   Metadata,
   PixelDataTypedArray,
   Point3,
   IImageLoadObject,
   Mat3,
+  RGB,
 } from '../types';
 
 /**
@@ -69,6 +71,9 @@ interface IImageVolume {
   /** return the volume scalar data */
   getScalarData(): PixelDataTypedArray;
 
+  /** A voxel manager to manage the scalar data */
+  voxelManager?: VoxelManager<number> | VoxelManager<RGB>;
+
   convertToImageSlicesAndCache(): string[];
 
   /** return the index of a given imageId */

package/src/types/IVideoViewport.ts

@@ -65,6 +65,11 @@ export default interface IVideoViewport extends IViewport {
    */
   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.

package/src/types/index.ts

@@ -18,7 +18,13 @@ import type {
   PublicViewportInput,
   TargetSpecifier,
 } from './IViewport';
-import type { VolumeActor, Actor, ActorEntry, ImageActor } from './IActor';
+import type {
+  VolumeActor,
+  Actor,
+  ActorEntry,
+  ImageActor,
+  ICanvasActor,
+} from './IActor';
 import type {
   IImageLoadObject,
   IVolumeLoadObject,
@@ -160,6 +166,7 @@ export type {
   Actor,
   ActorEntry,
   ImageActor,
+  ICanvasActor,
   IImageLoadObject,
   IVolumeLoadObject,
   IVolumeInput,

package/src/utilities/RLEVoxelMap.ts

@@ -0,0 +1,331 @@
+import { PixelDataTypedArray } from '../types';
+
+/**
+ * The RLERun specifies a contigous run of values for a row,
+ * where all indices (i only) from `[start,end)` have the specified
+ * value.
+ */
+export type RLERun<T> = {
+  value: T;
+  start: number;
+  end: number;
+};
+
+/**
+ * RLE based implementation of a voxel map.
+ * This can be used as single or multi-plane, as the underlying indexes are
+ * mapped to rows and hte rows are indexed started at 0 and continuing
+ * incrementing for all rows in the multi-plane voxel.
+ */
+export default class RLEVoxelMap<T> {
+  /**
+   * The rows for the voxel map is a map from the j index location (or for
+   * volumes, `j + k*height`) to a list of RLE runs.  That is, each entry in
+   * the rows specifies the voxel data for a given row in the image.
+   * Then, the RLE runs themselves specify the pixel values for given rows as
+   * a pair of start/end indices, plus the value to apply.
+   */
+  protected rows = new Map<number, RLERun<T>[]>();
+  /** The height of the images stored in the voxel map (eg the height of each plane) */
+  protected height = 1;
+  /** The width of the image planes */
+  protected width = 1;
+  /**
+   * The number of image planes stored (the depth of the indices), with the k
+   * index going from 0...depth.
+   */
+  protected depth = 1;
+  /**
+   * A multiplier value to go from j values to overall index values.
+   */
+  protected jMultiple = 1;
+  /**
+   * A multiplier value to go from k values to overall index values.
+   */
+  protected kMultiple = 1;
+  /** Number of components in the value */
+  protected numComps = 1;
+
+  /**
+   * The default value returned for get.
+   * This allows treting the voxel map more like scalar data, returning the right
+   * default value for unset values.
+   * Set to 0 by default, but any maps where 0 not in T should update this value.
+   */
+  public defaultValue: T = 0 as unknown as T;
+
+  /**
+   * The constructor for creating pixel data.
+   */
+  public pixelDataConstructor = Uint8Array;
+
+  constructor(width: number, height: number, depth = 1) {
+    this.width = width;
+    this.height = height;
+    this.depth = depth;
+    this.jMultiple = width;
+    this.kMultiple = this.jMultiple * height;
+  }
+
+  /**
+   * Gets the value encoded in the map at the given index, which is
+   * an integer `[i,j,k]` voxel index, equal to `index=i+(j+k*height)*width`
+   * value (eg a standard ScalarData index for stack/volume single component
+   * indices.)
+   *
+   * Returns defaultValue if the RLE value is not found.
+   */
+  public get = (index: number): T => {
+    const i = index % this.jMultiple;
+    const j = (index - i) / this.jMultiple;
+    const rle = this.getRLE(i, j);
+    return rle?.value || this.defaultValue;
+  };
+
+  /**
+   * Gets a list of RLERun values which specify the data on the row j
+   * This allows applying or modifying the run directly.  See CanvasActor
+   * for an example in the RLE rendering.
+   */
+  protected getRLE(i: number, j: number, k = 0): RLERun<T> {
+    const row = this.rows.get(j + k * this.height);
+    if (!row) {
+      return;
+    }
+    const index = this.findIndex(row, i);
+    const rle = row[index];
+    return i >= rle?.start ? rle : undefined;
+  }
+
+  /**
+   * Finds the index in the row that i is contained in, OR that i would be
+   * before.   That is, the rle value for the returned index in that row
+   * has `i ε [start,end)` if a direct RLE is found, or `i ε [end_-1,start)` if
+   * in the prefix.  If no RLE is found with that index, then
+   * `i ε [end_final,length)`
+   */
+  protected findIndex(row: RLERun<T>[], i: number) {
+    for (let index = 0; index < row.length; index++) {
+      const { end: iEnd } = row[index];
+      if (i < iEnd) {
+        return index;
+      }
+    }
+    return row.length;
+  }
+
+  /**
+   * Gets the run for the given j,k indices.  This is used to allow fast access
+   * to runs for data for things like rendering entire rows of data.
+   */
+  public getRun = (j: number, k: number) => {
+    const runIndex = j + k * this.height;
+    return this.rows.get(runIndex);
+  };
+
+  /**
+   * Adds to the RLE at the given position.  This is unfortunately fairly
+   * complex since it is desirable to minimize the number of runs, but to still
+   * allow it to be efficient.
+   */
+  public set = (index: number, value: T) => {
+    if (value === undefined) {
+      throw new Error(`Can't set undefined at ${index % this.width}`);
+    }
+    const i = index % this.width;
+    const j = (index - i) / this.width;
+    const row = this.rows.get(j);
+    if (!row) {
+      this.rows.set(j, [{ start: i, end: i + 1, value }]);
+      return;
+    }
+    const rleIndex = this.findIndex(row, i);
+    const rle1 = row[rleIndex];
+    const rle0 = row[rleIndex - 1];
+
+    // Adding to the end of the row
+    if (!rle1) {
+      // We are at the end, check if the previous rle can be extended
+      if (!rle0 || rle0.value !== value || rle0.end !== i) {
+        row[rleIndex] = { start: i, end: i + 1, value };
+        // validateRow(row, i, rleIndex, value);
+        return;
+      }
+      // Just add it to the previous element.
+      rle0.end++;
+      return;
+    }
+
+    const { start, end, value: oldValue } = rle1;
+
+    // Handle the already in place case
+    if (value === oldValue && i >= start) {
+      // validateRow(row, i, rleIndex, value, start);
+      return;
+    }
+
+    const rleInsert = { start: i, end: i + 1, value };
+    const isAfter = i > start;
+    const insertIndex = isAfter ? rleIndex + 1 : rleIndex;
+    const rlePrev = isAfter ? rle1 : rle0;
+    let rleNext = isAfter ? row[rleIndex + 1] : rle1;
+
+    // Can merge with previous value, so no insert
+    if (rlePrev?.value === value && rlePrev?.end === i) {
+      rlePrev.end++;
+      if (rleNext?.value === value && rleNext.start === i + 1) {
+        rlePrev.end = rleNext.end;
+        row.splice(rleIndex, 1);
+        // validateRow(row, i, rleIndex, value);
+      } else if (rleNext?.start === i) {
+        rleNext.start++;
+        if (rleNext.start === rleNext.end) {
+          row.splice(rleIndex, 1);
+          rleNext = row[rleIndex];
+          // Check if we can merge twice
+          if (rleNext?.start === i + 1 && rleNext.value === value) {
+            rlePrev.end = rleNext.end;
+            row.splice(rleIndex, 1);
+          }
+        }
+        // validateRow(row, i, rleIndex, value);
+      }
+      return;
+    }
+
+    // Can merge with next, so no insert
+    if (rleNext?.value === value && rleNext.start === i + 1) {
+      rleNext.start--;
+      if (rlePrev?.end > i) {
+        rlePrev.end = i;
+        if (rlePrev.end === rlePrev.start) {
+          row.splice(rleIndex, 1);
+        }
+      }
+      // validateRow(row, i, rleIndex, value);
+      return;
+    }
+
+    // Can't merge, need to see if we can replace
+    if (rleNext?.start === i && rleNext.end === i + 1) {
+      rleNext.value = value;
+      const nextnext = row[rleIndex + 1];
+      if (nextnext?.start == i + 1 && nextnext.value === value) {
+        row.splice(rleIndex + 1, 1);
+        rleNext.end = nextnext.end;
+      }
+      // validateRow(row, i, rleIndex, value);
+      return;
+    }
+
+    // Need to fix the next start value
+    if (i === rleNext?.start) {
+      rleNext.start++;
+    }
+    if (isAfter && end > i + 1) {
+      // Insert two items, to split the existing into three
+      row.splice(insertIndex, 0, rleInsert, {
+        start: i + 1,
+        end: rlePrev.end,
+        value: rlePrev.value,
+      });
+    } else {
+      row.splice(insertIndex, 0, rleInsert);
+    }
+    if (rlePrev?.end > i) {
+      rlePrev.end = i;
+    }
+    // validateRow(row, i, rleIndex, value, insertIndex);
+  };
+
+  /**
+   * Clears all entries.
+   */
+  public clear() {
+    this.rows.clear();
+  }
+
+  /**
+   * Gets the set of key entries - that is j values.  This may include
+   * `j>=height`, where `j = key % height`, and `k = Math.floor(j / height)`
+   */
+  public keys(): number[] {
+    return [...this.rows.keys()];
+  }
+
+  /**
+   * Gets the pixel data into the provided pixel data array, or creates one
+   * according to the assigned type.
+   */
+  public getPixelData(
+    k = 0,
+    pixelData?: PixelDataTypedArray
+  ): PixelDataTypedArray {
+    if (!pixelData) {
+      pixelData = new this.pixelDataConstructor(
+        this.width * this.height * this.numComps
+      );
+    } else {
+      pixelData.fill(0);
+    }
+    const { width, height, numComps } = this;
+
+    for (let j = 0; j < height; j++) {
+      const row = this.getRun(j, k);
+      if (!row) {
+        continue;
+      }
+      if (numComps === 1) {
+        for (const rle of row) {
+          const rowOffset = j * width;
+          const { start, end, value } = rle;
+          for (let i = start; i < end; i++) {
+            pixelData[rowOffset + i] = value as unknown as number;
+          }
+        }
+      } else {
+        for (const rle of row) {
+          const rowOffset = j * width * numComps;
+          const { start, end, value } = rle;
+          for (let i = start; i < end; i += numComps) {
+            for (let comp = 0; comp < numComps; comp++) {
+              pixelData[rowOffset + i + comp] = value[comp];
+            }
+          }
+        }
+      }
+    }
+    return pixelData;
+  }
+}
+
+// This is some code to allow debugging RLE maps
+// To be deleted along with references once RLE is better tested.
+// Might move to testing code at that point
+// function validateRow(row, ...inputs) {
+//   if (!row) {
+//     return;
+//   }
+//   let lastRle;
+//   for (const rle of row) {
+//     const { start, end, value } = rle;
+//     if (start < 0 || end > 1920 || start >= end) {
+//       console.log('Wrong order', ...inputs);
+//       debugger;
+//     }
+//     if (!lastRle) {
+//       lastRle = rle;
+//       continue;
+//     }
+//     const { start: lastStart, end: lastEnd, value: lastValue } = lastRle;
+//     lastRle = rle;
+//     if (start < lastEnd) {
+//       console.log('inputs for wrong overlap', ...inputs);
+//       debugger;
+//     }
+//     if (start === lastEnd && value === lastValue) {
+//       console.log('inputs for two in a row same', ...inputs);
+//       debugger;
+//     }
+//   }
+// }

package/src/utilities/VoxelManager.ts

@@ -1,4 +1,19 @@
-import type { BoundsIJK, Point3, PixelDataTypedArray } from '../types';
+import type {
+  BoundsIJK,
+  Point3,
+  PixelDataTypedArray,
+  IImage,
+  RGB,
+} from '../types';
+import RLEVoxelMap from './RLEVoxelMap';
+import isEqual from './isEqual';
+
+/**
+ * Have a default size for cached RLE encoded images.  This is hard to guess
+ * up front because the RLE is usually used to store new/updated data, but this
+ * is a first guess.
+ */
+const DEFAULT_RLE_SIZE = 5 * 1024;
 
 /**
  * This is a simple, standard interface to values associated with a voxel.
@@ -13,10 +28,11 @@ export default class VoxelManager<T> {
 
   // Provide direct access to the underlying data, if any
   public scalarData: PixelDataTypedArray;
-  public map: Map<number, T>;
+  public map: Map<number, T> | RLEVoxelMap<T>;
   public sourceVoxelManager: VoxelManager<T>;
   public isInObject: (pointIPS, pointIJK) => boolean;
   public readonly dimensions: Point3;
+  public numComps = 1;
 
   points: Set<number>;
   width: number;
@@ -233,21 +249,89 @@ export default class VoxelManager<T> {
     bounds[2][1] = Math.max(point[2], bounds[2][1]);
   }
 
+  /**
+   * Gets the pixel data for the given array.
+   */
+  public getPixelData: (
+    sliceIndex?: number,
+    pixelData?: PixelDataTypedArray
+  ) => PixelDataTypedArray;
+
+  /**
+   * Creates a voxel manager backed by an array of scalar data having the
+   * given number of components.
+   * Note that the number of components can be larger than three, in case data
+   * is stored in additional pixels.  However, the return type is still RGB.
+   */
+  public static createRGBVolumeVoxelManager(
+    dimensions: Point3,
+    scalarData,
+    numComponents
+  ): VoxelManager<RGB> {
+    const voxels = new VoxelManager<RGB>(
+      dimensions,
+      (index) => {
+        index *= numComponents;
+        return [scalarData[index++], scalarData[index++], scalarData[index++]];
+      },
+      (index, v) => {
+        index *= 3;
+        const isChanged = !isEqual(scalarData[index], v);
+        scalarData[index++] = v[0];
+        scalarData[index++] = v[1];
+        scalarData[index++] = v[2];
+        return isChanged;
+      }
+    );
+    voxels.numComps = numComponents;
+    voxels.scalarData = scalarData;
+    return voxels;
+  }
+
   /**
    *  Creates a volume value accessor, based on a volume scalar data instance.
    * This also works for image value accessors for single plane (k=0) accessors.
    */
   public static createVolumeVoxelManager(
     dimensions: Point3,
-    scalarData
-  ): VoxelManager<number> {
+    scalarData,
+    numComponents = 0
+  ): VoxelManager<number> | VoxelManager<RGB> {
     if (dimensions.length !== 3) {
       throw new Error(
         'Dimensions must be provided as [number, number, number] for [width, height, depth]'
       );
     }
+    if (!numComponents) {
+      numComponents =
+        scalarData.length / dimensions[0] / dimensions[1] / dimensions[2];
+      // We only support 1,3,4 component data, and sometimes the scalar data
+      // doesn't match for some reason, so throw an exception
+      if (numComponents > 4 || numComponents < 1 || numComponents === 2) {
+        throw new Error(
+          `Number of components ${numComponents} must be 1, 3 or 4`
+        );
+      }
+    }
+    if (numComponents > 1) {
+      return VoxelManager.createRGBVolumeVoxelManager(
+        dimensions,
+        scalarData,
+        numComponents
+      );
+    }
+    return VoxelManager.createNumberVolumeVoxelManager(dimensions, scalarData);
+  }
 
-    const voxels = new VoxelManager(
+  /**
+   * Creates a volume voxel manager that works on single numeric values stored
+   * in an array like structure of numbers.
+   */
+  public static createNumberVolumeVoxelManager(
+    dimensions: Point3,
+    scalarData
+  ): VoxelManager<number> {
+    const voxels = new VoxelManager<number>(
       dimensions,
       (index) => scalarData[index],
       (index, v) => {
@@ -308,6 +392,92 @@ export default class VoxelManager<T> {
     voxelManager.sourceVoxelManager = sourceVoxelManager;
     return voxelManager;
   }
+
+  /**
+   * Creates a lazy voxel manager that will create an image plane as required
+   * for each slice of a volume as it gets changed.  This can be used to
+   * store image data that gets created as required.
+   */
+  public static createLazyVoxelManager<T>(
+    dimensions: Point3,
+    planeFactory: (width: number, height: number) => T
+  ): VoxelManager<T> {
+    const map = new Map<number, T>();
+    const [width, height, depth] = dimensions;
+    const planeSize = width * height;
+
+    const voxelManager = new VoxelManager(
+      dimensions,
+      (index) => map.get(Math.floor(index / planeSize))?.[index % planeSize],
+      (index, v) => {
+        const k = Math.floor(index / planeSize);
+        let layer = map.get(k);
+        if (!layer) {
+          layer = planeFactory(width, height);
+          map.set(k, layer);
+        }
+        layer[index % planeSize] = v;
+      }
+    );
+    voxelManager.map = map;
+    return voxelManager;
+  }
+
+  /**
+   * Creates a RLE based voxel manager.  This is effective for storing
+   * segmentation maps or already RLE encoded data such as ultrasounds.
+   */
+  public static createRLEVoxelManager<T>(dimensions: Point3): VoxelManager<T> {
+    const [width, height, depth] = dimensions;
+    const map = new RLEVoxelMap<T>(width, height, depth);
+
+    const voxelManager = new VoxelManager<T>(
+      dimensions,
+      (index) => map.get(index),
+      (index, v) => map.set(index, v)
+    );
+    voxelManager.map = map;
+    voxelManager.getPixelData = map.getPixelData.bind(map);
+    return voxelManager;
+  }
+
+  /**
+   * This method adds a voxelManager instance to the image object
+   * where the object added is of type:
+   * 1. RLE map if the scalar data is missing or too small (dummy data)
+   * 2. Volume VoxelManager scalar data representations
+   */
+  public static addInstanceToImage(image: IImage) {
+    const { width, height } = image;
+    const scalarData = image.getPixelData();
+    // This test works for single images, or single representations of images
+    // from a volume representation, for grayscale, indexed and RGB or RGBA images.
+    if (scalarData?.length >= width * height) {
+      // This case means there is enough scalar data for at least one image,
+      // with 1 or more components, and creates a volume voxel manager
+      // that can lookup the data
+      image.voxelManager = VoxelManager.createVolumeVoxelManager(
+        [width, height, 1],
+        scalarData
+      );
+      return;
+    }
+    // This case occurs when the image data is a dummy image data set
+    // created just to prevent exceptions in the caching logic.  Then, the
+    // RLE voxel manager can be created to store the data instead.
+    image.voxelManager = VoxelManager.createRLEVoxelManager<number>([
+      width,
+      height,
+      1,
+    ]);
+    // The RLE voxel manager knows how to get scalar data pixel data representations.
+    // That allows using the RLE representation as a normal pixel data representation
+    // for VIEWING purposes.
+    image.getPixelData = image.voxelManager.getPixelData;
+    // Assign a different size to the cached data because this is actually
+    // storing an RLE representation, which doesn't have an up front size.
+    image.sizeInBytes = DEFAULT_RLE_SIZE;
+  }
 }
 
 export type { VoxelManager };

package/src/utilities/updateVTKImageDataWithCornerstoneImage.ts

@@ -6,6 +6,10 @@ function updateVTKImageDataWithCornerstoneImage(
   image: IImage
 ) {
   const pixelData = image.getPixelData();
+  if (!sourceImageData.getPointData) {
+    // This happens for a CanvasActor, that doesn't have the getPointData
+    return;
+  }
   const scalarData = sourceImageData
     .getPointData()
     .getScalars()

package/dist/cjs/enums/VideoViewport.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"VideoViewport.js","sourceRoot":"","sources":["../../../src/enums/VideoViewport.ts"],"names":[],"mappings":";;;AAGA,IAAK,SAGJ;AAHD,WAAK,SAAS;IACZ,wBAAW,CAAA;IACX,yBAAY,CAAA;AACd,CAAC,EAHI,SAAS,KAAT,SAAS,QAGb;AAEQ,8BAAS"}

package/dist/esm/enums/VideoViewport.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"VideoViewport.js","sourceRoot":"","sources":["../../../src/enums/VideoViewport.ts"],"names":[],"mappings":"AAGA,IAAK,SAGJ;AAHD,WAAK,SAAS;IACZ,wBAAW,CAAA;IACX,yBAAY,CAAA;AACd,CAAC,EAHI,SAAS,KAAT,SAAS,QAGb;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/types/enums/VideoViewport.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"VideoViewport.d.ts","sourceRoot":"","sources":["../../../src/enums/VideoViewport.ts"],"names":[],"mappings":"AAGA,aAAK,SAAS;IACZ,KAAK,MAAM;IACX,MAAM,MAAM;CACb;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}