ppmtojpeg - convert portable pixmap into a JPEG/JFIF file
SYNOPSIS
ppmtojpeg [ options ] [ filename ]
DESCRIPTION
ppmtojpeg converts the named PPM image file, or the stan
dard input if no file is named, to a JPEG/JFIF file on the
standard output. It also takes PGM and PBM files as
input, by "promoting" them to PPM files before processing.
ppmtojpeg uses the Independent JPEG Group's JPEG library
to create the output file. See http://www.ijg.org for
information on the library.
OPTIONS
The basic options are:
--quality=n
Scale quantization tables to adjust image quality.
n is 0 (worst) to 100 (best); default is 75. (See
below for more info.)
--grayscale
--greyscale
Create gray scale JPEG/JFIF file. With this
option, ppmtojpeg converts color input to gray
scale. If you don't specify this option, even if
your input contains nothing but grays, and even if
your input file is a PBM or PGM file, the output
file is in color format. Of course, the colors in
it are still gray. The difference is that color
format takes up a lot more space and takes longer
to create and process.
--optimize
Perform optimization of entropy encoding parame
ters. Without this, ppmtojpeg uses default encod
ing parameters. --optimize usually makes the JPEG
file a little smaller, but ppmtojpeg runs somewhat
slower and needs much more memory. Image quality
and speed of decompression are unaffected by
--optimize.
--progressive
Create a progressive JPEG file (see below).
--comment=text
Include a comment marker in the JPEG output, with
comment text text. Without this option, there are
The --quality option 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 pur
pose the quality setting should be between 50 and 95; the
default of 75 is often about right. If you see defects at
--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.)
--quality=100 generates 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 experimen
tal purposes. Quality values above about 95 are not rec
ommended for normal use; the compressed file size goes up
dramatically for hardly any gain in output image quality.
In the other direction, quality values below 50 will pro
duce 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 --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. ppmtojpeg
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 option 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 equiva
lent to a standard JPEG file of the same quality setting,
and the total file size is about the same -- often a lit
tle smaller. Caution: progressive JPEG is not yet widely
implemented, so many decoders will be unable to view a
progressive JPEG file at all.
Options for advanced users:
--dct=int
Use integer DCT method (default).
Use fast integer DCT (less accurate).
--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.
--restart=n
Emit a JPEG restart marker every n MCU rows, or
every n MCU blocks if you append B to the number.
--restart 0 (the default) means no restart markers.
--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.
--maxmemory=n
Set a limit for amount of memory to use in process
ing large images. Value is in thousands of bytes,
or millions of bytes if you append M to the number.
For example, --max=4m selects 4,000,000 bytes. If
ppmtojpeg needs more space, it will use temporary
files.
--verbose
Print to the Standard Error file messages about the
conversion process. This can be helpful in debug
ging problems.
The --restart option tells ppmtojpeg to insert extra mark
ers 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
--restart=1 for images that will be transmitted across
unreliable networks such as Usenet.
The --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, however.
Options for wizards:
--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 --baseline and --progressive together.)
--qtables=filespec
Use the quantization tables given in the specified
text file.
--qslots=n[,...]
Select which quantization table to use for each
color component.
--sample=HxV[,...]
Set JPEG sampling factors for each color component.
--scans=filespec
Use the scan script given in the specified text
file. See below for information on scan scripts.
The "wizard" options are intended for experimentation with
JPEG. If you don't know what you are doing, don't use
them. These switches are documented further in the file
wizard.doc that comes with the Independent JPEG Group's
JPEG library.
EXAMPLES
This example compresses the PPM file foo.ppm with a qual
ity factor of 60 and saves the output as foo.jpg:
ppmtojpeg --quality=60 foo.ppm > foo.jpg
cat foo.bmp | bmptoppm | ppmtojpeg > foo.jpg
HINTS
JPEG is not ideal for cartoons, line drawings, and other
images that have only a few distinct colors. For those,
try instead pnmtopng or ppmtobmp. If you need to convert
such an image to JPEG, though, you should experiment with
ppmtojpeg's --quality and --smooth options to get a satis
factory conversion. --smooth 10 or so is often helpful.
JPEG compression is notable for being a "lossy." This
means that, unlike with most graphics conversions, you
lose information, which means image quality, when you
repeatedly, image quality loss will accumulate. After ten
or so cycles the image may be noticeably worse than it was
after one cycle.
Because of this, you should do all the manipulation you
have to do on the image in some other format and convert
to JPEG as the last step. And if you can keep a copy in
the original format, so much the better. PNG is a good
choice for a format that is lossless, yet fairly compact.
GIF is another way to go, but chances are you can't create
a GIF image without owing a lot of money to Unisys and
IBM, holders of patents on the LZW compression used in the
GIF format.
The --optimize option to ppmtojpeg 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,
--optimize mode is automatically in effect when you gener
ate a progressive JPEG file).
Another program, cjpeg, is similar. cjpeg is maintained
by the Independent JPEG Group and packaged with the JPEG
library which ppmtojpeg uses for all its JPEG work.
Because of that, you may expect it to exploit more current
JPEG features. Also, since you have to have the library
to run ppmtojpeg, but not vice versa, cjpeg may be more
commonly available.
On the other hand, cjpeg does not use the NetPBM libraries
to process its input, as all the NetPBM tools such as ppm
tojpeg do. This means it is less likely to be consistent
with all the other programs that deal with the NetPBM for
mats. Also, the command syntax of ppmtojpeg is consistent
with that of the other Netpbm tools, unlike cjpeg.
SCAN SCRIPTS
Use the -scan option to specify a scan script. Or use the
-progressive option to specify a particular built-in scan
script.
Just what a scan script is, and the basic format of the
scan script file, is covered in the wizard.doc file that
comes with the Independent JPEG Group's JPEG library.
Scan scripts are same for ppmjpeg as the are for cjpeg.
This section contains additional information that isn't,
but probably should be, in that document.
First, there are many restrictions on what is a valid scan
script. The JPEG library, and thus ppmtojpeg, checks
tions, but does little to tell you how the script fails to
comply. The messages are very general and sometimes
untrue.
To start with, the entries for the DC coefficient must
come before any entries for the AC coefficients. The DC
coefficient is Coefficient 0; all the other coefficients
are AC coefficients. So In an entry for the DC coeffi
cient, the two numbers after the colon must be 0 and 0.
In an entry for AC coefficients, the first number after
the colon must not be 0.
In a DC entry, the color components must be in increasing
order. E.g. "0,2,1" before the colon is wrong. So is
"0,0,0".
In an entry for an AC coeffient, you must specify only one
color component. I.e. there can be only one number before
the colon.
In the first entry for a particular coefficient for a par
ticular color component, the "Ah" value must be zero, but
the Al value can be any valid bit number. In subsequent
entries, Ah must be the Al value from the previous entry
(for that coefficient for that color component), and the
Al value must be one less than the Ah value.
The script must ultimately specify at least some of the DC
coefficent for every color component. Otherwise, you get
the error message "Script does not transmit all the data."
You need not specify all of the bits of the DC coeffi
cient, or any of the AC coefficients.
There is a standard option in building the JPEG library to
omit scan script capability. If for some reason your
library was built with this option, you get the message
"Requested feature was omitted at compile time."
ENVIRONMENT
JPEGMEM
If this environment variable is set, its value is
the default memory limit. The value is specified
as described for the --maxmemory option. An
explicit --maxmemory option overrides any JPEGMEM.
SEE ALSO
cjpeg(1), djpeg(1), jpegtran(1), rdjpgcom(1), wrjpgcom(1)
ppm(5), pgm(5), jpegtopnm(1)
Wallace, Gregory K. "The JPEG Still Picture Compression
Standard", Communications of the ACM, April 1991 (vol. 34,
no. 4), pp. 30-44.
Arithmetic coding is not supported for legal reasons.
The program could be much faster.
AUTHOR
ppmtojpeg and this man page were derived in large part
from cjpeg, by the Independent JPEG Group. The program is
otherwise by Bryan Henderson on March 07, 2000.
Man(1) output converted with
man2html