4 \page dcmj2pnm Convert DICOM images to PGM/PPM, PNG, TIFF, JPEG or BMP
6 \page dcmj2pnm dcmj2pnm: Convert DICOM images to PGM/PPM, PNG, TIFF, JPEG or BMP
9 \section synopsis SYNOPSIS
12 dcmj2pnm [options] dcmfile-in [bitmap-out]
15 \section description DESCRIPTION
17 The \b dcmj2pnm 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, JPEG
20 (Joint Photographic Experts Group) or Windows BMP format. This utility
21 supports uncompressed as well as JPEG and RLE compressed DICOM images.
23 \section parameters PARAMETERS
26 dcmfile-in DICOM input filename to be converted
28 bitmap-out output filename to be written (default: stdout)
31 \section options OPTIONS
33 \subsection general_options general options
36 print this help text and exit
39 print version information and exit
42 print expanded command line arguments
45 quiet mode, print no warnings and errors
48 verbose mode, print processing details
51 debug mode, print debug information
53 -ll --log-level [l]evel: string constant
54 (fatal, error, warn, info, debug, trace)
55 use level l for the logger
57 -lc --log-config [f]ilename: string
58 use config file f for the logger
61 \subsection input_options input options
66 read file format or data set (default)
72 read data set without file meta information
74 input transfer syntax:
77 use TS recognition (default)
79 -td --read-xfer-detect
80 ignore TS specified in the file meta header
82 -te --read-xfer-little
83 read with explicit VR little endian TS
86 read with explicit VR big endian TS
88 -ti --read-xfer-implicit
89 read with implicit VR little endian TS
92 \subsection image_processing_options image processing options
96 +F --frame [n]umber: integer
97 select specified frame (default: 1)
99 +Fr --frame-range [n]umber [c]ount: integer
100 select c frames beginning with frame n
108 rotate image left (-90 degrees)
111 rotate image right (+90 degrees)
113 +Rtd --rotate-top-down
114 rotate image top-down (180 degrees)
118 +Lh --flip-horizontally
119 flip image horizontally
121 +Lv --flip-vertically
122 flip image vertically
124 +Lhv --flip-both-axes
125 flip image horizontally and vertically
129 +a --recognize-aspect
130 recognize pixel aspect ratio (default)
133 ignore pixel aspect ratio when scaling
135 +i --interpolate [n]umber of algorithm: integer
136 use interpolation when scaling (1..4, default: 1)
138 -i --no-interpolation
139 no interpolation when scaling
142 no scaling, ignore pixel aspect ratio (default)
144 +Sxf --scale-x-factor [f]actor: float
145 scale x axis by factor, auto-compute y axis
147 +Syf --scale-y-factor [f]actor: float
148 scale y axis by factor, auto-compute x axis
150 +Sxv --scale-x-size [n]umber: integer
151 scale x axis to n pixels, auto-compute y axis
153 +Syv --scale-y-size [n]umber: integer
154 scale y axis to n pixels, auto-compute x axis
156 color space conversion (compressed images only):
158 +cp --conv-photometric
159 convert if YCbCr photometric interpretation (default)
162 convert YCbCr to RGB if lossy JPEG
165 convert to RGB if YCbCr is guessed by library
167 +cgl --conv-guess-lossy
168 convert to RGB if lossy JPEG and YCbCr is
169 guessed by the underlying JPEG library
172 always convert YCbCr to RGB
175 never convert color space
177 modality LUT transformation:
180 ignore stored modality LUT transformation
183 use modality LUT transformation (default)
185 VOI LUT transformation:
188 no VOI windowing (default)
190 +Wi --use-window [n]umber: integer
191 use the n-th VOI window from image file
193 +Wl --use-voi-lut [n]umber: integer
194 use the n-th VOI look up table from image file
197 compute VOI window using min-max algorithm
199 +Wn --min-max-window-n
200 compute VOI window using min-max algorithm,
201 ignoring extreme values
203 +Wr --roi-min-max-window [l]eft [t]op [w]idth [h]eight: integer
204 compute ROI window using min-max algorithm,
205 region of interest is specified by l,t,w,h
207 +Wh --histogram-window [n]umber: integer
208 compute VOI window using Histogram algorithm,
211 +Ww --set-window [c]enter [w]idth: float
212 compute VOI window using center c and width w
214 +Wfl --linear-function
215 set VOI LUT function to LINEAR
217 +Wfs --sigmoid-function
218 set VOI LUT function to SIGMOID
220 presentation LUT transformation:
222 +Pid --identity-shape
223 set presentation LUT shape to IDENTITY
226 set presentation LUT shape to INVERSE
229 set presentation LUT shape to LIN OD
234 do not display overlays
236 +O --display-overlay [n]umber: integer
237 display overlay n (0..16, 0=all, default: +O 0)
240 use overlay mode "Replace"
241 (default for Graphic overlays)
244 use overlay mode "Threshold Replace"
246 +Omc --ovl-complement
247 use overlay mode "Complement"
250 use overlay mode "Invert Bitmap"
253 use overlay mode "Region of Interest"
254 (default for ROI overlays)
256 +Osf --set-foreground [d]ensity: float
257 set overlay foreground density (0..1, default: 1)
259 +Ost --set-threshold [d]ensity: float
260 set overlay threshold density (0..1, default: 0.5)
262 display LUT transformation:
264 +Dm --monitor-file [f]ilename: string
265 calibrate output according to monitor characteristics
268 +Dp --printer-file [f]ilename: string
269 calibrate output according to printer characteristics
272 +Da --ambient-light [a]mbient light: float
273 ambient light value (cd/m^2, default: file f)
275 +Di --illumination [i]llumination: float
276 illumination value (cd/m^2, default: file f)
278 +Dn --min-density [m]inimum optical density: float
279 Dmin value (default: off, only with +Dp)
281 +Dx --max-density [m]aximum optical density: float
282 Dmax value (default: off, only with +Dp)
285 use GSDF for calibration (default for +Dm/+Dp)
287 +Dc --cielab-function
288 use CIELAB function for calibration
292 +Ma --accept-acr-nema
293 accept ACR-NEMA images without photometric
296 +Mp --accept-palettes
297 accept incorrect palette attribute tags
298 (0028,111x) and (0028,121x)
300 +Mc --check-lut-depth
301 check 3rd value of the LUT descriptor, compare
302 with expected bit depth based on LUT data
304 +Mm --ignore-mlut-depth
305 ignore 3rd value of the modality LUT descriptor,
306 determine bits per table entry automatically
308 +Mv --ignore-vlut-depth
309 ignore 3rd value of the VOI LUT descriptor,
310 determine bits per table entry automatically
315 LZW compression (default)
323 +Pd --predictor-default
324 no LZW predictor (default)
327 LZW predictor 1 (no prediction)
330 LZW predictor 2 (horizontal differencing)
332 +Rs --rows-per-strip [r]ows: integer (default: 0)
333 rows per strip, default 8K per strip
338 create interlaced file (default)
341 create non-interlaced file
344 create PNG file meta information (default)
347 no PNG file meta information
351 +Jq --compr-quality [q]uality: integer (0..100, default: 90)
352 quality value for compression (in percent)
355 4:4:4 sampling (no subsampling)
358 4:2:2 subsampling (horizontal subsampling of
359 chroma components, default)
362 4:1:1 subsampling (horizontal and vertical
363 subsampling of chroma components)
365 other transformations:
368 convert to grayscale if necessary
371 change polarity (invert pixel output)
373 +C --clip-region [l]eft [t]op [w]idth [h]eight: integer
374 clip image region (l, t, w, h)
377 \subsection output_options output options
382 print image details (requires verbose mode)
385 do not create any output (useful with -im)
390 write 8-bit binary PGM/PPM (default for files)
392 +opb --write-8-bit-pnm
393 write 8-bit ASCII PGM/PPM (default for stdout)
395 +opw --write-16-bit-pnm
396 write 16-bit ASCII PGM/PPM
398 +opn --write-n-bit-pnm [n]umber: integer
399 write n-bit ASCII PGM/PPM (1..32)
402 write 8-bit (monochrome) or 24-bit (color) BMP
404 +obp --write-8-bit-bmp
405 write 8-bit palette BMP (monochrome only)
407 +obt --write-24-bit-bmp
408 write 24-bit truecolor BMP
410 +obr --write-32-bit-bmp
411 write 32-bit truecolor BMP
414 write 8-bit (monochrome) or 24-bit (color) TIFF
417 write 8-bit (monochrome) or 24-bit (color) PNG
420 write 8-bit lossy JPEG (baseline)
425 The following preferred interpolation algorithms can be selected using the
426 \e --interpolate option:
428 \li 1 = free scaling algorithm with interpolation from pbmplus toolkit
429 \li 2 = free scaling algorithm with interpolation from c't magazine
430 \li 3 = magnification algorithm with bilinear interpolation from Eduard Stanescu
431 \li 4 = magnification algorithm with bicubic interpolation from Eduard Stanescu
433 The \e --write-tiff option is only available when DCMTK has been configured
434 and compiled with support for the external \b libtiff TIFF library. The
435 availability of the TIFF compression options depends on the \b libtiff
436 configuration. In particular, the patented LZW algorithm may not be
439 The \e --write-png option is only available when DCMTK has been configured
440 and compiled with support for the external \b libpng PNG library. Option
441 \e --interlace enables progressive image view while loading the PNG file.
442 Only a few applications take care of the meta info (TEXT) in a PNG file.
444 \section transfer_syntaxes TRANSFER SYNTAXES
446 \b dcmj2pnm supports the following transfer syntaxes for input (\e dcmfile-in):
449 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
450 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
451 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*)
452 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
453 JPEGProcess1TransferSyntax 1.2.840.10008.1.2.4.50
454 JPEGProcess2_4TransferSyntax 1.2.840.10008.1.2.4.51
455 JPEGProcess6_8TransferSyntax 1.2.840.10008.1.2.4.53
456 JPEGProcess10_12TransferSyntax 1.2.840.10008.1.2.4.55
457 JPEGProcess14TransferSyntax 1.2.840.10008.1.2.4.57
458 JPEGProcess14SV1TransferSyntax 1.2.840.10008.1.2.4.70
459 RLELosslessTransferSyntax 1.2.840.10008.1.2.5
462 (*) if compiled with zlib support enabled
464 \section logging LOGGING
466 The level of logging output of the various command line tools and underlying
467 libraries can be specified by the user. By default, only errors and warnings
468 are written to the standard error stream. Using option \e --verbose also
469 informational messages like processing details are reported. Option
470 \e --debug can be used to get more details on the internal activity, e.g. for
471 debugging purposes. Other logging levels can be selected using option
472 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
473 very severe error events, the application will usually terminate. For more
474 details on the different logging levels, see documentation of module "oflog".
476 In case the logging output should be written to file (optionally with logfile
477 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
478 can be used. This configuration file also allows for directing only certain
479 messages to a particular output stream and for filtering certain messages
480 based on the module or application where they are generated. An example
481 configuration file is provided in <em><etcdir>/logger.cfg</em>).
483 \section command_line COMMAND LINE
485 All command line tools use the following notation for parameters: square
486 brackets enclose optional values (0-1), three trailing dots indicate that
487 multiple values are allowed (1-n), a combination of both means 0 to n values.
489 Command line options are distinguished from parameters by a leading '+' or '-'
490 sign, respectively. Usually, order and position of command line options are
491 arbitrary (i.e. they can appear anywhere). However, if options are mutually
492 exclusive the rightmost appearance is used. This behaviour conforms to the
493 standard evaluation rules of common Unix shells.
495 In addition, one or more command files can be specified using an '@' sign as a
496 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
497 is replaced by the content of the corresponding text file (multiple
498 whitespaces are treated as a single separator unless they appear between two
499 quotation marks) prior to any further evaluation. Please note that a command
500 file cannot contain another command file. This simple but effective approach
501 allows to summarize common combinations of options/parameters and avoids
502 longish and confusing command lines (an example is provided in file
503 <em><datadir>/dumppat.txt</em>).
505 \section environment ENVIRONMENT
507 The \b dcmj2pnm utility will attempt to load DICOM data dictionaries specified
508 in the \e DCMDICTPATH environment variable. By default, i.e. if the
509 \e DCMDICTPATH environment variable is not set, the file
510 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
511 into the application (default for Windows).
513 The default behaviour should be preferred and the \e DCMDICTPATH environment
514 variable only used when alternative data dictionaries are required. The
515 \e DCMDICTPATH environment variable has the same format as the Unix shell
516 \e PATH variable in that a colon (":") separates entries. On Windows systems,
517 a semicolon (";") is used as a separator. The data dictionary code will
518 attempt to load each file specified in the \e DCMDICTPATH environment variable.
519 It is an error if no data dictionary can be loaded.
523 <em><datadir>/camera.lut</em> - sample characteristics file of a camera
524 \n<em><datadir>/monitor.lut</em> - sample characteristics file of a monitor
525 \n<em><datadir>/printer.lut</em> - sample characteristics file of a printer
526 \n<em><datadir>/scanner.lut</em> - sample characteristics file of a scanner
528 \section see_also SEE ALSO
530 <b>dcm2pnm</b>(1), <b>img2dcm</b>(1)
532 \section copyright COPYRIGHT
534 Copyright (C) 2001-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.