| USAGE instructions for the Independent JPEG Group's JPEG software |
| ================================================================= |
| |
| INTRODUCTION |
| |
| This distribution contains software to implement JPEG image compression and |
| decompression. JPEG (pronounced "jay-peg") is a standardized compression |
| method for full-color and gray-scale images. JPEG is designed to handle |
| "real-world" scenes, for example scanned photographs. Cartoons, line |
| drawings, and other non-realistic images are not JPEG's strong suit; on this |
| sort of material you may get poor image quality and/or little compression. |
| |
| JPEG is lossy, meaning that the output image is not necessarily identical to |
| the input image. Hence you should not use JPEG if you have to have identical |
| output bits. However, on typical real-world images, very good compression |
| levels can be obtained with no visible change, and amazingly high compression |
| is possible if you can tolerate a low-quality image. You can trade off image |
| quality against file size by adjusting the compressor's "quality" setting. |
| |
| This file describes usage of the standard programs "cjpeg" and "djpeg" that |
| can be built directly from the distributed C code. See the README file for |
| hints on incorporating the JPEG software into other programs. |
| |
| If you are on a Unix machine you may prefer to read the Unix-style manual |
| pages in files cjpeg.1 and djpeg.1. But also see the HINTS section below, |
| which is not present in either manual page. |
| |
| NOTE: the switch syntax has been redesigned since the v3 release of |
| cjpeg/djpeg. Switch names are now words instead of single letters. |
| |
| |
| 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 Unix-like 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. |
| |
| On most non-Unix systems, you 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 get this style on Unix too, if you prefer, by defining |
| TWO_FILE_COMMANDLINE when you compile the programs; see SETUP.) |
| |
| 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 gray-scale format), GIF, Targa, and RLE (Utah Raster Toolkit |
| format). (RLE is supported only if the URT library is available.) |
| cjpeg recognizes the input image format automatically, with the exception |
| of some Targa-format files. You have to tell djpeg which format to generate. |
| |
| The only JPEG file format currently supported is the JFIF format. Support for |
| the TIFF 6.0 JPEG format will probably be added at some future date. |
| |
| 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 (-GIF is the same as -gif). |
| 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. |
| Be sure to use this switch when compressing a grayscale |
| GIF file, because cjpeg isn't bright enough to notice |
| whether a GIF file uses only shades of gray. By |
| saying -grayscale, you'll get a smaller JPEG file that |
| takes less time to process. |
| |
| -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. |
| |
| -targa Input file is Targa format. 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. |
| |
| 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 be between 50 and 95; the default of 75 is |
| often about right. 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, eliminating loss |
| in the quantization step (but there is still information loss in subsampling, |
| as well as roundoff error). This setting is mainly of interest for |
| experimental purposes. Quality values above about 95 are NOT recommended for |
| normal use; the compressed file size goes up dramatically for hardly any gain |
| in output image quality. |
| |
| 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 commercial JPEG programs may be unable to decode the resulting file.) |
| |
| Switches for advanced users: |
| |
| -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, temporary files will be used. |
| |
| -restart N Emit a JPEG restart marker every N MCU rows, or every |
| N MCU blocks if "B" is attached to the number. |
| -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. |
| |
| -verbose Enable debug printout. More -v's give more printout. |
| or -debug Also, version information is printed at startup. |
| |
| 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 GIF files 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: |
| |
| -arithmetic Use arithmetic coding rather than Huffman coding. |
| (Not currently supported for legal reasons.) |
| |
| -nointerleave Generate noninterleaved JPEG file (not yet supported). |
| |
| -qtables file Use the quantization tables given in the specified |
| file. The file should contain one to four tables |
| (64 values each) as plain text. Comments preceded by |
| '#' may be included in the file. The tables are |
| implicitly numbered 0,1,etc. If -quality N is also |
| specified, the values in the file are scaled according |
| to cjpeg's quality scaling curve. |
| |
| -sample HxV[,...] Set JPEG sampling factors. If you specify |
| fewer H/V pairs than there are components, the |
| remaining components are set to 1x1 sampling. The |
| default setting is equivalent to "-sample 2x2". |
| |
| The "wizard" switches are intended for experimentation with JPEG. If you |
| don't know what you are doing, DON'T USE THEM. You can easily produce files |
| with worse image quality and/or poorer compression than you'll get from the |
| default settings. Furthermore, these switches should not be used when making |
| files intended for general use, because not all JPEG implementations will |
| support unusual JPEG parameter settings. |
| |
| |
| DJPEG DETAILS |
| |
| The basic command line switches for djpeg are: |
| |
| -colors N Reduce image to at most N colors. This reduces the |
| or -quantize N number of colors used in the output image, so that it |
| can be displayed on a colormapped display or stored in |
| a colormapped file format. For example, if you have |
| an 8-bit display, you'd need to reduce to 256 or fewer |
| colors. (-colors is the recommended name, -quantize |
| is provided only for backwards compatibility.) |
| |
| -gif Select GIF output format. Since GIF does not support |
| more than 256 colors, -colors 256 is assumed (unless |
| you specify a smaller number of colors). |
| |
| -pnm Select PBMPLUS (PPM/PGM) output format (this is the |
| default format). PGM is emitted if the JPEG file is |
| gray-scale or if -grayscale is specified; otherwise |
| PPM is emitted. |
| |
| -rle Select RLE output format. (Requires URT library.) |
| |
| -targa Select Targa output format. Gray-scale format is |
| emitted if the JPEG file is gray-scale or if |
| -grayscale is specified; otherwise, colormapped format |
| is emitted if -colors is specified; otherwise, 24-bit |
| full-color format is emitted. |
| |
| Switches for advanced users: |
| |
| -blocksmooth Perform cross-block smoothing. This is slow, quite |
| memory-intensive, and only seems to improve the image |
| at very low quality settings (-quality 10 to 20 or so). |
| At normal quality settings it may make things worse. |
| |
| -grayscale Force gray-scale output even if JPEG file is color. |
| Useful for viewing on monochrome displays. |
| |
| -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, temporary files will be used. |
| |
| -nodither Do not use dithering in color quantization. |
| By default, Floyd-Steinberg dithering is applied when |
| quantizing colors, but on some images dithering may |
| result in objectionable "graininess". If that |
| happens, you can turn off dithering with -nodither. |
| -nodither is ignored unless you also say -colors N. |
| |
| -onepass Use one-pass instead of two-pass color quantization. |
| The one-pass method is faster and needs less memory, |
| but it produces a lower-quality image. -onepass is |
| ignored unless you also say -colors N. Also, |
| the one-pass method is always used for gray-scale |
| output (the two-pass method is no improvement then). |
| |
| -verbose Enable debug printout. More -v's give more printout. |
| or -debug Also, version information is printed at startup. |
| |
| |
| HINTS |
| |
| Color GIF files are not the ideal input for JPEG; JPEG is really intended for |
| compressing full-color (24-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. |
| |
| When making images to be posted on Usenet, we recommend using cjpeg's option |
| -restart 1. This option limits the damage done to a compressed image by |
| netnews transmission errors. |
| |
| The default memory usage limit (-maxmemory) is set when the software is |
| compiled. If you get an "insufficient memory" error, try specifying a smaller |
| -maxmemory value, even -maxmemory 0 to use the absolute minimum space. You |
| may want to recompile with a smaller default value if this happens often. |
| |
| 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. |
| |
| On MS-DOS machines, -maxmemory is the amount of main (conventional) memory to |
| use. (Extended or expanded memory is also used if available.) Most |
| DOS-specific versions of this software do their own memory space estimation |
| and do not need -maxmemory. |
| |
| djpeg with two-pass color quantization requires a good deal of memory; on |
| MS-DOS machines it may run out of memory even with -maxmemory 0. In that case |
| you can still decompress, with some loss of image quality, by specifying |
| -onepass for one-pass quantization. |
| |
| If more space is needed than will fit in the available main memory (as |
| determined by -maxmemory), temporary files will be used. (MS-DOS versions |
| will try to get extended or expanded memory first.) The temporary files are |
| often rather large: in typical cases they occupy three bytes per pixel, for |
| example 3*800*600 = 1.44Mb for an 800x600 image. If you don't have enough |
| free disk space, leave out -optimize (for cjpeg) or specify -onepass (for |
| djpeg). On MS-DOS, the temporary files are created in the directory named by |
| the TMP or TEMP environment variable, or in the current directory if neither |
| of those exist. Amiga implementations put the temp files in the directory |
| named by JPEGTMP:, so be sure to assign JPEGTMP: to a disk partition with |
| adequate free space. |