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

NAME

6       dcml2pnm - Convert DICOM images to PGM/PPM, PNG, TIFF or BMP
7
8

SYNOPSIS

10       dcml2pnm [options] dcmfile-in [bitmap-out]
11

DESCRIPTION

13       The  dcml2pnm  utility  reads  a  DICOM  image, converts the pixel data
14       according to the selected image processing options and writes  back  an
15       image in the well-known PGM/PPM (portable gray map / portable pix map),
16       PNG, TIFF or Windows BMP format. This utility supports uncompressed  as
17       well as JPEG-LS and RLE compressed DICOM images.
18

PARAMETERS

20       dcmfile-in  DICOM input filename to be converted
21
22       bitmap-out  output filename to be written (default: stdout)
23

OPTIONS

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

NOTES

379       The  following preferred interpolation algorithms can be selected using
380       the --interpolate option:
381
382       • 1 = free scaling algorithm with interpolation from pbmplus toolkit
383       • 2 = free scaling algorithm with interpolation from c't magazine
384       • 3 = magnification algorithm with bilinear interpolation  from  Eduard
385         Stanescu
386       • 4  =  magnification  algorithm with bicubic interpolation from Eduard
387         Stanescu
388       The  --write-tiff  option  is  only  available  when  DCMTK  has   been
389       configured  and  compiled  with  support  for the external libtiff TIFF
390       library. The availability of the TIFF compression  options  depends  on
391       the libtiff configuration.
392       The --write-png option is only available when DCMTK has been configured
393       and compiled with support for the external libpng PNG  library.  Option
394       --interlace  enables progressive image view while loading the PNG file.
395       Only a few applications take care of the meta  info  (TEXT)  in  a  PNG
396       file.

TRANSFER SYNTAXES

398       dcml2pnm  supports  the following transfer syntaxes for input (dcmfile-
399       in):
400       LittleEndianImplicitTransferSyntax             1.2.840.10008.1.2
401       LittleEndianExplicitTransferSyntax             1.2.840.10008.1.2.1
402       DeflatedExplicitVRLittleEndianTransferSyntax   1.2.840.10008.1.2.1.99 (*)
403       BigEndianExplicitTransferSyntax                1.2.840.10008.1.2.2
404       JPEGLSLosslessTransferSyntax                   1.2.840.10008.1.2.4.80
405       JPEGLSLossyTransferSyntax                      1.2.840.10008.1.2.4.81
406       RLELosslessTransferSyntax                      1.2.840.10008.1.2.5
407       (*) if compiled with zlib support enabled

LOGGING

409       The level of logging output of  the  various  command  line  tools  and
410       underlying  libraries  can  be  specified by the user. By default, only
411       errors and warnings are written to the  standard  error  stream.  Using
412       option  --verbose  also  informational messages like processing details
413       are reported. Option --debug can be used to get  more  details  on  the
414       internal  activity,  e.g.  for debugging purposes. Other logging levels
415       can be selected using option --log-level. In --quiet  mode  only  fatal
416       errors  are reported. In such very severe error events, the application
417       will usually terminate. For  more  details  on  the  different  logging
418       levels, see documentation of module 'oflog'.
419       In  case  the logging output should be written to file (optionally with
420       logfile rotation), to syslog (Unix) or the event log  (Windows)  option
421       --log-config  can  be  used.  This  configuration  file also allows for
422       directing only certain messages to a particular output stream  and  for
423       filtering  certain  messages  based  on the module or application where
424       they are generated.  An  example  configuration  file  is  provided  in
425       <etcdir>/logger.cfg.

COMMAND LINE

427       All  command  line  tools  use  the  following notation for parameters:
428       square brackets enclose optional  values  (0-1),  three  trailing  dots
429       indicate  that multiple values are allowed (1-n), a combination of both
430       means 0 to n values.
431       Command line options are distinguished from parameters by a leading '+'
432       or  '-' sign, respectively. Usually, order and position of command line
433       options are arbitrary (i.e. they  can  appear  anywhere).  However,  if
434       options  are  mutually exclusive the rightmost appearance is used. This
435       behavior conforms to the  standard  evaluation  rules  of  common  Unix
436       shells.
437       In  addition,  one  or more command files can be specified using an '@'
438       sign as a prefix to the filename (e.g. @command.txt).  Such  a  command
439       argument  is  replaced  by  the  content of the corresponding text file
440       (multiple whitespaces are treated as a  single  separator  unless  they
441       appear  between  two  quotation marks) prior to any further evaluation.
442       Please note that a command file cannot contain  another  command  file.
443       This  simple  but  effective  approach  allows  one to summarize common
444       combinations of options/parameters and  avoids  longish  and  confusing
445       command lines (an example is provided in file <datadir>/dumppat.txt).

ENVIRONMENT

447       The  dcml2pnm  utility  will  attempt  to  load DICOM data dictionaries
448       specified in the DCMDICTPATH environment variable. By default, i.e.  if
449       the   DCMDICTPATH   environment   variable   is   not   set,  the  file
450       <datadir>/dicom.dic will be loaded unless the dictionary is built  into
451       the application (default for Windows).
452       The   default   behavior   should  be  preferred  and  the  DCMDICTPATH
453       environment variable only used when alternative data  dictionaries  are
454       required.  The  DCMDICTPATH environment variable has the same format as
455       the Unix shell PATH variable in that a colon (':')  separates  entries.
456       On  Windows systems, a semicolon (';') is used as a separator. The data
457       dictionary code will  attempt  to  load  each  file  specified  in  the
458       DCMDICTPATH  environment variable. It is an error if no data dictionary
459       can be loaded.

FILES

461       <datadir>/camera.lut - sample characteristics file of a camera
462       <datadir>/monitor.lut - sample characteristics file of a monitor
463       <datadir>/printer.lut - sample characteristics file of a printer
464       <datadir>/scanner.lut - sample characteristics file of a scanner

SEE ALSO

466       dcm2pnm(1), img2dcm(1)
468       Copyright (C) 2001-2022 by OFFIS e.V., Escherweg  2,  26121  Oldenburg,
469       Germany.
470
471
472
473Version 3.6.7                   Fri Apr 22 2022                    dcml2pnm(1)
Impressum