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