Utility Programs

The Merge DICOM Toolkit supplies several useful utility programs. These utilities can be used to help you validate your own implementations and better understand the standard.

All these utilities use the Merge DICOM Toolkit C Run-time Library and require that you set your MERGE_INI environment variable to point to the toolkit's initialization file (merge.ini).


Compare two DICOM objects - mc3comp

The mc3comp utility can be used to find the differences between two DICOM objects. The objects can be encoded in either the DICOM file or "stream" format and do not have to be encoded in the same format. The utility will output differences in tags between the messages taking into account differences in byte ordering and encoding. The syntax for the utility is the following:

mc3comp [-t1 <syntax> -t2 <syntax>] [-e file] [-o -m1 -m2] file1 file2

where:

-t1=Optional specify transfer syntax of 'file1' message, where
<syntax>=‘il’ for implicit little endian (default),
‘el’ for explicit little endian,
‘eb’ for explicit big endian
-t2=Optional specify transfer syntax of 'file1' message, where
<syntax>=‘il’ for implicit little endian (default),
‘el’ for explicit little endian,
‘eb’ for explicit big endian
-e <file>=Optional exception file of all tags to ignore in comparison
-o=Compare OB/OW (e.g. binary pixel data)
-m1=Compare ‘file1’ in DICOM-3 file format
-m2=Compare ‘file2’ in DICOM-3 file format
file1=DICOM SOP Instance (message) file
file2=Another DICOM SOP Instance (message) file
-h=get help - print this usage description

Example: mc3comp -t1 il -m2 -o 1.img 1.dcm



Convert between various transfer syntaxes - mc3conv

The mc3conv utility can be used to convert a DICOM object between various transfer syntaxes and formats. The utility will read an input file and then write the output file in the transfer syntax specified in the command line. The utility can also convert between DICOM "stream" format and the DICOM file format. The syntax for the mc3conv utility is the following:

mc3conv input_file output_file [-t <syntax>] [-p] [-m] [-s <syntax>] [-tag <tag> <"newvalue">]

where:

input_file=DICOM SOP Instance (message) file
output_file=output DICOM SOP Instance (message)/XML file
-t=Specify transfer syntax for 'output_file', where
<syntax>=‘il’ for implicit little endian (default),
‘el’ for explicit little endian,
‘eb’ for explicit big endian
‘eb’ for explicit big endian
‘ib’ for implicit big endian
‘jb’ for jpeg baseline
‘je’ for jpeg extended 2_4
‘jl’ for jpeg lossless hier 14
‘j2lo’ for jpeg 2000 lossless only
‘j2’ for fpeg 2000
‘rle’ for rle

Example: mc3conv in.img out.dcm -t el -m


DICOM ping - mc3echo

The mc3echo utility validates application level communication between two DICOM AE's. An echo test is the equivalent of a network 'ping' operation, but at the DICOM application level rather than the TCP/IP transport level.

The DICOM Toolkit has built-in support of the Verification Service Class and the C-ECHO command.

The command syntax follows:

mc3echo [-c count] [-r remote_host] [-l local_app_title] [-p remote_port] remote_app_title

where:

c countInteger number specifying the number of echoes to send to the
remote host. If -c is not specified, one echo will be performed
r remote_hostHost name of the remote computer. If -r is not specified, the default
value for remote_host is configured in the Application Profile.
l local_app_titleApplication title of this program. If -l is not specified,
the default value for local_app_title is MERGE_ECHO_SCU
p remote_portPort number the remote computer is listening on. If -p is not specified,
the default value for remote_host is configured in the Application Profile.


Display DICOM content - mc3list

mc3list displays the contents of binary DICOM message files in an easy to read manner.

This tool is a useful educational tool as well as a tool that can be used for off-line display of the DICOM messages your application generates or receives.

The command syntax follows:

mc3list [-t ] [-m]

where:

<filename>'=binary file containing a DICOM-3 message
-t=Optional transfer syntax of the message, where
<syntax>=‘il’ for implicit little endian (default),
‘el’ for explicit little endian,
‘eb’ for explicit big endian
‘eb’ for explicit big endian
-mSpecify this if the file is in DICOM Part 10 media format

Example: mc3list message.001 -t eb

The default transfer syntax is implicit little endian (the DICOM default transfer syntax). If the transfer syntax is incorrectly specified, the message will not be displayed correctly.


DICOM message validation tool - mc3valid

The mc3valid utility validates binary message files according to the DICOM standard and notifies you of missing attributes, improper data types, illegal values, and other problems with a message. mc3valid is a powerful educational and validation tool that can be used for the off-line validation of the DICOM messages your application generates or receives.

The command syntax follows:

mc3valid <filename> [-s <serv> -c <cmd>] [-e | -w | -i] [-t <syntax>] [-q] [-p]

where:

<filename>=Name of file containing the message (mandatory, one or more
files may be specified for the same service-command pair)
-s <serv>=Service name for message(s) streamed in (optional)
-s <cmd>=Command name for message(s) streamed in (optional)
-e=Display only error messages (optional)
-w=Display error and warning messages (optional, default)
-i=Display error, warning and info messages (optional)
-t <syntax>=Specify transfer syntax of message, where
<syntax>=‘il’ for implicit little endian (default),
‘el’ for explicit little endian,
‘eb’ for explicit big endian
-q=Disable prompting for correct service-command pair (optional)
-p=Use message template to validate message against (optional,
maintained for backward compatibility only)
-h, -?=print this usage instructions

This tool validates the specified message file; printing errors, warnings, and information generated to standard output. The user can force the message to be validated against a specified DICOM service-command pair if the message does not already contain this information.

If the service-command pair is not contained in the message, the program will list the possible service-command pairs and the user can select one of them. When using this program with a batch file, this option can be shut off with the -q flag.

The default transfer syntax is implicit little endian (the DICOM default transfer syntax). If the transfer syntax is incorrectly specified, the message cannot be validated.

While the toolkit's message validation is quite comprehensive, it does have limitations. These limitations are in general related to conditional attribute types where the condition can not be verified. The DICOM Standard should be always be considered the final authority in validating a DICOM object.


DICOM message generation tool - mc3file

Sample DICOM messages can be generated with the mc3file utility. You specify the service, command, and transfer syntax and mc3file generates a reasonable sample message that is written to a binary file. The contents of this file are generated in DICOM file format or in exactly the format as the message would be streamed over the network.

The program fills in default values for all the required attributes within the message. You can also use this utility to generate its own configuration file, which you can then modify to specify your own values for attributes in generated messages.

These generated messages are purely meant as ‘useful’ examples that can be used to test message exchange or give the application developer a feel for the structure of DICOM messages. They are not intended to represent real world medical data.

The command syntax for mc3file is the following:

mc3file <serv> <cmd> <num> [-g <file>] [-c <file>] [-l] [-m] [-q] [-t <syntax>] [-f <file>]

<serv> <cmd>These two options are always used together. They specify the service name and command for the message to be generated, respectively. These names can be either upper or lower case. If the exact names for a service command pair are not known, the -l option can be used instead to specify the service name and command. If the service name and command are improperly specified, mc3file will act as if the -l option was used and ask the user to input the correct service name and command.
<num>This option specifies the number of message files to be generated by mc3file. If the -g option is used, this option is not needed on the command line. If the -c option is used, mc3file assumes the number is 1, although a higher number can be specified on the command line. mc3file will vary any fields that have a value representation of time when multiple files are generated, although when the -c option is used, the utility will use the time fields as specified in the configuration file. Thus multiple message files generated with the -c option are identical.
-g <filename>This option causes mc3file to generate an ASCII configuration file. The file contains a listing of all the valid attributes for the specified message. The utility also adds sequences contained in the message along with their attributes. Each attribute in the file contains the tag, value representation, and the default value MC3File uses for the attribute. If a given attribute has more than one value, the character '\' is used to delimit the values. A default value listed as 'NULL' means the attribute is set to NULL. If the filename specified already exists, it will be written over my MC3File. The configuration file can be modified and reloaded into MC3File with the -c option to generate a DICOM message.
-c <filename>This option reads in a configuration file previously generated by mc3file. The service name and command for the message need not be specified on the command line because they are contained in . Because multiple files generated with this option are identical, mc3file assume only one file should be generated. This assumption can be overridden by specifying a number on the command line.
-lThis option lists all the service command pairs supported by mc3file. When generating a message, this option can be used instead of explicitly specifying the service name and command on the command line. When specified alone in the command line, the complete list of pairs is printed out without pausing.
-mThis option allows the user to generate a DICOM file. When generating the file object, mc3file encodes the File Meta Information.
-qThis option prevents mc3file from prompting the user for correct service command pairs. It is a useful option when running the program from a batch file.
-t <syntax>This option specifies the transfer syntax the DICOM message generated is stored in. The default transfer syntax is implicit little endian. The possible values for are 'il' for implicit little endian, 'el' for explicit little endian, and 'eb' for explicit big endian.
-f <file>This option allows the user to specify the first eight characters of the names of the DICOM message files being generated. mc3file will then append a unique count to the end of the filename for each message being generated. The default value is 'file' when creating a DICOM file and 'message' when creating the format that DICOM messages send over a network.

MC3File retrieves default values for attributes from the text file "default.pfl". Unlike the "info.pfl" and "diction.pfl" files which are converted into binary files, "default.pfl" is used as a text file. It will first be searched for in the current directory and then in the message information directory. This file contains default values for all messages and for specific service-command pairs. This file can be modified to contain defaults specific for the user, although it is recommended that a backup of the original be kept. If this file is modified, there are no guarantees that the messages generated will validate properly.


Copyright © 2023 Merge Healthcare Solutions Inc. All Rights Reserved.