kc3-lang/libjpeg-turbo/djpeg.1
-
Show log
Commit
-
Hash : 94c64ead
Author :
Date : 2024-06-17T20:27:57
Various doc tweaks - "bits per component" = "bits per sample" Describing the data precision of a JPEG image using "bits per component" is technically correct, but "bits per sample" is the terminology that the JPEG-1 spec uses. Also, "bits per component" is more commonly used to describe the precision of packed-pixel formats (as opposed to "bits per pixel") rather than planar formats, in which all components are grouped together. - Unmention legacy display technologies. Colormapped and monochrome displays aren't a thing anymore, and even when they were still a thing, it was possible to display full-color images to them. In 1991, when JPEG decompression time was measured in minutes per megapixel, it made sense to keep a decompressed copy of JPEG images on disk, in a format that could be displayed without further color conversion (since color conversion was slow and memory-intensive.) In 2024, JPEG decompression time is measured in milliseconds per megapixel, and color conversion is even faster. Thus, JPEG images can be decompressed, displayed, and color-converted (if necessary) "on the fly" at speeds too fast for human vision to perceive. (In fact, your TV performs much more complicated decompression algorithms at least 60 times per second.) - Document that color quantization (and associated features), GIF input/output, Targa input/output, and OS/2 BMP input/output are legacy features. Legacy status doesn't necessarily mean that the features are deprecated. Rather, it is meant to discourage users from using features that may be of little or no benefit on modern machines (such as low-quality modes that had significant performance advantages in the early 1990s but no longer do) and that are maintained on a break/fix basis only. - General wordsmithing, grammar/punctuation policing, and formatting tweaks - Clarify which data precisions each cjpeg input format and each djpeg output format supports. - cjpeg.1: Remove unnecessary and impolitic statement about the -targa switch. - Adjust or remove performance claims to reflect the fact that: * On modern machines, the djpeg "-fast" switch has a negligible effect on performance. * There is a measurable difference between the performance of Floyd- Steinberg dithering and no dithering, but it is not likely perceptible to most users. * There is a measurable difference between the performance of 1-pass and 2-pass color quantization, but it is not likely perceptible to most users. * There is a measurable difference between the performance of full-color and grayscale output when decompressing a full-color JPEG image, but it is not likely perceptible to most users. * IDCT scaling does not necessarily improve performance. (It generally does if the scaling factor is <= 1/2 and generally doesn't if the scaling factor is > 1/2, at least on my machine. The performance claim made in jpeg-6b was probably invalidated when we merged the additional scaling factors from jpeg-7.) - Clarify which djpeg switches/output formats cannot be used when decompressing lossless JPEG images. - Remove djpeg hints, since those involve quality vs. speed tradeoffs that are no longer relevant for modern machines. - Remove documentation regarding using color quantization with 16-bit data precision. (Color quantization requires lossy mode.) - Java: Fix typos in TJDecompressor.decompress12() and TJDecompressor.decompress16() documentation. - jpegtran.1: Fix truncated paragraph In a man page, a single quote at the start of a line is interpreted as a macro. Closes #775 - libjpeg.txt: * Mention J16SAMPLE data type (oversight.) * Remove statement about extending jdcolor.c. (libjpeg-turbo is not quite as DIY as libjpeg once was.) * Remove paragraph about tweaking the various typedefs in jmorecfg.h. It is no longer relevant for modern machines. * Remove caveat regarding systems with ints less than 16 bits wide. (ANSI/ISO C requires an int to be at least 16 bits wide, and libjpeg-turbo has never supported non-ANSI compilers.) - usage.txt: * Add copyright header. * Document cjpeg -icc, -memdst, -report, -strict, and -version switches. * Document djpeg -icc, -maxscans, -memsrc, -report, -skip, -crop, -strict, and -version switches. * Document jpegtran -icc, -maxscans, -report, -strict, and -version switches.
-
djpeg.1
-
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301
.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.