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

NAME

6       dcmcjpeg - Encode DICOM file to JPEG transfer syntax
7
8

SYNOPSIS

10       dcmcjpeg [options] dcmfile-in dcmfile-out
11

DESCRIPTION

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

PARAMETERS

19       dcmfile-in   DICOM input filename to be converted
20
21       dcmfile-out  DICOM output filename
22

OPTIONS

24   general options
25         -h    --help
26                 print this help text and exit
27
28               --version
29                 print version information and exit
30
31               --arguments
32                 print expanded command line arguments
33
34         -q    --quiet
35                 quiet mode, print no warnings and errors
36
37         -v    --verbose
38                 verbose mode, print processing details
39
40         -d    --debug
41                 debug mode, print debug information
42
43         -ll   --log-level  [l]evel: string constant
44                 (fatal, error, warn, info, debug, trace)
45                 use level l for the logger
46
47         -lc   --log-config  [f]ilename: string
48                 use config file f for the logger
49
50   input options
51       input file format:
52
53         +f    --read-file
54                 read file format or data set (default)
55
56         +fo   --read-file-only
57                 read file format only
58
59         -f    --read-dataset
60                 read data set without file meta information
61
62       input transfer syntax:
63
64         -t=   --read-xfer-auto
65                 use TS recognition (default)
66
67         -td   --read-xfer-detect
68                 ignore TS specified in the file meta header
69
70         -te   --read-xfer-little
71                 read with explicit VR little endian TS
72
73         -tb   --read-xfer-big
74                 read with explicit VR big endian TS
75
76         -ti   --read-xfer-implicit
77                 read with implicit VR little endian TS
78
79       compatibility (ignored by +tl):
80
81         +Ma   --accept-acr-nema
82                 accept ACR-NEMA images without photometric interpretation
83
84         # Enables compatibility for old ACR-NEMA images without photometric
85         # information (only pseudo lossless encoder)
86
87         +Mp   --accept-palettes
88                 accept incorrect palette attribute tags (0028,111x) and
89                 (0028,121x)
90
91         # If enabled, incorrect palette attribute tags are accepted
92         # (only pseudo lossless encoder)
93
94   JPEG encoding options
95       JPEG process:
96
97         +e1   --encode-lossless-sv1
98                 encode lossless sv1 (default)
99
100         # 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
104         +el   --encode-lossless
105                 encode lossless
106
107         # This option selects the JPEG Lossless, Non-Hierarchical (Process 14)
108         # Transfer Syntax for Lossless JPEG Image Compression.
109
110         +eb   --encode-baseline
111                 encode baseline
112
113         # This option selects the JPEG Baseline (Process 1) Transfer Syntax
114         # for Lossy JPEG 8 Bit Image Compression.
115
116         +ee   --encode-extended
117                 encode extended sequential
118
119         # This option selects the JPEG Extended (Process 2 & 4) Transfer
120         # Syntax for Lossy JPEG Image Compression.
121
122         +es   --encode-spectral
123                 encode spectral selection
124
125         # This option selects the JPEG Spectral Selection, Non-Hierarchical
126         # (Process 6 & 8) Transfer Syntax for Lossy JPEG Image Compression.
127
128         +ep   --encode-progressive
129                 encode progressive
130
131         # This option selects the JPEG Full Progression, Non-Hierarchical
132         # (Process 10 & 12) Transfer Syntax for Lossy JPEG Image Compression.
133
134       lossless JPEG codec selection:
135
136         +tl   --true-lossless
137                 true lossless codec (default)
138
139         # This option selects an encoder, that guarantees truly lossless
140         # image compression. See NOTES for further information.
141
142         +pl   --pseudo-lossless
143                 old pseudo-lossless codec
144
145         # 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
149       lossless JPEG representation:
150
151         +sv   --selection-value  [sv]: integer (1..7, default: 6)
152                 use selection value sv only with --encode-lossless
153
154         # This option selects the selection value for lossless JPEG.
155
156         +pt   --point-transform  [pt]: integer (0..15, default: 0)
157                 use point transform pt
158
159         # 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
163       lossy JPEG representation:
164
165         +q    --quality  [q]: integer (0..100, default: 90)
166                 use quality factor q
167
168         # 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
173         +sm   --smooth  [s]: integer (0..100, default: 0)
174                 use smoothing factor s
175
176         # 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
180       other JPEG options:
181
182         +ho   --huffman-optimize
183                 optimize huffman tables (default)
184
185         # 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
189         -ho   --huffman-standard
190                 use standard huffman tables if 8 bits/sample
191
192         # This option disables an optimization of the huffman tables during
193         # image compression.
194
195       compressed bits per sample (always +ba with +tl):
196
197         +ba   --bits-auto
198                 choose bits/sample automatically (default)
199
200         +be   --bits-force-8
201                 force 8 bits/sample
202
203         +bt   --bits-force-12
204                 force 12 bits/sample (not with baseline)
205
206         +bs   --bits-force-16
207                 force 16 bits/sample (lossless only)
208
209       compression color space conversion (overridden by +tl):
210
211         +cy   --color-ybr
212                 use YCbCr for color images if lossy (default)
213
214         # This option enables a transformation of the color space to YCbCr
215         # prior to image compression for color images in lossy JPEG.
216
217         +cr   --color-rgb
218                 use RGB for color images if lossy
219
220         # 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
225         +cm   --monochrome
226                 convert color images to monochrome
227
228         # This option forces a conversion of color images to monochrome
229         # prior to compression.
230
231       decompression color space conversion
232       (if input is compressed; always +cn with +tl):
233
234         +cp   --conv-photometric
235                 convert if YCbCr photometric interpretation (default)
236
237         # 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
242         +cl   --conv-lossy
243                 convert YCbCr to RGB if lossy JPEG
244
245         # If the compressed image is encoded in lossy JPEG, assume YCbCr
246         # color model and convert to RGB.
247
248         +cg   --conv-guess
249                 convert to RGB if YCbCr is guessed by library
250
251         # If the underlying JPEG library "guesses" the color space of the
252         # compressed image to be YCbCr, convert to RGB.
253
254         +cgl  --conv-guess-lossy
255                 convert to RGB if lossy JPEG and YCbCr is
256                 guessed by the underlying JPEG library
257
258         # 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
261         +ca   --conv-always
262                 always convert YCbCr to RGB
263
264         # If the compressed image is a color image, assume YCbCr color model
265         # and convert to RGB.
266
267         +cn   --conv-never
268                 never convert color space
269
270         # Never convert color space during decompression.
271
272       decompr. workaround options for incorrect encodings (if input is compressed):
273
274         +w6   --workaround-pred6
275                 enable workaround for JPEG lossless images
276                 with overflow in predictor 6
277
278         # 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
286         +wi   --workaround-incpl
287                 enable workaround for incomplete JPEG data
288
289         # 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
294         +wc   --workaround-cornell
295                 enable workaround for 16-bit JPEG lossless
296                 Cornell images with Huffman table overflow
297
298         # 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
304       YCbCr component subsampling (lossy JPEG only):
305
306         +s2   --sample-422
307                 4:2:2 subsampling with YBR_FULL_422 (default)
308
309         # 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
313       non-standard YCbCr component subsampling (not with +tl):
314
315         +s4   --nonstd-444
316                 4:4:4 sampling with YBR_FULL
317
318         # 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
322         +n2   --nonstd-422-full
323                 4:2:2 subsampling with YBR_FULL
324
325         # 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
329         +n1   --nonstd-411-full
330                 4:1:1 subsampling with YBR_FULL
331
332         # 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
336         +np   --nonstd-411
337                 4:1:1 subsampling with YBR_FULL_422
338
339         # 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
343   encapsulated pixel data encoding options:
344       encapsulated pixel data fragmentation:
345
346         +ff   --fragment-per-frame
347                 encode each frame as one fragment (default)
348
349         # This option causes the creation of one compressed fragment for each
350         # frame (recommended).
351
352         +fs   --fragment-size  [s]ize: integer
353                 limit fragment size to s kbytes
354
355         # This option limits the fragment size which may cause the creation of
356         # multiple fragments per frame.
357
358       basic offset table encoding:
359
360         +ot   --offset-table-create
361                 create offset table (default)
362
363         # This option causes the creation of a valid offset table for the
364         # compressed JPEG fragments.
365
366         -ot   --offset-table-empty
367                 leave offset table empty
368
369         # This option causes the creation of an empty offset table
370         # for the compressed JPEG fragments.
371
372       VOI windowing for monochrome images (not with +tl):
373
374         -W    --no-windowing
375                 no VOI windowing (default)
376
377         # 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
381         +Wi   --use-window  [n]umber: integer
382                 use the n-th VOI window from image file
383
384         # Apply the n-th window center/width encoded in the image data prior
385         # to compression.
386
387         +Wl   --use-voi-lut  [n]umber: integer
388                 use the n-th VOI look up table from image file
389
390         # Apply the n-th VOI LUT encoded in the image data prior
391         # to compression.
392
393         +Wm   --min-max-window
394                 compute VOI window using min-max algorithm
395
396         # Compute and apply a window center and width that covers the
397         # range from the smallest to the largest occurring pixel value.
398
399         +Wn   --min-max-window-n
400                 compute VOI window using min-max algorithm,
401                 ignoring extreme values
402
403         # 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
410         +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
414         # This option works like --min-max-window but only considers the given
415         # region of interest inside the image.
416
417         +Wh   --histogram-window  [n]umber: integer
418                 compute VOI window using Histogram algorithm,
419                 ignoring n percent
420
421         # 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
425         +Ww   --set-window  [c]enter [w]idth: float
426                 compute VOI window using center c and width w
427
428         # Apply the given window center/width prior to compression.
429
430       pixel scaling for monochrome images (--no-windowing; ignored by +tl):
431
432         +sp   --scaling-pixel
433                 scale using min/max pixel value (default)
434
435         # 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
444         +sr   --scaling-range
445                 scale using min/max range
446
447         # 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
452       rescale slope/intercept encoding for monochrome (-W; ignored by +tl):
453
454         +ri   --rescale-identity
455                 encode identity modality rescale (default)
456                 Never used for CT images
457
458         # 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
463         +rm   --rescale-map
464                 use modality rescale to scale pixel range
465                 Never used for XA/RF/XA Biplane images
466
467         # 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
473       SOP Class UID:
474
475         +cd   --class-default
476                 keep SOP Class UID (default)
477
478         # Keep the SOP Class UID of the source image.
479
480         +cs   --class-sc
481                 convert to Secondary Capture Image (implies --uid-always)
482
483         # 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
487       SOP Instance UID:
488
489         +ud   --uid-default
490                 assign new UID if lossy compression (default)
491
492         # Assigns a new SOP instance UID if the compression is lossy.
493
494         +ua   --uid-always
495                 always assign new UID
496
497         # Unconditionally assigns a new SOP instance UID.
498
499         +un   --uid-never
500                 never assign new UID
501
502         # Never assigns a new SOP instance UID.
503
504   output options
505       post-1993 value representations:
506
507         +u    --enable-new-vr
508                 enable support for new VRs (UN/UT) (default)
509
510         -u    --disable-new-vr
511                 disable support for new VRs, convert to OB
512
513       group length encoding:
514
515         +g=   --group-length-recalc
516                 recalculate group lengths if present (default)
517
518         +g    --group-length-create
519                 always write with group length elements
520
521         -g    --group-length-remove
522                 always write without group length elements
523
524       length encoding in sequences and items:
525
526         +e    --length-explicit
527                 write with explicit lengths (default)
528
529         -e    --length-undefined
530                 write with undefined lengths
531
532       data set trailing padding:
533
534         -p=   --padding-retain
535                 do not change padding (default)
536
537         -p    --padding-off
538                 no padding
539
540         +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

NOTES

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
554       A few examples:
555
556       • 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.

TRANSFER SYNTAXES

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

LOGGING

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.

COMMAND LINE

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).

ENVIRONMENT

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.

SEE ALSO

663       dcmdjpeg(1)
665       Copyright  (C)  2001-2022  by OFFIS e.V., Escherweg 2, 26121 Oldenburg,
666       Germany.
667
668
669
670Version 3.6.7                   Fri Apr 22 2022                    dcmcjpeg(1)
Impressum