@bettermedicine/imeasure 0.0.5 → 0.0.7-0

package/README.md

@@ -10,10 +10,15 @@ Better Medicine's iMeasure API.
     - [Cropping](#cropping)
       - [Cropping region calulation](#cropping-region-calulation)
       - [Executing the crop](#executing-the-crop)
+        - [Working with data from GPU texture buffers](#working-with-data-from-gpu-texture-buffers)
+        - [Image data bit depth](#image-data-bit-depth)
       - [Affines](#affines)
     - [World metadata](#world-metadata)
     - [Composing the request payload](#composing-the-request-payload)
 
+You can find the primary documentation site at [https://docs.imeasure.bettermedicine.ai](https://docs.imeasure.bettermedicine.ai).
+Module references mentioned in this document can be located under the `@bettermedicine/namespaces` sidebar route.
+
 ## Installation
 
 ```bash
@@ -89,7 +94,15 @@ const {
 } = imageCrop;
 ```
 
-Note: in modern versions of Cornerstone 3D, the image volume's voxel data only exists in the GPU texture buffer.
+> :bulb: **Note**: In case the measurement we're generating the crop region around is near the edge of the volume or in case the measurement
+> is long enough, the crop region may extend beyond the volume's boundaries. In such cases, the consumer is expected to provide a non-cuboid input
+> volume but still preserve metadata about the originally intended crop region. The utilities provided in the cropping module will handle this
+> case automatically by supplying `cropBoundariesUnclippedVoxel` and `cropCuboidCenterVoxel` corresponding to the original crop region, while the
+> `cropBoundariesVoxel`, `cropBoundariesWorld` and `shape` attributes in `TCropMetadata` will be adjusted to the actual effective cropped region.
+
+##### Working with data from GPU texture buffers
+
+In modern versions of Cornerstone 3D, unless forced by configuration, the image volume's voxel data only exists in the GPU texture buffer.
 If the above function outputs empty `voxelValues`, we need to take a few additional steps to ensure the data is reachable by our code:
 
 ```ts
@@ -183,6 +196,24 @@ function getVTKImageData(cornerstoneVolumeID: VolumeID): vtkImageData {
 }
 ```
 
+##### Image data bit depth
+
+DICOM CT HU values typically fit within the range allowance of a 16-bit signed integer. As such, this is what the iMeasure API expects
+as the scalar data type. Unless you're forcing 16-bit textures via OHIF config, the scalar data may be of the `Float32Array` type.
+You can slash the converted `vtkImageData` object's memory footprint by half by using our `formatting.float32ArrayToInt16Array`
+utility inlined into the above `vtkDataArray` instantiation:
+
+```ts
+import { formatting } from '@bettermedicine/imeasure';
+
+const da = vtkDataArray.newInstance({
+    ...
+    values: formatting.float32ArrayToInt16Array(
+        baseVolume.voxelManager.getCompleteScalarDataArray()
+    ),
+});
+```
+
 #### Affines
 
 In order to accurately calculate the crop region, we need some more information about the the shape, orientation, origin and spacing of the series' world coordinate system. The standard way to express this is through an affine transformation matrix - a 4x4 matrix that describes how to transform points from the voxel coordinate system to the world coordinate system.
@@ -238,8 +269,7 @@ const voxelPoint = math.affines.affineTranslateVec3(worldPoint, worldToVoxelMatr
 
 ### World metadata
 
-TODO: A brief explanation of which world metadata we require for the request and how to derive it. For now,
-please refer to the IO module's documentation for the `IStaticIMeasurePayload` type.
+Please refer to the IO module's documentation for the `IStaticIMeasurePayload` type.
 
 ### Composing the request payload
 
@@ -251,6 +281,7 @@ const worldMetadata = ...
 const cropMetadata = ...
 const clicks = ...
 const id = uuidv4();
+// note: this should be an Int16Array - see the bit depth section above.
 const imageVoxelValues = ... // the flattened array of voxel values from the cropped region
 
 const requestPayload = formatting.formatStaticPayload(
@@ -267,7 +298,8 @@ const requestPayload = formatting.formatStaticPayload(
 const resp = await fetch('https://api.bettermedicine.com/imeasure', {
     method: 'POST',
     body: requestPayload,
-    // note: setting headers manually here is not recommended as Fetch should handle it correctly automatically.
+    // note: setting content-type headers manually here is not recommended as `fetch`
+    // should handle it correctly automatically.
 });
 
 const responseData = await resp.json();

package/dist/math/cropping.js

@@ -1,23 +1,33 @@
 import { affineTranslateVec3, invertAffineMatrix } from "./affines";
 import { INTERACTIVE_IMEASURE_BASE } from "../constants";
-import { calculateZAxisLength, roundPoint3 } from "./utility";
+import { roundPoint3 } from "./utility";
+const worldLengthAndAffineToCropCuboidDimensions = (worldLength, worldToVoxelAffine) => {
+    const voxelToWorldAffine = invertAffineMatrix(worldToVoxelAffine);
+    // we effectively need to make the length of the measurement fit the crop region
+    // in all 3 dimensions.
+    const pixelSpacing = voxelToWorldAffine[0];
+    const sliceThickness = voxelToWorldAffine[10];
+    // calculate the length in voxel space
+    let xyLength = Math.max(INTERACTIVE_IMEASURE_BASE.X, Math.round(worldLength / pixelSpacing) +
+        INTERACTIVE_IMEASURE_BASE.PADDING * 2);
+    if (xyLength % 2 !== 0) {
+        xyLength += 1; // ensure even number
+    }
+    let zLength = Math.max(INTERACTIVE_IMEASURE_BASE.Z, Math.round((xyLength * pixelSpacing) / sliceThickness));
+    if (zLength % 2 !== 0) {
+        zLength += 1; // ensure even number
+    }
+    return [xyLength, xyLength, zLength];
+};
 // TODO: should expand scale based on z-axis input point diff.
 // Tests first.
 export const getInteractiveImeasureCropCuboidDimensions = (measurement, worldToVoxelAffine) => {
-    const [voxelStart, voxelEnd] = measurement.map((pt) => roundPoint3(affineTranslateVec3(pt, worldToVoxelAffine)));
-    const x_size = Math.abs(voxelStart[0] - voxelEnd[0]) +
-        INTERACTIVE_IMEASURE_BASE.PADDING * 2;
-    const y_size = Math.abs(voxelStart[1] - voxelEnd[1]) +
-        INTERACTIVE_IMEASURE_BASE.PADDING * 2;
-    let xyCubeSize = Math.max(x_size, y_size, INTERACTIVE_IMEASURE_BASE.X);
-    // the model always expects an even number of voxels on each axis
-    if (xyCubeSize % 2 !== 0) {
-        xyCubeSize += 1;
-    }
-    const voxelToWorldAffine = invertAffineMatrix(worldToVoxelAffine);
-    const maxDistanceBetweenPoints = Math.max(x_size, y_size);
-    const zLength = calculateZAxisLength(maxDistanceBetweenPoints, voxelToWorldAffine);
-    return [xyCubeSize, xyCubeSize, zLength];
+    const [worldStart, worldEnd] = measurement;
+    // calculate the world-space length of the measurement
+    const worldLength = Math.sqrt(Math.pow(worldEnd[0] - worldStart[0], 2) +
+        Math.pow(worldEnd[1] - worldStart[1], 2) +
+        Math.pow(worldEnd[2] - worldStart[2], 2));
+    return worldLengthAndAffineToCropCuboidDimensions(worldLength, worldToVoxelAffine);
 };
 const getCropCuboidFromCenterAndEdgeLengths = (voxelSpaceCenter, edgeLengths) => {
     const minCropCoordinates = [
@@ -47,6 +57,7 @@ const getCropCuboidFromCenterAndEdgeLengths = (voxelSpaceCenter, edgeLengths) =>
 export const calculateInteractiveImeasureCropRegion = (worldBasePoints, voxelToWorldAffine) => {
     let center;
     const singlePoint = worldBasePoints.length === 1;
+    let worldBaseLength = 0;
     if (singlePoint) {
         center = worldBasePoints[0];
     }
@@ -56,19 +67,15 @@ export const calculateInteractiveImeasureCropRegion = (worldBasePoints, voxelToW
             (worldBasePoints[0][1] + worldBasePoints[1][1]) / 2,
             (worldBasePoints[0][2] + worldBasePoints[1][2]) / 2,
         ];
+        worldBaseLength = Math.sqrt(Math.pow(worldBasePoints[1][0] - worldBasePoints[0][0], 2) +
+            Math.pow(worldBasePoints[1][1] - worldBasePoints[0][1], 2) +
+            Math.pow(worldBasePoints[1][2] - worldBasePoints[0][2], 2));
     }
     // we want to convert (and round) this to voxel coordinates
     const worldToVoxelAffine = invertAffineMatrix(voxelToWorldAffine);
     const voxelSpaceCenter = roundPoint3(affineTranslateVec3(center, worldToVoxelAffine));
     // if we only have a single click, use constants for edge lengths.
-    let x_edge = INTERACTIVE_IMEASURE_BASE.X;
-    let y_edge = INTERACTIVE_IMEASURE_BASE.Y;
-    let z_edge = INTERACTIVE_IMEASURE_BASE.Z;
-    if (!singlePoint) {
-        // if we have two clicks, calculate the edges based on the points
-        const tempProposedCuboidEdges = getInteractiveImeasureCropCuboidDimensions(worldBasePoints, worldToVoxelAffine);
-        [x_edge, y_edge, z_edge] = tempProposedCuboidEdges;
-    }
+    const [x_edge, y_edge, z_edge] = worldLengthAndAffineToCropCuboidDimensions(worldBaseLength, worldToVoxelAffine);
     const { cropCubePoints, croppingPlanes } = getCropCuboidFromCenterAndEdgeLengths(voxelSpaceCenter, {
         x: x_edge,
         y: y_edge,
@@ -95,17 +102,17 @@ export const calculateInteractiveImeasureCropRegion = (worldBasePoints, voxelToW
  * The function maintains the center and cropping planes, and updates edge lengths if necessary.
  */
 export const calculateInteractiveImeasureBoundingBox = (firstClicks, extraClicks = [], voxelToWorldAffine) => {
-    const worldToVoxelAffine = invertAffineMatrix(voxelToWorldAffine);
     const { center, voxelSpaceCenter, cropCubePoints, croppingPlanes, edgeLengths, } = calculateInteractiveImeasureCropRegion(firstClicks, voxelToWorldAffine);
     let maxDistanceFromCenter = 0;
-    const extraClicksInVoxelSpace = extraClicks.map((pt) => roundPoint3(affineTranslateVec3(pt, worldToVoxelAffine)));
-    extraClicksInVoxelSpace.forEach((point) => {
-        maxDistanceFromCenter = Math.max(Math.abs(point[0] - voxelSpaceCenter[0]), Math.abs(point[1] - voxelSpaceCenter[1]), maxDistanceFromCenter);
-        // TODO: handle z-axis differences
+    extraClicks.forEach((point) => {
+        const distanceFromCenter = Math.sqrt(Math.pow(point[0] - center[0], 2) +
+            Math.pow(point[1] - center[1], 2) +
+            Math.pow(point[2] - center[2], 2));
+        maxDistanceFromCenter = Math.max(distanceFromCenter, maxDistanceFromCenter);
     });
-    const halfEdgeLength = maxDistanceFromCenter + INTERACTIVE_IMEASURE_BASE.PADDING;
+    const newEdgeLengths = worldLengthAndAffineToCropCuboidDimensions(maxDistanceFromCenter * 2, voxelToWorldAffine);
     // check if we need to expand the box at all?
-    if (halfEdgeLength * 2 < edgeLengths.x) {
+    if (newEdgeLengths[0] <= edgeLengths.x) {
         return {
             center,
             voxelSpaceCenter,
@@ -114,19 +121,21 @@ export const calculateInteractiveImeasureBoundingBox = (firstClicks, extraClicks
             edgeLengths,
         };
     }
-    const zLength = calculateZAxisLength(halfEdgeLength * 2, voxelToWorldAffine);
-    const newEdgeLengths = {
-        x: halfEdgeLength * 2,
-        y: halfEdgeLength * 2,
-        z: zLength,
-    };
-    const { cropCubePoints: newCropCubePoints, croppingPlanes: newCroppingPlanes, } = getCropCuboidFromCenterAndEdgeLengths(voxelSpaceCenter, newEdgeLengths);
+    const { cropCubePoints: newCropCubePoints, croppingPlanes: newCroppingPlanes, } = getCropCuboidFromCenterAndEdgeLengths(voxelSpaceCenter, {
+        x: newEdgeLengths[0],
+        y: newEdgeLengths[1],
+        z: newEdgeLengths[2],
+    });
     return {
         center,
         voxelSpaceCenter,
         cropCubePoints: newCropCubePoints,
         croppingPlanes: newCroppingPlanes,
-        edgeLengths: newEdgeLengths,
+        edgeLengths: {
+            x: newEdgeLengths[0],
+            y: newEdgeLengths[1],
+            z: newEdgeLengths[2],
+        },
     };
 };
 /**

package/dist/math/cropping.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/math/cropping.test.js

@@ -0,0 +1,184 @@
+import { mat4 } from "gl-matrix";
+import { it, describe, expect } from "vitest";
+import { calculateInteractiveImeasureBoundingBox, getInteractiveImeasureCropCuboidDimensions, } from "./cropping";
+const identityMatrix = mat4.fromValues(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1);
+// a matrix where the pixel spacing is 1mm and slice thickness is 2mm
+// since these are world-to-voxel affine matrices, the 0.5 indicates
+// that for every z-axis millimeter in the world we move 0.5 units in voxel space
+const thickSlicesMatrix = mat4.fromValues(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0.5, // slice thickness
+0, 0, 0, 0, 1);
+describe("getInteractiveImeasureCropCuboidDimensions", () => {
+    const testCases = [
+        {
+            it: "returns expected minimums in case of a very short base measurement",
+            measurement: [
+                [100, 100, 256],
+                [101, 101, 256],
+            ],
+            expectedDimensions: [128, 128, 128],
+        },
+        {
+            it: "returns expected dimensions for a larger measurement",
+            measurement: [
+                [0, 100, 256],
+                [0, 0, 256],
+            ],
+            // the length of the line in the largest axis (X) is 100, so the z-axis length
+            // is 100 + 2*padding = 116 but x/y dimensions are not scaled as they still fit
+            // the minimum size of 128
+            expectedDimensions: [128, 128, 128],
+        },
+        {
+            it: "returns expected dimensions that extend past minimums in x/y axes",
+            measurement: [
+                [0, 200, 256],
+                [0, 0, 256],
+            ],
+            expectedDimensions: [216, 216, 216],
+        },
+        {
+            it: "properly scales z-axis even if x/y movement is minimal",
+            measurement: [
+                [0, 0, 0],
+                [0, 0, 100],
+            ],
+            // length of the line in the largest axis is 100 so z-axis of crop cuboid
+            // should scale accordingly
+            expectedDimensions: [128, 128, 128],
+        },
+        {
+            it: "properly scales z-axis when movement happens in all axes",
+            measurement: [
+                [0, 0, 0],
+                [50, 50, 50],
+            ],
+            expectedDimensions: [128, 128, 128],
+        },
+        {
+            it: "properly scales all axes when movement happens in all axes and doesn't fit minimums",
+            measurement: [
+                [0, 0, 0],
+                [200, 200, 200],
+            ],
+            expectedDimensions: [362, 362, 362],
+        },
+        {
+            it: "properly scales z-axis with minimal x/y movement and thick slices",
+            measurement: [
+                [0, 0, 0],
+                [0, 0, 100],
+            ],
+            // 100/2 + 2*padding = 50 + 16 = 66
+            expectedDimensions: [128, 128, 64],
+            matrix: thickSlicesMatrix,
+        },
+        {
+            it: "properly scales z-axis with minimal x/y movement and thick slices when z-axis doesn't fit minimums",
+            measurement: [
+                [0, 0, 0],
+                [0, 0, 200],
+            ],
+            // the length of the measurement is 200 -> measurement + padding gives us 216 in x/y and
+            // half that in z-axis due to slice thickness
+            expectedDimensions: [216, 216, 108],
+            matrix: thickSlicesMatrix,
+        },
+        {
+            it: "properly scales all axes with thick slices",
+            measurement: [
+                [0, 0, 0],
+                [200, 200, 200],
+            ],
+            expectedDimensions: [362, 362, 182],
+            matrix: thickSlicesMatrix,
+        },
+        {
+            it: "properly scales all axes if z-axis diff is minimal but not null",
+            measurement: [
+                [0, 0, 0],
+                [200, 200, 100],
+            ],
+            // whereas a 100mm movement in z-axis would result in 66 voxels of cuboid length,
+            // we _are_ still trying to keep it cuboid shaped - since the naive z-axis  calculation
+            // of `max(x_length, y_length) * proportion` yields 108 voxels, we use that  as it
+            // is bigger and thus more likely to fit a spherical shape.
+            expectedDimensions: [316, 316, 158],
+            matrix: thickSlicesMatrix,
+        },
+    ];
+    const hasOnly = testCases.some((test) => test.only);
+    testCases.forEach(({ it: name, measurement, expectedDimensions, matrix, only }) => {
+        if (hasOnly && !only) {
+            return; // skip this test if there is an 'only' test case
+        }
+        it(name, () => {
+            const dims = getInteractiveImeasureCropCuboidDimensions(measurement, matrix || identityMatrix);
+            expect(dims).toEqual(expectedDimensions);
+        });
+    });
+});
+describe("calculateInteractiveImeasureBoundingBox", () => {
+    const testCases = [
+        {
+            it: "returns a base bounding box for a single click",
+            baseClicks: [[100, 100, 100]],
+            extraClicks: [],
+            expectedCenter: [100, 100, 100],
+            expectedEdgeLengths: { x: 128, y: 128, z: 128 },
+        },
+        {
+            it: "returns a base bounding box for a very short measurement",
+            baseClicks: [
+                [99, 99, 99],
+                [101, 101, 101],
+            ],
+            extraClicks: [],
+            expectedCenter: [100, 100, 100],
+            expectedEdgeLengths: { x: 128, y: 128, z: 128 },
+        },
+        {
+            it: "returns base bounding box if extra clicks fit within the initial box",
+            baseClicks: [
+                [99, 99, 99],
+                [101, 101, 101],
+            ],
+            extraClicks: [
+                [100, 100, 100],
+                [102, 102, 102],
+            ],
+            expectedCenter: [100, 100, 100],
+            expectedEdgeLengths: { x: 128, y: 128, z: 128 },
+        },
+        {
+            it: "returns scaled box if base clicks don't fit minimums but extra clicks fit",
+            baseClicks: [
+                [50, 50, 50],
+                [150, 150, 150],
+            ],
+            extraClicks: [[100, 100, 100]],
+            expectedCenter: [100, 100, 100],
+            expectedEdgeLengths: { x: 190, y: 190, z: 190 },
+        },
+        {
+            it: "returns scaled box if base clicks fit minimums but extra clicks don't",
+            baseClicks: [
+                [99, 99, 99],
+                [101, 101, 101],
+            ],
+            extraClicks: [[99, 99, 250]],
+            expectedCenter: [100, 100, 100],
+            expectedEdgeLengths: { x: 316, y: 316, z: 316 },
+        },
+    ];
+    const hasOnly = testCases.some((test) => test.only);
+    testCases.forEach(({ it: name, baseClicks, extraClicks, worldToVoxelAffine, expectedCenter, expectedEdgeLengths, only, }) => {
+        if (hasOnly && !only) {
+            return; // skip this test if there is an 'only' test case
+        }
+        it(name, () => {
+            const result = calculateInteractiveImeasureBoundingBox(baseClicks, extraClicks, worldToVoxelAffine || identityMatrix);
+            expect(result.center).toEqual(expectedCenter);
+            expect(result.edgeLengths).toEqual(expectedEdgeLengths);
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettermedicine/imeasure",
-  "version": "0.0.5",
+  "version": "0.0.7-0",
   "main": "dist/index.js",
   "scripts": {
     "prepack": "npm run build",

package/src/math/cropping.test.ts

@@ -0,0 +1,260 @@
+import { mat4 } from "gl-matrix";
+import { it, describe, expect, test } from "vitest";
+import {
+  calculateInteractiveImeasureBoundingBox,
+  getInteractiveImeasureCropCuboidDimensions,
+} from "./cropping";
+import { Point3D } from "../types/cornerstone";
+
+type TCropTestCase = {
+  it: string;
+  measurement: [[number, number, number], [number, number, number]];
+  expectedDimensions: [number, number, number];
+  matrix?: mat4; // an undefined matrix will default to identity
+  only?: true; // only run this test case - useful for debugging
+};
+const identityMatrix = mat4.fromValues(
+  1,
+  0,
+  0,
+  0,
+  0,
+  1,
+  0,
+  0,
+  0,
+  0,
+  1,
+  0,
+  0,
+  0,
+  0,
+  1
+);
+// a matrix where the pixel spacing is 1mm and slice thickness is 2mm
+// since these are world-to-voxel affine matrices, the 0.5 indicates
+// that for every z-axis millimeter in the world we move 0.5 units in voxel space
+const thickSlicesMatrix = mat4.fromValues(
+  1,
+  0,
+  0,
+  0,
+  0,
+  1,
+  0,
+  0,
+  0,
+  0,
+  0.5, // slice thickness
+  0,
+  0,
+  0,
+  0,
+  1
+);
+
+describe("getInteractiveImeasureCropCuboidDimensions", () => {
+  const testCases: TCropTestCase[] = [
+    {
+      it: "returns expected minimums in case of a very short base measurement",
+      measurement: [
+        [100, 100, 256],
+        [101, 101, 256],
+      ],
+      expectedDimensions: [128, 128, 128],
+    },
+    {
+      it: "returns expected dimensions for a larger measurement",
+      measurement: [
+        [0, 100, 256],
+        [0, 0, 256],
+      ],
+      // the length of the line in the largest axis (X) is 100, so the z-axis length
+      // is 100 + 2*padding = 116 but x/y dimensions are not scaled as they still fit
+      // the minimum size of 128
+      expectedDimensions: [128, 128, 128],
+    },
+    {
+      it: "returns expected dimensions that extend past minimums in x/y axes",
+      measurement: [
+        [0, 200, 256],
+        [0, 0, 256],
+      ],
+      expectedDimensions: [216, 216, 216],
+    },
+    {
+      it: "properly scales z-axis even if x/y movement is minimal",
+      measurement: [
+        [0, 0, 0],
+        [0, 0, 100],
+      ],
+      // length of the line in the largest axis is 100 so z-axis of crop cuboid
+      // should scale accordingly
+      expectedDimensions: [128, 128, 128],
+    },
+    {
+      it: "properly scales z-axis when movement happens in all axes",
+      measurement: [
+        [0, 0, 0],
+        [50, 50, 50],
+      ],
+      expectedDimensions: [128, 128, 128],
+    },
+    {
+      it: "properly scales all axes when movement happens in all axes and doesn't fit minimums",
+      measurement: [
+        [0, 0, 0],
+        [200, 200, 200],
+      ],
+      expectedDimensions: [362, 362, 362],
+    },
+    {
+      it: "properly scales z-axis with minimal x/y movement and thick slices",
+      measurement: [
+        [0, 0, 0],
+        [0, 0, 100],
+      ],
+      // 100/2 + 2*padding = 50 + 16 = 66
+      expectedDimensions: [128, 128, 64],
+      matrix: thickSlicesMatrix,
+    },
+    {
+      it: "properly scales z-axis with minimal x/y movement and thick slices when z-axis doesn't fit minimums",
+      measurement: [
+        [0, 0, 0],
+        [0, 0, 200],
+      ],
+      // the length of the measurement is 200 -> measurement + padding gives us 216 in x/y and
+      // half that in z-axis due to slice thickness
+      expectedDimensions: [216, 216, 108],
+      matrix: thickSlicesMatrix,
+    },
+    {
+      it: "properly scales all axes with thick slices",
+      measurement: [
+        [0, 0, 0],
+        [200, 200, 200],
+      ],
+      expectedDimensions: [362, 362, 182],
+      matrix: thickSlicesMatrix,
+    },
+    {
+      it: "properly scales all axes if z-axis diff is minimal but not null",
+      measurement: [
+        [0, 0, 0],
+        [200, 200, 100],
+      ],
+      // whereas a 100mm movement in z-axis would result in 66 voxels of cuboid length,
+      // we _are_ still trying to keep it cuboid shaped - since the naive z-axis  calculation
+      // of `max(x_length, y_length) * proportion` yields 108 voxels, we use that  as it
+      // is bigger and thus more likely to fit a spherical shape.
+      expectedDimensions: [316, 316, 158],
+      matrix: thickSlicesMatrix,
+    },
+  ];
+  const hasOnly = testCases.some((test) => test.only);
+  testCases.forEach(
+    ({ it: name, measurement, expectedDimensions, matrix, only }) => {
+      if (hasOnly && !only) {
+        return; // skip this test if there is an 'only' test case
+      }
+      it(name, () => {
+        const dims = getInteractiveImeasureCropCuboidDimensions(
+          measurement,
+          matrix || identityMatrix
+        );
+        expect(dims).toEqual(expectedDimensions);
+      });
+    }
+  );
+});
+
+type TBBTestCase = {
+  it: string;
+  baseClicks: [Point3D, Point3D] | [Point3D];
+  extraClicks: Point3D[];
+  worldToVoxelAffine?: mat4;
+  expectedCenter: [number, number, number];
+  expectedEdgeLengths: { x: number; y: number; z: number };
+  only?: true; // only run this test case - useful for debugging
+};
+
+describe("calculateInteractiveImeasureBoundingBox", () => {
+  const testCases: TBBTestCase[] = [
+    {
+      it: "returns a base bounding box for a single click",
+      baseClicks: [[100, 100, 100]],
+      extraClicks: [],
+      expectedCenter: [100, 100, 100],
+      expectedEdgeLengths: { x: 128, y: 128, z: 128 },
+    },
+    {
+      it: "returns a base bounding box for a very short measurement",
+      baseClicks: [
+        [99, 99, 99],
+        [101, 101, 101],
+      ],
+      extraClicks: [],
+      expectedCenter: [100, 100, 100],
+      expectedEdgeLengths: { x: 128, y: 128, z: 128 },
+    },
+    {
+      it: "returns base bounding box if extra clicks fit within the initial box",
+      baseClicks: [
+        [99, 99, 99],
+        [101, 101, 101],
+      ],
+      extraClicks: [
+        [100, 100, 100],
+        [102, 102, 102],
+      ],
+      expectedCenter: [100, 100, 100],
+      expectedEdgeLengths: { x: 128, y: 128, z: 128 },
+    },
+    {
+      it: "returns scaled box if base clicks don't fit minimums but extra clicks fit",
+      baseClicks: [
+        [50, 50, 50],
+        [150, 150, 150],
+      ],
+      extraClicks: [[100, 100, 100]],
+      expectedCenter: [100, 100, 100],
+      expectedEdgeLengths: { x: 190, y: 190, z: 190 },
+    },
+    {
+      it: "returns scaled box if base clicks fit minimums but extra clicks don't",
+      baseClicks: [
+        [99, 99, 99],
+        [101, 101, 101],
+      ],
+      extraClicks: [[99, 99, 250]],
+      expectedCenter: [100, 100, 100],
+      expectedEdgeLengths: { x: 316, y: 316, z: 316 },
+    },
+  ];
+  const hasOnly = testCases.some((test) => test.only);
+  testCases.forEach(
+    ({
+      it: name,
+      baseClicks,
+      extraClicks,
+      worldToVoxelAffine,
+      expectedCenter,
+      expectedEdgeLengths,
+      only,
+    }) => {
+      if (hasOnly && !only) {
+        return; // skip this test if there is an 'only' test case
+      }
+      it(name, () => {
+        const result = calculateInteractiveImeasureBoundingBox(
+          baseClicks,
+          extraClicks,
+          worldToVoxelAffine || identityMatrix
+        );
+        expect(result.center).toEqual(expectedCenter);
+        expect(result.edgeLengths).toEqual(expectedEdgeLengths);
+      });
+    }
+  );
+});

package/src/math/cropping.ts

@@ -10,37 +10,55 @@ import {
   TIMeasureCropRegion,
 } from "../types/crop";
 
+const worldLengthAndAffineToCropCuboidDimensions = (
+  worldLength: number,
+  worldToVoxelAffine: mat4
+): [number, number, number] => {
+  const voxelToWorldAffine = invertAffineMatrix(worldToVoxelAffine);
+  // we effectively need to make the length of the measurement fit the crop region
+  // in all 3 dimensions.
+  const pixelSpacing = voxelToWorldAffine[0];
+  const sliceThickness = voxelToWorldAffine[10];
+  // calculate the length in voxel space
+  let xyLength = Math.max(
+    INTERACTIVE_IMEASURE_BASE.X,
+    Math.round(worldLength / pixelSpacing) +
+      INTERACTIVE_IMEASURE_BASE.PADDING * 2
+  );
+  if (xyLength % 2 !== 0) {
+    xyLength += 1; // ensure even number
+  }
+
+  let zLength = Math.max(
+    INTERACTIVE_IMEASURE_BASE.Z,
+    Math.round((xyLength * pixelSpacing) / sliceThickness)
+  );
+  if (zLength % 2 !== 0) {
+    zLength += 1; // ensure even number
+  }
+
+  return [xyLength, xyLength, zLength];
+};
+
 // TODO: should expand scale based on z-axis input point diff.
 // Tests first.
 export const getInteractiveImeasureCropCuboidDimensions = (
   measurement: [Point3D, Point3D],
   worldToVoxelAffine: mat4
 ): number[] => {
-  const [voxelStart, voxelEnd] = measurement.map((pt) =>
-    roundPoint3(affineTranslateVec3(pt, worldToVoxelAffine))
-  );
-
-  const x_size =
-    Math.abs(voxelStart[0] - voxelEnd[0]) +
-    INTERACTIVE_IMEASURE_BASE.PADDING * 2;
-  const y_size =
-    Math.abs(voxelStart[1] - voxelEnd[1]) +
-    INTERACTIVE_IMEASURE_BASE.PADDING * 2;
-
-  let xyCubeSize = Math.max(x_size, y_size, INTERACTIVE_IMEASURE_BASE.X);
-  // the model always expects an even number of voxels on each axis
-  if (xyCubeSize % 2 !== 0) {
-    xyCubeSize += 1;
-  }
-  const voxelToWorldAffine = invertAffineMatrix(worldToVoxelAffine);
-  const maxDistanceBetweenPoints = Math.max(x_size, y_size);
+  const [worldStart, worldEnd] = measurement;
 
-  const zLength = calculateZAxisLength(
-    maxDistanceBetweenPoints,
-    voxelToWorldAffine
+  // calculate the world-space length of the measurement
+  const worldLength = Math.sqrt(
+    Math.pow(worldEnd[0] - worldStart[0], 2) +
+      Math.pow(worldEnd[1] - worldStart[1], 2) +
+      Math.pow(worldEnd[2] - worldStart[2], 2)
   );
 
-  return [xyCubeSize, xyCubeSize, zLength];
+  return worldLengthAndAffineToCropCuboidDimensions(
+    worldLength,
+    worldToVoxelAffine
+  );
 };
 
 const getCropCuboidFromCenterAndEdgeLengths = (
@@ -78,7 +96,7 @@ export const calculateInteractiveImeasureCropRegion = (
 ): TIMeasureCropRegion => {
   let center: Point3D;
   const singlePoint = worldBasePoints.length === 1;
-
+  let worldBaseLength = 0;
   if (singlePoint) {
     center = worldBasePoints[0];
   } else {
@@ -87,6 +105,11 @@ export const calculateInteractiveImeasureCropRegion = (
       (worldBasePoints[0][1] + worldBasePoints[1][1]) / 2,
       (worldBasePoints[0][2] + worldBasePoints[1][2]) / 2,
     ];
+    worldBaseLength = Math.sqrt(
+      Math.pow(worldBasePoints[1][0] - worldBasePoints[0][0], 2) +
+        Math.pow(worldBasePoints[1][1] - worldBasePoints[0][1], 2) +
+        Math.pow(worldBasePoints[1][2] - worldBasePoints[0][2], 2)
+    );
   }
 
   // we want to convert (and round) this to voxel coordinates
@@ -96,18 +119,10 @@ export const calculateInteractiveImeasureCropRegion = (
   );
 
   // if we only have a single click, use constants for edge lengths.
-  let x_edge = INTERACTIVE_IMEASURE_BASE.X;
-  let y_edge = INTERACTIVE_IMEASURE_BASE.Y;
-  let z_edge = INTERACTIVE_IMEASURE_BASE.Z;
-
-  if (!singlePoint) {
-    // if we have two clicks, calculate the edges based on the points
-    const tempProposedCuboidEdges = getInteractiveImeasureCropCuboidDimensions(
-      worldBasePoints as [Point3D, Point3D],
-      worldToVoxelAffine
-    );
-    [x_edge, y_edge, z_edge] = tempProposedCuboidEdges;
-  }
+  const [x_edge, y_edge, z_edge] = worldLengthAndAffineToCropCuboidDimensions(
+    worldBaseLength,
+    worldToVoxelAffine
+  );
 
   const { cropCubePoints, croppingPlanes } =
     getCropCuboidFromCenterAndEdgeLengths(voxelSpaceCenter, {
@@ -142,8 +157,6 @@ export const calculateInteractiveImeasureBoundingBox = (
   extraClicks: Point3D[] = [],
   voxelToWorldAffine: mat4
 ): TIMeasureCropRegion => {
-  const worldToVoxelAffine = invertAffineMatrix(voxelToWorldAffine);
-
   const {
     center,
     voxelSpaceCenter,
@@ -153,24 +166,22 @@ export const calculateInteractiveImeasureBoundingBox = (
   } = calculateInteractiveImeasureCropRegion(firstClicks, voxelToWorldAffine);
 
   let maxDistanceFromCenter = 0;
-  const extraClicksInVoxelSpace = extraClicks.map((pt) =>
-    roundPoint3(affineTranslateVec3(pt, worldToVoxelAffine))
-  );
 
-  extraClicksInVoxelSpace.forEach((point) => {
-    maxDistanceFromCenter = Math.max(
-      Math.abs(point[0] - voxelSpaceCenter[0]),
-      Math.abs(point[1] - voxelSpaceCenter[1]),
-      maxDistanceFromCenter
+  extraClicks.forEach((point) => {
+    const distanceFromCenter = Math.sqrt(
+      Math.pow(point[0] - center[0], 2) +
+        Math.pow(point[1] - center[1], 2) +
+        Math.pow(point[2] - center[2], 2)
     );
-    // TODO: handle z-axis differences
+    maxDistanceFromCenter = Math.max(distanceFromCenter, maxDistanceFromCenter);
   });
 
-  const halfEdgeLength =
-    maxDistanceFromCenter + INTERACTIVE_IMEASURE_BASE.PADDING;
-
+  const newEdgeLengths = worldLengthAndAffineToCropCuboidDimensions(
+    maxDistanceFromCenter * 2,
+    voxelToWorldAffine
+  );
   // check if we need to expand the box at all?
-  if (halfEdgeLength * 2 < edgeLengths.x) {
+  if (newEdgeLengths[0] <= edgeLengths.x) {
     return {
       center,
       voxelSpaceCenter,
@@ -179,23 +190,24 @@ export const calculateInteractiveImeasureBoundingBox = (
       edgeLengths,
     };
   }
-  const zLength = calculateZAxisLength(halfEdgeLength * 2, voxelToWorldAffine);
-
-  const newEdgeLengths = {
-    x: halfEdgeLength * 2,
-    y: halfEdgeLength * 2,
-    z: zLength,
-  };
   const {
     cropCubePoints: newCropCubePoints,
     croppingPlanes: newCroppingPlanes,
-  } = getCropCuboidFromCenterAndEdgeLengths(voxelSpaceCenter, newEdgeLengths);
+  } = getCropCuboidFromCenterAndEdgeLengths(voxelSpaceCenter, {
+    x: newEdgeLengths[0],
+    y: newEdgeLengths[1],
+    z: newEdgeLengths[2],
+  });
   return {
     center,
     voxelSpaceCenter,
     cropCubePoints: newCropCubePoints,
     croppingPlanes: newCroppingPlanes,
-    edgeLengths: newEdgeLengths,
+    edgeLengths: {
+      x: newEdgeLengths[0],
+      y: newEdgeLengths[1],
+      z: newEdgeLengths[2],
+    },
   };
 };