1/*!
2
3\if MANPAGES
4\page dcmj2pnm Convert DICOM images to PGM/PPM, PNG, TIFF, JPEG or BMP
5\else
6\page dcmj2pnm dcmj2pnm: Convert DICOM images to PGM/PPM, PNG, TIFF, JPEG or BMP
7\endif
8
9\section dcmj2pnm_synopsis SYNOPSIS
10
11\verbatim
12dcmj2pnm [options] dcmfile-in [bitmap-out]
13\endverbatim
14
15\section dcmj2pnm_description DESCRIPTION
16
17The \b dcmj2pnm utility reads a DICOM image, converts the pixel data according
18to the selected image processing options and writes back an image in the
19well-known PGM/PPM (portable gray map / portable pix map), PNG, TIFF, JPEG
20(Joint Photographic Experts Group) or Windows BMP format.  This utility
21supports uncompressed as well as JPEG and RLE compressed DICOM images.
22
23\section dcmj2pnm_parameters PARAMETERS
24
25\verbatim
26dcmfile-in  DICOM input filename to be converted
27
28bitmap-out  output filename to be written (default: stdout)
29\endverbatim
30
31\section dcmj2pnm_options OPTIONS
32
33\subsection dcmj2pnm_general_options general options
34\verbatim
35  -h    --help
36          print this help text and exit
37
38        --version
39          print version information and exit
40
41        --arguments
42          print expanded command line arguments
43
44  -q    --quiet
45          quiet mode, print no warnings and errors
46
47  -v    --verbose
48          verbose mode, print processing details
49
50  -d    --debug
51          debug mode, print debug information
52
53  -ll   --log-level  [l]evel: string constant
54          (fatal, error, warn, info, debug, trace)
55          use level l for the logger
56
57  -lc   --log-config  [f]ilename: string
58          use config file f for the logger
59\endverbatim
60
61\subsection dcmj2pnm_input_options input options
62\verbatim
63input file format:
64
65  +f    --read-file
66          read file format or data set (default)
67
68  +fo   --read-file-only
69          read file format only
70
71  -f    --read-dataset
72          read data set without file meta information
73
74input transfer syntax:
75
76  -t=   --read-xfer-auto
77          use TS recognition (default)
78
79  -td   --read-xfer-detect
80          ignore TS specified in the file meta header
81
82  -te   --read-xfer-little
83          read with explicit VR little endian TS
84
85  -tb   --read-xfer-big
86          read with explicit VR big endian TS
87
88  -ti   --read-xfer-implicit
89          read with implicit VR little endian TS
90\endverbatim
91
92\subsection dcmj2pnm_image_processing_options image processing options
93\verbatim
94frame selection:
95
96  +F    --frame  [n]umber: integer
97          select specified frame (default: 1)
98
99  +Fr   --frame-range  [n]umber [c]ount: integer
100          select c frames beginning with frame n
101
102  +Fa   --all-frames
103          select all frames
104
105rotation:
106
107  +Rl   --rotate-left
108          rotate image left (-90 degrees)
109
110  +Rr   --rotate-right
111          rotate image right (+90 degrees)
112
113  +Rtd  --rotate-top-down
114          rotate image top-down (180 degrees)
115
116flipping:
117
118  +Lh   --flip-horizontally
119          flip image horizontally
120
121  +Lv   --flip-vertically
122          flip image vertically
123
124  +Lhv  --flip-both-axes
125          flip image horizontally and vertically
126
127scaling:
128
129  +a    --recognize-aspect
130          recognize pixel aspect ratio when scaling (default)
131
132  -a    --ignore-aspect
133          ignore pixel aspect ratio when scaling
134
135  +i    --interpolate  [n]umber of algorithm: integer
136          use interpolation when scaling (1..4, default: 1)
137
138  -i    --no-interpolation
139          no interpolation when scaling
140
141  -S    --no-scaling
142          no scaling, ignore pixel aspect ratio (default)
143
144  +Sxf  --scale-x-factor  [f]actor: float
145          scale x axis by factor, auto-compute y axis
146
147  +Syf  --scale-y-factor  [f]actor: float
148          scale y axis by factor, auto-compute x axis
149
150  +Sxv  --scale-x-size  [n]umber: integer
151          scale x axis to n pixels, auto-compute y axis
152
153  +Syv  --scale-y-size  [n]umber: integer
154          scale y axis to n pixels, auto-compute x axis
155
156color space conversion (JPEG compressed images only):
157
158  +cp   --conv-photometric
159          convert if YCbCr photometric interpretation (default)
160
161  +cl   --conv-lossy
162          convert YCbCr to RGB if lossy JPEG
163
164  +cg   --conv-guess
165          convert to RGB if YCbCr is guessed by library
166
167  +cgl  --conv-guess-lossy
168          convert to RGB if lossy JPEG and YCbCr is
169          guessed by the underlying JPEG library
170
171  +ca   --conv-always
172          always convert YCbCr to RGB
173
174  +cn   --conv-never
175          never convert color space
176
177workaround options for incorrect encodings (JPEG compressed images only):
178
179  +w6   --workaround-pred6
180          enable workaround for JPEG lossless images
181          with overflow in predictor 6
182
183  # DICOM images with 16 bits/pixel have been observed "in the wild"
184  # that are compressed with lossless JPEG and need special handling
185  # because the encoder produced an 16-bit integer overflow in predictor
186  # 6, which needs to be compensated (reproduced) during decompression.
187  # This flag enables a correct decompression of such faulty images, but
188  # at the same time will cause an incorrect decompression of correctly
189  # compressed images. Use with care.
190
191  +wi   --workaround-incpl
192          enable workaround for incomplete JPEG data
193
194  # This option causes dcmj2pnm to ignore incomplete JPEG data
195  # at the end of a compressed fragment and to start decompressing
196  # the next frame from the next fragment (if any). This permits
197  # images with incomplete JPEG data to be decoded.
198
199  +wc   --workaround-cornell
200          enable workaround for 16-bit JPEG lossless
201          Cornell images with Huffman table overflow
202
203  # One of the first open-source implementations of lossless JPEG
204  # compression, the "Cornell" library, has a well-known bug that leads
205  # to invalid values in the Huffmann table when images with 16 bit/sample
206  # are compressed. This flag enables a workaround that permits such
207  # images to be decoded correctly.
208
209modality LUT transformation:
210
211  -M    --no-modality
212          ignore stored modality LUT transformation
213
214  +M    --use-modality
215          use modality LUT transformation (default)
216
217VOI LUT transformation:
218
219  -W    --no-windowing
220          no VOI windowing (default)
221
222  +Wi   --use-window  [n]umber: integer
223          use the n-th VOI window from image file
224
225  +Wl   --use-voi-lut  [n]umber: integer
226          use the n-th VOI look up table from image file
227
228  +Wm   --min-max-window
229          compute VOI window using min-max algorithm
230
231  +Wn   --min-max-window-n
232          compute VOI window using min-max algorithm,
233          ignoring extreme values
234
235  +Wr   --roi-min-max-window  [l]eft [t]op [w]idth [h]eight: integer
236          compute ROI window using min-max algorithm,
237          region of interest is specified by l,t,w,h
238
239  +Wh   --histogram-window  [n]umber: integer
240          compute VOI window using Histogram algorithm,
241          ignoring n percent
242
243  +Ww   --set-window  [c]enter [w]idth: float
244          compute VOI window using center c and width w
245
246  +Wfl  --linear-function
247          set VOI LUT function to LINEAR
248
249  +Wfs  --sigmoid-function
250          set VOI LUT function to SIGMOID
251
252presentation LUT transformation:
253
254  +Pid  --identity-shape
255          set presentation LUT shape to IDENTITY
256
257  +Piv  --inverse-shape
258          set presentation LUT shape to INVERSE
259
260  +Pod  --lin-od-shape
261          set presentation LUT shape to LIN OD
262
263overlay:
264
265  -O    --no-overlays
266          do not display overlays
267
268  +O    --display-overlay  [n]umber: integer
269          display overlay n (0..16, 0=all, default: +O 0)
270
271  +Omr  --ovl-replace
272          use overlay mode "Replace"
273          (default for Graphic overlays)
274
275  +Omt  --ovl-threshold
276          use overlay mode "Threshold Replace"
277
278  +Omc  --ovl-complement
279          use overlay mode "Complement"
280
281  +Omv  --ovl-invert
282          use overlay mode "Invert Bitmap"
283
284  +Omi  --ovl-roi
285          use overlay mode "Region of Interest"
286          (default for ROI overlays)
287
288  +Osf  --set-foreground  [d]ensity: float
289          set overlay foreground density (0..1, default: 1)
290
291  +Ost  --set-threshold  [d]ensity: float
292          set overlay threshold density (0..1, default: 0.5)
293
294display LUT transformation:
295
296  +Dm   --monitor-file  [f]ilename: string
297          calibrate output according to monitor characteristics
298          defined in f
299
300  +Dp   --printer-file  [f]ilename: string
301          calibrate output according to printer characteristics
302          defined in f
303
304  +Da   --ambient-light  [a]mbient light: float
305          ambient light value (cd/m^2, default: file f)
306
307  +Di   --illumination  [i]llumination: float
308          illumination value (cd/m^2, default: file f)
309
310  +Dn   --min-density  [m]inimum optical density: float
311          Dmin value (default: off, only with +Dp)
312
313  +Dx   --max-density  [m]aximum optical density: float
314          Dmax value (default: off, only with +Dp)
315
316  +Dg   --gsd-function
317          use GSDF for calibration (default for +Dm/+Dp)
318
319  +Dc   --cielab-function
320          use CIELAB function for calibration
321
322compatibility:
323
324  +Ma   --accept-acr-nema
325          accept ACR-NEMA images without photometric
326          interpretation
327
328  +Mp   --accept-palettes
329          accept incorrect palette attribute tags
330          (0028,111x) and (0028,121x)
331
332  +Mc   --check-lut-depth
333          check 3rd value of the LUT descriptor, compare
334          with expected bit depth based on LUT data
335
336  +Mm   --ignore-mlut-depth
337          ignore 3rd value of the modality LUT descriptor,
338          determine bits per table entry automatically
339
340  +Mv   --ignore-vlut-depth
341          ignore 3rd value of the VOI LUT descriptor,
342          determine bits per table entry automatically
343
344TIFF format:
345
346  +Tl   --compr-lzw
347          LZW compression (default)
348
349  +Tr   --compr-rle
350          RLE compression
351
352  +Tn   --compr-none
353          uncompressed
354
355  +Pd   --predictor-default
356          no LZW predictor (default)
357
358  +Pn   --predictor-none
359          LZW predictor 1 (no prediction)
360
361  +Ph   --predictor-horz
362          LZW predictor 2 (horizontal differencing)
363
364  +Rs   --rows-per-strip  [r]ows: integer (default: 0)
365          rows per strip, default 8K per strip
366
367PNG format:
368
369  +il   --interlace
370          create interlaced file (default)
371
372  -il   --nointerlace
373          create non-interlaced file
374
375  +mf   --meta-file
376          create PNG file meta information (default)
377
378  -mf   --meta-none
379          no PNG file meta information
380
381JPEG format:
382
383  +Jq   --compr-quality  [q]uality: integer (0..100, default: 90)
384          quality value for compression (in percent)
385
386  +Js4  --sample-444
387          4:4:4 sampling (no subsampling)
388
389  +Js2  --sample-422
390          4:2:2 subsampling (horizontal subsampling of
391          chroma components, default)
392
393  +Js1  --sample-411
394          4:1:1 subsampling (horizontal and vertical
395          subsampling of chroma components)
396
397other transformations:
398
399  +G    --grayscale
400          convert color image to grayscale (monochrome)
401
402  +P    --change-polarity
403          change polarity (invert pixel output)
404
405  +C    --clip-region  [l]eft [t]op [w]idth [h]eight: integer
406          clip image region (l, t, w, h)
407\endverbatim
408
409\subsection dcmj2pnm_output_options output options
410\verbatim
411general:
412
413  -im   --image-info
414          print image details (requires verbose mode)
415
416  -o    --no-output
417          do not create any output (useful with -im)
418
419filename generation (only with --frame-range or --all-frames):
420
421  +Fc   --use-frame-counter
422          use 0-based counter for filenames (default)
423
424  +Fn   --use-frame-number
425          use absolute frame number for filenames
426
427image format:
428
429  +op   --write-raw-pnm
430          write 8-bit binary PGM/PPM (default for files)
431
432  +opb  --write-8-bit-pnm
433          write 8-bit ASCII PGM/PPM (default for stdout)
434
435  +opw  --write-16-bit-pnm
436          write 16-bit ASCII PGM/PPM
437
438  +opn  --write-n-bit-pnm  [n]umber: integer
439          write n-bit ASCII PGM/PPM (1..32)
440
441  +ob   --write-bmp
442          write 8-bit (monochrome) or 24-bit (color) BMP
443
444  +obp  --write-8-bit-bmp
445          write 8-bit palette BMP (monochrome only)
446
447  +obt  --write-24-bit-bmp
448          write 24-bit truecolor BMP
449
450  +obr  --write-32-bit-bmp
451          write 32-bit truecolor BMP
452
453  +ot   --write-tiff
454          write 8-bit (monochrome) or 24-bit (color) TIFF
455
456  +on   --write-png
457          write 8-bit (monochrome) or 24-bit (color) PNG
458
459  +on2  --write-16-bit-png
460          write 16-bit (monochrome) or 48-bit (color) PNG
461
462  +oj   --write-jpeg
463          write 8-bit lossy JPEG (baseline)
464\endverbatim
465
466\section dcmj2pnm_notes NOTES
467
468The following preferred interpolation algorithms can be selected using the
469\e --interpolate option:
470
471\li 1 = free scaling algorithm with interpolation from pbmplus toolkit
472\li 2 = free scaling algorithm with interpolation from c't magazine
473\li 3 = magnification algorithm with bilinear interpolation from Eduard Stanescu
474\li 4 = magnification algorithm with bicubic interpolation from Eduard Stanescu
475
476The \e --write-tiff option is only available when DCMTK has been configured
477and compiled with support for the external \b libtiff TIFF library.  The
478availability of the TIFF compression options depends on the \b libtiff
479configuration.  In particular, the patented LZW algorithm may not be
480available.
481
482The \e --write-png option is only available when DCMTK has been configured
483and compiled with support for the external \b libpng PNG library.  Option
484\e --interlace enables progressive image view while loading the PNG file.
485Only a few applications take care of the meta info (TEXT) in a PNG file.
486
487\section dcmj2pnm_transfer_syntaxes TRANSFER SYNTAXES
488
489\b dcmj2pnm supports the following transfer syntaxes for input (\e dcmfile-in):
490
491\verbatim
492LittleEndianImplicitTransferSyntax             1.2.840.10008.1.2
493LittleEndianExplicitTransferSyntax             1.2.840.10008.1.2.1
494DeflatedExplicitVRLittleEndianTransferSyntax   1.2.840.10008.1.2.1.99 (*)
495BigEndianExplicitTransferSyntax                1.2.840.10008.1.2.2
496JPEGProcess1TransferSyntax                     1.2.840.10008.1.2.4.50
497JPEGProcess2_4TransferSyntax                   1.2.840.10008.1.2.4.51
498JPEGProcess6_8TransferSyntax                   1.2.840.10008.1.2.4.53
499JPEGProcess10_12TransferSyntax                 1.2.840.10008.1.2.4.55
500JPEGProcess14TransferSyntax                    1.2.840.10008.1.2.4.57
501JPEGProcess14SV1TransferSyntax                 1.2.840.10008.1.2.4.70
502RLELosslessTransferSyntax                      1.2.840.10008.1.2.5
503\endverbatim
504
505(*) if compiled with zlib support enabled
506
507\section dcmj2pnm_logging LOGGING
508
509The level of logging output of the various command line tools and underlying
510libraries can be specified by the user.  By default, only errors and warnings
511are written to the standard error stream.  Using option \e --verbose also
512informational messages like processing details are reported.  Option
513\e --debug can be used to get more details on the internal activity, e.g. for
514debugging purposes.  Other logging levels can be selected using option
515\e --log-level.  In \e --quiet mode only fatal errors are reported.  In such
516very severe error events, the application will usually terminate.  For more
517details on the different logging levels, see documentation of module "oflog".
518
519In case the logging output should be written to file (optionally with logfile
520rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
521can be used.  This configuration file also allows for directing only certain
522messages to a particular output stream and for filtering certain messages
523based on the module or application where they are generated.  An example
524configuration file is provided in <em>\<etcdir\>/logger.cfg</em>.
525
526\section dcmj2pnm_command_line COMMAND LINE
527
528All command line tools use the following notation for parameters: square
529brackets enclose optional values (0-1), three trailing dots indicate that
530multiple values are allowed (1-n), a combination of both means 0 to n values.
531
532Command line options are distinguished from parameters by a leading '+' or '-'
533sign, respectively.  Usually, order and position of command line options are
534arbitrary (i.e. they can appear anywhere).  However, if options are mutually
535exclusive the rightmost appearance is used.  This behavior conforms to the
536standard evaluation rules of common Unix shells.
537
538In addition, one or more command files can be specified using an '@' sign as a
539prefix to the filename (e.g. <em>\@command.txt</em>).  Such a command argument
540is replaced by the content of the corresponding text file (multiple
541whitespaces are treated as a single separator unless they appear between two
542quotation marks) prior to any further evaluation.  Please note that a command
543file cannot contain another command file.  This simple but effective approach
544allows one to summarize common combinations of options/parameters and avoids
545longish and confusing command lines (an example is provided in file
546<em>\<datadir\>/dumppat.txt</em>).
547
548\section dcmj2pnm_environment ENVIRONMENT
549
550The \b dcmj2pnm utility will attempt to load DICOM data dictionaries specified
551in the \e DCMDICTPATH environment variable.  By default, i.e. if the
552\e DCMDICTPATH environment variable is not set, the file
553<em>\<datadir\>/dicom.dic</em> will be loaded unless the dictionary is built
554into the application (default for Windows).
555
556The default behavior should be preferred and the \e DCMDICTPATH environment
557variable only used when alternative data dictionaries are required.  The
558\e DCMDICTPATH environment variable has the same format as the Unix shell
559\e PATH variable in that a colon (":") separates entries.  On Windows systems,
560a semicolon (";") is used as a separator.  The data dictionary code will
561attempt to load each file specified in the \e DCMDICTPATH environment variable.
562It is an error if no data dictionary can be loaded.
563
564\section dcmj2pnm_files FILES
565
566<em>\<datadir\>/camera.lut</em> - sample characteristics file of a camera
567\n<em>\<datadir\>/monitor.lut</em> - sample characteristics file of a monitor
568\n<em>\<datadir\>/printer.lut</em> - sample characteristics file of a printer
569\n<em>\<datadir\>/scanner.lut</em> - sample characteristics file of a scanner
570
571\section dcmj2pnm_see_also SEE ALSO
572
573<b>dcm2pnm</b>(1), <b>img2dcm</b>(1)
574
575\section dcmj2pnm_copyright COPYRIGHT
576
577Copyright (C) 2001-2020 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.
578
579*/
580