Command Line Tools - dgobbi/vtk-dicom GitHub Wiki
The following command-line tools are provided:
- dicomdump displays all of the attributes of a DICOM file
- dicomfind searches a directory for DICOM files, similar to UNIX "find"
- dicompull copy files that match a query to a new directory
- dicomtocsv finds DICOM files and prints requested fields into a .csv file
- dicomtodicom performs some simple manipulations on DICOM files
- dicomtonifti converts DICOM files to NIfTI format
- niftitodicom converts NIfTI files to DICOM
Download
These tools can be downloaded from https://github.com/dgobbi/vtk-dicom/releases, which provides pre-built binaries for several operating systems.
They are also available in the vtk-dicom-tools package on Ubuntu and Debian Linux:
sudo apt-get install vtk-dicom-tools
Unicode support
All arguments (including filenames) to these command-line tools are expected to be in Unicode, and all input/output text is utf-8. On UNIX and Linux, this implies the use of a utf-8 locale. On Windows, the console automatically converts the local encoding to unicode.
For example, when dicomdump or dicomtocsv are used to display the contents of a DICOM data element that supports character-set encoding, the SpecificCharacterSet attribute is used to convert the text to utf-8 prior to display.
If the files are missing the SpecificCharacterSet attribute, you can use the "--charset" option to set the file encoding. The following is a table of the available encodings:
ascii us-ascii iso-646-us iso-ir-6
latin1 iso-8859-1 iso-ir-100
latin2 iso-8859-2 iso-ir-101
latin3 iso-8859-3 iso-ir-109
latin4 iso-8859-4 iso-ir-110
cyrillic iso-8859-5 iso-ir-144
arabic iso-8859-6 iso-ir-127
greek iso-8859-7 iso-ir-126
hebrew iso-8859-8 iso-ir-138
latin5 iso-8859-9 iso-ir-148
tis-620 iso-8859-11 iso-ir-166
latin9 iso-8859-15 iso-ir-203
utf-8 iso-ir-192
iso-2022 (generic iso-2022 decoding)
jis_x0201 iso-ir-13 iso-ir-14
iso-2022-jp iso-ir-87
shift-jis ms932 windows-31j
korean euc-kr windows-949 iso-ir-149
chinese gbk
gb2312 iso-ir-58
gb18030
big5
cp1250
cp1251
cp1252
cp1253
cp1254
cp1255
Query options
The tools dicomfind, dicompull, dicomtocsv, and dicomdump support the use of queries via the "-k" and "-q" options. These options provide a unified syntax for supplying attributes to be used in a query. The following two calls to dicomfind are equivalent, given the following contents of "query.txt":
dicomfind . -k Modality=MR -k ImageType=ORIGINAL
dicomfind . -q query.txt
Contents of "query.txt":
# query.txt
Modality=MR
ImageType=ORIGINAL
The "-k" and "-q" options can be mixed on the same command line, since the query file is interpreted as a series of "-k" arguments.
Queries are always combined with a logical "and" operation, so the above query will only match files where Modality=MR and ImageType=ORIGINAL.
Syntax
The general syntax for a query attribute is "Key=Value", though the "Value" is optional. If no value is given, then the attribute is simply used as a hint that programs like dicomtocsv should return information about the attribute. Some examples of query syntax are as follows:
SeriesDescription="*T1*" # value in quotes, with wildcards (quotes are optional)
SeriesDate=2011-2014 # date range (ranges are inclusive)
PatientName="Smith^John" # name (for names, matching is case-insensitive)
PatientName # universal match (always matches)
PatientName= # ditto
0008,0060=MR # hexadecimal tag
The key must be the "Keyword" given in Part 6, Table 6-1 of the DICOM standard, or given in hexadecimal. Double-quotes around the value are optional, unless the value contains spaces, in which case the quotes are mandatory. A quote can be escaped by using two quote characters:
SeriesDescription="DTI ""31""" # DTI "31"
The backslash is not used as an escape character, because it is used in DICOM as a value separator:
ImageType=ORIGINAL\PRIMARY # two values: ORIGINAL and PRIMARY
A backslash can also be used to specify a tag path for nested data elements:
# these are equivalent
0040,0260\0008,0100
PerformedProtocolCodeSequence\CodeValue
As indicated by all these samples, "#" can be used to begin a comment, but it must be preceded by a space unless it appears at the beginning of the line.
Private element syntax
Private elements must be identified not only by their tag, but also by the value of the associated creator element. As well, the VR for private tags should be given explicitly:
[GEMS_ACQU_01]0019,0084:DS # PeakSAR private tag with VR of DS
The creator value appears first in square brackets, to identify the private dictionary. The tag and the VR follow, with an optional "=" followed by a value for matching. The first two digits of the element number (0084 in the example above) should be set to zero, since they are ignored (see DICOM Part 5 Section 7.8 for further details).
Matching
When query attributes are given a value, then the command-line tools will only return information for files whose attributes match the query. The following matching rules are used:
Date, Time, and DateTime attributes can specify a range by using a hyphen. For dates, the month and day are optional. For times, the minutes and seconds are optional.
StudyDate=2004 # match all dates in 2004
StudyDate=20040130-20040215 # dates from Jan 30, 2004 to Feb 15, 2004 inclusive
Non-numerical text attributes can be matched with a wildcard string, where "*" and "?" are the wildcards. If no wildcards are present, the match must be exact. All text matching is done in utf-8 (non-utf8 text is converted to utf8 for matching).
Name matching is case-insensitive, with "^" as the component separator. You can provide as many or as few parts of the name as desired, and can include wildcards.
If the query provides a multi-valued attribute, then in the file the attribute must have those same values in the same order. For example,
ImageType=ORIGINAL\AXIAL # will match ORIGINAL\PRIMARY\AXIAL
UID matching is an exception to this rule. If a UI attribute is given in the query with multiple values, then a match will be generated if one of those values matches the file.