|
1 USAGE instructions for the Independent JPEG Group's JPEG software |
|
2 ================================================================= |
|
3 |
|
4 This file describes usage of the JPEG conversion programs cjpeg and djpeg, |
|
5 as well as the utility programs jpegtran, rdjpgcom and wrjpgcom. (See |
|
6 the other documentation files if you wish to use the JPEG library within |
|
7 your own programs.) |
|
8 |
|
9 If you are on a Unix machine you may prefer to read the Unix-style manual |
|
10 pages in files cjpeg.1, djpeg.1, jpegtran.1, rdjpgcom.1, wrjpgcom.1. |
|
11 |
|
12 |
|
13 INTRODUCTION |
|
14 |
|
15 These programs implement JPEG image encoding, decoding, and transcoding. |
|
16 JPEG (pronounced "jay-peg") is a standardized compression method for |
|
17 full-color and gray-scale images. |
|
18 |
|
19 |
|
20 GENERAL USAGE |
|
21 |
|
22 We provide two programs, cjpeg to compress an image file into JPEG format, |
|
23 and djpeg to decompress a JPEG file back into a conventional image format. |
|
24 |
|
25 On Unix-like systems, you say: |
|
26 cjpeg [switches] [imagefile] >jpegfile |
|
27 or |
|
28 djpeg [switches] [jpegfile] >imagefile |
|
29 The programs read the specified input file, or standard input if none is |
|
30 named. They always write to standard output (with trace/error messages to |
|
31 standard error). These conventions are handy for piping images between |
|
32 programs. |
|
33 |
|
34 On most non-Unix systems, you say: |
|
35 cjpeg [switches] imagefile jpegfile |
|
36 or |
|
37 djpeg [switches] jpegfile imagefile |
|
38 i.e., both the input and output files are named on the command line. This |
|
39 style is a little more foolproof, and it loses no functionality if you don't |
|
40 have pipes. (You can get this style on Unix too, if you prefer, by defining |
|
41 TWO_FILE_COMMANDLINE when you compile the programs; see install.txt.) |
|
42 |
|
43 You can also say: |
|
44 cjpeg [switches] -outfile jpegfile imagefile |
|
45 or |
|
46 djpeg [switches] -outfile imagefile jpegfile |
|
47 This syntax works on all systems, so it is useful for scripts. |
|
48 |
|
49 The currently supported image file formats are: PPM (PBMPLUS color format), |
|
50 PGM (PBMPLUS gray-scale format), BMP, Targa, and RLE (Utah Raster Toolkit |
|
51 format). (RLE is supported only if the URT library is available.) |
|
52 cjpeg recognizes the input image format automatically, with the exception |
|
53 of some Targa-format files. You have to tell djpeg which format to generate. |
|
54 |
|
55 JPEG files are in the defacto standard JFIF file format. There are other, |
|
56 less widely used JPEG-based file formats, but we don't support them. |
|
57 |
|
58 All switch names may be abbreviated; for example, -grayscale may be written |
|
59 -gray or -gr. Most of the "basic" switches can be abbreviated to as little as |
|
60 one letter. Upper and lower case are equivalent (-BMP is the same as -bmp). |
|
61 British spellings are also accepted (e.g., -greyscale), though for brevity |
|
62 these are not mentioned below. |
|
63 |
|
64 |
|
65 CJPEG DETAILS |
|
66 |
|
67 The basic command line switches for cjpeg are: |
|
68 |
|
69 -quality N[,...] Scale quantization tables to adjust image quality. |
|
70 Quality is 0 (worst) to 100 (best); default is 75. |
|
71 (See below for more info.) |
|
72 |
|
73 -grayscale Create monochrome JPEG file from color input. |
|
74 Be sure to use this switch when compressing a grayscale |
|
75 BMP file, because cjpeg isn't bright enough to notice |
|
76 whether a BMP file uses only shades of gray. By |
|
77 saying -grayscale, you'll get a smaller JPEG file that |
|
78 takes less time to process. |
|
79 |
|
80 -optimize Perform optimization of entropy encoding parameters. |
|
81 Without this, default encoding parameters are used. |
|
82 -optimize usually makes the JPEG file a little smaller, |
|
83 but cjpeg runs somewhat slower and needs much more |
|
84 memory. Image quality and speed of decompression are |
|
85 unaffected by -optimize. |
|
86 |
|
87 -progressive Create progressive JPEG file (see below). |
|
88 |
|
89 -scale M/N Scale the output image by a factor M/N. Currently |
|
90 supported scale factors are 8/N with all N from 1 to |
|
91 16. |
|
92 |
|
93 -targa Input file is Targa format. Targa files that contain |
|
94 an "identification" field will not be automatically |
|
95 recognized by cjpeg; for such files you must specify |
|
96 -targa to make cjpeg treat the input as Targa format. |
|
97 For most Targa files, you won't need this switch. |
|
98 |
|
99 The -quality switch lets you trade off compressed file size against quality of |
|
100 the reconstructed image: the higher the quality setting, the larger the JPEG |
|
101 file, and the closer the output image will be to the original input. Normally |
|
102 you want to use the lowest quality setting (smallest file) that decompresses |
|
103 into something visually indistinguishable from the original image. For this |
|
104 purpose the quality setting should be between 50 and 95; the default of 75 is |
|
105 often about right. If you see defects at -quality 75, then go up 5 or 10 |
|
106 counts at a time until you are happy with the output image. (The optimal |
|
107 setting will vary from one image to another.) |
|
108 |
|
109 -quality 100 will generate a quantization table of all 1's, minimizing loss |
|
110 in the quantization step (but there is still information loss in subsampling, |
|
111 as well as roundoff error). This setting is mainly of interest for |
|
112 experimental purposes. Quality values above about 95 are NOT recommended for |
|
113 normal use; the compressed file size goes up dramatically for hardly any gain |
|
114 in output image quality. |
|
115 |
|
116 In the other direction, quality values below 50 will produce very small files |
|
117 of low image quality. Settings around 5 to 10 might be useful in preparing an |
|
118 index of a large image library, for example. Try -quality 2 (or so) for some |
|
119 amusing Cubist effects. (Note: quality values below about 25 generate 2-byte |
|
120 quantization tables, which are considered optional in the JPEG standard. |
|
121 cjpeg emits a warning message when you give such a quality value, because some |
|
122 other JPEG programs may be unable to decode the resulting file. Use -baseline |
|
123 if you need to ensure compatibility at low quality values.) |
|
124 |
|
125 The -quality option has been extended in IJG version 7 for support of separate |
|
126 quality settings for luminance and chrominance (or in general, for every |
|
127 provided quantization table slot). This feature is useful for high-quality |
|
128 applications which cannot accept the damage of color data by coarse |
|
129 subsampling settings. You can now easily reduce the color data amount more |
|
130 smoothly with finer control without separate subsampling. The resulting file |
|
131 is fully compliant with standard JPEG decoders. |
|
132 Note that the -quality ratings refer to the quantization table slots, and that |
|
133 the last value is replicated if there are more q-table slots than parameters. |
|
134 The default q-table slots are 0 for luminance and 1 for chrominance with |
|
135 default tables as given in the JPEG standard. This is compatible with the old |
|
136 behaviour in case that only one parameter is given, which is then used for |
|
137 both luminance and chrominance (slots 0 and 1). More or custom quantization |
|
138 tables can be set with -qtables and assigned to components with -qslots |
|
139 parameter (see the "wizard" switches below). |
|
140 CAUTION: You must explicitly add -sample 1x1 for efficient separate color |
|
141 quality selection, since the default value used by library is 2x2! |
|
142 |
|
143 The -progressive switch creates a "progressive JPEG" file. In this type of |
|
144 JPEG file, the data is stored in multiple scans of increasing quality. If the |
|
145 file is being transmitted over a slow communications link, the decoder can use |
|
146 the first scan to display a low-quality image very quickly, and can then |
|
147 improve the display with each subsequent scan. The final image is exactly |
|
148 equivalent to a standard JPEG file of the same quality setting, and the total |
|
149 file size is about the same --- often a little smaller. |
|
150 |
|
151 Switches for advanced users: |
|
152 |
|
153 -dct int Use integer DCT method (default). |
|
154 -dct fast Use fast integer DCT (less accurate). |
|
155 -dct float Use floating-point DCT method. |
|
156 The float method is very slightly more accurate than |
|
157 the int method, but is much slower unless your machine |
|
158 has very fast floating-point hardware. Also note that |
|
159 results of the floating-point method may vary slightly |
|
160 across machines, while the integer methods should give |
|
161 the same results everywhere. The fast integer method |
|
162 is much less accurate than the other two. |
|
163 |
|
164 -nosmooth Don't use high-quality downsampling. |
|
165 |
|
166 -restart N Emit a JPEG restart marker every N MCU rows, or every |
|
167 N MCU blocks if "B" is attached to the number. |
|
168 -restart 0 (the default) means no restart markers. |
|
169 |
|
170 -smooth N Smooth the input image to eliminate dithering noise. |
|
171 N, ranging from 1 to 100, indicates the strength of |
|
172 smoothing. 0 (the default) means no smoothing. |
|
173 |
|
174 -maxmemory N Set limit for amount of memory to use in processing |
|
175 large images. Value is in thousands of bytes, or |
|
176 millions of bytes if "M" is attached to the number. |
|
177 For example, -max 4m selects 4000000 bytes. If more |
|
178 space is needed, temporary files will be used. |
|
179 |
|
180 -verbose Enable debug printout. More -v's give more printout. |
|
181 or -debug Also, version information is printed at startup. |
|
182 |
|
183 The -restart option inserts extra markers that allow a JPEG decoder to |
|
184 resynchronize after a transmission error. Without restart markers, any damage |
|
185 to a compressed file will usually ruin the image from the point of the error |
|
186 to the end of the image; with restart markers, the damage is usually confined |
|
187 to the portion of the image up to the next restart marker. Of course, the |
|
188 restart markers occupy extra space. We recommend -restart 1 for images that |
|
189 will be transmitted across unreliable networks such as Usenet. |
|
190 |
|
191 The -smooth option filters the input to eliminate fine-scale noise. This is |
|
192 often useful when converting dithered images to JPEG: a moderate smoothing |
|
193 factor of 10 to 50 gets rid of dithering patterns in the input file, resulting |
|
194 in a smaller JPEG file and a better-looking image. Too large a smoothing |
|
195 factor will visibly blur the image, however. |
|
196 |
|
197 Switches for wizards: |
|
198 |
|
199 -arithmetic Use arithmetic coding. CAUTION: arithmetic coded JPEG |
|
200 is not yet widely implemented, so many decoders will |
|
201 be unable to view an arithmetic coded JPEG file at |
|
202 all. |
|
203 |
|
204 -baseline Force baseline-compatible quantization tables to be |
|
205 generated. This clamps quantization values to 8 bits |
|
206 even at low quality settings. (This switch is poorly |
|
207 named, since it does not ensure that the output is |
|
208 actually baseline JPEG. For example, you can use |
|
209 -baseline and -progressive together.) |
|
210 |
|
211 -qtables file Use the quantization tables given in the specified |
|
212 text file. |
|
213 |
|
214 -qslots N[,...] Select which quantization table to use for each color |
|
215 component. |
|
216 |
|
217 -sample HxV[,...] Set JPEG sampling factors for each color component. |
|
218 |
|
219 -scans file Use the scan script given in the specified text file. |
|
220 |
|
221 The "wizard" switches are intended for experimentation with JPEG. If you |
|
222 don't know what you are doing, DON'T USE THEM. These switches are documented |
|
223 further in the file wizard.txt. |
|
224 |
|
225 |
|
226 DJPEG DETAILS |
|
227 |
|
228 The basic command line switches for djpeg are: |
|
229 |
|
230 -colors N Reduce image to at most N colors. This reduces the |
|
231 or -quantize N number of colors used in the output image, so that it |
|
232 can be displayed on a colormapped display or stored in |
|
233 a colormapped file format. For example, if you have |
|
234 an 8-bit display, you'd need to reduce to 256 or fewer |
|
235 colors. (-colors is the recommended name, -quantize |
|
236 is provided only for backwards compatibility.) |
|
237 |
|
238 -fast Select recommended processing options for fast, low |
|
239 quality output. (The default options are chosen for |
|
240 highest quality output.) Currently, this is equivalent |
|
241 to "-dct fast -nosmooth -onepass -dither ordered". |
|
242 |
|
243 -grayscale Force gray-scale output even if JPEG file is color. |
|
244 Useful for viewing on monochrome displays; also, |
|
245 djpeg runs noticeably faster in this mode. |
|
246 |
|
247 -scale M/N Scale the output image by a factor M/N. Currently |
|
248 supported scale factors are M/N with all M from 1 to |
|
249 16, where N is the source DCT size, which is 8 for |
|
250 baseline JPEG. If the /N part is omitted, then M |
|
251 specifies the DCT scaled size to be applied on the |
|
252 given input. For baseline JPEG this is equivalent to |
|
253 M/8 scaling, since the source DCT size for baseline |
|
254 JPEG is 8. Scaling is handy if the image is larger |
|
255 than your screen; also, djpeg runs much faster when |
|
256 scaling down the output. |
|
257 |
|
258 -bmp Select BMP output format (Windows flavor). 8-bit |
|
259 colormapped format is emitted if -colors or -grayscale |
|
260 is specified, or if the JPEG file is gray-scale; |
|
261 otherwise, 24-bit full-color format is emitted. |
|
262 |
|
263 -gif Select GIF output format. Since GIF does not support |
|
264 more than 256 colors, -colors 256 is assumed (unless |
|
265 you specify a smaller number of colors). If you |
|
266 specify -fast, the default number of colors is 216. |
|
267 |
|
268 -os2 Select BMP output format (OS/2 1.x flavor). 8-bit |
|
269 colormapped format is emitted if -colors or -grayscale |
|
270 is specified, or if the JPEG file is gray-scale; |
|
271 otherwise, 24-bit full-color format is emitted. |
|
272 |
|
273 -pnm Select PBMPLUS (PPM/PGM) output format (this is the |
|
274 default format). PGM is emitted if the JPEG file is |
|
275 gray-scale or if -grayscale is specified; otherwise |
|
276 PPM is emitted. |
|
277 |
|
278 -rle Select RLE output format. (Requires URT library.) |
|
279 |
|
280 -targa Select Targa output format. Gray-scale format is |
|
281 emitted if the JPEG file is gray-scale or if |
|
282 -grayscale is specified; otherwise, colormapped format |
|
283 is emitted if -colors is specified; otherwise, 24-bit |
|
284 full-color format is emitted. |
|
285 |
|
286 Switches for advanced users: |
|
287 |
|
288 -dct int Use integer DCT method (default). |
|
289 -dct fast Use fast integer DCT (less accurate). |
|
290 -dct float Use floating-point DCT method. |
|
291 The float method is very slightly more accurate than |
|
292 the int method, but is much slower unless your machine |
|
293 has very fast floating-point hardware. Also note that |
|
294 results of the floating-point method may vary slightly |
|
295 across machines, while the integer methods should give |
|
296 the same results everywhere. The fast integer method |
|
297 is much less accurate than the other two. |
|
298 |
|
299 -dither fs Use Floyd-Steinberg dithering in color quantization. |
|
300 -dither ordered Use ordered dithering in color quantization. |
|
301 -dither none Do not use dithering in color quantization. |
|
302 By default, Floyd-Steinberg dithering is applied when |
|
303 quantizing colors; this is slow but usually produces |
|
304 the best results. Ordered dither is a compromise |
|
305 between speed and quality; no dithering is fast but |
|
306 usually looks awful. Note that these switches have |
|
307 no effect unless color quantization is being done. |
|
308 Ordered dither is only available in -onepass mode. |
|
309 |
|
310 -map FILE Quantize to the colors used in the specified image |
|
311 file. This is useful for producing multiple files |
|
312 with identical color maps, or for forcing a predefined |
|
313 set of colors to be used. The FILE must be a GIF |
|
314 or PPM file. This option overrides -colors and |
|
315 -onepass. |
|
316 |
|
317 -nosmooth Don't use high-quality upsampling. |
|
318 |
|
319 -onepass Use one-pass instead of two-pass color quantization. |
|
320 The one-pass method is faster and needs less memory, |
|
321 but it produces a lower-quality image. -onepass is |
|
322 ignored unless you also say -colors N. Also, |
|
323 the one-pass method is always used for gray-scale |
|
324 output (the two-pass method is no improvement then). |
|
325 |
|
326 -maxmemory N Set limit for amount of memory to use in processing |
|
327 large images. Value is in thousands of bytes, or |
|
328 millions of bytes if "M" is attached to the number. |
|
329 For example, -max 4m selects 4000000 bytes. If more |
|
330 space is needed, temporary files will be used. |
|
331 |
|
332 -verbose Enable debug printout. More -v's give more printout. |
|
333 or -debug Also, version information is printed at startup. |
|
334 |
|
335 |
|
336 HINTS FOR CJPEG |
|
337 |
|
338 Color GIF files are not the ideal input for JPEG; JPEG is really intended for |
|
339 compressing full-color (24-bit) images. In particular, don't try to convert |
|
340 cartoons, line drawings, and other images that have only a few distinct |
|
341 colors. GIF works great on these, JPEG does not. If you want to convert a |
|
342 GIF to JPEG, you should experiment with cjpeg's -quality and -smooth options |
|
343 to get a satisfactory conversion. -smooth 10 or so is often helpful. |
|
344 |
|
345 Avoid running an image through a series of JPEG compression/decompression |
|
346 cycles. Image quality loss will accumulate; after ten or so cycles the image |
|
347 may be noticeably worse than it was after one cycle. It's best to use a |
|
348 lossless format while manipulating an image, then convert to JPEG format when |
|
349 you are ready to file the image away. |
|
350 |
|
351 The -optimize option to cjpeg is worth using when you are making a "final" |
|
352 version for posting or archiving. It's also a win when you are using low |
|
353 quality settings to make very small JPEG files; the percentage improvement |
|
354 is often a lot more than it is on larger files. (At present, -optimize |
|
355 mode is always selected when generating progressive JPEG files.) |
|
356 |
|
357 GIF input files are no longer supported, to avoid the Unisys LZW patent. |
|
358 (Conversion of GIF files to JPEG is usually a bad idea anyway.) |
|
359 |
|
360 |
|
361 HINTS FOR DJPEG |
|
362 |
|
363 To get a quick preview of an image, use the -grayscale and/or -scale switches. |
|
364 "-grayscale -scale 1/8" is the fastest case. |
|
365 |
|
366 Several options are available that trade off image quality to gain speed. |
|
367 "-fast" turns on the recommended settings. |
|
368 |
|
369 "-dct fast" and/or "-nosmooth" gain speed at a small sacrifice in quality. |
|
370 When producing a color-quantized image, "-onepass -dither ordered" is fast but |
|
371 much lower quality than the default behavior. "-dither none" may give |
|
372 acceptable results in two-pass mode, but is seldom tolerable in one-pass mode. |
|
373 |
|
374 If you are fortunate enough to have very fast floating point hardware, |
|
375 "-dct float" may be even faster than "-dct fast". But on most machines |
|
376 "-dct float" is slower than "-dct int"; in this case it is not worth using, |
|
377 because its theoretical accuracy advantage is too small to be significant |
|
378 in practice. |
|
379 |
|
380 Two-pass color quantization requires a good deal of memory; on MS-DOS machines |
|
381 it may run out of memory even with -maxmemory 0. In that case you can still |
|
382 decompress, with some loss of image quality, by specifying -onepass for |
|
383 one-pass quantization. |
|
384 |
|
385 To avoid the Unisys LZW patent, djpeg produces uncompressed GIF files. These |
|
386 are larger than they should be, but are readable by standard GIF decoders. |
|
387 |
|
388 |
|
389 HINTS FOR BOTH PROGRAMS |
|
390 |
|
391 If more space is needed than will fit in the available main memory (as |
|
392 determined by -maxmemory), temporary files will be used. (MS-DOS versions |
|
393 will try to get extended or expanded memory first.) The temporary files are |
|
394 often rather large: in typical cases they occupy three bytes per pixel, for |
|
395 example 3*800*600 = 1.44Mb for an 800x600 image. If you don't have enough |
|
396 free disk space, leave out -progressive and -optimize (for cjpeg) or specify |
|
397 -onepass (for djpeg). |
|
398 |
|
399 On MS-DOS, the temporary files are created in the directory named by the TMP |
|
400 or TEMP environment variable, or in the current directory if neither of those |
|
401 exist. Amiga implementations put the temp files in the directory named by |
|
402 JPEGTMP:, so be sure to assign JPEGTMP: to a disk partition with adequate free |
|
403 space. |
|
404 |
|
405 The default memory usage limit (-maxmemory) is set when the software is |
|
406 compiled. If you get an "insufficient memory" error, try specifying a smaller |
|
407 -maxmemory value, even -maxmemory 0 to use the absolute minimum space. You |
|
408 may want to recompile with a smaller default value if this happens often. |
|
409 |
|
410 On machines that have "environment" variables, you can define the environment |
|
411 variable JPEGMEM to set the default memory limit. The value is specified as |
|
412 described for the -maxmemory switch. JPEGMEM overrides the default value |
|
413 specified when the program was compiled, and itself is overridden by an |
|
414 explicit -maxmemory switch. |
|
415 |
|
416 On MS-DOS machines, -maxmemory is the amount of main (conventional) memory to |
|
417 use. (Extended or expanded memory is also used if available.) Most |
|
418 DOS-specific versions of this software do their own memory space estimation |
|
419 and do not need you to specify -maxmemory. |
|
420 |
|
421 |
|
422 JPEGTRAN |
|
423 |
|
424 jpegtran performs various useful transformations of JPEG files. |
|
425 It can translate the coded representation from one variant of JPEG to another, |
|
426 for example from baseline JPEG to progressive JPEG or vice versa. It can also |
|
427 perform some rearrangements of the image data, for example turning an image |
|
428 from landscape to portrait format by rotation. |
|
429 |
|
430 jpegtran works by rearranging the compressed data (DCT coefficients), without |
|
431 ever fully decoding the image. Therefore, its transformations are lossless: |
|
432 there is no image degradation at all, which would not be true if you used |
|
433 djpeg followed by cjpeg to accomplish the same conversion. But by the same |
|
434 token, jpegtran cannot perform lossy operations such as changing the image |
|
435 quality. |
|
436 |
|
437 jpegtran uses a command line syntax similar to cjpeg or djpeg. |
|
438 On Unix-like systems, you say: |
|
439 jpegtran [switches] [inputfile] >outputfile |
|
440 On most non-Unix systems, you say: |
|
441 jpegtran [switches] inputfile outputfile |
|
442 where both the input and output files are JPEG files. |
|
443 |
|
444 To specify the coded JPEG representation used in the output file, |
|
445 jpegtran accepts a subset of the switches recognized by cjpeg: |
|
446 -optimize Perform optimization of entropy encoding parameters. |
|
447 -progressive Create progressive JPEG file. |
|
448 -restart N Emit a JPEG restart marker every N MCU rows, or every |
|
449 N MCU blocks if "B" is attached to the number. |
|
450 -arithmetic Use arithmetic coding. |
|
451 -scans file Use the scan script given in the specified text file. |
|
452 See the previous discussion of cjpeg for more details about these switches. |
|
453 If you specify none of these switches, you get a plain baseline-JPEG output |
|
454 file. The quality setting and so forth are determined by the input file. |
|
455 |
|
456 The image can be losslessly transformed by giving one of these switches: |
|
457 -flip horizontal Mirror image horizontally (left-right). |
|
458 -flip vertical Mirror image vertically (top-bottom). |
|
459 -rotate 90 Rotate image 90 degrees clockwise. |
|
460 -rotate 180 Rotate image 180 degrees. |
|
461 -rotate 270 Rotate image 270 degrees clockwise (or 90 ccw). |
|
462 -transpose Transpose image (across UL-to-LR axis). |
|
463 -transverse Transverse transpose (across UR-to-LL axis). |
|
464 |
|
465 The transpose transformation has no restrictions regarding image dimensions. |
|
466 The other transformations operate rather oddly if the image dimensions are not |
|
467 a multiple of the iMCU size (usually 8 or 16 pixels), because they can only |
|
468 transform complete blocks of DCT coefficient data in the desired way. |
|
469 |
|
470 jpegtran's default behavior when transforming an odd-size image is designed |
|
471 to preserve exact reversibility and mathematical consistency of the |
|
472 transformation set. As stated, transpose is able to flip the entire image |
|
473 area. Horizontal mirroring leaves any partial iMCU column at the right edge |
|
474 untouched, but is able to flip all rows of the image. Similarly, vertical |
|
475 mirroring leaves any partial iMCU row at the bottom edge untouched, but is |
|
476 able to flip all columns. The other transforms can be built up as sequences |
|
477 of transpose and flip operations; for consistency, their actions on edge |
|
478 pixels are defined to be the same as the end result of the corresponding |
|
479 transpose-and-flip sequence. |
|
480 |
|
481 For practical use, you may prefer to discard any untransformable edge pixels |
|
482 rather than having a strange-looking strip along the right and/or bottom edges |
|
483 of a transformed image. To do this, add the -trim switch: |
|
484 -trim Drop non-transformable edge blocks. |
|
485 Obviously, a transformation with -trim is not reversible, so strictly speaking |
|
486 jpegtran with this switch is not lossless. Also, the expected mathematical |
|
487 equivalences between the transformations no longer hold. For example, |
|
488 "-rot 270 -trim" trims only the bottom edge, but "-rot 90 -trim" followed by |
|
489 "-rot 180 -trim" trims both edges. |
|
490 |
|
491 If you are only interested in perfect transformation, add the -perfect switch: |
|
492 -perfect Fails with an error if the transformation is not |
|
493 perfect. |
|
494 For example you may want to do |
|
495 jpegtran -rot 90 -perfect foo.jpg || djpeg foo.jpg | pnmflip -r90 | cjpeg |
|
496 to do a perfect rotation if available or an approximated one if not. |
|
497 |
|
498 We also offer a lossless-crop option, which discards data outside a given |
|
499 image region but losslessly preserves what is inside. Like the rotate and |
|
500 flip transforms, lossless crop is restricted by the current JPEG format: the |
|
501 upper left corner of the selected region must fall on an iMCU boundary. If |
|
502 this does not hold for the given crop parameters, we silently move the upper |
|
503 left corner up and/or left to make it so, simultaneously increasing the region |
|
504 dimensions to keep the lower right crop corner unchanged. (Thus, the output |
|
505 image covers at least the requested region, but may cover more.) |
|
506 |
|
507 The image can be losslessly cropped by giving the switch: |
|
508 -crop WxH+X+Y Crop to a rectangular subarea of width W, height H |
|
509 starting at point X,Y. |
|
510 |
|
511 Other not-strictly-lossless transformation switches are: |
|
512 |
|
513 -grayscale Force grayscale output. |
|
514 This option discards the chrominance channels if the input image is YCbCr |
|
515 (ie, a standard color JPEG), resulting in a grayscale JPEG file. The |
|
516 luminance channel is preserved exactly, so this is a better method of reducing |
|
517 to grayscale than decompression, conversion, and recompression. This switch |
|
518 is particularly handy for fixing a monochrome picture that was mistakenly |
|
519 encoded as a color JPEG. (In such a case, the space savings from getting rid |
|
520 of the near-empty chroma channels won't be large; but the decoding time for |
|
521 a grayscale JPEG is substantially less than that for a color JPEG.) |
|
522 |
|
523 -scale M/N Scale the output image by a factor M/N. |
|
524 Currently supported scale factors are M/N with all M from 1 to 16, where N is |
|
525 the source DCT size, which is 8 for baseline JPEG. If the /N part is omitted, |
|
526 then M specifies the DCT scaled size to be applied on the given input. For |
|
527 baseline JPEG this is equivalent to M/8 scaling, since the source DCT size |
|
528 for baseline JPEG is 8. CAUTION: An implementation of the JPEG SmartScale |
|
529 extension is required for this feature. SmartScale enabled JPEG is not yet |
|
530 widely implemented, so many decoders will be unable to view a SmartScale |
|
531 extended JPEG file at all. |
|
532 |
|
533 jpegtran also recognizes these switches that control what to do with "extra" |
|
534 markers, such as comment blocks: |
|
535 -copy none Copy no extra markers from source file. This setting |
|
536 suppresses all comments and other excess baggage |
|
537 present in the source file. |
|
538 -copy comments Copy only comment markers. This setting copies |
|
539 comments from the source file, but discards |
|
540 any other inessential (for image display) data. |
|
541 -copy all Copy all extra markers. This setting preserves |
|
542 miscellaneous markers found in the source file, such |
|
543 as JFIF thumbnails, Exif data, and Photoshop settings. |
|
544 In some files these extra markers can be sizable. |
|
545 The default behavior is -copy comments. (Note: in IJG releases v6 and v6a, |
|
546 jpegtran always did the equivalent of -copy none.) |
|
547 |
|
548 Additional switches recognized by jpegtran are: |
|
549 -outfile filename |
|
550 -maxmemory N |
|
551 -verbose |
|
552 -debug |
|
553 These work the same as in cjpeg or djpeg. |
|
554 |
|
555 |
|
556 THE COMMENT UTILITIES |
|
557 |
|
558 The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file. |
|
559 Although the standard doesn't actually define what COM blocks are for, they |
|
560 are widely used to hold user-supplied text strings. This lets you add |
|
561 annotations, titles, index terms, etc to your JPEG files, and later retrieve |
|
562 them as text. COM blocks do not interfere with the image stored in the JPEG |
|
563 file. The maximum size of a COM block is 64K, but you can have as many of |
|
564 them as you like in one JPEG file. |
|
565 |
|
566 We provide two utility programs to display COM block contents and add COM |
|
567 blocks to a JPEG file. |
|
568 |
|
569 rdjpgcom searches a JPEG file and prints the contents of any COM blocks on |
|
570 standard output. The command line syntax is |
|
571 rdjpgcom [-raw] [-verbose] [inputfilename] |
|
572 The switch "-raw" (or just "-r") causes rdjpgcom to also output non-printable |
|
573 characters in comments, which are normally escaped for security reasons. |
|
574 The switch "-verbose" (or just "-v") causes rdjpgcom to also display the JPEG |
|
575 image dimensions. If you omit the input file name from the command line, |
|
576 the JPEG file is read from standard input. (This may not work on some |
|
577 operating systems, if binary data can't be read from stdin.) |
|
578 |
|
579 wrjpgcom adds a COM block, containing text you provide, to a JPEG file. |
|
580 Ordinarily, the COM block is added after any existing COM blocks, but you |
|
581 can delete the old COM blocks if you wish. wrjpgcom produces a new JPEG |
|
582 file; it does not modify the input file. DO NOT try to overwrite the input |
|
583 file by directing wrjpgcom's output back into it; on most systems this will |
|
584 just destroy your file. |
|
585 |
|
586 The command line syntax for wrjpgcom is similar to cjpeg's. On Unix-like |
|
587 systems, it is |
|
588 wrjpgcom [switches] [inputfilename] |
|
589 The output file is written to standard output. The input file comes from |
|
590 the named file, or from standard input if no input file is named. |
|
591 |
|
592 On most non-Unix systems, the syntax is |
|
593 wrjpgcom [switches] inputfilename outputfilename |
|
594 where both input and output file names must be given explicitly. |
|
595 |
|
596 wrjpgcom understands three switches: |
|
597 -replace Delete any existing COM blocks from the file. |
|
598 -comment "Comment text" Supply new COM text on command line. |
|
599 -cfile name Read text for new COM block from named file. |
|
600 (Switch names can be abbreviated.) If you have only one line of comment text |
|
601 to add, you can provide it on the command line with -comment. The comment |
|
602 text must be surrounded with quotes so that it is treated as a single |
|
603 argument. Longer comments can be read from a text file. |
|
604 |
|
605 If you give neither -comment nor -cfile, then wrjpgcom will read the comment |
|
606 text from standard input. (In this case an input image file name MUST be |
|
607 supplied, so that the source JPEG file comes from somewhere else.) You can |
|
608 enter multiple lines, up to 64KB worth. Type an end-of-file indicator |
|
609 (usually control-D or control-Z) to terminate the comment text entry. |
|
610 |
|
611 wrjpgcom will not add a COM block if the provided comment string is empty. |
|
612 Therefore -replace -comment "" can be used to delete all COM blocks from a |
|
613 file. |
|
614 |
|
615 These utility programs do not depend on the IJG JPEG library. In |
|
616 particular, the source code for rdjpgcom is intended as an illustration of |
|
617 the minimum amount of code required to parse a JPEG file header correctly. |