| .TH DJPEG 1 "17 June 2024" |
| .SH NAME |
| djpeg \- decompress a JPEG file to an image file |
| .SH SYNOPSIS |
| .B djpeg |
| [ |
| .I options |
| ] |
| [ |
| .I filename |
| ] |
| .LP |
| .SH DESCRIPTION |
| .LP |
| .B djpeg |
| decompresses the named JPEG file, or the standard input if no file is named, |
| and produces an image file on the standard output. PBMPLUS (PPM/PGM), BMP, |
| GIF, or Targa output format can be selected. |
| .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 \-colors " N" |
| Reduce image to at most N colors [legacy feature]. This reduces the number of |
| colors used in the output image so that it can be stored in a colormapped file |
| format. This feature cannot be used when decompressing lossless JPEG images. |
| .TP |
| .BI \-quantize " N" |
| Same as |
| .BR \-colors . |
| .B \-colors |
| is the recommended name. |
| .B \-quantize |
| is provided only for backward compatibility. |
| .TP |
| .B \-fast |
| Select recommended processing options for low-quality output [legacy feature]. |
| (The default options are chosen for highest-quality output.) Currently, this |
| is equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR. On |
| modern CPUs, these settings have little or no performance benefit and are |
| retained solely for backward compatibility. |
| .TP |
| .B \-grayscale |
| Force grayscale output even if JPEG file is full-color. This feature cannot be |
| used when decompressing full-color lossless JPEG images. |
| .TP |
| .B \-rgb |
| Force RGB output even if JPEG file is grayscale. This feature cannot be used |
| when decompressing grayscale lossless JPEG images. |
| .TP |
| .BI \-scale " M/N" |
| Scale the output image by a factor M/N. Currently the scale factor must be |
| M/8, where M is an integer between 1 and 16 inclusive, or any reduced fraction |
| thereof (such as 1/2, 3/4, etc.) Scaling is handy if the image is larger than |
| your screen. This feature cannot be used when decompressing lossless JPEG |
| images. |
| .TP |
| .B \-bmp |
| Select BMP output format (Windows flavor). 8-bit colormapped format is |
| emitted if |
| .B \-colors |
| or |
| .B \-grayscale |
| is specified, or if the JPEG file is grayscale; otherwise, 24-bit full-color |
| format is emitted. This format can only be used when decompressing |
| 8-bit-per-sample JPEG images. |
| .TP |
| .B \-gif |
| Select GIF output format (LZW-compressed) [legacy feature]. Since GIF does not |
| support more than 256 colors, |
| .B \-colors 256 |
| is assumed (unless you specify a smaller number of colors). If you specify |
| .BR \-fast, |
| the default number of colors is 216. This format can only be used when |
| decompressing 8-bit-per-sample or 12-bit-per-sample lossy JPEG images. |
| .TP |
| .B \-gif0 |
| Select GIF output format (uncompressed) [legacy feature]. Since GIF does not |
| support more than 256 colors, |
| .B \-colors 256 |
| is assumed (unless you specify a smaller number of colors). If you specify |
| .BR \-fast, |
| the default number of colors is 216. This format can only be used when |
| decompressing 8-bit-per-sample or 12-bit-per-sample lossy JPEG images. |
| .TP |
| .B \-os2 |
| Select BMP output format (OS/2 1.x flavor) [legacy feature]. 8-bit colormapped |
| format is emitted if |
| .B \-colors |
| or |
| .B \-grayscale |
| is specified, or if the JPEG file is grayscale; otherwise, 24-bit full-color |
| format is emitted. This format can only be used when decompressing |
| 8-bit-per-sample JPEG images. |
| .TP |
| .B \-pnm |
| Select PBMPLUS (PPM/PGM) output format (this is the default format). |
| PGM is emitted if the JPEG file is grayscale or if |
| .B \-grayscale |
| is specified; otherwise PPM is emitted. |
| .TP |
| .B \-targa |
| Select Targa output format [legacy feature]. Grayscale format is emitted if |
| the JPEG file is grayscale or if |
| .B \-grayscale |
| is specified; otherwise, colormapped format is emitted if |
| .B \-colors |
| is specified; otherwise, 24-bit full-color format is emitted. This format can |
| only be used when decompressing 8-bit-per-sample JPEG images. |
| .PP |
| Switches for advanced users: |
| .TP |
| .B \-dct int |
| Use accurate integer DCT method (default). |
| .TP |
| .B \-dct fast |
| Use less accurate integer DCT method [legacy feature]. |
| When the Independent JPEG Group's software was first released in 1991, the |
| decompression time for a 1-megapixel JPEG image on a mainstream PC was measured |
| in minutes. Thus, the \fBfast\fR integer DCT algorithm provided noticeable |
| performance benefits. On modern CPUs running libjpeg-turbo, however, the |
| decompression time for a 1-megapixel JPEG image is measured in milliseconds, |
| and thus the performance benefits of the \fBfast\fR algorithm are much less |
| noticeable. On modern x86/x86-64 CPUs that support AVX2 instructions, the |
| \fBfast\fR and \fBint\fR methods have similar performance. On other types of |
| CPUs, the \fBfast\fR method is generally about 5-15% faster than the \fBint\fR |
| method. |
| |
| If the JPEG image was compressed using a quality level of 85 or below, then |
| there should be little or no perceptible quality difference between the two |
| algorithms. When decompressing images that were compressed using quality |
| levels above 85, however, the difference between the \fBfast\fR and \fBint\fR |
| methods becomes more pronounced. With images compressed using quality=97, for |
| instance, the \fBfast\fR method incurs generally about a 4-6 dB loss in PSNR |
| relative to the \fBint\fR method, but this can be larger for some images. If |
| you can avoid it, do not use the \fBfast\fR method when decompressing images |
| that were compressed using quality levels above 97. The algorithm often |
| degenerates for such images and can actually produce a more lossy output image |
| than if the JPEG image had been compressed using lower quality levels. |
| .TP |
| .B \-dct float |
| Use floating-point DCT method [legacy feature]. |
| The \fBfloat\fR method does not produce significantly more accurate results |
| than the \fBint\fR method, and it is much slower. The \fBfloat\fR method may |
| also give different results on different machines due to varying roundoff |
| behavior, whereas the integer methods should give the same results on all |
| machines. |
| .TP |
| .B \-dither fs |
| Use Floyd-Steinberg dithering when quantizing colors [legacy feature]. |
| .TP |
| .B \-dither ordered |
| Use ordered dithering when quantizing colors [legacy feature]. |
| .TP |
| .B \-dither none |
| Do not use dithering when quantizing colors [legacy feature]. By default, |
| Floyd-Steinberg dithering is applied when quantizing colors. This is slower |
| but usually produces the best results. Ordered dithering is a compromise |
| between speed and quality. No dithering is faster but usually looks awful. |
| Note that these switches have no effect unless color quantization is being |
| done. Ordered dithering is only available in |
| .B \-onepass |
| mode. |
| .TP |
| .BI \-icc " file" |
| Extract ICC color management profile to the specified file. |
| .TP |
| .BI \-map " file" |
| Quantize to the colors used in the specified image file [legacy feature]. This |
| is useful for producing multiple files with identical color maps, or for |
| forcing a predefined set of colors to be used. The |
| .I file |
| must be a GIF or PPM file. This option overrides |
| .B \-colors |
| and |
| .BR \-onepass . |
| .TP |
| .B \-nosmooth |
| Use a faster, lower-quality upsampling routine. |
| .TP |
| .B \-onepass |
| Use one-pass instead of two-pass color quantization [legacy feature]. The |
| one-pass method needs less memory, but it produces a lower-quality image. |
| .B \-onepass |
| is ignored unless you also specify |
| .B \-colors |
| .IR N . |
| Also, the one-pass method is always used for grayscale output. (The two-pass |
| method has no improvement in that case.) |
| .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, an error will occur. |
| .TP |
| .BI \-maxscans " N" |
| Abort if the JPEG image contains more than |
| .I N |
| scans. This feature demonstrates a method by which applications can guard |
| against denial-of-service attacks instigated by specially-crafted malformed |
| JPEG images containing numerous scans with missing image data or image data |
| consisting only of "EOB runs" (a feature of progressive JPEG images that allows |
| potentially hundreds of thousands of adjoining zero-value pixels to be |
| represented using only a few bytes.) Attempting to decompress such malformed |
| JPEG images can cause excessive CPU activity, since the decompressor must fully |
| process each scan (even if the scan is corrupt) before it can proceed to the |
| next scan. |
| .TP |
| .BI \-outfile " name" |
| Send output image to the named file, not to standard output. |
| .TP |
| .BI \-memsrc |
| Load input file into memory before decompressing. This feature was implemented |
| mainly as a way of testing the in-memory source manager (jpeg_mem_src().) |
| .TP |
| .BI \-report |
| Report decompression progress. |
| .TP |
| .BI \-skip " Y0,Y1" |
| Decompress all rows of the JPEG image except those between Y0 and Y1 |
| (inclusive.) Note that if decompression scaling is being used, then Y0 and Y1 |
| are relative to the scaled image dimensions. |
| .TP |
| .BI \-crop " WxH+X+Y" |
| Decompress only a rectangular subregion of the image, starting at point X,Y |
| with width W and height H. If necessary, X will be shifted left to the nearest |
| iMCU boundary, and the width will be increased accordingly. Note that if |
| decompression scaling is being used, then X, Y, W, and H are relative to the |
| scaled image dimensions. Currently this option only works with the |
| PBMPLUS (PPM/PGM), GIF, and Targa output formats. |
| .TP |
| .BI \-strict |
| Treat all warnings as fatal. This feature also demonstrates a method by which |
| applications can guard against attacks instigated by specially-crafted |
| malformed JPEG images. Enabling this option will cause the decompressor to |
| abort if the JPEG image contains incomplete or corrupt image data. |
| .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 . |
| .TP |
| .B \-version |
| Print version information and exit. |
| .SH EXAMPLES |
| .LP |
| This example decompresses the JPEG file foo.jpg and saves the output in 8-bit |
| BMP format in foo.bmp: |
| .IP |
| .B djpeg \-bmp |
| .I foo.jpg |
| .B > |
| .I foo.bmp |
| .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 cjpeg (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 |
| .PP |
| This file was modified by The libjpeg-turbo Project to include only information |
| relevant to libjpeg-turbo, to wordsmith certain sections, and to describe |
| features not present in libjpeg. |