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