1
by Tom Gall
Import upstream version 1.1.90+svn702 |
1 |
.TH JPEGTRAN 1 "11 October 2010" |
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 |
.B \-arithmetic |
|
64 |
Use arithmetic coding. |
|
65 |
.TP
|
|
66 |
.BI \-scans " file" |
|
67 |
Use the scan script given in the specified text file. |
|
68 |
.PP
|
|
69 |
See |
|
70 |
.BR cjpeg (1) |
|
71 |
for more details about these switches. |
|
72 |
If you specify none of these switches, you get a plain baseline-JPEG output |
|
73 |
file. The quality setting and so forth are determined by the input file. |
|
74 |
.PP
|
|
75 |
The image can be losslessly transformed by giving one of these switches: |
|
76 |
.TP
|
|
77 |
.B \-flip horizontal |
|
78 |
Mirror image horizontally (left-right). |
|
79 |
.TP
|
|
80 |
.B \-flip vertical |
|
81 |
Mirror image vertically (top-bottom). |
|
82 |
.TP
|
|
83 |
.B \-rotate 90 |
|
84 |
Rotate image 90 degrees clockwise. |
|
85 |
.TP
|
|
86 |
.B \-rotate 180 |
|
87 |
Rotate image 180 degrees. |
|
88 |
.TP
|
|
89 |
.B \-rotate 270 |
|
90 |
Rotate image 270 degrees clockwise (or 90 ccw). |
|
91 |
.TP
|
|
92 |
.B \-transpose |
|
93 |
Transpose image (across UL-to-LR axis). |
|
94 |
.TP
|
|
95 |
.B \-transverse |
|
96 |
Transverse transpose (across UR-to-LL axis). |
|
97 |
.PP
|
|
98 |
The transpose transformation has no restrictions regarding image dimensions. |
|
99 |
The other transformations operate rather oddly if the image dimensions are not |
|
100 |
a multiple of the iMCU size (usually 8 or 16 pixels), because they can only |
|
101 |
transform complete blocks of DCT coefficient data in the desired way. |
|
102 |
.PP
|
|
103 |
.BR jpegtran 's |
|
104 |
default behavior when transforming an odd-size image is designed |
|
105 |
to preserve exact reversibility and mathematical consistency of the |
|
106 |
transformation set. As stated, transpose is able to flip the entire image |
|
107 |
area. Horizontal mirroring leaves any partial iMCU column at the right edge |
|
108 |
untouched, but is able to flip all rows of the image. Similarly, vertical |
|
109 |
mirroring leaves any partial iMCU row at the bottom edge untouched, but is |
|
110 |
able to flip all columns. The other transforms can be built up as sequences |
|
111 |
of transpose and flip operations; for consistency, their actions on edge |
|
112 |
pixels are defined to be the same as the end result of the corresponding |
|
113 |
transpose-and-flip sequence. |
|
114 |
.PP
|
|
115 |
For practical use, you may prefer to discard any untransformable edge pixels |
|
116 |
rather than having a strange-looking strip along the right and/or bottom edges |
|
117 |
of a transformed image. To do this, add the |
|
118 |
.B \-trim |
|
119 |
switch: |
|
120 |
.TP
|
|
121 |
.B \-trim |
|
122 |
Drop non-transformable edge blocks. |
|
123 |
.IP
|
|
124 |
Obviously, a transformation with |
|
125 |
.B \-trim |
|
126 |
is not reversible, so strictly speaking |
|
127 |
.B jpegtran |
|
128 |
with this switch is not lossless. Also, the expected mathematical |
|
129 |
equivalences between the transformations no longer hold. For example, |
|
130 |
.B \-rot 270 -trim |
|
131 |
trims only the bottom edge, but |
|
132 |
.B \-rot 90 -trim |
|
133 |
followed by |
|
134 |
.B \-rot 180 -trim |
|
135 |
trims both edges. |
|
136 |
.TP
|
|
137 |
.B \-perfect |
|
138 |
If you are only interested in perfect transformations, add the |
|
139 |
.B \-perfect |
|
140 |
switch. This causes |
|
141 |
.B jpegtran |
|
142 |
to fail with an error if the transformation is not perfect. |
|
143 |
.IP
|
|
144 |
For example, you may want to do |
|
145 |
.IP
|
|
146 |
.B (jpegtran \-rot 90 -perfect |
|
147 |
.I foo.jpg |
|
148 |
.B || djpeg |
|
149 |
.I foo.jpg |
|
150 |
.B | pnmflip \-r90 | cjpeg) |
|
151 |
.IP
|
|
152 |
to do a perfect rotation, if available, or an approximated one if not. |
|
153 |
.TP
|
|
154 |
.B \-crop WxH+X+Y |
|
155 |
Crop the image to a rectangular region of width W and height H, starting at |
|
156 |
point X,Y. The lossless crop feature discards data outside of a given image |
|
157 |
region but losslessly preserves what is inside. Like the rotate and flip |
|
158 |
transforms, lossless crop is restricted by the current JPEG format; the upper |
|
159 |
left corner of the selected region must fall on an iMCU boundary. If it |
|
160 |
doesn't, then it is silently moved up and/or left to the nearest iMCU boundary |
|
161 |
(the lower right corner is unchanged.) |
|
162 |
.PP
|
|
163 |
Other not-strictly-lossless transformation switches are: |
|
164 |
.TP
|
|
165 |
.B \-grayscale |
|
166 |
Force grayscale output. |
|
167 |
.IP
|
|
168 |
This option discards the chrominance channels if the input image is YCbCr |
|
169 |
(ie, a standard color JPEG), resulting in a grayscale JPEG file. The |
|
170 |
luminance channel is preserved exactly, so this is a better method of reducing |
|
171 |
to grayscale than decompression, conversion, and recompression. This switch |
|
172 |
is particularly handy for fixing a monochrome picture that was mistakenly |
|
173 |
encoded as a color JPEG. (In such a case, the space savings from getting rid |
|
174 |
of the near-empty chroma channels won't be large; but the decoding time for |
|
175 |
a grayscale JPEG is substantially less than that for a color JPEG.) |
|
176 |
.PP
|
|
177 |
.B jpegtran |
|
178 |
also recognizes these switches that control what to do with "extra" markers, |
|
179 |
such as comment blocks: |
|
180 |
.TP
|
|
181 |
.B \-copy none |
|
182 |
Copy no extra markers from source file. This setting suppresses all |
|
183 |
comments and other excess baggage present in the source file. |
|
184 |
.TP
|
|
185 |
.B \-copy comments |
|
186 |
Copy only comment markers. This setting copies comments from the source file |
|
187 |
but discards any other data which is inessential for image display. |
|
188 |
.TP
|
|
189 |
.B \-copy all |
|
190 |
Copy all extra markers. This setting preserves miscellaneous markers |
|
191 |
found in the source file, such as JFIF thumbnails, Exif data, and Photoshop |
|
192 |
settings. In some files, these extra markers can be sizable. |
|
193 |
.PP
|
|
194 |
The default behavior is \fB-copy comments\fR. (Note: in IJG releases v6 and |
|
195 |
v6a, \fBjpegtran\fR always did the equivalent of \fB-copy none\fR.) |
|
196 |
.PP
|
|
197 |
Additional switches recognized by jpegtran are: |
|
198 |
.TP
|
|
199 |
.BI \-maxmemory " N" |
|
200 |
Set limit for amount of memory to use in processing large images. Value is |
|
201 |
in thousands of bytes, or millions of bytes if "M" is attached to the |
|
202 |
number. For example, |
|
203 |
.B \-max 4m |
|
204 |
selects 4000000 bytes. If more space is needed, temporary files will be used. |
|
205 |
.TP
|
|
206 |
.BI \-outfile " name" |
|
207 |
Send output image to the named file, not to standard output. |
|
208 |
.TP
|
|
209 |
.B \-verbose |
|
210 |
Enable debug printout. More |
|
211 |
.BR \-v 's |
|
212 |
give more output. Also, version information is printed at startup. |
|
213 |
.TP
|
|
214 |
.B \-debug |
|
215 |
Same as |
|
216 |
.BR \-verbose . |
|
217 |
.SH EXAMPLES |
|
218 |
.LP
|
|
219 |
This example converts a baseline JPEG file to progressive form: |
|
220 |
.IP
|
|
221 |
.B jpegtran \-progressive |
|
222 |
.I foo.jpg |
|
223 |
.B > |
|
224 |
.I fooprog.jpg |
|
225 |
.PP
|
|
226 |
This example rotates an image 90 degrees clockwise, discarding any |
|
227 |
unrotatable edge pixels: |
|
228 |
.IP
|
|
229 |
.B jpegtran \-rot 90 -trim |
|
230 |
.I foo.jpg |
|
231 |
.B > |
|
232 |
.I foo90.jpg |
|
233 |
.SH ENVIRONMENT |
|
234 |
.TP
|
|
235 |
.B JPEGMEM |
|
236 |
If this environment variable is set, its value is the default memory limit. |
|
237 |
The value is specified as described for the |
|
238 |
.B \-maxmemory |
|
239 |
switch. |
|
240 |
.B JPEGMEM |
|
241 |
overrides the default value specified when the program was compiled, and |
|
242 |
itself is overridden by an explicit |
|
243 |
.BR \-maxmemory . |
|
244 |
.SH SEE ALSO |
|
245 |
.BR cjpeg (1), |
|
246 |
.BR djpeg (1), |
|
247 |
.BR rdjpgcom (1), |
|
248 |
.BR wrjpgcom (1) |
|
249 |
.br
|
|
250 |
Wallace, Gregory K. "The JPEG Still Picture Compression Standard", |
|
251 |
Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. |
|
252 |
.SH AUTHOR |
|
253 |
Independent JPEG Group |
|
254 |
.SH BUGS |
|
255 |
The transform options can't transform odd-size images perfectly. Use |
|
256 |
.B \-trim |
|
257 |
or |
|
258 |
.B \-perfect |
|
259 |
if you don't like the results. |
|
260 |
.PP
|
|
261 |
The entire image is read into memory and then written out again, even in |
|
262 |
cases where this isn't really necessary. Expect swapping on large images, |
|
263 |
especially when using the more complex transform options. |