@cornerstonejs/tools 2.0.0-beta.1 → 2.0.0-beta.11

package/src/utilities/contours/interpolation/selectHandles.ts

@@ -0,0 +1,245 @@
+import { vec3 } from 'gl-matrix';
+import { utilities } from '@cornerstonejs/core';
+import type { PointsArray3 } from './interpolate';
+
+const { PointsManager } = utilities;
+
+/**
+ * Selects handles by looking for local maximums in the angle that the local
+ * vector makes
+ *
+ * @param polyline - an array of points, usually the polyline for the contour to
+ *        select handles from.
+ * @param handleCount - a guideline for how many handles to create
+ */
+export default function selectHandles(
+  polyline: PointsArray3,
+  handleCount = 12
+): PointsArray3 {
+  const handles = PointsManager.create3(handleCount) as PointsArray3;
+  handles.sources = [];
+  const { sources: destPoints } = handles;
+  const { length, sources: sourcePoints = [] } = polyline;
+  // The distance used for figuring out the local angle of a line
+  const distance = 5;
+  if (length < distance * 3) {
+    return polyline.subselect(handleCount);
+  }
+  // Need to make the interval between handles long enough to allow for some
+  // variation between points in terms of the distance of a line angle, but
+  // also not too many handles either.
+  // On average, we get twice the interval between handles, so double the length here.
+  // Or, choose a longer interval if the handle count would have too many handles (too short an interval)
+  const interval = Math.floor(
+    Math.max((2 * length) / handleCount, distance * 2)
+  );
+  sourcePoints.forEach(() =>
+    destPoints.push(PointsManager.create3(handleCount))
+  );
+
+  const dotValues = createDotValues(polyline, distance);
+
+  const minimumRegions = findMinimumRegions(dotValues, handleCount);
+  const indices = [];
+  if (minimumRegions?.length > 2) {
+    let lastHandle = -1;
+    const thirdInterval = interval / 3;
+    minimumRegions.forEach((region) => {
+      const [start, , end] = region;
+      const midIndex = Math.ceil((start + end) / 2);
+      if (end - lastHandle < thirdInterval) {
+        return;
+      }
+      if (midIndex - start > 2 * thirdInterval) {
+        addInterval(indices, lastHandle, start, interval, length);
+        lastHandle = addInterval(indices, start, midIndex, interval, length);
+      } else {
+        lastHandle = addInterval(
+          indices,
+          lastHandle,
+          midIndex,
+          interval,
+          length
+        );
+      }
+      if (end - lastHandle > thirdInterval) {
+        lastHandle = addInterval(indices, lastHandle, end, interval, length);
+      }
+    });
+    const firstHandle = indices[0];
+    const lastDistance = indexValue(firstHandle + length - lastHandle, length);
+    // Check that there is enough space between the last and first handle to
+    // need an extra handle.
+    if (lastDistance > 2 * thirdInterval) {
+      addInterval(
+        indices,
+        lastHandle,
+        // Don't add a point too close to the first handle
+        firstHandle - thirdInterval,
+        interval,
+        length
+      );
+    }
+  } else {
+    const interval = Math.floor(length / handleCount);
+    addInterval(indices, -1, length - interval, interval, length);
+  }
+
+  indices.forEach((index) => {
+    const point = polyline.getPointArray(index);
+    handles.push(point);
+    sourcePoints.forEach((source, destSourceIndex) =>
+      destPoints[destSourceIndex].push(source.getPoint(index))
+    );
+  });
+  return handles;
+}
+
+/**
+ * Creates an array of the dot products between each point in the points array
+ * and a point +/- distance from that point, unitized to vector length 1.
+ * That is, this is a measure of the angle at the given point, where 1 is a
+ * straight line, and -1 is a 180 degree angle change.
+ *
+ * @param polyline - the array of Point3 values
+ * @param distance - previous/next distance to use for the vectors for the dot product
+ * @returns - Float32Array of dot products, one per point in the source array.
+ */
+export function createDotValues(
+  polyline: PointsArray3,
+  distance = 6
+): Float32Array {
+  const { length } = polyline;
+  const prevVec3 = vec3.create();
+  const nextVec3 = vec3.create();
+  const dotValues = new Float32Array(length);
+
+  for (let i = 0; i < length; i++) {
+    const point = polyline.getPoint(i);
+    const prevPoint = polyline.getPoint(i - distance);
+    const nextPoint = polyline.getPoint((i + distance) % length);
+    vec3.sub(prevVec3, point, prevPoint);
+    vec3.sub(nextVec3, nextPoint, point);
+    const dot =
+      vec3.dot(prevVec3, nextVec3) / (vec3.len(prevVec3) * vec3.len(nextVec3));
+    dotValues[i] = dot;
+  }
+
+  return dotValues;
+}
+
+/**
+ * Finds minimum regions in the dot products.  These are detected as
+ * center points of the dot values regions having a minimum value - that is,
+ * where the direction of the line is changing fastest.
+ */
+function findMinimumRegions(dotValues, handleCount) {
+  const { max, deviation } = getStats(dotValues);
+  const { length } = dotValues;
+  // Fallback for very uniform ojects.
+  if (deviation < 0.01 || length < handleCount * 3) {
+    return [];
+  }
+
+  const inflection = [];
+  let pair = null;
+  let minValue;
+  let minIndex = 0;
+
+  for (let i = 0; i < length; i++) {
+    const dot = dotValues[i];
+    if (dot < max - deviation) {
+      if (pair) {
+        pair[2] = i;
+        if (dot < minValue) {
+          minValue = dot;
+          minIndex = i;
+        }
+        pair[1] = minIndex;
+      } else {
+        minValue = dot;
+        minIndex = i;
+        pair = [i, i, i];
+      }
+    } else {
+      if (pair) {
+        inflection.push(pair);
+        pair = null;
+      }
+    }
+  }
+  if (pair) {
+    if (inflection[0][0] === 0) {
+      inflection[0][0] = pair[0];
+    } else {
+      pair[1] = minIndex;
+      pair[2] = length - 1;
+      inflection.push(pair);
+    }
+  }
+
+  return inflection;
+}
+
+/**
+ * Adds points in between the start and finish.
+ * This is currently just the center point for short values and the start/center/end
+ * for ranges where the distance between these is at least the increment.
+ */
+export function addInterval(indices, start, finish, interval, length) {
+  if (finish < start) {
+    // Always want a positive distance even if the long way round
+    finish += length;
+  }
+  const distance = finish - start;
+  const count = Math.ceil(distance / interval);
+  if (count <= 0) {
+    if (indices[indices.length - 1] !== finish) {
+      indices.push(indexValue(finish, length));
+    }
+    return finish;
+  }
+  // Don't add the start index, and always add the end index
+  for (let i = 1; i <= count; i++) {
+    const index = indexValue(start + (i * distance) / count, length);
+    indices.push(index);
+  }
+  return indices[indices.length - 1];
+}
+
+/**
+ * Gets the index value of a closed polyline, rounding the value and
+ * doing the module operation as required.
+ */
+function indexValue(v, length) {
+  return (Math.round(v) + length) % length;
+}
+
+/**
+ * Gets statistics on the provided array numbers.
+ */
+function getStats(dotValues) {
+  const { length } = dotValues;
+  let sum = 0;
+  let min = Infinity;
+  let max = -Infinity;
+  let sumSq = 0;
+  for (let i = 0; i < length; i++) {
+    const dot = dotValues[i];
+    sum += dot;
+    min = Math.min(min, dot);
+    max = Math.max(max, dot);
+  }
+  const mean = sum / length;
+  for (let i = 0; i < length; i++) {
+    const valueDiff = dotValues[i] - mean;
+    sumSq += valueDiff * valueDiff;
+  }
+  return {
+    mean,
+    max,
+    min,
+    sumSq,
+    deviation: Math.sqrt(sumSq / length),
+  };
+}

package/src/utilities/contours/interpolation/updateChildInterpolationUID.ts

@@ -0,0 +1,23 @@
+import type { InterpolationROIAnnotation } from '../../../types/ToolSpecificAnnotationTypes';
+import * as annotationState from '../../../stateManagement/annotation';
+
+/**
+ * Updates child annotation interpolation UIDs to be the parent interpolationUID
+ * followed by `-{index}` where the index is the hole/child index.  This causes
+ * child annotations to be matched positionally within the parent.
+ */
+export default function updateChildInterpolationUID(
+  annotation: InterpolationROIAnnotation
+) {
+  const { parentAnnotationUID, annotationUID } = annotation;
+  if (!parentAnnotationUID) {
+    return annotation.interpolationUID;
+  }
+  const parentAnnotation = annotationState.state.getAnnotation(
+    parentAnnotationUID
+  ) as InterpolationROIAnnotation;
+  const { interpolationUID } = parentAnnotation;
+  const index = parentAnnotation.childAnnotationUIDs.indexOf(annotationUID);
+  annotation.interpolationUID = `${interpolationUID}-${index}`;
+  return annotation.interpolationUID;
+}

package/src/utilities/contours/reverseIfAntiClockwise.ts

@@ -0,0 +1,29 @@
+import { Types } from '@cornerstonejs/core';
+import { getSignedArea } from '../math/polyline';
+
+/**
+ * _reverseIfAntiClockwise - If the contour's nodes run anti-clockwise,
+ * reverse them.
+ *
+ * @param points - The points array.
+ * @param otherListsToReverse - any number of additional lists to also reverse
+ *       when the primary list is anti-clockwise.
+ * @returns The contour, corrected to be clockwise if appropriate.
+ */
+export default function reverseIfAntiClockwise(
+  points: Types.Point2[],
+  ...otherListsToReverse: unknown[][]
+) {
+  const signedArea = getSignedArea(points);
+
+  // signedArea will be less than zero for anti-clockwise
+  if (signedArea < 0) {
+    if (otherListsToReverse) {
+      otherListsToReverse.forEach((list) => list.reverse());
+    }
+
+    return points.slice().reverse();
+  }
+
+  return points;
+}

package/src/utilities/contours/updateContourPolyline.ts

@@ -0,0 +1,111 @@
+import { utilities as csUtils } from '@cornerstonejs/core';
+import { Types } from '@cornerstonejs/core';
+import type { ContourAnnotation } from '../../types';
+import type { ContourWindingDirection } from '../../types/ContourAnnotation';
+import * as math from '../math';
+import {
+  getParentAnnotation,
+  invalidateAnnotation,
+} from '../../stateManagement';
+
+/**
+ * Update the contour polyline data
+ * @param annotation - Contour annotation
+ * @param viewport - Viewport
+ * @param polylineData - Polyline data (points, winding direction and closed)
+ * @param transforms - Methods to convert points to/from canvas and world spaces
+ * @param options - Options
+ *   - decimate: allow to set some parameters to decimate the polyline reducing
+ *   the amount of points stored which also affects how fast it will draw the
+ *   annotation in a viewport, compute the winding direction, append/remove
+ *   contours and create holes. A higher `epsilon` value results in a polyline
+ *   with less points.
+ */
+export default function updateContourPolyline(
+  annotation: ContourAnnotation,
+  polylineData: {
+    points: Types.Point2[];
+    closed?: boolean;
+    targetWindingDirection?: ContourWindingDirection;
+  },
+  transforms: {
+    canvasToWorld: (point: Types.Point2) => Types.Point3;
+    worldToCanvas: (point: Types.Point3) => Types.Point2;
+  },
+  options?: {
+    decimate?: {
+      enabled?: boolean;
+      epsilon?: number;
+    };
+  }
+) {
+  const { canvasToWorld, worldToCanvas } = transforms;
+  const { data } = annotation;
+  const { targetWindingDirection } = polylineData;
+  let { points: polyline } = polylineData;
+
+  // Decimate the polyline to reduce tha amount of points
+  if (options?.decimate?.enabled) {
+    polyline = math.polyline.decimate(
+      polylineData.points,
+      options?.decimate?.epsilon
+    );
+  }
+
+  let { closed } = polylineData;
+  const numPoints = polyline.length;
+  const polylineWorldPoints = new Array(numPoints);
+  const currentPolylineWindingDirection =
+    math.polyline.getWindingDirection(polyline);
+  const parentAnnotation = getParentAnnotation(annotation) as ContourAnnotation;
+
+  if (closed === undefined) {
+    let currentClosedState = false;
+
+    // With two points it is just a line and do not make sense to consider it closed
+    if (polyline.length > 3) {
+      const lastToFirstDist = math.point.distanceToPointSquared(
+        polyline[0],
+        polyline[numPoints - 1]
+      );
+
+      currentClosedState = csUtils.isEqual(0, lastToFirstDist);
+    }
+
+    closed = currentClosedState;
+  }
+
+  // It must be in the opposite direction if it is a child annotation (hole)
+  let windingDirection = parentAnnotation
+    ? parentAnnotation.data.contour.windingDirection * -1
+    : targetWindingDirection;
+
+  if (windingDirection === undefined) {
+    windingDirection = currentPolylineWindingDirection;
+  }
+
+  if (windingDirection !== currentPolylineWindingDirection) {
+    polyline.reverse();
+  }
+
+  const handlePoints = data.handles.points.map((p) => worldToCanvas(p));
+
+  if (handlePoints.length > 2) {
+    const currentHandlesWindingDirection =
+      math.polyline.getWindingDirection(handlePoints);
+
+    if (currentHandlesWindingDirection !== windingDirection) {
+      data.handles.points.reverse();
+    }
+  }
+
+  for (let i = 0; i < numPoints; i++) {
+    polylineWorldPoints[i] = canvasToWorld(polyline[i]);
+  }
+
+  data.contour.polyline = polylineWorldPoints;
+  data.contour.closed = closed;
+  data.contour.windingDirection = windingDirection;
+
+  invalidateAnnotation(annotation);
+}

package/src/utilities/dynamicVolume/generateImageFromTimeData.ts

@@ -5,10 +5,10 @@ import { Enums, Types } from '@cornerstonejs/core';
  * array of scalar data after performing AVERAGE, SUM or SUBTRACT to be used to
  * create a 3D volume
  *
- * @param dynamicVolume4D: volume to compute time frame data from
- * @param operation: operation to perform on time frame data, operations include
+ * @param dynamicVolume4D - volume to compute time frame data from
+ * @param operation - operation to perform on time frame data, operations include
  * SUM, AVERAGE, and SUBTRACT (can only be used with 2 time frames provided)
- * @param frameNumbers: an array of frame indexs to perform the operation on, if
+ * @param frameNumbers - an array of frame indices to perform the operation on, if
  * left empty, all frames will be used
  * @returns
  */

package/src/utilities/dynamicVolume/getDataInTime.ts

@@ -1,15 +1,17 @@
 import { utilities, cache, Types } from '@cornerstonejs/core';
+import { getVoxelOverlap } from '../segmentation/utilities';
+import pointInShapeCallback from '../pointInShapeCallback';
 
 /**
  * Gets the scalar data for a series of time points for either a single
  * coordinate or a segmentation mask, it will return the an array of scalar
  * data for a single coordinate or an array of arrays for a segmentation.
  *
- * @param dynamicVolume: 4D volume to compute time point data from
- * @param options: frameNumbers: which frames to use as timepoints, if left
+ * @param dynamicVolume - 4D volume to compute time point data from
+ * @param options - frameNumbers: which frames to use as timepoints, if left
  * blank, gets data timepoints over all frames
  * maskVolumeId: segmentationId to get timepoint data of
- * imageCoordinate: world coordinate to get timepoint data of
+ * worldCoordinate: world coordinate to get timepoint data of
  * @returns
  */
 function getDataInTime(
@@ -17,7 +19,7 @@ function getDataInTime(
   options: {
     frameNumbers?;
     maskVolumeId?;
-    imageCoordinate?;
+    worldCoordinate?;
   }
 ): number[] | number[][] {
   let dataInTime;
@@ -27,35 +29,35 @@ function getDataInTime(
     ...Array(dynamicVolume.numTimePoints).keys(),
   ];
 
-  // You only need to provide either maskVolumeId OR imageCoordinate.
-  // Throws error if neither maskVolumeId or imageCoordinate is given,
-  // throws error if BOTH maskVolumeId and imageCoordinate is given
-  if (!options.maskVolumeId && !options.imageCoordinate) {
-    throw new Error('No ROI provided');
+  // You only need to provide either maskVolumeId OR worldCoordinate.
+  // Throws error if neither maskVolumeId or worldCoordinate is given,
+  // throws error if BOTH maskVolumeId and worldCoordinate is given
+  if (!options.maskVolumeId && !options.worldCoordinate) {
+    throw new Error(
+      'You should provide either maskVolumeId or imageCoordinate'
+    );
   }
 
-  if (options.maskVolumeId && options.imageCoordinate) {
-    throw new Error('Please provide only one ROI');
+  if (options.maskVolumeId && options.worldCoordinate) {
+    throw new Error('You can only use one of maskVolumeId or imageCoordinate');
   }
 
   if (options.maskVolumeId) {
     const segmentationVolume = cache.getVolume(options.maskVolumeId);
 
-    // Get the index of every non-zero voxel in mask by mapping indexes to
-    // new array, then using the array to filter
-    const indexArray = segmentationVolume
-      .getScalarData()
-      .map((_, i) => i)
-      .filter((i) => segmentationVolume.getScalarData()[i] !== 0);
-    const dataInTime = _getTimePointDataMask(frames, indexArray, dynamicVolume);
+    const [dataInTime, ijkCoords] = _getTimePointDataMask(
+      frames,
+      dynamicVolume,
+      segmentationVolume
+    );
 
-    return dataInTime;
+    return [dataInTime, ijkCoords];
   }
 
-  if (options.imageCoordinate) {
+  if (options.worldCoordinate) {
     const dataInTime = _getTimePointDataCoordinate(
       frames,
-      options.imageCoordinate,
+      options.worldCoordinate,
       dynamicVolume
     );
 
@@ -92,19 +94,123 @@ function _getTimePointDataCoordinate(frames, coordinate, volume) {
   return value;
 }
 
-function _getTimePointDataMask(frames, indexArray, volume) {
-  const allScalarData = volume.getScalarDataArrays();
-  const value = [];
+function _getTimePointDataMask(frames, dynamicVolume, segmentationVolume) {
+  const { imageData: maskImageData } = segmentationVolume;
+  const segScalarData = segmentationVolume.getScalarData();
+
+  const len = segScalarData.length;
+
+  // Pre-allocate memory for array
+  const nonZeroVoxelIndices = [];
+  nonZeroVoxelIndices.length = len;
+  const ijkCoords = [];
+
+  const dimensions = segmentationVolume.dimensions;
+
+  // Get the index of every non-zero voxel in mask
+  let actualLen = 0;
+  for (let i = 0, len = segScalarData.length; i < len; i++) {
+    if (segScalarData[i] !== 0) {
+      ijkCoords.push([
+        i % dimensions[0],
+        Math.floor((i / dimensions[0]) % dimensions[1]),
+        Math.floor(i / (dimensions[0] * dimensions[1])),
+      ]);
+      nonZeroVoxelIndices[actualLen++] = i;
+    }
+  }
 
-  for (let i = 0; i < indexArray.length; i++) {
-    const indexValues = [];
-    frames.forEach((frame) => {
-      const activeScalarData = allScalarData[frame];
-      indexValues.push(activeScalarData[indexArray[i]]);
-    });
-    value.push(indexValues);
+  // Trim the array to actual size
+  nonZeroVoxelIndices.length = actualLen;
+
+  const dynamicVolumeScalarDataArray = dynamicVolume.getScalarDataArrays();
+  const values = [];
+  const isSameVolume =
+    dynamicVolumeScalarDataArray[0].length === len &&
+    JSON.stringify(dynamicVolume.spacing) ===
+      JSON.stringify(segmentationVolume.spacing);
+
+  // if the segmentation mask is the same size as the dynamic volume (one frame)
+  // means we can just return the scalar data for the non-zero voxels
+  if (isSameVolume) {
+    for (let i = 0; i < nonZeroVoxelIndices.length; i++) {
+      const indexValues = [];
+      frames.forEach((frame) => {
+        const activeScalarData = dynamicVolumeScalarDataArray[frame];
+        indexValues.push(activeScalarData[nonZeroVoxelIndices[i]]);
+      });
+      values.push(indexValues);
+    }
+
+    return [values, ijkCoords];
   }
-  return value;
+
+  // In case that the segmentation mask is not the same size as the dynamic volume (one frame)
+  // then we need to consider each voxel in the segmentation mask and check if it
+  // overlaps with the other volume, and if so we need to average the values of the
+  // overlapping voxels.
+  const callback = ({
+    pointLPS: segPointLPS,
+    value: segValue,
+    pointIJK: segPointIJK,
+  }) => {
+    // see if the value is non-zero
+    if (segValue === 0) {
+      // not interested
+      return;
+    }
+
+    // Then for each non-zero voxel in the segmentation mask, we should
+    // again perform the pointInShapeCallback to run the averaging callback
+    // function to get the average value of the overlapping voxels.
+    const overlapIJKMinMax = getVoxelOverlap(
+      dynamicVolume.imageData,
+      dynamicVolume.dimensions,
+      dynamicVolume.spacing,
+      segPointLPS
+    );
+
+    // count represents the number of voxels of the dynamic volume that represents
+    // one voxel of the segmentation mask
+    let count = 0;
+    const perFrameSum = new Map();
+
+    // Pre-initialize the Map
+    frames.forEach((frame) => perFrameSum.set(frame, 0));
+
+    const averageCallback = ({ index }) => {
+      for (let i = 0; i < frames.length; i++) {
+        const value = dynamicVolumeScalarDataArray[i][index];
+        const frame = frames[i];
+        perFrameSum.set(frame, perFrameSum.get(frame) + value);
+      }
+      count++;
+    };
+
+    pointInShapeCallback(
+      dynamicVolume.imageData,
+      () => true,
+      averageCallback,
+      overlapIJKMinMax
+    );
+
+    // average the values
+    const averageValues = [];
+    perFrameSum.forEach((sum) => {
+      averageValues.push(sum / count);
+    });
+
+    ijkCoords.push(segPointIJK);
+    values.push(averageValues);
+  };
+
+  // Since we have the non-zero voxel indices of the segmentation mask,
+  // we theoretically can use them, however, we kind of need to compute the
+  // pointLPS for each of the non-zero voxel indices, which is a bit of a pain.
+  // Todo: consider using the nonZeroVoxelIndices to compute the pointLPS
+  pointInShapeCallback(maskImageData, () => true, callback);
+
+  return [values, ijkCoords];
 }
 
 export default getDataInTime;