+++ /dev/null
-USAGE instructions for the Independent JPEG Group's JPEG software
-=================================================================
-
-This file describes usage of the JPEG conversion programs cjpeg and djpeg,
-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, jpegtran.1, rdjpgcom.1, wrjpgcom.1.
-
-
-INTRODUCTION
-
-These programs implement JPEG image compression and decompression. JPEG
-(pronounced "jay-peg") is a standardized compression method for full-color
-and gray-scale images. JPEG is designed to handle "real-world" scenes,
-for example scanned photographs. Cartoons, line drawings, and other
-non-realistic images are not JPEG's strong suit; on that sort of material
-you may get poor image quality and/or little compression.
-
-JPEG is lossy, meaning that the output image is not necessarily identical to
-the input image. Hence you should not use JPEG if you have to have identical
-output bits. However, on typical real-world images, very good compression
-levels can be obtained with no visible change, and amazingly high compression
-is possible if you can tolerate a low-quality image. You can trade off image
-quality against file size by adjusting the compressor's "quality" setting.
-
-
-GENERAL USAGE
-
-We provide two programs, cjpeg to compress an image file into JPEG format,
-and djpeg to decompress a JPEG file back into a conventional image format.
-
-On Unix-like systems, you say:
- cjpeg [switches] [imagefile] >jpegfile
-or
- djpeg [switches] [jpegfile] >imagefile
-The programs read the specified input file, or standard input if none is
-named. They always write to standard output (with trace/error messages to
-standard error). These conventions are handy for piping images between
-programs.
-
-On most non-Unix systems, you say:
- cjpeg [switches] imagefile jpegfile
-or
- djpeg [switches] jpegfile imagefile
-i.e., both the input and output files are named on the command line. This
-style is a little more foolproof, and it loses no functionality if you don't
-have pipes. (You can get this style on Unix too, if you prefer, by defining
-TWO_FILE_COMMANDLINE when you compile the programs; see install.doc.)
-
-You can also say:
- cjpeg [switches] -outfile jpegfile imagefile
-or
- djpeg [switches] -outfile imagefile jpegfile
-This syntax works on all systems, so it is useful for scripts.
-
-The currently supported image 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.)
-cjpeg recognizes the input image format automatically, with the exception
-of some Targa-format files. You have to tell djpeg which format to generate.
-
-JPEG files are in the defacto standard JFIF file format. There are other,
-less widely used JPEG-based file formats, but we don't support them.
-
-All switch names may be abbreviated; for example, -grayscale may be written
--gray or -gr. Most of the "basic" switches can be abbreviated to as little as
-one letter. Upper and lower case are equivalent (-BMP is the same as -bmp).
-British spellings are also accepted (e.g., -greyscale), though for brevity
-these are not mentioned below.
-
-
-CJPEG DETAILS
-
-The basic command line switches for cjpeg are:
-
- -quality N Scale quantization tables to adjust image quality.
- Quality is 0 (worst) to 100 (best); default is 75.
- (See below for more info.)
-
- -grayscale Create monochrome JPEG file from color input.
- Be sure to use this switch when compressing a grayscale
- BMP file, because cjpeg isn't bright enough to notice
- whether a BMP file uses only shades of gray. By
- saying -grayscale, you'll get a smaller JPEG file that
- takes less time to process.
-
- -optimize Perform optimization of entropy encoding parameters.
- Without this, default encoding parameters are used.
- -optimize usually makes the JPEG file a little smaller,
- but cjpeg runs somewhat slower and needs much more
- 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
- -targa to make cjpeg treat the input as Targa format.
- For most Targa files, you won't need this switch.
-
-The -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 -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 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
-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.
-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:
-
- -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 "B" is attached 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 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, -max 4m selects 4000000 bytes. If more
- space is needed, temporary files will be used.
-
- -verbose Enable debug printout. More -v's give more printout.
- or -debug Also, version information is printed at startup.
-
-The -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 -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.
-
-Switches 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 file 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 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. These switches are documented
-further in the file wizard.doc.
-
-
-DJPEG DETAILS
-
-The basic command line switches for djpeg are:
-
- -colors N Reduce image to at most N colors. This reduces the
- or -quantize N number of colors used in the output image, so that it
- can be displayed on a colormapped display or stored in
- a colormapped file format. For example, if you have
- an 8-bit display, you'd need to reduce to 256 or fewer
- colors. (-colors is the recommended name, -quantize
- is provided only for backwards compatibility.)
-
- -fast Select recommended processing options for fast, low
- quality output. (The default options are chosen for
- highest quality output.) Currently, this is equivalent
- to "-dct fast -nosmooth -onepass -dither ordered".
-
- -grayscale Force gray-scale output even if JPEG file is color.
- Useful for viewing on monochrome displays; also,
- djpeg runs noticeably faster in this mode.
-
- -scale M/N Scale the output image by a factor M/N. Currently
- the scale factor must be 1/1, 1/2, 1/4, or 1/8.
- Scaling is handy if the image is larger than your
- screen; also, djpeg runs much faster when scaling
- down the output.
-
- -bmp Select BMP output format (Windows flavor). 8-bit
- colormapped format is emitted if -colors or -grayscale
- is specified, or if the JPEG file is gray-scale;
- otherwise, 24-bit full-color format is emitted.
-
- -gif Select GIF output format. Since GIF does not support
- more than 256 colors, -colors 256 is assumed (unless
- you specify a smaller number of colors). If you
- specify -fast, the default number of colors is 216.
-
- -os2 Select BMP output format (OS/2 1.x flavor). 8-bit
- colormapped format is emitted if -colors or -grayscale
- is specified, or if the JPEG file is gray-scale;
- otherwise, 24-bit full-color format is emitted.
-
- -pnm Select PBMPLUS (PPM/PGM) output format (this is the
- default format). PGM is emitted if the JPEG file is
- gray-scale or if -grayscale is specified; otherwise
- PPM is emitted.
-
- -rle Select RLE output format. (Requires URT library.)
-
- -targa Select Targa output format. Gray-scale format is
- emitted if the JPEG file is gray-scale or if
- -grayscale is specified; otherwise, colormapped format
- is emitted if -colors is specified; otherwise, 24-bit
- full-color format is emitted.
-
-Switches 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.
-
- -dither fs Use Floyd-Steinberg dithering in color quantization.
- -dither ordered Use ordered dithering in color quantization.
- -dither none Do not use dithering in color quantization.
- By default, Floyd-Steinberg dithering is applied when
- quantizing colors; this is slow but usually produces
- the best results. Ordered dither is a compromise
- between speed and quality; no dithering is fast but
- usually looks awful. Note that these switches have
- no effect unless color quantization is being done.
- Ordered dither is only available in -onepass mode.
-
- -map FILE Quantize to the colors used in the specified image
- file. This is useful for producing multiple files
- with identical color maps, or for forcing a predefined
- set of colors to be used. The FILE must be a GIF
- or PPM file. This option overrides -colors and
- -onepass.
-
- -nosmooth Use a faster, lower-quality upsampling routine.
-
- -onepass Use one-pass instead of two-pass color quantization.
- The one-pass method is faster and needs less memory,
- but it produces a lower-quality image. -onepass is
- ignored unless you also say -colors N. Also,
- the one-pass method is always used for gray-scale
- output (the two-pass method is no improvement then).
-
- -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, -max 4m selects 4000000 bytes. If more
- space is needed, temporary files will be used.
-
- -verbose Enable debug printout. More -v's give more printout.
- or -debug Also, version information is printed at startup.
-
-
-HINTS FOR CJPEG
-
-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 cjpeg's -quality and -smooth options
-to get a satisfactory conversion. -smooth 10 or so is often helpful.
-
-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.
-
-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. (At present, -optimize
-mode is always selected when generating progressive JPEG files.)
-
-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.)
-
-
-HINTS FOR DJPEG
-
-To get a quick preview of an image, use the -grayscale and/or -scale switches.
-"-grayscale -scale 1/8" is the fastest case.
-
-Several options are available that trade off image quality to gain speed.
-"-fast" turns on the recommended settings.
-
-"-dct fast" and/or "-nosmooth" gain speed at a small sacrifice in quality.
-When producing a color-quantized image, "-onepass -dither ordered" is fast but
-much lower quality than the default behavior. "-dither none" may give
-acceptable results in two-pass mode, but is seldom tolerable in one-pass mode.
-
-If you are fortunate enough to have very fast floating point hardware,
-"-dct float" may be even faster than "-dct fast". But on most machines
-"-dct float" is slower than "-dct int"; in this case it is not worth using,
-because its theoretical accuracy advantage is too small to be significant
-in practice.
-
-Two-pass color quantization requires a good deal of memory; on MS-DOS machines
-it may run out of memory even with -maxmemory 0. In that case you can still
-decompress, with some loss of image quality, by specifying -onepass for
-one-pass quantization.
-
-To avoid the Unisys LZW patent, djpeg produces uncompressed GIF files. These
-are larger than they should be, but are readable by standard GIF decoders.
-
-
-HINTS FOR BOTH PROGRAMS
-
-If more space is needed than will fit in the available main memory (as
-determined by -maxmemory), temporary files will be used. (MS-DOS versions
-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 -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
-exist. Amiga implementations put the temp files in the directory named by
-JPEGTMP:, so be sure to assign JPEGTMP: to a disk partition with adequate free
-space.
-
-The default memory usage limit (-maxmemory) is set when the software is
-compiled. If you get an "insufficient memory" error, try specifying a smaller
--maxmemory value, even -maxmemory 0 to use the absolute minimum space. You
-may want to recompile with a smaller default value if this happens often.
-
-On machines that have "environment" variables, you can define the environment
-variable JPEGMEM to set the default memory limit. The value is specified as
-described for the -maxmemory switch. JPEGMEM overrides the default value
-specified when the program was compiled, and itself is overridden by an
-explicit -maxmemory switch.
-
-On MS-DOS machines, -maxmemory is the amount of main (conventional) memory to
-use. (Extended or expanded memory is also used if available.) Most
-DOS-specific versions of this software do their own memory space estimation
-and do not need you to specify -maxmemory.
-
-
-JPEGTRAN
-
-jpegtran performs various useful transformations of JPEG files.
-It can translate the coded representation from one variant of JPEG to another,
-for example from baseline JPEG to progressive JPEG or vice versa. It can also
-perform some rearrangements of the image data, for example turning an image
-from landscape to portrait format by rotation.
-
-jpegtran works by rearranging the compressed data (DCT coefficients), without
-ever fully decoding the image. Therefore, its transformations are lossless:
-there is no image degradation at all, which would not be true if you used
-djpeg followed by cjpeg to accomplish the same conversion. But by the same
-token, jpegtran cannot perform lossy operations such as changing the image
-quality.
-
-jpegtran uses a command line syntax similar to cjpeg or djpeg.
-On Unix-like systems, you say:
- jpegtran [switches] [inputfile] >outputfile
-On most non-Unix systems, you say:
- jpegtran [switches] inputfile outputfile
-where both the input and output files are JPEG files.
-
-To specify the coded JPEG representation used in the output file,
-jpegtran accepts a subset of the switches recognized by cjpeg:
- -optimize Perform optimization of entropy encoding parameters.
- -progressive Create progressive JPEG file.
- -restart N Emit a JPEG restart marker every N MCU rows, or every
- N MCU blocks if "B" is attached to the number.
- -scans file Use the scan script given in the specified text file.
-See the previous discussion of cjpeg for more details about these switches.
-If you specify none of these switches, you get a plain baseline-JPEG output
-file. The quality setting and so forth are determined by the input file.
-
-The image can be losslessly transformed by giving one of these switches:
- -flip horizontal Mirror image horizontally (left-right).
- -flip vertical Mirror image vertically (top-bottom).
- -rotate 90 Rotate image 90 degrees clockwise.
- -rotate 180 Rotate image 180 degrees.
- -rotate 270 Rotate image 270 degrees clockwise (or 90 ccw).
- -transpose Transpose image (across UL-to-LR axis).
- -transverse Transverse transpose (across UR-to-LL axis).
-
-The transpose transformation has no restrictions regarding image dimensions.
-The other transformations operate rather oddly if the image dimensions are not
-a multiple of the iMCU size (usually 8 or 16 pixels), because they can only
-transform complete blocks of DCT coefficient data in the desired way.
-
-jpegtran's default behavior when transforming an odd-size image is designed
-to preserve exact reversibility and mathematical consistency of the
-transformation set. As stated, transpose is able to flip the entire image
-area. Horizontal mirroring leaves any partial iMCU column at the right edge
-untouched, but is able to flip all rows of the image. Similarly, vertical
-mirroring leaves any partial iMCU row at the bottom edge untouched, but is
-able to flip all columns. The other transforms can be built up as sequences
-of transpose and flip operations; for consistency, their actions on edge
-pixels are defined to be the same as the end result of the corresponding
-transpose-and-flip sequence.
-
-For practical use, you may prefer to discard any untransformable edge pixels
-rather than having a strange-looking strip along the right and/or bottom edges
-of a transformed image. To do this, add the -trim switch:
- -trim Drop non-transformable edge blocks.
-Obviously, a transformation with -trim is not reversible, so strictly speaking
-jpegtran with this switch is not lossless. Also, the expected mathematical
-equivalences between the transformations no longer hold. For example,
-"-rot 270 -trim" trims only the bottom edge, but "-rot 90 -trim" followed by
-"-rot 180 -trim" trims both edges.
-
-Another not-strictly-lossless transformation switch is:
- -grayscale Force grayscale output.
-This option discards the chrominance channels if the input image is YCbCr
-(ie, a standard color JPEG), resulting in a grayscale JPEG file. The
-luminance channel is preserved exactly, so this is a better method of reducing
-to grayscale than decompression, conversion, and recompression. This switch
-is particularly handy for fixing a monochrome picture that was mistakenly
-encoded as a color JPEG. (In such a case, the space savings from getting rid
-of the near-empty chroma channels won't be large; but the decoding time for
-a grayscale JPEG is substantially less than that for a color JPEG.)
-
-jpegtran also recognizes these switches that control what to do with "extra"
-markers, such as comment blocks:
- -copy none Copy no extra markers from source file. This setting
- suppresses all comments and other excess baggage
- present in the source file.
- -copy comments Copy only comment markers. This setting copies
- comments from the source file, but discards
- any other inessential data.
- -copy all Copy all extra markers. This setting preserves
- miscellaneous markers found in the source file, such
- as JFIF thumbnails and Photoshop settings. In some
- files these extra markers can be sizable.
-The default behavior is -copy comments. (Note: in IJG releases v6 and v6a,
-jpegtran always did the equivalent of -copy none.)
-
-Additional switches recognized by jpegtran are:
- -outfile filename
- -maxmemory N
- -verbose
- -debug
-These work the same as in cjpeg or djpeg.
-
-
-THE COMMENT UTILITIES
-
-The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file.
-Although the standard doesn't actually define what COM blocks are for, they
-are widely used to hold user-supplied text strings. This lets you add
-annotations, titles, index terms, etc to your JPEG files, and later retrieve
-them as text. COM blocks do not interfere with the image stored in the JPEG
-file. The maximum size of a COM block is 64K, but you can have as many of
-them as you like in one JPEG file.
-
-We provide two utility programs to display COM block contents and add COM
-blocks to a JPEG file.
-
-rdjpgcom searches a JPEG file and prints the contents of any COM blocks on
-standard output. The command line syntax is
- rdjpgcom [-verbose] [inputfilename]
-The switch "-verbose" (or just "-v") causes rdjpgcom to also display the JPEG
-image dimensions. If you omit the input file name from the command line,
-the JPEG file is read from standard input. (This may not work on some
-operating systems, if binary data can't be read from stdin.)
-
-wrjpgcom adds a COM block, containing text you provide, to a JPEG file.
-Ordinarily, the COM block is added after any existing COM blocks, but you
-can delete the old COM blocks if you wish. wrjpgcom produces a new JPEG
-file; it does not modify the input file. DO NOT try to overwrite the input
-file by directing wrjpgcom's output back into it; on most systems this will
-just destroy your file.
-
-The command line syntax for wrjpgcom is similar to cjpeg's. On Unix-like
-systems, it is
- wrjpgcom [switches] [inputfilename]
-The output file is written to standard output. The input file comes from
-the named file, or from standard input if no input file is named.
-
-On most non-Unix systems, the syntax is
- wrjpgcom [switches] inputfilename outputfilename
-where both input and output file names must be given explicitly.
-
-wrjpgcom understands three switches:
- -replace Delete any existing COM blocks from the file.
- -comment "Comment text" Supply new COM text on command line.
- -cfile name Read text for new COM block from named file.
-(Switch names can be abbreviated.) If you have only one line of comment text
-to add, you can provide it on the command line with -comment. The comment
-text must be surrounded with quotes so that it is treated as a single
-argument. Longer comments can be read from a text file.
-
-If you give neither -comment nor -cfile, then wrjpgcom will read the comment
-text from standard input. (In this case an input image file name MUST be
-supplied, so that the source JPEG file comes from somewhere else.) You can
-enter multiple lines, up to 64KB worth. Type an end-of-file indicator
-(usually control-D or control-Z) to terminate the comment text entry.
-
-wrjpgcom will not add a COM block if the provided comment string is empty.
-Therefore -replace -comment "" can be used to delete all COM blocks from a
-file.
-
-These utility programs do not depend on the IJG JPEG library. In
-particular, the source code for rdjpgcom is intended as an illustration of
-the minimum amount of code required to parse a JPEG file header correctly.
projects / synfig.git / blobdiff