Console Applications

Included console applications

dicom_dump

Scan folders of DICOM files, and report the structure. Can be handy when the sorting of the images is unclear.

Example of output on a MR diffusion-weighted acquisition:

% dicom_dump ./EP2D_DIFF_B50_400_800_TRA_P2_TRACEW_DFC_MIX_0007
StuInsUID 1.2.3.4.30000019020708423676500000016: 90 images
SerInsUID 1.2.3.4.2019020714224132517098797.0.0.0: 90 images
SerTim 142629.896000: 90 images
SeqNam *ep_b50t: 30 images
SeqNam *ep_b400t: 30 images
SeqNam *ep_b800t: 30 images
AcqNum 1: 90 images
ImaTyp DERIVED: 90 images
Echo 1: 90 images

image_calculator

Calculate a new series based on existing series.

Usage:: image_calculator <output> <expression> <inputs>

The inputs will be assigned variables a, b, c, etc. The expression, like ‘a+b’, should result in a new series of similar size as ‘a’. This series will be saved in the <output>. The calculator can do simple math and np (NumPy) operations, as long as the resulting image has a shape compatible with ‘a’.

DICOM series typically result in uint16 data. To perform the calculation in floating point, include option ‘--dtype float64’.

Example calculating mean of three series. The input data are converted to float64:

% image_calculator --serdes 'Mean T1_VIBE_FLIP' --dtype float64 \
    mean '(a+b+c)/3' T1_VIBE_FLIP*
Converting input...
a = T1_VIBE_FLIP18_0013 (30, 192, 192) float64
b = T1_VIBE_FLIP3_0011 (30, 192, 192) float64
c = T1_VIBE_FLIP8_0012 (30, 192, 192) float64
mean = (a+b+c)/3 (30, 192, 192) float64

Example creating a mask=1 of equal size to input data. Notice the input data is only used to give matrix dimensions:

% image_calculator mask '1' T1_VIBE_FLIP8_0012/
a = T1_VIBE_FLIP8_0012/ (30, 192, 192) uint16
mask = 1 (30, 192, 192) uint16

Example creating a mask = np.eye(128). Notice there is no input data:

% image_calculator eye 'Series(np.eye(128))'
eye = Series(np.eye(128)) (128, 128) float64

By default, np.eye() will produce float64 data as above. There are three methods to set the output to uint16:

% image_calculator eye 'Series(np.eye(128, dtype=np.uint16))'
eye = Series(np.eye(128,dtype=np.uint16)) (128, 128) uint16

% image_calculator --dtype uint16 eye 'Series(np.eye(128))'
eye = Series(np.eye(128)) (128, 128) float64

In the latter case, the output float64 data is converted to uint16 when writing the output.

An existing DICOM object can be used as template to set DICOM attributes:

% image_calculator --template dicom/input --geometry dicom/input eye 'Series(np.eye(128))'
eye = Series(np.eye(128)) (128, 128) float64

image_data

Convert input to output data, possible modifying the image format. The input data can be a cohort of series, study and patients. The output will be sorted in folders with appropriate names.

Usage:

image_data [<options>] <output> <input list…>

Some options:

--of <output format>: Possible output format: dicom, itk, nifti, mat (default: dicom). Can be repeated.

--order <input order>: How to sort input files: time, b, fa, te (default: ‘none’).

--dtype <dtype>: Specify output datatype. Otherwise keep input datatype. Dtypes: uint8, uint16, int16, int, float, float32, float64, double.

--template <template>: Source to get DICOM template from.

--geometry <template>: Second DICOM template for geometry attributes.

--sernum <number>: Set DICOM series number.

--serdes <string>: Set DICOM series description.

--imagetype: Set DICOM imagetype, comma-separated. E.g. ‘DERIVED,SECONDARY,MASK’

See “imagedata --help” for other options.

Example: First a DICOM volume is converted to ITK MetaImage. Next, the ITK MetaImage is read, adding DICOM attributes from the original DICOM volume. After setting series number and description, the images are sent to PACS using the DICOM protocol.

# Convert dicom/volume to itk/Image.mha
#                   Output        Input
image_data --of itk itk/Image.mha dicom/volume

# Convert itk/Image.mha to dicom using original data as template
# Send to DICOM store
image_data --of dicom \
    --template dicom/volume \
    --sernum 1000 \
    --serdes 'Series description' \
    --imagetype 'DERIVED,SECONDARY,MASK' \
    dicom://server:104/AETITLE # Output destination \
    itk/Image.mha              # Input data

image_list

List available data on URL.

Example, recursive list on xnat-server:

% image_list -r xnat://xnat.local/Project/Subject/Experiment

image_show

Display an image stack interactively.

Some options:: --order <input order>: How to sort input files (time, b, fa, te) (default: ‘none’).

The following controls can be used to manipulate the viewer:

Mouse scroll wheel: scroll through the slices of a volume
Array up/down: scroll through the slices of a volume
Array left/right: step through the 4th dimension of a 4D dataset
PgUp/PgDown: Page through datasets when there are more datasets than views
Left mouse key pressed: adjust window/level of display
Mouse over: will display 2D coordinate and signal intensity at mouse position
‘q’: Quit. Will end the console application.

image_statistics

Describe series shape, dtype, min, max and mean. The input data can be a cohort of series, study and patients. The output will report on series parameters for each patient, study and series.

timeline

Print timeline for a dynamic acquisition

Write your own console applications

A command line program can be as simple as copying input to output, selecting input and output formats by command line options. See Figure for an example:

import argparse
import imagedata.cmdline
from imagedata import Series

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    imagedata.cmdline.add_argparse_options(parser)
    parser.add_argument("out_name", help="Output URL")
    parser.add_argument("in_dirs", nargs='+', help="Input URL")
    args = parser.parse_args()

    try:
        si = Series(args.in_dirs, opts=args)
    except Exception as e:
        print('Could not read {}: {}’.format(args.in_dirs, e))

    si.write(args.out_name, opts=args)

This python script can be called from the command line to convert and transport images.