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.
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/.
developer environment for your platform (compiler, git)
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:
Both can be installed with npm as follows:
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
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:
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:
To resolve this, check your global git settings. If you have autocrlf set, you may try setting it to auto.
dcmqi is a collection of libraries and command line tools. It is currently possible to install dcmqi using one of the following approaches:
Using binaries for your platform from either the "latest" or named release
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.
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.
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.
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.
You will first need to install Docker on your system following these instructions. 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.
Note the system requirements:
you will need to have Windows 10 Pro or above
you will need to enable Hyper-V package (Docker will prompt you)
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:
right click onto the Docker task bar icon and choose "Settings"
choose "Shared Drives" from the left menu (a list of drives that are available to share will be displayed)
select the drive for your HOST_DIR to be shared
confirm with Apply and continue
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 here. It does not rely on any proprietary or non-open-source components.
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.
(also see dcmqi introduction tutorial!)
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.
