af618ffe09
- Rename jpeg_simple_lossless() to jpeg_enable_lossless() and modify the
function so that it stores the lossless parameters directly in the Ss
and Al fields of jpeg_compress_struct rather than using a scan script.
- Move the cjpeg -lossless switch into "Switches for advanced users".
- Document the libjpeg API and run-time features that are unavailable in
lossless mode, and ensure that all parameters, functions, and switches
related to unavailable features are ignored or generate errors in
lossless mode.
- Defer any action that depends on whether lossless mode is enabled
until jpeg_start_compress()/jpeg_start_decompress() is called.
- Document the purpose of the point transform value.
- "Codec" stands for coder/decoder, so it is a bit awkward to say
"lossless compression codec" and "lossless decompression codec".
Use "lossless compressor" and "lossless decompressor" instead.
- Restore backward API/ABI compatibility with libjpeg v6b:
* Move the new 'lossless' field from the exposed jpeg_compress_struct
and jpeg_decompress_struct structures into the opaque
jpeg_comp_master and jpeg_decomp_master structures, and allocate the
master structures in the body of jpeg_create_compress() and
jpeg_create_decompress().
* Remove the new 'process' field from jpeg_compress_struct and
jpeg_decompress_struct and replace it with the old
'progressive_mode' field and the new 'lossless' field.
* Remove the new 'data_unit' field from jpeg_compress_struct and
jpeg_decompress_struct and replace it with a locally-computed
data unit variable.
* Restore the names of macros and fields that refer to DCT blocks, and
document that they have a different meaning in lossless mode. (Most
of them aren't very meaningful in lossless mode anyhow.)
* Remove the new alloc_darray() method from jpeg_memory_mgr and
replace it with an internal macro that wraps the alloc_sarray()
method.
* Move the JDIFF* data types from jpeglib.h and jmorecfg.h into
jpegint.h.
* Remove the new 'codec' field from jpeg_compress_struct and
jpeg_decompress_struct and instead reuse the existing internal
coefficient control, forward/inverse DCT, and entropy
encoding/decoding structures for lossless compression/decompression.
* Repurpose existing error codes rather than introducing new ones.
(The new JERR_BAD_RESTART and JWRN_MUST_DOWNSCALE codes remain,
although JWRN_MUST_DOWNSCALE will probably be removed in
libjpeg-turbo, since we have a different way of handling multiple
data precisions.)
- Automatically enable lossless mode when a scan script with parameters
that are only valid for lossless mode is detected, and document the
use of scan scripts to generate lossless JPEG images.
- Move the sequential and shared Huffman routines back into jchuff.c and
jdhuff.c, and document that those routines are shared with jclhuff.c
and jdlhuff.c as well as with jcphuff.c and jdphuff.c.
- Move MAX_DIFF_BITS from jchuff.h into jclhuff.c, the only place where
it is used.
- Move the predictor and scaler code into jclossls.c and jdlossls.c.
- Streamline register usage in the [un]differencers (inspired by similar
optimizations in the color [de]converters.)
- Restructure the logic in a few places to reduce duplicated code.
- Ensure that all lossless-specific code is guarded by
C_LOSSLESS_SUPPORTED or D_LOSSLESS_SUPPORTED and that the library can
be built successfully if either or both of those macros is undefined.
- Remove all short forms of external names introduced by the lossless
JPEG patch. (These will not be needed by libjpeg-turbo, so there is
no use cleaning them up.)
- Various wordsmithing, formatting, and punctuation tweaks
- Eliminate various compiler warnings.
330 lines
11 KiB
Groff
330 lines
11 KiB
Groff
.TH CJPEG 1 "11 November 2022"
|
|
.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
|
|
.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 \-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.
|
|
.B Caution:
|
|
progressive JPEG is not yet widely implemented, so many decoders will be
|
|
unable to view a progressive JPEG file at all.
|
|
.PP
|
|
Switches for advanced users:
|
|
.TP
|
|
.BI \-lossless " psv[,Pt]"
|
|
Create a lossless JPEG file using the specified predictor selection value
|
|
(1 through 7) and optional point transform (0 through
|
|
.nh
|
|
.I precision
|
|
.hy
|
|
- 1, where
|
|
.nh
|
|
.I precision
|
|
.hy
|
|
is the JPEG data precision in bits). A point transform value of 0 (the
|
|
default) is necessary in order to create a fully lossless JPEG file. (A
|
|
non-zero point transform value right-shifts the input samples by the specified
|
|
number of bits, which is effectively a form of lossy color quantization.)
|
|
.B Caution:
|
|
lossless JPEG is not yet widely implemented, so many decoders will be unable to
|
|
view a lossless JPEG file at all. Note that the following features will be
|
|
unavailable when compressing or decompressing a lossless JPEG file:
|
|
.IP
|
|
- Quality/quantization table selection
|
|
.IP
|
|
- Color conversion (the JPEG image will use the same color space as the input
|
|
image)
|
|
.IP
|
|
- DCT/IDCT algorithm selection
|
|
.IP
|
|
- Smoothing
|
|
.IP
|
|
- Downsampling/upsampling
|
|
.IP
|
|
- IDCT scaling
|
|
.IP
|
|
- Transformations using
|
|
.B jpegtran
|
|
.IP
|
|
Any switches used to enable or configure those features will be ignored.
|
|
.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
|
|
.BI \-restart " N"
|
|
Emit a JPEG restart marker every N MCU rows, or every N MCU blocks (samples in
|
|
lossless mode) 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 \-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.doc.
|
|
.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
|
|
Arithmetic coding is not supported for legal reasons.
|
|
.PP
|
|
GIF input files are no longer supported, to avoid the Unisys LZW patent.
|
|
Use a Unisys-licensed program if you need to read a GIF file. (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.)
|
|
.PP
|
|
Still not as fast as we'd like.
|