This tool can be used to convert a DICOM Structured Report object that follows template TID1500 into a JSON representation of the measurements. The converter was developed and tested specifically to recognize SR TID1500 objects that store measurements derived from volumetric rasterized segmentations. It will not work for other use cases of TID1500.
dcmqi provides command line tools to convert lists of measurements calculated from the images for the regions defined by rasterized segmentations into DICOM representation. Specifically, the DICOM representation suitable for such data is DICOM Structured Reporting (SR) Template ID 1500.
Each measurement is associated with a specific segment in the corresponding DICOM Segmentation object. For each measurements, Quantity, Units and Derivation (when appropriate) must be specified as coded tuples. Multiple measurements can be assigned in a list for the individual segment.
At the moment, the measurements must be specified in a JSON file, such as the one shown in this example. It is in our plans to provide support of the CSV format for bi-directional conversion of the measurements data.
You can use this online validator to check if the JSON file you are passing to the converter is conforming to the schema: https://qiicr.org/dcmqi/#/validators.
This tool can be used to save measurements calculated from the image over a volume defined by image segmentation into a DICOM Structured Report that follows template TID1500.
Most of the effort will be required to populate the content of the meta-information JSON file. Its structure is defined by this JSON-Schema file. Interpretation of JSON-Schema may require some effort, especially considering that this particular file uses externally defined items. It may be easier to start with an example JSON file that "instantiates" this schema, such as this one.
In the following, we will guide you through the contents of this file - line by line.
This opening line references the schema this parameter file should conform to. Make sure you include this line without changes!
These lines define top-level attributes of the resulting DICOM object. You can change these to adjust to your needs, subject to some constraints that are not covered here for now.
These two items contain lists of file names that should exist in the directories specified by the --compositeContextDataDir and --imageLibraryDataDir, correspondingly. You should include the file with the DICOM Segmentation object defining the segmented region in the compositeContext attribute!
These are the attributes of either the person that performed the measurements. If you want to list the device instead of a person, it is also possible, but should be done differently. Please ask about details.
Values for VerificationFlag can be one of VERIFIED or UNVERIFIED. CompletionFlag values are either PARTIAL or COMPLETE.
activitySession attribute can be used to encode session number, when, for example, the same structure was segmented multiple times. timePoint can be used in the situation of longitudinal tracking of the measurements.
This is the beginning of the structure where the actual measurements are stored. The measurements are stored hierarchically, and can include 1 or more measurement groups, where each measurement group encodes one or more measurement items.
For each measurement group, you will need to define certain common attributes shared by all measurement items within that group:
TrackingIdentifier is a human-readable string naming the group
ReferencedSegment is the ID of the segment within the DICOM segmentation object that defines the region used to calculate the measurement.
SourceSeriesForImageSegmentation is the SeriesInstanceUID of the original image series on which the segmentation was created.
segmentationSOPInstanceUID is the SOPInstanceUID of the DICOM Segmentation object.
Finding is a triplet of (code, codingSchemeDesignator, codeMeaning) defining the finding over which the measurement is being performed. You can read more about how these triples are defined here.
Finally, measurementItems contains the list of individual measurement. Each measurement is encoded by specifying the following properties:
value: the number, the actual measurement
quantity: code triplet encoding the quantity.
units: code triplet defining the units corresponding of the value. DICOM is using the Unified Code for Units of Measure (UCUM) system for encoding units.
derivationModifier: code triplet encoding the quantity modifier.
The most challenging part of encoding measurements is arguably the process of identifying the codes corresponding to the quantity and derivation modifier (if necessary). You may want to read the discussion on this topic on p.19 of this paper. For practical purposes, you can study the measurements encoded in this example and follow the pattern: https://github.com/QIICR/dcmqi/blob/master/doc/sr-tid1500-ct-liver-example.json. In the future, we will add more details, more examples, and more user-level tools to simplify the process of selecting such codes.
Once you generated the output DICOM object using tid1500writer tool, it is always a very good idea to validate the resulting object. For this purpose we recommend DicomSRValidator tool from the Pixelmed toolkit:
You can also examine the content of the resulting document with various tools such as dcsrdump from the dicom3tools suite
or (more colorful!) dsrdump from DCMTK
You can also use dicom-dump plugin in the Atom editor to conveniently view the content without having to use the terminal.
*
