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