@cornerstonejs/tools 1.51.5 → 1.53.0

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

@@ -1,4 +1,4 @@
-import { triggerEvent } from '@cornerstonejs/core';
+import { triggerEvent, utilities } from '@cornerstonejs/core';
 import type { Types } from '@cornerstonejs/core';
 import { vec3 } from 'gl-matrix';
 
@@ -9,13 +9,20 @@ import type { InterpolationROIAnnotation } from '../../../types/ToolSpecificAnno
 import type { AnnotationInterpolationCompletedEventDetail } from '../../../types/EventTypes';
 import EventTypes from '../../../enums/Events';
 import * as annotationState from '../../../stateManagement/annotation';
-import { PointsArray } from '../PointsArray';
+import selectHandles from './selectHandles';
+
+const { PointsManager } = utilities;
 
 /**
  * An XYZ encoded points that also includes an indicator I for whether the
  * point is included in the original contour.
  */
-type PointsXYZI = Types.PointsXYZ & {
+export type PointsXYZI = Types.PointsXYZ & {
+  I?: boolean[];
+  kIndex?: number;
+};
+
+export type PointsArray3 = Types.PointsManager<Types.Point3> & {
   I?: boolean[];
 };
 
@@ -25,7 +32,13 @@ let interpolating = false;
 
 /**
  * interpolate - Interpolate missing contours in the ROIContours.
- * If input is tool data collection, it is expected to be sorted in the order of stack image in which it was drawn
+ * If input is tool data collection, it is expected to be sorted in the order
+ * of stack image in which it was drawn.
+ *
+ * This is performed in a microtask in order to avoid delaying the event handler
+ * excessively, but to ensure it is completed before the data is additionally
+ * changed.  It was originally done in a setTimeout, but that allowed the data
+ * to be updated between calls, causing issues with the interpolation process.
  *
  * @param viewportData - Object
  * @returns null
@@ -35,11 +48,24 @@ function interpolate(viewportData: InterpolationViewportData) {
     return;
   }
   interpolating = true;
-  try {
-    startInterpolation(viewportData);
-  } finally {
-    interpolating = false;
-  }
+  const { isInterpolationUpdate, annotation } = viewportData;
+  queueMicrotask(() => {
+    try {
+      if (isInterpolationUpdate) {
+        annotation.isInterpolationUpdate = true;
+        // This may not be true long term, but treat it as user generated for
+        // this run.
+        annotation.autoGenerated = false;
+      }
+      startInterpolation(viewportData);
+    } finally {
+      interpolating = false;
+      if (isInterpolationUpdate) {
+        // Reset the auto generated flag
+        annotation.autoGenerated = true;
+      }
+    }
+  });
 }
 
 /**
@@ -111,6 +137,8 @@ function _linearlyInterpolateBetween(
   );
 
   const { c1Interp, c2Interp } = _generateInterpolationContourPair(c1, c2);
+  c1Interp.kIndex = annotationPair[0];
+  c2Interp.kIndex = annotationPair[1];
 
   // Using the newly constructed contours, interpolate each ROI.
   indices.forEach(function (index) {
@@ -126,6 +154,16 @@ function _linearlyInterpolateBetween(
   });
 }
 
+function getPointCount(pointArray) {
+  let sum = 0;
+  for (let i = 0; i < pointArray.I.length; i++) {
+    if (pointArray.I[i]) {
+      sum++;
+    }
+  }
+  return sum;
+}
+
 /**
  * _linearlyInterpolateContour - Inserts a linearly interpolated contour at
  * specified slice index.
@@ -133,7 +171,7 @@ function _linearlyInterpolateBetween(
  * @param c1Interp - object, The first reference contour.
  * @param c2Interp - object,  The second reference contour.
  * @param sliceIndex - Number, The slice index to interpolate.
- * @param annotationPair - Number[], The slice indicies of the reference contours.
+ * @param annotationPair - Number[], The slice indices of the reference contours.
  * @param interpolationData - object[], Data for the slice location of contours
  *                                  for the ROIContour.
  * @param c1HasMoreNodes - boolean, True if c1 has more nodes than c2.
@@ -162,17 +200,7 @@ function _linearlyInterpolateContour(
     annotationPair[zInterp > 0.5 ? 1 : 0]
   )[0];
 
-  // A bit adhoc figuring out how many handles to use, but this seems to generate
-  // enough handles for use.
-  const handleCount = Math.round(
-    Math.max(
-      8,
-      interpolationData.get(startIndex)[0].data.handles.points.length,
-      interpolationData.get(endIndex)[0].data.handles.points.length,
-      interpolated3DPoints.x.length / 50
-    )
-  );
-  const handlePoints = _subselect(interpolated3DPoints, handleCount);
+  const handlePoints = selectHandles(interpolated3DPoints);
 
   if (interpolationData.has(sliceIndex)) {
     _editInterpolatedContour(
@@ -193,25 +221,6 @@ function _linearlyInterpolateContour(
   }
 }
 
-function _subselect(points, count = 10) {
-  const handles = [];
-  const { length } = points.x;
-  if (!length) {
-    return handles;
-  }
-  for (let i = 0; i < count; i++) {
-    const handleIndex = Math.floor((length * i) / count);
-    handles.push(
-      vec3.fromValues(
-        points.x[handleIndex],
-        points.y[handleIndex],
-        points.z[handleIndex]
-      )
-    );
-  }
-  return handles;
-}
-
 /**
  * _addInterpolatedContour - Adds a new contour to the imageId.
  *
@@ -223,13 +232,13 @@ function _subselect(points, count = 10) {
  * @returns null
  */
 function _addInterpolatedContour(
-  interpolated3DPoints: Types.PointsXYZ,
-  handlePoints: Types.Point3[],
+  interpolated3DPoints: PointsArray3,
+  handlePoints: PointsArray3,
   sliceIndex: number,
   referencedToolData,
   eventData
 ) {
-  const points = PointsArray.fromXYZ(interpolated3DPoints).points;
+  const points = interpolated3DPoints.points;
   const { viewport } = eventData;
 
   const interpolatedAnnotation = createPolylineToolData(
@@ -242,7 +251,7 @@ function _addInterpolatedContour(
   interpolatedAnnotation.metadata.referencedImageId = targetId;
   interpolatedAnnotation.metadata.referencedSliceIndex = sliceIndex;
   annotationState.state.addAnnotation(interpolatedAnnotation, viewport.element);
-  referencedToolData.postInterpolateAction?.(
+  referencedToolData.onInterpolationComplete?.(
     interpolatedAnnotation,
     referencedToolData
   );
@@ -260,8 +269,8 @@ function _addInterpolatedContour(
  * @returns null
  */
 function _editInterpolatedContour(
-  interpolated3DPoints: Types.PointsXYZ,
-  handlePoints: Types.Point3[],
+  interpolated3DPoints: PointsArray3,
+  handlePoints: PointsArray3,
   sliceIndex,
   referencedToolData,
   eventData
@@ -296,7 +305,7 @@ function _editInterpolatedContour(
   }
 
   const oldToolData = annotations[toolDataIndex] as InterpolationROIAnnotation;
-  const points = PointsArray.fromXYZ(interpolated3DPoints).points;
+  const points = interpolated3DPoints.points;
   const interpolatedAnnotation = createPolylineToolData(
     points,
     handlePoints,
@@ -327,22 +336,39 @@ function _generateInterpolatedOpenContour(
   c2ir,
   zInterp,
   c1HasMoreNodes
-): PointsXYZI {
-  const cInterp = {
-    x: [],
-    y: [],
-    z: [],
-  };
-
+): PointsArray3 {
   const indices = c1HasMoreNodes ? c1ir.I : c2ir.I;
 
+  const c1 = PointsManager.fromXYZ(c1ir);
+  const c2 = PointsManager.fromXYZ(c2ir);
+  const { length } = c1;
+  const cInterp = PointsManager.create3(length) as PointsArray3;
+
+  const vecSubtract = vec3.create();
+  const vecResult = vec3.create();
+  const c1Source = PointsManager.create3(length);
+  c1Source.kIndex = c1ir.kIndex;
+  const c2Source = PointsManager.create3(length);
+  c2Source.kIndex = c2ir.kIndex;
+
   for (let i = 0; i < c1ir.x.length; i++) {
     if (indices[i]) {
-      cInterp.x.push(c1ir.x[i] + (c2ir.x[i] - c1ir.x[i]) * zInterp);
-      cInterp.y.push(c1ir.y[i] + (c2ir.y[i] - c1ir.y[i]) * zInterp);
-      cInterp.z.push(c1ir.z[i] + (c2ir.z[i] - c1ir.z[i]) * zInterp);
+      const c1point = c1.getPoint(i);
+      const c2point = c2.getPoint(i);
+      c1Source.push(c1point);
+      c2Source.push(c2point);
+      vec3.sub(vecSubtract, c2point, c1point);
+      cInterp.push(
+        vec3.scaleAndAdd(
+          vecResult,
+          c1point,
+          vecSubtract,
+          zInterp
+        ) as Types.Point3
+      );
     }
   }
+  cInterp.sources = [c1Source, c2Source];
 
   return cInterp;
 }
@@ -370,12 +396,12 @@ function _generateInterpolationContourPair(c1, c2) {
   const numNodes1 = interpNodes + c2.x.length;
   const numNodes2 = interpNodes + c1.x.length;
 
-  // concatinate p && cumPerimNorm
+  // concatenate p && cumPerimNorm
   const perim1Interp = _getInterpolatedPerim(numNodes1, cumPerim1Norm);
   const perim2Interp = _getInterpolatedPerim(numNodes2, cumPerim2Norm);
 
-  const perim1Ind = _getIndicatorArray(c1, numNodes1);
-  const perim2Ind = _getIndicatorArray(c2, numNodes2);
+  const perim1Ind = _getIndicatorArray(numNodes1 - 2, c1.x.length);
+  const perim2Ind = _getIndicatorArray(numNodes2 - 2, c2.x.length);
 
   const nodesPerSegment1 = _getNodesPerSegment(perim1Interp, perim1Ind);
   const nodesPerSegment2 = _getNodesPerSegment(perim2Interp, perim2Ind);
@@ -398,13 +424,13 @@ function _generateInterpolationContourPair(c1, c2) {
  * @returns  An object containing the two reduced contours.
  */
 function _reduceContoursToOriginNodes(c1i: PointsXYZI, c2i: PointsXYZI) {
-  const c1Interp = {
+  const c1Interp: PointsXYZI = {
     x: [],
     y: [],
     z: [],
     I: [],
   };
-  const c2Interp = {
+  const c2Interp: PointsXYZI = {
     x: [],
     y: [],
     z: [],
@@ -505,7 +531,7 @@ function _shiftCircularArray(arr, count) {
  *                                    per line segment.
  * @returns object, The super sampled contour.
  */
-function _getSuperSampledContour(c, nodesPerSegment) {
+function _getSuperSampledContour(c, nodesPerSegment): PointsXYZI {
   const ci = {
     x: [],
     y: [],
@@ -593,17 +619,10 @@ function _getNodesPerSegment(perimInterp, perimInd) {
  * @param numNodes - Number, The number of nodes added.
  * @returns boolean[], The indicator array of original node locations.
  */
-function _getIndicatorArray(contour, numNodes) {
-  const perimInd = [];
-
-  for (let i = 0; i < numNodes - 2; i++) {
-    perimInd.push(false);
-  }
-
-  for (let i = 0; i < contour.x.length; i++) {
-    perimInd.push(true);
-  }
-
+function _getIndicatorArray(numFalse, numTrue) {
+  const perimInd = new Array(numFalse + numTrue);
+  perimInd.fill(false, 0, numFalse);
+  perimInd.fill(true, numFalse, numFalse + numTrue);
   return perimInd;
 }
 
@@ -619,7 +638,7 @@ function _getInterpolatedPerim(numNodes, cumPerimNorm) {
   const diff = 1 / (numNodes - 1);
   const linspace = [diff];
 
-  // Length - 2 as we are discarding 0 an 1 for efficiency (no need to calculate them).
+  // Length - 2 as we are discarding 0 and 1 for efficiency (no need to calculate them).
   for (let i = 1; i < numNodes - 2; i++) {
     linspace.push(linspace[linspace.length - 1] + diff);
   }

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

@@ -0,0 +1,240 @@
+import { vec3 } from 'gl-matrix';
+import { utilities } from '@cornerstonejs/core';
+import type { PointsArray3 } from './interpolate';
+import { add } from '@kitware/vtk.js/Common/Core/Math';
+
+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 = 8
+): PointsArray3 {
+  const handles = PointsManager.create3(handleCount) as PointsArray3;
+  handles.sources = [];
+  const { sources: destPoints } = handles;
+  const { length, sources: sourcePoints = [] } = polyline;
+  const distance = 6;
+  if (length < distance * 3) {
+    console.log('Adding subselect handles', handleCount, length);
+    return polyline.subselect(handleCount);
+  }
+  const interval = Math.min(30, Math.floor(length / 3));
+  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) {
+    // TODO - create handleCount evenly spaced handles
+    return [0, Math.floor(length / 3), Math.floor((length * 2) / 3)];
+  }
+
+  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/updateContourPolyline.ts

@@ -0,0 +1,74 @@
+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
+ */
+export default function updateContourPolyline(
+  annotation: ContourAnnotation,
+  polylineData: {
+    points: Types.Point2[];
+    closed?: boolean;
+    targetWindingDirection?: ContourWindingDirection;
+  },
+  transforms: {
+    canvasToWorld: (point: Types.Point2) => Types.Point3;
+  }
+) {
+  const { canvasToWorld } = transforms;
+  const { data } = annotation;
+  const { points: polyline, targetWindingDirection } = polylineData;
+  let { closed } = polylineData;
+  const numPoints = polyline.length;
+  const polylineWorldPoints = new Array(numPoints);
+  const currentWindingDirection = 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 = currentWindingDirection;
+  } else if (windingDirection !== currentWindingDirection) {
+    polyline.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);
+}