larvitar 1.5.13 → 2.0.0

package/imaging/{imageParsing.js → imageParsing.ts}

@@ -3,17 +3,22 @@
  */
 
 // external libraries
-import { parseDicom } from "dicom-parser";
+import { DataSet, parseDicom } from "dicom-parser";
 import { forEach, each, has, pick } from "lodash";
 import { v4 as uuidv4 } from "uuid";
 
 // internal libraries
-import { getPixelRepresentation, randomId, parseTag } from "./imageUtils.js";
-import { updateLoadedStack } from "./imageLoading.js";
-import { checkMemoryAllocation } from "./monitors/memory.js";
+import { getPixelRepresentation, randomId } from "./imageUtils";
+import { parseTag } from "./imageTags";
+import { updateLoadedStack } from "./imageLoading";
+import { checkMemoryAllocation } from "./monitors/memory";
+import { ImageObject, Instance, MetaData, Series } from "./types";
+import { getLarvitarManager } from "./loaders/commonLoader";
+import type { MetaDataTypes } from "./MetaDataTypes";
+import { NrrdSeries } from "./loaders/nrrdLoader";
 
 // global module variables
-var t0 = null; // t0 variable for timing debugging purpose
+var t0: number; // t0 variable for timing debugging purpose
 
 /*
  * This module provides the following functions to be exported:
@@ -29,14 +34,18 @@ var t0 = null; // t0 variable for timing debugging purpose
  * @function clearImageParsing
  * @param {Object} seriesStack - Parsed series stack object
  */
-export const clearImageParsing = function (seriesStack) {
-  each(seriesStack, function (stack) {
-    each(stack.instances, function (instance) {
+export const clearImageParsing = function (
+  seriesStack: ReturnType<typeof getLarvitarManager> | null
+) {
+  each(seriesStack, function (stack: Series | NrrdSeries) {
+    each(stack.instances, function (instance: Instance) {
       if (instance.dataSet) {
+        // @ts-ignore
         instance.dataSet.byteArray = null;
       }
       instance.dataSet = null;
       instance.file = null;
+      // @ts-ignore
       instance.metadata = null;
     });
   });
@@ -50,11 +59,8 @@ export const clearImageParsing = function (seriesStack) {
  * @param {Array} entries - List of file objects
  * @returns {Promise} - Return a promise which will resolve to a image object list or fail if an error occurs
  */
-export const readFiles = function (entries) {
-  let promise = new Promise((resolve, reject) => {
-    parseFiles(entries).then(resolve).catch(reject);
-  });
-  return promise;
+export const readFiles = function (entries: File[]) {
+  return parseFiles(entries);
 };
 
 /**
@@ -64,15 +70,24 @@ export const readFiles = function (entries) {
  * @param {File} entry - File object
  * @returns {Promise} - Return a promise which will resolve to a image object or fail if an error occurs
  */
-export const readFile = function (entry) {
-  let promise = new Promise((resolve, reject) => {
-    parseFile(entry).then(resolve).catch(reject);
-  });
-  return promise;
+export const readFile = function (entry: File) {
+  return parseFile(entry);
 };
 
 /* Internal module functions */
 
+//This type is used to instantiate metadata and nested objects in imageParsing in order to allow dynamic setting
+//of MetaDataTypes objects' properties.
+//In other words, metadata : ExtendedMetaDataTypes is useful and substitutes metadata : MetaDataTypes when metadata values
+//aren't called explicitly using metadata['xGGGGEEEEE']
+//and are instead called using TAG as a variable (i.e. metadata[TAG]).
+//It is important to highlight that even if we set metadata[TAG]=tagValue; whose type (of tagValue) is the correct one (returned by ParseTag).
+//if we then extract x=metadata[TAG]; we obtain tagValue : unknown and a casting with : MetaDataType[typeof TAG] is necessary.
+
+type ExtendedMetaDataTypes = MetaDataTypes & {
+  [key: string]: unknown;
+};
+
 /**
  * Parse metadata from dicom parser dataSet object
  * @instance
@@ -82,7 +97,12 @@ export const readFile = function (entry) {
  * @param {Array} customFilter - Optional filter: {tags:[], frameId: 0}
  */
 // This function iterates through dataSet recursively and store tag values into metadata object
-export const parseDataSet = function (dataSet, metadata, customFilter) {
+
+export const parseDataSet = function (
+  dataSet: DataSet,
+  metadata: ExtendedMetaDataTypes,
+  customFilter?: { tags: string[]; frameId: number }
+) {
   // customFilter= {tags:[], frameId:xxx}
   // the dataSet.elements object contains properties for each element parsed.  The name of the property
   // is based on the elements tag and looks like 'xGGGGEEEE' where GGGG is the group number and EEEE is the
@@ -90,39 +110,60 @@ export const parseDataSet = function (dataSet, metadata, customFilter) {
   // be named 'x0008103e'.  Here we iterate over each property (element) so we can build a string describing its
   // contents to add to the output array
   try {
-    let elements =
-      customFilter && has(customFilter, "tags")
-        ? pick(dataSet.elements, customFilter.tags)
-        : dataSet.elements;
+    let elements = dataSet.elements;
+
+    customFilter && has(customFilter, "tags")
+      ? pick(dataSet.elements, customFilter.tags)
+      : dataSet.elements;
     for (let propertyName in elements) {
-      let element = elements[propertyName];
-      // Here we check for Sequence items and iterate over them if present.  items will not be set in the
+      let element = elements[propertyName]; //metadata
+      const TAG = propertyName as keyof ExtendedMetaDataTypes;
+      // Here we check for Sequence items and iterate over them if present. items will not be set in the
       // element object for elements that don't have SQ VR type.  Note that implicit little endian
       // sequences will are currently not parsed.
       if (element.items) {
-        // each item contains its own data set so we iterate over the items
-        // and recursively call this function
-        if (customFilter && has(customFilter, "frameId")) {
-          let item = element.items[customFilter.frameId];
-          parseDataSet(item.dataSet, metadata);
-        } else {
-          element.items.forEach(function (item) {
-            parseDataSet(item.dataSet, metadata);
-          });
-        }
-      } else {
-        let tagValue = parseTag(dataSet, propertyName, element);
+        let nestedArray: MetaDataTypes[] = [];
 
+        // iterates over nested elements (nested metadata)
+        element.items.forEach(function (item) {
+          let nestedObject: ExtendedMetaDataTypes = {};
+          for (let nestedPropertyName in item.dataSet!.elements) {
+            let TAG_tagValue = nestedPropertyName as keyof MetaDataTypes;
+
+            let tagValue = parseTag<MetaDataTypes[typeof TAG_tagValue]>(
+              item.dataSet!,
+              nestedPropertyName,
+              item.dataSet!.elements[nestedPropertyName]
+            );
+
+            let TAG_nested = nestedPropertyName as keyof ExtendedMetaDataTypes;
+            nestedObject[TAG_nested] = tagValue;
+            //see MetaDataTypes.ts last property to understand how this dynamic value setting is possible
+          }
+          nestedArray.push(nestedObject);
+        });
+        metadata[TAG] = nestedArray;
+      } else {
+        let TAG_tagValue = propertyName as keyof MetaDataTypes;
+        let tagValue = parseTag<MetaDataTypes[typeof TAG_tagValue]>(
+          dataSet,
+          propertyName,
+          element
+        );
+        let TAG = propertyName as keyof ExtendedMetaDataTypes;
         // identify duplicated tags (keep the first occurency and store the others in another tag eg x00280010_uuid)
-        if (metadata[propertyName] !== undefined) {
+        if (metadata[TAG] !== undefined) {
           console.debug(
             `Identified duplicated tag "${propertyName}", values are:`,
-            metadata[propertyName],
+            metadata[TAG],
             tagValue
           );
-          metadata[propertyName + "_" + uuidv4()] = tagValue;
+          let TAG_uuidv4 = (propertyName +
+            "_" +
+            uuidv4()) as keyof ExtendedMetaDataTypes;
+          metadata[TAG_uuidv4] = tagValue;
         } else {
-          metadata[propertyName] = tagValue;
+          metadata[TAG] = tagValue;
         }
       }
     }
@@ -142,11 +183,11 @@ export const parseDataSet = function (dataSet, metadata, customFilter) {
  * @param {Function} reject - Promise reject function
  */
 let parseNextFile = function (
-  parsingQueue,
-  allSeriesStack,
-  uuid,
-  resolve,
-  reject
+  parsingQueue: File[],
+  allSeriesStack: ReturnType<typeof getLarvitarManager>,
+  uuid: string,
+  resolve: Function,
+  reject: Function
 ) {
   // initialize t0 on first file of the queue
   if (
@@ -164,7 +205,12 @@ let parseNextFile = function (
   }
 
   // remove and return first item from queue
-  let file = parsingQueue.shift();
+  let file = parsingQueue.shift() as File | undefined | null;
+
+  if (!file) {
+    console.warn("File is undefined or null");
+    return;
+  }
 
   // Check if there is enough memory to parse the file
   if (checkMemoryAllocation(file.size) === false) {
@@ -178,18 +224,18 @@ let parseNextFile = function (
   } else {
     // parse the file and wait for results
     parseFile(file)
-      .then(seriesData => {
+      .then((seriesData: ImageObject | null) => {
         // use generated series uid if not found in dicom file
-        seriesData.metadata.seriesUID = seriesData.metadata.seriesUID || uuid;
+        seriesData!.metadata.seriesUID = seriesData!.metadata.seriesUID || uuid;
         // add file to cornerstoneDICOMImageLoader file manager
-        updateLoadedStack(seriesData, allSeriesStack);
+        updateLoadedStack(seriesData!, allSeriesStack);
         // proceed with the next file to parse
         parseNextFile(parsingQueue, allSeriesStack, uuid, resolve, reject);
         seriesData = null;
         file = null;
       })
       .catch(err => {
-        console.warn(err);
+        console.error(err);
         parseNextFile(parsingQueue, allSeriesStack, uuid, resolve, reject);
         file = null;
       });
@@ -203,11 +249,11 @@ let parseNextFile = function (
  * @param {Array} fileList - Array of file objects
  * @returns {Promise} - Return a promise which will resolve to a image object list or fail if an error occurs
  */
-let parseFiles = function (fileList) {
+const parseFiles = function (fileList: File[]) {
   let allSeriesStack = {};
-  let parsingQueue = [];
+  let parsingQueue: File[] = [];
 
-  forEach(fileList, function (file) {
+  forEach(fileList, function (file: File) {
     if (!file.name.startsWith(".") && !file.name.startsWith("DICOMDIR")) {
       parsingQueue.push(file);
     }
@@ -225,45 +271,66 @@ let parseFiles = function (fileList) {
  * @param {File} file - File object to be parsed
  * @returns {Promise} - Return a promise which will resolve to a image object or fail if an error occurs
  */
-let parseFile = function (file) {
-  let parsePromise = new Promise((resolve, reject) => {
+const parseFile = function (file: File) {
+  const parsePromise = new Promise<ImageObject>((resolve, reject) => {
     let reader = new FileReader();
     reader.onload = function () {
       let arrayBuffer = reader.result;
       // Here we have the file data as an ArrayBuffer.
       // dicomParser requires as input a Uint8Array so we create that here.
-      let byteArray = new Uint8Array(arrayBuffer);
+
+      if (!arrayBuffer || typeof arrayBuffer === "string") {
+        reject("Error reading file");
+        return;
+      }
+
+      let byteArray: Uint8Array | null = new Uint8Array(arrayBuffer);
       let dataSet;
 
+      // this try-catch is used to handle non-DICOM files: log error but continue parsing the other files
       try {
         dataSet = parseDicom(byteArray);
         byteArray = null;
-        let metadata = {};
+        let metadata: MetaData = {};
         parseDataSet(dataSet, metadata);
 
         let temporalPositionIdentifier = metadata["x00200100"]; // Temporal order of a dynamic or functional set of Images.
         let numberOfTemporalPositions = metadata["x00200105"]; // Total number of temporal positions prescribed.
         const is4D =
-          (temporalPositionIdentifier !== undefined) &
-          (numberOfTemporalPositions > 1)
+          temporalPositionIdentifier !== undefined &&
+          (numberOfTemporalPositions as number) > 1
             ? true
             : false;
 
-        let numberOfFrames = metadata["x00280008"];
-        let isMultiframe = numberOfFrames > 1 ? true : false;
-        // Overwrite SOPInstanceUID to manage multiframes.
+        let modality = metadata["x00080060"] as string;
+        let singleFrameModalities = [
+          "CR",
+          "DX",
+          "MG",
+          "PX",
+          "RF",
+          "XA",
+          "US",
+          "IVUS",
+          "OCT"
+        ];
+        // US XA RF IVUS OCT DX CR PX MG
+        // Overwrite SOPInstanceUID to manage single stack images (US, XA).
         // Usually different SeriesInstanceUID means different series and that value
         // is used into the application to group different instances into the same series,
         // but if a DICOM file contains a multiframe series, then the SeriesInstanceUID
         // can be shared by other files of the same study.
-        // In multiframe cases, the SOPInstanceUID (unique) is used as SeriesInstanceUID.
-        let seriesInstanceUID = isMultiframe
+        // In these cases, the SOPInstanceUID (unique) is used as SeriesInstanceUID.
+        let uniqueId = singleFrameModalities.includes(modality)
           ? metadata["x00080018"]
           : metadata["x0020000e"];
+        let seriesInstanceUID = metadata["x0020000e"];
         let pixelSpacing = metadata["x00280030"];
         let imageOrientation = metadata["x00200037"];
         let imagePosition = metadata["x00200032"];
         let sliceThickness = metadata["x00180050"];
+        let numberOfFrames = metadata["x00280008"];
+        let isMultiframe = (numberOfFrames as number) > 1 ? true : false;
 
         if (dataSet.warnings.length > 0) {
           // warnings
@@ -274,24 +341,28 @@ let parseFile = function (file) {
           if (pixelDataElement) {
             // done, pixelDataElement found
             let instanceUID = metadata["x00080018"] || randomId();
-            let imageObject = {
+            let imageObject: Partial<ImageObject> = {
               // data needed for rendering
               file: file,
               dataSet: dataSet
             };
-            imageObject.metadata = metadata;
+            imageObject.metadata = metadata as MetaData;
             imageObject.metadata.anonymized = false;
+            imageObject.metadata.larvitarSeriesInstanceUID = uniqueId;
             imageObject.metadata.seriesUID = seriesInstanceUID;
             imageObject.metadata.instanceUID = instanceUID;
             imageObject.metadata.studyUID = metadata["x0020000d"];
             imageObject.metadata.accessionNumber = metadata["x00080050"];
             imageObject.metadata.studyDescription = metadata["x00081030"];
-            imageObject.metadata.patientName = metadata["x00100010"];
+            imageObject.metadata.patientName = metadata["x00100010"] as string;
             imageObject.metadata.patientBirthdate = metadata["x00100030"];
-            imageObject.metadata.seriesDescription = metadata["x0008103e"];
+            imageObject.metadata.seriesDescription = metadata[
+              "x0008103e"
+            ] as string;
             imageObject.metadata.seriesDate = metadata["x00080021"];
-            imageObject.metadata.seriesModality =
-              metadata["x00080060"].toLowerCase();
+            imageObject.metadata.seriesModality = metadata["x00080060"]
+              ?.toString()
+              .toLowerCase();
             imageObject.metadata.intercept = metadata["x00281052"];
             imageObject.metadata.slope = metadata["x00281053"];
             imageObject.metadata.pixelSpacing = pixelSpacing;
@@ -307,6 +378,9 @@ let parseFile = function (file) {
             if (isMultiframe) {
               imageObject.metadata.frameTime = metadata["x00181063"];
               imageObject.metadata.frameDelay = metadata["x00181066"];
+              if (metadata["x00186060"]) {
+                imageObject.metadata.rWaveTimeVector = metadata["x00186060"];
+              }
             }
             imageObject.metadata.isMultiframe = isMultiframe;
             if (is4D) {
@@ -323,38 +397,42 @@ let parseFile = function (file) {
             imageObject.metadata.maxPixelValue = metadata["x00280107"];
             imageObject.metadata.length = pixelDataElement.length;
             imageObject.metadata.repr = getPixelRepresentation(dataSet);
-            resolve(imageObject);
+            resolve(imageObject as ImageObject);
           } else if (SOPUID == "1.2.840.10008.5.1.4.1.1.104.1") {
-            let pdfObject = {
+            let pdfObject: Partial<ImageObject> = {
               // data needed for rendering
               file: file,
               dataSet: dataSet
             };
             pdfObject.metadata = metadata;
+            pdfObject.metadata.larvitarSeriesInstanceUID = uniqueId;
             pdfObject.metadata.seriesUID = seriesInstanceUID;
-            pdfObject.instanceUID = metadata["x00080018"] || randomId();
+            pdfObject.instanceUID =
+              metadata["x00080018"]?.toString() || randomId();
             pdfObject.metadata.studyUID = metadata["x0020000d"];
             pdfObject.metadata.accessionNumber = metadata["x00080050"];
             pdfObject.metadata.studyDescription = metadata["x00081030"];
-            pdfObject.metadata.patientName = metadata["x00100010"];
+            pdfObject.metadata.patientName = metadata["x00100010"] as string;
             pdfObject.metadata.patientBirthdate = metadata["x00100030"];
             pdfObject.metadata.seriesDate = metadata["x00080021"];
-            pdfObject.metadata.seriesModality =
-              metadata["x00080060"].toLowerCase();
+            pdfObject.metadata.seriesModality = metadata["x00080060"]
+              ?.toString()
+              .toLowerCase();
             pdfObject.metadata.mimeType = metadata["x00420012"];
             pdfObject.metadata.is4D = false;
             pdfObject.metadata.numberOfFrames = 0;
             pdfObject.metadata.numberOfSlices = 0;
             pdfObject.metadata.numberOfTemporalPositions = 0;
-            resolve(pdfObject);
+            resolve(pdfObject as ImageObject);
           } else {
             // done, no pixelData
             reject("no pixelData");
           }
         }
       } catch (err) {
-        console.warn(err);
-        reject("can not read this file");
+        reject(
+          `Larvitar: can not read file "${file.name}" \nParsing error: ${err}`
+        );
       }
     };
     reader.readAsArrayBuffer(file);

package/imaging/{imagePresets.js → imagePresets.ts}

@@ -8,7 +8,7 @@ import cornerstone from "cornerstone-core";
 import { each, find } from "lodash";
 
 // internal libraries
-import { larvitar_store } from "./imageStore";
+import { set as setStore } from "./imageStore";
 
 /**
  * Object used to list image presets
@@ -46,24 +46,35 @@ export const getImagePresets = function () {
  * @instance
  * @function setImagePreset
  * @param {Array} viewportNames - List of viewports where to apply preset
- * @param {String} preset_name - The image preset name
+ * @param {String} preset - The image preset name or the preset object
  */
-export const setImagePreset = function (viewportNames, preset_name) {
+export const setImagePreset = function (
+  viewportNames: string[],
+  preset: string | (typeof IMAGE_PRESETS)[0]
+) {
   if (!Array.isArray(viewportNames)) {
     console.error(
       "Invalid parameter, viewportNames has to be an array of viewport names."
     );
     return;
   }
-  let image_preset = find(IMAGE_PRESETS, { name: preset_name });
+  let image_preset =
+    typeof preset === "string" ? find(IMAGE_PRESETS, { name: preset }) : preset;
+
   if (!image_preset) {
     console.error("Invalid image preset");
     return;
   }
-  each(viewportNames, function (viewportName) {
+
+  each(viewportNames, function (viewportName: string) {
     let element = document.getElementById(viewportName);
     let enabledElement;
 
+    if (!element) {
+      console.warn("No element with id", viewportName);
+      return;
+    }
+
     try {
       enabledElement = cornerstone.getEnabledElement(element);
     } catch {
@@ -72,11 +83,18 @@ export const setImagePreset = function (viewportNames, preset_name) {
     }
 
     let viewport = cornerstone.getViewport(element);
-    viewport.voi.windowWidth = image_preset.ww;
-    viewport.voi.windowCenter = image_preset.wl;
+
+    if (!viewport) {
+      console.warn("No viewport with id", viewportName);
+      return;
+    }
+
+    viewport.voi.windowWidth = image_preset!.ww;
+    viewport.voi.windowCenter = image_preset!.wl;
     cornerstone.setViewport(element, viewport);
     // sync ww and wc values in store
-    larvitar_store.set("contrast", [
+    setStore([
+      "contrast",
       viewportName,
       viewport.voi.windowWidth,
       viewport.voi.windowCenter
@@ -91,17 +109,25 @@ export const setImagePreset = function (viewportNames, preset_name) {
  * @param {Array} viewportNames - List of viewports where to apply preset
  * @param {Object} customValues - {wl: value, ww: value}
  */
-export const setImageCustomPreset = function (viewportNames, customValues) {
+export const setImageCustomPreset = function (
+  viewportNames: string[],
+  customValues: { wl: number; ww: number }
+) {
   if (!Array.isArray(viewportNames)) {
     console.error(
       "Invalid parameter, viewportNames has to be an array of viewport names."
     );
     return;
   }
-  each(viewportNames, function (viewportName) {
+  each(viewportNames, function (viewportName: string) {
     let element = document.getElementById(viewportName);
     let enabledElement;
 
+    if (!element) {
+      console.warn("No element with id", viewportName);
+      return;
+    }
+
     try {
       enabledElement = cornerstone.getEnabledElement(element);
     } catch {
@@ -110,11 +136,18 @@ export const setImageCustomPreset = function (viewportNames, customValues) {
     }
 
     let viewport = cornerstone.getViewport(element);
+
+    if (!viewport) {
+      console.warn("No viewport with id", viewportName);
+      return;
+    }
+
     viewport.voi.windowWidth = customValues.ww;
     viewport.voi.windowCenter = customValues.wl;
     cornerstone.setViewport(element, viewport);
     // sync ww and wc values in store
-    larvitar_store.set("contrast", [
+    setStore([
+      "contrast",
       viewportName,
       viewport.voi.windowWidth,
       viewport.voi.windowCenter