.TH CJPEG 1 "30 December 2009"+
−
.SH NAME+
−
cjpeg \- compress an image file to a JPEG file+
−
.SH SYNOPSIS+
−
.B cjpeg+
−
[+
−
.I options+
−
]+
−
[+
−
.I filename+
−
]+
−
.LP+
−
.SH DESCRIPTION+
−
.LP+
−
.B cjpeg+
−
compresses the named image file, or the standard input if no file is+
−
named, and produces a JPEG/JFIF file on the standard output.+
−
The currently supported input file formats are: PPM (PBMPLUS color+
−
format), PGM (PBMPLUS gray-scale format), BMP, Targa, and RLE (Utah Raster+
−
Toolkit format).  (RLE is supported only if the URT library is available.)+
−
.SH OPTIONS+
−
All switch names may be abbreviated; for example,+
−
.B \-grayscale+
−
may be written+
−
.B \-gray+
−
or+
−
.BR \-gr .+
−
Most of the "basic" switches can be abbreviated to as little as one letter.+
−
Upper and lower case are equivalent (thus+
−
.B \-BMP+
−
is the same as+
−
.BR \-bmp ).+
−
British spellings are also accepted (e.g.,+
−
.BR \-greyscale ),+
−
though for brevity these are not mentioned below.+
−
.PP+
−
The basic switches are:+
−
.TP+
−
.BI \-quality " N[,...]"+
−
Scale quantization tables to adjust image quality.  Quality is 0 (worst) to+
−
100 (best); default is 75.  (See below for more info.)+
−
.TP+
−
.B \-grayscale+
−
Create monochrome JPEG file from color input.  Be sure to use this switch when+
−
compressing a grayscale BMP file, because+
−
.B cjpeg+
−
isn't bright enough to notice whether a BMP file uses only shades of gray.+
−
By saying+
−
.BR \-grayscale ,+
−
you'll get a smaller JPEG file that takes less time to process.+
−
.TP+
−
.B \-optimize+
−
Perform optimization of entropy encoding parameters.  Without this, default+
−
encoding parameters are used.+
−
.B \-optimize+
−
usually makes the JPEG file a little smaller, but+
−
.B cjpeg+
−
runs somewhat slower and needs much more memory.  Image quality and speed of+
−
decompression are unaffected by+
−
.BR \-optimize .+
−
.TP+
−
.B \-progressive+
−
Create progressive JPEG file (see below).+
−
.TP+
−
.BI \-scale " M/N"+
−
Scale the output image by a factor M/N.  Currently supported scale factors are+
−
8/N with all N from 1 to 16.+
−
.TP+
−
.B \-targa+
−
Input file is Targa format.  Targa files that contain an "identification"+
−
field will not be automatically recognized by+
−
.BR cjpeg ;+
−
for such files you must specify+
−
.B \-targa+
−
to make+
−
.B cjpeg+
−
treat the input as Targa format.+
−
For most Targa files, you won't need this switch.+
−
.PP+
−
The+
−
.B \-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+
−
.B \-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.)+
−
.PP+
−
.B \-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+
−
.B not+
−
recommended for normal use; the compressed file size goes up dramatically for+
−
hardly any gain in output image quality.+
−
.PP+
−
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+
−
.B \-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.+
−
.B 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+
−
.B \-baseline+
−
if you need to ensure compatibility at low quality values.)+
−
.PP+
−
The+
−
.B \-quality+
−
option has been extended in IJG version 7 for support of separate quality+
−
settings for luminance and chrominance (or in general, for every provided+
−
quantization table slot).  This feature is useful for high-quality+
−
applications which cannot accept the damage of color data by coarse+
−
subsampling settings.  You can now easily reduce the color data amount more+
−
smoothly with finer control without separate subsampling.  The resulting file+
−
is fully compliant with standard JPEG decoders.+
−
Note that the+
−
.B \-quality+
−
ratings refer to the quantization table slots, and that the last value is+
−
replicated if there are more q-table slots than parameters.  The default+
−
q-table slots are 0 for luminance and 1 for chrominance with default tables as+
−
given in the JPEG standard.  This is compatible with the old behaviour in case+
−
that only one parameter is given, which is then used for both luminance and+
−
chrominance (slots 0 and 1).  More or custom quantization tables can be set+
−
with+
−
.B \-qtables+
−
and assigned to components with+
−
.B \-qslots+
−
parameter (see the "wizard" switches below).+
−
.B Caution:+
−
You must explicitly add+
−
.BI \-sample " 1x1"+
−
for efficient separate color+
−
quality selection, since the default value used by library is 2x2!+
−
.PP+
−
The+
−
.B \-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.+
−
.PP+
−
Switches for advanced users:+
−
.TP+
−
.B \-dct int+
−
Use integer DCT method (default).+
−
.TP+
−
.B \-dct fast+
−
Use fast integer DCT (less accurate).+
−
.TP+
−
.B \-dct float+
−
Use floating-point DCT method.+
−
The float method is very slightly more accurate than the int method, but is+
−
much slower unless your machine has very fast floating-point hardware.  Also+
−
note that results of the floating-point method may vary slightly across+
−
machines, while the integer methods should give the same results everywhere.+
−
The fast integer method is much less accurate than the other two.+
−
.TP+
−
.B \-nosmooth+
−
Don't use high-quality downsampling.+
−
.TP+
−
.BI \-restart " N"+
−
Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is+
−
attached to the number.+
−
.B \-restart 0+
−
(the default) means no restart markers.+
−
.TP+
−
.BI \-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.+
−
.TP+
−
.BI \-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,+
−
.B \-max 4m+
−
selects 4000000 bytes.  If more space is needed, temporary files will be used.+
−
.TP+
−
.BI \-outfile " name"+
−
Send output image to the named file, not to standard output.+
−
.TP+
−
.B \-verbose+
−
Enable debug printout.  More+
−
.BR \-v 's+
−
give more output.  Also, version information is printed at startup.+
−
.TP+
−
.B \-debug+
−
Same as+
−
.BR \-verbose .+
−
.PP+
−
The+
−
.B \-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+
−
.B \-restart 1+
−
for images that will be transmitted across unreliable networks such as Usenet.+
−
.PP+
−
The+
−
.B \-smooth+
−
option filters the input to eliminate fine-scale noise.  This is often useful+
−
when converting dithered images 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.+
−
.PP+
−
Switches for wizards:+
−
.TP+
−
.B \-arithmetic+
−
Use arithmetic coding.+
−
.B Caution:+
−
arithmetic coded JPEG is not yet widely implemented, so many decoders will be+
−
unable to view an arithmetic coded JPEG file at all.+
−
.TP+
−
.B \-baseline+
−
Force baseline-compatible quantization tables to be generated.  This clamps+
−
quantization values to 8 bits even at low quality settings.  (This switch is+
−
poorly named, since it does not ensure that the output is actually baseline+
−
JPEG.  For example, you can use+
−
.B \-baseline+
−
and+
−
.B \-progressive+
−
together.)+
−
.TP+
−
.BI \-qtables " file"+
−
Use the quantization tables given in the specified text file.+
−
.TP+
−
.BI \-qslots " N[,...]"+
−
Select which quantization table to use for each color component.+
−
.TP+
−
.BI \-sample " HxV[,...]"+
−
Set JPEG sampling factors for each color component.+
−
.TP+
−
.BI \-scans " file"+
−
Use the scan script given in the specified text file.+
−
.PP+
−
The "wizard" switches are intended for experimentation with JPEG.  If you+
−
don't know what you are doing, \fBdon't use them\fR.  These switches are+
−
documented further in the file wizard.txt.+
−
.SH EXAMPLES+
−
.LP+
−
This example compresses the PPM file foo.ppm with a quality factor of+
−
60 and saves the output as foo.jpg:+
−
.IP+
−
.B cjpeg \-quality+
−
.I 60 foo.ppm+
−
.B >+
−
.I foo.jpg+
−
.SH 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+
−
.BR cjpeg 's+
−
.B \-quality+
−
and+
−
.B \-smooth+
−
options to get a satisfactory conversion.+
−
.B \-smooth 10+
−
or so is often helpful.+
−
.PP+
−
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.+
−
.PP+
−
The+
−
.B \-optimize+
−
option to+
−
.B 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.  (At present,+
−
.B \-optimize+
−
mode is always selected when generating progressive JPEG files.)+
−
.SH ENVIRONMENT+
−
.TP+
−
.B JPEGMEM+
−
If this environment variable is set, its value is the default memory limit.+
−
The value is specified as described for the+
−
.B \-maxmemory+
−
switch.+
−
.B JPEGMEM+
−
overrides the default value specified when the program was compiled, and+
−
itself is overridden by an explicit+
−
.BR \-maxmemory .+
−
.SH SEE ALSO+
−
.BR djpeg (1),+
−
.BR jpegtran (1),+
−
.BR rdjpgcom (1),+
−
.BR wrjpgcom (1)+
−
.br+
−
.BR ppm (5),+
−
.BR pgm (5)+
−
.br+
−
Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",+
−
Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.+
−
.SH AUTHOR+
−
Independent JPEG Group+
−
.SH BUGS+
−
GIF input files are no longer supported, to avoid the Unisys LZW patent.+
−
(Conversion of GIF files to JPEG is usually a bad idea anyway.)+
−
.PP+
−
Not all variants of BMP and Targa file formats are supported.+
−
.PP+
−
The+
−
.B \-targa+
−
switch is not a bug, it's a feature.  (It would be a bug if the Targa format+
−
designers had not been clueless.)+
−