1JPEGTRAN(1) General Commands Manual JPEGTRAN(1)
2
6 jpegtran - lossless transformation of JPEG files
7
9 jpegtran [ options ] [ filename ]
10
12 jpegtran performs various useful transformations of JPEG files. It can
13 translate the coded representation from one variant of JPEG to another,
14 for example from baseline JPEG to progressive JPEG or vice versa. It
15 can also perform some rearrangements of the image data, for example
16 turning an image from landscape to portrait format by rotation.
17 For EXIF files and JPEG files containing Exif data, you may prefer to
19 use exiftran instead.
20 jpegtran works by rearranging the compressed data (DCT coefficients),
22 without ever fully decoding the image. Therefore, its transformations
23 are lossless: there is no image degradation at all, which would not be
24 true if you used djpeg followed by cjpeg to accomplish the same conver‐
25 sion. But by the same token, jpegtran cannot perform lossy operations
26 such as changing the image quality. However, while the image data is
27 losslessly transformed, metadata can be removed. See the -copy option
28 for specifics.
29 jpegtran reads the named JPEG/JFIF file, or the standard input if no
31 file is named, and produces a JPEG/JFIF file on the standard output.
32
34 All switch names may be abbreviated; for example, -optimize may be
35 written -opt or -o. Upper and lower case are equivalent. British
36 spellings are also accepted (e.g., -optimise), though for brevity these
37 are not mentioned below.
38 To specify the coded JPEG representation used in the output file, jpeg‐
40 tran accepts a subset of the switches recognized by cjpeg:
41 -optimize
43 Perform optimization of entropy encoding parameters.
44 -progressive
46 Create progressive JPEG file.
47 -restart N
49 Emit a JPEG restart marker every N MCU rows, or every N MCU
50 blocks if "B" is attached to the number.
51 -arithmetic
53 Use arithmetic coding.
54 -scans file
56 Use the scan script given in the specified text file.
57 See cjpeg(1) for more details about these switches. If you specify
59 none of these switches, you get a plain baseline-JPEG output file. The
60 quality setting and so forth are determined by the input file.
61 The image can be losslessly transformed by giving one of these
63 switches:
64 -flip horizontal
66 Mirror image horizontally (left-right).
67 -flip vertical
69 Mirror image vertically (top-bottom).
70 -rotate 90
72 Rotate image 90 degrees clockwise.
73 -rotate 180
75 Rotate image 180 degrees.
76 -rotate 270
78 Rotate image 270 degrees clockwise (or 90 ccw).
79 -transpose
81 Transpose image (across UL-to-LR axis).
82 -transverse
84 Transverse transpose (across UR-to-LL axis).
85 The transpose transformation has no restrictions regarding image dimen‐
87 sions. The other transformations operate rather oddly if the image di‐
88 mensions are not a multiple of the iMCU size (usually 8 or 16 pixels),
89 because they can only transform complete blocks of DCT coefficient data
90 in the desired way.
91 jpegtran's default behavior when transforming an odd-size image is de‐
93 signed to preserve exact reversibility and mathematical consistency of
94 the transformation set. As stated, transpose is able to flip the en‐
95 tire image area. Horizontal mirroring leaves any partial iMCU column
96 at the right edge untouched, but is able to flip all rows of the image.
97 Similarly, vertical mirroring leaves any partial iMCU row at the bottom
98 edge untouched, but is able to flip all columns. The other transforms
99 can be built up as sequences of transpose and flip operations; for con‐
100 sistency, their actions on edge pixels are defined to be the same as
101 the end result of the corresponding transpose-and-flip sequence.
102 For practical use, you may prefer to discard any untransformable edge
104 pixels rather than having a strange-looking strip along the right
105 and/or bottom edges of a transformed image. To do this, add the -trim
106 switch:
107 -trim Drop non-transformable edge blocks.
109 Obviously, a transformation with -trim is not reversible, so
111 strictly speaking jpegtran with this switch is not lossless.
112 Also, the expected mathematical equivalences between the trans‐
113 formations no longer hold. For example, -rot 270 -trim trims
114 only the bottom edge, but -rot 90 -trim followed by -rot 180
115 -trim trims both edges.
116 -perfect
118 If you are only interested in perfect transformations, add the
119 -perfect switch. This causes jpegtran to fail with an error if
120 the transformation is not perfect.
121 For example, you may want to do
123 (jpegtran -rot 90 -perfect foo.jpg || djpeg foo.jpg | pnmflip
125 -r90 | cjpeg)
126 to do a perfect rotation, if available, or an approximated one
128 if not.
129 This version of jpegtran also offers a lossless crop option, which dis‐
131 cards data outside of a given image region but losslessly preserves
132 what is inside. Like the rotate and flip transforms, lossless crop is
133 restricted by the current JPEG format; the upper left corner of the se‐
134 lected region must fall on an iMCU boundary. If it doesn't, then it is
135 silently moved up and/or left to the nearest iMCU boundary (the lower
136 right corner is unchanged.) Thus, the output image covers at least the
137 requested region, but it may cover more. The adjustment of the region
138 dimensions may be optionally disabled by attaching an
139 The image can be losslessly cropped by giving the switch:
141 -crop WxH+X+Y
143 Crop the image to a rectangular region of width W and height H,
144 starting at point X,Y. The lossless crop feature discards data
145 outside of a given image region but losslessly preserves what is
146 inside. Like the rotate and flip transforms, lossless crop is
147 restricted by the current JPEG format; the upper left corner of
148 the selected region must fall on an iMCU boundary. If it
149 doesn't, then it is silently moved up and/or left to the nearest
150 iMCU boundary (the lower right corner is unchanged.)
151 If W or H is larger than the width/height of the input image, then the
153 output image is expanded in size, and the expanded region is filled in
154 with zeros (neutral gray). Attaching an 'f' character ("flatten") to
155 the width number will cause each block in the expanded region to be
156 filled in with the DC coefficient of the nearest block in the input im‐
157 age rather than grayed out. Attaching an 'r' character ("reflect") to
158 the width number will cause the expanded region to be filled in with
159 repeated reflections of the input image rather than grayed out.
160 A complementary lossless wipe option is provided to discard (gray out)
162 data inside a given image region while losslessly preserving what is
163 outside:
164 -wipe WxH+X+Y
166 Wipe (gray out) a rectangular region of width W and height H
167 from the input image, starting at point X,Y.
168 Attaching an 'f' character ("flatten") to the width number will cause
170 the region to be filled with the average of adjacent blocks rather than
171 grayed out. If the wipe region and the region outside the wipe region,
172 when adjusted to the nearest iMCU boundary, form two horizontally adja‐
173 cent rectangles, then attaching an 'r' character ("reflect") to the
174 width number will cause the wipe region to be filled with repeated re‐
175 flections of the outside region rather than grayed out.
176 A lossless drop option is also provided, which allows another JPEG im‐
178 age to be inserted ("dropped") into the input image data at a given po‐
179 sition, replacing the existing image data at that position:
180 -drop +X+Y filename
182 Drop (insert) another image at point X,Y
183 Both the input image and the drop image must have the same subsampling
185 level. It is best if they also have the same quantization (quality.)
186 Otherwise, the quantization of the output image will be adapted to ac‐
187 commodate the higher of the input image quality and the drop image
188 quality. The trim option can be used with the drop option to requan‐
189 tize the drop image to match the input image. Note that a grayscale
190 image can be dropped into a full-color image or vice versa, as long as
191 the full-color image has no vertical subsampling. If the input image
192 is grayscale and the drop image is full-color, then the chrominance
193 channels from the drop image will be discarded.
194 Other not-strictly-lossless transformation switches are:
196 -grayscale
198 Force grayscale output.
199 This option discards the chrominance channels if the input image
201 is YCbCr (ie, a standard color JPEG), resulting in a grayscale
202 JPEG file. The luminance channel is preserved exactly, so this
203 is a better method of reducing to grayscale than decompression,
204 conversion, and recompression. This switch is particularly
205 handy for fixing a monochrome picture that was mistakenly en‐
206 coded as a color JPEG. (In such a case, the space savings from
207 getting rid of the near-empty chroma channels won't be large;
208 but the decoding time for a grayscale JPEG is substantially less
209 than that for a color JPEG.)
210 jpegtran also recognizes these switches that control what to do with
212 "extra" markers, such as comment blocks:
213 -copy none
215 Copy no extra markers from source file. This setting suppresses
216 all comments and other metadata in the source file.
217 -copy comments
219 Copy only comment markers. This setting copies comments from
220 the source file but discards any other metadata.
221 -copy all
223 Copy all extra markers. This setting preserves miscellaneous
224 markers found in the source file, such as JFIF thumbnails, Exif
225 data, and Photoshop settings. In some files, these extra mark‐
226 ers can be sizable. Note that this option will copy thumbnails
227 as-is; they will not be transformed.
228 The default behavior is -copy comments. (Note: in IJG releases v6 and
230 v6a, jpegtran always did the equivalent of -copy none.)
231 Additional switches recognized by jpegtran are:
233 -icc file
235 Embed ICC color management profile contained in the specified
236 file. Note that this will cause jpegtran to ignore any APP2
237 markers in the input file, even if -copy all is specified.
238 -maxmemory N
240 Set limit for amount of memory to use in processing large im‐
241 ages. Value is in thousands of bytes, or millions of bytes if
242 "M" is attached to the number. For example, -max 4m selects
243 4000000 bytes. If more space is needed, an error will occur.
244 -maxscans N
246 Abort if the input image contains more than N scans. This fea‐
247 ture demonstrates a method by which applications can guard
248 against denial-of-service attacks instigated by specially-
249 crafted malformed JPEG images containing numerous scans with
250 missing image data or image data consisting only of "EOB runs"
251 (a feature of progressive JPEG images that allows potentially
252 hundreds of thousands of adjoining zero-value pixels to be rep‐
253 resented using only a few bytes.) Attempting to transform such
254 malformed JPEG images can cause excessive CPU activity, since
255 the decompressor must fully process each scan (even if the scan
256 is corrupt) before it can proceed to the next scan.
257 -outfile name
259 Send output image to the named file, not to standard output.
260 -report
262 Report transformation progress.
263 -strict
265 Treat all warnings as fatal. This feature also demonstrates a
266 method by which applications can guard against attacks insti‐
267 gated by specially-crafted malformed JPEG images. Enabling this
268 option will cause the decompressor to abort if the input image
269 contains incomplete or corrupt image data.
270 -verbose
272 Enable debug printout. More -v's give more output. Also, ver‐
273 sion information is printed at startup.
274 -debug Same as -verbose.
276 -version
278 Print version information and exit.
279
281 This example converts a baseline JPEG file to progressive form:
282 jpegtran -progressive foo.jpg > fooprog.jpg
284 This example rotates an image 90 degrees clockwise, discarding any un‐
286 rotatable edge pixels:
287 jpegtran -rot 90 -trim foo.jpg > foo90.jpg
289
291 JPEGMEM
292 If this environment variable is set, its value is the default
293 memory limit. The value is specified as described for the
294 -maxmemory switch. JPEGMEM overrides the default value speci‐
295 fied when the program was compiled, and itself is overridden by
296 an explicit -maxmemory.
297
299 cjpeg(1), djpeg(1), rdjpgcom(1), wrjpgcom(1)
300 Wallace, Gregory K. "The JPEG Still Picture Compression Standard",
301 Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.
302
304 Independent JPEG Group
305 This file was modified by The libjpeg-turbo Project to include only in‐
307 formation relevant to libjpeg-turbo and to wordsmith certain sections.
308
310 The transform options can't transform odd-size images perfectly. Use
311 -trim or -perfect if you don't like the results.
312 The entire image is read into memory and then written out again, even
314 in cases where this isn't really necessary. Expect swapping on large
315 images, especially when using the more complex transform options.
316 26 October 2020 JPEGTRAN(1)