1dcmicmp(1)                        OFFIS DCMTK                       dcmicmp(1)
2
3
4

NAME

6       dcmicmp - Compare DICOM images and compute difference metrics
7
8

SYNOPSIS

10       dcmicmp [options] dcmfile-in-1 dcmfile-in-2
11

DESCRIPTION

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
20       The dcmicmp utility then compares both images and computes  and  prints
21       metrics that describe how similar or different both images are:
22
23       • 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
27       • the  mean  absolute  error  (MAE)  is  the average difference between
28         original pixel value and test image pixel value
29
30       • 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
34       • 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
40       • 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
45       All  metrics  are  computed as defined in R.C. Gonzalez and R.E. Woods,
46       'Digital Image Processing,' Prentice Hall 2008.
47

PARAMETERS

49       dcmfile-in-1  Reference DICOM image file for comparison
50
51       dcmfile-in-2  Test DICOM image file for comparison
52

OPTIONS

54   general options
55         -h    --help
56                 print this help text and exit
57
58               --version
59                 print version information and exit
60
61               --arguments
62                 print expanded command line arguments
63
64         -q    --quiet
65                 quiet mode, print no warnings and errors
66
67         -v    --verbose
68                 verbose mode, print processing details
69
70         -d    --debug
71                 debug mode, print debug information
72
73         -ll   --log-level  [l]evel: string constant
74                 (fatal, error, warn, info, debug, trace)
75                 use level l for the logger
76
77         -lc   --log-config  [f]ilename: string
78                 use config file f for the logger
79
80   input options
81       input file format:
82
83         +f    --read-file
84                 read file format or data set (default)
85
86         +fo   --read-file-only
87                 read file format only
88
89         -f    --read-dataset
90                 read data set without file meta information
91
92       input transfer syntax:
93
94         -t=   --read-xfer-auto
95                 use TS recognition (default)
96
97         -td   --read-xfer-detect
98                 ignore TS specified in the file meta header
99
100         -te   --read-xfer-little
101                 read with explicit VR little endian TS
102
103         -tb   --read-xfer-big
104                 read with explicit VR big endian TS
105
106         -ti   --read-xfer-implicit
107                 read with implicit VR little endian TS
108
109   image processing options
110       modality LUT transformation:
111
112         +M    --use-modality
113                 use modality LUT transformation (default)
114
115         -M    --no-modality
116                 ignore stored modality LUT transformation
117
118       VOI LUT transformation:
119
120         -W    --no-windowing
121                 no VOI windowing (default)
122
123         +Wi   --use-window  [n]umber: integer
124                 use the n-th VOI window from image file
125
126         +Wl   --use-voi-lut  [n]umber: integer
127                 use the n-th VOI look up table from image file
128
129         +Wm   --min-max-window
130                 compute VOI window using min-max algorithm
131                 on both images separately
132
133         +Wn   --min-max-window-n
134                 compute VOI window using min-max algorithm
135                 on both images separately, ignoring extremes
136
137         +Wr   --min-max-ref
138                 compute VOI window using min-max algorithm
139                 and use same window for the test image
140
141         +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
146         +Ww   --set-window  [c]enter [w]idth: float
147                 compute VOI window using center c and width w
148
149         +Wfl  --linear-function
150                 set VOI LUT function to LINEAR
151
152         +Wfs  --sigmoid-function
153                 set VOI LUT function to SIGMOID
154
155       presentation LUT transformation:
156
157         +Pid  --identity-shape
158                 set presentation LUT shape to IDENTITY
159
160         +Piv  --inverse-shape
161                 set presentation LUT shape to INVERSE
162
163         +Pod  --lin-od-shape
164                 set presentation LUT shape to LIN OD
165
166   image comparison metrics options
167         +ce   --check-error  [l]imit: integer
168                 check if max absolute error <= limit
169
170         # Return exit code EXITCODE_LIMIT_EXCEEDED_MAX_ERROR if the computed
171         # maximum absolute error is larger than the given limit.
172
173         +cm   --check-mae  [l]imit: float
174                 check if mean absolute error <= limit
175
176         # Return exit code EXITCODE_LIMIT_EXCEEDED_MAE if the computed
177         # mean absolute error is larger than the given limit.
178
179         +cr   --check-rmse  [l]imit: float
180                 check if root mean square error <= limit
181
182         # Return exit code EXITCODE_LIMIT_EXCEEDED_RMSE if the computed
183         # root mean square error is larger than the given limit.
184
185         +cp   --check-psnr  [l]imit: float
186                 check if PSNR >= limit
187
188         # 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
192         +cs   --check-snr  [l]imit: float
193                 check if SNR >= limit
194
195         # 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
199   output options
200         +sd   --save-diff  [f]ilename: string
201                 write secondary capture difference image
202
203         # 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
211         +a    --amplify  [f]actor: float
212                 multiply diff image pixel values by f
213
214         # 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

NOTES

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
241   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

TRANSFER SYNTAXES

250       dcmicmp supports the following transfer syntaxes for input:
251
252       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
257       The  difference  image file is always written in Little Endian Implicit
258       Transfer Syntax.
259
260       (*) if compiled with zlib support enabled
261

LOGGING

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
274       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

COMMAND LINE

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
288       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
295       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

EXIT CODES

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
307   general
308       EXITCODE_NO_ERROR                         0
309       EXITCODE_COMMANDLINE_SYNTAX_ERROR         1
310
311   input/output file errors
312       EXITCODE_INVALID_INPUT_FILE              22
313       EXITCODE_CANNOT_WRITE_OUTPUT_FILE        40
314
315   image processing errors
316       EXITCODE_INITIALIZE_DIFF_IMAGE           80
317       EXITCODE_DISPLAY_PIPELINE                81
318       EXITCODE_IMAGE_COMPARISON                82
319
320   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

ENVIRONMENT

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
334       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

SEE ALSO

344       dcm2pnm(1)
345
347       Copyright  (C)  2018  by  OFFIS  e.V.,  Escherweg  2,  26121 Oldenburg,
348       Germany.
349
350
351
352Version 3.6.4                   Thu Nov 29 2018                     dcmicmp(1)
Impressum