4 \page dcmcjpeg Encode DICOM file to JPEG transfer syntax
6 \page dcmcjpeg dcmcjpeg: Encode DICOM file to JPEG transfer syntax
9 \section synopsis SYNOPSIS
12 dcmcjpeg [options] dcmfile-in dcmfile-out
15 \section description DESCRIPTION
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).
21 \section parameters PARAMETERS
24 dcmfile-in DICOM input filename to be converted
26 dcmfile-out DICOM output filename
29 \section options OPTIONS
31 \subsection general_options general options
34 print this help text and exit
37 print version information and exit
40 print expanded command line arguments
43 quiet mode, print no warnings and errors
46 verbose mode, print processing details
49 debug mode, print debug information
51 -ll --log-level [l]evel: string constant
52 (fatal, error, warn, info, debug, trace)
53 use level l for the logger
55 -lc --log-config [f]ilename: string
56 use config file f for the logger
59 \subsection input_options input options
64 read file format or data set (default)
70 read data set without file meta information
72 input transfer syntax:
75 use TS recognition (default)
77 -td --read-xfer-detect
78 ignore TS specified in the file meta header
80 -te --read-xfer-little
81 read with explicit VR little endian TS
84 read with explicit VR big endian TS
86 -ti --read-xfer-implicit
87 read with implicit VR little endian TS
89 compatibility (ignored by +tl):
92 accept ACR-NEMA images without photometric interpretation
94 # Enables compatibility for old ACR-NEMA images without photometric
95 # information (only pseudo lossless encoder)
98 accept incorrect palette attribute tags (0028,111x) and
101 # If enabled, incorrect palette attribute tags are accepted
102 # (only pseudo lossless encoder)
105 \subsection JPEG_encoding_options JPEG encoding options
109 +e1 --encode-lossless-sv1
110 encode lossless sv1 (default)
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.
116 +el --encode-lossless
119 # This option selects the JPEG Lossless, Non-Hierarchical (Process 14)
120 # Transfer Syntax for Lossless JPEG Image Compression.
122 +eb --encode-baseline
125 # This option selects the JPEG Baseline (Process 1) Transfer Syntax
126 # for Lossy JPEG 8 Bit Image Compression.
128 +ee --encode-extended
129 encode extended sequential
131 # This option selects the JPEG Extended (Process 2 & 4) Transfer
132 # Syntax for Lossy JPEG Image Compression.
134 +es --encode-spectral
135 encode spectral selection
137 # This option selects the JPEG Spectral Selection, Non-Hierarchical
138 # (Process 6 & 8) Transfer Syntax for Lossy JPEG Image Compression.
140 +ep --encode-progressive
143 # This option selects the JPEG Full Progression, Non-Hierarchical
144 # (Process 10 & 12) Transfer Syntax for Lossy JPEG Image Compression.
146 lossless JPEG codec selection:
149 true lossless codec (default)
151 # This option selects an encoder, that guarantees truely lossless
152 # image compression. See NOTES for further information.
154 +pl --pseudo-lossless
155 old pseudo-lossless codec
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.
161 lossless JPEG representation:
163 +sv --selection-value [sv]: integer (1..7, default: 6)
164 use selection value sv only with --encode-lossless
166 # This option selects the selection value for lossless JPEG.
168 +pt --point-transform [pt]: integer (0..15, default: 0)
169 use point transform pt
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".
175 lossy JPEG representation:
177 +q --quality [q]: integer (0..100, default: 90)
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.
185 +sm --smooth [s]: integer (0..100, default: 0)
186 use smoothing factor s
188 # This option enables a smoothing (low-pass filter) of the image data
189 # prior to compression. Increases the compression ratio at the expense
194 +ho --huffman-optimize
195 optimize huffman tables (default)
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.
201 -ho --huffman-standard
202 use standard huffman tables if 8 bits/sample
204 # This option disables an optimization of the huffman tables during
207 compressed bits per sample (always +ba with +tl):
210 choose bits/sample automatically (default)
216 force 12 bits/sample (not with baseline)
219 force 16 bits/sample (lossless only)
221 compression color space conversion (overriden by +tl):
224 use YCbCr for color images if lossy (default)
226 # This option enables a transformation of the color space to YCbCr
227 # prior to image compression for color images in lossy JPEG.
230 use RGB for color images if lossy
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
238 convert color images to monochrome
240 # This option forces a conversion of color images to monochrome
241 # prior to compression.
243 decompression color space conversion
244 (if input is compressed; always +cn with +tl):
246 +cp --conv-photometric
247 convert if YCbCr photometric interpretation (default)
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.
255 convert YCbCr to RGB if lossy JPEG
257 # If the compressed image is encoded in lossy JPEG, assume YCbCr
258 # color model and convert to RGB.
261 convert to RGB if YCbCr is guessed by library
263 # If the underlying JPEG library "guesses" the color space of the
264 # compressed image to be YCbCr, convert to RGB.
266 +cgl --conv-guess-lossy
267 convert to RGB if lossy JPEG and YCbCr is
268 guessed by the underlying JPEG library
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.
274 always convert YCbCr to RGB
276 # If the compressed image is a color image, assume YCbCr color model
277 # and convert to RGB.
280 never convert color space
282 # Never convert color space during decompression.
284 standard YCbCr component subsampling (not with +tl):
287 4:4:4 sampling with YBR_FULL (default)
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.
294 4:2:2 subsampling with YBR_FULL_422
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.
300 non-standard YCbCr component subsampling (not with +tl):
302 +n2 --nonstd-422-full
303 4:2:2 subsampling with YBR_FULL
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.
309 +n1 --nonstd-411-full
310 4:1:1 subsampling with YBR_FULL
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.
317 4:1:1 subsampling with YBR_FULL_422
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.
324 \subsection enc_pix_data_encoding_opt encapsulated pixel data encoding options:
326 encapsulated pixel data fragmentation:
328 +ff --fragment-per-frame
329 encode each frame as one fragment (default)
331 # This option causes the creation of one compressed fragment for each
332 # frame (recommended).
334 +fs --fragment-size [s]ize: integer
335 limit fragment size to s kbytes
337 # This option limits the fragment size which may cause the creation of
338 # multiple fragments per frame.
340 basic offset table encoding:
342 +ot --offset-table-create
343 create offset table (default)
345 # This option causes the creation of a valid offset table for the
346 # compressed JPEG fragments.
348 -ot --offset-table-empty
349 leave offset table empty
351 # This option causes the creation of an empty offset table
352 # for the compressed JPEG fragments.
354 VOI windowing for monochrome images (not with +tl):
357 no VOI windowing (default)
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.
363 +Wi --use-window [n]umber: integer
364 use the n-th VOI window from image file
366 # Apply the n-th window center/width encoded in the image data prior
369 +Wl --use-voi-lut [n]umber: integer
370 use the n-th VOI look up table from image file
372 # Apply the n-th VOI LUT encoded in the image data prior
376 compute VOI window using min-max algorithm
378 # Compute and apply a window center and width that covers the
379 # range from the smallest to the largest occuring pixel value.
381 +Wn --min-max-window-n
382 compute VOI window using min-max algorithm,
383 ignoring extreme values
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
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
396 # This option works like --min-max-window but only considers the given
397 # region of interest inside the image.
399 +Wh --histogram-window [n]umber: integer
400 compute VOI window using Histogram algorithm,
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
407 +Ww --set-window [c]enter [w]idth: float
408 compute VOI window using center c and width w
410 # Apply the given window center/width prior to compression.
412 pixel scaling for monochrome images (--no-windowing; ignored by +tl):
415 scale using min/max pixel value (default)
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.
427 scale using min/max range
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.
434 rescale slope/intercept encoding for monochrome (-W; ignored by +tl):
436 +ri --rescale-identity
437 encode identity modality rescale (default)
438 Never used for CT images
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.
446 use modality rescale to scale pixel range
447 Never used for XA/RF/XA Biplane images
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.
458 keep SOP Class UID (default)
460 # Keep the SOP Class UID of the source image.
463 convert to Secondary Capture Image (implies --uid-always)
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.
472 assign new UID if lossy compression (default)
474 # Assigns a new SOP instance UID if the compression is lossy.
477 always assign new UID
479 # Unconditionally assigns a new SOP instance UID.
484 # Never assigns a new SOP instance UID.
487 \subsection output_options output options
489 post-1993 value representations:
492 enable support for new VRs (UN/UT) (default)
495 disable support for new VRs, convert to OB
497 group length encoding:
499 +g= --group-length-recalc
500 recalculate group lengths if present (default)
502 +g --group-length-create
503 always write with group length elements
505 -g --group-length-remove
506 always write without group length elements
508 length encoding in sequences and items:
511 write with explicit lengths (default)
513 -e --length-undefined
514 write with undefined lengths
516 data set trailing padding:
519 do not change padding (default)
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
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.
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
544 \li Hardcopy Color images must have RGB color model which is a problem if lossy
545 compression is to be performed.
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.
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:
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
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
564 \li The compression ratio can be lower than in \e --pseudo-lossless mode
566 However, when using the new encoder (default), you can be sure, that
567 compression does not affect image quality.
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.
576 \section transfer_syntaxes TRANSFER SYNTAXES
578 \b dcmcjpeg supports the following transfer syntaxes for input
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
594 (*) if compiled with zlib support enabled
596 \b dcmcjpeg supports the following transfer syntaxes for output
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
608 \section logging LOGGING
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".
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>).
627 \section command_line COMMAND LINE
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.
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.
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>).
649 \section environment ENVIRONMENT
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).
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.
665 \section see_also SEE ALSO
669 \section copyright COPYRIGHT
671 Copyright (C) 2001-2010 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany.