4 \page dcm2pnm Convert DICOM images to PGM/PPM, PNG, TIFF or BMP
6 \page dcm2pnm dcm2pnm: Convert DICOM images to PGM/PPM, PNG, TIFF or BMP
9 \section synopsis SYNOPSIS
12 dcm2pnm [options] dcmfile-in [bitmap-out]
15 \section description DESCRIPTION
17 The \b dcm2pnm utility reads a DICOM image, converts the pixel data according
18 to the selected image processing options and writes back an image in the
19 well-known PGM/PPM (portable gray map / portable pix map), PNG, TIFF or
20 Windows BMP format. This utility only supports uncompressed and RLE
21 compressed DICOM images. The command line tool \b dcmj2pnm also supports a
22 number of JPEG compression schemes.
24 \section parameters PARAMETERS
27 dcmfile-in DICOM input filename to be converted
29 bitmap-out output filename to be written (default: stdout)
32 \section options OPTIONS
34 \subsection general_options general options
37 print this help text and exit
40 print version information and exit
43 print expanded command line arguments
46 quiet mode, print no warnings and errors
49 verbose mode, print processing details
52 debug mode, print debug information
54 -ll --log-level [l]evel: string constant
55 (fatal, error, warn, info, debug, trace)
56 use level l for the logger
58 -lc --log-config [f]ilename: string
59 use config file f for the logger
62 \subsection input_options input options
67 read file format or data set (default)
73 read data set without file meta information
75 input transfer syntax:
78 use TS recognition (default)
80 -td --read-xfer-detect
81 ignore TS specified in the file meta header
83 -te --read-xfer-little
84 read with explicit VR little endian TS
87 read with explicit VR big endian TS
89 -ti --read-xfer-implicit
90 read with implicit VR little endian TS
93 \subsection image_processing_options image processing options
97 +F --frame [n]umber: integer
98 select specified frame (default: 1)
100 +Fr --frame-range [n]umber [c]ount: integer
101 select c frames beginning with frame n
109 rotate image left (-90 degrees)
112 rotate image right (+90 degrees)
114 +Rtd --rotate-top-down
115 rotate image top-down (180 degrees)
119 +Lh --flip-horizontally
120 flip image horizontally
122 +Lv --flip-vertically
123 flip image vertically
125 +Lhv --flip-both-axes
126 flip image horizontally and vertically
130 +a --recognize-aspect
131 recognize pixel aspect ratio (default)
134 ignore pixel aspect ratio when scaling
136 +i --interpolate [n]umber of algorithm: integer
137 use interpolation when scaling (1..4, default: 1)
139 -i --no-interpolation
140 no interpolation when scaling
143 no scaling, ignore pixel aspect ratio (default)
145 +Sxf --scale-x-factor [f]actor: float
146 scale x axis by factor, auto-compute y axis
148 +Syf --scale-y-factor [f]actor: float
149 scale y axis by factor, auto-compute x axis
151 +Sxv --scale-x-size [n]umber: integer
152 scale x axis to n pixels, auto-compute y axis
154 +Syv --scale-y-size [n]umber: integer
155 scale y axis to n pixels, auto-compute x axis
157 modality LUT transformation:
160 ignore stored modality LUT transformation
163 use modality LUT transformation (default)
165 VOI LUT transformation:
168 no VOI windowing (default)
170 +Wi --use-window [n]umber: integer
171 use the n-th VOI window from image file
173 +Wl --use-voi-lut [n]umber: integer
174 use the n-th VOI look up table from image file
177 compute VOI window using min-max algorithm
179 +Wn --min-max-window-n
180 compute VOI window using min-max algorithm,
181 ignoring extreme values
183 +Wr --roi-min-max-window [l]eft [t]op [w]idth [h]eight: integer
184 compute ROI window using min-max algorithm,
185 region of interest is specified by l,t,w,h
187 +Wh --histogram-window [n]umber: integer
188 compute VOI window using Histogram algorithm,
191 +Ww --set-window [c]enter [w]idth: float
192 compute VOI window using center c and width w
194 +Wfl --linear-function
195 set VOI LUT function to LINEAR
197 +Wfs --sigmoid-function
198 set VOI LUT function to SIGMOID
200 presentation LUT transformation:
202 +Pid --identity-shape
203 set presentation LUT shape to IDENTITY
206 set presentation LUT shape to INVERSE
209 set presentation LUT shape to LIN OD
214 do not display overlays
216 +O --display-overlay [n]umber: integer
217 display overlay n (0..16, 0=all, default: +O 0)
220 use overlay mode "Replace"
221 (default for Graphic overlays)
224 use overlay mode "Threshold Replace"
226 +Omc --ovl-complement
227 use overlay mode "Complement"
230 use overlay mode "Invert Bitmap"
233 use overlay mode "Region of Interest"
234 (default for ROI overlays)
236 +Osf --set-foreground [d]ensity: float
237 set overlay foreground density (0..1, default: 1)
239 +Ost --set-threshold [d]ensity: float
240 set overlay threshold density (0..1, default: 0.5)
242 display LUT transformation:
244 +Dm --monitor-file [f]ilename: string
245 calibrate output according to monitor characteristics
248 +Dp --printer-file [f]ilename: string
249 calibrate output according to printer characteristics
252 +Da --ambient-light [a]mbient light: float
253 ambient light value (cd/m^2, default: file f)
255 +Di --illumination [i]llumination: float
256 illumination value (cd/m^2, default: file f)
258 +Dn --min-density [m]inimum optical density: float
259 Dmin value (default: off, only with +Dp)
261 +Dx --max-density [m]aximum optical density: float
262 Dmax value (default: off, only with +Dp)
265 use GSDF for calibration (default for +Dm/+Dp)
267 +Dc --cielab-function
268 use CIELAB function for calibration
272 +Ma --accept-acr-nema
273 accept ACR-NEMA images without photometric
276 +Mp --accept-palettes
277 accept incorrect palette attribute tags
278 (0028,111x) and (0028,121x)
280 +Mc --check-lut-depth
281 check 3rd value of the LUT descriptor, compare
282 with expected bit depth based on LUT data
284 +Mm --ignore-mlut-depth
285 ignore 3rd value of the modality LUT descriptor,
286 determine bits per table entry automatically
288 +Mv --ignore-vlut-depth
289 ignore 3rd value of the VOI LUT descriptor,
290 determine bits per table entry automatically
295 LZW compression (default)
303 +Pd --predictor-default
304 no LZW predictor (default)
307 LZW predictor 1 (no prediction)
310 LZW predictor 2 (horizontal differencing)
312 +Rs --rows-per-strip [r]ows: integer (default: 0)
313 rows per strip, default 8K per strip
318 create interlaced file (default)
321 create non-interlaced file
324 create PNG file meta information (default)
327 no PNG file meta information
329 other transformations:
332 convert to grayscale if necessary
335 change polarity (invert pixel output)
337 +C --clip-region [l]eft [t]op [w]idth [h]eight: integer
338 clip image region (l, t, w, h)
341 \subsection output_options output options
346 print image details (requires verbose mode)
349 do not create any output (useful with -im)
354 write 8-bit binary PGM/PPM (default for files)
356 +opb --write-8-bit-pnm
357 write 8-bit ASCII PGM/PPM (default for stdout)
359 +opw --write-16-bit-pnm
360 write 16-bit ASCII PGM/PPM
362 +opn --write-n-bit-pnm [n]umber: integer
363 write n-bit ASCII PGM/PPM (1..32)
366 write 8-bit (monochrome) or 24-bit (color) BMP
368 +obp --write-8-bit-bmp
369 write 8-bit palette BMP (monochrome only)
371 +obt --write-24-bit-bmp
372 write 24-bit truecolor BMP
374 +obr --write-32-bit-bmp
375 write 32-bit truecolor BMP
378 write 8-bit (monochrome) or 24-bit (color) TIFF
381 write 8-bit (monochrome) or 24-bit (color) PNG
386 The following preferred interpolation algorithms can be selected using the
387 \e --interpolate option:
389 \li 1 = free scaling algorithm with interpolation from pbmplus toolkit
390 \li 2 = free scaling algorithm with interpolation from c't magazine
391 \li 3 = magnification algorithm with bilinear interpolation from Eduard Stanescu
392 \li 4 = magnification algorithm with bicubic interpolation from Eduard Stanescu
394 The \e --write-tiff option is only available when DCMTK has been configured
395 and compiled with support for the external \b libtiff TIFF library. The
396 availability of the TIFF compression options depends on the \b libtiff
397 configuration. In particular, the patented LZW algorithm may not be
400 The \e --write-png option is only available when DCMTK has been configured
401 and compiled with support for the external \b libpng PNG library. Option
402 \e --interlace enables progressive image view while loading the PNG file.
403 Only a few applications take care of the meta info (TEXT) in a PNG file.
405 \section transfer_syntaxes TRANSFER SYNTAXES
407 \b dcm2pnm supports the following transfer syntaxes for input (\e dcmfile-in):
410 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
411 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
412 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*)
413 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
414 RLELosslessTransferSyntax 1.2.840.10008.1.2.5
417 (*) if compiled with zlib support enabled
419 \section logging LOGGING
421 The level of logging output of the various command line tools and underlying
422 libraries can be specified by the user. By default, only errors and warnings
423 are written to the standard error stream. Using option \e --verbose also
424 informational messages like processing details are reported. Option
425 \e --debug can be used to get more details on the internal activity, e.g. for
426 debugging purposes. Other logging levels can be selected using option
427 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
428 very severe error events, the application will usually terminate. For more
429 details on the different logging levels, see documentation of module "oflog".
431 In case the logging output should be written to file (optionally with logfile
432 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
433 can be used. This configuration file also allows for directing only certain
434 messages to a particular output stream and for filtering certain messages
435 based on the module or application where they are generated. An example
436 configuration file is provided in <em><etcdir>/logger.cfg</em>).
438 \section command_line COMMAND LINE
440 All command line tools use the following notation for parameters: square
441 brackets enclose optional values (0-1), three trailing dots indicate that
442 multiple values are allowed (1-n), a combination of both means 0 to n values.
444 Command line options are distinguished from parameters by a leading '+' or '-'
445 sign, respectively. Usually, order and position of command line options are
446 arbitrary (i.e. they can appear anywhere). However, if options are mutually
447 exclusive the rightmost appearance is used. This behaviour conforms to the
448 standard evaluation rules of common Unix shells.
450 In addition, one or more command files can be specified using an '@' sign as a
451 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
452 is replaced by the content of the corresponding text file (multiple
453 whitespaces are treated as a single separator unless they appear between two
454 quotation marks) prior to any further evaluation. Please note that a command
455 file cannot contain another command file. This simple but effective approach
456 allows to summarize common combinations of options/parameters and avoids
457 longish and confusing command lines (an example is provided in file
458 <em><datadir>/dumppat.txt</em>).
460 \section environment ENVIRONMENT
462 The \b dcm2pnm utility will attempt to load DICOM data dictionaries specified
463 in the \e DCMDICTPATH environment variable. By default, i.e. if the
464 \e DCMDICTPATH environment variable is not set, the file
465 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
466 into the application (default for Windows).
468 The default behaviour should be preferred and the \e DCMDICTPATH environment
469 variable only used when alternative data dictionaries are required. The
470 \e DCMDICTPATH environment variable has the same format as the Unix shell
471 \e PATH variable in that a colon (":") separates entries. On Windows systems,
472 a semicolon (";") is used as a separator. The data dictionary code will
473 attempt to load each file specified in the \e DCMDICTPATH environment variable.
474 It is an error if no data dictionary can be loaded.
478 <em><datadir>/camera.lut</em> - sample characteristics file of a camera
479 \n<em><datadir>/monitor.lut</em> - sample characteristics file of a monitor
480 \n<em><datadir>/printer.lut</em> - sample characteristics file of a printer
481 \n<em><datadir>/scanner.lut</em> - sample characteristics file of a scanner
483 \section see_also SEE ALSO
485 <b>dcmj2pnm</b>(1), <b>img2dcm</b>(1)
487 \section copyright COPYRIGHT
489 Copyright (C) 1998-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.