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