Commit | Line | Data |
---|---|---|
e1929140 RR |
1 | .TH JPEGTRAN 1 "3 August 1997" |
2 | .SH NAME | |
3 | jpegtran \- lossless transformation of JPEG files | |
4 | .SH SYNOPSIS | |
5 | .B jpegtran | |
6 | [ | |
7 | .I options | |
8 | ] | |
9 | [ | |
10 | .I filename | |
11 | ] | |
12 | .LP | |
13 | .SH DESCRIPTION | |
14 | .LP | |
15 | .B jpegtran | |
16 | performs various useful transformations of JPEG files. | |
17 | It can translate the coded representation from one variant of JPEG to another, | |
18 | for example from baseline JPEG to progressive JPEG or vice versa. It can also | |
19 | perform some rearrangements of the image data, for example turning an image | |
20 | from landscape to portrait format by rotation. | |
21 | .PP | |
22 | .B jpegtran | |
23 | works by rearranging the compressed data (DCT coefficients), without | |
24 | ever fully decoding the image. Therefore, its transformations are lossless: | |
25 | there is no image degradation at all, which would not be true if you used | |
26 | .B djpeg | |
27 | followed by | |
28 | .B cjpeg | |
29 | to accomplish the same conversion. But by the same token, | |
30 | .B jpegtran | |
31 | cannot perform lossy operations such as changing the image quality. | |
32 | .PP | |
33 | .B jpegtran | |
34 | reads the named JPEG/JFIF file, or the standard input if no file is | |
35 | named, and produces a JPEG/JFIF file on the standard output. | |
36 | .SH OPTIONS | |
37 | All switch names may be abbreviated; for example, | |
38 | .B \-optimize | |
39 | may be written | |
40 | .B \-opt | |
41 | or | |
42 | .BR \-o . | |
43 | Upper and lower case are equivalent. | |
44 | British spellings are also accepted (e.g., | |
45 | .BR \-optimise ), | |
46 | though for brevity these are not mentioned below. | |
47 | .PP | |
48 | To specify the coded JPEG representation used in the output file, | |
49 | .B jpegtran | |
50 | accepts a subset of the switches recognized by | |
51 | .BR cjpeg : | |
52 | .TP | |
53 | .B \-optimize | |
54 | Perform optimization of entropy encoding parameters. | |
55 | .TP | |
56 | .B \-progressive | |
57 | Create progressive JPEG file. | |
58 | .TP | |
59 | .BI \-restart " N" | |
60 | Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is | |
61 | attached to the number. | |
62 | .TP | |
63 | .BI \-scans " file" | |
64 | Use the scan script given in the specified text file. | |
65 | .PP | |
66 | See | |
67 | .BR cjpeg (1) | |
68 | for more details about these switches. | |
69 | If you specify none of these switches, you get a plain baseline-JPEG output | |
70 | file. The quality setting and so forth are determined by the input file. | |
71 | .PP | |
72 | The image can be losslessly transformed by giving one of these switches: | |
73 | .TP | |
74 | .B \-flip horizontal | |
75 | Mirror image horizontally (left-right). | |
76 | .TP | |
77 | .B \-flip vertical | |
78 | Mirror image vertically (top-bottom). | |
79 | .TP | |
80 | .B \-rotate 90 | |
81 | Rotate image 90 degrees clockwise. | |
82 | .TP | |
83 | .B \-rotate 180 | |
84 | Rotate image 180 degrees. | |
85 | .TP | |
86 | .B \-rotate 270 | |
87 | Rotate image 270 degrees clockwise (or 90 ccw). | |
88 | .TP | |
89 | .B \-transpose | |
90 | Transpose image (across UL-to-LR axis). | |
91 | .TP | |
92 | .B \-transverse | |
93 | Transverse transpose (across UR-to-LL axis). | |
94 | .PP | |
95 | The transpose transformation has no restrictions regarding image dimensions. | |
96 | The other transformations operate rather oddly if the image dimensions are not | |
97 | a multiple of the iMCU size (usually 8 or 16 pixels), because they can only | |
98 | transform complete blocks of DCT coefficient data in the desired way. | |
99 | .PP | |
100 | .BR jpegtran 's | |
101 | default behavior when transforming an odd-size image is designed | |
102 | to preserve exact reversibility and mathematical consistency of the | |
103 | transformation set. As stated, transpose is able to flip the entire image | |
104 | area. Horizontal mirroring leaves any partial iMCU column at the right edge | |
105 | untouched, but is able to flip all rows of the image. Similarly, vertical | |
106 | mirroring leaves any partial iMCU row at the bottom edge untouched, but is | |
107 | able to flip all columns. The other transforms can be built up as sequences | |
108 | of transpose and flip operations; for consistency, their actions on edge | |
109 | pixels are defined to be the same as the end result of the corresponding | |
110 | transpose-and-flip sequence. | |
111 | .PP | |
112 | For practical use, you may prefer to discard any untransformable edge pixels | |
113 | rather than having a strange-looking strip along the right and/or bottom edges | |
114 | of a transformed image. To do this, add the | |
115 | .B \-trim | |
116 | switch: | |
117 | .TP | |
118 | .B \-trim | |
119 | Drop non-transformable edge blocks. | |
120 | .PP | |
121 | Obviously, a transformation with | |
122 | .B \-trim | |
123 | is not reversible, so strictly speaking | |
124 | .B jpegtran | |
125 | with this switch is not lossless. Also, the expected mathematical | |
126 | equivalences between the transformations no longer hold. For example, | |
127 | .B \-rot 270 -trim | |
128 | trims only the bottom edge, but | |
129 | .B \-rot 90 -trim | |
130 | followed by | |
131 | .B \-rot 180 -trim | |
132 | trims both edges. | |
133 | .PP | |
134 | Another not-strictly-lossless transformation switch is: | |
135 | .TP | |
136 | .B \-grayscale | |
137 | Force grayscale output. | |
138 | .PP | |
139 | This option discards the chrominance channels if the input image is YCbCr | |
140 | (ie, a standard color JPEG), resulting in a grayscale JPEG file. The | |
141 | luminance channel is preserved exactly, so this is a better method of reducing | |
142 | to grayscale than decompression, conversion, and recompression. This switch | |
143 | is particularly handy for fixing a monochrome picture that was mistakenly | |
144 | encoded as a color JPEG. (In such a case, the space savings from getting rid | |
145 | of the near-empty chroma channels won't be large; but the decoding time for | |
146 | a grayscale JPEG is substantially less than that for a color JPEG.) | |
147 | .PP | |
148 | .B jpegtran | |
149 | also recognizes these switches that control what to do with "extra" markers, | |
150 | such as comment blocks: | |
151 | .TP | |
152 | .B \-copy none | |
153 | Copy no extra markers from source file. This setting suppresses all | |
154 | comments and other excess baggage present in the source file. | |
155 | .TP | |
156 | .B \-copy comments | |
157 | Copy only comment markers. This setting copies comments from the source file, | |
158 | but discards any other inessential data. | |
159 | .TP | |
160 | .B \-copy all | |
161 | Copy all extra markers. This setting preserves miscellaneous markers | |
162 | found in the source file, such as JFIF thumbnails and Photoshop settings. | |
163 | In some files these extra markers can be sizable. | |
164 | .PP | |
165 | The default behavior is | |
166 | .BR "\-copy comments" . | |
167 | (Note: in IJG releases v6 and v6a, | |
168 | .B jpegtran | |
169 | always did the equivalent of | |
170 | .BR "\-copy none" .) | |
171 | .PP | |
172 | Additional switches recognized by jpegtran are: | |
173 | .TP | |
174 | .BI \-maxmemory " N" | |
175 | Set limit for amount of memory to use in processing large images. Value is | |
176 | in thousands of bytes, or millions of bytes if "M" is attached to the | |
177 | number. For example, | |
178 | .B \-max 4m | |
179 | selects 4000000 bytes. If more space is needed, temporary files will be used. | |
180 | .TP | |
181 | .BI \-outfile " name" | |
182 | Send output image to the named file, not to standard output. | |
183 | .TP | |
184 | .B \-verbose | |
185 | Enable debug printout. More | |
186 | .BR \-v 's | |
187 | give more output. Also, version information is printed at startup. | |
188 | .TP | |
189 | .B \-debug | |
190 | Same as | |
191 | .BR \-verbose . | |
192 | .SH EXAMPLES | |
193 | .LP | |
194 | This example converts a baseline JPEG file to progressive form: | |
195 | .IP | |
196 | .B jpegtran \-progressive | |
197 | .I foo.jpg | |
198 | .B > | |
199 | .I fooprog.jpg | |
200 | .PP | |
201 | This example rotates an image 90 degrees clockwise, discarding any | |
202 | unrotatable edge pixels: | |
203 | .IP | |
204 | .B jpegtran \-rot 90 -trim | |
205 | .I foo.jpg | |
206 | .B > | |
207 | .I foo90.jpg | |
208 | .SH ENVIRONMENT | |
209 | .TP | |
210 | .B JPEGMEM | |
211 | If this environment variable is set, its value is the default memory limit. | |
212 | The value is specified as described for the | |
213 | .B \-maxmemory | |
214 | switch. | |
215 | .B JPEGMEM | |
216 | overrides the default value specified when the program was compiled, and | |
217 | itself is overridden by an explicit | |
218 | .BR \-maxmemory . | |
219 | .SH SEE ALSO | |
220 | .BR cjpeg (1), | |
221 | .BR djpeg (1), | |
222 | .BR rdjpgcom (1), | |
223 | .BR wrjpgcom (1) | |
224 | .br | |
225 | Wallace, Gregory K. "The JPEG Still Picture Compression Standard", | |
226 | Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. | |
227 | .SH AUTHOR | |
228 | Independent JPEG Group | |
229 | .SH BUGS | |
230 | Arithmetic coding is not supported for legal reasons. | |
231 | .PP | |
232 | The transform options can't transform odd-size images perfectly. Use | |
233 | .B \-trim | |
234 | if you don't like the results without it. | |
235 | .PP | |
236 | The entire image is read into memory and then written out again, even in | |
237 | cases where this isn't really necessary. Expect swapping on large images, | |
238 | especially when using the more complex transform options. |