PPMTOJPEG(1)

NAME
ppmtojpeg - convert portable pixmap into a JPEG/JFIF file

SYNOPSIS
ppmtojpeg [ options ] [ filename ]

DESCRIPTION

ppmtojpeg converts the named PPM image file, or the standard 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 parameters. Without this, ppmtojpeg uses default encoding 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).

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 purpose 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 experimental purposes. Quality values above about 95 are not recommended 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 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 --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 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.

Options for advanced users:

--dct=int
    Use integer DCT method (default).

--dct=fast
    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 processing 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 debugging problems.

The --restart option tells ppmtojpeg to insert 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 --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. Too large a smoothing factor will visibly blur the 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.

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 quality 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 satisfactory 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 convert to JPEG. If you convert from PPM to JPEG and back 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 generate 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 ppmtojpeg do. This means it is less likely to be consistent with all the other programs that deal with the NetPBM formats. Also, the command syntax of ppmtojpeg is consistent with that of the other Netpbm tools, unlike cjpeg.

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.

LIMITATIONS
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.