🎉 Metadata Overhaul 3.7.8+ 🎉

[JamesAPetts]

Overview

Hey all,

In 3.7.8 PR #1481 revamped how we deal with metadata in OHIF. The main goal was to address these issues:

• Remove dependency of metadata on specific imageIds, and instead associate metadata with the StudyInstanceUID, SeriesInstanceUID and SOPInstanceUIDs.
  • An example of this would be when the headers are fetched with WADO-RS, and indexed under a WADO-RS imageId, and then the images are fetched with WADO-URI (WADO-RS retrieve frames isn't supported everywhere), and then the images couldn't access their metadata from their own imageId.
• Store metadata in a standardised format (See below).
• Retain backwards compability with libraries such as cornerstoneTools, which expect the metadata to be provided in a legacy format.

The upshot of this is now the following methods of using the application:

• WADO-RS retrieve metadata + WADO-RS retrieve frames,
• WADO-RS retrieve metadata + WADO-URI retrieve instance,
• JSON launch from arbitrary backend which supplies P10 DICOM,
• Local DICOM viewing (drag + drop folder of DICOM),

are all processed in the same way, and provided the DICOM headers are rich, will all be able to access the same functionality. Which was a major issue issue previously.

MetadataProvider

We now have a re-vamped metadata provider in @ohif/core:

import OHIF from '@ohif/core'

const metadataProvider = OHIF.cornerstone.metadataProvider;

With which data can be added via the following method

metadataProvider.addInstance(payload, options = {})

Where the payload is either:

• DICOMJSON (e.g. WADO-RS headers)
• naturalized DICOM JSON (e.g. output from dcmjs)
• P10 DICOM ArrayBuffer (a "DICOM file")

The data is then indexed based on its Study, Series and SOPInstanceUIDs.

This provider is registered to cornerstone with a high priority, and data can then be retrieved by:

const result = cornerstone.metaData.get(query,imageId);

As standard.

The imageId is broken down into it's UIDs if it is a WADO-URI or WADO-RS imageId, and the appropriate resource is fetched. imageIds for JSON launch are auto registered as a route to the correct resource even if they are in some proprietary format, e.g. https://jamesesnicebackend/someStrangeRoute/dicom_1 .

The queries you may give are:

• Any naturalized DICOMJSON tag. If a sequence is requested, the whole sequence will be returned.
• "instance" - Returns the entire naturalized DICOMJSON instance.
• "legacy" requests such as "imagePlaneModule", "voiLutModule", etc. Data is aggregated from the underlying DICOMJSON and is returned in the same form as cornerstoneWADOImageLoader and react-cornerstone-viewport define.

JSON Launch

JSON launch has had its schema changed, to contain naturalized DICOM JSON headers:

{
    "studies": [
      {
        "StudyInstanceUID": "1.2.840.113619.2.5.1762583153.215519.978957063.78",
        "StudyDescription": "BRAIN SELLA",
        "StudyDate": "20010108",
        "StudyTime": "120022",
        "PatientName": "MISTER^MR",
        "PatientId": "832040",
        "series": [
          {
            "SeriesDescription": "SAG T-1",
            "SeriesInstanceUID": "1.2.840.113619.2.5.1762583153.215519.978957063.121",
            "SeriesNumber": 2,
            "SeriesDate": "20010108",
            "SeriesTime": "120318",
            "Modality": "MR",
            "instances": [
              {
                "metadata": {
                    "Columns": 512,
                    "Rows": 512,
                    "InstanceNumber": 3,
                    "AcquisitionNumber": 0,
                    "PhotometricInterpretation": "MONOCHROME2",
                    "BitsAllocated": 16,
                    "BitsStored": 16,
                    "PixelRepresentation": 1,
                    "SamplesPerPixel": 1,
                    "PixelSpacing": [0.390625, 0.390625],
                    "HighBit": 15,
                    "ImageOrientationPatient": [0,1,0,0,0,-1],
                    "ImagePositionPatient": [11.600000,-92.500000, 98.099998],
                    "FrameOfReferenceUID": "1.2.840.113619.2.5.1762583153.223134.978956938.470",
                    "ImageType": ["ORIGINAL","PRIMARY","OTHER"],
                    "Modality": "MR",
                    "SOPInstanceUID": "1.2.840.113619.2.5.1762583153.215519.978957063.124",
                    "SeriesInstanceUID": "1.2.840.113619.2.5.1762583153.215519.978957063.121",
                    "StudyInstanceUID": "1.2.840.113619.2.5.1762583153.215519.978957063.78"
                },
                "url": "dicomweb://s3.amazonaws.com/lury/MRStudy/1.2.840.113619.2.5.1762583153.215519.978957063.124.dcm"
             }
           ]
         }
       ]
     }
   ]
}

The format is the same as before, but note seriesList has been renamed series, and under instances there are now only 2 properties:

• metadata - DICOM JSON formatted metadata.
• url - The url to the Part 10 DICOM.

Above shows the minimum data required to use all functionality in OHIF at the time of writing. However in the general sense, if you return a full naturalized DICOM JSON header in the metadata property, all future content added to the repo that works with a full DICOMWeb implementation should work.

naturalized DICOM JSON as the source of truth

Throughout the app any DICOM keywords have been capitalized as they are in the standard, e.g.: sopInstanceUid, sopInstanceUID, etc have all become SOPInstanceUID. All naturalized DICOM variables should follow this practice across the application.

Naturalized DICOM JSON is DICOM JSON where the tag names are replaced with keywords, single values replaced with strings or numbers, multiple values replaced with arrays, and sequences replaced with arrays. I.e. human readable DICOM.

You can naturalize any DICOMJSON (e.g. a WADO-RS header for an instance) with dcmjs:

const naturalizedDataset = dcmjs.data.DicomMetaDictionary.naturalizeDataset(
   dicomJSONDataset
);

Which is probably the best way to look at the format at this time, by example. At this time dcmjs documentation could do with some love.

I believe that is all for now. Happy DICOM-ing!

[swederik]

FYI @nutzlastfan @Zaid-Safadi