The following section is intended for the users of command-line tools provided by dcmqi.

We are continuously working on the content of this guide. It will change and improve in the future.

Your feedback is very important in improving the quality of this guide.

To contribute your feedback, you can initiate a discussion for a specific paragraph of text. If you mouse over the paragraph while reading the web version of the book on gitbooks.io, you should see a + symbol to the right of the paragraph you are reading. You can click it and initiate a new discussion, as shown in the screenshot below.

Once you post your feedback, developers of this guide will receive automatic notifications, and will respond to your suggestions or concerns.

Note that you will need to sign in before you can participate in a discussion (gitbook accepts Facebook, Twitter, Google and Github authentication).

dcmqi is a collection of libraries and command line tools. It is currently possible to install dcmqi using one of the following approaches:

1. Using binaries for your platform from either the "latest" or named release

2. Using docker

3. Build from source

4. From 3D Slicer extension

We are also working on providing a downloadable binaries of dcmqi independent of the 3D Slicer application. This option will be supported in the future.

Background

is a project that automates deployment of applications inside software containers. Docker application is defined by images that contain all of the components and steps needed to initialize the application instance. A container is a running instance of the image. We provide an image that contains the compiled dcmqi library. By using dcmqi Docker container you can use dcmqi on any operating system without having to compile it. All you need to do is install Docker on your system, and download the dcmqi Docker image.

Usage

You will first need to install Docker on your system following . Docker is available for Mac, Windows and Linux. For the most part Docker installation is straightforward, but some extra steps need to be taken on Windows as discussed below.

If you use Docker on Windows ...

Note the :

• you will need to have Windows 10 Pro or above

• you will need to enable Hyper-V package (Docker will prompt you)

• you will need to enable virtualization; to learn how to check if it is enabled, and if it is not - here is that may help you do that, but it assumes you can access your BIOS settings

IMPORTANT: You will also need to share the drive you will be using to communicate data to and from Docker image in Docker Settings as shown in the screenshot below.

Most likely you will experience the display of an error message similar to the one shown below.

If you have this error, make sure that the drive, where the HOST_DIR is located, is shared:

1. right click onto the Docker task bar icon and choose "Settings"

2. choose "Shared Drives" from the left menu (a list of drives that are available to share will be displayed)

3. select the drive for your HOST_DIR to be shared

4. confirm with Apply and continue

Once Docker is installed

Pull the dcmqi image to your system to instantiate the dcmqi container:

You can now run any of the command line converter provided by dcmqi by passing the name of the converter as shown below:

Shared directory between Docker container and host

Docker containers cannot directly access the filesystem of the host. In order to pass files as arguments to the dcmqi converter and to access files that converters create, an extra step is required to specify which directories will be used for file exchange using the -v argument:

The argument above will make the HOST_DIR path available within the container at CONTAINER_DIR location. The files that will be read or written by the converter run from the docker container should be referred to via the CONTAINER_DIR path.

Usage example

Assuming the docker image is installed, create an empty directory docker_test.

Put the following test files from dcmqi source code repository into the docker_test directory:

Run the itkimage2paramap converter

The output DICOM object will be saved as docker_output_paramap.dcm in the docker_test directory.

Platform-specific packages of dcmqi accompany the library starting from release v1.0.1. You can download these packages for Windows, macOS and Linux at https://github.com/QIICR/dcmqi/releases. Extract the package archive for your operating system to access command line tools.

dcmqi should build on Linux, Mac and Windows. You can confirm this is the case for the current version of the code by looking at the continuous integration (CI) platforms.

• Linux build:

• Windows build:

• Mac OS X build:

Note that the failure icons indicate that something in the dashboard script failed - this could be build error, failed test, failed artifact upload, or failed download of a prerequisite. You will need to check the console output for the specific platform to see if there are problems with the build.

Checking out the source code

We use git/github to maintain the repository. You can clone the repository using this command:

git clone https://github.com/QIICR/dcmqi.git

If you are not familiar with git, there are many guides to help you get started, such as this one that should take about 10 minutes: https://guides.github.com/activities/hello-world/.

Prerequisites

1. developer environment for your platform (compiler, git)

2. recent version of cmake

Note that you can also see the specific components and steps needed to build dcmqi by looking at the CI configuration scripts (circle.yml for Lunux, .travis.yml for Mac, and appveyor.yml for Windows).

If you would like to run dcmqi tests, you will need to install few extra tools for validating JSON files. These tools depend on npm installed as part of Node.js, and are the following:

• jsonlint

• ajv-cli

Both can be installed with npm as follows:

sudo npm install jsonlint -g
sudo npm install ajv-cli -g

Superbuild approach

With the superbuild approach, all of the dependencies will be build as part of the build process. This approach is the easiest, but also most time-consuming. 1. create dcmqi-superbuild directory 2. configure the project by running cmake <dcmqi source directory> from dcmqi-superbuild 3. run make from the superbuild directory

Non-superbuild approach

You can use this approach if you have (some of) the dependency libraries already built on your platform. dcmqi dependencies are

• DCMTK

• ITK

• SlicerExecutionModel

• zlib

To reuse builds of those libraries, you will need to pass the corresponding variables to cmake as shown in the example below:

cmake DITK_DIR:PATH=C:\ITK-install \ 
  -DSlicerExecutionModel_DIR:PATH=C:\SlicerExecutionModel\SlicerExecutionModel-build \
  -DDCMTK_DIR:PATH=C:\DCMTK-install\cmake  \
  -DZLIB_ROOT:PATH=c:\zlib-install \ 
  -DZLIB_INCLUDE_DIR:PATH=c:\zlib-install\include \ 
  -DZLIB_LIBRARY:FILEPATH=c:\zlib-install\lib\zlib.lib \
  <dcmqi source directory>

Troubleshooting

• Under certain conditions, line endings may be incorrectly initialized for your platform by the checkout process (reported by @CJGoch in https://github.com/QIICR/dcmqi/issues/14), which may result in errors like below:

dcmqi/dcmqi-build/apps/seg/itkimage2segimageCLP.h:214:1: error: stray ‘\’ in program
{
^
dcmqi/dcmqi-build/apps/seg/itkimage2segimageCLP.h:214:3: warning: missing terminating " character
{
^
dcmqi/dcmqi-build/apps/seg/itkimage2segimageCLP.h:214:1: error: missing terminating " character
{
^

To resolve this, check your global git settings. If you have autocrlf set, you may try setting it to auto.

We use JSON to represent metadata that is either passed to the converter into DICOM, or that is extracted from DICOM representation.

As such, you will need to have some understanding of both DICOM and JSON if you want to use dcmqi.

We provide the following tools that can help you use dcmqi more effectively.

• dicom-dump is an extension for Atom text editor that can be used to explore the content of DICOM data

• dcmqi validators web app can be used to see examples of metadata JSON for specific object types, to explore the schema, and to validate your own metadata JSON against the schema

You can check out our Learning resources section for some reference material about JSON and DICOM that we found helpful.

One of the fundamental principles of DICOM is the use of controlled terminologies, or lexicons, or coding schemes (for the purposes of this guide, these can be used interchangeably). While using dcmqi you will encounter various situations where you will need to select codes to describe the data you are converting into DICOM. In this and the following sections we give you an overview and describe the general principles of deciding on how to choose such codes.

Controlled terminologies define a set of codes, and sometimes their relationships, that are carefully curated to describe entities for a certain application domain. Consistent use of such terminologies helps with uniform data collection and is critical for harmonization of activities conducted by independent groups.

When codes are used in DICOM, they are saved as triplets that consist of

• CodeValue: unique identifier for a term

• CodingSchemeDesignator: code for the authority that issued this code

• CodeMeaning: human-readable code description

DICOM relies on various sources of codes, all of which are listed in PS3.16 Section 8 of the standard.

The first question while choosing the coding scheme is whether you will use an existing code, or define your own. Depending on your choice, follow one of the two recipes below.

1. Use one of the codes defined in DICOM

2. If there is no matching code that is already included in DICOM, you can search one of the existing terminologies/ontologies for a suitable code: this option often requires more effort, but it will make your resulting data consistent with the existing controlled terminologies, facilitating reasoning on the resulting data, and aggregation of the results collected from different sources. This “semantic” approach using standard codes allows for greater reuse and harmonization with other data sets, since the need for natural language parsing of plain text during “data mining” is obviated by the commonality of standard codes for standard entities, such as anatomical regions, types of tumor, etc. The choice of the coding scheme and specific codes will depend on the specific data conversion task.

3. Introduce a new coding scheme: if you follow this option, you can either reuse an existing terminology which is not listed in the DICOM standard here, or define your own terminology and set of codes. You can still produce the data that is harmonized with other sources, but to achieve this you will need to make sure all "data producers" follow your coding scheme! This approach is suitable when you are working on an application where no established terminology exists (e.g., no consensus within your community is reached), or when semantic interoperability is not a priority.

In DICOM, the process of choosing a code, and a coding scheme, depends on the context. In the following, we will discuss some of the guidelines that can be used to choose suitable codes for the tasks of segmentation, measurements and parametric map conversion supported by dcmqi.

• Segmentation

• Measurements

• Parametric map

Segmentation

While converting segmentations, you will need to define the following coded entities in the JSON file:

• SegmentedPropertyCategoryCodeSequence

• SegmentedPropertyTypeCodeSequence

• SegmentedPropertyTypeModifierCodeSequence (when applicable)

• AnatomicRegionSequence (when applicable)

• AnatomicRegionModifierSequence (when applicable)

This looks overwhelming indeed! That's why we developed a web application to help you interactively choose the codes for each of those items. If you want to know the details, read on!

For each of these attributes, DICOM provides guidance on the selection of the suitable codes.

SegmentedPropertyCategoryCodeSequence codes are listed in context group ID (CID) CID 7150 (extensible, i.e., you are not forced to use only the codes from this selection)

SegmentedPropertyTypeCodeSequence codes are defined in CID 7151, which points to the application-specific CIDs that you can follow for the lists of codes

SegmentedPropertyTypeModifierCodeSequence is an optional attribute that augments segmented property type code. As an example, if SegmentedPropertyTypeModifier is "Kidney", SegmentedPropertyTypeModifier can be "Left" to specify laterality. More modifier codes are available in part 16 of the standard, as an example see CID 2 Anatomic Modifier.

AnatomicRegionSequence and its modifier do not always have to be specified. In some situations, information contained in SegmentedPropertyType is sufficient. E.g., if one is creating an atlas, where the properties are purely anatomical, and there is no more to say about them than the anatomy, then the anatomy goes in the Segmented Property Type Code Sequence. If one has different types of properties (e.g., necrosis, enhancing rim, gross tumor volume), but one wants to say something about the anatomy (e.g., where the tumor is at), then the property goes in Segmented Property Type Code Sequence and the anatomy goes in Anatomic Region Sequence. When you do want to specify AnatomicRegion, you can consult CID 4 Anatomic Region for the list of codes. Modifier for this code is specified as needed, following the same approach as discussed for SegmentedPropertyTypeModifierCodeSequence.

The web application we mentioned earlier provides an interactive interface to somewhat simplify the task of populating the codes discussed above.

SNOMED CT

Most, if not all codes listed in the contexts referenced earlier are from SNOMED CT, and have DICOM CodingSchemeDesignator SRT. The reason for this is that Systematized Nomenclature of Medicine Clinical Terms (SNOMED® CT) coding scheme is the preferred controlled terminology used by DICOM . Most, if not all, of the codes used to define the entities above are from SNOMED CT. SNOMED CT maintains a systematically organized computer processable collection of medical terms providing codes, terms, synonyms and definitions used in clinical documentation and reporting. SNOMED CT maintains the hierarchy of relationships among the codes, which can be used for semantic reasoning on the data. As an example, see hierarchy of the entities related to the Liver code in the SNOMED CT Browser.

SNOMED CT License exemption

Note that SNOMED CT codes included in the DICOM standard are exempt from SNOMED CT license. The details are discussed in this blog post. In short:

Users and commercial and open source DICOM developers can be reassured that they may continue to use the subset of SNOMED concepts in the DICOM standard in their products and software, globally and without a fee or individual license.

Measurements

TBD - work in progress

Parametric map

The following codes can be passed to describe the parametric map you are converting using itkimage2paramap converter:

• QuantityValueCode: Quantity being measured at each pixel - select code from TID 7180, or introduce a private code.

• MeasurementUnitsCode: Units of measurement. DICOM uses Unified Code of Units of Measurement (UCUM) code system (CodingSchemeDesignator UCUM) to describe units. Some of the commonly used unit codes are listed in CID 7181, but as discussed in Part 16 Section 7.2.2, any of the UCUM codes can be used in DICOM.

• DerivationCode: select code from CID 7203, or introduce a private code.

• AnatomicRegionSequence and Modifier (optional): follow the same guidelines as discussed for Segmentation

  anatomic codes selection.

• MeasurementMethodCode (optional): code describing the model used for deriving the quantity.

• ModelFittingMethodCode (optional): code describing the model fitting method.

In the future we plan to provide specific recipes that describe the sets of codes suitable for specific use-cases (e.g., estimating Apparent Diffusion Coefficient (ADC) from Diffusion-Weighted MRI, or performing pharmacokinetic modeling of the Dynamic Contrast-Enhanced MRI).

Relevant development of the codes related to ADC calculation can be found in DICOM Correction Proposal (CP)CP-1665. These codes are expected to become part of the standard in Spring 2017.

For now, the best place to start is this web application (select pm-schema in the Validation schema selector) that you can use to choose an existing example and modify it to tailor to your use case.

You can access the functionality provided by dcmqi in 3D Slicer using QuantitativeReporting extension. Specifically, you can use QuantitativeReporting to prepare segmentations of DICOM imaging series, define semantics of the segmentation, calculate measurements and export the result as DICOM. You can also load DICOM segmentations, measurement structured reports and parametric maps with QuantitativeReporting, which is using dcmqi to support data conversion. See user guide of QuantitativeReporting for further details.

dcmqi itself is also available as a 3D Slicer extension. It provides the libraries and converters that can be integrated with other 3D Slicer extensions. If you are developing an extension for 3D Slicer, you can access dcmqi converters by specifying dependency on dcmqi 3D Slicer extension.

QuantitativeReporting should be available as an extension in the nightly version of 3D Slicer, starting November 2016. We always suggest that you use the latest (nightly) version of the software when you try it for the first time.

Download the latest nightly release for your platform from http://download.slicer.org.

Do NOT use installers tagged as "Stable Release"!

After downloading, follow the installation procedure for your platform.

If you use Mac, make sure you move the Slicer application to the Applications folder on your computer before launching it!

Once installed, open 3D Slicer Extension Manager by clicking the icon as shown below.

Search for QuantitativeReporting and install the extension by clicking the INSTALL button.

Upgrade

It is currently not possible to upgrade an extension without upgrading the 3D Slicer application.

If you need to upgrade the software, download the latest nightly release of 3D Slicer and install QuantitativeReporting as explained above.

While DICOM allows for reuse of the codes defined in other terminologies, such as SNOMED, as well as those defined in the DICOM standard itself, so called “private” codes can also be defined by the creator of the object, when no standard codes are available. Such private codes are distinguished by a coding scheme designator that must start with the “99” prefix.

As an example, consider Dr. Smith developed a new model for estimate ADC from diffusion MRI. Since the method is new, there is no standard code for it. Dr. Smith then can establish her own coding scheme designator, say, 99DRSMITH, and define a new code as the following triple:

('SADC123','99SMITH','Smith Diffusion Model').

To find a suitable code in an existing terminology, you will need to know what terminology to search, and you will need a tool that would facilitate your search.

DICOM has a preference for using SNOMED-CT codes. If you find a code in SNOMED-CT that would fill an important gap, but is not in the standard, you can propose inclusion of that new code into the standard. While looking for codes in SNOMED-CT, note the following guideline from the standard (PS3.16, Section 8.1.1):

8.1.1 Use of SNOMED Anatomic Concepts

In general, DICOM uses the anatomic concepts with the term "structure", rather than with the term "entire". This is an important distinction in SNOMED. "Entire" is a child concept to "structure", has a more restricted meaning, and typically is used in conjunction with treatments (e.g., "excision of entire right kidney"). It is used in distinction to other sibling children of the parent concept that may identify parts of the parent anatomic feature. Since imaging typically targets both the anatomic feature and the area around it, or sometimes just part of the anatomic feature, DICOM usually uses "structure" concepts that are more inclusive than the "entire" concepts.

However, keep in mind that:

1. the process of contributing something into the DICOM standard is lengthy and can take a year before you see your change in the standard text;

2. you will need to learn the procedures of contributing changes to the standard;

3. although the SNOMED-CT codes included in the standard are exempt from the licensing constraints of SNOMED-CT, the ontology defined by SNOMED-CT is NOT covered by the exemption. Therefore, you will still need a secondary ontology if you are concerned about the license, and want to do reasoning on your data.

If a certain term is not found in SNOMED, it might be possible to add it. If you would like to request adding a new term in the context of DICOM, you can contact DICOM secretariat at http://www.dicomstandard.org/contact/secretariat/, and they would then pass your request to the person responsible for the interactions with SNOMED. Also, each country has its SNOMED national member contact: http://www.snomed.org/our-customers/members, in case you want to make a non-DICOM related request.

Using existing terminologies other than SNOMED

Therefore, it can be more practical to find a suitable term in an ontology other than SNOMED-CT.

In this regard, David Clunie, the long-time Editor of the DICOM standard, gave the following guidance on what terminologies to consider when a gap in the standard is identified:

[...] we (DICOM) use FMA then NeuroNames as a fallback when there are no appropriate SNOMED codes (yet), and have contacts with each of the appropriate groups to extend the schemes as necessary. We have not used RadLex for anatomy, since it is all/mostly(?) in FMA anyway (and if I recall correctly, was derived from it, since the original RadLex protagonists had no interest in reinventing that wheel).

If you need to automate anatomical code mapping, consider using the UMLS as a tool ... frequently both SNOMED and FMA terms map to a common UMLS code which helps a lot.

You can also use the FMAIDs included in the RadLex ontology (http://purl.bioontology.org/ontology/RADLEX) to map from RadLex back to FMA (or the reverse, since I think the FMA OWL file also includes the RadLex RIDs), then to UMLS and on to SNOMED, and indeed then undo the pre-coordinated laterality (if necessary) using the SNOMED hierarchy.

To search existing terminologies, you can consider using the following tools that search across different ontologies:

• BioPortal

• EMBL-EBI Ontology Lookup Service (OLS)

With both of these search engines you have an option of the advanced search to restrict the terms to a specific ontology.

There are also some search tools that provide searches for the individual ontologies (such as FMA), but in some instances their search capabilities are not flexible enough, and as such we recommend BioPortal and OLS. Unfortunately, neither BioPortal nor OLS include Neuronames, so you will need to use the specialized search tool for that ontology: http://braininfo.rprc.washington.edu/.

Here is an illustrative example of searching for a term "anterior cingulate gyrus", which is not included in DICOM (note that you can use AnatomicRegionModifier to encode laterality of the structure).

1. Using BioPortal, go to the Advanced search, put the search term in the search box, and specify FMA in the "Ontologies" selector:

The search is successful, leading to this entry, which includes the FMA ID 61916. Coding scheme designator for FMA is FMA, so the you can use the following code to describe the item:

(61916, FMA, "Anterior cingulate gyrus")

1. Using OLS, you can select the specific ontology, and search specifically in FMA for the same term, which will result in the same code:

Note that OLS is (as of writing this) using a "slimmed down version of FMA", but for common purposes perhaps this should still be sufficient.

References

• Definition of post-coordinated codes from UMLS: https://utsreport.nlm.nih.gov/umlsreport/sourceDocs/postcoordinated.html

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

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.

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

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

   -p <std::string>,  --prefix <std::string>
     Prefix for output file.

   --outputDirectory <std::string>
     Directory to store individual segments saved using the output format
     specified files. When specified, file names will contain prefix,
     followed by the segment number.

   --inputDICOM <std::string>
     File name of the input DICOM Segmentation image object.
     
   --mergeSegments
     Save all segments into a single file. When segments are
     non-overlapping, output is a single 3D file. If overlapping segments
     are identified, multiple 3D files will be created each containing
     non-overlapping segments. Metadata JSON files will be created for each
     such 3D file. (value: 0)

Examples of DICOM Segmentation objects

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

Here are some representative examples of DICOM Segmentations:

• Segmentation of a lung nodule from the DICOM-LIDC-IDRI-Nodules collection

  • viewer link: https://viewer.imaging.datacommons.cancer.gov/v3/viewer/?StudyInstanceUIDs=1.3.6.1.4.1.14519.5.2.1.6279.6001.101324598070011890446155612648

• TotalSegmentator segmentation results from the TotalSegmentator-CT-Segmentations collection

  • viewer link: https://viewer.imaging.datacommons.cancer.gov/v3/viewer/?StudyInstanceUIDs=1.2.840.113654.2.55.256011367872217445472654886973509892961

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

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

   --skip <int>
     Skip empty slices while encoding segmentation image. By default, empty
     slices will not be encoded, resulting in a smaller output file size.
     (value: 1)

   --inputImageList <std::vector<std::string>>
     Comma-separated list of file names of the segmentation images in a
     format readable by ITK (NRRD, NIfTI, MHD, etc.). Each of the
     individual files can contain one or more labels (segments). Segments
     from different files are allowed to overlap. See documentation for
     details.

   --inputDICOMDirectory <std::string>
     Directory with the DICOM files corresponding to the original image
     that was segmented.

   --inputDICOMList <std::vector<std::string>>
     Comma-separated list of DICOM images that correspond to the original
     image that was segmented. This means you must have access to the
     original data in DICOM in order to use the converter (at least for
     now).

   --outputDICOM <std::string>
     File name of the DICOM SEG object that will store the result of
     conversion.

   --inputMetadata <std::string>
     JSON file containing the meta-information that describes the
     measurements to be encoded. See documentation for details.
     
   --useLabelIDAsSegmentNumber
     Use label IDs from ITK images as Segment Numbers in DICOM. Only works
     if label IDs are consecutively numbered starting from 1, otherwise
     conversion will fail. (value: 0)

Detailed usage

Most of the effort will be required to populate the content of the meta-information JSON file. You can use the helper web application 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 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.

{
  "@schema": "https://raw.githubusercontent.com/qiicr/dcmqi/master/doc/schemas/seg-schema.json#",

This opening line references the schema this parameter file should conform to. Make sure you include this line without changes!

  "ContentCreatorName": "Doe^John",
  "ClinicalTrialSeriesID": "Session1",
  "ClinicalTrialTimePointID": "1",
  "ClinicalTrialCoordinatingCenterName": "BWH",
  "SeriesDescription": "Segmentation",
  "SeriesNumber": "300",
  "InstanceNumber": "1",

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.

  "segmentAttributes": [
    [
      {

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": 1,

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:

SegmentedPropertyCategoryCodeSequence = (M-01000, SRT, "Morphologically
Altered Structure")
SegmentedPropertyTypeCodeSequence = (M-80003, SRT, "Neoplasm, Primary")
SegmentNumber=1

and

SegmentLabel = 255

or

SegmentLabel = "primary tumor"

or

SegmentLabel = "primary tumor (255)"

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

SegmentLabel = "Neoplasm, Primary"

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

        "SegmentDescription": "Liver Segmentation",

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

        "SegmentAlgorithmType": "SEMIAUTOMATIC",

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!

        "SegmentAlgorithmName": "SlicerEditor",

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

        "recommendedDisplayRGBValue": [
          221,
          130,
          101
        ]

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": {
          "CodeValue": "T-D0050",
          "CodingSchemeDesignator": "SRT",
          "CodeMeaning": "Tissue"
        },
        "SegmentedPropertyTypeCodeSequence": {
          "CodeValue": "T-62000",
          "CodingSchemeDesignator": "SRT",
          "CodeMeaning": "Liver"
        },

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 in PS3.16 Section 8.

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 helper web application 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 PS3.16 Section 8.2).

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

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 .

Usage

Usage details

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.

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.

Examples

Encoding measurements over segmentation of liver in CT

*

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 .

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 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

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

Examples of DICOM Parametric map objects

You can experiment with the converter using the following objects:

• (zip archive)

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

Detailed usage

In the following, we will guide you through the contents of this file - line by line.

These lines correspond to the metadata attributes that will be populated in the resulting DICOM Parametric Map image 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.

QuantityValueCode, MeasurementUnitsCode, MeasurementMethodCode, AnatomicRegionSequence are attributes (code tuples) to describe the meaning the pixels stored in this parametric map. AnatomicRegionSequence, DerivedPixelContrast, FrameLaterality are the only attributes that are required. All others are optional.

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.