@cornerstonejs/tools 0.56.2 → 0.56.4

package/src/utilities/touch/index.ts

@@ -0,0 +1,246 @@
+import { IDistance, IPoints, ITouchPoints } from '../../types';
+import { Types } from '@cornerstonejs/core';
+
+/**
+ * Returns the difference between multiple `IPoints` instances.
+ * @param currentPoints - The current points.
+ * @param lastPoints - The last points, to be subtracted from the `currentPoints`.
+ *
+ * @returns The difference in IPoints format
+ */
+function getDeltaPoints(
+  currentPoints: IPoints[],
+  lastPoints: IPoints[]
+): IPoints {
+  const curr = getMeanPoints(currentPoints);
+  const last = getMeanPoints(lastPoints);
+  return {
+    page: _subtractPoints2D(curr.page, last.page),
+    client: _subtractPoints2D(curr.client, last.client),
+    canvas: _subtractPoints2D(curr.canvas, last.canvas),
+    world: _subtractPoints3D(curr.world, last.world),
+  };
+}
+
+/**
+ * Returns the distance between multiple `IPoints` instances.
+ * @param currentPoints - The current points.
+ * @param lastPoints - The last points, to be subtracted from the `currentPoints`.
+ *
+ * @returns The distance difference in IDistance format
+ */
+function getDeltaDistance(
+  currentPoints: IPoints[],
+  lastPoints: IPoints[]
+): IDistance {
+  const curr = getMeanPoints(currentPoints);
+  const last = getMeanPoints(lastPoints);
+  return {
+    page: _getDistance2D(curr.page, last.page),
+    client: _getDistance2D(curr.client, last.client),
+    canvas: _getDistance2D(curr.canvas, last.canvas),
+    world: _getDistance3D(curr.world, last.world),
+  };
+}
+
+function getDeltaRotation(
+  currentPoints: ITouchPoints[],
+  lastPoints: ITouchPoints[]
+) {
+  // TODO
+}
+
+/**
+ * Returns the distance difference between multiple `IPoints` instances.
+ * @param currentPoints - The current points.
+ * @param lastPoints -- The last points.
+ *
+ * @returns The difference in IPoints format
+ */
+function getDeltaDistanceBetweenIPoints(
+  currentPoints: IPoints[],
+  lastPoints: IPoints[]
+): IDistance {
+  const currentDistance = _getMeanDistanceBetweenAllIPoints(currentPoints);
+  const lastDistance = _getMeanDistanceBetweenAllIPoints(lastPoints);
+  const deltaDistance = {
+    page: currentDistance.page - lastDistance.page,
+    client: currentDistance.client - lastDistance.client,
+    canvas: currentDistance.canvas - lastDistance.canvas,
+    world: currentDistance.world - lastDistance.world,
+  };
+  return deltaDistance;
+}
+
+/**
+ * Copies a set of points.
+ * @param points - The `IPoints` instance to copy.
+ *
+ * @returns A copy of the points.
+ */
+function copyPointsList(points: ITouchPoints[]): ITouchPoints[] {
+  return JSON.parse(JSON.stringify(points));
+}
+
+function copyPoints(points: ITouchPoints): ITouchPoints {
+  return JSON.parse(JSON.stringify(points));
+}
+
+function getMeanPoints(points: IPoints[]): IPoints {
+  return points.reduce(
+    (prev, curr) => {
+      return {
+        page: [
+          prev.page[0] + curr.page[0] / points.length,
+          prev.page[1] + curr.page[1] / points.length,
+        ],
+        client: [
+          prev.client[0] + curr.client[0] / points.length,
+          prev.client[1] + curr.client[1] / points.length,
+        ],
+        canvas: [
+          prev.canvas[0] + curr.canvas[0] / points.length,
+          prev.canvas[1] + curr.canvas[1] / points.length,
+        ],
+        world: [
+          prev.world[0] + curr.world[0] / points.length,
+          prev.world[1] + curr.world[1] / points.length,
+          prev.world[2] + curr.world[2] / points.length,
+        ],
+      };
+    },
+    {
+      page: [0, 0],
+      client: [0, 0],
+      canvas: [0, 0],
+      world: [0, 0, 0],
+    }
+  );
+}
+
+function getMeanTouchPoints(points: ITouchPoints[]): ITouchPoints {
+  return points.reduce(
+    (prev, curr) => {
+      return {
+        page: [
+          prev.page[0] + curr.page[0] / points.length,
+          prev.page[1] + curr.page[1] / points.length,
+        ],
+        client: [
+          prev.client[0] + curr.client[0] / points.length,
+          prev.client[1] + curr.client[1] / points.length,
+        ],
+        canvas: [
+          prev.canvas[0] + curr.canvas[0] / points.length,
+          prev.canvas[1] + curr.canvas[1] / points.length,
+        ],
+        world: [
+          prev.world[0] + curr.world[0] / points.length,
+          prev.world[1] + curr.world[1] / points.length,
+          prev.world[2] + curr.world[2] / points.length,
+        ],
+        touch: {
+          identifier: null,
+          radiusX: prev.touch.radiusX + curr.touch.radiusX / points.length,
+          radiusY: prev.touch.radiusY + curr.touch.radiusY / points.length,
+          force: prev.touch.force + curr.touch.force / points.length,
+          rotationAngle:
+            prev.touch.rotationAngle + curr.touch.rotationAngle / points.length,
+        },
+      };
+    },
+    {
+      page: [0, 0],
+      client: [0, 0],
+      canvas: [0, 0],
+      world: [0, 0, 0],
+      touch: {
+        identifier: null,
+        radiusX: 0,
+        radiusY: 0,
+        force: 0,
+        rotationAngle: 0,
+      },
+    }
+  );
+}
+/**
+ * _subtractPoints - Subtracts `point1` from `point0`.
+ * @param point0 - The first point.
+ * @param point1 - The second point to subtract from the first.
+ *
+ * @returns The difference.
+ */
+function _subtractPoints2D(
+  point0: Types.Point2,
+  point1: Types.Point2
+): Types.Point2 {
+  return [point0[0] - point1[0], point0[1] - point1[1]];
+}
+
+function _subtractPoints3D(
+  point0: Types.Point3,
+  point1: Types.Point3
+): Types.Point3 {
+  return [point0[0] - point1[0], point0[1] - point1[1], point0[2] - point1[2]];
+}
+
+function _getMeanDistanceBetweenAllIPoints(points: IPoints[]): IDistance {
+  // get mean distance between all unordered pairs of points
+  const pairedDistance: IDistance[] = [];
+  for (let i = 0; i < points.length; i++) {
+    for (let j = 0; j < points.length; j++) {
+      if (i < j) {
+        pairedDistance.push({
+          page: _getDistance2D(points[i].page, points[j].page),
+          client: _getDistance2D(points[i].client, points[j].client),
+          canvas: _getDistance2D(points[i].canvas, points[j].canvas),
+          world: _getDistance3D(points[i].world, points[j].world),
+        });
+      }
+    }
+  }
+
+  // take the average distance
+  return pairedDistance.reduce(
+    (prev, curr) => {
+      return {
+        page: prev.page + curr.page / pairedDistance.length,
+        client: prev.client + curr.client / pairedDistance.length,
+        canvas: prev.canvas + curr.canvas / pairedDistance.length,
+        world: prev.world + curr.world / pairedDistance.length,
+      };
+    },
+    {
+      page: 0,
+      client: 0,
+      canvas: 0,
+      world: 0,
+    }
+  );
+}
+
+function _getDistance2D(point0: Types.Point2, point1: Types.Point2): number {
+  return Math.sqrt(
+    Math.pow(point0[0] - point1[0], 2) + Math.pow(point0[1] - point1[1], 2)
+  );
+}
+
+function _getDistance3D(point0: Types.Point3, point1: Types.Point3): number {
+  return Math.sqrt(
+    Math.pow(point0[0] - point1[0], 2) +
+      Math.pow(point0[1] - point1[1], 2) +
+      Math.pow(point0[2] - point1[2], 2)
+  );
+}
+
+export {
+  getMeanPoints,
+  getMeanTouchPoints,
+  copyPoints,
+  copyPointsList,
+  getDeltaDistanceBetweenIPoints,
+  getDeltaPoints,
+  getDeltaDistance,
+  getDeltaRotation,
+};

package/src/utilities/triggerAnnotationRender.ts

@@ -0,0 +1,237 @@
+import {
+  getEnabledElement,
+  triggerEvent,
+  getRenderingEngine,
+} from '@cornerstonejs/core';
+import { Events, ToolModes } from '../enums';
+import { draw as drawSvg } from '../drawingSvg';
+import getToolsWithModesForElement from './getToolsWithModesForElement';
+import { AnnotationRenderedEventDetail } from '../types/EventTypes';
+const { Active, Passive, Enabled } = ToolModes;
+
+/**
+ * AnnotationRenderingEngine is a class that is responsible for rendering
+ * annotations defined in the renderAnnotation method of annotation tools on the page.
+ * It mimics the RenderingEngine in the Cornerstone Core. Here it uses requestAnimationFrame
+ * is used to render annotations by calling renderAnnotations() on each enabled tool. Note: This
+ * is a Singleton class and should not be instantiated directly. To trigger
+ * an annotation render for an HTML element containing a viewport you can use
+ *
+ * ```
+ * triggerAnnotationRender(element)
+ * ```
+ */
+class AnnotationRenderingEngine {
+  public hasBeenDestroyed: boolean;
+  private _needsRender: Set<HTMLDivElement> = new Set();
+  private _animationFrameSet = false;
+  private _animationFrameHandle: number | null = null;
+  private _viewportElements: Map<string, HTMLDivElement>;
+
+  constructor() {
+    this._viewportElements = new Map();
+  }
+
+  /**
+   * Add the viewport's HTMLDivElement to the viewports for rendering. This method
+   * just informs the annotationRenderingEngine about the viewport and
+   * does not initiate a render.
+   * @param viewportId - Viewport Unique identifier
+   * @param element - HTMLDivElement
+   */
+  public addViewportElement(viewportId: string, element: HTMLDivElement) {
+    this._viewportElements.set(viewportId, element);
+  }
+
+  /**
+   * Remove the viewport's HTMLDivElement from subsequent annotation renders
+   * @param viewportId - Viewport Unique identifier
+   */
+  public removeViewportElement(viewportId: string, element: HTMLDivElement) {
+    this._viewportElements.delete(viewportId);
+
+    // delete element from needsRender if element exist
+    this._needsRender.delete(element);
+
+    // I don' think there is any disadvantage to canceling the animation frame
+    // and resetting the flags on viewport's element removal, since the removeVIewportElement
+    // might be as a result of reEnabling the element (in re-enable we disable first), hence the need to render the
+    // new one while removing the old one
+    this._reset();
+  }
+
+  /**
+   * It tells the AnnotationRenderingEngine to render the viewport element the next
+   * time it renders.
+   *
+   * @param element - The element to render.
+   */
+  public renderViewport(element: HTMLDivElement): void {
+    this._setViewportsToBeRenderedNextFrame([element]);
+  }
+
+  /**
+   * _throwIfDestroyed Throws an error if trying to interact with the `RenderingEngine`
+   * instance after its `destroy` method has been called.
+   */
+  private _throwIfDestroyed() {
+    if (this.hasBeenDestroyed) {
+      throw new Error(
+        'this.destroy() has been manually called to free up memory, can not longer use this instance. Instead make a new one.'
+      );
+    }
+  }
+
+  private _renderFlaggedViewports = () => {
+    this._throwIfDestroyed();
+
+    const elements = Array.from(this._viewportElements.values());
+
+    for (let i = 0; i < elements.length; i++) {
+      const element = elements[i];
+      if (this._needsRender.has(element)) {
+        this._triggerRender(element);
+
+        // This viewport has been rendered, we can remove it from the set
+        this._needsRender.delete(element);
+
+        // If there is nothing left that is flagged for rendering, stop here
+        // and allow RAF to be called again
+        if (this._needsRender.size === 0) {
+          this._animationFrameSet = false;
+          this._animationFrameHandle = null;
+          return;
+        }
+      }
+    }
+  };
+
+  private _setAllViewportsToBeRenderedNextFrame() {
+    const elements = [...this._viewportElements.values()];
+
+    elements.forEach((element) => {
+      this._needsRender.add(element);
+    });
+
+    this._renderFlaggedViewports();
+  }
+
+  private _setViewportsToBeRenderedNextFrame(elements: HTMLDivElement[]) {
+    const elementsEnabled = [...this._viewportElements.values()];
+
+    // Add the viewports to the set of flagged viewports
+    elements.forEach((element) => {
+      // only enabledElement need to render
+      if (elementsEnabled.indexOf(element) !== -1) {
+        this._needsRender.add(element);
+      }
+    });
+
+    // Render any flagged viewports
+    this._render();
+  }
+
+  /**
+   * _render Sets up animation frame if necessary
+   */
+  private _render() {
+    // If we have viewports that need rendering and we have not already
+    // set the RAF callback to run on the next frame.
+    if (this._needsRender.size > 0 && this._animationFrameSet === false) {
+      this._animationFrameHandle = window.requestAnimationFrame(
+        this._renderFlaggedViewports
+      );
+
+      // Set the flag that we have already set up the next RAF call.
+      this._animationFrameSet = true;
+    }
+  }
+
+  _triggerRender(element) {
+    const enabledElement = getEnabledElement(element);
+
+    if (!enabledElement) {
+      console.warn('Element has been disabled');
+      return;
+    }
+
+    const renderingEngine = getRenderingEngine(
+      enabledElement.renderingEngineId
+    );
+    if (!renderingEngine) {
+      console.warn('rendering Engine has been destroyed');
+      return;
+    }
+
+    const enabledTools = getToolsWithModesForElement(element, [
+      Active,
+      Passive,
+      Enabled,
+    ]);
+
+    const { renderingEngineId, viewportId } = enabledElement;
+    const eventDetail: AnnotationRenderedEventDetail = {
+      element,
+      renderingEngineId,
+      viewportId,
+    };
+
+    // const enabledToolsWithAnnotations = enabledTools.filter((tool) => {
+    //   const annotations = getAnnotations(tool.getToolName(), {FrameOfReferenceUID});
+    //   return annotations && annotations.length;
+    // });
+
+    drawSvg(element, (svgDrawingHelper) => {
+      let anyRendered = false;
+      const handleDrawSvg = (tool) => {
+        if (tool.renderAnnotation) {
+          const rendered = tool.renderAnnotation(
+            enabledElement,
+            svgDrawingHelper
+          );
+          anyRendered = anyRendered || rendered;
+        }
+      };
+
+      /**
+       * We should be able to filter tools that don't have annotations, but
+       * currently some of tools have renderAnnotation method BUT
+       * don't keep annotation in the state, so if we do so, the tool will not be
+       * rendered.
+       */
+      enabledTools.forEach(handleDrawSvg);
+
+      if (anyRendered) {
+        triggerEvent(element, Events.ANNOTATION_RENDERED, { ...eventDetail });
+      }
+    });
+  }
+
+  /**
+   * _reset Resets the `RenderingEngine`
+   */
+  private _reset() {
+    window.cancelAnimationFrame(this._animationFrameHandle);
+
+    this._needsRender.clear();
+    this._animationFrameSet = false;
+    this._animationFrameHandle = null;
+
+    this._setAllViewportsToBeRenderedNextFrame();
+  }
+}
+
+const annotationRenderingEngine = new AnnotationRenderingEngine();
+
+/**
+ * It triggers the rendering of the annotations for the given HTML element using
+ * the `AnnotationRenderingEngine`
+ * @param element - The element to render the annotation on.
+ */
+function triggerAnnotationRender(element: HTMLDivElement): void {
+  annotationRenderingEngine.renderViewport(element);
+}
+
+export { annotationRenderingEngine, triggerAnnotationRender };
+
+export default triggerAnnotationRender;

package/src/utilities/triggerAnnotationRenderForViewportIds.ts

@@ -0,0 +1,18 @@
+import type { Types } from '@cornerstonejs/core';
+import triggerAnnotationRender from './triggerAnnotationRender';
+
+export function triggerAnnotationRenderForViewportIds(
+  renderingEngine: Types.IRenderingEngine,
+  viewportIdsToRender: string[]
+): void {
+  if (!viewportIdsToRender.length) {
+    return;
+  }
+
+  viewportIdsToRender.forEach((viewportId) => {
+    const { element } = renderingEngine.getViewport(viewportId);
+    triggerAnnotationRender(element);
+  });
+}
+
+export default triggerAnnotationRenderForViewportIds;

package/src/utilities/viewport/index.ts

@@ -0,0 +1,5 @@
+import { isViewportPreScaled } from './isViewportPreScaled';
+import jumpToSlice from './jumpToSlice';
+import jumpToWorld from './jumpToWorld';
+
+export { isViewportPreScaled, jumpToSlice, jumpToWorld };

package/src/utilities/viewport/isViewportPreScaled.ts

@@ -0,0 +1,24 @@
+import {
+  cache,
+  StackViewport,
+  Types,
+  BaseVolumeViewport,
+} from '@cornerstonejs/core';
+
+function isViewportPreScaled(
+  viewport: Types.IStackViewport | Types.IVolumeViewport,
+  targetId: string
+): boolean {
+  if (viewport instanceof BaseVolumeViewport) {
+    const volumeId = targetId.split('volumeId:')[1];
+    const volume = cache.getVolume(volumeId);
+    return volume.scaling && Object.keys(volume.scaling).length > 0;
+  } else if (viewport instanceof StackViewport) {
+    const { preScale } = viewport.getImageData();
+    return preScale.scaled;
+  } else {
+    throw new Error('Viewport is not a valid type');
+  }
+}
+
+export { isViewportPreScaled };

package/src/utilities/viewport/jumpToSlice.ts

@@ -0,0 +1,73 @@
+import {
+  getEnabledElement,
+  StackViewport,
+  VolumeViewport,
+  utilities as csUtils,
+  Types,
+} from '@cornerstonejs/core';
+import JumpToSliceOptions from '../../types/JumpToSliceOptions';
+import clip from '../clip';
+import scroll from '../scroll';
+
+/**
+ * It uses the imageIndex in the Options to scroll to the slice that is intended.
+ * It works for both Stack and Volume viewports. In VolumeViewports, the imageIndex
+ * should be given with respect to the index in the 3D image in the view direction
+ * (i.e. the index of the slice in Axial, Sagittal, Coronal, or Oblique).
+ *
+ * @param element - the HTML Div element scrolling inside
+ * @param options - the options used for jumping to a slice
+ * @returns Promise that resolves to ImageIdIndex
+ */
+async function jumpToSlice(
+  element: HTMLDivElement,
+  options = {} as JumpToSliceOptions
+): Promise<void> {
+  const { imageIndex, debounceLoading, volumeId } = options;
+  const enabledElement = getEnabledElement(element);
+
+  if (!enabledElement) {
+    throw new Error('Element has been disabled');
+  }
+
+  const { viewport } = enabledElement;
+
+  const { imageIndex: currentImageIndex, numberOfSlices } = _getImageSliceData(
+    viewport,
+    debounceLoading
+  );
+
+  const imageIndexToJump = _getImageIndexToJump(numberOfSlices, imageIndex);
+  const delta = imageIndexToJump - currentImageIndex;
+
+  scroll(viewport, { delta, debounceLoading, volumeId });
+}
+
+function _getImageSliceData(
+  viewport: Types.IStackViewport | Types.IVolumeViewport,
+  debounceLoading?: boolean
+): Types.ImageSliceData {
+  if (viewport instanceof StackViewport) {
+    return {
+      numberOfSlices: viewport.getImageIds().length,
+      imageIndex: debounceLoading
+        ? viewport.getTargetImageIdIndex()
+        : viewport.getCurrentImageIdIndex(),
+    };
+  } else if (viewport instanceof VolumeViewport) {
+    return csUtils.getImageSliceDataForVolumeViewport(viewport);
+  } else {
+    throw new Error('Unsupported viewport type');
+  }
+}
+
+function _getImageIndexToJump(
+  numberOfSlices: number,
+  imageIndex: number
+): number {
+  const lastSliceIndex = numberOfSlices - 1;
+
+  return clip(imageIndex, 0, lastSliceIndex);
+}
+
+export default jumpToSlice;

package/src/utilities/viewport/jumpToWorld.ts

@@ -0,0 +1,58 @@
+import { VolumeViewport } from '@cornerstonejs/core';
+import type { Types } from '@cornerstonejs/core';
+
+import { vec3 } from 'gl-matrix';
+
+// Todo: merge this utility functionality with Crosshair _jump
+/**
+ * Uses the viewport's current camera to jump to a specific world coordinate
+ * @param enabledElement - enabled element
+ * @param jumpWorld - location in the world to jump to
+ * @returns True if successful
+ */
+export default function jumpToWorld(
+  viewport: Types.IVolumeViewport,
+  jumpWorld: Types.Point3
+): true | undefined {
+  // if not instance of volumeViewport, return
+  if (!(viewport instanceof VolumeViewport)) {
+    return;
+  }
+
+  const { focalPoint } = viewport.getCamera();
+
+  const delta: Types.Point3 = [0, 0, 0];
+  vec3.sub(delta, jumpWorld, focalPoint);
+
+  _applyShift(viewport, delta);
+
+  return true;
+}
+
+function _applyShift(viewport, delta) {
+  const camera = viewport.getCamera();
+  const normal = camera.viewPlaneNormal;
+
+  const dotProd = vec3.dot(delta, normal);
+  const projectedDelta = vec3.fromValues(normal[0], normal[1], normal[2]);
+
+  vec3.scale(projectedDelta, projectedDelta, dotProd);
+
+  if (
+    Math.abs(projectedDelta[0]) > 1e-3 ||
+    Math.abs(projectedDelta[1]) > 1e-3 ||
+    Math.abs(projectedDelta[2]) > 1e-3
+  ) {
+    const newFocalPoint: Types.Point3 = [0, 0, 0];
+    const newPosition: Types.Point3 = [0, 0, 0];
+
+    vec3.add(newFocalPoint, camera.focalPoint, projectedDelta);
+    vec3.add(newPosition, camera.position, projectedDelta);
+
+    viewport.setCamera({
+      focalPoint: newFocalPoint,
+      position: newPosition,
+    });
+    viewport.render();
+  }
+}

package/src/utilities/viewportFilters/filterViewportsWithFrameOfReferenceUID.ts

@@ -0,0 +1,28 @@
+import type { Types } from '@cornerstonejs/core';
+
+/**
+ * Given an array of viewports, returns a list of viewports that are viewing a
+ * world space with the given `FrameOfReferenceUID`.
+ *
+ * @param viewports - An array of viewports.
+ * @param FrameOfReferenceUID - The UID defining a particular world space/Frame Of Reference.
+ *
+ * @returns A filtered array of viewports.
+ */
+export default function filterViewportsWithFrameOfReferenceUID(
+  viewports: Array<Types.IStackViewport | Types.IVolumeViewport>,
+  FrameOfReferenceUID: string
+): Array<Types.IStackViewport | Types.IVolumeViewport> {
+  const numViewports = viewports.length;
+  const viewportsWithFrameOfReferenceUID = [];
+
+  for (let vp = 0; vp < numViewports; vp++) {
+    const viewport = viewports[vp];
+
+    if (viewport.getFrameOfReferenceUID() === FrameOfReferenceUID) {
+      viewportsWithFrameOfReferenceUID.push(viewport);
+    }
+  }
+
+  return viewportsWithFrameOfReferenceUID;
+}