OFFIS DCMTK  Version 3.6.0
dcmcjpeg.man
1 /*!
2 
3 \if MANPAGES
4 \page dcmcjpeg Encode DICOM file to JPEG transfer syntax
5 \else
6 \page dcmcjpeg dcmcjpeg: Encode DICOM file to JPEG transfer syntax
7 \endif
8 
9 \section synopsis SYNOPSIS
10 
11 \verbatim
12 dcmcjpeg [options] dcmfile-in dcmfile-out
13 \endverbatim
14 
15 \section description DESCRIPTION
16 
17 The \b dcmcjpeg utility reads an uncompressed DICOM image (\e dcmfile-in),
18 performs a JPEG compression (i. e. conversion to an encapsulated DICOM transfer
19 syntax) and writes the converted image to an output file (\e dcmfile-out).
20 
21 \section parameters PARAMETERS
22 
23 \verbatim
24 dcmfile-in DICOM input filename to be converted
25 
26 dcmfile-out DICOM output filename
27 \endverbatim
28 
29 \section options OPTIONS
30 
31 \subsection general_options general options
32 \verbatim
33  -h --help
34  print this help text and exit
35 
36  --version
37  print version information and exit
38 
39  --arguments
40  print expanded command line arguments
41 
42  -q --quiet
43  quiet mode, print no warnings and errors
44 
45  -v --verbose
46  verbose mode, print processing details
47 
48  -d --debug
49  debug mode, print debug information
50 
51  -ll --log-level [l]evel: string constant
52  (fatal, error, warn, info, debug, trace)
53  use level l for the logger
54 
55  -lc --log-config [f]ilename: string
56  use config file f for the logger
57 \endverbatim
58 
59 \subsection input_options input options
60 \verbatim
61 input file format:
62 
63  +f --read-file
64  read file format or data set (default)
65 
66  +fo --read-file-only
67  read file format only
68 
69  -f --read-dataset
70  read data set without file meta information
71 
72 input transfer syntax:
73 
74  -t= --read-xfer-auto
75  use TS recognition (default)
76 
77  -td --read-xfer-detect
78  ignore TS specified in the file meta header
79 
80  -te --read-xfer-little
81  read with explicit VR little endian TS
82 
83  -tb --read-xfer-big
84  read with explicit VR big endian TS
85 
86  -ti --read-xfer-implicit
87  read with implicit VR little endian TS
88 
89 compatibility (ignored by +tl):
90 
91  +Ma --accept-acr-nema
92  accept ACR-NEMA images without photometric interpretation
93 
94  # Enables compatibility for old ACR-NEMA images without photometric
95  # information (only pseudo lossless encoder)
96 
97  +Mp --accept-palettes
98  accept incorrect palette attribute tags (0028,111x) and
99  (0028,121x)
100 
101  # If enabled, incorrect palette attribute tags are accepted
102  # (only pseudo lossless encoder)
103 \endverbatim
104 
105 \subsection JPEG_encoding_options JPEG encoding options
106 \verbatim
107 JPEG process:
108 
109  +e1 --encode-lossless-sv1
110  encode lossless sv1 (default)
111 
112  # This option selects the JPEG Lossless, Non-Hierarchical, First-Order
113  # Prediction (Process 14 Selection Value 1) Transfer Syntax for
114  # Lossless JPEG Image Compression.
115 
116  +el --encode-lossless
117  encode lossless
118 
119  # This option selects the JPEG Lossless, Non-Hierarchical (Process 14)
120  # Transfer Syntax for Lossless JPEG Image Compression.
121 
122  +eb --encode-baseline
123  encode baseline
124 
125  # This option selects the JPEG Baseline (Process 1) Transfer Syntax
126  # for Lossy JPEG 8 Bit Image Compression.
127 
128  +ee --encode-extended
129  encode extended sequential
130 
131  # This option selects the JPEG Extended (Process 2 & 4) Transfer
132  # Syntax for Lossy JPEG Image Compression.
133 
134  +es --encode-spectral
135  encode spectral selection
136 
137  # This option selects the JPEG Spectral Selection, Non-Hierarchical
138  # (Process 6 & 8) Transfer Syntax for Lossy JPEG Image Compression.
139 
140  +ep --encode-progressive
141  encode progressive
142 
143  # This option selects the JPEG Full Progression, Non-Hierarchical
144  # (Process 10 & 12) Transfer Syntax for Lossy JPEG Image Compression.
145 
146 lossless JPEG codec selection:
147 
148  +tl --true-lossless
149  true lossless codec (default)
150 
151  # This option selects an encoder, that guarantees truely lossless
152  # image compression. See NOTES for further information.
153 
154  +pl --pseudo-lossless
155  old pseudo-lossless codec
156 
157  # Old encoder, that uses lossless compression algorithms, but can
158  # cause lossy images because of internal color space transformations
159  # etc. Higher compression ratio than --true-lossless in most cases.
160 
161 lossless JPEG representation:
162 
163  +sv --selection-value [sv]: integer (1..7, default: 6)
164  use selection value sv only with --encode-lossless
165 
166  # This option selects the selection value for lossless JPEG.
167 
168  +pt --point-transform [pt]: integer (0..15, default: 0)
169  use point transform pt
170 
171  # This option selects the point transform for lossless JPEG.
172  # WARNING: Using this option with a value other than zero causes
173  # a loss of precision, i. e. makes the compression "lossy".
174 
175 lossy JPEG representation:
176 
177  +q --quality [q]: integer (0..100, default: 90)
178  use quality factor q
179 
180  # This option selects the quality factor used to determine the
181  # quantization table inside the JPEG compressor, which affects
182  # compression ratio and image quality in lossy JPEG.
183  # See documentation of the Independent JPEG Group for details.
184 
185  +sm --smooth [s]: integer (0..100, default: 0)
186  use smoothing factor s
187 
188  # This option enables a smoothing (low-pass filter) of the image data
189  # prior to compression. Increases the compression ratio at the expense
190  # of image quality.
191 
192 other JPEG options:
193 
194  +ho --huffman-optimize
195  optimize huffman tables (default)
196 
197  # This option enables an optimization of the huffman tables during
198  # image compression. It results in a slightly smaller image at a small
199  # increase of CPU time. Always on if bits/sample is larger than 8.
200 
201  -ho --huffman-standard
202  use standard huffman tables if 8 bits/sample
203 
204  # This option disables an optimization of the huffman tables during
205  # image compression.
206 
207 compressed bits per sample (always +ba with +tl):
208 
209  +ba --bits-auto
210  choose bits/sample automatically (default)
211 
212  +be --bits-force-8
213  force 8 bits/sample
214 
215  +bt --bits-force-12
216  force 12 bits/sample (not with baseline)
217 
218  +bs --bits-force-16
219  force 16 bits/sample (lossless only)
220 
221 compression color space conversion (overriden by +tl):
222 
223  +cy --color-ybr
224  use YCbCr for color images if lossy (default)
225 
226  # This option enables a transformation of the color space to YCbCr
227  # prior to image compression for color images in lossy JPEG.
228 
229  +cr --color-rgb
230  use RGB for color images if lossy
231 
232  # This option prevents the transformation of the color space to YCbCr
233  # prior to image compression for color images in lossy JPEG. It causes
234  # lossy image compression in the RGB color space which is not
235  # recommendable.
236 
237  +cm --monochrome
238  convert color images to monochrome
239 
240  # This option forces a conversion of color images to monochrome
241  # prior to compression.
242 
243 decompression color space conversion
244 (if input is compressed; always +cn with +tl):
245 
246  +cp --conv-photometric
247  convert if YCbCr photometric interpretation (default)
248 
249  # This option describes the behavior of dcmcjpeg when a compressed
250  # image is read and decompressed prior to re-compression. If the
251  # compressed image uses YBR_FULL or YBR_FULL_422 photometric
252  # interpretation, it is converted to RGB during decompression.
253 
254  +cl --conv-lossy
255  convert YCbCr to RGB if lossy JPEG
256 
257  # If the compressed image is encoded in lossy JPEG, assume YCbCr
258  # color model and convert to RGB.
259 
260  +cg --conv-guess
261  convert to RGB if YCbCr is guessed by library
262 
263  # If the underlying JPEG library "guesses" the color space of the
264  # compressed image to be YCbCr, convert to RGB.
265 
266  +cgl --conv-guess-lossy
267  convert to RGB if lossy JPEG and YCbCr is
268  guessed by the underlying JPEG library
269 
270  # If the compressed image is encoded in lossy JPEG and the underlying
271  # JPEG library "guesses" the color space to be YCbCr, convert to RGB.
272 
273  +ca --conv-always
274  always convert YCbCr to RGB
275 
276  # If the compressed image is a color image, assume YCbCr color model
277  # and convert to RGB.
278 
279  +cn --conv-never
280  never convert color space
281 
282  # Never convert color space during decompression.
283 
284 standard YCbCr component subsampling (not with +tl):
285 
286  +s4 --sample-444
287  4:4:4 sampling with YBR_FULL (default)
288 
289  # This option disables color component subsampling for compression in
290  # the YCbCr color space. The DICOM photometric interpretation is
291  # encoded as YBR_FULL.
292 
293  +s2 --sample-422
294  4:2:2 subsampling with YBR_FULL_422
295 
296  # This option enables a 4:2:2 color component subsampling for
297  # compression in the YCbCr color space. The DICOM photometric
298  # interpretation is encoded as YBR_FULL.
299 
300 non-standard YCbCr component subsampling (not with +tl):
301 
302  +n2 --nonstd-422-full
303  4:2:2 subsampling with YBR_FULL
304 
305  # This option enables a 4:2:2 color component subsampling for
306  # compression in the YCbCr color space. The DICOM photometric
307  # interpretation is encoded as YBR_FULL which violates DICOM rules.
308 
309  +n1 --nonstd-411-full
310  4:1:1 subsampling with YBR_FULL
311 
312  # This option enables a 4:1:1 color component subsampling for
313  # compression in the YCbCr color space. The DICOM photometric
314  # interpretation is encoded as YBR_FULL which violates DICOM rules.
315 
316  +np --nonstd-411
317  4:1:1 subsampling with YBR_FULL_422
318 
319  # This option enables a 4:1:1 color component subsampling for
320  # compression in the YCbCr color space. The DICOM photometric
321  # interpretation is encoded as YBR_FULL_422 which violates DICOM rules.
322 \endverbatim
323 
324 \subsection enc_pix_data_encoding_opt encapsulated pixel data encoding options:
325 \verbatim
326 encapsulated pixel data fragmentation:
327 
328  +ff --fragment-per-frame
329  encode each frame as one fragment (default)
330 
331  # This option causes the creation of one compressed fragment for each
332  # frame (recommended).
333 
334  +fs --fragment-size [s]ize: integer
335  limit fragment size to s kbytes
336 
337  # This option limits the fragment size which may cause the creation of
338  # multiple fragments per frame.
339 
340 basic offset table encoding:
341 
342  +ot --offset-table-create
343  create offset table (default)
344 
345  # This option causes the creation of a valid offset table for the
346  # compressed JPEG fragments.
347 
348  -ot --offset-table-empty
349  leave offset table empty
350 
351  # This option causes the creation of an empty offset table
352  # for the compressed JPEG fragments.
353 
354 VOI windowing for monochrome images (not with +tl):
355 
356  -W --no-windowing
357  no VOI windowing (default)
358 
359  # No window level/width is "burned" into monochrome images prior to
360  # compression. See notes below on pixel scaling and rescale slope
361  # and intercept encoding.
362 
363  +Wi --use-window [n]umber: integer
364  use the n-th VOI window from image file
365 
366  # Apply the n-th window center/width encoded in the image data prior
367  # to compression.
368 
369  +Wl --use-voi-lut [n]umber: integer
370  use the n-th VOI look up table from image file
371 
372  # Apply the n-th VOI LUT encoded in the image data prior
373  # to compression.
374 
375  +Wm --min-max-window
376  compute VOI window using min-max algorithm
377 
378  # Compute and apply a window center and width that covers the
379  # range from the smallest to the largest occuring pixel value.
380 
381  +Wn --min-max-window-n
382  compute VOI window using min-max algorithm,
383  ignoring extreme values
384 
385  # Compute and apply a window center and width that covers the
386  # range from the second smallest to the second largest occuring
387  # pixel value. This is useful if the background is set to an
388  # artificial black (padding value) or if white overlays are burned
389  # into the image data which should not be considered for the window
390  # computation.
391 
392  +Wr --roi-min-max-window [l]eft [t]op [w]idth [h]eight: integer
393  compute ROI window using min-max algorithm,
394  region of interest is specified by l,t,w,h
395 
396  # This option works like --min-max-window but only considers the given
397  # region of interest inside the image.
398 
399  +Wh --histogram-window [n]umber: integer
400  compute VOI window using Histogram algorithm,
401  ignoring n percent
402 
403  # Compute a histogram of the image data and apply window center
404  # and width such than n% of the image data are ignored for the window
405  # computation
406 
407  +Ww --set-window [c]enter [w]idth: float
408  compute VOI window using center c and width w
409 
410  # Apply the given window center/width prior to compression.
411 
412 pixel scaling for monochrome images (--no-windowing; ignored by +tl):
413 
414  +sp --scaling-pixel
415  scale using min/max pixel value (default)
416 
417  # Monochrome image pixel values are always scaled to make use of the
418  # pixel range available with the selected JPEG process as good as
419  # possible. This option selects a scaling based on the minimum and
420  # maximum pixel value occuring in the image. This often leads to
421  # significantly better image quality, but may cause different
422  # compressed images within one series to have different values for
423  # rescale slope and intercept, which is a problem if a presentation
424  # state for one series is to be created.
425 
426  +sr --scaling-range
427  scale using min/max range
428 
429  # This options selects a scaling based on the pixel range as defined
430  # by the stored bits, pixel representation and modality transform,
431  # without consideration of the minimum and maximum value really
432  # used within the image.
433 
434 rescale slope/intercept encoding for monochrome (-W; ignored by +tl):
435 
436  +ri --rescale-identity
437  encode identity modality rescale (default)
438  Never used for CT images
439 
440  # This options prevents the creation of a modality transformation
441  # other than an identity transformation (which is required for
442  # many DICOM IODs). Window center/width settings encoded
443  # in the image are adapted, VOI LUTs are removed.
444 
445  +rm --rescale-map
446  use modality rescale to scale pixel range
447  Never used for XA/RF/XA Biplane images
448 
449  # This option causes the creation of a modality rescale slope and
450  # intercept that maps the decompressed image data back to their
451  # original range. This keeps all VOI transformations valid but
452  # requires that the DICOM IOD supports a modality rescale slope
453  # and intercept transformation other than identity.
454 
455 SOP Class UID:
456 
457  +cd --class-default
458  keep SOP Class UID (default)
459 
460  # Keep the SOP Class UID of the source image.
461 
462  +cs --class-sc
463  convert to Secondary Capture Image (implies --uid-always)
464 
465  # Convert the image to Secondary Capture. In addition to the SOP
466  # Class UID, all attributes required for a valid secondary capture
467  # image are added. A new SOP instance UID is always assigned.
468 
469 SOP Instance UID:
470 
471  +ud --uid-default
472  assign new UID if lossy compression (default)
473 
474  # Assigns a new SOP instance UID if the compression is lossy.
475 
476  +ua --uid-always
477  always assign new UID
478 
479  # Unconditionally assigns a new SOP instance UID.
480 
481  +un --uid-never
482  never assign new UID
483 
484  # Never assigns a new SOP instance UID.
485 \endverbatim
486 
487 \subsection output_options output options
488 \verbatim
489 post-1993 value representations:
490 
491  +u --enable-new-vr
492  enable support for new VRs (UN/UT) (default)
493 
494  -u --disable-new-vr
495  disable support for new VRs, convert to OB
496 
497 group length encoding:
498 
499  +g= --group-length-recalc
500  recalculate group lengths if present (default)
501 
502  +g --group-length-create
503  always write with group length elements
504 
505  -g --group-length-remove
506  always write without group length elements
507 
508 length encoding in sequences and items:
509 
510  +e --length-explicit
511  write with explicit lengths (default)
512 
513  -e --length-undefined
514  write with undefined lengths
515 
516 data set trailing padding:
517 
518  -p= --padding-retain
519  do not change padding (default)
520 
521  -p --padding-off
522  no padding
523 
524  +p --padding-create [f]ile-pad [i]tem-pad: integer
525  align file on multiple of f bytes
526  and items on multiple of i bytes
527 \endverbatim
528 
529 \section notes NOTES
530 
531 The \b dcmcjpeg utility compresses DICOM images of all SOP classes. Special
532 handling has been implemented for CT images (where the modality transformation
533 is required to create Hounsfield units) and the XA/RF/Biplane SOP classes
534 (where the modality transformation has "inversed" semantics). However,
535 \b dcmcjpeg does not attempt to ensure that the compressed image still complies
536 with all restrictions of the object's IOD.
537 
538 A few examples:
539 
540 \li MR images are required to have BitsAllocated=16.
541 \li NM Images can only be encoded with MONOCHROME2 or PALETTE COLOR photometric
542  interpretation but not with RGB or YBR_FULL (which effectively prevents
543  compression).
544 \li Hardcopy Color images must have RGB color model which is a problem if lossy
545  compression is to be performed.
546 
547 The user is responsible for making sure that the compressed images he creates
548 are compliant with the DICOM standard. If in question, the \b dcmcjpeg utility
549 allows to convert an image to secondary capture - this SOP class does not pose
550 restrictions as the ones mentioned above.
551 
552 With version DCMTK 3.5.4 a new encoder for truely lossless JPEG compression was
553 added (\e --true-lossless). Compared to the old (\e --pseudo-lossless) encoder,
554 that creates slightly lossy images caused from internal color space conversions,
555 windowing etc., there are a some issues to consider:
556 
557 \li Only source images with Bits Allocated 8 or 16 are supported
558 \li Options for color space conversions, windowing or pixel scaling are
559  ignored or overriden
560 \li Photometric Interpretations YBR_FULL_422, YBR_PARTIAL_422, YBR_PARTIAL_420,
561  YBR_ICT, YBR_RCT are not supported
562 \li The encoder changes automatically Planar Configuration from 1 to 0 if
563  necessary
564 \li The compression ratio can be lower than in \e --pseudo-lossless mode
565 
566 However, when using the new encoder (default), you can be sure, that
567 compression does not affect image quality.
568 
569 In order to be on the safe side, the Lossy Compression Flag is always set to
570 "01" and a new SOP instance UID is assigned (by default) for the old
571 pseudo-lossless encoder. The output of the old and new lossless encoder can
572 also be distinguished by the Derivation Description in the resulting DICOM
573 image, which contains the term "Lossless JPEG compression" for the new and
574 "Pseudo-Lossless JPEG compression" for the old encoder.
575 
576 \section transfer_syntaxes TRANSFER SYNTAXES
577 
578 \b dcmcjpeg supports the following transfer syntaxes for input
579 (\e dcmfile-in):
580 
581 \verbatim
582 LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2
583 LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1
584 DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*)
585 BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2
586 JPEGProcess1TransferSyntax 1.2.840.10008.1.2.4.50
587 JPEGProcess2_4TransferSyntax 1.2.840.10008.1.2.4.51
588 JPEGProcess6_8TransferSyntax 1.2.840.10008.1.2.4.53
589 JPEGProcess10_12TransferSyntax 1.2.840.10008.1.2.4.55
590 JPEGProcess14TransferSyntax 1.2.840.10008.1.2.4.57
591 JPEGProcess14SV1TransferSyntax 1.2.840.10008.1.2.4.70
592 \endverbatim
593 
594 (*) if compiled with zlib support enabled
595 
596 \b dcmcjpeg supports the following transfer syntaxes for output
597 (\e dcmfile-out):
598 
599 \verbatim
600 JPEGProcess1TransferSyntax 1.2.840.10008.1.2.4.50
601 JPEGProcess2_4TransferSyntax 1.2.840.10008.1.2.4.51
602 JPEGProcess6_8TransferSyntax 1.2.840.10008.1.2.4.53
603 JPEGProcess10_12TransferSyntax 1.2.840.10008.1.2.4.55
604 JPEGProcess14TransferSyntax 1.2.840.10008.1.2.4.57
605 JPEGProcess14SV1TransferSyntax 1.2.840.10008.1.2.4.70
606 \endverbatim
607 
608 \section logging LOGGING
609 
610 The level of logging output of the various command line tools and underlying
611 libraries can be specified by the user. By default, only errors and warnings
612 are written to the standard error stream. Using option \e --verbose also
613 informational messages like processing details are reported. Option
614 \e --debug can be used to get more details on the internal activity, e.g. for
615 debugging purposes. Other logging levels can be selected using option
616 \e --log-level. In \e --quiet mode only fatal errors are reported. In such
617 very severe error events, the application will usually terminate. For more
618 details on the different logging levels, see documentation of module "oflog".
619 
620 In case the logging output should be written to file (optionally with logfile
621 rotation), to syslog (Unix) or the event log (Windows) option \e --log-config
622 can be used. This configuration file also allows for directing only certain
623 messages to a particular output stream and for filtering certain messages
624 based on the module or application where they are generated. An example
625 configuration file is provided in <em><etcdir>/logger.cfg</em>).
626 
627 \section command_line COMMAND LINE
628 
629 All command line tools use the following notation for parameters: square
630 brackets enclose optional values (0-1), three trailing dots indicate that
631 multiple values are allowed (1-n), a combination of both means 0 to n values.
632 
633 Command line options are distinguished from parameters by a leading '+' or '-'
634 sign, respectively. Usually, order and position of command line options are
635 arbitrary (i.e. they can appear anywhere). However, if options are mutually
636 exclusive the rightmost appearance is used. This behaviour conforms to the
637 standard evaluation rules of common Unix shells.
638 
639 In addition, one or more command files can be specified using an '@' sign as a
640 prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument
641 is replaced by the content of the corresponding text file (multiple
642 whitespaces are treated as a single separator unless they appear between two
643 quotation marks) prior to any further evaluation. Please note that a command
644 file cannot contain another command file. This simple but effective approach
645 allows to summarize common combinations of options/parameters and avoids
646 longish and confusing command lines (an example is provided in file
647 <em><datadir>/dumppat.txt</em>).
648 
649 \section environment ENVIRONMENT
650 
651 The \b dcmcjpeg utility will attempt to load DICOM data dictionaries specified
652 in the \e DCMDICTPATH environment variable. By default, i.e. if the
653 \e DCMDICTPATH environment variable is not set, the file
654 <em><datadir>/dicom.dic</em> will be loaded unless the dictionary is built
655 into the application (default for Windows).
656 
657 The default behaviour should be preferred and the \e DCMDICTPATH environment
658 variable only used when alternative data dictionaries are required. The
659 \e DCMDICTPATH environment variable has the same format as the Unix shell
660 \e PATH variable in that a colon (":") separates entries. On Windows systems,
661 a semicolon (";") is used as a separator. The data dictionary code will
662 attempt to load each file specified in the \e DCMDICTPATH environment variable.
663 It is an error if no data dictionary can be loaded.
664 
665 \section see_also SEE ALSO
666 
667 <b>dcmdjpeg</b>(1)
668 
669 \section copyright COPYRIGHT
670 
671 Copyright (C) 2001-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.
672 
673 */


Generated on Wed Dec 28 2016 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.8.8