dcmqi provides a set of command line tools that perform conversion between research formats and .

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.

Usage

Usage details

Most of the effort will be required to populate the content of the meta-information JSON file. Its structure is defined by 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 .

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

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

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 . For practical purposes, you can study the measurements encoded in this example and follow the pattern: . 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 :

You can also examine the content of the resulting document with various tools such as from the suite

or (more colorful!) from

You can also use in the to conveniently view the content without having to use the terminal.

Examples

Encoding measurements over segmentation of liver in CT

*

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.

dcmqi provides command line tools to convert rasterized segmentations stored in commonly used research formats, such as NRRD or NIfTI, into DICOM Segmentation image storage (DICOM Segmentation) object.

DICOM Segmentations are organized as a lists of segments, where each segment corresponds to a separate object/label being segmented. Segments can overlap (i.e., a single voxel of the source image can have multiple labels). Each segment contains information about what it describes, and what method was used to generate it.

To perform the conversion to DICOM, the segmentation (image volume representing the labeling of the individual image voxels) needs to be accompanied by a JSON file that describes segmentation metadata (such as the one in this example), and by the DICOM dataset corresponding to the source image data being segmented. The source DICOM dataset is used to populate metadata attributes that are inherited by the segmentation (i.e., composite context), such as information about patient and imaging study.

Conversion from DICOM Segmentation to research formats produces one file per segment saving the labeled image raster in the research format, such as NRRD or NIfTI, and a metadata JSON file.

itkimage2segimage tool can be used to save the volumetric segmentation(s) stored as labeled pixels using any of the formats supported by ITK, such as NRRD or NIFTI, as a DICOM Segmentation Object (further referred to as SEG).

Usage

Detailed usage

Most of the effort will be required to populate the content of the meta-information JSON file. You can use the that provides a user interface to help with populating the content of the metadata JSON file. The details are discussed below.

The structure of the metadata JSON is defined by 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 .

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 correspond to the metadata attributes that will be populated in the resulting DICOM SEG object. It is your choice how you want to populate those. There are certain constraints on the values of these attributes. If those constraints are not met, converter will fail. In the future, we will provide instructions for validating your meta-information file.

The remainder of the file is a nested list (top-level list corresponds to the input segmentation files, and the inner list corresponds to the individual segments within each file) that specifies metadata attributes for each of the segments that are present in the input segmentation files.

For each of the segments, you will need to specify the following attributes that are mandatory:

labelID defines the value of the segment in the segmentation file that will be assigned attributes listed.

WARNING: labelID is not stored in the output DICOM! The sole purpose of this attribute is to establish the connection between the labels encoded in the input ITK files and the metadata describing those labels (segments). The output DICOM files will have segments numbered consecutively starting from 1, and labelID should not be used to encode the type of structure being segmented. What the segment actually represents is indicated by a set of "codes": SegmentedPropertyCategoryCodeSequence, SegmentedPropertyTypeCodeSequence, and SegmentedPropertyTypeModifierCodeSequence (optionally), as discussed below.

Note that if you really wanted to preserve a particular identifier from a source format, though DICOM SegmentNumber is required to start from 1 and increase by 1 (and is used for internal reference within the segment instance), SegmentLabel can be anything that fits within a 64 character string.

E.g., one could write:

and

or

or

or, what the standard recommends but does not mandate (use CodeMeaning of SegmentedPropertyTypeCodeSequence):

Note that the anatomic region (where the primary tumor is) can be coded separately.

SegmentDescription is a short free-text description of the segment.

SegmentAlgorithmType can be assigned to MANUAL, SEMIAUTOMATIC or AUTOMATIC. If the value of this attribute is not MANUA, SegmentAlgorithmName attribute is required to be initialized!

This attribute should be used to assign short name of the algorithm used to perform the segmentation.

This attribute can be used to specify the RGB color with the recommended. Alternatively, RecommendedDisplayCIELabValue attribute can be used to specify the color in CIELab color space.

SegmentedPropertyCategoryCodeSequence and SegmentedPropertyCategoryCodeSequence are attributes that should be assigned code tuples to describe the meaning of what is being segmented.

Each code tuple consists of the three components: CodeValue, CodingSchemeDesignator and CodeMeaning. CodingSchemeDesignator defines the "authority", or source of the code. Each CodeValue should be unique for a given CodingSchemeDesignator. CodeMeaning is a human-readable meaning of the code. DICOM defines several coding schemes recognized by the standard listed .

The task of selecting a code to describe a given segment may not be trivial, since there are implicit constraints/expectations on the values of these codes. As an example, the possible values of SegmentedPropertyTypeCodeSequence are predicated on the value of the SegmentedPropertyCategoryCodeSequence. It is also possible to define SegmentedPropertyTypeModifierCodeSequence that can be used , for example, to define the laterality. In some situations, it is appropriate or required to also specify anatomical location of the segmentation (e.g., organ a tumor was segmented). The latter can be achieved using AnatomicRegionSequence and AnatomicRegionModifierSequence coded attributes.

To simplify selection of codes for defining semantics of the segment, we provide a that can be used to browse supported codes and automatically generate the corresponding section of the JSON file. When no suitable codes can be found, it is also permissible to define so called private, or local, coding schemes (see ).

You can also see of the documentation discussing the various options of searching for the coded terms that are available to you.

segimage2itkimage

This tool can be used to convert DICOM Segmentation into volumetric segmentations stored as labeled pixels using research format, such as NRRD or NIfTI, and meta information stored in the JSON file format.

Usage

Examples of DICOM Segmentation objects

If you are looking for publicly available examples of segmentation objects, or other DICOM images, you should check out (IDC) (see documentation ).

Here are some representative examples of DICOM Segmentations:

• Segmentation of a lung nodule from the collection

  • viewer link:

• TotalSegmentator segmentation results from the collection

To download the files for the studies listed above:

1. install idc-index package with pip install --upgrade idc-index

2. download the study by specifying StudyInstanceUID (listed in the URLs above after the '=' sign) with idc download 1.2.840.113654.2.55.256011367872217445472654886973509892961

itkimage2paramap can be used to convert a parametric map provided in any of the formats supported by ITK, such as NRRD or NIFTI, as a DICOM Parametric Map image object.

Usage

dcmqi provides command line tools to convert results of post-processing of the image data, such as by applying certain model to the data, into DICOM format. As an example, Apparent Diffusion Coefficient (ADC) maps derived by fitting various models to the Diffusion-Weighted Magnetic Resonance Imaging (DW-MRI) data have been shown promising in characterizing aggressiveness of prostate cancer. The result of conversion is DICOM Parametric map object.

Mandatory metadata that needs to be specified to enable conversion include:

• Quantity being measured

• Units of the quantity being measured

• Measurement method

Each of these items, in addition to some other attributes, must be specified using coded values. An example of the metadata file is available .

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.

Usage

   --outputMetadata <std::string>
     File name of the JSON file that will keep the metadata and
     measurements information.

   --inputDICOM <std::string>
     File name of the DICOM SR TID1500 object.

Example objects

This tool can be used to convert a DICOM Parametric Map Image object into ITK image format, and generate a JSON file holding meta information.

Usage

   -t <nrrd|mhd|mha|nii|nifti|hdr|img>,  --outputType <nrrd|mhd|mha|nii
      |nifti|hdr|img>
     Output ITK format for the output image. (default: nrrd)

   --outputDirectory <std::string>
     Directory to store parametric map in an ITK format, and the JSON
     metadata file.

   --inputDICOM <std::string>
     File name of the DICOM Parametric map image.

Examples of DICOM Parametric map objects

You can experiment with the converter using the following objects:

• (zip archive)