dicomfind

Search a directory tree for DICOM files

Usage

dicomfind [options] <directory> ...

Options

  -L                Follow symbolic links (default).
  -P                Do not follow symbolic links.
  -k tag=value      Provide an attribute to be queried and matched.
  -q <query.txt>    Provide a file to describe the find query.
  -u <uids.txt>     Provide a file that contains a list of UIDs.
  -maxdepth n       Set the maximum directory depth.
  -name pattern     Set a pattern to match (with "*" or "?").
  -image            Restrict the search to files with PixelData.
  -series           Find all files in series if even one file matches.
  -print            Print the filenames of all matched files (default).
  -print0           Print the filenames with terminating null, for xargs.
  -exec ... +       Execute the given command for every series matched.
  -exec ... \;      Execute the given command for every file matched.
  -execdir ... +    Go to directory and execute command on every series.
  -execdir ... \;   Go to directory and execute command on every file.
  --ignore-dicomdir Ignore the DICOMDIR file even if it is present.
  --charset <cs>    Charset to use if SpecificCharacterSet is missing.
  --help            Print a brief help message.
  --version         Print the software version.

The backslash before ';' is required when using dicomfind in a UNIX shell, because the semicolon is a special character. The semicolon is used here because it is also used in the UNIX find command.

Description

This command can be used to locate DICOM files, and to optionally execute a command on each file. It shares many features with the UNIX "find" command. When searching for files with a specific attribute (with "-k"), the tag can be specified in the form GGGG,EEEE or with its canonical name e.g. Modality=MR from the DICOM dictionary. Alternately, the tags can be listed in a query file given with the "-q" option (one tag per line). Private tags are supported with a special syntax, as described in Command Line Tools.

Details

The "-maxdepth", "-name", "-print", and "-print0" options work the same as for UNIX find. Because "-print" is the default action, it is usually omitted unless you want to use it as a side-effect with "-exec". Unlike UNIX find, there is no "-or" or "-and", and no grouping of options with parentheses.

The "-image" option will match files that have PixelData, and will also match FloatPixelData and DoubleFloatPixelData. Note that DICOMDIR files are considered to be indexes to other DICOM files, so they are never returned. See below for additional information on DICOMDIR handling.

The "-exec" and "-execdir" arguments cause dicomfind to run the specified program on the found files. For example, to dump each file one would use "-exec dicomdump {} ;" where each instance of {} will be replaced by a found file, and ";" indicates the end of the args to dicomdump. Alternately, if "+" is used to end the args, then the program will be run on each DICOM series and {} will be replaced by all files in the series. The "-execdir" argument is similar, except that it runs the program from within the directory of the file (or files), and {} is replaced by just the filenames instead of with the full paths.

An example for finding all image files with Modality=MR in the current directory or subdirectories, and running gdcmconv to decompress them in-place by using the file as both the input and the output for gdcmconv:

dicomfind . -k Modality=MR -image -exec gdcmconv --raw {} {} \;

If the specified directory contains a DICOMDIR file, then dicomfind will use the DICOMDIR file as an index for the files within that directory and its subdirectories, and any files not listed in the DICOMDIR will be ignored. The purpose is to accelerate the search of DICOM CDs. DICOMDIR files that are found in any subdirectories are ignored.

An advanced feature that dicomfind shares with dicompull and dicomtocsv is that you can specify an OsiriX Database.sql file in place of a directory. This will cause these programs to scan the OsiriX database for matching files. Since the author of dicomfind has no documentation for the OsiriX database schema (which may change from one version of OsiriX to the next), this is an unsupported and highly experimental feature.

See also

• dicompull will find files and copy them into a new directory structure
• dicomtocsv will find files and summarize them for use in a spreadsheet