@cornerstonejs/tools 1.40.3 → 1.42.0

package/src/utilities/getCalibratedUnits.ts

@@ -1,12 +1,31 @@
-import { Enums } from '@cornerstonejs/core';
+import { Enums, utilities } from '@cornerstonejs/core';
 
 const { CalibrationTypes } = Enums;
 const PIXEL_UNITS = 'px';
 
+const SUPPORTED_REGION_DATA_TYPES = [
+  1, // Tissue
+];
+
+const SUPPORTED_LENGTH_VARIANT = [
+  '3,3', // x: cm  &  y:cm
+];
+
+const SUPPORTED_PROBE_VARIANT = [
+  '4,3', // x: seconds  &  y : cm
+];
+
+const UNIT_MAPPING = {
+  3: 'cm',
+  4: 'seconds',
+};
+
+const EPS = 1e-3;
+
 /**
  * Extracts the length units and the type of calibration for those units
  * into the response.  The length units will typically be either mm or px
- * while the calibration type can be any of a number of different calibraiton types.
+ * while the calibration type can be any of a number of different calibration types.
  *
  * Volumetric images have no calibration type, so are just the raw mm.
  *
@@ -23,14 +42,16 @@ const getCalibratedLengthUnits = (handles, image): string => {
   const { calibration, hasPixelSpacing } = image;
   // Anachronistic - moving to using calibration consistently, but not completed yet
   const units = hasPixelSpacing ? 'mm' : PIXEL_UNITS;
-  if (!calibration || !calibration.type) {
+  if (
+    !calibration ||
+    (!calibration.type && !calibration.sequenceOfUltrasoundRegions)
+  ) {
     return units;
   }
   if (calibration.type === CalibrationTypes.UNCALIBRATED) {
     return PIXEL_UNITS;
   }
-  // TODO - handle US regions properly
-  if (calibration.SequenceOfUltrasoundRegions) {
+  if (calibration.sequenceOfUltrasoundRegions) {
     return 'US Region';
   }
   return `${units} ${calibration.type}`;
@@ -46,7 +67,7 @@ const getCalibratedAreaUnits = (handles, image): string => {
   if (!calibration || !calibration.type) {
     return units;
   }
-  if (calibration.SequenceOfUltrasoundRegions) {
+  if (calibration.sequenceOfUltrasoundRegions) {
     return 'US Region';
   }
   return `${units} ${calibration.type}`;
@@ -56,7 +77,180 @@ const getCalibratedAreaUnits = (handles, image): string => {
  * Gets the scale divisor for converting from internal spacing to
  * image spacing for calibrated images.
  */
-const getCalibratedScale = (image) => image.calibration?.scale || 1;
+const getCalibratedScale = (image, handles = []) => {
+  if (image.calibration?.sequenceOfUltrasoundRegions) {
+    // image.spacing / image.us.space
+  } else if (image.calibration?.scale) {
+    return image.calibration.scale;
+  } else {
+    return 1;
+  }
+};
+
+/**
+ * Extracts the calibrated length units, area units, and the scale
+ * for converting from internal spacing to image spacing.
+ *
+ * @param handles - to detect if spacing information is different between points
+ * @param image - to extract the calibration from
+ * @returns Object containing the units, area units, and scale
+ */
+const getCalibratedLengthUnitsAndScale = (image, handles) => {
+  const [imageIndex1, imageIndex2] = handles;
+  const { calibration, hasPixelSpacing } = image;
+  let units = hasPixelSpacing ? 'mm' : PIXEL_UNITS;
+  const areaUnits = units + SQUARE;
+  let scale = 1;
+  let calibrationType = '';
+
+  if (
+    !calibration ||
+    (!calibration.type && !calibration.sequenceOfUltrasoundRegions)
+  ) {
+    return { units, areaUnits, scale };
+  }
+
+  if (calibration.type === CalibrationTypes.UNCALIBRATED) {
+    return { units: PIXEL_UNITS, areaUnits: PIXEL_UNITS + SQUARE, scale };
+  }
+
+  if (calibration.sequenceOfUltrasoundRegions) {
+    let regions = calibration.sequenceOfUltrasoundRegions.filter(
+      (region) =>
+        imageIndex1[0] >= region.regionLocationMinX0 &&
+        imageIndex1[0] <= region.regionLocationMaxX1 &&
+        imageIndex1[1] >= region.regionLocationMinY0 &&
+        imageIndex1[1] <= region.regionLocationMaxY1 &&
+        imageIndex2[0] >= region.regionLocationMinX0 &&
+        imageIndex2[0] <= region.regionLocationMaxX1 &&
+        imageIndex2[1] >= region.regionLocationMinY0 &&
+        imageIndex2[1] <= region.regionLocationMaxY1
+    );
+
+    // If we are not in a region at all we should show the underlying calibration
+    // which might be the mm spacing for the image
+    if (!regions?.length) {
+      return { units, areaUnits, scale };
+    }
+
+    // if we are in a region then it is the question of whether we support it
+    // or not. If we do not support it we should show px
+
+    regions = regions.filter(
+      (region) =>
+        SUPPORTED_REGION_DATA_TYPES.includes(region.regionDataType) &&
+        SUPPORTED_LENGTH_VARIANT.includes(
+          `${region.physicalUnitXDirection},${region.physicalUnitYDirection}`
+        )
+    );
+
+    if (!regions.length) {
+      return { units: PIXEL_UNITS, areaUnits: PIXEL_UNITS + SQUARE, scale };
+    }
+
+    // Todo: expand on this logic
+    const region = regions[0];
+
+    const physicalDeltaX = Math.abs(region.physicalDeltaX);
+    const physicalDeltaY = Math.abs(region.physicalDeltaY);
+
+    // if we are in a supported region then we should check if the
+    // physicalDeltaX and physicalDeltaY are the same. If they are not
+    // then we should show px again, but if they are the same then we should
+    // show the units
+    const isSamePhysicalDelta = utilities.isEqual(
+      physicalDeltaX,
+      physicalDeltaY,
+      EPS
+    );
+
+    if (isSamePhysicalDelta) {
+      scale = 1 / (physicalDeltaX * physicalDeltaY * 100);
+      calibrationType = 'US Region';
+      units = 'mm';
+    } else {
+      return { units: PIXEL_UNITS, areaUnits: PIXEL_UNITS + SQUARE, scale };
+    }
+  } else if (calibration.scale) {
+    scale = calibration.scale;
+  }
+
+  return {
+    units: units + (calibrationType ? ` ${calibrationType}` : ''),
+    areaUnits: areaUnits + (calibrationType ? ` ${calibrationType}` : ''),
+    scale,
+  };
+};
+
+const getCalibratedProbeUnitsAndValue = (image, handles) => {
+  const [imageIndex] = handles;
+  const { calibration } = image;
+  let units = ['raw'];
+  let values = [null];
+  let calibrationType = '';
+
+  if (
+    !calibration ||
+    (!calibration.type && !calibration.sequenceOfUltrasoundRegions)
+  ) {
+    return { units, values };
+    // Todo: add support for other scenarios
+  }
+
+  if (calibration.sequenceOfUltrasoundRegions) {
+    // for Probe tool
+    const supportedRegionsMetadata =
+      calibration.sequenceOfUltrasoundRegions.filter(
+        (region) =>
+          SUPPORTED_REGION_DATA_TYPES.includes(region.regionDataType) &&
+          SUPPORTED_PROBE_VARIANT.includes(
+            `${region.physicalUnitXDirection},${region.physicalUnitYDirection}`
+          )
+      );
+
+    if (!supportedRegionsMetadata?.length) {
+      return { units, values };
+    }
+
+    const region = supportedRegionsMetadata.find(
+      (region) =>
+        imageIndex[0] >= region.regionLocationMinX0 &&
+        imageIndex[0] <= region.regionLocationMaxX1 &&
+        imageIndex[1] >= region.regionLocationMinY0 &&
+        imageIndex[1] <= region.regionLocationMaxY1
+    );
+
+    if (!region) {
+      return { units, values };
+    }
+
+    // Todo: I think this is a ok assumption for now that if the referencePixelX0 and referencePixelY0
+    // are not defined, then we can assume 0 for them
+    const { referencePixelX0 = 0, referencePixelY0 = 0 } = region;
+    const { physicalDeltaX, physicalDeltaY } = region;
+
+    const yValue =
+      (imageIndex[1] - region.regionLocationMinY0 - referencePixelY0) *
+      physicalDeltaY;
+
+    const xValue =
+      (imageIndex[0] - region.regionLocationMinX0 - referencePixelX0) *
+      physicalDeltaX;
+
+    calibrationType = 'US Region';
+    values = [xValue, yValue];
+    units = [
+      UNIT_MAPPING[region.physicalUnitXDirection],
+      UNIT_MAPPING[region.physicalUnitYDirection],
+    ];
+  }
+
+  return {
+    units,
+    values,
+    calibrationType,
+  };
+};
 
 /** Gets the aspect ratio of the screen display relative to the image
  * display in order to square up measurement values.
@@ -71,6 +265,8 @@ export default getCalibratedLengthUnits;
 export {
   getCalibratedAreaUnits,
   getCalibratedLengthUnits,
+  getCalibratedLengthUnitsAndScale,
   getCalibratedScale,
   getCalibratedAspect,
+  getCalibratedProbeUnitsAndValue,
 };

package/src/utilities/index.ts

@@ -26,6 +26,7 @@ import { pointToString } from './pointToString';
 import annotationFrameRange from './annotationFrameRange';
 
 // name spaces
+import * as contours from './contours';
 import * as segmentation from './segmentation';
 import * as drawing from './drawing';
 import * as math from './math';
@@ -63,6 +64,7 @@ export {
   getCalibratedAreaUnits,
   getCalibratedScale,
   segmentation,
+  contours,
   triggerAnnotationRenderForViewportIds,
   triggerAnnotationRender,
   pointInShapeCallback,

package/src/utilities/segmentation/contourAndFindLargestBidirectional.ts

@@ -0,0 +1,46 @@
+import { generateContourSetsFromLabelmap } from '../contours';
+import SegmentationRepresentations from '../../enums/SegmentationRepresentations';
+import findLargestBidirectional from './findLargestBidirectional';
+
+const EPSILON = 1e-2;
+const { Labelmap } = SegmentationRepresentations;
+
+/**
+ * Generates a contour object over the segment, and then uses the contouring to
+ * find the largest bidirectional object that can be applied within the acquisition
+ * plane that is within the segment index, or the contained segment indices.
+ *
+ * @param segmentation.segments - a list of segments to apply the contour to.
+ * @param segmentation.segments.containedSegmentIndices - a set of segment indexes equivalent to the primary segment
+ * @param segmentation.segments.label - the label for the segment
+ * @param segmentation.segments.color - the color to use for the segment label
+ */
+export default function contourAndFindLargestBidirectional(segmentation) {
+  const contours = generateContourSetsFromLabelmap({
+    segmentations: segmentation,
+  });
+
+  if (!contours?.length || !contours[0].sliceContours.length) {
+    return;
+  }
+
+  const {
+    representationData,
+    segments = [
+      null,
+      { label: 'Unspecified', color: null, containedSegmentIndices: null },
+    ],
+  } = segmentation;
+  const { volumeId: segVolumeId } = representationData[Labelmap];
+
+  const segmentIndex = segments.findIndex((it) => !!it);
+  if (segmentIndex === -1) {
+    return;
+  }
+  segments[segmentIndex].segmentIndex = segmentIndex;
+  return findLargestBidirectional(
+    contours[0],
+    segVolumeId,
+    segments[segmentIndex]
+  );
+}

package/src/utilities/segmentation/createBidirectionalToolData.ts

@@ -0,0 +1,68 @@
+import type { Types } from '@cornerstonejs/core';
+import type { Annotation } from '../../types/AnnotationTypes';
+
+export type BidirectionalData = {
+  majorAxis: [Types.Point3, Types.Point3];
+  minorAxis: [Types.Point3, Types.Point3];
+  maxMajor: number;
+  maxMinor: number;
+  segmentIndex: number;
+  label?: string;
+  color?: string | number[];
+  referencedImageId: string;
+  FrameOfReferenceUID: string;
+};
+
+/**
+ * Creates data suitable for the BidirectionalTool from the basic bidirectional
+ * data object.
+ */
+export default function createBidirectionalToolData(
+  bidirectionalData: BidirectionalData,
+  viewport
+): Annotation {
+  const {
+    majorAxis,
+    minorAxis,
+    label = '',
+    FrameOfReferenceUID,
+    referencedImageId,
+  } = bidirectionalData;
+  const [major0, major1] = majorAxis;
+  const [minor0, minor1] = minorAxis;
+
+  const { viewUp, viewPlaneNormal } = viewport.getCamera();
+  const points = [major0, major1, minor0, minor1];
+  const bidirectionalToolData = {
+    highlighted: true,
+    invalidated: true,
+    metadata: {
+      toolName: 'Bidirectional',
+      viewPlaneNormal,
+      viewUp,
+      FrameOfReferenceUID,
+      referencedImageId,
+    },
+    data: {
+      handles: {
+        points,
+        textBox: {
+          hasMoved: false,
+          worldPosition: [0, 0, 0] as Types.Point3,
+          worldBoundingBox: {
+            topLeft: [0, 0, 0] as Types.Point3,
+            topRight: [0, 0, 0] as Types.Point3,
+            bottomLeft: [0, 0, 0] as Types.Point3,
+            bottomRight: [0, 0, 0] as Types.Point3,
+          },
+        },
+        activeHandleIndex: null,
+      },
+      label,
+      cachedStats: {},
+    },
+    isLocked: false,
+    isVisible: true,
+  };
+  return bidirectionalToolData;
+}

package/src/utilities/segmentation/findLargestBidirectional.ts

@@ -0,0 +1,159 @@
+import { vec3 } from 'gl-matrix';
+
+import { createIsInSegment, isLineInSegment } from './isLineInSegment';
+import type { BidirectionalData } from './createBidirectionalToolData';
+
+const EPSILON = 1e-2;
+
+/**
+ * Search in the contours for the given segment to find the largest bidirectional
+ * that will fit entirely within the slice contours inside the contours object.
+ * Assumptions/implementation details:
+ *
+ *   1. The major and minor bidirectional lines must not cross the contour
+ *   2. The center point for both major and minor bidirectional lines must be
+ *      within the segment, or the contained segment index.
+ *   3. The major/minor axis must be orthogonal
+ *
+ * Note this does NOT test that the major/minor axis intersect.  Normally they will, but
+ * it isn't a hard requirement.
+ *
+ * The way that islands within the contours are handled is to allow the island to be
+ * coloured with something that is contained - that way both open and closed islands
+ * can be handled correctly for finding the bidirectional  (an open island is a section
+ * inside the segment that is open to the outside - this can happen at bone endpoints or when
+ * one region flows into another)
+ */
+export default function findLargestBidirectional(
+  contours,
+  segVolumeId: string,
+  segment
+) {
+  const { sliceContours } = contours;
+  const { segmentIndex, containedSegmentIndices } = segment;
+  let maxBidirectional;
+  const isInSegment = createIsInSegment(
+    segVolumeId,
+    segmentIndex,
+    containedSegmentIndices
+  );
+  for (const sliceContour of sliceContours) {
+    const bidirectional = createBidirectionalForSlice(
+      sliceContour,
+      isInSegment,
+      maxBidirectional
+    );
+    if (!bidirectional) {
+      continue;
+    }
+    maxBidirectional = bidirectional;
+  }
+  if (maxBidirectional) {
+    Object.assign(maxBidirectional, segment);
+  }
+  return maxBidirectional;
+}
+
+/**
+ * This function creates a bidirectional data object for the given slice and
+ * slice contour, only when the major distance is larger than currentMax, or
+ * equal to current max and the minor is larger than currentMax's minor.
+ * It does this by looking at every pair of distances in sliceCountour to find
+ * those larger than the currentMax, and then finds the minor distance for those
+ * major distances.
+ *
+ */
+function createBidirectionalForSlice(
+  sliceContour,
+  isInSegment,
+  currentMax = { maxMajor: 0, maxMinor: 0 }
+) {
+  const { points } = sliceContour.polyData;
+  const { maxMinor: currentMaxMinor, maxMajor: currentMaxMajor } = currentMax;
+  let maxMajor = currentMaxMajor * currentMaxMajor;
+  let maxMinor = currentMaxMinor * currentMaxMinor;
+  let maxMajorPoints;
+  for (let index1 = 0; index1 < points.length; index1++) {
+    for (let index2 = index1 + 1; index2 < points.length; index2++) {
+      const point1 = points[index1];
+      const point2 = points[index2];
+      const distance2 = vec3.sqrDist(point1, point2);
+      if (distance2 < maxMajor) {
+        continue;
+      }
+      if (distance2 - EPSILON < maxMajor + EPSILON && maxMajorPoints) {
+        // Consider adding to the set of points rather than continuing here
+        // so that all minor axis can be tested
+        continue;
+      }
+      if (!isInSegment.testCenter(point1, point2)) {
+        // Center between the two points has to be in the segment, otherwise
+        // this is out of bounds.
+        continue;
+      }
+      if (!isLineInSegment(point1, point2, isInSegment)) {
+        // If the line intersects the segment boundary, then skip it
+        continue;
+      }
+      maxMajor = distance2 - EPSILON;
+      maxMajorPoints = [index1, index2];
+      maxMinor = 0;
+    }
+  }
+  if (!maxMajorPoints) {
+    return;
+  }
+
+  maxMajor = Math.sqrt(maxMajor + EPSILON);
+  const handle0 = points[maxMajorPoints[0]];
+  const handle1 = points[maxMajorPoints[1]];
+  const unitMajor = vec3.sub(vec3.create(), handle0, handle1);
+  vec3.scale(unitMajor, unitMajor, 1 / maxMajor);
+
+  let maxMinorPoints;
+
+  for (let index1 = 0; index1 < points.length; index1++) {
+    for (let index2 = index1 + 1; index2 < points.length; index2++) {
+      const point1 = points[index1];
+      const point2 = points[index2];
+      const distance2 = vec3.sqrDist(point1, point2);
+      if (distance2 <= maxMinor) {
+        continue;
+      }
+      const delta = vec3.sub(vec3.create(), point1, point2);
+
+      const dot = Math.abs(vec3.dot(delta, unitMajor)) / Math.sqrt(distance2);
+      if (dot > EPSILON) {
+        continue;
+      }
+
+      if (!isInSegment.testCenter(point1, point2)) {
+        // Center between the two points has to be in the segment, otherwise
+        // this is out of bounds.
+        continue;
+      }
+      if (!isLineInSegment(point1, point2, isInSegment)) {
+        continue;
+      }
+      maxMinor = distance2;
+      maxMinorPoints = [index1, index2];
+    }
+  }
+
+  if (!maxMinorPoints) {
+    // Didn't find a larger minor distance
+    return;
+  }
+  maxMinor = Math.sqrt(maxMinor);
+  const handle2 = points[maxMinorPoints[0]];
+  const handle3 = points[maxMinorPoints[1]];
+
+  const bidirectional = {
+    majorAxis: [handle0, handle1],
+    minorAxis: [handle2, handle3],
+    maxMajor,
+    maxMinor,
+    ...sliceContour,
+  } as BidirectionalData;
+  return bidirectional;
+}

package/src/utilities/segmentation/index.ts

@@ -15,6 +15,9 @@ import {
   setBrushThresholdForToolGroup,
 } from './brushThresholdForToolGroup';
 import thresholdSegmentationByRange from './thresholdSegmentationByRange';
+import contourAndFindLargestBidirectional from './contourAndFindLargestBidirectional';
+import createBidirectionalToolData from './createBidirectionalToolData';
+import segmentContourAction from './segmentContourAction';
 
 export {
   thresholdVolumeByRange,
@@ -30,4 +33,7 @@ export {
   getBrushThresholdForToolGroup,
   setBrushThresholdForToolGroup,
   thresholdSegmentationByRange,
+  contourAndFindLargestBidirectional,
+  createBidirectionalToolData,
+  segmentContourAction,
 };

package/src/utilities/segmentation/isLineInSegment.ts

@@ -0,0 +1,84 @@
+import type { Types } from '@cornerstonejs/core';
+import { cache } from '@cornerstonejs/core';
+import { vec3 } from 'gl-matrix';
+
+/**
+ * Determines if there is a point between point1 and point2 which is not
+ * contained in the segmentation
+ */
+export default function isLineInSegment(
+  point1: Types.Point3,
+  point2: Types.Point3,
+  isInSegment
+) {
+  const ijk1 = isInSegment.toIJK(point1);
+  const ijk2 = isInSegment.toIJK(point2);
+  const testPoint = vec3.create();
+  const { testIJK } = isInSegment;
+  const delta = vec3.sub(vec3.create(), ijk1, ijk2);
+
+  // Test once for index value between the two points, so the max of the
+  // difference in IJK values
+  const testSize = Math.round(Math.max(...delta.map(Math.abs)));
+  if (testSize < 2) {
+    // No need to test when there are only two points
+    return true;
+  }
+  const unitDelta = vec3.scale(vec3.create(), delta, 1 / testSize);
+
+  for (let i = 1; i < testSize; i++) {
+    vec3.scaleAndAdd(testPoint, ijk2, unitDelta, i);
+    if (!testIJK(testPoint)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Creates a function that tests to see if the provided line segment, specified
+ * in LPS space (as endpoints) is contained in the segment
+ */
+function createIsInSegment(
+  segVolumeId: string,
+  segmentIndex: number,
+  containedSegmentIndices?: Set<number>
+) {
+  // Get segmentation volume
+  const vol = cache.getVolume(segVolumeId);
+  if (!vol) {
+    console.warn(`No volume found for ${segVolumeId}`);
+    return;
+  }
+
+  const segData = vol.imageData.getPointData().getScalars().getData();
+  const width = vol.dimensions[0];
+  const pixelsPerSlice = width * vol.dimensions[1];
+
+  return {
+    /**
+     * Find the center point between point1 and point2, convert it to IJK space
+     * and test if the value at that location is in the segment
+     */
+    testCenter: (point1, point2) => {
+      const point = vec3.add(vec3.create(), point1, point2).map((it) => it / 2);
+      const ijk = vol.imageData.worldToIndex(point as vec3).map(Math.round);
+      const [i, j, k] = ijk;
+      const index = i + j * width + k * pixelsPerSlice;
+      const value = segData[index];
+      return value === segmentIndex || containedSegmentIndices?.has(value);
+    },
+
+    toIJK: (point) => vol.imageData.worldToIndex(point as vec3),
+
+    testIJK: (ijk) => {
+      const [i, j, k] = ijk;
+      const index =
+        Math.round(i) + Math.round(j) * width + Math.round(k) * pixelsPerSlice;
+      const value = segData[index];
+      return value === segmentIndex || containedSegmentIndices?.has(value);
+    },
+  };
+}
+
+export { createIsInSegment, isLineInSegment };