kc3-lang/libjpeg-turbo/doc/usage.txt
Branch
-
doc/usage.txt
-
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822
This file was part of the Independent JPEG Group's software: Copyright (C) 1991-2020, Thomas G. Lane, Guido Vollbeding. libjpeg-turbo Modifications: Copyright (C) 2010, 2012, 2014-2017, 2020-2024, D. R. Commander. For conditions of distribution and use, see the accompanying README.ijg file. USAGE instructions for the Independent JPEG Group's JPEG software ================================================================= This file describes usage of the JPEG conversion programs cjpeg and djpeg, as well as the utility programs jpegtran, rdjpgcom and wrjpgcom. (See the other documentation files if you wish to use the JPEG library within your own programs.) If you are on a Unix machine you may prefer to read the Unix-style manual pages in files cjpeg.1, djpeg.1, jpegtran.1, rdjpgcom.1, wrjpgcom.1. INTRODUCTION These programs implement JPEG image encoding, decoding, and transcoding. JPEG (pronounced "jay-peg") is a standardized compression method for full-color and grayscale images. GENERAL USAGE We provide two programs, cjpeg to compress an image file into JPEG format, and djpeg to decompress a JPEG file back into a conventional image format. On most systems, you say: cjpeg [switches] [imagefile] >jpegfile or djpeg [switches] [jpegfile] >imagefile The programs read the specified input file, or standard input if none is named. They always write to standard output (with trace/error messages to standard error). These conventions are handy for piping images between programs. If you defined TWO_FILE_COMMANDLINE when compiling the programs, you can instead say: cjpeg [switches] imagefile jpegfile or djpeg [switches] jpegfile imagefile i.e., both the input and output files are named on the command line. This style is a little more foolproof, and it loses no functionality if you don't have pipes. You can also say: cjpeg [switches] -outfile jpegfile imagefile or djpeg [switches] -outfile imagefile jpegfile This syntax works on all systems, so it is useful for scripts. The currently supported image file formats are: PPM (PBMPLUS color format), PGM (PBMPLUS grayscale format), BMP, GIF [legacy feature], and Targa [legacy feature]. cjpeg recognizes the input image format automatically, with the exception of some Targa files. You have to tell djpeg which format to generate. JPEG files are in the defacto standard JFIF file format. There are other, less widely used JPEG-based file formats, but we don't support them. All switch names may be abbreviated; for example, -grayscale may be written -gray or -gr. Most of the "basic" switches can be abbreviated to as little as one letter. Upper and lower case are equivalent (-BMP is the same as -bmp). British spellings are also accepted (e.g., -greyscale), though for brevity these are not mentioned below. CJPEG DETAILS The basic command line switches for cjpeg are: -quality N[,...] Scale quantization tables to adjust image quality. Quality is 0 (worst) to 100 (best); default is 75. (See below for more info.) -grayscale Create monochrome JPEG file from color input. By specifying -grayscale, you'll get a smaller JPEG file that takes less time to process. -rgb Create RGB JPEG file. Using this switch suppresses the conversion from RGB colorspace input to the default YCbCr JPEG colorspace. -optimize Perform optimization of entropy encoding parameters. Without this, default encoding parameters are used. -optimize usually makes the JPEG file a little smaller, but cjpeg runs somewhat slower and needs much more memory. Image quality and speed of decompression are unaffected by -optimize. -progressive Create progressive JPEG file (see below). Implies -optimize unless -arithmetic is also specified. -targa Input file is Targa format [legacy feature]. Targa files that contain an "identification" field will not be automatically recognized by cjpeg. For such files, you must specify -targa to make cjpeg treat the input as Targa format. For most Targa files, you won't need this switch. The -quality switch lets you trade off compressed file size against quality of the reconstructed image: the higher the quality setting, the larger the JPEG file, and the closer the output image will be to the original input. Normally you want to use the lowest quality setting (smallest file) that decompresses into something visually indistinguishable from the original image. For this purpose the quality setting should generally be between 50 and 95 (the default is 75) for photographic images. If you see defects at -quality 75, then go up 5 or 10 counts at a time until you are happy with the output image. (The optimal setting will vary from one image to another.) -quality 100 will generate a quantization table of all 1's, minimizing loss in the quantization step (but there is still information loss in subsampling, as well as roundoff error.) For most images, specifying a quality value above about 95 will increase the size of the compressed file dramatically, and while the quality gain from these higher quality values is measurable (using metrics such as PSNR or SSIM), it is rarely perceivable by human vision. In the other direction, quality values below 50 will produce very small files of low image quality. Settings around 5 to 10 might be useful in preparing an index of a large image library, for example. Try -quality 2 (or so) for some amusing Cubist effects. (Note: quality values below about 25 generate 2-byte quantization tables, which are considered optional in the JPEG standard. cjpeg emits a warning message when you give such a quality value, because some other JPEG programs may be unable to decode the resulting file. Use -baseline if you need to ensure compatibility at low quality values.) The -quality option has been extended in this version of cjpeg to support separate quality settings for luminance and chrominance (or, in general, separate settings for every quantization table slot.) The principle is the same as chrominance subsampling: since the human eye is more sensitive to spatial changes in brightness than spatial changes in color, the chrominance components can be quantized more than the luminance components without incurring any visible image quality loss. However, unlike subsampling, this feature reduces data in the frequency domain instead of the spatial domain, which allows for more fine-grained control. This option is useful in quality-sensitive applications, for which the artifacts generated by subsampling may be unacceptable. The -quality option accepts a comma-separated list of parameters, which respectively refer to the quality levels that should be assigned to the quantization table slots. If there are more q-table slots than parameters, then the last parameter is replicated. Thus, if only one quality parameter is given, this is used for both luminance and chrominance (slots 0 and 1, respectively), preserving the legacy behavior of cjpeg v6b and prior. More (or customized) quantization tables can be set with the -qtables option and assigned to components with the -qslots option (see the "wizard" switches below.) JPEG files generated with separate luminance and chrominance quality are fully compliant with standard JPEG decoders. CAUTION: For this setting to be useful, be sure to pass an argument of -sample 1x1 to cjpeg to disable chrominance subsampling. Otherwise, the default subsampling level (2x2, AKA "4:2:0") will be used. The -progressive switch creates a "progressive JPEG" file. In this type of JPEG file, the data is stored in multiple scans of increasing quality. If the file is being transmitted over a slow communications link, the decoder can use the first scan to display a low-quality image very quickly, and can then improve the display with each subsequent scan. The final image is exactly equivalent to a standard JPEG file of the same quality setting, and the total file size is about the same --- often a little smaller. Switches for advanced users: -precision N Create JPEG file with N-bit data precision. N is 2 to 16; default is 8. If N is not 8 or 12, then -lossless must also be specified. Note that only the PBMPLUS input file format supports data precisions other than 8. Note also that PBMPLUS input files are silently scaled to the target data precision, even if it is lower than the precision of the input file. Passing an argument of -verbose to cjpeg will cause it to print information about the precision of the input file. CAUTION: only 8-bit data precision is widely implemented, so many decoders will be unable to handle JPEG files with other data precisions. "-precision 12" implies -optimize unless -arithmetic is also specified. -lossless psv[,Pt] Create a lossless JPEG file using the specified predictor selection value (1 - 7) and optional point transform (0 - {precision}-1, where {precision} is the JPEG data precision in bits). A point transform value of 0 (the default) is necessary in order to create a fully lossless JPEG file. (A non-zero point transform value right-shifts the input samples by the specified number of bits, which is effectively a form of lossy color quantization.) CAUTION: lossless JPEG is not yet widely implemented, so many decoders will be unable to handle a lossless JPEG file at all. In most cases, compressing and decompressing a lossless JPEG file is considerably slower than compressing and decompressing a lossy JPEG file, and lossless JPEG files are much larger than lossy JPEG files. Also note that the following features will be unavailable when compressing or decompressing a lossless JPEG file: * Quality/quantization table selection * Color space conversion (the JPEG image will use the same color space as the input image) * Color quantization * DCT/IDCT algorithm selection * Smoothing * Downsampling/upsampling * IDCT scaling * Partial image decompression * Transformations using jpegtran Any switches used to enable or configure those features will be ignored. -arithmetic Use arithmetic coding. CAUTION: arithmetic-coded JPEG is not yet widely implemented, so many decoders will be unable to handle an arithmetic-coded JPEG file at all. -dct int Use accurate integer DCT method (default). -dct fast Use less accurate integer DCT method [legacy feature]. When the Independent JPEG Group's software was first released in 1991, the compression time for a 1-megapixel JPEG image on a mainstream PC was measured in minutes. Thus, the fast integer DCT algorithm provided noticeable performance benefits. On modern CPUs running libjpeg-turbo, however, the compression time for a 1-megapixel JPEG image is measured in milliseconds, and thus the performance benefits of the fast algorithm are much less noticeable. On modern x86/x86-64 CPUs that support AVX2 instructions, the fast and int methods have similar performance. On other types of CPUs, the fast method is generally about 5-15% faster than the int method. For quality levels of 90 and below, there should be little or no perceptible quality difference between the two algorithms. For quality levels above 90, however, the difference between the fast and int methods becomes more pronounced. With quality=97, for instance, the fast method incurs generally about a 1-3 dB loss in PSNR relative to the int method, but this can be larger for some images. Do not use the fast method with quality levels above 97. The algorithm often degenerates at quality=98 and above and can actually produce a more lossy image than if lower quality levels had been used. Also, in libjpeg-turbo, the fast method is not fully accelerated for quality levels above 97, so it will be slower than the int method. -dct float Use floating-point DCT method [legacy feature]. The float method does not produce significantly more accurate results than the int method, and it is much slower. The float method may also give different results on different machines due to varying roundoff behavior, whereas the integer methods should give the same results on all machines. -icc FILE Embed ICC color management profile contained in the specified file. -restart N Emit a JPEG restart marker every N MCU rows, or every N MCUs if "B" is attached to the number. In typical JPEG images, an MCU (Minimum Coded Unit) is the minimum set of interleaved "data units" (8x8 DCT blocks if the image is lossy or samples if the image is lossless) necessary to represent at least one data unit per component. (For example, an MCU in an interleaved lossy JPEG image that uses 4:2:2 subsampling consists of two luminance blocks followed by one block for each chrominance component.) In single-component or non-interleaved JPEG images, an MCU is the same as a data unit. An MCU row is a row of MCUs spanning the entire width of the image. -restart 0 (the default) means no restart markers. -smooth N Smooth the input image to eliminate dithering noise. N, ranging from 1 to 100, indicates the strength of smoothing. 0 (the default) means no smoothing. -maxmemory N Set limit for amount of memory to use in processing large images. Value is in thousands of bytes, or millions of bytes if "M" is attached to the number. For example, -max 4m selects 4000000 bytes. If more space is needed, an error will occur. -memdst Compress to memory instead of a file. This feature was implemented mainly as a way of testing the in-memory destination manager (jpeg_mem_dest()), but it is also useful for benchmarking, since it reduces the I/O overhead. -report Report compression progress. -strict Treat all warnings as fatal. Enabling this option will cause the compressor to abort if an LZW-compressed GIF input image contains incomplete or corrupt image data. -verbose Enable debug printout. More -v's give more output. or -debug Also, version information is printed at startup. -version Print version information and exit. The -restart option inserts extra markers that allow a JPEG decoder to resynchronize after a transmission error. Without restart markers, any damage to a compressed file will usually ruin the image from the point of the error to the end of the image; with restart markers, the damage is usually confined to the portion of the image up to the next restart marker. Of course, the restart markers occupy extra space. We recommend -restart 1 for images that will be transmitted across unreliable networks such as Usenet. The -smooth option filters the input to eliminate fine-scale noise. This is often useful when converting dithered images to JPEG: a moderate smoothing factor of 10 to 50 gets rid of dithering patterns in the input file, resulting in a smaller JPEG file and a better-looking image. Too large a smoothing factor will visibly blur the image, however. Switches for wizards: -baseline Force baseline-compatible quantization tables to be generated. This clamps quantization values to 8 bits even at low quality settings. (This switch is poorly named, since it does not ensure that the output is actually baseline JPEG. For example, you can use -baseline and -progressive together.) -qtables file Use the quantization tables given in the specified text file. -qslots N[,...] Select which quantization table to use for each color component. -sample HxV[,...] Set JPEG sampling factors for each color component. -scans file Use the scan script given in the specified text file. The "wizard" switches are intended for experimentation with JPEG. If you don't know what you are doing, DON'T USE THEM. These switches are documented further in the file wizard.txt. DJPEG DETAILS The basic command line switches for djpeg are: -colors N Reduce image to at most N colors [legacy feature]. or -quantize N This reduces the number of colors used in the output image so that it can be stored in a colormapped file format. This feature cannot be used when decompressing lossless JPEG images. (-colors is the recommended name. -quantize is provided only for backward compatibility.) -fast Select recommended processing options for low-quality output [legacy feature]. (The default options are chosen for highest-quality output.) Currently, this is equivalent to "-dct fast -nosmooth -onepass -dither ordered". On modern CPUs, these settings have little or no performance benefit and are retained solely for backward compatibility. -grayscale Force grayscale output even if JPEG file is full-color. This feature cannot be used when decompressing full-color lossless JPEG images. -rgb Force RGB output even if JPEG file is grayscale. This feature cannot be used when decompressing grayscale lossless JPEG images. -scale M/N Scale the output image by a factor M/N. Currently the scale factor must be M/8, where M is an integer between 1 and 16 inclusive, or any reduced fraction thereof (such as 1/2, 3/4, etc.) Scaling is handy if the image is larger than your screen. This feature cannot be used when decompressing lossless JPEG images. -bmp Select BMP output format (Windows flavor). 8-bit colormapped format is emitted if -colors or -grayscale is specified, or if the JPEG file is grayscale; otherwise, 24-bit full-color format is emitted. This format can only be used when decompressing 8-bit-per-sample JPEG images. -gif Select GIF output format (LZW-compressed) [legacy feature]. Since GIF does not support more than 256 colors, -colors 256 is assumed (unless you specify a smaller number of colors). If you specify -fast, the default number of colors is 216. This format can only be used when decompressing 8-bit-per-sample or 12-bit-per-sample lossy JPEG images. -gif0 Select GIF output format (uncompressed) [legacy feature]. Since GIF does not support more than 256 colors, -colors 256 is assumed (unless you specify a smaller number of colors). If you specify -fast, the default number of colors is 216. This format can only be used when decompressing 8-bit-per-sample or 12-bit-per-sample lossy JPEG images. -os2 Select BMP output format (OS/2 1.x flavor) [legacy feature]. 8-bit colormapped format is emitted if -colors or -grayscale is specified, or if the JPEG file is grayscale; otherwise, 24-bit full-color format is emitted. This format can only be used when decompressing 8-bit-per-sample JPEG images. -pnm Select PBMPLUS (PPM/PGM) output format (this is the default format). PGM is emitted if the JPEG file is grayscale or if -grayscale is specified; otherwise PPM is emitted. -targa Select Targa output format [legacy feature]. Grayscale format is emitted if the JPEG file is grayscale or if -grayscale is specified; otherwise, colormapped format is emitted if -colors is specified; otherwise, 24-bit full-color format is emitted. This format can only be used when decompressing 8-bit-per-sample JPEG images. Switches for advanced users: -dct int Use accurate integer DCT method (default). -dct fast Use less accurate integer DCT method [legacy feature]. When the Independent JPEG Group's software was first released in 1991, the decompression time for a 1-megapixel JPEG image on a mainstream PC was measured in minutes. Thus, the fast integer DCT algorithm provided noticeable performance benefits. On modern CPUs running libjpeg-turbo, however, the decompression time for a 1-megapixel JPEG image is measured in milliseconds, and thus the performance benefits of the fast algorithm are much less noticeable. On modern x86/x86-64 CPUs that support AVX2 instructions, the fast and int methods have similar performance. On other types of CPUs, the fast method is generally about 5-15% faster than the int method. If the JPEG image was compressed using a quality level of 85 or below, then there should be little or no perceptible quality difference between the two algorithms. When decompressing images that were compressed using quality levels above 85, however, the difference between the fast and int methods becomes more pronounced. With images compressed using quality=97, for instance, the fast method incurs generally about a 4-6 dB loss in PSNR relative to the int method, but this can be larger for some images. If you can avoid it, do not use the fast method when decompressing images that were compressed using quality levels above 97. The algorithm often degenerates for such images and can actually produce a more lossy output image than if the JPEG image had been compressed using lower quality levels. -dct float Use floating-point DCT method [legacy feature]. The float method does not produce significantly more accurate results than the int method, and it is much slower. The float method may also give different results on different machines due to varying roundoff behavior, whereas the integer methods should give the same results on all machines. -dither fs Use Floyd-Steinberg dithering when quantizing colors [legacy feature]. -dither ordered Use ordered dithering when quantizing colors [legacy feature]. -dither none Do not use dithering when quantizing colors [legacy feature]. By default, Floyd-Steinberg dithering is applied when quantizing colors. This is slower but usually produces the best results. Ordered dithering is a compromise between speed and quality. No dithering is faster but usually looks awful. Note that these switches have no effect unless color quantization is being done. Ordered dithering is only available in -onepass mode. -icc FILE Extract ICC color management profile to the specified file. -map FILE Quantize to the colors used in the specified image file [legacy feature]. This is useful for producing multiple files with identical color maps, or for forcing a predefined set of colors to be used. The FILE must be a GIF or PPM file. This option overrides -colors and -onepass. -nosmooth Use a faster, lower-quality upsampling routine. -onepass Use one-pass instead of two-pass color quantization [legacy feature]. The one-pass method needs less memory, but it produces a lower-quality image. -onepass is ignored unless you also specify -colors N. Also, the one-pass method is always used for grayscale output. (The two-pass method has no improvement in that case.) -maxmemory N Set limit for amount of memory to use in processing large images. Value is in thousands of bytes, or millions of bytes if "M" is attached to the number. For example, -max 4m selects 4000000 bytes. If more space is needed, an error will occur. -maxscans N Abort if the JPEG image contains more than N scans. This feature demonstrates a method by which applications can guard against denial-of-service attacks instigated by specially-crafted malformed JPEG images containing numerous scans with missing image data or image data consisting only of "EOB runs" (a feature of progressive JPEG images that allows potentially hundreds of thousands of adjoining zero-value pixels to be represented using only a few bytes.) Attempting to decompress such malformed JPEG images can cause excessive CPU activity, since the decompressor must fully process each scan (even if the scan is corrupt) before it can proceed to the next scan. -memsrc Load input file into memory before decompressing. This feature was implemented mainly as a way of testing the in-memory source manager (jpeg_mem_src().) -report Report decompression progress. -skip Y0,Y1 Decompress all rows of the JPEG image except those between Y0 and Y1 (inclusive.) Note that if decompression scaling is being used, then Y0 and Y1 are relative to the scaled image dimensions. -crop WxH+X+Y Decompress only a rectangular subregion of the image, starting at point X,Y with width W and height H. If necessary, X will be shifted left to the nearest iMCU boundary, and the width will be increased accordingly. Note that if decompression scaling is being used, then X, Y, W, and H are relative to the scaled image dimensions. Currently this option only works with the PBMPLUS (PPM/PGM), GIF, and Targa output formats. -strict Treat all warnings as fatal. This feature also demonstrates a method by which applications can guard against attacks instigated by specially-crafted malformed JPEG images. Enabling this option will cause the decompressor to abort if the JPEG image contains incomplete or corrupt image data. -verbose Enable debug printout. More -v's give more output. or -debug Also, version information is printed at startup. -version Print version information and exit. HINTS FOR CJPEG Color GIF files are not the ideal input for JPEG; JPEG is really intended for compressing full-color (24-bit through 48-bit) images. In particular, don't try to convert cartoons, line drawings, and other images that have only a few distinct colors. GIF works great on these; JPEG does not. If you want to convert a GIF to JPEG, you should experiment with cjpeg's -quality and -smooth options to get a satisfactory conversion. -smooth 10 or so is often helpful. Avoid running an image through a series of JPEG compression/decompression cycles. Image quality loss will accumulate; after ten or so cycles the image may be noticeably worse than it was after one cycle. It's best to use a lossless format while manipulating an image, then convert to JPEG format when you are ready to file the image away. The -optimize option to cjpeg is worth using when you are making a "final" version for posting or archiving. It's also a win when you are using low quality settings to make very small JPEG files; the percentage improvement is often a lot more than it is on larger files. (At present, -optimize mode is always selected when generating progressive JPEG files.) HINTS FOR BOTH PROGRAMS If the memory needed by cjpeg or djpeg exceeds the limit specified by -maxmemory, an error will occur. You can leave out -progressive and -optimize (for cjpeg) or specify -onepass (for djpeg) to reduce memory usage. On machines that have "environment" variables, you can define the environment variable JPEGMEM to set the default memory limit. The value is specified as described for the -maxmemory switch. JPEGMEM overrides the default value specified when the program was compiled, and itself is overridden by an explicit -maxmemory switch. JPEGTRAN jpegtran performs various useful transformations of lossy (DCT-based) JPEG files. It can translate the coded representation from one variant of JPEG to another, for example from baseline JPEG to progressive JPEG or vice versa. It can also perform some rearrangements of the image data, for example turning an image from landscape to portrait format by rotation. For EXIF files and JPEG files containing Exif data, you may prefer to use exiftran instead. jpegtran works by rearranging the compressed data (DCT coefficients), without ever fully decoding the image. Therefore, its transformations are lossless: there is no image degradation at all, which would not be true if you used djpeg followed by cjpeg to accomplish the same conversion. But by the same token, jpegtran cannot perform lossy operations such as changing the image quality. However, while the image data is losslessly transformed, metadata can be removed. See the -copy option for specifics. jpegtran uses a command line syntax similar to cjpeg or djpeg. On most systems, you say: jpegtran [switches] [inputfile] >outputfile If you defined TWO_FILE_COMMANDLINE when compiling the program, you can instead say: jpegtran [switches] inputfile outputfile where both the input and output files are JPEG files. To specify the coded JPEG representation used in the output file, jpegtran accepts a subset of the switches recognized by cjpeg: -optimize Perform optimization of entropy encoding parameters. -progressive Create progressive JPEG file. -arithmetic Use arithmetic coding. -restart N Emit a JPEG restart marker every N MCU rows, or every N MCUs if "B" is attached to the number. -scans file Use the scan script given in the specified text file. See the previous discussion of cjpeg for more details about these switches. If you specify none of these switches, you get a plain baseline-JPEG output file. The quality setting and so forth are determined by the input file. The image can be losslessly transformed by giving one of these switches: -flip horizontal Mirror image horizontally (left-right). -flip vertical Mirror image vertically (top-bottom). -rotate 90 Rotate image 90 degrees clockwise. -rotate 180 Rotate image 180 degrees. -rotate 270 Rotate image 270 degrees clockwise (or 90 ccw). -transpose Transpose image (across UL-to-LR axis). -transverse Transverse transpose (across UR-to-LL axis). The transpose transformation has no restrictions regarding image dimensions. The other transformations operate rather oddly if the image dimensions are not a multiple of the iMCU size (usually 8 or 16 pixels), because they can only transform complete blocks of DCT coefficient data in the desired way. jpegtran's default behavior when transforming an odd-size image is designed to preserve exact reversibility and mathematical consistency of the transformation set. As stated, transpose is able to flip the entire image area. Horizontal mirroring leaves any partial iMCU column at the right edge untouched, but is able to flip all rows of the image. Similarly, vertical mirroring leaves any partial iMCU row at the bottom edge untouched, but is able to flip all columns. The other transforms can be built up as sequences of transpose and flip operations; for consistency, their actions on edge pixels are defined to be the same as the end result of the corresponding transpose-and-flip sequence. For practical use, you may prefer to discard any untransformable edge pixels rather than having a strange-looking strip along the right and/or bottom edges of a transformed image. To do this, add the -trim switch: -trim Drop non-transformable edge blocks. Obviously, a transformation with -trim is not reversible, so strictly speaking jpegtran with this switch is not lossless. Also, the expected mathematical equivalences between the transformations no longer hold. For example, "-rot 270 -trim" trims only the bottom edge, but "-rot 90 -trim" followed by "-rot 180 -trim" trims both edges. If you are only interested in perfect transformations, add the -perfect switch: -perfect Fail with an error if the transformation is not perfect. For example, you may want to do jpegtran -rot 90 -perfect foo.jpg || djpeg foo.jpg | pnmflip -r90 | cjpeg to do a perfect rotation, if available, or an approximated one if not. This version of jpegtran also offers a lossless crop option, which discards data outside of a given image region but losslessly preserves what is inside. Like the rotate and flip transforms, lossless crop is restricted by the current JPEG format; the upper left corner of the selected region must fall on an iMCU boundary. If it doesn't, then it is silently moved up and/or left to the nearest iMCU boundary (the lower right corner is unchanged.) Thus, the output image covers at least the requested region, but it may cover more. The adjustment of the region dimensions may be optionally disabled by attaching an 'f' character ("force") to the width or height number. The image can be losslessly cropped by giving the switch: -crop WxH+X+Y Crop to a rectangular region of width W and height H, starting at point X,Y. If W or H is larger than the width/height of the input image, then the output image is expanded in size, and the expanded region is filled in with zeros (neutral gray). Attaching an 'f' character ("flatten") to the width number will cause each block in the expanded region to be filled in with the DC coefficient of the nearest block in the input image rather than grayed out. Attaching an 'r' character ("reflect") to the width number will cause the expanded region to be filled in with repeated reflections of the input image rather than grayed out. A complementary lossless wipe option is provided to discard (gray out) data inside a given image region while losslessly preserving what is outside: -wipe WxH+X+Y Wipe (gray out) a rectangular region of width W and height H from the input image, starting at point X,Y. Attaching an 'f' character ("flatten") to the width number will cause the region to be filled with the average of adjacent blocks rather than grayed out. If the wipe region and the region outside the wipe region, when adjusted to the nearest iMCU boundary, form two horizontally adjacent rectangles, then attaching an 'r' character ("reflect") to the width number will cause the wipe region to be filled with repeated reflections of the outside region rather than grayed out. A lossless drop option is also provided, which allows another JPEG image to be inserted ("dropped") into the input image data at a given position, replacing the existing image data at that position: -drop +X+Y filename Drop (insert) another image at point X,Y Both the input image and the drop image must have the same subsampling level. It is best if they also have the same quantization (quality.) Otherwise, the quantization of the output image will be adapted to accommodate the higher of the input image quality and the drop image quality. The trim option can be used with the drop option to requantize the drop image to match the input image. Note that a grayscale image can be dropped into a full-color image or vice versa, as long as the full-color image has no vertical subsampling. If the input image is grayscale and the drop image is full-color, then the chrominance channels from the drop image will be discarded. Other not-strictly-lossless transformation switches are: -grayscale Force grayscale output. This option discards the chrominance channels if the input image is YCbCr (ie, a standard color JPEG), resulting in a grayscale JPEG file. The luminance channel is preserved exactly, so this is a better method of reducing to grayscale than decompression, conversion, and recompression. This switch is particularly handy for fixing a monochrome picture that was mistakenly encoded as a color JPEG. (In such a case, the space savings from getting rid of the near-empty chroma channels won't be large; but the decoding time for a grayscale JPEG is substantially less than that for a color JPEG.) jpegtran also recognizes these switches that control what to do with "extra" markers, such as comment blocks: -copy none Copy no extra markers from source file. This setting suppresses all comments and other metadata in the source file. -copy comments Copy only comment markers. This setting copies comments from the source file but discards any other metadata. -copy icc Copy only ICC profile markers. This setting copies the ICC profile from the source file but discards any other metadata. -copy all Copy all extra markers. This setting preserves miscellaneous markers found in the source file, such as JFIF thumbnails, Exif data, and Photoshop settings. In some files, these extra markers can be sizable. Note that this option will copy thumbnails as-is; they will not be transformed. The default behavior is -copy comments. (Note: in IJG releases v6 and v6a, jpegtran always did the equivalent of -copy none.) Additional switches recognized by jpegtran are: -icc FILE -maxmemory N -maxscans N -outfile filename -report -strict -verbose -debug -version These work the same as in cjpeg or djpeg. THE COMMENT UTILITIES The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file. Although the standard doesn't actually define what COM blocks are for, they are widely used to hold user-supplied text strings. This lets you add annotations, titles, index terms, etc to your JPEG files, and later retrieve them as text. COM blocks do not interfere with the image stored in the JPEG file. The maximum size of a COM block is 64K, but you can have as many of them as you like in one JPEG file. We provide two utility programs to display COM block contents and add COM blocks to a JPEG file. rdjpgcom searches a JPEG file and prints the contents of any COM blocks on standard output. The command line syntax is rdjpgcom [-raw] [-verbose] [inputfilename] The switch "-raw" (or just "-r") causes rdjpgcom to output non-printable characters in JPEG comments. These characters are normally escaped for security reasons. The switch "-verbose" (or just "-v") causes rdjpgcom to also display the JPEG image dimensions. If you omit the input file name from the command line, the JPEG file is read from standard input. (This may not work on some operating systems, if binary data can't be read from stdin.) wrjpgcom adds a COM block, containing text you provide, to a JPEG file. Ordinarily, the COM block is added after any existing COM blocks, but you can delete the old COM blocks if you wish. wrjpgcom produces a new JPEG file; it does not modify the input file. DO NOT try to overwrite the input file by directing wrjpgcom's output back into it; on most systems this will just destroy your file. The command line syntax for wrjpgcom is similar to cjpeg's. On most systems, it is wrjpgcom [switches] [inputfilename] The output file is written to standard output. The input file comes from the named file, or from standard input if no input file is named. If you defined TWO_FILE_COMMANDLINE when compiling the program, the syntax is: wrjpgcom [switches] inputfilename outputfilename where both input and output file names must be given explicitly. wrjpgcom understands three switches: -replace Delete any existing COM blocks from the file. -comment "Comment text" Supply new COM text on command line. -cfile name Read text for new COM block from named file. (Switch names can be abbreviated.) If you have only one line of comment text to add, you can provide it on the command line with -comment. The comment text must be surrounded with quotes so that it is treated as a single argument. Longer comments can be read from a text file. If you give neither -comment nor -cfile, then wrjpgcom will read the comment text from standard input. (In this case an input image file name MUST be supplied, so that the source JPEG file comes from somewhere else.) You can enter multiple lines, up to 64KB worth. Type an end-of-file indicator (usually control-D or control-Z) to terminate the comment text entry. wrjpgcom will not add a COM block if the provided comment string is empty. Therefore -replace -comment "" can be used to delete all COM blocks from a file. These utility programs do not depend on the IJG JPEG library. In particular, the source code for rdjpgcom is intended as an illustration of the minimum amount of code required to parse a JPEG file header correctly.