OFFIS DCMTK  Version 3.6.0
dcm2pnm.man
1 /*!
2 
3 \if MANPAGES
4 \page dcm2pnm Convert DICOM images to PGM/PPM, PNG, TIFF or BMP
5 \else
6 \page dcm2pnm dcm2pnm: Convert DICOM images to PGM/PPM, PNG, TIFF or BMP
7 \endif
8 
9 \section synopsis SYNOPSIS
10 
11 \verbatim
12 dcm2pnm [options] dcmfile-in [bitmap-out]
13 \endverbatim
14 
15 \section description DESCRIPTION
16 
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.
23 
24 \section parameters PARAMETERS
25 
26 \verbatim
27 dcmfile-in DICOM input filename to be converted
28 
29 bitmap-out output filename to be written (default: stdout)
30 \endverbatim
31 
32 \section options OPTIONS
33 
34 \subsection general_options general options
35 \verbatim
36  -h --help
37  print this help text and exit
38 
39  --version
40  print version information and exit
41 
42  --arguments
43  print expanded command line arguments
44 
45  -q --quiet
46  quiet mode, print no warnings and errors
47 
48  -v --verbose
49  verbose mode, print processing details
50 
51  -d --debug
52  debug mode, print debug information
53 
54  -ll --log-level [l]evel: string constant
55  (fatal, error, warn, info, debug, trace)
56  use level l for the logger
57 
58  -lc --log-config [f]ilename: string
59  use config file f for the logger
60 \endverbatim
61 
62 \subsection input_options input options
63 \verbatim
64 input file format:
65 
66  +f --read-file
67  read file format or data set (default)
68 
69  +fo --read-file-only
70  read file format only
71 
72  -f --read-dataset
73  read data set without file meta information
74 
75 input transfer syntax:
76 
77  -t= --read-xfer-auto
78  use TS recognition (default)
79 
80  -td --read-xfer-detect
81  ignore TS specified in the file meta header
82 
83  -te --read-xfer-little
84  read with explicit VR little endian TS
85 
86  -tb --read-xfer-big
87  read with explicit VR big endian TS
88 
89  -ti --read-xfer-implicit
90  read with implicit VR little endian TS
91 \endverbatim
92 
93 \subsection image_processing_options image processing options
94 \verbatim
95 frame selection:
96 
97  +F --frame [n]umber: integer
98  select specified frame (default: 1)
99 
100  +Fr --frame-range [n]umber [c]ount: integer
101  select c frames beginning with frame n
102 
103  +Fa --all-frames
104  select all frames
105 
106 rotation:
107 
108  +Rl --rotate-left
109  rotate image left (-90 degrees)
110 
111  +Rr --rotate-right
112  rotate image right (+90 degrees)
113 
114  +Rtd --rotate-top-down
115  rotate image top-down (180 degrees)
116 
117 flipping:
118 
119  +Lh --flip-horizontally
120  flip image horizontally
121 
122  +Lv --flip-vertically
123  flip image vertically
124 
125  +Lhv --flip-both-axes
126  flip image horizontally and vertically
127 
128 scaling:
129 
130  +a --recognize-aspect
131  recognize pixel aspect ratio (default)
132 
133  -a --ignore-aspect
134  ignore pixel aspect ratio when scaling
135 
136  +i --interpolate [n]umber of algorithm: integer
137  use interpolation when scaling (1..4, default: 1)
138 
139  -i --no-interpolation
140  no interpolation when scaling
141 
142  -S --no-scaling
143  no scaling, ignore pixel aspect ratio (default)
144 
145  +Sxf --scale-x-factor [f]actor: float
146  scale x axis by factor, auto-compute y axis
147 
148  +Syf --scale-y-factor [f]actor: float
149  scale y axis by factor, auto-compute x axis
150 
151  +Sxv --scale-x-size [n]umber: integer
152  scale x axis to n pixels, auto-compute y axis
153 
154  +Syv --scale-y-size [n]umber: integer
155  scale y axis to n pixels, auto-compute x axis
156 
157 modality LUT transformation:
158 
159  -M --no-modality
160  ignore stored modality LUT transformation
161 
162  +M --use-modality
163  use modality LUT transformation (default)
164 
165 VOI LUT transformation:
166 
167  -W --no-windowing
168  no VOI windowing (default)
169 
170  +Wi --use-window [n]umber: integer
171  use the n-th VOI window from image file
172 
173  +Wl --use-voi-lut [n]umber: integer
174  use the n-th VOI look up table from image file
175 
176  +Wm --min-max-window
177  compute VOI window using min-max algorithm
178 
179  +Wn --min-max-window-n
180  compute VOI window using min-max algorithm,
181  ignoring extreme values
182 
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
186 
187  +Wh --histogram-window [n]umber: integer
188  compute VOI window using Histogram algorithm,
189  ignoring n percent
190 
191  +Ww --set-window [c]enter [w]idth: float
192  compute VOI window using center c and width w
193 
194  +Wfl --linear-function
195  set VOI LUT function to LINEAR
196 
197  +Wfs --sigmoid-function
198  set VOI LUT function to SIGMOID
199 
200 presentation LUT transformation:
201 
202  +Pid --identity-shape
203  set presentation LUT shape to IDENTITY
204 
205  +Piv --inverse-shape
206  set presentation LUT shape to INVERSE
207 
208  +Pod --lin-od-shape
209  set presentation LUT shape to LIN OD
210 
211 overlay:
212 
213  -O --no-overlays
214  do not display overlays
215 
216  +O --display-overlay [n]umber: integer
217  display overlay n (0..16, 0=all, default: +O 0)
218 
219  +Omr --ovl-replace
220  use overlay mode "Replace"
221  (default for Graphic overlays)
222 
223  +Omt --ovl-threshold
224  use overlay mode "Threshold Replace"
225 
226  +Omc --ovl-complement
227  use overlay mode "Complement"
228 
229  +Omv --ovl-invert
230  use overlay mode "Invert Bitmap"
231 
232  +Omi --ovl-roi
233  use overlay mode "Region of Interest"
234  (default for ROI overlays)
235 
236  +Osf --set-foreground [d]ensity: float
237  set overlay foreground density (0..1, default: 1)
238 
239  +Ost --set-threshold [d]ensity: float
240  set overlay threshold density (0..1, default: 0.5)
241 
242 display LUT transformation:
243 
244  +Dm --monitor-file [f]ilename: string
245  calibrate output according to monitor characteristics
246  defined in f
247 
248  +Dp --printer-file [f]ilename: string
249  calibrate output according to printer characteristics
250  defined in f
251 
252  +Da --ambient-light [a]mbient light: float
253  ambient light value (cd/m^2, default: file f)
254 
255  +Di --illumination [i]llumination: float
256  illumination value (cd/m^2, default: file f)
257 
258  +Dn --min-density [m]inimum optical density: float
259  Dmin value (default: off, only with +Dp)
260 
261  +Dx --max-density [m]aximum optical density: float
262  Dmax value (default: off, only with +Dp)
263 
264  +Dg --gsd-function
265  use GSDF for calibration (default for +Dm/+Dp)
266 
267  +Dc --cielab-function
268  use CIELAB function for calibration
269 
270 compatibility:
271 
272  +Ma --accept-acr-nema
273  accept ACR-NEMA images without photometric
274  interpretation
275 
276  +Mp --accept-palettes
277  accept incorrect palette attribute tags
278  (0028,111x) and (0028,121x)
279 
280  +Mc --check-lut-depth
281  check 3rd value of the LUT descriptor, compare
282  with expected bit depth based on LUT data
283 
284  +Mm --ignore-mlut-depth
285  ignore 3rd value of the modality LUT descriptor,
286  determine bits per table entry automatically
287 
288  +Mv --ignore-vlut-depth
289  ignore 3rd value of the VOI LUT descriptor,
290  determine bits per table entry automatically
291 
292 TIFF format:
293 
294  +Tl --compr-lzw
295  LZW compression (default)
296 
297  +Tr --compr-rle
298  RLE compression
299 
300  +Tn --compr-none
301  uncompressed
302 
303  +Pd --predictor-default
304  no LZW predictor (default)
305 
306  +Pn --predictor-none
307  LZW predictor 1 (no prediction)
308 
309  +Ph --predictor-horz
310  LZW predictor 2 (horizontal differencing)
311 
312  +Rs --rows-per-strip [r]ows: integer (default: 0)
313  rows per strip, default 8K per strip
314 
315 PNG format:
316 
317  +il --interlace
318  create interlaced file (default)
319 
320  -il --nointerlace
321  create non-interlaced file
322 
323  +mf --meta-file
324  create PNG file meta information (default)
325 
326  -mf --meta-none
327  no PNG file meta information
328 
329 other transformations:
330 
331  +G --grayscale
332  convert to grayscale if necessary
333 
334  +P --change-polarity
335  change polarity (invert pixel output)
336 
337  +C --clip-region [l]eft [t]op [w]idth [h]eight: integer
338  clip image region (l, t, w, h)
339 \endverbatim
340 
341 \subsection output_options output options
342 \verbatim
343 general:
344 
345  -im --image-info
346  print image details (requires verbose mode)
347 
348  -o --no-output
349  do not create any output (useful with -im)
350 
351 image format:
352 
353  +op --write-raw-pnm
354  write 8-bit binary PGM/PPM (default for files)
355 
356  +opb --write-8-bit-pnm
357  write 8-bit ASCII PGM/PPM (default for stdout)
358 
359  +opw --write-16-bit-pnm
360  write 16-bit ASCII PGM/PPM
361 
362  +opn --write-n-bit-pnm [n]umber: integer
363  write n-bit ASCII PGM/PPM (1..32)
364 
365  +ob --write-bmp
366  write 8-bit (monochrome) or 24-bit (color) BMP
367 
368  +obp --write-8-bit-bmp
369  write 8-bit palette BMP (monochrome only)
370 
371  +obt --write-24-bit-bmp
372  write 24-bit truecolor BMP
373 
374  +obr --write-32-bit-bmp
375  write 32-bit truecolor BMP
376 
377  +ot --write-tiff
378  write 8-bit (monochrome) or 24-bit (color) TIFF
379 
380  +on --write-png
381  write 8-bit (monochrome) or 24-bit (color) PNG
382 \endverbatim
383 
384 \section notes NOTES
385 
386 The following preferred interpolation algorithms can be selected using the
387 \e --interpolate option:
388 
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
393 
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
398 available.
399 
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.
404 
405 \section transfer_syntaxes TRANSFER SYNTAXES
406 
407 \b dcm2pnm supports the following transfer syntaxes for input (\e dcmfile-in):
408 
409 \verbatim
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
415 \endverbatim
416 
417 (*) if compiled with zlib support enabled
418 
419 \section logging LOGGING
420 
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".
430 
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>).
437 
438 \section command_line COMMAND LINE
439 
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.
443 
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.
449 
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>).
459 
460 \section environment ENVIRONMENT
461 
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).
467 
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.
475 
476 \section files FILES
477 
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
482 
483 \section see_also SEE ALSO
484 
485 <b>dcmj2pnm</b>(1), <b>img2dcm</b>(1)
486 
487 \section copyright COPYRIGHT
488 
489 Copyright (C) 1998-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.
490 
491 */


Generated on Wed Dec 14 2016 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.8.11