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