🎉 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

[shlomgad]

Hello, Using the JSON launch method, compared to version 1 of the viewer, many metadata items have been added as a requirement. Many of them (if not all) like "Columns" and "Rows" for example (as well as most pixel related metadata in the example above), are present in the dicom instance metadata and are available for the viewer once the dicom instance has been retrieved using its url. So why is this required ? Implementing this on a production web app is inefficient because it requires either preparing the metadata in advance for each study - which produces a lot of redundant data (for example, for a 2000 images MRI study, with 10 series, the StudyInstanceUID field repeats 2011 times (1 for the study level, 1 for each series and 1 for each image), or producing the metadata on the fly, which requires unnecessary compute and time (for the same reasons). The previous version of the viewer was able to render images with much less metadata. So, is there a way to get the required metadata from the dicom instances after retrieval?

[shlomgad]

What is the correct JSON for loading multiframe images ? Should the "instances" key be repeated for each frame ? (I think this is not consistent with the DICOM information model where one instance can have many frames). Or is there a "frames" section in the JSON ? Can someone point to the correct path ?

[VinayBaviri]

Hii all, I recently started integrating OHIF viewer for displaying DICOM images with the JSON support. I observed that we need to change ROWS, COLUMNS properties in metadata object to render DICOM images perfectly without dis-alignment.

Is there any support to give ROWS, COLUMNS values like AUTO 🤔 . or How can i get metadata of a DICOM file located in public url 🤔 . So that we can extract that data and form JSON accordingly.

[pmd23]

I am able to view dicom images but I am facing issue with SR files to load it using json. How to load SR dicom images using this json file?

[joeciti]

Similar to pmd23, I can view standard DICOM images but not DICOM-RT using the JSON method as the following tags are missing:

DicomTag.AcquisitionNumber: False DicomTag.PixelSpacing: False DicomTag.ImageOrientationPatient: False DicomTag.ImagePositionPatient: False DicomTag.FrameOfReferenceUID: False.

Any suggestions? Thanks in advance for your help.