@cornerstonejs/tools 0.56.2 → 0.56.3

package/src/utilities/cine/playClip.ts

@@ -0,0 +1,435 @@
+import { glMatrix, vec3 } from 'gl-matrix';
+import {
+  utilities as csUtils,
+  getEnabledElement,
+  StackViewport,
+  VolumeViewport,
+  cache,
+} from '@cornerstonejs/core';
+
+import { Types } from '@cornerstonejs/core';
+import CINE_EVENTS from './events';
+import { addToolState, getToolState } from './state';
+import { CINETypes } from '../../types';
+import scroll from '../scroll';
+
+const { triggerEvent } = csUtils;
+
+const debounced = true;
+const loop = true;
+const dynamicVolumesPlayingMap = new Map();
+
+/**
+ * Starts playing a clip or adjusts the frame rate of an already playing clip.  framesPerSecond is
+ * optional and defaults to 30 if not specified.  A negative framesPerSecond will play the clip in reverse.
+ * The element must be a stack of images
+ * @param element - HTML Element
+ * @param framesPerSecond - Number of frames per second
+ */
+function playClip(
+  element: HTMLDivElement,
+  playClipOptions: CINETypes.PlayClipOptions
+): void {
+  let playClipTimeouts;
+  let playClipIsTimeVarying;
+
+  if (element === undefined) {
+    throw new Error('playClip: element must not be undefined');
+  }
+
+  const enabledElement = getEnabledElement(element);
+
+  if (!enabledElement) {
+    throw new Error(
+      'playClip: element must be a valid Cornerstone enabled element'
+    );
+  }
+
+  // 4D Cine is enabled by default
+  playClipOptions.dynamicCineEnabled =
+    playClipOptions.dynamicCineEnabled ?? true;
+
+  const { viewport } = enabledElement;
+  const volume = _getVolumeFromViewport(viewport);
+  const playClipContext = _createCinePlayContext(viewport, playClipOptions);
+  let playClipData = getToolState(element);
+
+  const isDynamicCinePlaying =
+    playClipOptions.dynamicCineEnabled && volume?.isDynamicVolume();
+
+  // If user is trying to play CINE for a 4D volume it first needs
+  // to stop CINE that has may be playing for any other viewport.
+  if (isDynamicCinePlaying) {
+    _stopDynamicVolumeCine(element);
+  }
+
+  if (!playClipData) {
+    playClipData = {
+      intervalId: undefined,
+      framesPerSecond: 30,
+      lastFrameTimeStamp: undefined,
+      ignoreFrameTimeVector: false,
+      usingFrameTimeVector: false,
+      frameTimeVector: playClipOptions.frameTimeVector ?? undefined,
+      speed: playClipOptions.frameTimeVectorSpeedMultiplier ?? 1,
+      reverse: playClipOptions.reverse ?? false,
+      loop: playClipOptions.loop ?? true,
+    };
+    addToolState(element, playClipData);
+  } else {
+    // Make sure the specified clip is not running before any property update.
+    // If a 3D CINE was playing it passes isDynamicCinePlaying as FALSE to
+    // prevent stopping a 4D CINE in case it is playing on another viewport.
+    _stopClip(element, isDynamicCinePlaying);
+  }
+
+  playClipData.dynamicCineEnabled = playClipOptions.dynamicCineEnabled;
+
+  // If a framesPerSecond is specified and is valid, update the playClipData now
+  if (
+    playClipOptions.framesPerSecond < 0 ||
+    playClipOptions.framesPerSecond > 0
+  ) {
+    playClipData.framesPerSecond = Number(playClipOptions.framesPerSecond);
+    playClipData.reverse = playClipData.framesPerSecond < 0;
+    // If framesPerSecond is given, frameTimeVector will be ignored...
+    playClipData.ignoreFrameTimeVector = true;
+  }
+
+  // Determine if frame time vector should be used instead of a fixed frame rate...
+  if (
+    playClipData.ignoreFrameTimeVector !== true &&
+    playClipData.frameTimeVector &&
+    playClipData.frameTimeVector.length === playClipContext.numScrollSteps &&
+    playClipContext.frameTimeVectorEnabled
+  ) {
+    const { timeouts, isTimeVarying } = _getPlayClipTimeouts(
+      playClipData.frameTimeVector,
+      playClipData.speed
+    );
+
+    playClipTimeouts = timeouts;
+    playClipIsTimeVarying = isTimeVarying;
+  }
+
+  // This function encapsulates the frame rendering logic...
+  const playClipAction = () => {
+    const { numScrollSteps, currentStepIndex } = playClipContext;
+    let newStepIndex = currentStepIndex + (playClipData.reverse ? -1 : 1);
+    const newStepIndexOutOfRange =
+      newStepIndex < 0 || newStepIndex >= numScrollSteps;
+
+    if (!loop && newStepIndexOutOfRange) {
+      // If a 3D CINE was playing it passes isDynamicCinePlaying as FALSE to
+      // prevent stopping a 4D CINE in case it is playing on another viewport.
+      _stopClip(element, isDynamicCinePlaying);
+
+      const eventDetail = { element };
+
+      triggerEvent(element, CINE_EVENTS.CLIP_STOPPED, eventDetail);
+      return;
+    }
+
+    // Loop around if newStepIndex is out of range
+    if (newStepIndex >= numScrollSteps) {
+      newStepIndex = 0;
+    } else if (newStepIndex < 0) {
+      newStepIndex = numScrollSteps - 1;
+    }
+
+    const delta = newStepIndex - currentStepIndex;
+
+    if (delta) {
+      playClipContext.scroll(delta);
+    }
+  };
+
+  if (isDynamicCinePlaying) {
+    dynamicVolumesPlayingMap.set(volume.volumeId, element);
+  }
+
+  // If playClipTimeouts array is available, not empty and its elements are NOT uniform ...
+  // ... (at least one timeout is different from the others), use alternate setTimeout implementation
+  if (
+    playClipTimeouts &&
+    playClipTimeouts.length > 0 &&
+    playClipIsTimeVarying
+  ) {
+    playClipData.usingFrameTimeVector = true;
+    playClipData.intervalId = window.setTimeout(
+      function playClipTimeoutHandler() {
+        playClipData.intervalId = window.setTimeout(
+          playClipTimeoutHandler,
+          playClipTimeouts[playClipContext.currentStepIndex]
+        );
+        playClipAction();
+      },
+      0
+    );
+  } else {
+    // ... otherwise user setInterval implementation which is much more efficient.
+    playClipData.usingFrameTimeVector = false;
+    playClipData.intervalId = window.setInterval(
+      playClipAction,
+      1000 / Math.abs(playClipData.framesPerSecond)
+    );
+  }
+
+  const eventDetail = {
+    element,
+  };
+
+  triggerEvent(element, CINE_EVENTS.CLIP_STARTED, eventDetail);
+}
+
+/**
+ * Stops an already playing clip.
+ * @param element - HTML Element
+ */
+function stopClip(element: HTMLDivElement): void {
+  _stopClip(element, true);
+}
+
+function _stopClip(element: HTMLDivElement, stopDynamicCine: boolean): void {
+  const enabledElement = getEnabledElement(element);
+  if (!enabledElement) return;
+  const { viewport } = enabledElement;
+  const cineToolData = getToolState(viewport.element);
+
+  if (cineToolData) {
+    _stopClipWithData(cineToolData);
+  }
+
+  if (stopDynamicCine) {
+    _stopDynamicVolumeCine(element);
+  }
+}
+
+/**
+ * [private] Stops any CINE playing for the dynamic volume loaded on this viewport
+ * @param element - HTML Element
+ */
+function _stopDynamicVolumeCine(element) {
+  const { viewport } = getEnabledElement(element);
+  const volume = _getVolumeFromViewport(viewport);
+
+  // If the current viewport has a 4D volume loaded it may be playing
+  // if it is also loaded on another viewport and user has started CINE
+  // for that one. This guarantees the other viewport will also be stopped.
+  if (volume?.isDynamicVolume()) {
+    const dynamicCineElement = dynamicVolumesPlayingMap.get(volume.volumeId);
+
+    dynamicVolumesPlayingMap.delete(volume.volumeId);
+
+    if (dynamicCineElement && dynamicCineElement !== element) {
+      stopClip(<HTMLDivElement>dynamicCineElement);
+    }
+  }
+}
+
+/**
+ * [private] Turns a Frame Time Vector (0018,1065) array into a normalized array of timeouts. Each element
+ * ... of the resulting array represents the amount of time each frame will remain on the screen.
+ * @param vector - A Frame Time Vector (0018,1065) as specified in section C.7.6.5.1.2 of DICOM standard.
+ * @param speed - A speed factor which will be applied to each element of the resulting array.
+ * @returns An array with timeouts for each animation frame.
+ */
+function _getPlayClipTimeouts(vector: number[], speed: number) {
+  let i;
+  let sample;
+  let delay;
+  let sum = 0;
+  const limit = vector.length;
+  const timeouts = [];
+
+  // Initialize time varying to false
+  let isTimeVarying = false;
+
+  if (typeof speed !== 'number' || speed <= 0) {
+    speed = 1;
+  }
+
+  // First element of a frame time vector must be discarded
+  for (i = 1; i < limit; i++) {
+    // eslint-disable-next-line no-bitwise
+    delay = (Number(vector[i]) / speed) | 0; // Integral part only
+    timeouts.push(delay);
+    if (i === 1) {
+      // Use first item as a sample for comparison
+      sample = delay;
+    } else if (delay !== sample) {
+      isTimeVarying = true;
+    }
+
+    sum += delay;
+  }
+
+  if (timeouts.length > 0) {
+    if (isTimeVarying) {
+      // If it's a time varying vector, make the last item an average...
+      // eslint-disable-next-line no-bitwise
+      delay = (sum / timeouts.length) | 0;
+    } else {
+      delay = timeouts[0];
+    }
+
+    timeouts.push(delay);
+  }
+
+  return { timeouts, isTimeVarying };
+}
+
+/**
+ * [private] Performs the heavy lifting of stopping an ongoing animation.
+ * @param element - HTML Element
+ * @param playClipData - The data from playClip that needs to be stopped.
+ */
+function _stopClipWithData(playClipData) {
+  const id = playClipData.intervalId;
+
+  if (typeof id !== 'undefined') {
+    playClipData.intervalId = undefined;
+    if (playClipData.usingFrameTimeVector) {
+      clearTimeout(id);
+    } else {
+      clearInterval(id);
+    }
+  }
+}
+
+function _getVolumeFromViewport(viewport): Types.IImageVolume {
+  const actorEntry = viewport.getDefaultActor();
+
+  if (!actorEntry) {
+    console.warn('No actor found');
+    return;
+  }
+
+  const volumeId = actorEntry.uid;
+  return cache.getVolume(volumeId);
+}
+
+function _createStackViewportCinePlayContext(
+  viewport: StackViewport
+): CINETypes.CinePlayContext {
+  const imageIds = viewport.getImageIds();
+
+  return {
+    get numScrollSteps(): number {
+      return imageIds.length;
+    },
+    get currentStepIndex(): number {
+      return viewport.getTargetImageIdIndex();
+    },
+    get frameTimeVectorEnabled(): boolean {
+      // It is always in acquired orientation
+      return true;
+    },
+    scroll(delta: number): void {
+      scroll(viewport, { delta, debounceLoading: debounced });
+    },
+  };
+}
+
+function _createVolumeViewportCinePlayContext(
+  viewport: VolumeViewport,
+  volume: Types.IImageVolume
+): CINETypes.CinePlayContext {
+  const { volumeId } = volume;
+  const cachedScrollInfo = {
+    viewPlaneNormal: vec3.create(),
+    scrollInfo: null,
+  };
+
+  const getScrollInfo = () => {
+    const camera = viewport.getCamera();
+    const updateCache =
+      !cachedScrollInfo.scrollInfo ||
+      !vec3.equals(camera.viewPlaneNormal, cachedScrollInfo.viewPlaneNormal);
+
+    // Number of steps would change only after rotating the volume so it
+    // caches the result and recomputes only when necessary. Until it is
+    // rotated the current frame is updated locally
+    if (updateCache) {
+      const scrollInfo = csUtils.getVolumeViewportScrollInfo(
+        viewport,
+        volumeId
+      );
+
+      cachedScrollInfo.viewPlaneNormal = camera.viewPlaneNormal;
+      cachedScrollInfo.scrollInfo = scrollInfo;
+    }
+
+    return cachedScrollInfo.scrollInfo;
+  };
+
+  return {
+    get numScrollSteps(): number {
+      return getScrollInfo().numScrollSteps;
+    },
+    get currentStepIndex(): number {
+      return getScrollInfo().currentStepIndex;
+    },
+    get frameTimeVectorEnabled(): boolean {
+      const camera = viewport.getCamera();
+      const volumeViewPlaneNormal = volume.direction
+        .slice(6, 9)
+        .map((x) => -x) as Types.Point3;
+      const dot = vec3.dot(volumeViewPlaneNormal, camera.viewPlaneNormal);
+
+      // Check if the volume is in acquired orientation
+      // it may be flipped or rotated in plane
+      return glMatrix.equals(dot, 1);
+    },
+    scroll(delta: number): void {
+      getScrollInfo().currentStepIndex += delta;
+      scroll(viewport, { delta });
+    },
+  };
+}
+
+function _createDynamicVolumeViewportCinePlayContext(
+  volume: Types.IDynamicImageVolume
+): CINETypes.CinePlayContext {
+  return {
+    get numScrollSteps(): number {
+      return volume.numTimePoints;
+    },
+    get currentStepIndex(): number {
+      return volume.timePointIndex;
+    },
+    get frameTimeVectorEnabled(): boolean {
+      // Looping throught time does not uses frameTimeVector
+      return false;
+    },
+    scroll(delta: number): void {
+      // Updating this property (setter) makes it move to the desired time point
+      volume.timePointIndex += delta;
+    },
+  };
+}
+
+function _createCinePlayContext(
+  viewport,
+  playClipOptions: CINETypes.PlayClipOptions
+): CINETypes.CinePlayContext {
+  if (viewport instanceof StackViewport) {
+    return _createStackViewportCinePlayContext(viewport);
+  }
+
+  if (viewport instanceof VolumeViewport) {
+    const volume = _getVolumeFromViewport(viewport);
+
+    if (playClipOptions.dynamicCineEnabled && volume?.isDynamicVolume()) {
+      return _createDynamicVolumeViewportCinePlayContext(
+        <Types.IDynamicImageVolume>volume
+      );
+    }
+
+    return _createVolumeViewportCinePlayContext(viewport, volume);
+  }
+
+  throw new Error('Unknown viewport type');
+}
+
+export { playClip, stopClip };

package/src/utilities/cine/state.ts

@@ -0,0 +1,18 @@
+import { getEnabledElement } from '@cornerstonejs/core';
+import { CINETypes } from '../../types';
+
+const state: Record<string, CINETypes.ToolData> = {};
+
+function addToolState(element: HTMLDivElement, data: CINETypes.ToolData): void {
+  const enabledElement = getEnabledElement(element);
+  const { viewportId } = enabledElement;
+  state[viewportId] = data;
+}
+
+function getToolState(element: HTMLDivElement): CINETypes.ToolData | undefined {
+  const enabledElement = getEnabledElement(element);
+  const { viewportId } = enabledElement;
+  return state[viewportId];
+}
+
+export { addToolState, getToolState };

package/src/utilities/clip.js

@@ -0,0 +1,30 @@
+/**
+ * Clips a value to an upper and lower bound.
+ * @export @public @method
+ * @name clip
+ *
+ * @param  {number} val  The value to clip.
+ * @param  {number} low  The lower bound.
+ * @param  {number} high The upper bound.
+ * @returns {number}      The clipped value.
+ */
+export function clip(val, low, high) {
+  return Math.min(Math.max(low, val), high);
+}
+
+/**
+ * Clips a value within a box.
+ * @export @public @method
+ * @name clipToBox
+ *
+ * @param  {Object} point The point to clip
+ * @param  {Object} box   The bounding box to clip to.
+ * @returns {Object}       The clipped point.
+ */
+export function clipToBox(point, box) {
+  // Clip an {x, y} point to a box of size {width, height}
+  point.x = clip(point.x, 0, box.width);
+  point.y = clip(point.y, 0, box.height);
+}
+
+export default clip;

package/src/utilities/debounce.js

@@ -0,0 +1,217 @@
+import isObject from './isObject';
+
+/**
+ * Creates a debounced function that delays invoking `func` until after `wait`
+ * milliseconds have elapsed since the last time the debounced function was
+ * invoked, or until the next browser frame is drawn. The debounced function
+ * comes with a `cancel` method to cancel delayed `func` invocations and a
+ * `flush` method to immediately invoke them. Provide `options` to indicate
+ * whether `func` should be invoked on the leading and/or trailing edge of the
+ * `wait` timeout. The `func` is invoked with the last arguments provided to the
+ * debounced function. Subsequent calls to the debounced function return the
+ * result of the last `func` invocation.
+ *
+ * **Note:** If `leading` and `trailing` options are `true`, `func` is
+ * invoked on the trailing edge of the timeout only if the debounced function
+ * is invoked more than once during the `wait` timeout.
+ *
+ * If `wait` is `0` and `leading` is `false`, `func` invocation is deferred
+ * until the next tick, similar to `setTimeout` with a timeout of `0`.
+ *
+ * If `wait` is omitted in an environment with `requestAnimationFrame`, `func`
+ * invocation will be deferred until the next frame is drawn (typically about
+ * 16ms).
+ *
+ * See [David Corbacho's article](https://css-tricks.com/debouncing-throttling-explained-examples/)
+ * for details over the differences between `debounce` and `throttle`.
+ *
+ * @param {Function} func The function to debounce.
+ * @param {number} [wait=0]
+ *  The number of milliseconds to delay; if omitted, `requestAnimationFrame` is
+ *  used (if available).
+ * @param {Object} [options={}] The options object.
+ * @param {boolean} [options.leading=false]
+ *  Specify invoking on the leading edge of the timeout.
+ * @param {number} [options.maxWait]
+ *  The maximum time `func` is allowed to be delayed before it's invoked.
+ * @param {boolean} [options.trailing=true]
+ *  Specify invoking on the trailing edge of the timeout.
+ * @returns {Function} Returns the new debounced function.
+ * @example
+ *
+ * // Avoid costly calculations while the window size is in flux.
+ * jQuery(window).on('resize', debounce(calculateLayout, 150))
+ *
+ * // Invoke `sendMail` when clicked, debouncing subsequent calls.
+ * jQuery(element).on('click', debounce(sendMail, 300, {
+ *   'leading': true,
+ *   'trailing': false
+ * }))
+ *
+ * // Ensure `batchLog` is invoked once after 1 second of debounced calls.
+ * const debounced = debounce(batchLog, 250, { 'maxWait': 1000 })
+ * const source = new EventSource('/stream')
+ * jQuery(source).on('message', debounced)
+ *
+ * // Cancel the trailing debounced invocation.
+ * jQuery(window).on('popstate', debounced.cancel)
+ *
+ * // Check for pending invocations.
+ * const status = debounced.pending() ? "Pending..." : "Ready"
+ */
+function debounce(func, wait, options) {
+  let lastArgs, lastThis, maxWait, result, timerId, lastCallTime;
+
+  let lastInvokeTime = 0;
+  let leading = false;
+  let maxing = false;
+  let trailing = true;
+
+  // Bypass `requestAnimationFrame` by explicitly setting `wait=0`.
+  const useRAF =
+    !wait && wait !== 0 && typeof window.requestAnimationFrame === 'function';
+
+  if (typeof func !== 'function') {
+    throw new TypeError('Expected a function');
+  }
+  wait = Number(wait) || 0;
+  if (isObject(options)) {
+    leading = Boolean(options.leading);
+    maxing = 'maxWait' in options;
+    maxWait = maxing ? Math.max(Number(options.maxWait) || 0, wait) : maxWait;
+    trailing = 'trailing' in options ? Boolean(options.trailing) : trailing;
+  }
+
+  function invokeFunc(time) {
+    const args = lastArgs;
+    const thisArg = lastThis;
+
+    lastArgs = lastThis = undefined;
+    lastInvokeTime = time;
+    result = func.apply(thisArg, args);
+
+    return result;
+  }
+
+  function startTimer(pendingFunc, wait) {
+    if (useRAF) {
+      return window.requestAnimationFrame(pendingFunc);
+    }
+
+    return setTimeout(pendingFunc, wait);
+  }
+
+  function cancelTimer(id) {
+    if (useRAF) {
+      return window.cancelAnimationFrame(id);
+    }
+    clearTimeout(id);
+  }
+
+  function leadingEdge(time) {
+    // Reset any `maxWait` timer.
+    lastInvokeTime = time;
+    // Start the timer for the trailing edge.
+    timerId = startTimer(timerExpired, wait);
+
+    // Invoke the leading edge.
+    return leading ? invokeFunc(time) : result;
+  }
+
+  function remainingWait(time) {
+    const timeSinceLastCall = time - lastCallTime;
+    const timeSinceLastInvoke = time - lastInvokeTime;
+    const timeWaiting = wait - timeSinceLastCall;
+
+    return maxing
+      ? Math.min(timeWaiting, maxWait - timeSinceLastInvoke)
+      : timeWaiting;
+  }
+
+  function shouldInvoke(time) {
+    const timeSinceLastCall = time - lastCallTime;
+    const timeSinceLastInvoke = time - lastInvokeTime;
+
+    // Either this is the first call, activity has stopped and we're at the
+    // trailing edge, the system time has gone backwards and we're treating
+    // it as the trailing edge, or we've hit the `maxWait` limit.
+    return (
+      lastCallTime === undefined ||
+      timeSinceLastCall >= wait ||
+      timeSinceLastCall < 0 ||
+      (maxing && timeSinceLastInvoke >= maxWait)
+    );
+  }
+
+  function timerExpired() {
+    const time = Date.now();
+
+    if (shouldInvoke(time)) {
+      return trailingEdge(time);
+    }
+    // Restart the timer.
+    timerId = startTimer(timerExpired, remainingWait(time));
+  }
+
+  function trailingEdge(time) {
+    timerId = undefined;
+
+    // Only invoke if we have `lastArgs` which means `func` has been
+    // debounced at least once.
+    if (trailing && lastArgs) {
+      return invokeFunc(time);
+    }
+    lastArgs = lastThis = undefined;
+
+    return result;
+  }
+
+  function cancel() {
+    if (timerId !== undefined) {
+      cancelTimer(timerId);
+    }
+    lastInvokeTime = 0;
+    lastArgs = lastCallTime = lastThis = timerId = undefined;
+  }
+
+  function flush() {
+    return timerId === undefined ? result : trailingEdge(Date.now());
+  }
+
+  function pending() {
+    return timerId !== undefined;
+  }
+
+  function debounced(...args) {
+    const time = Date.now();
+    const isInvoking = shouldInvoke(time);
+
+    lastArgs = args;
+    lastThis = this; // eslint-disable-line consistent-this
+    lastCallTime = time;
+
+    if (isInvoking) {
+      if (timerId === undefined) {
+        return leadingEdge(lastCallTime);
+      }
+      if (maxing) {
+        // Handle invocations in a tight loop.
+        timerId = startTimer(timerExpired, wait);
+
+        return invokeFunc(lastCallTime);
+      }
+    }
+    if (timerId === undefined) {
+      timerId = startTimer(timerExpired, wait);
+    }
+
+    return result;
+  }
+  debounced.cancel = cancel;
+  debounced.flush = flush;
+  debounced.pending = pending;
+
+  return debounced;
+}
+
+export default debounce;