The Independent JPEG Group's JPEG software v6
diff --git a/usage.doc b/usage.doc
index ceb8528..49f3d7f 100644
--- a/usage.doc
+++ b/usage.doc
@@ -2,12 +2,12 @@
=================================================================
This file describes usage of the JPEG conversion programs cjpeg and djpeg,
-as well as the utility programs rdjpgcom and wrjpgcom. (See the other
-documentation files if you wish to use the JPEG library within your own
-programs.)
+as well as the utility programs jpegtran, rdjpgcom and wrjpgcom. (See
+the other documentation files if you wish to use the JPEG library within
+your own programs.)
If you are on a Unix machine you may prefer to read the Unix-style manual
-pages in files cjpeg.1, djpeg.1, rdjpgcom.1, wrjpgcom.1.
+pages in files cjpeg.1, djpeg.1, jpegtran.1, rdjpgcom.1, wrjpgcom.1.
INTRODUCTION
@@ -94,6 +94,8 @@
memory. Image quality and speed of decompression are
unaffected by -optimize.
+ -progressive Create progressive JPEG file (see below).
+
-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
@@ -110,7 +112,7 @@
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
+-quality 100 will generate a quantization table of all 1's, minimizing 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
@@ -122,9 +124,19 @@
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.
-Use -baseline if you need to ensure compatibility at low quality values.)
+cjpeg emits a warning message when you give such a quality value, because some
+other JPEG programs may be unable to decode the resulting file. Use -baseline
+if you need to ensure compatibility at low quality values.)
+
+The -progressive switch creates a "progressive JPEG" file. In this type of
+JPEG file, the data is stored in multiple scans of increasing quality. If the
+file is being transmitted over a slow communications link, the decoder can use
+the first scan to display a low-quality image very quickly, and can then
+improve the display with each subsequent scan. The final image is exactly
+equivalent to a standard JPEG file of the same quality setting, and the total
+file size is about the same --- often a little smaller. CAUTION: progressive
+JPEG is not yet widely implemented, so many decoders will be unable to view a
+progressive JPEG file at all.
Switches for advanced users:
@@ -172,38 +184,23 @@
Switches for wizards:
- -arithmetic Use arithmetic coding rather than Huffman coding.
- (Not currently supported for legal reasons.)
-
-baseline Force a baseline JPEG file to be generated. This
clamps quantization values to 8 bits even at low
quality settings.
- -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.
+ text file.
-qslots N[,...] Select which quantization table to use for each color
- component. By default, table 0 is used for luminance
- and table 1 for chrominance components.
+ component.
- -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".
+ -sample HxV[,...] Set JPEG sampling factors for each color component.
+
+ -scans file Use the scan script given in the specified text file.
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.
+don't know what you are doing, DON'T USE THEM. These switches are documented
+further in the file wizard.doc.
DJPEG DETAILS
@@ -329,7 +326,8 @@
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.
+is often a lot more than it is on larger files. (At present, -optimize
+mode is always selected when generating progressive JPEG files.)
HINTS FOR DJPEG
@@ -364,8 +362,8 @@
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).
+free disk space, leave out -progressive and -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
@@ -390,6 +388,31 @@
and do not need you to specify -maxmemory.
+JPEGTRAN
+
+jpegtran translates JPEG files from one variant of JPEG to another, for
+example from baseline JPEG to progressive JPEG or vice versa. The
+transformation is lossless: no image degradation occurs, which would not
+be true if you used djpeg followed by cjpeg. However, you cannot alter
+the image quality, because that would not be a lossless operation.
+
+jpegtran operates similarly to cjpeg, except that it reads a JPEG file
+and writes another JPEG file.
+
+jpegtran accepts a subset of the switches recognized by cjpeg:
+ -outfile filename
+ -optimize
+ -progressive
+ -restart N
+ -scans file
+ -maxmemory N
+ -verbose
+ -debug
+See the previous discussion of cjpeg for details about these switches.
+
+If you specify no switches, you get a plain baseline-JPEG output file.
+
+
THE COMMENT UTILITIES
The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file.