djpeg.1

   1 .TH DJPEG 1 "4 November 2020"
   2 .SH NAME
   3 djpeg \- decompress a JPEG file to an image file
   4 .SH SYNOPSIS
   5 .B djpeg
   6 [
   7 .I options
   8 ]
   9 [
  10 .I filename
  11 ]
  12 .LP
  13 .SH DESCRIPTION
  14 .LP
  15 .B djpeg
  16 decompresses the named JPEG file, or the standard input if no file is named,
  17 and produces an image file on the standard output.  PBMPLUS (PPM/PGM), BMP,
  18 GIF, Targa, or RLE (Utah Raster Toolkit) output format can be selected.
  19 (RLE is supported only if the URT library is available.)
  20 .SH OPTIONS
  21 All switch names may be abbreviated; for example,
  22 .B \-grayscale
  23 may be written
  24 .B \-gray
  25 or
  26 .BR \-gr .
  27 Most of the "basic" switches can be abbreviated to as little as one letter.
  28 Upper and lower case are equivalent (thus
  29 .B \-BMP
  30 is the same as
  31 .BR \-bmp ).
  32 British spellings are also accepted (e.g.,
  33 .BR \-greyscale ),
  34 though for brevity these are not mentioned below.
  35 .PP
  36 The basic switches are:
  37 .TP
  38 .BI \-colors " N"
  39 Reduce image to at most N colors.  This reduces the number of colors used in
  40 the output image, so that it can be displayed on a colormapped display or
  41 stored in a colormapped file format.  For example, if you have an 8-bit
  42 display, you'd need to reduce to 256 or fewer colors.
  43 .TP
  44 .BI \-quantize " N"
  45 Same as
  46 .BR \-colors .
  47 .B \-colors
  48 is the recommended name,
  49 .B \-quantize
  50 is provided only for backwards compatibility.
  51 .TP
  52 .B \-fast
  53 Select recommended processing options for fast, low quality output.  (The
  54 default options are chosen for highest quality output.)  Currently, this is
  55 equivalent to \fB\-dct fast \-nosmooth \-onepass \-dither ordered\fR.
  56 .TP
  57 .B \-grayscale
  58 Force grayscale output even if JPEG file is color.  Useful for viewing on
  59 monochrome displays; also,
  60 .B djpeg
  61 runs noticeably faster in this mode.
  62 .TP
  63 .B \-rgb
  64 Force RGB output even if JPEG file is grayscale.
  65 .TP
  66 .BI \-scale " M/N"
  67 Scale the output image by a factor M/N.  Currently the scale factor must be
  68 M/8, where M is an integer between 1 and 16 inclusive, or any reduced fraction
  69 thereof (such as 1/2, 3/4, etc.)  Scaling is handy if the image is larger than
  70 your screen; also,
  71 .B djpeg
  72 runs much faster when scaling down the output.
  73 .TP
  74 .B \-bmp
  75 Select BMP output format (Windows flavor).  8-bit colormapped format is
  76 emitted if
  77 .B \-colors
  78 or
  79 .B \-grayscale
  80 is specified, or if the JPEG file is grayscale; otherwise, 24-bit full-color
  81 format is emitted.
  82 .TP
  83 .B \-gif
  84 Select GIF output format.  Since GIF does not support more than 256 colors,
  85 .B \-colors 256
  86 is assumed (unless you specify a smaller number of colors).
  87 .TP
  88 .B \-os2
  89 Select BMP output format (OS/2 1.x flavor).  8-bit colormapped format is
  90 emitted if
  91 .B \-colors
  92 or
  93 .B \-grayscale
  94 is specified, or if the JPEG file is grayscale; otherwise, 24-bit full-color
  95 format is emitted.
  96 .TP
  97 .B \-pnm
  98 Select PBMPLUS (PPM/PGM) output format (this is the default format).
  99 PGM is emitted if the JPEG file is grayscale or if
 100 .B \-grayscale
 101 is specified; otherwise PPM is emitted.
 102 .TP
 103 .B \-rle
 104 Select RLE output format.  (Requires URT library.)
 105 .TP
 106 .B \-targa
 107 Select Targa output format.  Grayscale format is emitted if the JPEG file is
 108 grayscale or if
 109 .B \-grayscale
 110 is specified; otherwise, colormapped format is emitted if
 111 .B \-colors
 112 is specified; otherwise, 24-bit full-color format is emitted.
 113 .PP
 114 Switches for advanced users:
 115 .TP
 116 .B \-dct int
 117 Use accurate integer DCT method (default).
 118 .TP
 119 .B \-dct fast
 120 Use less accurate integer DCT method [legacy feature].
 121 When the Independent JPEG Group's software was first released in 1991, the
 122 decompression time for a 1-megapixel JPEG image on a mainstream PC was measured
 123 in minutes.  Thus, the \fBfast\fR integer DCT algorithm provided noticeable
 124 performance benefits.  On modern CPUs running libjpeg-turbo, however, the
 125 decompression time for a 1-megapixel JPEG image is measured in milliseconds,
 126 and thus the performance benefits of the \fBfast\fR algorithm are much less
 127 noticeable.  On modern x86/x86-64 CPUs that support AVX2 instructions, the
 128 \fBfast\fR and \fBint\fR methods have similar performance.  On other types of
 129 CPUs, the \fBfast\fR method is generally about 5-15% faster than the \fBint\fR
 130 method.
 131
 132 If the JPEG image was compressed using a quality level of 85 or below, then
 133 there should be little or no perceptible quality difference between the two
 134 algorithms.  When decompressing images that were compressed using quality
 135 levels above 85, however, the difference between the \fBfast\fR and \fBint\fR
 136 methods becomes more pronounced.  With images compressed using quality=97, for
 137 instance, the \fBfast\fR method incurs generally about a 4-6 dB loss in PSNR
 138 relative to the \fBint\fR method, but this can be larger for some images.  If
 139 you can avoid it, do not use the \fBfast\fR method when decompressing images
 140 that were compressed using quality levels above 97.  The algorithm often
 141 degenerates for such images and can actually produce a more lossy output image
 142 than if the JPEG image had been compressed using lower quality levels.
 143 .TP
 144 .B \-dct float
 145 Use floating-point DCT method [legacy feature].
 146 The \fBfloat\fR method does not produce significantly more accurate results
 147 than the \fBint\fR method, and it is much slower.  The \fBfloat\fR method may
 148 also give different results on different machines due to varying roundoff
 149 behavior, whereas the integer methods should give the same results on all
 150 machines.
 151 .TP
 152 .B \-dither fs
 153 Use Floyd-Steinberg dithering in color quantization.
 154 .TP
 155 .B \-dither ordered
 156 Use ordered dithering in color quantization.
 157 .TP
 158 .B \-dither none
 159 Do not use dithering in color quantization.
 160 By default, Floyd-Steinberg dithering is applied when quantizing colors; this
 161 is slow but usually produces the best results.  Ordered dither is a compromise
 162 between speed and quality; no dithering is fast but usually looks awful.  Note
 163 that these switches have no effect unless color quantization is being done.
 164 Ordered dither is only available in
 165 .B \-onepass
 166 mode.
 167 .TP
 168 .BI \-icc " file"
 169 Extract ICC color management profile to the specified file.
 170 .TP
 171 .BI \-map " file"
 172 Quantize to the colors used in the specified image file.  This is useful for
 173 producing multiple files with identical color maps, or for forcing a
 174 predefined set of colors to be used.  The
 175 .I file
 176 must be a GIF or PPM file. This option overrides
 177 .B \-colors
 178 and
 179 .BR \-onepass .
 180 .TP
 181 .B \-nosmooth
 182 Use a faster, lower-quality upsampling routine.
 183 .TP
 184 .B \-onepass
 185 Use one-pass instead of two-pass color quantization.  The one-pass method is
 186 faster and needs less memory, but it produces a lower-quality image.
 187 .B \-onepass
 188 is ignored unless you also say
 189 .B \-colors
 190 .IR N .
 191 Also, the one-pass method is always used for grayscale output (the two-pass
 192 method is no improvement then).
 193 .TP
 194 .BI \-maxmemory " N"
 195 Set limit for amount of memory to use in processing large images.  Value is
 196 in thousands of bytes, or millions of bytes if "M" is attached to the
 197 number.  For example,
 198 .B \-max 4m
 199 selects 4000000 bytes.  If more space is needed, an error will occur.
 200 .TP
 201 .BI \-outfile " name"
 202 Send output image to the named file, not to standard output.
 203 .TP
 204 .BI \-memsrc
 205 Load input file into memory before decompressing.  This feature was implemented
 206 mainly as a way of testing the in-memory source manager (jpeg_mem_src().)
 207 .TP
 208 .BI \-skip " Y0,Y1"
 209 Decompress all rows of the JPEG image except those between Y0 and Y1
 210 (inclusive.)  Note that if decompression scaling is being used, then Y0 and Y1
 211 are relative to the scaled image dimensions.
 212 .TP
 213 .BI \-crop " WxH+X+Y"
 214 Decompress only a rectangular subregion of the image, starting at point X,Y
 215 with width W and height H.  If necessary, X will be shifted left to the nearest
 216 iMCU boundary, and the width will be increased accordingly.  Note that if
 217 decompression scaling is being used, then X, Y, W, and H are relative to the
 218 scaled image dimensions.  Currently this option only works with the
 219 PBMPLUS (PPM/PGM), GIF, and Targa output formats.
 220 .TP
 221 .B \-verbose
 222 Enable debug printout.  More
 223 .BR \-v 's
 224 give more output.  Also, version information is printed at startup.
 225 .TP
 226 .B \-debug
 227 Same as
 228 .BR \-verbose .
 229 .TP
 230 .B \-version
 231 Print version information and exit.
 232 .SH EXAMPLES
 233 .LP
 234 This example decompresses the JPEG file foo.jpg, quantizes it to
 235 256 colors, and saves the output in 8-bit BMP format in foo.bmp:
 236 .IP
 237 .B djpeg \-colors 256 \-bmp
 238 .I foo.jpg
 239 .B >
 240 .I foo.bmp
 241 .SH HINTS
 242 To get a quick preview of an image, use the
 243 .B \-grayscale
 244 and/or
 245 .B \-scale
 246 switches.
 247 .B \-grayscale \-scale 1/8
 248 is the fastest case.
 249 .PP
 250 Several options are available that trade off image quality to gain speed.
 251 .B \-fast
 252 turns on the recommended settings.
 253 .PP
 254 .B \-dct fast
 255 and/or
 256 .B \-nosmooth
 257 gain speed at a small sacrifice in quality.
 258 When producing a color-quantized image,
 259 .B \-onepass \-dither ordered
 260 is fast but much lower quality than the default behavior.
 261 .B \-dither none
 262 may give acceptable results in two-pass mode, but is seldom tolerable in
 263 one-pass mode.
 264 .SH ENVIRONMENT
 265 .TP
 266 .B JPEGMEM
 267 If this environment variable is set, its value is the default memory limit.
 268 The value is specified as described for the
 269 .B \-maxmemory
 270 switch.
 271 .B JPEGMEM
 272 overrides the default value specified when the program was compiled, and
 273 itself is overridden by an explicit
 274 .BR \-maxmemory .
 275 .SH SEE ALSO
 276 .BR cjpeg (1),
 277 .BR jpegtran (1),
 278 .BR rdjpgcom (1),
 279 .BR wrjpgcom (1)
 280 .br
 281 .BR ppm (5),
 282 .BR pgm (5)
 283 .br
 284 Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",
 285 Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.
 286 .SH AUTHOR
 287 Independent JPEG Group
 288 .PP
 289 This file was modified by The libjpeg-turbo Project to include only information
 290 relevant to libjpeg-turbo, to wordsmith certain sections, and to describe
 291 features not present in libjpeg.
 292 .SH ISSUES
 293 Support for compressed GIF output files was removed in djpeg v6b due to
 294 concerns over the Unisys LZW patent.  Although this patent expired in 2006,
 295 djpeg still lacks compressed GIF support, for these historical reasons.
 296 (Conversion of JPEG files to GIF is usually a bad idea anyway, since GIF is a
 297 256-color format.)  The uncompressed GIF files that djpeg generates are larger
 298 than they should be, but they are readable by standard GIF decoders.