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 explicitely 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/8 with all M from 1 to |
---|
249 | 16. If the /N part is omitted, then M specifies the |
---|
250 | DCT scaled size to be applied on the given input, |
---|
251 | which is currently equivalent to M/8 scaling, since |
---|
252 | the source DCT size is currently always 8. |
---|
253 | Scaling is handy if the image is larger than your |
---|
254 | screen; also, djpeg runs much faster when scaling |
---|
255 | down the output. |
---|
256 | |
---|
257 | -bmp Select BMP output format (Windows flavor). 8-bit |
---|
258 | colormapped format is emitted if -colors or -grayscale |
---|
259 | is specified, or if the JPEG file is gray-scale; |
---|
260 | otherwise, 24-bit full-color format is emitted. |
---|
261 | |
---|
262 | -gif Select GIF output format. Since GIF does not support |
---|
263 | more than 256 colors, -colors 256 is assumed (unless |
---|
264 | you specify a smaller number of colors). If you |
---|
265 | specify -fast, the default number of colors is 216. |
---|
266 | |
---|
267 | -os2 Select BMP output format (OS/2 1.x flavor). 8-bit |
---|
268 | colormapped format is emitted if -colors or -grayscale |
---|
269 | is specified, or if the JPEG file is gray-scale; |
---|
270 | otherwise, 24-bit full-color format is emitted. |
---|
271 | |
---|
272 | -pnm Select PBMPLUS (PPM/PGM) output format (this is the |
---|
273 | default format). PGM is emitted if the JPEG file is |
---|
274 | gray-scale or if -grayscale is specified; otherwise |
---|
275 | PPM is emitted. |
---|
276 | |
---|
277 | -rle Select RLE output format. (Requires URT library.) |
---|
278 | |
---|
279 | -targa Select Targa output format. Gray-scale format is |
---|
280 | emitted if the JPEG file is gray-scale or if |
---|
281 | -grayscale is specified; otherwise, colormapped format |
---|
282 | is emitted if -colors is specified; otherwise, 24-bit |
---|
283 | full-color format is emitted. |
---|
284 | |
---|
285 | Switches for advanced users: |
---|
286 | |
---|
287 | -dct int Use integer DCT method (default). |
---|
288 | -dct fast Use fast integer DCT (less accurate). |
---|
289 | -dct float Use floating-point DCT method. |
---|
290 | The float method is very slightly more accurate than |
---|
291 | the int method, but is much slower unless your machine |
---|
292 | has very fast floating-point hardware. Also note that |
---|
293 | results of the floating-point method may vary slightly |
---|
294 | across machines, while the integer methods should give |
---|
295 | the same results everywhere. The fast integer method |
---|
296 | is much less accurate than the other two. |
---|
297 | |
---|
298 | -dither fs Use Floyd-Steinberg dithering in color quantization. |
---|
299 | -dither ordered Use ordered dithering in color quantization. |
---|
300 | -dither none Do not use dithering in color quantization. |
---|
301 | By default, Floyd-Steinberg dithering is applied when |
---|
302 | quantizing colors; this is slow but usually produces |
---|
303 | the best results. Ordered dither is a compromise |
---|
304 | between speed and quality; no dithering is fast but |
---|
305 | usually looks awful. Note that these switches have |
---|
306 | no effect unless color quantization is being done. |
---|
307 | Ordered dither is only available in -onepass mode. |
---|
308 | |
---|
309 | -map FILE Quantize to the colors used in the specified image |
---|
310 | file. This is useful for producing multiple files |
---|
311 | with identical color maps, or for forcing a predefined |
---|
312 | set of colors to be used. The FILE must be a GIF |
---|
313 | or PPM file. This option overrides -colors and |
---|
314 | -onepass. |
---|
315 | |
---|
316 | -nosmooth Don't use high-quality upsampling. |
---|
317 | |
---|
318 | -onepass Use one-pass instead of two-pass color quantization. |
---|
319 | The one-pass method is faster and needs less memory, |
---|
320 | but it produces a lower-quality image. -onepass is |
---|
321 | ignored unless you also say -colors N. Also, |
---|
322 | the one-pass method is always used for gray-scale |
---|
323 | output (the two-pass method is no improvement then). |
---|
324 | |
---|
325 | -maxmemory N Set limit for amount of memory to use in processing |
---|
326 | large images. Value is in thousands of bytes, or |
---|
327 | millions of bytes if "M" is attached to the number. |
---|
328 | For example, -max 4m selects 4000000 bytes. If more |
---|
329 | space is needed, temporary files will be used. |
---|
330 | |
---|
331 | -verbose Enable debug printout. More -v's give more printout. |
---|
332 | or -debug Also, version information is printed at startup. |
---|
333 | |
---|
334 | |
---|
335 | HINTS FOR CJPEG |
---|
336 | |
---|
337 | Color GIF files are not the ideal input for JPEG; JPEG is really intended for |
---|
338 | compressing full-color (24-bit) images. In particular, don't try to convert |
---|
339 | cartoons, line drawings, and other images that have only a few distinct |
---|
340 | colors. GIF works great on these, JPEG does not. If you want to convert a |
---|
341 | GIF to JPEG, you should experiment with cjpeg's -quality and -smooth options |
---|
342 | to get a satisfactory conversion. -smooth 10 or so is often helpful. |
---|
343 | |
---|
344 | Avoid running an image through a series of JPEG compression/decompression |
---|
345 | cycles. Image quality loss will accumulate; after ten or so cycles the image |
---|
346 | may be noticeably worse than it was after one cycle. It's best to use a |
---|
347 | lossless format while manipulating an image, then convert to JPEG format when |
---|
348 | you are ready to file the image away. |
---|
349 | |
---|
350 | The -optimize option to cjpeg is worth using when you are making a "final" |
---|
351 | version for posting or archiving. It's also a win when you are using low |
---|
352 | quality settings to make very small JPEG files; the percentage improvement |
---|
353 | is often a lot more than it is on larger files. (At present, -optimize |
---|
354 | mode is always selected when generating progressive JPEG files.) |
---|
355 | |
---|
356 | GIF input files are no longer supported, to avoid the Unisys LZW patent. |
---|
357 | (Conversion of GIF files to JPEG is usually a bad idea anyway.) |
---|
358 | |
---|
359 | |
---|
360 | HINTS FOR DJPEG |
---|
361 | |
---|
362 | To get a quick preview of an image, use the -grayscale and/or -scale switches. |
---|
363 | "-grayscale -scale 1/8" is the fastest case. |
---|
364 | |
---|
365 | Several options are available that trade off image quality to gain speed. |
---|
366 | "-fast" turns on the recommended settings. |
---|
367 | |
---|
368 | "-dct fast" and/or "-nosmooth" gain speed at a small sacrifice in quality. |
---|
369 | When producing a color-quantized image, "-onepass -dither ordered" is fast but |
---|
370 | much lower quality than the default behavior. "-dither none" may give |
---|
371 | acceptable results in two-pass mode, but is seldom tolerable in one-pass mode. |
---|
372 | |
---|
373 | If you are fortunate enough to have very fast floating point hardware, |
---|
374 | "-dct float" may be even faster than "-dct fast". But on most machines |
---|
375 | "-dct float" is slower than "-dct int"; in this case it is not worth using, |
---|
376 | because its theoretical accuracy advantage is too small to be significant |
---|
377 | in practice. |
---|
378 | |
---|
379 | Two-pass color quantization requires a good deal of memory; on MS-DOS machines |
---|
380 | it may run out of memory even with -maxmemory 0. In that case you can still |
---|
381 | decompress, with some loss of image quality, by specifying -onepass for |
---|
382 | one-pass quantization. |
---|
383 | |
---|
384 | To avoid the Unisys LZW patent, djpeg produces uncompressed GIF files. These |
---|
385 | are larger than they should be, but are readable by standard GIF decoders. |
---|
386 | |
---|
387 | |
---|
388 | HINTS FOR BOTH PROGRAMS |
---|
389 | |
---|
390 | If more space is needed than will fit in the available main memory (as |
---|
391 | determined by -maxmemory), temporary files will be used. (MS-DOS versions |
---|
392 | will try to get extended or expanded memory first.) The temporary files are |
---|
393 | often rather large: in typical cases they occupy three bytes per pixel, for |
---|
394 | example 3*800*600 = 1.44Mb for an 800x600 image. If you don't have enough |
---|
395 | free disk space, leave out -progressive and -optimize (for cjpeg) or specify |
---|
396 | -onepass (for djpeg). |
---|
397 | |
---|
398 | On MS-DOS, the temporary files are created in the directory named by the TMP |
---|
399 | or TEMP environment variable, or in the current directory if neither of those |
---|
400 | exist. Amiga implementations put the temp files in the directory named by |
---|
401 | JPEGTMP:, so be sure to assign JPEGTMP: to a disk partition with adequate free |
---|
402 | space. |
---|
403 | |
---|
404 | The default memory usage limit (-maxmemory) is set when the software is |
---|
405 | compiled. If you get an "insufficient memory" error, try specifying a smaller |
---|
406 | -maxmemory value, even -maxmemory 0 to use the absolute minimum space. You |
---|
407 | may want to recompile with a smaller default value if this happens often. |
---|
408 | |
---|
409 | On machines that have "environment" variables, you can define the environment |
---|
410 | variable JPEGMEM to set the default memory limit. The value is specified as |
---|
411 | described for the -maxmemory switch. JPEGMEM overrides the default value |
---|
412 | specified when the program was compiled, and itself is overridden by an |
---|
413 | explicit -maxmemory switch. |
---|
414 | |
---|
415 | On MS-DOS machines, -maxmemory is the amount of main (conventional) memory to |
---|
416 | use. (Extended or expanded memory is also used if available.) Most |
---|
417 | DOS-specific versions of this software do their own memory space estimation |
---|
418 | and do not need you to specify -maxmemory. |
---|
419 | |
---|
420 | |
---|
421 | JPEGTRAN |
---|
422 | |
---|
423 | jpegtran performs various useful transformations of JPEG files. |
---|
424 | It can translate the coded representation from one variant of JPEG to another, |
---|
425 | for example from baseline JPEG to progressive JPEG or vice versa. It can also |
---|
426 | perform some rearrangements of the image data, for example turning an image |
---|
427 | from landscape to portrait format by rotation. |
---|
428 | |
---|
429 | jpegtran works by rearranging the compressed data (DCT coefficients), without |
---|
430 | ever fully decoding the image. Therefore, its transformations are lossless: |
---|
431 | there is no image degradation at all, which would not be true if you used |
---|
432 | djpeg followed by cjpeg to accomplish the same conversion. But by the same |
---|
433 | token, jpegtran cannot perform lossy operations such as changing the image |
---|
434 | quality. |
---|
435 | |
---|
436 | jpegtran uses a command line syntax similar to cjpeg or djpeg. |
---|
437 | On Unix-like systems, you say: |
---|
438 | jpegtran [switches] [inputfile] >outputfile |
---|
439 | On most non-Unix systems, you say: |
---|
440 | jpegtran [switches] inputfile outputfile |
---|
441 | where both the input and output files are JPEG files. |
---|
442 | |
---|
443 | To specify the coded JPEG representation used in the output file, |
---|
444 | jpegtran accepts a subset of the switches recognized by cjpeg: |
---|
445 | -optimize Perform optimization of entropy encoding parameters. |
---|
446 | -progressive Create progressive JPEG file. |
---|
447 | -restart N Emit a JPEG restart marker every N MCU rows, or every |
---|
448 | N MCU blocks if "B" is attached to the number. |
---|
449 | -arithmetic Use arithmetic coding. |
---|
450 | -scans file Use the scan script given in the specified text file. |
---|
451 | See the previous discussion of cjpeg for more details about these switches. |
---|
452 | If you specify none of these switches, you get a plain baseline-JPEG output |
---|
453 | file. The quality setting and so forth are determined by the input file. |
---|
454 | |
---|
455 | The image can be losslessly transformed by giving one of these switches: |
---|
456 | -flip horizontal Mirror image horizontally (left-right). |
---|
457 | -flip vertical Mirror image vertically (top-bottom). |
---|
458 | -rotate 90 Rotate image 90 degrees clockwise. |
---|
459 | -rotate 180 Rotate image 180 degrees. |
---|
460 | -rotate 270 Rotate image 270 degrees clockwise (or 90 ccw). |
---|
461 | -transpose Transpose image (across UL-to-LR axis). |
---|
462 | -transverse Transverse transpose (across UR-to-LL axis). |
---|
463 | |
---|
464 | The transpose transformation has no restrictions regarding image dimensions. |
---|
465 | The other transformations operate rather oddly if the image dimensions are not |
---|
466 | a multiple of the iMCU size (usually 8 or 16 pixels), because they can only |
---|
467 | transform complete blocks of DCT coefficient data in the desired way. |
---|
468 | |
---|
469 | jpegtran's default behavior when transforming an odd-size image is designed |
---|
470 | to preserve exact reversibility and mathematical consistency of the |
---|
471 | transformation set. As stated, transpose is able to flip the entire image |
---|
472 | area. Horizontal mirroring leaves any partial iMCU column at the right edge |
---|
473 | untouched, but is able to flip all rows of the image. Similarly, vertical |
---|
474 | mirroring leaves any partial iMCU row at the bottom edge untouched, but is |
---|
475 | able to flip all columns. The other transforms can be built up as sequences |
---|
476 | of transpose and flip operations; for consistency, their actions on edge |
---|
477 | pixels are defined to be the same as the end result of the corresponding |
---|
478 | transpose-and-flip sequence. |
---|
479 | |
---|
480 | For practical use, you may prefer to discard any untransformable edge pixels |
---|
481 | rather than having a strange-looking strip along the right and/or bottom edges |
---|
482 | of a transformed image. To do this, add the -trim switch: |
---|
483 | -trim Drop non-transformable edge blocks. |
---|
484 | Obviously, a transformation with -trim is not reversible, so strictly speaking |
---|
485 | jpegtran with this switch is not lossless. Also, the expected mathematical |
---|
486 | equivalences between the transformations no longer hold. For example, |
---|
487 | "-rot 270 -trim" trims only the bottom edge, but "-rot 90 -trim" followed by |
---|
488 | "-rot 180 -trim" trims both edges. |
---|
489 | |
---|
490 | If you are only interested in perfect transformation, add the -perfect switch: |
---|
491 | -perfect Fails with an error if the transformation is not |
---|
492 | perfect. |
---|
493 | For example you may want to do |
---|
494 | jpegtran -rot 90 -perfect foo.jpg || djpeg foo.jpg | pnmflip -r90 | cjpeg |
---|
495 | to do a perfect rotation if available or an approximated one if not. |
---|
496 | |
---|
497 | We also offer a lossless-crop option, which discards data outside a given |
---|
498 | image region but losslessly preserves what is inside. Like the rotate and |
---|
499 | flip transforms, lossless crop is restricted by the current JPEG format: the |
---|
500 | upper left corner of the selected region must fall on an iMCU boundary. If |
---|
501 | this does not hold for the given crop parameters, we silently move the upper |
---|
502 | left corner up and/or left to make it so, simultaneously increasing the region |
---|
503 | dimensions to keep the lower right crop corner unchanged. (Thus, the output |
---|
504 | image covers at least the requested region, but may cover more.) |
---|
505 | |
---|
506 | The image can be losslessly cropped by giving the switch: |
---|
507 | -crop WxH+X+Y Crop to a rectangular subarea of width W, height H |
---|
508 | starting at point X,Y. |
---|
509 | |
---|
510 | Another not-strictly-lossless transformation switch is: |
---|
511 | -grayscale Force grayscale output. |
---|
512 | This option discards the chrominance channels if the input image is YCbCr |
---|
513 | (ie, a standard color JPEG), resulting in a grayscale JPEG file. The |
---|
514 | luminance channel is preserved exactly, so this is a better method of reducing |
---|
515 | to grayscale than decompression, conversion, and recompression. This switch |
---|
516 | is particularly handy for fixing a monochrome picture that was mistakenly |
---|
517 | encoded as a color JPEG. (In such a case, the space savings from getting rid |
---|
518 | of the near-empty chroma channels won't be large; but the decoding time for |
---|
519 | a grayscale JPEG is substantially less than that for a color JPEG.) |
---|
520 | |
---|
521 | jpegtran also recognizes these switches that control what to do with "extra" |
---|
522 | markers, such as comment blocks: |
---|
523 | -copy none Copy no extra markers from source file. This setting |
---|
524 | suppresses all comments and other excess baggage |
---|
525 | present in the source file. |
---|
526 | -copy comments Copy only comment markers. This setting copies |
---|
527 | comments from the source file, but discards |
---|
528 | any other inessential (for image display) data. |
---|
529 | -copy all Copy all extra markers. This setting preserves |
---|
530 | miscellaneous markers found in the source file, such |
---|
531 | as JFIF thumbnails, Exif data, and Photoshop settings. |
---|
532 | In some files these extra markers can be sizable. |
---|
533 | The default behavior is -copy comments. (Note: in IJG releases v6 and v6a, |
---|
534 | jpegtran always did the equivalent of -copy none.) |
---|
535 | |
---|
536 | Additional switches recognized by jpegtran are: |
---|
537 | -outfile filename |
---|
538 | -maxmemory N |
---|
539 | -verbose |
---|
540 | -debug |
---|
541 | These work the same as in cjpeg or djpeg. |
---|
542 | |
---|
543 | |
---|
544 | THE COMMENT UTILITIES |
---|
545 | |
---|
546 | The JPEG standard allows "comment" (COM) blocks to occur within a JPEG file. |
---|
547 | Although the standard doesn't actually define what COM blocks are for, they |
---|
548 | are widely used to hold user-supplied text strings. This lets you add |
---|
549 | annotations, titles, index terms, etc to your JPEG files, and later retrieve |
---|
550 | them as text. COM blocks do not interfere with the image stored in the JPEG |
---|
551 | file. The maximum size of a COM block is 64K, but you can have as many of |
---|
552 | them as you like in one JPEG file. |
---|
553 | |
---|
554 | We provide two utility programs to display COM block contents and add COM |
---|
555 | blocks to a JPEG file. |
---|
556 | |
---|
557 | rdjpgcom searches a JPEG file and prints the contents of any COM blocks on |
---|
558 | standard output. The command line syntax is |
---|
559 | rdjpgcom [-raw] [-verbose] [inputfilename] |
---|
560 | The switch "-raw" (or just "-r") causes rdjpgcom to also output non-printable |
---|
561 | characters in comments, which are normally escaped for security reasons. |
---|
562 | The switch "-verbose" (or just "-v") causes rdjpgcom to also display the JPEG |
---|
563 | image dimensions. If you omit the input file name from the command line, |
---|
564 | the JPEG file is read from standard input. (This may not work on some |
---|
565 | operating systems, if binary data can't be read from stdin.) |
---|
566 | |
---|
567 | wrjpgcom adds a COM block, containing text you provide, to a JPEG file. |
---|
568 | Ordinarily, the COM block is added after any existing COM blocks, but you |
---|
569 | can delete the old COM blocks if you wish. wrjpgcom produces a new JPEG |
---|
570 | file; it does not modify the input file. DO NOT try to overwrite the input |
---|
571 | file by directing wrjpgcom's output back into it; on most systems this will |
---|
572 | just destroy your file. |
---|
573 | |
---|
574 | The command line syntax for wrjpgcom is similar to cjpeg's. On Unix-like |
---|
575 | systems, it is |
---|
576 | wrjpgcom [switches] [inputfilename] |
---|
577 | The output file is written to standard output. The input file comes from |
---|
578 | the named file, or from standard input if no input file is named. |
---|
579 | |
---|
580 | On most non-Unix systems, the syntax is |
---|
581 | wrjpgcom [switches] inputfilename outputfilename |
---|
582 | where both input and output file names must be given explicitly. |
---|
583 | |
---|
584 | wrjpgcom understands three switches: |
---|
585 | -replace Delete any existing COM blocks from the file. |
---|
586 | -comment "Comment text" Supply new COM text on command line. |
---|
587 | -cfile name Read text for new COM block from named file. |
---|
588 | (Switch names can be abbreviated.) If you have only one line of comment text |
---|
589 | to add, you can provide it on the command line with -comment. The comment |
---|
590 | text must be surrounded with quotes so that it is treated as a single |
---|
591 | argument. Longer comments can be read from a text file. |
---|
592 | |
---|
593 | If you give neither -comment nor -cfile, then wrjpgcom will read the comment |
---|
594 | text from standard input. (In this case an input image file name MUST be |
---|
595 | supplied, so that the source JPEG file comes from somewhere else.) You can |
---|
596 | enter multiple lines, up to 64KB worth. Type an end-of-file indicator |
---|
597 | (usually control-D or control-Z) to terminate the comment text entry. |
---|
598 | |
---|
599 | wrjpgcom will not add a COM block if the provided comment string is empty. |
---|
600 | Therefore -replace -comment "" can be used to delete all COM blocks from a |
---|
601 | file. |
---|
602 | |
---|
603 | These utility programs do not depend on the IJG JPEG library. In |
---|
604 | particular, the source code for rdjpgcom is intended as an illustration of |
---|
605 | the minimum amount of code required to parse a JPEG file header correctly. |
---|