JPEGView/Independent JPEG Group/usage.doc

USAGE instructions for the Independent JPEG Group's JPEG software
=================================================================

This file describes usage of the JPEG conversion programs "cjpeg" and "djpeg".
(See the other documentation files if you wish to use the JPEG library within
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.


INTRODUCTION

These programs 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.


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 install.doc.)

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.

JPEG files are in the defacto standard JFIF file format.  There are other,
less widely used JPEG-based file formats, but we don't support them.

All switch names may be abbreviated; for example, -grayscale may be written
-gray or -gr.  Most of the "basic" switches can be abbreviated to as little as
one letter.  Upper and lower case are equivalent (-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