| 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. |
| |
| NOTE: at some point we will probably redesign the user interface, so the |
| command line switches described here will change. |
| |
| |
| 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.) |
| |
| 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/JPEG format will probably be added at some future date. |
| |
| |
| CJPEG DETAILS |
| |
| The command line switches for cjpeg are: |
| |
| -Q quality Scale quantization tables to adjust image quality. |
| Quality is 0 (worst) to 100 (best); default is 75. |
| (See below for more info.) |
| |
| -o Perform optimization of entropy encoding parameters. |
| Without this, default encoding parameters are used. |
| -o 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 -o. |
| |
| -T 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 |
| -T to force cjpeg to treat the input as Targa format. |
| |
| -I Generate noninterleaved JPEG file (not yet supported). |
| |
| -a Use arithmetic coding rather than Huffman coding. |
| (Not currently supported for legal reasons.) |
| |
| -d Enable debug printout. More -d's give more printout. |
| Also, version information is printed at startup. |
| |
| -m memory 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, -m 4m selects 4000000 bytes. If more |
| space is needed, temporary files will be used. |
| |
| The -Q switch lets you trade off compressed file size against quality of the |
| reconstructed image: the higher the -Q 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 -Q setting (smallest file) that decompresses into something |
| visually indistinguishable from the original image. For this purpose the -Q |
| setting should be between 50 and 95; the default of 75 is often about right. |
| If you see defects at -Q 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.) |
| |
| -Q 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. -Q 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, -Q 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 -Q 2 (or so) for some |
| amusing Cubist effects. (Note: -Q 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 -Q value, because some |
| commercial JPEG programs may be unable to decode the resulting file.) |
| |
| |
| DJPEG DETAILS |
| |
| The command line switches for djpeg are: |
| |
| -G Select GIF output format (implies -q, with default |
| of 256 colors). |
| |
| -P Select PPM or PGM output format (this is the default). |
| PGM is emitted if the JPEG file is gray-scale or if -g |
| is specified. |
| |
| -R Select RLE output format. Requires URT library. |
| |
| -T Select Targa output format. Gray-scale format is |
| emitted if the JPEG file is gray-scale or if -g is |
| specified; otherwise, colormapped format is emitted |
| if -q is specified; otherwise, 24-bit full-color |
| format is emitted. |
| |
| -g Force gray-scale output even if input is color. |
| |
| -q N Quantize to N colors. This reduces the number of |
| colors 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 quantize to 256 or fewer colors. |
| |
| -D 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 -D. |
| -D is ignored unless you also say -q or -G. |
| |
| -1 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. |
| -1 is ignored unless you also say -q or -G. Also, |
| the one-pass method is always used for gray-scale |
| output (the two-pass method is no improvement then). |
| |
| -b Perform cross-block smoothing. This is quite |
| memory-intensive and only seems to improve the image |
| at very low quality settings (-Q 10 to 20 or so). |
| At normal -Q settings it may make the image worse. |
| |
| -d Enable debug printout. More -d's give more printout. |
| Also, version information is printed at startup. |
| |
| -m memory 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, -m 4m selects 4000000 bytes. If more |
| space is needed, temporary files will be used. |
| |
| |
| HINTS |
| |
| 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 -o 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 -Q settings |
| to make very small JPEG files; the percentage improvement is often a lot more |
| than it is on larger files. |
| |
| The default memory usage limit (-m) is set when the software is compiled. |
| If you get an "insufficient memory" error, try specifying a smaller -m value, |
| even -m 0 to use the absolute minimum space. You may want to recompile with |
| a smaller default value if this happens often. |
| |
| djpeg with two-pass color quantization requires a good deal of space; on |
| MS-DOS machines it may run out of memory even with -m 0. In that case you |
| can still decompress, with some loss of image quality, by specifying -1 |
| for one-pass quantization. |
| |
| If more space is needed than will fit in the available main memory (as |
| determined by -m), 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 -o (for cjpeg) or specify -1 (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. |