Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

馃帀 Metadata Overhaul 3.7.8+ 馃帀 #1500

JamesAPetts opened this issue Mar 10, 2020 · 6 comments

馃帀 Metadata Overhaul 3.7.8+ 馃帀 #1500

JamesAPetts opened this issue Mar 10, 2020 · 6 comments


Copy link


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.


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:

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://"

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 =

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!

@JamesAPetts JamesAPetts pinned this issue Mar 10, 2020
@dannyrb dannyrb changed the title Metadata Overhaul 3.7.8+ 馃帀 Metadata Overhaul 3.7.8+ Mar 10, 2020
@dannyrb dannyrb changed the title 馃帀 Metadata Overhaul 3.7.8+ 馃帀 Metadata Overhaul 3.7.8+ 馃帀 Mar 10, 2020
@dannyrb dannyrb self-assigned this Mar 10, 2020
Copy link

FYI @nutzlastfan @Zaid-Safadi

Copy link

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?

Copy link

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 ?

@swederik swederik unpinned this issue Sep 1, 2021
Copy link

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 馃 .
How can i get metadata of a DICOM file located in public url 馃 . So that we can extract that data and form JSON accordingly.

Copy link

pmd23 commented Sep 28, 2021

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?

Copy link

joeciti commented Oct 5, 2021

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet

No branches or pull requests

8 participants