larvitar 0.20.0 → 1.2.2

package/imaging/tools/{tools.segmentation.js → segmentation.js}

@@ -1,33 +1,23 @@
+/** @module imaging/tools/segmentation
+ *  @desc  This file provides functionalities
+ *         for handling masks and luts
+ */
+
 // external libraries
 import cornerstone from "cornerstone-core";
 import cornerstoneTools from "cornerstone-tools/dist/cornerstoneTools.js";
-// tools
-import { setToolActive, setToolDisabled } from "./tools.main";
-// utils
-import { cloneDeep, extend, values } from "lodash";
-
+import { cloneDeep, extend, values, sum } from "lodash";
 const segModule = cornerstoneTools.getModule("segmentation");
-const setters = segModule.setters;
-const getters = segModule.getters;
+const { getters, setters } = segModule;
 
-/**
- * THIS MODULE IS A WIP
- */
+// internal libraries
+import { setToolActive, setToolDisabled } from "./main";
+import { isElement } from "../imageUtils";
 
-// DEV
-window.segModule = segModule;
-window.cornerstone = cornerstone;
-window.cornerstoneTools = cornerstoneTools;
-
-/**
- * NOTES ON CS TOOLS SEGMENTATION MODULE
- * The value in the mask (binary) define which color will be used from the LUT map
- * The different masks are 'labelmap', while different values in the same mask are 'segments'
- * Segments get the color from the lutmap (up to 2^16 segments) and can be shown/hidden one by one
- * > setters.toggleSegmentVisibility(htmlelement,segmentvalue,labelmapid)
- * > setters.colorForSegmentIndexOfColorLUT(colorLutIndex, segmentValue, colorRGBAarray)
- * Labelmaps are linked to a colormap and can be active / inactive
- * */
+// custom code
+import { setLabelmap3DForElement } from "./setLabelMap3D";
+// override function
+setters.labelmap3DForElement = setLabelmap3DForElement;
 
 // General segmentation cs tools module configuration
 const config = {
@@ -145,53 +135,153 @@ function generateUniformLUT(hex_color, opacity) {
   return lut;
 }
 
+/**
+ * Set color for label
+ * @param {Number} labelId
+ * @param {String} color in hex format
+ */
+export function setLabelColor(labelId, color) {
+  let volumeId = 0; // TODO MULTIVOLUME
+  let rgb = hexToRgb(color);
+  let rgba = [...rgb, 128];
+  setters.colorForSegmentIndexOfColorLUT(volumeId, labelId, rgba);
+  // force render ? depends on image visualization (render all ?)
+}
+
+/**
+ * Get color from label
+ * @param {Number} labelId
+ * @returns {String} Color in hex format
+ */
+export function getLabelColor(labelId) {
+  let volumeId = 0; // TODO MULTIVOLUME
+  let rgba = getters.colorForSegmentIndexColorLUT(volumeId, labelId);
+  return rgbToHex(rgba);
+}
+
 /**
  * A function to group all settings to load before masks
- * TODO add a param to override config
+ * @param {Object} customConfig - Object containing override values for segmentation module config
  */
-export function initSegmentationModule() {
+export function initSegmentationModule(customConfig) {
   // set configuration
   segModule.configuration = cloneDeep(config);
+  extend(segModule.configuration, customConfig);
 }
 
 /**
  * Add segmentation mask to segmentation module
- * @param {Number} labelId - The label index (must be unique)
+ * @param {Object} maskProps - The mask properties (labelId, color and opacity)
  * @param {TypedArray} - The mask data array
+ * @param {String} elementId - The target html element Id or its DOM HTMLElement
+ * @returns {Promise} - Return a promise which will resolve when segmentation mask is added
  */
-export function addSegmentationMask(props, data, elementId, cb) {
-  let element = document.getElementById(elementId);
-  setters.labelmap3DForElement(element, data.buffer, props.labelId);
-  // if user set a color property, use that color for all segments on the labelmap
-  let lut = props.color
-    ? generateUniformLUT(props.color, props.opacity)
-    : generateLUT(props.opacity);
-  setters.colorLUT(props.labelId, lut);
-  // bind labelmap to colorLUT
-  let labelmap3d = getters.labelmap3D(element, props.labelId);
-  setters.colorLUTIndexForLabelmap3D(labelmap3d, props.labelId);
-  if (cb) {
-    cb();
+export function addSegmentationMask(props, data, elementId) {
+  let promise = new Promise(async resolve => {
+    let element = isElement(elementId)
+      ? elementId
+      : document.getElementById(elementId);
+    if (!element) {
+      console.error("invalid html element: " + elementId);
+      return;
+    }
+
+    const res = await setters.labelmap3DForElement(
+      element,
+      data.buffer,
+      props.labelId
+    );
+    // if user set a color property, use that color for all segments on the labelmap
+    let lut = props.color
+      ? generateUniformLUT(props.color, props.opacity)
+      : generateLUT(props.opacity);
+    setters.colorLUT(props.labelId, lut);
+    // bind labelmap to colorLUT
+    let labelmap3d = getters.labelmap3D(element, props.labelId);
+    setters.colorLUTIndexForLabelmap3D(labelmap3d, props.labelId);
+    resolve();
+  });
+  return promise;
+}
+
+/**
+ * Set a new mask slice into the labelmap buffer
+ * @param {String} elementId - The target html element Id or its DOM HTMLElement
+ * @param {Number} sliceIndex - the index of the new mask slice
+ * @param {ArrayBuffer} pixelData - the pixelData array
+ */
+export function loadMaskSlice(elementId, sliceIndex, pixelData) {
+  // optimization: if pixelData contains no labels, return
+  if (sum(pixelData) === 0) {
+    return;
+  }
+
+  let element = isElement(elementId)
+    ? elementId
+    : document.getElementById(elementId);
+  if (!element) {
+    console.error("invalid html element: " + elementId);
+    return;
   }
+  let volumeId = 0; // TODO for multivolume
+  // get labelmap buffer
+  let labelmaps2D = getters.labelmap3D(element, volumeId).labelmaps2D;
+
+  // add if not alresdy present
+  if (!labelmaps2D[sliceIndex]) {
+    labelmaps2D[sliceIndex] = {};
+  }
+
+  labelmaps2D[sliceIndex].pixelData = pixelData;
+  setters.updateSegmentsOnLabelmap2D(labelmaps2D[sliceIndex]);
+  cornerstone.updateImage(element);
 }
 
 /**
  * Activate a specific labelmap through its labelId
  * @param {Number} labelId - The labelmap id to activate
- * @param {String} elementId - The target html element id
+ * @param {String} elementId - The target html element Id or its DOM HTMLElement
  */
 export function setActiveLabelmap(labelId, elementId) {
-  let element = document.getElementById(elementId);
+  let element = isElement(elementId)
+    ? elementId
+    : document.getElementById(elementId);
+  if (!element) {
+    console.error("invalid html element: " + elementId);
+    return;
+  }
   setters.activeLabelmapIndex(element, labelId);
 }
 
+/**
+ * Get active labelmap for target element
+ * @param {String} elementId - The target html element Id or its DOM HTMLElement
+ * @returns {Object} The active labelmap object that contains the buffer
+ */
+export function getActiveLabelmapBuffer(elementId) {
+  let element = isElement(elementId)
+    ? elementId
+    : document.getElementById(elementId);
+  if (!element) {
+    console.error("invalid html element: " + elementId);
+    return;
+  }
+  return getters.activeLabelmapBuffer(element);
+}
+
 /**
  * Activate a specific segment through its index
  * @param {Number} segmentIndex - The segment index to activate
- * @param {String} elementId - The target html element id
+ * @param {String} elementId - The target html element Id or its DOM HTMLElement
  */
 export function setActiveSegment(segmentIndex, elementId) {
-  let element = document.getElementById(elementId);
+  let element = isElement(elementId)
+    ? elementId
+    : document.getElementById(elementId);
+  if (!element) {
+    console.error("invalid html element: " + elementId);
+    return;
+  }
   setters.activeSegmentIndex(element, segmentIndex);
 }
 
@@ -213,6 +303,24 @@ export function setInactiveLabelOpacity(opacity) {
   forceRender();
 }
 
+/**
+ * Toggle mask visibility
+ * @param {String} elementId - The target html element Id or its DOM HTMLElement
+ * @param {Number} labelId - The id of the mask label
+ */
+export function toggleVisibility(elementId, labelId) {
+  let element = isElement(elementId)
+    ? elementId
+    : document.getElementById(elementId);
+  if (!element) {
+    console.error("invalid html element: " + elementId);
+    return;
+  }
+  let volumeId = 0; // TODO MULTIVOLUME
+  setters.toggleSegmentVisibility(element, labelId, volumeId);
+  cornerstone.updateImage(element);
+}
+
 /**
  * Toggle between 'contours mode' and 'filled mode'
  * @param {Bool} toggle - Contour mode enabled if true
@@ -236,9 +344,7 @@ export function toggleContourMode(toggle) {
 
 /**
  * Set mask appearance props
- * @param {String} tag - The mask tag
- * @param {Integer} mode - [0=filled, 1=contour, 2=hidden]
- * @param {Float} alpha - Opacity value (if mode=0), between 0 and 1
+ * @param {Object} maskProps - The mask appearance props (labelId, visualization [0=filled, 1=contour, 2=hidden], opacity (if mode=0), between 0 and 1)
  */
 export function setMaskProps(props) {
   // Lut index and segment values are hardcoded because they will depend on design choices:
@@ -299,6 +405,7 @@ export function clearSegmentationState() {
 /**
  * Enable brushing
  * @param {Number} dimension - The initial brush radius
+ * @param {Array} thresholds - The threshold values (min and max)
  */
 export function enableBrushTool(dimension, thresholds) {
   segModule.configuration.radius = dimension;
@@ -324,35 +431,41 @@ export function setBrushProps(props) {
   forceRender();
 }
 
-/**
- * Retrieve the buffer that represents the current active mask
- */
-export function getActiveLabelmapBuffer() {
-  let element = document.getElementById("axial");
-  let object = segModule.getters.activeLabelmapBuffer(element);
-  return object.buffer;
-}
-
 /**
  * Undo last brush operation (stroke)
+ * @param {String} elementId - The target html element Id or its DOM HTMLElement
  */
 export function undoLastStroke(elementId) {
-  let element = document.getElementById(elementId);
+  let element = isElement(elementId)
+    ? elementId
+    : document.getElementById(elementId);
+  if (!element) {
+    console.error("invalid html element: " + elementId);
+    return;
+  }
   let activeLabelMapIndex = segModule.getters.activeLabelmapIndex(element);
   setters.undo(element, activeLabelMapIndex);
 }
 
 /**
  * Redo last brush operation (stroke)
+ * @param {String} elementId - The target html element Id or its DOM HTMLElement
  */
 export function redoLastStroke(elementId) {
-  let element = document.getElementById(elementId);
+  let element = isElement(elementId)
+    ? elementId
+    : document.getElementById(elementId);
+  if (!element) {
+    console.error("invalid html element: " + elementId);
+    return;
+  }
   let activeLabelMapIndex = segModule.getters.activeLabelmapIndex(element);
   setters.redo(element, activeLabelMapIndex);
 }
 
 /**
  * Delete mask from state
+ * @param {Number} labelId - The labelmap id to activate
  */
 export function deleteMask(labelId) {
   let masks = values(segModule.state.series)[0].labelmaps3D;

package/imaging/tools/segmentations.md

@@ -0,0 +1,38 @@
+# Introduction
+
+This guide explains the key concepts of Larvitar **segmentation masks management**, based on cornerstone tools's **segmentation module**.
+
+# Definitions
+
+- _segmentation mask_ or just _mask_: the set of pixels that belongs to a specific structure
+- _volume_: a buffer containing one or more segmentations
+- _label_: the value inside a volume that identifies a specific segmentation
+
+# CS tools
+
+## Segmentation module structure
+
+In cs tools world, the different volumes are defined _labelmaps_, while the different labels in a volume are _segments_. Labelmaps can support up to 2^16 segments.
+The values in the volume (ie, labels) define which color will be used from the LUT map: in fact, segments get the color from the lutmap and can be shown/hidden one by one.
+Each labelmaps can be linked to a different colormap and has a active / inactive property that affects the rendering style (see configuration).
+
+> setters.toggleSegmentVisibility(htmlelement,segmentvalue,labelmapid)  
+> setters.colorForSegmentIndexOfColorLUT(colorLutIndex, segmentValue, colorRGBAarray)
+
+## Configuration
+
+TODO
+
+# Larvitar segmentation management
+
+TODO
+
+# Larvitar segmentation API
+
+TODO
+
+# Customization
+
+Some function in larvitar overrides the default behaviour of cornerstone tools, here is a list of them:
+
+- `setters.labelmap3DForElement` is overridden to have a non-blocking behaviour, the custom code is in ./setLabelMap3D.js, same as original code in cs tools repo.

package/imaging/tools/setLabelMap3D.js

@@ -0,0 +1,248 @@
+/**
+ * This is a custom version of setLabelMap3D from cs tools source code
+ * This let us implement a non-blocking version of the for loop that loads 3d labelmaps on a volume
+ * @ronzim
+ */
+
+// import getElement from "./getElement";
+// import { getToolState } from "../../../stateManagement/toolState.js";
+// import state from "./state";
+// import getSegmentsOnPixelData from "./getSegmentsOnPixeldata";
+// import { triggerLabelmapModifiedEvent } from "../../../util/segmentation";
+// import ARRAY_TYPES from "./arrayTypes";
+// import { getModule } from "../../index.js";
+
+const ARRAY_TYPES = {
+  UINT_16_ARRAY: 0,
+  FLOAT_32_ARRAY: 1
+};
+const { UINT_16_ARRAY, FLOAT_32_ARRAY } = ARRAY_TYPES;
+
+import cornerstoneTools from "cornerstone-tools/dist/cornerstoneTools.js";
+const { triggerLabelmapModifiedEvent } = cornerstoneTools.importInternal(
+  "util/segmentationUtils"
+);
+const getModule = cornerstoneTools.getModule;
+const getToolState = cornerstoneTools.getToolState;
+const storeGetters = cornerstoneTools.store.getters;
+const state = getModule("segmentation").state;
+
+/**
+ * These function are reported since they are not exposed by cs tools
+ *
+ */
+
+// from getSegmentsOnPixelData.js
+function getSegmentsOnPixelData(pixelData) {
+  return [...new Set(pixelData)];
+}
+
+// from getElement.js
+function getElement(elementOrEnabledElementUID) {
+  if (elementOrEnabledElementUID instanceof HTMLElement) {
+    return elementOrEnabledElementUID;
+  }
+
+  return storeGetters.enabledElementByUID(elementOrEnabledElementUID);
+}
+
+/**
+ * Takes a 16-bit encoded `ArrayBuffer` and stores it as a `Labelmap3D` for the
+ * `BrushStackState` associated with the element.
+ *
+ * @param  {HTMLElement|string} elementOrEnabledElementUID The cornerstone
+ *                                                  enabled element or its UUID.
+ * @param  {ArrayBuffer} buffer
+ * @param  {number} labelmapIndex The index to store the labelmap under.
+ * @param  {Object[]} metadata = [] Any metadata about the segments.
+ * @param  {number[][]} [segmentsOnLabelmapArray] An array of array of segments on each imageIdIndex.
+ *                       If not present, is calculated.
+ * @param  {colorLUTIndex} [colorLUTIndex = 0] The index of the colorLUT to use to render the segmentation.
+ * @returns {null}
+ */
+async function setLabelmap3DForElement(
+  elementOrEnabledElementUID,
+  buffer,
+  labelmapIndex,
+  metadata = [],
+  segmentsOnLabelmapArray,
+  colorLUTIndex = 0
+) {
+  const element = getElement(elementOrEnabledElementUID);
+
+  if (!element) {
+    return;
+  }
+
+  const stackState = getToolState(element, "stack");
+  const numberOfFrames = stackState.data[0].imageIds.length;
+  const firstImageId = stackState.data[0].imageIds[0];
+
+  const res = await setLabelmap3DByFirstImageId(
+    firstImageId,
+    buffer,
+    labelmapIndex,
+    metadata,
+    numberOfFrames,
+    segmentsOnLabelmapArray,
+    colorLUTIndex
+  );
+
+  triggerLabelmapModifiedEvent(element, labelmapIndex);
+
+  return res;
+}
+
+/**
+ * Takes an 16-bit encoded `ArrayBuffer` and stores it as a `Labelmap3D` for
+ * the `BrushStackState` associated with the firstImageId.
+ *
+ * @param  {HTMLElement|string} firstImageId  The firstImageId of the series to
+ *                                            store the segmentation on.
+ * @param  {ArrayBuffer} buffer
+ * @param  {number} labelmapIndex The index to store the labelmap under.
+ * @param  {Object[]} metadata = [] Any metadata about the segments.
+ * @param  {number} numberOfFrames The number of frames, required to set up the
+ *                                 relevant labelmap2D views.
+ * @param  {number[][]} [segmentsOnLabelmapArray] An array of array of segments on each imageIdIndex.
+ *                       If not present, is calculated.
+ * @param  {colorLUTIndex} [colorLUTIndex = 0] The index of the colorLUT to use to render the segmentation.
+ * @returns {null}
+ */
+function setLabelmap3DByFirstImageId(
+  firstImageId,
+  buffer,
+  labelmapIndex,
+  metadata = [],
+  numberOfFrames,
+  segmentsOnLabelmapArray,
+  colorLUTIndex = 0
+) {
+  const { configuration } = getModule("segmentation");
+
+  let brushStackState = state.series[firstImageId];
+
+  if (!brushStackState) {
+    state.series[firstImageId] = {
+      activeLabelmapIndex: labelmapIndex,
+      labelmaps3D: []
+    };
+
+    brushStackState = state.series[firstImageId];
+  }
+
+  brushStackState.labelmaps3D[labelmapIndex] = {
+    buffer,
+    labelmaps2D: [],
+    metadata,
+    activeSegmentIndex: 1,
+    colorLUTIndex,
+    segmentsHidden: [],
+    undo: [],
+    redo: []
+  };
+
+  const labelmaps2D = brushStackState.labelmaps3D[labelmapIndex].labelmaps2D;
+  const slicelengthInBytes = buffer.byteLength / numberOfFrames;
+
+  /* non-blocking implementation by @ronzim */
+
+  return new Promise(resolve => {
+    function setSingleSlice(i, numberOfFrames) {
+      var pixelData = void 0;
+
+      switch (configuration.arrayType) {
+        case UINT_16_ARRAY:
+          pixelData = new Uint16Array(
+            buffer,
+            slicelengthInBytes * i, // 2 bytes/voxel
+            slicelengthInBytes / 2
+          );
+          break;
+
+        case FLOAT_32_ARRAY:
+          pixelData = new Float32Array(
+            buffer,
+            slicelengthInBytes * i,
+            slicelengthInBytes / 4
+          );
+          break;
+
+        default:
+          throw new Error(
+            "Unsupported Array Type ".concat(configuration.arrayType)
+          );
+      }
+
+      var segmentsOnLabelmap = segmentsOnLabelmapArray
+        ? segmentsOnLabelmapArray[i]
+        : getSegmentsOnPixelData(pixelData);
+
+      if (
+        segmentsOnLabelmap &&
+        segmentsOnLabelmap.some(function (segment) {
+          return segment;
+        })
+      ) {
+        labelmaps2D[i] = {
+          pixelData: pixelData,
+          segmentsOnLabelmap: segmentsOnLabelmap
+        };
+      }
+
+      ++i;
+
+      if (i < numberOfFrames) {
+        setTimeout(() => {
+          setSingleSlice(i, numberOfFrames);
+        }, 0);
+      } else {
+        resolve("OK");
+      }
+    }
+
+    setSingleSlice(0, numberOfFrames);
+  });
+
+  /* original implementation 
+
+  for (let i = 0; i < numberOfFrames; i++) {
+    let pixelData;
+
+    switch (configuration.arrayType) {
+      case UINT_16_ARRAY:
+        pixelData = new Uint16Array(
+          buffer,
+          slicelengthInBytes * i, // 2 bytes/voxel
+          slicelengthInBytes / 2
+        );
+
+        break;
+
+      case FLOAT_32_ARRAY:
+        pixelData = new Float32Array(
+          buffer,
+          slicelengthInBytes * i,
+          slicelengthInBytes / 4
+        );
+        break;
+
+      default:
+        throw new Error(`Unsupported Array Type ${configuration.arrayType}`);
+    }
+
+    const segmentsOnLabelmap = segmentsOnLabelmapArray
+      ? segmentsOnLabelmapArray[i]
+      : getSegmentsOnPixelData(pixelData);
+
+    if (segmentsOnLabelmap && segmentsOnLabelmap.some(segment => segment)) {
+      labelmaps2D[i] = {
+        pixelData,
+        segmentsOnLabelmap
+      };
+    }
+  }
+  */
+}
+
+export { setLabelmap3DByFirstImageId, setLabelmap3DForElement };

package/imaging/tools/{tools.state.js → state.js}

@@ -1,8 +1,14 @@
+/** @module imaging/tools/state
+ *  @desc  This file provides functionalities
+ *         for handling tools' state
+ */
+
 // external libraries
 import cornerstone from "cornerstone-core";
 import cornerstoneTools from "cornerstone-tools";
-
 import { each } from "lodash";
+
+// internal libraries
 import { state_example } from "./cstools_state_example.js";
 
 /**

package/imaging/tools/strategies/eraseFreehand.js

@@ -1,17 +1,16 @@
-import cornerstoneTools from "cornerstone-tools";
-
-const {
-  getBoundingBoxAroundPolygon,
-  eraseInsideShape,
-  eraseOutsideShape
-} = cornerstoneTools.importInternal("util/segmentationUtils");
+/** @module imaging/strategies/eraseFreehand
+ *  @desc  This file provides functionalities for
+ *         erasing pixels
+ */
 
+// external libraries
+import cornerstoneTools from "cornerstone-tools";
+const { getBoundingBoxAroundPolygon, eraseInsideShape, eraseOutsideShape } =
+  cornerstoneTools.importInternal("util/segmentationUtils");
 const isPointInPolygon = cornerstoneTools.importInternal(
   "util/isPointInPolygon"
 );
-
 const getLogger = cornerstoneTools.importInternal("util/getLogger");
-
 const logger = getLogger("util:segmentation:operations:eraseInsideFreehand");
 
 /**

package/imaging/tools/strategies/fillFreehand.js

@@ -1,17 +1,16 @@
-import cornerstoneTools from "cornerstone-tools";
-
-const {
-  getBoundingBoxAroundPolygon,
-  fillInsideShape,
-  fillOutsideShape
-} = cornerstoneTools.importInternal("util/segmentationUtils");
+/** @module imaging/strategies/fillFreehand
+ *  @desc  This file provides functionalities for
+ *         filling pixels
+ */
 
+// external libraries
+import cornerstoneTools from "cornerstone-tools";
+const { getBoundingBoxAroundPolygon, fillInsideShape, fillOutsideShape } =
+  cornerstoneTools.importInternal("util/segmentationUtils");
 const isPointInPolygon = cornerstoneTools.importInternal(
   "util/isPointInPolygon"
 );
-
 const getLogger = cornerstoneTools.importInternal("util/getLogger");
-
 const logger = getLogger("util:segmentation:operations:fillInsideFreehand");
 
 /**