1dcmicmp(1) OFFIS DCMTK dcmicmp(1)
2
6 dcmicmp - Compare DICOM images and compute difference metrics
7
10 dcmicmp [options] dcmfile-in-1 dcmfile-in-2
11
13 The dcmicmp utility reads two DICOM images, an original 'reference
14 image' and a post-processed 'test image', to which some kind of
15 processing such as a lossy image compression, followed by
16 decompression, has been applied. This tool requires that both images
17 have the same resolution, the same number of frames and are either both
18 color or monochrome. Compressed images are not supported.
19 The dcmicmp utility then compares both images and computes and prints
21 metrics that describe how similar or different both images are:
22 • the maximum absolute error is the largest difference between an pixel
24 value in the reference image and the corresponding pixel value in the
25 test image.
26 • the mean absolute error (MAE) is the average difference between
28 original pixel value and test image pixel value
29 • the root mean square error (RMSE) is computed by adding the squares
31 of all difference values, then dividing by the number of values
32 added, and then taking the square root.
33 • The peak signal to noise ratio (PSNR) considers the reference image
35 as a signal and the differences between reference and test image as
36 noise. PSNR is the maximum signal strength (i.e. maximum pixel value
37 in the reference image) divided by the RMSE, expressed on a
38 logarithmic scale in dB.
39 • The signal to noise ratio (PSNR) also considers the reference image
41 as a signal and the differences between reference and test image as
42 noise. SNR is the average signal strength divided by the RMSE,
43 expressed on a logarithmic scale in dB.
44 All metrics are computed as defined in R.C. Gonzalez and R.E. Woods,
46 'Digital Image Processing,' Prentice Hall 2008.
47
49 dcmfile-in-1 Reference DICOM image file for comparison
50 dcmfile-in-2 Test DICOM image file for comparison
52
54 general options
55 -h --help
56 print this help text and exit
57 --version
59 print version information and exit
60 --arguments
62 print expanded command line arguments
63 -q --quiet
65 quiet mode, print no warnings and errors
66 -v --verbose
68 verbose mode, print processing details
69 -d --debug
71 debug mode, print debug information
72 -ll --log-level [l]evel: string constant
74 (fatal, error, warn, info, debug, trace)
75 use level l for the logger
76 -lc --log-config [f]ilename: string
78 use config file f for the logger
79 input options
81 input file format:
82 +f --read-file
84 read file format or data set (default)
85 +fo --read-file-only
87 read file format only
88 -f --read-dataset
90 read data set without file meta information
91 input transfer syntax:
93 -t= --read-xfer-auto
95 use TS recognition (default)
96 -td --read-xfer-detect
98 ignore TS specified in the file meta header
99 -te --read-xfer-little
101 read with explicit VR little endian TS
102 -tb --read-xfer-big
104 read with explicit VR big endian TS
105 -ti --read-xfer-implicit
107 read with implicit VR little endian TS
108 image processing options
110 modality LUT transformation:
111 +M --use-modality
113 use modality LUT transformation (default)
114 -M --no-modality
116 ignore stored modality LUT transformation
117 VOI LUT transformation:
119 -W --no-windowing
121 no VOI windowing (default)
122 +Wi --use-window [n]umber: integer
124 use the n-th VOI window from image file
125 +Wl --use-voi-lut [n]umber: integer
127 use the n-th VOI look up table from image file
128 +Wm --min-max-window
130 compute VOI window using min-max algorithm
131 on both images separately
132 +Wn --min-max-window-n
134 compute VOI window using min-max algorithm
135 on both images separately, ignoring extremes
136 +Wr --min-max-ref
138 compute VOI window using min-max algorithm
139 and use same window for the test image
140 +Wq --min-max-n-ref
142 compute VOI window using min-max algorithm,
143 ignoring extreme values
144 and use same window for the test image
145 +Ww --set-window [c]enter [w]idth: float
147 compute VOI window using center c and width w
148 +Wfl --linear-function
150 set VOI LUT function to LINEAR
151 +Wfs --sigmoid-function
153 set VOI LUT function to SIGMOID
154 presentation LUT transformation:
156 +Pid --identity-shape
158 set presentation LUT shape to IDENTITY
159 +Piv --inverse-shape
161 set presentation LUT shape to INVERSE
162 +Pod --lin-od-shape
164 set presentation LUT shape to LIN OD
165 image comparison metrics options
167 +ce --check-error [l]imit: integer
168 check if max absolute error <= limit
169 # Return exit code EXITCODE_LIMIT_EXCEEDED_MAX_ERROR if the computed
171 # maximum absolute error is larger than the given limit.
172 +cm --check-mae [l]imit: float
174 check if mean absolute error <= limit
175 # Return exit code EXITCODE_LIMIT_EXCEEDED_MAE if the computed
177 # mean absolute error is larger than the given limit.
178 +cr --check-rmse [l]imit: float
180 check if root mean square error <= limit
181 # Return exit code EXITCODE_LIMIT_EXCEEDED_RMSE if the computed
183 # root mean square error is larger than the given limit.
184 +cp --check-psnr [l]imit: float
186 check if PSNR >= limit
187 # Return exit code EXITCODE_LIMIT_EXCEEDED_PSNR if the computed
189 # peak signal to noise ratio is smaller than the given limit
190 # (for PSNR, higher values mean better image quality)
191 +cs --check-snr [l]imit: float
193 check if SNR >= limit
194 # Return exit code EXITCODE_LIMIT_EXCEEDED_PSNR if the computed
196 # signal to noise ratio is smaller than the given limit
197 # (for SNR, higher values mean better image quality)
198 output options
200 +sd --save-diff [f]ilename: string
201 write secondary capture difference image
202 # Create a Multiframe Secondary Capture image that contains a
204 # difference image between reference and test image. For monochrome
205 # images, one difference frame is created for each frame in the reference
206 # image. For color images, three monochrome frames are created for each
207 # frame in the reference image, corresponding to the differences in the
208 # red, green and blue color plane. The difference image will have
209 # BitsStored 8 or 16, depending on the properties of the reference image.
210 +a --amplify [f]actor: float
212 multiply diff image pixel values by f
213 # This option can be used to amplify the grayscale values in the
215 # difference image by multiplying each value with the given factor.
216 # Alternatively, a DICOM VOI LUT window may be used when visualizing
217 # the difference image.
218
220 grayscale display pipeline
221 Monochrome DICOM images require that a multi-stage display pipeline is
222 executed in order to convert the raw pixel values to the so-called
223 presentation values (p-values) that are sent to the (possibly
224 calibrated) display. When comparing the similarity of images before and
225 after post-processing, it can be relevant to activate some stages of
226 this display pipeline before calculating the difference image and
227 metrics. The image processing options allow the caller to either
228 activate or deactivate the Modality LUT, VOI LUT and Presentation LUT
229 transformations. In any case, the same transformation is applied to
230 both images, although possibly with different parameters if for example
231 the 'first VOI LUT window' stored in each image is applied. This
232 assumes that the post-processing algorithm (e.g. compression algorithm)
233 has adapted the values of such windows during compression such that the
234 image display after applying the window is as close as possible to the
235 reference. For images with more than 8 bits/sample it may be important
236 to known which VOI LUT transformation will be applied by the user when
237 viewing the image, because this may affect the perceived image quality.
238 Therefore, absolute Window parameters can also be given with the --set-
239 window option, which will then be applied to both images.
240 suitability of images for diagnostic purposes
242 The user should also note that the metrics computed by this tool cannot
243 predict or estimate the suitability of lossy compressed image for
244 diagnostic purposes. Much more complex image processing and an
245 understanding of the image content (e.g. body part) would be needed for
246 this purpose. The metrics computed provide an estimation of the level
247 of distortion caused by the post-processing - no more and no less.
248
250 dcmicmp supports the following transfer syntaxes for input:
251 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
253 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
254 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*)
255 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
256 The difference image file is always written in Little Endian Implicit
258 Transfer Syntax.
259 (*) if compiled with zlib support enabled
261
263 The level of logging output of the various command line tools and
264 underlying libraries can be specified by the user. By default, only
265 errors and warnings are written to the standard error stream. Using
266 option --verbose also informational messages like processing details
267 are reported. Option --debug can be used to get more details on the
268 internal activity, e.g. for debugging purposes. Other logging levels
269 can be selected using option --log-level. In --quiet mode only fatal
270 errors are reported. In such very severe error events, the application
271 will usually terminate. For more details on the different logging
272 levels, see documentation of module 'oflog'.
273 In case the logging output should be written to file (optionally with
275 logfile rotation), to syslog (Unix) or the event log (Windows) option
276 --log-config can be used. This configuration file also allows for
277 directing only certain messages to a particular output stream and for
278 filtering certain messages based on the module or application where
279 they are generated. An example configuration file is provided in
280 <etcdir>/logger.cfg.
281
283 All command line tools use the following notation for parameters:
284 square brackets enclose optional values (0-1), three trailing dots
285 indicate that multiple values are allowed (1-n), a combination of both
286 means 0 to n values.
287 Command line options are distinguished from parameters by a leading '+'
289 or '-' sign, respectively. Usually, order and position of command line
290 options are arbitrary (i.e. they can appear anywhere). However, if
291 options are mutually exclusive the rightmost appearance is used. This
292 behavior conforms to the standard evaluation rules of common Unix
293 shells.
294 In addition, one or more command files can be specified using an '@'
296 sign as a prefix to the filename (e.g. @command.txt). Such a command
297 argument is replaced by the content of the corresponding text file
298 (multiple whitespaces are treated as a single separator unless they
299 appear between two quotation marks) prior to any further evaluation.
300 Please note that a command file cannot contain another command file.
301
303 The dcmicmp utility uses the following exit codes when terminating.
304 This enables the user to check for the reason why the application
305 terminated.
306 general
308 EXITCODE_NO_ERROR 0
309 EXITCODE_COMMANDLINE_SYNTAX_ERROR 1
310 input/output file errors
312 EXITCODE_INVALID_INPUT_FILE 22
313 EXITCODE_CANNOT_WRITE_OUTPUT_FILE 40
314 image processing errors
316 EXITCODE_INITIALIZE_DIFF_IMAGE 80
317 EXITCODE_DISPLAY_PIPELINE 81
318 EXITCODE_IMAGE_COMPARISON 82
319 error codes for exceeded limits
321 EXITCODE_LIMIT_EXCEEDED_MAX_ERROR 90
322 EXITCODE_LIMIT_EXCEEDED_MAE 91
323 EXITCODE_LIMIT_EXCEEDED_RMSE 92
324 EXITCODE_LIMIT_EXCEEDED_PSNR 93
325 EXITCODE_LIMIT_EXCEEDED_SNR 94
326
328 The dcmicmp utility will attempt to load DICOM data dictionaries
329 specified in the DCMDICTPATH environment variable. By default, i.e. if
330 the DCMDICTPATH environment variable is not set, the file
331 <datadir>/dicom.dic will be loaded unless the dictionary is built into
332 the application (default for Windows).
333 The default behavior should be preferred and the DCMDICTPATH
335 environment variable only used when alternative data dictionaries are
336 required. The DCMDICTPATH environment variable has the same format as
337 the Unix shell PATH variable in that a colon (':') separates entries.
338 On Windows systems, a semicolon (';') is used as a separator. The data
339 dictionary code will attempt to load each file specified in the
340 DCMDICTPATH environment variable. It is an error if no data dictionary
341 can be loaded.
342
344 dcm2pnm(1)
345
347 Copyright (C) 2018-2022 by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
348 Germany.
349Version 3.6.7 Fri Apr 22 2022 dcmicmp(1)