blob: f10cdbb6b5c7bc9afbb6d80b06675c51be1dfb88 [file] [log] [blame]
DRC39ea5622010-10-12 01:55:31 +00001.TH JPEGTRAN 1 "11 October 2010"
Thomas G. Lanebc79e061995-08-02 00:00:00 +00002.SH NAME
Thomas G. Lane5ead57a1998-03-27 00:00:00 +00003jpegtran \- lossless transformation of JPEG files
Thomas G. Lanebc79e061995-08-02 00:00:00 +00004.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
Thomas G. Lane5ead57a1998-03-27 00:00:00 +000016performs various useful transformations of JPEG files.
17It can translate the coded representation from one variant of JPEG to another,
18for example from baseline JPEG to progressive JPEG or vice versa. It can also
19perform some rearrangements of the image data, for example turning an image
20from landscape to portrait format by rotation.
21.PP
22.B jpegtran
23works by rearranging the compressed data (DCT coefficients), without
24ever fully decoding the image. Therefore, its transformations are lossless:
25there is no image degradation at all, which would not be true if you used
Thomas G. Lanebc79e061995-08-02 00:00:00 +000026.B djpeg
27followed by
Thomas G. Lane5ead57a1998-03-27 00:00:00 +000028.B cjpeg
29to accomplish the same conversion. But by the same token,
30.B jpegtran
31cannot perform lossy operations such as changing the image quality.
32.PP
Thomas G. Lanebc79e061995-08-02 00:00:00 +000033.B jpegtran
34reads the named JPEG/JFIF file, or the standard input if no file is
35named, and produces a JPEG/JFIF file on the standard output.
36.SH OPTIONS
Thomas G. Lanebc79e061995-08-02 00:00:00 +000037All switch names may be abbreviated; for example,
38.B \-optimize
39may be written
40.B \-opt
41or
42.BR \-o .
43Upper and lower case are equivalent.
44British spellings are also accepted (e.g.,
45.BR \-optimise ),
46though for brevity these are not mentioned below.
47.PP
Thomas G. Lane5ead57a1998-03-27 00:00:00 +000048To specify the coded JPEG representation used in the output file,
49.B jpegtran
50accepts a subset of the switches recognized by
51.BR cjpeg :
Thomas G. Lanebc79e061995-08-02 00:00:00 +000052.TP
53.B \-optimize
Thomas G. Lane5ead57a1998-03-27 00:00:00 +000054Perform optimization of entropy encoding parameters.
Thomas G. Lanebc79e061995-08-02 00:00:00 +000055.TP
56.B \-progressive
Thomas G. Lane5ead57a1998-03-27 00:00:00 +000057Create progressive JPEG file.
Thomas G. Lanebc79e061995-08-02 00:00:00 +000058.TP
59.BI \-restart " N"
60Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is
61attached to the number.
Thomas G. Lane5ead57a1998-03-27 00:00:00 +000062.TP
Guido Vollbeding5996a252009-06-27 00:00:00 +000063.B \-arithmetic
64Use arithmetic coding.
65.TP
Thomas G. Lane5ead57a1998-03-27 00:00:00 +000066.BI \-scans " file"
67Use the scan script given in the specified text file.
68.PP
69See
70.BR cjpeg (1)
71for more details about these switches.
72If you specify none of these switches, you get a plain baseline-JPEG output
73file. The quality setting and so forth are determined by the input file.
74.PP
75The image can be losslessly transformed by giving one of these switches:
76.TP
77.B \-flip horizontal
78Mirror image horizontally (left-right).
79.TP
80.B \-flip vertical
81Mirror image vertically (top-bottom).
82.TP
83.B \-rotate 90
84Rotate image 90 degrees clockwise.
85.TP
86.B \-rotate 180
87Rotate image 180 degrees.
88.TP
89.B \-rotate 270
90Rotate image 270 degrees clockwise (or 90 ccw).
91.TP
92.B \-transpose
93Transpose image (across UL-to-LR axis).
94.TP
95.B \-transverse
96Transverse transpose (across UR-to-LL axis).
DRC39ea5622010-10-12 01:55:31 +000097.PP
Thomas G. Lane5ead57a1998-03-27 00:00:00 +000098The transpose transformation has no restrictions regarding image dimensions.
99The other transformations operate rather oddly if the image dimensions are not
100a multiple of the iMCU size (usually 8 or 16 pixels), because they can only
101transform complete blocks of DCT coefficient data in the desired way.
DRC39ea5622010-10-12 01:55:31 +0000102.PP
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000103.BR jpegtran 's
104default behavior when transforming an odd-size image is designed
105to preserve exact reversibility and mathematical consistency of the
106transformation set. As stated, transpose is able to flip the entire image
107area. Horizontal mirroring leaves any partial iMCU column at the right edge
108untouched, but is able to flip all rows of the image. Similarly, vertical
109mirroring leaves any partial iMCU row at the bottom edge untouched, but is
110able to flip all columns. The other transforms can be built up as sequences
111of transpose and flip operations; for consistency, their actions on edge
112pixels are defined to be the same as the end result of the corresponding
113transpose-and-flip sequence.
DRC39ea5622010-10-12 01:55:31 +0000114.PP
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000115For practical use, you may prefer to discard any untransformable edge pixels
116rather than having a strange-looking strip along the right and/or bottom edges
117of a transformed image. To do this, add the
118.B \-trim
119switch:
120.TP
121.B \-trim
122Drop non-transformable edge blocks.
Guido Vollbeding5996a252009-06-27 00:00:00 +0000123.IP
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000124Obviously, a transformation with
125.B \-trim
126is not reversible, so strictly speaking
127.B jpegtran
128with this switch is not lossless. Also, the expected mathematical
129equivalences between the transformations no longer hold. For example,
130.B \-rot 270 -trim
131trims only the bottom edge, but
132.B \-rot 90 -trim
133followed by
134.B \-rot 180 -trim
135trims both edges.
Guido Vollbeding5996a252009-06-27 00:00:00 +0000136.TP
137.B \-perfect
DRC39ea5622010-10-12 01:55:31 +0000138If you are only interested in perfect transformations, add the
139.B \-perfect
140switch. This causes
141.B jpegtran
142to fail with an error if the transformation is not perfect.
Guido Vollbeding5996a252009-06-27 00:00:00 +0000143.IP
DRC39ea5622010-10-12 01:55:31 +0000144For example, you may want to do
Guido Vollbeding5996a252009-06-27 00:00:00 +0000145.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
DRC39ea5622010-10-12 01:55:31 +0000152to do a perfect rotation, if available, or an approximated one if not.
Guido Vollbeding5996a252009-06-27 00:00:00 +0000153.TP
154.B \-crop WxH+X+Y
DRC39ea5622010-10-12 01:55:31 +0000155Crop the image to a rectangular region of width W and height H, starting at
156point X,Y. The lossless crop feature discards data outside of a given image
157region but losslessly preserves what is inside. Like the rotate and flip
158transforms, lossless crop is restricted by the current JPEG format; the upper
159left corner of the selected region must fall on an iMCU boundary. If it
160doesn't, then it is silently moved up and/or left to the nearest iMCU boundary
161(the lower right corner is unchanged.)
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000162.PP
Guido Vollbeding989630f2010-01-10 00:00:00 +0000163Other not-strictly-lossless transformation switches are:
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000164.TP
165.B \-grayscale
166Force grayscale output.
Guido Vollbeding5996a252009-06-27 00:00:00 +0000167.IP
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000168This option discards the chrominance channels if the input image is YCbCr
169(ie, a standard color JPEG), resulting in a grayscale JPEG file. The
170luminance channel is preserved exactly, so this is a better method of reducing
171to grayscale than decompression, conversion, and recompression. This switch
172is particularly handy for fixing a monochrome picture that was mistakenly
173encoded as a color JPEG. (In such a case, the space savings from getting rid
174of the near-empty chroma channels won't be large; but the decoding time for
175a grayscale JPEG is substantially less than that for a color JPEG.)
176.PP
177.B jpegtran
178also recognizes these switches that control what to do with "extra" markers,
179such as comment blocks:
180.TP
181.B \-copy none
182Copy no extra markers from source file. This setting suppresses all
183comments and other excess baggage present in the source file.
184.TP
185.B \-copy comments
DRC39ea5622010-10-12 01:55:31 +0000186Copy only comment markers. This setting copies comments from the source file
187but discards any other data which is inessential for image display.
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000188.TP
189.B \-copy all
190Copy all extra markers. This setting preserves miscellaneous markers
Guido Vollbeding5996a252009-06-27 00:00:00 +0000191found in the source file, such as JFIF thumbnails, Exif data, and Photoshop
DRC39ea5622010-10-12 01:55:31 +0000192settings. In some files, these extra markers can be sizable.
193.PP
194The default behavior is \fB-copy comments\fR. (Note: in IJG releases v6 and
195v6a, \fBjpegtran\fR always did the equivalent of \fB-copy none\fR.)
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000196.PP
197Additional switches recognized by jpegtran are:
Thomas G. Lanebc79e061995-08-02 00:00:00 +0000198.TP
199.BI \-maxmemory " N"
200Set limit for amount of memory to use in processing large images. Value is
201in thousands of bytes, or millions of bytes if "M" is attached to the
202number. For example,
203.B \-max 4m
204selects 4000000 bytes. If more space is needed, temporary files will be used.
205.TP
206.BI \-outfile " name"
207Send output image to the named file, not to standard output.
208.TP
209.B \-verbose
210Enable debug printout. More
211.BR \-v 's
212give more output. Also, version information is printed at startup.
213.TP
214.B \-debug
215Same as
216.BR \-verbose .
Thomas G. Lanebc79e061995-08-02 00:00:00 +0000217.SH EXAMPLES
218.LP
219This 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
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000225.PP
226This example rotates an image 90 degrees clockwise, discarding any
227unrotatable edge pixels:
228.IP
229.B jpegtran \-rot 90 -trim
230.I foo.jpg
231.B >
232.I foo90.jpg
Thomas G. Lanebc79e061995-08-02 00:00:00 +0000233.SH ENVIRONMENT
234.TP
235.B JPEGMEM
236If this environment variable is set, its value is the default memory limit.
237The value is specified as described for the
238.B \-maxmemory
239switch.
240.B JPEGMEM
241overrides the default value specified when the program was compiled, and
242itself 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
250Wallace, Gregory K. "The JPEG Still Picture Compression Standard",
251Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.
252.SH AUTHOR
253Independent JPEG Group
254.SH BUGS
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000255The transform options can't transform odd-size images perfectly. Use
256.B \-trim
Guido Vollbeding5996a252009-06-27 00:00:00 +0000257or
258.B \-perfect
259if you don't like the results.
Thomas G. Lane5ead57a1998-03-27 00:00:00 +0000260.PP
261The entire image is read into memory and then written out again, even in
262cases where this isn't really necessary. Expect swapping on large images,
263especially when using the more complex transform options.