@bettermedicine/imeasure 0.0.5 → 0.0.6-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

@@ -5,18 +5,39 @@ import { calculateZAxisLength, roundPoint3 } from "./utility";
 // Tests first.
 export const getInteractiveImeasureCropCuboidDimensions = (measurement, worldToVoxelAffine) => {
     const [voxelStart, voxelEnd] = measurement.map((pt) => roundPoint3(affineTranslateVec3(pt, worldToVoxelAffine)));
+    const voxelToWorldAffine = invertAffineMatrix(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;
+    // if the z-axis distance between the two points is not null, we need to take
+    // z-axis length into account as well.
+    const zSizeWithoutPadding = Math.abs(voxelStart[2] - voxelEnd[2]);
+    const maxDistanceBetweenPointsAxially = Math.max(x_size, y_size);
+    const zLength = calculateZAxisLength(maxDistanceBetweenPointsAxially, voxelToWorldAffine);
+    if (zSizeWithoutPadding !== 0) {
+        const pixelSpacing = voxelToWorldAffine[0];
+        const sliceThickness = voxelToWorldAffine[10];
+        // lets start by calculating the proportion between x/y pixel spacing and
+        // series slice thickness.
+        const proportion = sliceThickness / pixelSpacing;
+        // then find the z-axis length based on the largest axis
+        // lets take z-axis length and scale it to x/y axis length
+        const z_size = Math.max(zSizeWithoutPadding + INTERACTIVE_IMEASURE_BASE.PADDING * 2, INTERACTIVE_IMEASURE_BASE.Z);
+        const zSizeScaledWithoutPadding = Math.round(zSizeWithoutPadding * proportion);
+        const zSizeScaledPadded = zSizeScaledWithoutPadding + 2 * INTERACTIVE_IMEASURE_BASE.PADDING;
+        return [
+            Math.max(x_size, zSizeScaledPadded, INTERACTIVE_IMEASURE_BASE.X),
+            Math.max(y_size, zSizeScaledPadded, INTERACTIVE_IMEASURE_BASE.Y),
+            Math.max(z_size, zLength),
+        ];
+    }
     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);
+    console.log("zLength", zLength);
     return [xyCubeSize, xyCubeSize, zLength];
 };
 const getCropCuboidFromCenterAndEdgeLengths = (voxelSpaceCenter, edgeLengths) => {

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

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

package/dist/math/cropping.test.js

@@ -0,0 +1,119 @@
+import { mat4 } from "gl-matrix";
+import { it, describe, expect } from "vitest";
+import { getInteractiveImeasureCropCuboidDimensions } from "./cropping";
+describe("getInteractiveImeasureCropCuboidDimensions", () => {
+    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);
+    const testCases = [
+        {
+            it: "returns expected minimums in case of a very short base measurement",
+            measurement: [
+                [100, 100, 256],
+                [101, 101, 256],
+            ],
+            expectedDimensions: [128, 128, 32],
+        },
+        {
+            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, 116],
+        },
+        {
+            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, 116],
+        },
+        {
+            it: "properly scales z-axis when movement happens in all axes",
+            measurement: [
+                [0, 0, 0],
+                [100, 100, 100],
+            ],
+            expectedDimensions: [128, 128, 116],
+        },
+        {
+            it: "properly scales all axes when movement happens in all axes and doesn't fit minimums",
+            measurement: [
+                [0, 0, 0],
+                [200, 200, 200],
+            ],
+            expectedDimensions: [216, 216, 216],
+        },
+        {
+            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, 66],
+            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],
+            ],
+            // 200/2 + 2*padding = 100 + 16 = 116
+            expectedDimensions: [216, 216, 116],
+            matrix: thickSlicesMatrix,
+        },
+        {
+            it: "properly scales all axes with thick slices",
+            measurement: [
+                [0, 0, 0],
+                [200, 200, 200],
+            ],
+            // 200/2 + 2*padding = 100 + 16 = 116
+            expectedDimensions: [216, 216, 116],
+            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: [216, 216, 108],
+            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);
+        });
+    });
+});

package/package.json

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

package/src/math/cropping.test.ts

@@ -0,0 +1,168 @@
+import { mat4 } from "gl-matrix";
+import { it, describe, expect } from "vitest";
+import { Point3D } from "../types/cornerstone";
+import { getInteractiveImeasureCropCuboidDimensions } from "./cropping";
+
+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
+};
+
+describe("getInteractiveImeasureCropCuboidDimensions", () => {
+  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
+  );
+
+  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, 32],
+    },
+    {
+      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, 116],
+    },
+    {
+      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, 116],
+    },
+    {
+      it: "properly scales z-axis when movement happens in all axes",
+      measurement: [
+        [0, 0, 0],
+        [100, 100, 100],
+      ],
+      expectedDimensions: [128, 128, 116],
+    },
+    {
+      it: "properly scales all axes when movement happens in all axes and doesn't fit minimums",
+      measurement: [
+        [0, 0, 0],
+        [200, 200, 200],
+      ],
+      expectedDimensions: [216, 216, 216],
+    },
+    {
+      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, 66],
+      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],
+      ],
+      // 200/2 + 2*padding = 100 + 16 = 116
+      expectedDimensions: [216, 216, 116],
+      matrix: thickSlicesMatrix,
+    },
+    {
+      it: "properly scales all axes with thick slices",
+      measurement: [
+        [0, 0, 0],
+        [200, 200, 200],
+      ],
+      // 200/2 + 2*padding = 100 + 16 = 116
+      expectedDimensions: [216, 216, 116],
+      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: [216, 216, 108],
+      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);
+      });
+    }
+  );
+});

package/src/math/cropping.ts

@@ -19,6 +19,7 @@ export const getInteractiveImeasureCropCuboidDimensions = (
   const [voxelStart, voxelEnd] = measurement.map((pt) =>
     roundPoint3(affineTranslateVec3(pt, worldToVoxelAffine))
   );
+  const voxelToWorldAffine = invertAffineMatrix(worldToVoxelAffine);
 
   const x_size =
     Math.abs(voxelStart[0] - voxelEnd[0]) +
@@ -26,19 +27,51 @@ export const getInteractiveImeasureCropCuboidDimensions = (
   const y_size =
     Math.abs(voxelStart[1] - voxelEnd[1]) +
     INTERACTIVE_IMEASURE_BASE.PADDING * 2;
+  // if the z-axis distance between the two points is not null, we need to take
+  // z-axis length into account as well.
+  const zSizeWithoutPadding = Math.abs(voxelStart[2] - voxelEnd[2]);
+
+  const maxDistanceBetweenPointsAxially = Math.max(x_size, y_size);
+
+  const zLength = calculateZAxisLength(
+    maxDistanceBetweenPointsAxially,
+    voxelToWorldAffine
+  );
+
+  if (zSizeWithoutPadding !== 0) {
+    const pixelSpacing = voxelToWorldAffine[0];
+    const sliceThickness = voxelToWorldAffine[10];
+    // lets start by calculating the proportion between x/y pixel spacing and
+    // series slice thickness.
+    const proportion = sliceThickness / pixelSpacing;
+    // then find the z-axis length based on the largest axis
+
+    // lets take z-axis length and scale it to x/y axis length
+    const z_size = Math.max(
+      zSizeWithoutPadding + INTERACTIVE_IMEASURE_BASE.PADDING * 2,
+      INTERACTIVE_IMEASURE_BASE.Z
+    );
+
+    const zSizeScaledWithoutPadding = Math.round(
+      zSizeWithoutPadding * proportion
+    );
+
+    const zSizeScaledPadded =
+      zSizeScaledWithoutPadding + 2 * INTERACTIVE_IMEASURE_BASE.PADDING;
+    return [
+      Math.max(x_size, zSizeScaledPadded, INTERACTIVE_IMEASURE_BASE.X),
+      Math.max(y_size, zSizeScaledPadded, INTERACTIVE_IMEASURE_BASE.Y),
+      Math.max(z_size, zLength),
+    ];
+  }
 
   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
-  );
+  console.log("zLength", zLength);
 
   return [xyCubeSize, xyCubeSize, zLength];
 };