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 . Extract the package archive for your operating system to access command line tools.

Background

Docker 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

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:

The Dockerfile for qiicr/dcmqi is available in the main repository of dcmqi . It does not rely on any proprietary or non-open-source components.

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

(also see !)

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.

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.

should be available as an extension in the nightly version of , 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 .

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.

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

*

This section of the user guide contains (a growing collection of) illustrative worked out use cases where dcmqi was applied.

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.

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

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').

Tutorials below are accompanied by the narrated video instructions, pointers to the components you will need to install and sample data to follow along.

• dcmqi: A hands-on introduction

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.

About

This is user guide for the dcmqi (DICOM for Quantitative Imaging) library.

With dcmqi you can:

• Convert certain types of results into standardized DICOM form. This can help you with

  • sharing data in archives like

  • interoperating with PACS and commercial tools

  • supporting data queries to both image data and analysis results
• Convert DICOM data into a commonly used research file formats like JSON and NIfTI.

• Integrate DICOM concepts into your analysis workflows so that intermediate results are encoded in a standardized manner, making it easy to share your data.

License

dcmqi is distributed under .

Tutorials

Check out our !

Support

You can communicate you feedback, feature requests, comments or problem reports using any of the methods below:

• post a question to [dcmqi google

  group]()

• on dcmqi bug tracker

• leave feedback directly in the

Acknowledgments

To acknowledge dcmqi in an academic paper, please cite

Herz C, Fillion-Robin J-C, Onken M, Riesmeier J, Lasso A, Pinter C, Fichtinger G, Pieper S, Clunie D, Kikinis R, Fedorov A. dcmqi: An Open Source Library for Standardized Communication of Quantitative Image Analysis Results Using DICOM. Cancer Research. 2017;77(21):e87–e90 .

If you like dcmqi, please give the . This is an easy way to show thanks and it can help us qualify for useful services that are only open to widely recognized open projects.

This work is supported primarily by the National Institutes of Health, National Cancer Institute, , grant (U24 CA180918, PIs Kikinis and Fedorov). We also acknowledge support of the following grants: (P41 EB015902, PI Kikinis) and (P41 EB015898, PI Tempany).

References

1. Fedorov A, Clunie D, Ulrich E, Bauer C, Wahle A, Brown B, Onken M, Riesmeier J, Pieper S, Kikinis R, Buatti J, Beichel RR. (2016) DICOM for quantitative imaging biomarker development: a standards based approach to sharing clinical data and structured PET/CT analysis results in head and neck cancer research. PeerJ 4:e2057

2. Herz C, Fillion-Robin J-C, Onken M, Riesmeier J, Lasso A, Pinter C, Fichtinger G, Pieper S, Clunie D, Kikinis R, Fedorov A. dcmqi: An Open Source Library for Standardized Communication of Quantitative Image Analysis Results Using DICOM. Cancer Research. 2017;77(21):e87–e90 .

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

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.

Summary of the use case

In this use case we will summarize the approach to encode segmentations of various structures and measurements derived using those segmentations from multi-parametric Magnetic Resonance Imaging (MRI) of the prostate.

More specifically, we will discuss encoding of the imaging-derived data discussed in the following paper:

Fedorov A, Vangel MG, Tempany CM, Fennessy FM. Multiparametric Magnetic Resonance Imaging of the Prostate: Repeatability of Volume and Apparent Diffusion Coefficient Quantification. Investigative Radiology; 2017;52(9):538–546 .

The imaging-derived data discussed in that paper consists of the two components:

1. Segmentations of the following structures:

   • Whole gland of the prostate

   • Peripheral zone of the prostate

Each segmented structure is saved in an individual itk nrrd format file.

Conversion of Segmentations to DICOM SEG

Organizing the Data

It is advisable to organize the original dicom image files in a directory structure like <Patient>/<Study>/<Series>/orig-img-dicom/. Since one required input of the converter are all dicom files which represent the original image on which the segmentation was created. Organizing the data as described above will allow us to just provide the correct series directory instead of listing all files of that series.

All segmentations corresponding to a series should then be put into a folder like <Patient>/<Study>/<Series>/segmentations/. Into this folder we will also put the meta-information JSON file required to convert the segmentations.

Creating the Meta-Information JSON File

The first convenient place to start with generating JSON files for the dcmqi SEG converter is always .

The most confusing part is typically how to find the codes to encode specific items. In our case, some structures have codes already included in the DICOM standard, while some other codes had to be looked up in SNOMED.

Make sure to select DICOM master list in the "Segmentation Category Type Context Name". This will give you access to all of the codes in the standard.

• Whole prostate gland: we encode anatomic structure (short selection list in the Category selector), and can quickly locate the code for the prostate:

• Peripheral zone: this one is more difficult - no code could be located. We needed to consult to find "Peripheral zone of the prostate", which has SCTID 279706003. Next, we looked up SRT code for SCTID in an older version of SNOMED (this was done by our good friend David Clunie!). Result:

• Suspected tumor tissue: the most suitable code is "Lesion", but it is not available in the web interface we used before ... We will need to fix this... Note that for "Morphologically altered structure" we can (and should!) also specify "AnatomicRegionSequence" to encode the location of the lesion. In our case, all of the lesions are in the peripheral zone of the prostate.

Other attributes are rather trivial to populate:

• BodyPartExamined should be PROSTATE (all caps is important! ... we should add explanation to this ...)

• SegmentDescription can be populated with an abbreviated name reflecting the structure being segmented (note: this attribute can be at most 64 characters long!)

An almost complete meta-information JSON file for these cases could look like this:

Note that this file contains two placeholders which still need to be replaced with the correct value for the segmentations we are trying to convert: @TimePoint@ and @SeriesNumber@ . While all other properties in the JSON file are valid for all segmentation files, these two properties will differ for different segmentation files:

1. In this particular case we have segmentations of two timepoints, so we have to make sure the meta-information JSON file we use when running the converter has the correct timpoint encoded.

2. Segmentations based on one series in a study should also have a unique series number within that study. We can follow the following formula (or similar) to assign series number: <SeriesNumber of the image series>+1000.

This means we will need several slightly different JSON files to perform the conversion. The best approach is to create them dynamically with a script that inserts the correct values for the placeholders. If we follow the data organization approach suggested above we should have one JSON file per <Patient>/<Study>/<Series>/segmentations/ folder.

Running the Converter

The converter needs to run separately for each segmentation folder. Switch to a <Patient>/<Study>/<Series>/segmentations/ folder. Then run the converter like this:

This will place a file <out-name>.SEG.dcm into the segmentations folder. The SEG object will contain all four segmentations.

Note that the order of the files for --inputImageList has to exactly match the order of the segmentAttributes list in the meta.json. If the order of files in --inputImageList is different or contains less or more files, we need to adjust the meta.json accordingly.

Conversion of measurements to DICOM SR TID1500

Overall, the conversion of segmentation-based measurements into a DICOM Structured Report that follows is supported by the dcmqi tool tid1500writer. This tool expects as input the following items:

• DICOM image series that was used for segmentation

• DICOM Segmentation image series containing the segmentation result

• JSON file containing the individual measurements, and additional metadata needed by DICOM

Creating the Measurements JSON file

Assuming the segmentation conversion above was successful, a JSON file is required that specifies metadata for the structured report overall, and for the individual measurements.

We do not provide a web application to populate such file, so at this moment, the easiest is to start with an example and update it as needed. Let's start with .

Before discussing how to initialize individual items, we need to decide how to organize measurements. There are at least two options here: 1. Save measurements for each combination of structure/image series as a separate DICOM SR document. 2. Save measurements for all structures segmented in a given series in a single DICOM SR document.

Considering we made a decision to save all segments (whole gland, peripheral zone, tumor region, etc) in a single DICOM SEG file, it is logical to follow the same pattern and store per-segment measurements in separate groups within the same DICOM SR.

Here are the items we will need to update:

Although SeriesNumber is not formalized by DICOM, it is usually expected by the users that it should be unique. We can follow the following formula (or similar) to assign series number: <SeriesNumber of the image series being segmented>+2000.

This item contains the name of a DICOM file that should be used to populate composite context (information about study, patient, equipment, which is the same for all series in a study) of the output DICOM object. We can set this item to be the Segmentation DICOM object, or any of the DICOM instances from the input image.

imageLibrary should contain the list of all DICOM instances from the source image series being segmented. A component of the output SR document will include certain attributes of these instances, and will reference them by SOPInstanceUID.

In our case, there was a single reader, so we can leave this item unchanged.

These items can also remain unchanged, since we share final measurements. The exception is timePoint, which should have values of 1 for baseline, and 2 for the followup.

Next, we need to populate the list of Measurements. Each of the items (measurement groups) in this list will contain a list of attributes that apply to all individual measurements within the group, and a list of individual measurements.

In our case, each measurement group will contain measurements calculated over a single segmented structure.

First, let's look at the top-level attributes:

TrackingIdentifier is a human-readable description of the measurements group. We can use the pattern <structure name> measurements, i.e., Whole gland measurements etc.

These items should be propagated given the information about source image series and the segmentation generated in the previous conversion step. Availability of these items allows to link measurements with the results of segmentation and source image series.

• ReferencedSegment: The SegmentNumber for the corresponding segment in the DICOM segmentation object.

• sourceSeriesInstanceUID: The SeriesInstanceUID of the actual image from which the segmentation was created.

• segmentationSOPInstanceUID

The next items -- Finding and FindingSite -- are code tuples that allows us to encode what was the region over which measurement was done, and where it was located. These items are somewhat similar to what we had to specify for encoding segmentation.

Here are the codes we can use for each of the structures over which we performed the measurements (each tuple in parentheses contains (CodeMeaning, CodingSchemeDesignator, CodeValue):

• Whole gland:

  • Finding: ("Entire Gland", "SRT", T-F6078)

  • Finding site: ("Prostate", "SRT", "T-9200B")

Following the description of the top-level attributes for a measurement group is the list of individual measurements. Each measurement item must include the following attributes:

• value: the measurement value

• quantity, units, and derivationModifier: coded tuples describing the quantity. In our case, measurements are either volume of the segmented regions, or the mean value of the Apparent Diffusion Coefficient (ADC).

Volume:

Mean ADC (note how the fact that we encode the mean value of ADC over the region is with the derivationModifier):

Running the Converter

The converter needs to run separately for each measurements JSON file. Switch to the folder where you placed the measurements JSON file (preferably this should be a folder separate from the other data). Then execute the following command:

This will create a <out-name>.SR.dcm which contains the structured report with all measurements referencing the original images and the segmentations from which the measurements originated.

Conversion of the ADC maps

Optionally, we can also encode the ADC maps generated on the GE imaging post-processing equipment and stored as MR objects. Instead, we can use the DICOM Parametric map object, since it allows to explicitly communicate quantity, units and the type of ADC fitting approach that was used. can be used directly for this conversion task.

Summary of the use case

Segmentations of

• grey and white matter (labels 4 and 5 in this NIfTI file)

• left and right cerebral hemispheres (labels 2 and 3 in )

• overall brain mask (label 1 in )

were produced by FreeSurfer by segmenting .

We will go over the process of converting this representation into a standardized DICOM Segmentation image object.

Conversion to DICOM SEG

Visualization of the input data

As a first step, it is always a good idea to visualize the input data. We recommend for visualizing both DICOM and research format data.

Import DICOM dataset into Slicer DICOM database by unzipping the downloaded file with the MR series, opening DICOM Browser, and importing the directory with the DICOM MR series files (choose "Add link" when prompted).

Next, load segmentations stored in NIfTI. To do that, open "Add data", select the NIfTI segmentation files, check "Options" flag, and check "LabelMap" for each of the files in the list. This will tell Slicer that the files you are loading contain segmentations.

You should be able to see image with the segmentation for one of the labels shown in the overlay. If you mouse over the little pin icon in the corner of the slice viewer (orange arrow in the screenshot below), then expand the popup panel (red arrow), you can select each of the label files in the label selector (green arrow).

To figure out the value for the individual labels in the overlay, you can mouse over the label, and then look in the Data Probe panel in the bottom left corner of the Slicer window (red arrow in the screenshot below).

Using the hints discussed above, we can figure out that:

• 1 = overall brain mask label in brainmask-dcmspace.nii.gz

• 2 = left hemisphere label in lhrh-dcmspace.nii.gz

• 3 = right hemisphere label in lhrh-dcmspace.nii.gz

We will need the information above in the process of data conversion!

Preparation of the metadata JSON

In order to do the conversion, we need to pass extra metadata that would describe the segmentations to the converter.

We can use the web application that accompanies dcmqi to populate the metadata JSON file: .

We will need to create a new segment item in the web application for each of the labels we identified in the steps above. In our case, the structures we have are anatomical structures, and so this is what should be selected from the (short) list under "Segmented Property Category". "Segmented Property Type" contains the list of all items that belong to a category. Its drop-down contains a lot of items - start typing the name of the structure you are looking for, and it will suggest the matching names for you! The result should look like this:

Next let's add new segments for left and right hemisphere, and gray and white matter in this specific order. Add new segment by pushing the "+" button in the web application interface:

Note that you will not find codes for brain cerebral hemispheres in the drop-down - select brain ventricle as a placeholder, and select modifiers to be Left and Right for segments 2 and 3. We will put the proper codes at a later stage.

After populating all segments, you should see the following metadata for each of the individual segments in the webapp:

Next, click OK button in the webapp to generate the JSON metafile, and download it to your computer.

It should look something like .

Cleanup of the JSON file

Some extra work is needed to finalize the JSON file you generated.

Open JSON file in your favorite text editor (we recommend , a hackable text editor developed by GitHub). If you use Atom, we also recommend you install extension, as it will help you validate your JSON file and make it more readable by adjusting indentation.

We will need to complete two tasks to finalize the JSON file.

First, we need to replace "Brain ventricle" and assign the proper code to the cerebral hemispheres. To find the code, open in your browser (be patient, this is a very large page!). Once loading is completed, search for the word "hemisphere" on that page. One of the hits leads us to table CID 12022, which contains the code we need!

Replace all occurrences of "Brain ventricle" in your JSON file with "Cerebral hemisphere", and all codes "T-A1600" with "T-A010F". The result should look like .

Second, we need to reshuffle the content of the file. The "segmentAttributes" attribute of the JSON file is a list of lists, where each of the inner lists corresponds to one input file passed to the converter and contains metainformation for each of the segments. In our case, we have 3 input files. In the JSON file produced by the webapp, we have only one inner list with all of the segments. Edit the JSON file to have the first list contain just the brain mask, second list contain left and right cerebral hemispheres, and the third list containing gray and white matter. The resulting file should look like .

Now we should be ready to run the converter!

Run the converter

You can follow the and use either binary package for your platform, or a Docker image.

Considering you have the MR series in a folder called CMET-MRhead (it will be in that folder if you downloaded the dataset using the link on top of this page), segmentations in the files as specified on top, and your metadata JSON in meta.json, you should be able to run this command line to do the conversion:

Once the converter completes without errors, the resulting DICOM SEG object should be in freesurfer_seg.dcm!

Load the result into 3D Slicer

As a prerequisite, ! Without this extension, 3D Slicer will not know how to interpret DICOM SEG data!

Once QuantitativeReporting is installed, import the directory with the freesurfer_seg.dcm file. You should then see a new series with modality SEG in the DICOM Browser:

Select this series and load it. Slicer will prompt you whether you want to load the MR series which is referenced from the segmentation object. 3D rendering of the segmentation surfaces will be shown automatically in 3D and as overlay in the slice viewers. Switch to Segmentations module of 3D Slicer to control visibility and opacity of individual segments, access information about the semantics of the segments, and perform other operations.

This is it!

Advantages offered by using DICOM SEG

Too many to count, of course ... TBD

Potential issues

Picking vocabulary terms is pain!

See more detailed instructions on how to search for the terms outside DICOM in .

Size of the DICOM SEG representation is much larger than input

We identified a potential solution to this problem, and will add a feature to dcmqi to store segmentations in a compressed form:

To start using dcmqi, you can download the binary package with the command line converters for Windows, Linux and macOS from this page (both the latest release and pre-release corresponding to the current version of the source code): https://github.com/QIICR/dcmqi/releases.

If you prefer using Docker, download the dcmqi image from DockerHub with docker pull qiicr/dcmqi.

If you want to build dcmqi yourself, or modify the source code - get it on GitHub.

Encoding analysis results in DICOM

Many research studies such as imaging clinical trials or retrospective analysis of clinical data use a collection of databases, spreadsheets, and research data file formats such as NRRD, NIfTI, etc. As an example, a common practice to share segmentations is to provide NIfTI files along with a CSV file mapping label numbers to anatomical names.

As an alternative, you can use the itkimage2segimage command and related tools in dcmqi along with a JSON parameter file so that the segmentation output is described in terms of standardized vocabularies such as , and segmentation can be saved in DICOM format side by side and cross-referenced with the source image data. This can help remove ambiguity about the meaning of the results

Example command line:

Note for the Windows users

We recommend you use Windows PowerShell which is integrated in Windows 10 and further versions. The command line format on Windows will be different from that on Mac or Linux. Here is an example of the command line format on Windows (applied to using dcmqi from Docker):

Using DICOM data with research applications

If you get quantitative imaging data in DICOM format but want to use it in MATLAB or ITK, you can use segimage2itkimage to extract conventional NIfTI files of the segmentations or tid1500reader to convert structured reports into JSON.

Example command line:

Integrating DICOM into your analysis workflow

If you are designing a new analysis workflow from scratch, you can consider using DICOM as the format to store intermediate results. If you look at the , you can see how to create analysis results in native DICOM format that use standard terminologies and units, while retaining their linkage to the original input data. You could consider using dcmqi utilities to convert to and from research formats.

General questions

Why?

The goal of dcmqi is to help you use DICOM for storing the results of quantitative image analysis.

Why would you want to use DICOM for your analysis results?

You should use DICOM if you want to improve interoperability of your data, to enhance the ability to automatically find and use the data by the computational tools, as well as support reuse of your data by individuals. These goals are widely recognized as important in the scientific community .

To highlight some of the specific advantages of using DICOM for storing analysis data, below we annotate the FAIR (Findable, Accessible, Interoperable, Reusable) Guiding Principles formalized by , as applied to quantitative image analysis, describing how research formats help meet the FAIR requirements, and contrasting those with the functionality provided by DICOM.

While speaking of "research formats", we refer primarily to the formats commonly used by researchers developing quantitative image analysis tools. Examples include , , , and .

Notable example of a domain-specific solution proposed for data storage is being developed for neuroimaging applications. We are not aware of a domain-specific solution developed for cancer imaging.

[1] Wilkinson et al. 2016. The FAIR Guiding Principles for scientific data management and stewardship. Scientific data 3:160018. DOI: .

Isn't DICOM used only for clinical images?

No.

DICOM is the international standard for biomedical images and image-related information.

Widespread use of DICOM in clinic has led to a common mis-conception that DICOM is only suitable for storing clinical images. DICOM applications are not restricted to clinical use only. The standard defines objects for storing image and image-related data, which are perfectly suitable to support imaging research.

DICOM supports a wide range of biomedical applications, including preclinical, veterinary and small animal imaging. Preclinical small animal imaging was introduced to the standard in 2015, see .

Most common types of DICOM objects are those produced by the clinical imaging equipment: Computed Tomography (CT), Magnetic Resonance Imaging (MRI) or ultrasound (US) image objects.

Some of the examples of image-related information that can be stored using DICOM include:

• radiation therapy dose, encoding dose distribution calculated by radiotherapy planning systems;

• radiation therapy structure set, containing contours of patient structures derived from images;

• segmentation image, which describes a classification of pixels in one or more referenced images;

dcmqi provides tools to convert into standardized representation for the types of image-derived data produced in quantitative imaging research.

Do you support DICOM Radiation Therapy Structure Sets (RT-STRUCT)?

dcmqi does not support conversion to/from DICOM RT-STRUCT objects.

DICOM RT-STRUCT is a type of DICOM object that found wide adoption in the radiation therapy community to store the planar contours of the anatomical structures prepared for the purposes of radiation dose planning. Due to the large installation base of radiation therapy planning tools and history of their usage, there are large amounts of image data annotated with DICOM RT-STRUCT contours.

Many of the segmentation algorithms produce classification of image voxels, and thus do not naturally suit the representation by means of planar contours, requiring extra conversion operation and a potential for information loss. DICOM Segmentation image encodes classification of individual image voxels directly, and is thus more natural fit for voxel-based segmentation results.

We do not support RT-STRUCT, since there are established dedicated tools and libraries for handling DICOM RT-STRUCT, with some of the most notable examples include extension of , , and .

In our view, there is no need for yet another implementation of RT-STRUCT conversion to and from research formats.

We also note that although reporting of measurements for an image region defined by RT-STRUCT is supported by DICOM TID1500 Structured report, we currently do not implement direct support for this in dcmqi. We may consider adding this functionality in the future.

Users that have a need to report measurements over RT-STRUCT should first convert RT-STRUCT into a rasterized representation stored in an ITK-readable research format using any of the tools mentioned above, and then convert the result into DICOM Segmentation image using dcmqi. The measurements reported over the region defined by the Segmentation image can then be stored as a DICOM TID1500 Structured report.

What are the formats that dcmqi supports?

The research formats we support are specific to the type of the object being converted, as summarized in the table below.

How is dcmqi related to ...?

Below is the list of various tools that are used by medical imaging researchers, and description of how they relate to dcmqi:

• - does not provide tools for conversion of DICOM objects supported by dcmqi. dcmqi uses ITK as a lower-level component for reading and writing research formats, and for image data operations.

• , - provide attribute- and SR tree-level C++ API for interacting with DICOM data; provide general-purpose command line tools for converting DICOM objects into human-readable list of attribute, and editing individual attributes of a DICOM dataset; do not provide tools for generating DICOM objects from research formats. dcmqi is using DCMTK as the lower-level component to operate on DICOM data.

Can I use dcmqi for patient care?

dcmqi is intended for research work and has no FDA clearances or approvals of any kind. It is the responsibility of the user to comply with all laws and regulations (and moral/ethical guidelines) when using dcmqi.

Usage related questions

I cannot load DICOM SEG into Slicer

Make sure you install the .

Conversion fails with the "Missing Attribute(s)" error - what should I do?

Image-derived objects, such as segmentations or parametric map, inherit some of the attributes from the image they were derived from. Such attributes include, for example, those from the "General Study" and "Patient" modules. In the situation where some of those attributes that are mandatory, but are not present in the source images, converter will fail. The reason for this is that the converter will not write out an invalid object, and a valid object cannot be constructed when mandatory attributes are missing.

To resolve this situation, you can patch the source image to add the missing attributes. To do such patching we recommend the DCMTK tool.

As an example, here is an error that would be generated by the itkimage2segimage converter when a mandatory "CodingSchemeDesignator" attribute is missing in the source DICOM image:

Examining the content of the source image, indeed this attribute is missing, but :

To fix this issue, the following command can be used:

Note the "99" prefix used for the coding scheme designator. Unless you know which coding scheme the specific code belongs to, you should always use this prefix to indicate that the coding scheme is "private" (not one of ).

I cannot scroll when loading DICOM SEG into 3D Slicer

The way 3D Slicer works at the moment is that you cannot scroll over the slices of the segmentation unless your segmentation is accompanied by the image that was segmented.

Try importing the DICOM image you segmented into the Slicer DICOM database, and load both the segmentation and image series.

If you agree this behavior is confusing, add your voice to .

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

Prerequisites

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

2. recent version of

Note that you can also see the specific components and steps needed to build dcmqi by looking at the CI configuration scripts ( for Lunux, for Mac, and 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 , and are the following:

Both can be installed with npm as follows:

Superbuild approach

With the superbuild approach, all of the 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

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

Troubleshooting

• Under certain conditions, line endings may be incorrectly initialized for your platform by the checkout process (reported by @CJGoch in ), which may result in errors like below:

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

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

2. If there is no matching code that is already included in DICOM, you can : 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.

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 , 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 , 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: , 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 () 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:

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

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 , put the search term in the search box, and specify FMA in the "Ontologies" selector:

The search is successful, leading to , 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 , and for the same term, which :

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:

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

Segmentation

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

• SegmentedPropertyCategoryCodeSequence

• SegmentedPropertyTypeCodeSequence

• SegmentedPropertyTypeModifierCodeSequence (when applicable)

This looks overwhelming indeed! That's why we developed 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) (extensible, i.e., you are not forced to use only the codes from this selection)

SegmentedPropertyTypeCodeSequence codes are defined in , 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 , as an example see .

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 for the list of codes. Modifier for this code is specified as needed, following the same approach as discussed for SegmentedPropertyTypeModifierCodeSequence.

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

SNOMED CT License exemption

Note that SNOMED CT codes included in the DICOM standard are exempt from . The details are discussed in . 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 :

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

• MeasurementUnitsCode: Units of measurement. DICOM uses code system (CodingSchemeDesignator UCUM) to describe units. Some of the commonly used unit codes are listed in , but as discussed in , any of the UCUM codes can be used in DICOM.

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). These codes are expected to become part of the standard in Spring 2017.

For now, the best place to start is (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.

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.

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

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.

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.

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 .

These are some of the known limitations of dcmqi:

• It is currently not possible to use the converters when you don't have the source DICOM data; in the future, we are planning to add a mode of operation when all of necessary the metadata can be specified in the input JSON file.

• We do not support conversion of the data (segmentations, parametric maps or measurements) derived from enhanced multiframe images.

• Support of DICOM SR TID 1500 is limited to the measurements derived from the rasterized segmentations; we do not support all of the capabilities of TID 1500.

The following section provides information to developers that want to contribute to the DCMQI development.

With the current architecture, it is not straightforward to add a new attribute to the schema, since numerous locations need to be updated. It might be most efficient to use past pull requests adding specific attributes as a guide. The following examples might be useful:

• add SegmentLabel to DICOM SEG: https://github.com/QIICR/dcmqi/pull/376

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

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 .

dcmqi is using pre-built binaries of ITK and DCMTK for Appveyor to reduce the overall build time of the library.

Every time the release of DCMTK/ITK needs to be updated, it is important to re-generate these binaries, otherwise Appveyor build will fail when there are API changes.

Updating DCMTK and ITK packages

The modified version of DCMTK is located in the dcmqi branch of the . The only difference from the stock DCMTK source code is the appveyor.yml file. Thus, the steps are the following:

1. Check out the version of DCMTK that needs to be used

2. Rebase the dcmqi branch of dcmtk-dcmqi to the new version.

3. Update the name of the package to reflect the version and date of the DCMTK package to be created (deploy/release section of the appveyor.yml)

Appveyor build will be triggered automatically, and barring any build issues a new release will be uploaded to .

The URL corresponding to DCMTK-dcmqi.zip in the release should then be used to first update , which should result in re-generated ITK-dcmqi package under ITK-dcmqi releases in . At that time, URLs for both ITK-dcmqi and DCMTK-dcmqi packages should be updated in the dcmqi appveyor script file: .

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)

To generate a release, you will need to set up GPG keys on your platform to sign the commits. You can follow these GitHub instructions to complete that step.

1. Check that tests pass on all platforms

2. Edit CMakeLists.txt and update DCMQI_VERSION_* variables, update README.md file to point to the updated version number for the Docker image.

3. Commit changes using message like cmake: Set DCMQI version to 1.0.7

4. Create corresponding tag:

5. Push tag and master (in that order) to trigger the release build and upload

6. Once new packages are generated, update documentation section to point to the new package.

Under the hood ...

dcmqi is using publish_github_release from to upload and manage releases from CI to GitHub.

of the scikit-ci-addons documentation describes how to troubleshoot issues related to this mechanism.

Converter fails with the error - what should I do?

If you are on Windows:

• if you are using Docker, make sure you read this section: , and that the drive you are using to pass data in and out of the docker is shared in the Docker settings

dcmqi is leveraging multiple open source projects. We are gratefully acknowledging those projects in the list below (list to be extended, links to be added):