dcmmkdir - Man Page

Create a DICOMDIR file

Synopsis

dcmmkdir [options] [dcmfile-in...]

Description

The dcmmkdir utility creates a DICOMDIR file from the specified referenced DICOM files according to the DICOM Part 11 Media Storage Application Profiles​.

Currently the following profiles are supported (others might be added later):

This tool extends dcmgpdir which can only create General Purpose DICOMDIR files​. The default behavior of dcmmkdir (with --general-purpose) is equivalent to that of dcmgpdir​.

Parameters

dcmfile-in  referenced DICOM file (or directory to be scanned)

Options

general options

  -h    --help
          print this help text and exit

        --version
          print version information and exit

        --arguments
          print expanded command line arguments

  -q    --quiet
          quiet mode, print no warnings and errors

  -v    --verbose
          verbose mode, print processing details

  -d    --debug
          debug mode, print debug information

  -ll   --log-level  [l]evel: string constant
          (fatal, error, warn, info, debug, trace)
          use level l for the logger

  -lc   --log-config  [f]ilename: string
          use config file f for the logger

input options

DICOMDIR identifiers:

  +F    --fileset-id  [i]d: string
          use specific file-set ID
          (default: DCMTK_MEDIA_DEMO, "" for none)

  +R    --descriptor  [f]ilename: string
          add a file-set descriptor file ID
          (e.g. README, default: no descriptor)

  +C    --char-set  [c]harset: string
          add a specific character set for descriptor
          (default: "ISO_IR 100" if descriptor present)

reading:

  +id   --input-directory  [d]irectory: string
          read referenced DICOM files from directory d
          (default for --recurse: current directory)

  -m    --keep-filenames
          expect filenames to be in DICOM format (default)

  +m    --map-filenames
          map to DICOM filenames (lowercase->uppercase,
          and remove trailing period)

  -r    --no-recurse
          do not recurse within directories (default)

  +r    --recurse
          recurse within filesystem directories

  +p    --pattern  [p]attern: string (only with --recurse)
          pattern for filename matching (wildcards)

          # possibly not available on all systems

processing options

consistency check:

  -W    --no-consistency-check
          do not check files for consistency

  +W    --warn-inconsist-files
          warn about inconsistent files (default)

  -a    --abort-inconsist-file
          abort on first inconsistent file

type 1 attributes:

  -I    --strict
          exit with error if DICOMDIR type 1 attributes
          are missing in DICOM file (default)

  +I    --invent
          invent DICOMDIR type 1 attributes if missing in DICOM file

  +Ipi  --invent-patient-id
          invent new PatientID in case of inconsistent
          PatientName attributes

other checks:

  +Nrs  --allow-retired-sop
          allow retired SOP classes defined in previous editions
          of the DICOM standard

  -Nxc  --no-xfer-check
          do not reject images with non-standard transfer syntax
          (just warn)

  -Nec  --no-encoding-check
          do not reject images with non-standard pixel encoding
          (just warn)

  -Nrc  --no-resolution-check
          do not reject images with non-standard spatial resolution
          (just warn)

icon images:

  +X    --add-icon-image
          add monochrome icon image on IMAGE level
          (default for cardiac profiles)

  -Xs   --icon-image-size  [s]ize: integer (1..128)
          width and height of the icon image (in pixel)
          (fixed: 128 for XA, 64 for CT/MR profile)

  -Xi   --icon-file-prefix  [p]refix: string
          use PGM image 'prefix'+'dcmfile-in' as icon
          (default: create icon from DICOM image)

  -Xd   --default-icon  [f]ilename: string
          use specified PGM image if icon cannot be
          created automatically (default: black image)

output options

DICOMDIR file:

  +D    --output-file  [f]ilename: string
          generate specific DICOMDIR file
          (default: DICOMDIR in current directory)

profiles:

  -Pgp  --general-purpose
          General Purpose Interchange on CD-R, DVD-RAM or BD Media
          (STD-GEN-CD/DVD-RAM/BD, default)

  -Pdv  --general-dvd-jpeg
          General Purpose DVD Interchange with JPEG
          (STD-GEN-DVD-JPEG)

  -Pd2  --general-dvd-j2k
          General Purpose DVD Interchange with JPEG 2000
          (STD-GEN-DVD-J2K)

  -Pbd  --general-bd-jpeg
          General Purpose BD Interchange with JPEG
          (STD-GEN-BD-JPEG)

  -Pb2  --general-bd-j2k
          General Purpose BD Interchange with JPEG 2000
          (STD-GEN-BD-J2K)

  -Pbm  --general-bd-mpeg2-mpml
          General Purpose BD Interchange with MPEG2 MP@ML
          (STD-GEN-BD-MPEG2-MPML)

  -Pbh  --general-bd-mpeg2-mphl
          General Purpose BD Interchange with MPEG2 MP@HL
          (STD-GEN-BD-MPEG2-MPHL)

  -Pba  --general-bd-mpeg4-hp
          General Purpose BD Interchange with MPEG-4 AVC/H.264
          HiP@Level4.1 (STD-GEN-BD-MPEG4-HPLV41)

  -Pbb  --general-bd-mpeg4-hpbd
          General Purpose BD Interchange with MPEG-4 AVC/H.264
          BD-Compatible HiP@Level4.1 (STD-GEN-BD-MPEG4-HPLV41BD)

        --general-bd-mpeg4-hp2d
          General Purpose BD Interchange with MPEG-4 AVC/H.264
          HiP@Level4.2 for 2D video (STD-GEN-BD-MPEG4-HPLV42-2D)

        --general-bd-mpeg4-hp3d
          General Purpose BD Interchange with MPEG-4 AVC/H.264
          HiP@Level4.2 for 3D video (STD-GEN-BD-MPEG4-HPLV42-3D)

        --general-bd-mpeg4-hpst
          General Purpose BD Interchange with MPEG-4 AVC/H.264
          Stereo HiP@Level4.2 (STD-GEN-BD-MPEG4-SHPLV42)

  -Pfl  --usb-and-flash-jpeg
          General Purpose USB/Flash Memory Interchange with JPEG
          (STD-GEN-USB/MMC/CF/SD-JPEG)

  -Pf2  --usb-and-flash-j2k
          General Purpose USB/Flash Memory Interchange with JPEG 2000
          (STD-GEN-USB/MMC/CF/SD-J2K)

  -Pmi  --general-mime
          General Purpose MIME Interchange (STD-GEN-MIME)

  -Pmp  --mpeg2-mpml-dvd
          DVD Interchange with MPEG2 Main Profile @ Main Level
          (STD-DVD-MPEG2-MPML)

  -Pbc  --basic-cardiac
          Basic Cardiac X-Ray Angiographic Studies on CD-R Media
          (STD-XABC-CD)

  -Pxa  --xray-angiographic
          1024 X-Ray Angiographic Studies on CD-R Media
          (STD-XA1K-CD)

  -Pxd  --xray-angiographic-dvd
          1024 X-Ray Angiographic Studies on DVD Media
          (STD-XA1K-DVD)

  -Pde  --dental-radiograph
          Dental Radiograph Interchange (STD-DEN-CD)

  -Pcm  --ct-and-mr
          CT/MR Studies (STD-CTMR-xxxx)

  -Pus  --ultrasound-id-sf
          Ultrasound Single Frame for Image Display
          (STD-US-ID-SF-xxxx)

        --ultrasound-sc-sf
          Ultrasound Single Frame with Spatial Calibration
          (STD-US-SC-SF-xxxx)

        --ultrasound-cc-sf
          Ultrasound Single Frame with Combined Calibration
          (STD-US-CC-SF-xxxx)

  -Pum  --ultrasound-id-mf
          Ultrasound Single & Multi-Frame for Image Display
          (STD-US-ID-MF-xxxx)

        --ultrasound-sc-mf
          Ultrasound Single & Multi-Frame with Spatial Calibration
          (STD-UD-SC-MF-xxxx)

        --ultrasound-cc-mf
          Ultrasound Single & Multi-Frame with Combined Calibration
          (STD-UD-CC-MF-xxxx)

  -Pec  --12-lead-ecg
          12-lead ECG Interchange on Diskette
          (STD-WVFM-ECG-FD)

  -Phd  --hemodynamic-waveform
          Hemodynamic Waveform Interchange on Diskette
          (STD-WVFM-HD-FD)

writing:

  -A    --replace
          replace existing DICOMDIR (default)

  +A    --append
          append to existing DICOMDIR

  +U    --update
          update existing DICOMDIR

  -w    --discard
          do not write out DICOMDIR

backup:

        --create-backup
          create a backup of existing DICOMDIR (default)

  -nb   --no-backup
          do not create a backup of existing DICOMDIR

post-1993 value representations:

  +u    --enable-new-vr
          enable support for new VRs (UN/UT) (default)

  -u    --disable-new-vr
          disable support for new VRs, convert to OB

group length encoding:

  -g    --group-length-remove
          write without group length elements (default)

  +g    --group-length-create
          write with group length elements

length encoding in sequences and items:

  +e    --length-explicit
          write with explicit lengths (default)

  -e    --length-undefined
          write with undefined lengths

Notes

All files specified on the command line (or discovered by recursively examining the contents of directories with the +r option) are first evaluated for their compatibility with the specified Media Storage Application Profile (Part 11)​. Only appropriate files encoded using one of the allowed Transfer Syntaxes will be accepted​. Files having invalid filenames will be rejected (the rules can be relaxed via the +m option)​. Files missing required attributes will be rejected (the +I option can relax this behavior)​.

A DICOMDIR file will only be constructed if all files have passed initial tests​.

The dcmmkdir utility also allows one to append new entries to and to update existing entries in a DICOMDIR file​. Using option +A new entries are only appended to the DICOMDIR, i​.e​. existing records like the ones for PATIENT information are not updated​. Using option +U also existing records are updated according to the information found in the referenced DICOM files​. Please note that this update process might be slower than just appending new entries​. However, it makes sure that additional information that is required for the selected application profile is also added to existing records​.

The support for icon images is currently restricted to monochrome images​. This might change in the future​. Till then, color images are automatically converted to grayscale mode​. The icon size is 128*128 pixels for the cardiac profiles (as required by the DICOM standard) and 64*64 for all others​.

Scanning Directories

Adding files from directories is possible by using option --recurse​. If no further command line parameters are given, the directory specified by option --input-directory (default: current directory) is scanned for files​. If parameters are given, they can either specify a file or directory name; the input directory is always prepended​. If the files in the provided directories should be selected according to a specific name pattern (e​.g​. using wildcard matching), option --pattern has to be used​. Please note that this file pattern only applies to the files within the scanned directories, and, if any other patterns are specified on the command line outside the --input-directory option (e​.g​. in order to select further files), these do not apply to the specified directories​.

Logging

The level of logging output of the various command line tools and underlying libraries can be specified by the user​. By default, only errors and warnings are written to the standard error stream​. Using option --verbose also informational messages like processing details are reported​. Option --debug can be used to get more details on the internal activity, e​.g​. for debugging purposes​. Other logging levels can be selected using option --log-level​. In --quiet mode only fatal errors are reported​. In such very severe error events, the application will usually terminate​. For more details on the different logging levels, see documentation of module 'oflog'​.

In case the logging output should be written to file (optionally with logfile rotation), to syslog (Unix) or the event log (Windows) option --log-config can be used​. This configuration file also allows for directing only certain messages to a particular output stream and for filtering certain messages based on the module or application where they are generated​. An example configuration file is provided in <etcdir>/logger​.cfg​.

Command Line

All command line tools use the following notation for parameters: square brackets enclose optional values (0-1), three trailing dots indicate that multiple values are allowed (1-n), a combination of both means 0 to n values​.

Command line options are distinguished from parameters by a leading '+' or '-' sign, respectively​. Usually, order and position of command line options are arbitrary (i​.e​. they can appear anywhere)​. However, if options are mutually exclusive the rightmost appearance is used​. This behavior conforms to the standard evaluation rules of common Unix shells​.

In addition, one or more command files can be specified using an '@' sign as a prefix to the filename (e​.g​. @command​.txt)​. Such a command argument is replaced by the content of the corresponding text file (multiple whitespaces are treated as a single separator unless they appear between two quotation marks) prior to any further evaluation​. Please note that a command file cannot contain another command file​. This simple but effective approach allows one to summarize common combinations of options/parameters and avoids longish and confusing command lines (an example is provided in file <datadir>/dumppat​.txt)​.

Environment

The dcmmkdir utility will attempt to load DICOM data dictionaries specified in the DCMDICTPATH environment variable​. By default, i​.e​. if the DCMDICTPATH environment variable is not set, the file <datadir>/dicom​.dic will be loaded unless the dictionary is built into the application (default for Windows)​.

The default behavior should be preferred and the DCMDICTPATH environment variable only used when alternative data dictionaries are required​. The DCMDICTPATH environment variable has the same format as the Unix shell PATH variable in that a colon (':') separates entries​. On Windows systems, a semicolon (';') is used as a separator​. The data dictionary code will attempt to load each file specified in the DCMDICTPATH environment variable​. It is an error if no data dictionary can be loaded​.

See Also

dcmgpdir(1)

Info

Wed Dec 11 2024 Version 3.6.9 OFFIS DCMTK