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 dcmcjpeg_synopsis SYNOPSIS 10 11\verbatim 12dcmcjpeg [options] dcmfile-in dcmfile-out 13\endverbatim 14 15\section dcmcjpeg_description DESCRIPTION 16 17The \b dcmcjpeg utility reads an uncompressed DICOM image (\e dcmfile-in), 18performs a JPEG compression (i. e. conversion to an encapsulated DICOM transfer 19syntax) and writes the converted image to an output file (\e dcmfile-out). 20 21\section dcmcjpeg_parameters PARAMETERS 22 23\verbatim 24dcmfile-in DICOM input filename to be converted 25 26dcmfile-out DICOM output filename 27\endverbatim 28 29\section dcmcjpeg_options OPTIONS 30 31\subsection dcmcjpeg_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 dcmcjpeg_input_options input options 60\verbatim 61input 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 72input 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 89compatibility (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 dcmcjpeg_JPEG_encoding_options JPEG encoding options 106\verbatim 107JPEG 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 146lossless 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 161lossless 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 175lossy 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 192other 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 207compressed 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 221compression color space conversion (overridden 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 243decompression 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 284decompr. workaround options for incorrect encodings (if input is compressed): 285 286 +w6 --workaround-pred6 287 enable workaround for JPEG lossless images 288 with overflow in predictor 6 289 290 # DICOM images with 16 bits/pixel have been observed "in the wild" 291 # that are compressed with lossless JPEG and need special handling 292 # because the encoder produced an 16-bit integer overflow in predictor 293 # 6, which needs to be compensated (reproduced) during decompression. 294 # This flag enables a correct decompression of such faulty images, but 295 # at the same time will cause an incorrect decompression of correctly 296 # compressed images. Use with care. 297 298 +wi --workaround-incpl 299 enable workaround for incomplete JPEG data 300 301 # This option causes dcmjpeg to ignore incomplete JPEG data 302 # at the end of a compressed fragment and to start decompressing 303 # the next frame from the next fragment (if any). This permits 304 # images with incomplete JPEG data to be decoded. 305 306 +wc --workaround-cornell 307 enable workaround for 16-bit JPEG lossless 308 Cornell images with Huffman table overflow 309 310 # One of the first open-source implementations of lossless JPEG 311 # compression, the "Cornell" library, has a well-known bug that leads 312 # to invalid values in the Huffmann table when images with 16 bit/sample 313 # are compressed. This flag enables a workaround that permits such 314 # images to be decoded correctly. 315 316YCbCr component subsampling (lossy JPEG only): 317 318 +s2 --sample-422 319 4:2:2 subsampling with YBR_FULL_422 (default) 320 321 # This option enables a 4:2:2 color component subsampling for 322 # compression in the YCbCr color space. The DICOM photometric 323 # interpretation is encoded as YBR_FULL_422. 324 325non-standard YCbCr component subsampling (not with +tl): 326 327 +s4 --nonstd-444 328 4:4:4 sampling with YBR_FULL 329 330 # This option disables color component subsampling for compression in 331 # the YCbCr color space. The DICOM photometric interpretation is 332 # encoded as YBR_FULL, which violates DICOM rules for lossy JPEG. 333 334 +n2 --nonstd-422-full 335 4:2:2 subsampling with YBR_FULL 336 337 # This option enables a 4:2:2 color component subsampling for 338 # compression in the YCbCr color space. The DICOM photometric 339 # interpretation is encoded as YBR_FULL, which violates DICOM rules. 340 341 +n1 --nonstd-411-full 342 4:1:1 subsampling with YBR_FULL 343 344 # This option enables a 4:1:1 color component subsampling for 345 # compression in the YCbCr color space. The DICOM photometric 346 # interpretation is encoded as YBR_FULL, which violates DICOM rules. 347 348 +np --nonstd-411 349 4:1:1 subsampling with YBR_FULL_422 350 351 # This option enables a 4:1:1 color component subsampling for 352 # compression in the YCbCr color space. The DICOM photometric 353 # interpretation is encoded as YBR_FULL_422, which violates DICOM rules. 354\endverbatim 355 356\subsection dcmcjpeg_enc_pix_data_encoding_opt encapsulated pixel data encoding options: 357\verbatim 358encapsulated pixel data fragmentation: 359 360 +ff --fragment-per-frame 361 encode each frame as one fragment (default) 362 363 # This option causes the creation of one compressed fragment for each 364 # frame (recommended). 365 366 +fs --fragment-size [s]ize: integer 367 limit fragment size to s kbytes 368 369 # This option limits the fragment size which may cause the creation of 370 # multiple fragments per frame. 371 372basic offset table encoding: 373 374 +ot --offset-table-create 375 create offset table (default) 376 377 # This option causes the creation of a valid offset table for the 378 # compressed JPEG fragments. 379 380 -ot --offset-table-empty 381 leave offset table empty 382 383 # This option causes the creation of an empty offset table 384 # for the compressed JPEG fragments. 385 386VOI windowing for monochrome images (not with +tl): 387 388 -W --no-windowing 389 no VOI windowing (default) 390 391 # No window level/width is "burned" into monochrome images prior to 392 # compression. See notes below on pixel scaling and rescale slope 393 # and intercept encoding. 394 395 +Wi --use-window [n]umber: integer 396 use the n-th VOI window from image file 397 398 # Apply the n-th window center/width encoded in the image data prior 399 # to compression. 400 401 +Wl --use-voi-lut [n]umber: integer 402 use the n-th VOI look up table from image file 403 404 # Apply the n-th VOI LUT encoded in the image data prior 405 # to compression. 406 407 +Wm --min-max-window 408 compute VOI window using min-max algorithm 409 410 # Compute and apply a window center and width that covers the 411 # range from the smallest to the largest occurring pixel value. 412 413 +Wn --min-max-window-n 414 compute VOI window using min-max algorithm, 415 ignoring extreme values 416 417 # Compute and apply a window center and width that covers the 418 # range from the second smallest to the second largest occurring 419 # pixel value. This is useful if the background is set to an 420 # artificial black (padding value) or if white overlays are burned 421 # into the image data which should not be considered for the window 422 # computation. 423 424 +Wr --roi-min-max-window [l]eft [t]op [w]idth [h]eight: integer 425 compute ROI window using min-max algorithm, 426 region of interest is specified by l,t,w,h 427 428 # This option works like --min-max-window but only considers the given 429 # region of interest inside the image. 430 431 +Wh --histogram-window [n]umber: integer 432 compute VOI window using Histogram algorithm, 433 ignoring n percent 434 435 # Compute a histogram of the image data and apply window center 436 # and width such than n% of the image data are ignored for the window 437 # computation 438 439 +Ww --set-window [c]enter [w]idth: float 440 compute VOI window using center c and width w 441 442 # Apply the given window center/width prior to compression. 443 444pixel scaling for monochrome images (--no-windowing; ignored by +tl): 445 446 +sp --scaling-pixel 447 scale using min/max pixel value (default) 448 449 # Monochrome image pixel values are always scaled to make use of the 450 # pixel range available with the selected JPEG process as good as 451 # possible. This option selects a scaling based on the minimum and 452 # maximum pixel value occurring in the image. This often leads to 453 # significantly better image quality, but may cause different 454 # compressed images within one series to have different values for 455 # rescale slope and intercept, which is a problem if a presentation 456 # state for one series is to be created. 457 458 +sr --scaling-range 459 scale using min/max range 460 461 # This options selects a scaling based on the pixel range as defined 462 # by the stored bits, pixel representation and modality transform, 463 # without consideration of the minimum and maximum value really 464 # used within the image. 465 466rescale slope/intercept encoding for monochrome (-W; ignored by +tl): 467 468 +ri --rescale-identity 469 encode identity modality rescale (default) 470 Never used for CT images 471 472 # This options prevents the creation of a modality transformation 473 # other than an identity transformation (which is required for 474 # many DICOM IODs). Window center/width settings encoded 475 # in the image are adapted, VOI LUTs are removed. 476 477 +rm --rescale-map 478 use modality rescale to scale pixel range 479 Never used for XA/RF/XA Biplane images 480 481 # This option causes the creation of a modality rescale slope and 482 # intercept that maps the decompressed image data back to their 483 # original range. This keeps all VOI transformations valid but 484 # requires that the DICOM IOD supports a modality rescale slope 485 # and intercept transformation other than identity. 486 487SOP Class UID: 488 489 +cd --class-default 490 keep SOP Class UID (default) 491 492 # Keep the SOP Class UID of the source image. 493 494 +cs --class-sc 495 convert to Secondary Capture Image (implies --uid-always) 496 497 # Convert the image to Secondary Capture. In addition to the SOP 498 # Class UID, all attributes required for a valid secondary capture 499 # image are added. A new SOP instance UID is always assigned. 500 501SOP Instance UID: 502 503 +ud --uid-default 504 assign new UID if lossy compression (default) 505 506 # Assigns a new SOP instance UID if the compression is lossy. 507 508 +ua --uid-always 509 always assign new UID 510 511 # Unconditionally assigns a new SOP instance UID. 512 513 +un --uid-never 514 never assign new UID 515 516 # Never assigns a new SOP instance UID. 517\endverbatim 518 519\subsection dcmcjpeg_output_options output options 520\verbatim 521post-1993 value representations: 522 523 +u --enable-new-vr 524 enable support for new VRs (UN/UT) (default) 525 526 -u --disable-new-vr 527 disable support for new VRs, convert to OB 528 529group length encoding: 530 531 +g= --group-length-recalc 532 recalculate group lengths if present (default) 533 534 +g --group-length-create 535 always write with group length elements 536 537 -g --group-length-remove 538 always write without group length elements 539 540length encoding in sequences and items: 541 542 +e --length-explicit 543 write with explicit lengths (default) 544 545 -e --length-undefined 546 write with undefined lengths 547 548data set trailing padding: 549 550 -p= --padding-retain 551 do not change padding (default) 552 553 -p --padding-off 554 no padding 555 556 +p --padding-create [f]ile-pad [i]tem-pad: integer 557 align file on multiple of f bytes 558 and items on multiple of i bytes 559\endverbatim 560 561\section dcmcjpeg_notes NOTES 562 563The \b dcmcjpeg utility compresses DICOM images of all SOP classes. It 564processes all Pixel Data (7fe0,0010) elements in the dataset, i.e. compression 565is also performed on an icon image. Special handling has been implemented for 566CT images (where the modality transformation is required to create Hounsfield 567units) and the XA/RF/Biplane SOP classes (where the modality transformation has 568"inversed" semantics). However, \b dcmcjpeg does not attempt to ensure that the 569compressed image still complies with all restrictions of the object's IOD. 570 571A few examples: 572 573\li MR images are required to have BitsAllocated=16. 574\li NM Images can only be encoded with MONOCHROME2 or PALETTE COLOR photometric 575 interpretation but not with RGB or YBR_FULL (which effectively prevents 576 compression). 577\li Hardcopy Color images must have RGB color model which is a problem if lossy 578 compression is to be performed. 579 580The user is responsible for making sure that the compressed images he creates 581are compliant with the DICOM standard. If in question, the \b dcmcjpeg utility 582allows one to convert an image to secondary capture - this SOP class does not 583pose restrictions as the ones mentioned above. 584 585With version DCMTK 3.5.4 a new encoder for truly lossless JPEG compression was 586added (\e --true-lossless). Compared to the old (\e --pseudo-lossless) encoder, 587that creates slightly lossy images caused from internal color space conversions, 588windowing etc., there are a some issues to consider: 589 590\li Only source images with Bits Allocated 8 or 16 are supported 591\li Options for color space conversions, windowing or pixel scaling are 592 ignored or overridden 593\li Photometric Interpretations YBR_FULL_422, YBR_PARTIAL_422, YBR_PARTIAL_420, 594 YBR_ICT, YBR_RCT are not supported 595\li The encoder changes automatically Planar Configuration from 1 to 0 if 596 necessary 597\li The compression ratio can be lower than in \e --pseudo-lossless mode 598 599However, when using the new encoder (default), you can be sure, that 600compression does not affect image quality. 601 602In order to be on the safe side, the Lossy Compression Flag is always set to 603"01" and a new SOP instance UID is assigned (by default) for the old 604pseudo-lossless encoder. The output of the old and new lossless encoder can 605also be distinguished by the Derivation Description in the resulting DICOM 606image, which contains the term "Lossless JPEG compression" for the new and 607"Pseudo-Lossless JPEG compression" for the old encoder. 608 609\section dcmcjpeg_transfer_syntaxes TRANSFER SYNTAXES 610 611\b dcmcjpeg supports the following transfer syntaxes for input 612(\e dcmfile-in): 613 614\verbatim 615LittleEndianImplicitTransferSyntax 1.2.840.10008.1.2 616LittleEndianExplicitTransferSyntax 1.2.840.10008.1.2.1 617DeflatedExplicitVRLittleEndianTransferSyntax 1.2.840.10008.1.2.1.99 (*) 618BigEndianExplicitTransferSyntax 1.2.840.10008.1.2.2 619JPEGProcess1TransferSyntax 1.2.840.10008.1.2.4.50 620JPEGProcess2_4TransferSyntax 1.2.840.10008.1.2.4.51 621JPEGProcess6_8TransferSyntax 1.2.840.10008.1.2.4.53 622JPEGProcess10_12TransferSyntax 1.2.840.10008.1.2.4.55 623JPEGProcess14TransferSyntax 1.2.840.10008.1.2.4.57 624JPEGProcess14SV1TransferSyntax 1.2.840.10008.1.2.4.70 625\endverbatim 626 627(*) if compiled with zlib support enabled 628 629\b dcmcjpeg supports the following transfer syntaxes for output 630(\e dcmfile-out): 631 632\verbatim 633JPEGProcess1TransferSyntax 1.2.840.10008.1.2.4.50 634JPEGProcess2_4TransferSyntax 1.2.840.10008.1.2.4.51 635JPEGProcess6_8TransferSyntax 1.2.840.10008.1.2.4.53 636JPEGProcess10_12TransferSyntax 1.2.840.10008.1.2.4.55 637JPEGProcess14TransferSyntax 1.2.840.10008.1.2.4.57 638JPEGProcess14SV1TransferSyntax 1.2.840.10008.1.2.4.70 639\endverbatim 640 641\section dcmcjpeg_logging LOGGING 642 643The level of logging output of the various command line tools and underlying 644libraries can be specified by the user. By default, only errors and warnings 645are written to the standard error stream. Using option \e --verbose also 646informational messages like processing details are reported. Option 647\e --debug can be used to get more details on the internal activity, e.g. for 648debugging purposes. Other logging levels can be selected using option 649\e --log-level. In \e --quiet mode only fatal errors are reported. In such 650very severe error events, the application will usually terminate. For more 651details on the different logging levels, see documentation of module "oflog". 652 653In case the logging output should be written to file (optionally with logfile 654rotation), to syslog (Unix) or the event log (Windows) option \e --log-config 655can be used. This configuration file also allows for directing only certain 656messages to a particular output stream and for filtering certain messages 657based on the module or application where they are generated. An example 658configuration file is provided in <em>\<etcdir\>/logger.cfg</em>. 659 660\section dcmcjpeg_command_line COMMAND LINE 661 662All command line tools use the following notation for parameters: square 663brackets enclose optional values (0-1), three trailing dots indicate that 664multiple values are allowed (1-n), a combination of both means 0 to n values. 665 666Command line options are distinguished from parameters by a leading '+' or '-' 667sign, respectively. Usually, order and position of command line options are 668arbitrary (i.e. they can appear anywhere). However, if options are mutually 669exclusive the rightmost appearance is used. This behavior conforms to the 670standard evaluation rules of common Unix shells. 671 672In addition, one or more command files can be specified using an '@' sign as a 673prefix to the filename (e.g. <em>\@command.txt</em>). Such a command argument 674is replaced by the content of the corresponding text file (multiple 675whitespaces are treated as a single separator unless they appear between two 676quotation marks) prior to any further evaluation. Please note that a command 677file cannot contain another command file. This simple but effective approach 678allows one to summarize common combinations of options/parameters and avoids 679longish and confusing command lines (an example is provided in file 680<em>\<datadir\>/dumppat.txt</em>). 681 682\section dcmcjpeg_environment ENVIRONMENT 683 684The \b dcmcjpeg utility will attempt to load DICOM data dictionaries specified 685in the \e DCMDICTPATH environment variable. By default, i.e. if the 686\e DCMDICTPATH environment variable is not set, the file 687<em>\<datadir\>/dicom.dic</em> will be loaded unless the dictionary is built 688into the application (default for Windows). 689 690The default behavior should be preferred and the \e DCMDICTPATH environment 691variable only used when alternative data dictionaries are required. The 692\e DCMDICTPATH environment variable has the same format as the Unix shell 693\e PATH variable in that a colon (":") separates entries. On Windows systems, 694a semicolon (";") is used as a separator. The data dictionary code will 695attempt to load each file specified in the \e DCMDICTPATH environment variable. 696It is an error if no data dictionary can be loaded. 697 698\section dcmcjpeg_see_also SEE ALSO 699 700<b>dcmdjpeg</b>(1) 701 702\section dcmcjpeg_copyright COPYRIGHT 703 704Copyright (C) 2001-2018 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany. 705 706*/ 707