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 icc
223 Copy only ICC profile markers. This setting copies the ICC pro‐
224 file from the source file but discards any other metadata.
225 -copy all
227 Copy all extra markers. This setting preserves miscellaneous
228 markers found in the source file, such as JFIF thumbnails, Exif
229 data, and Photoshop settings. In some files, these extra mark‐
230 ers can be sizable. Note that this option will copy thumbnails
231 as-is; they will not be transformed.
232 The default behavior is -copy comments. (Note: in IJG releases v6 and
234 v6a, jpegtran always did the equivalent of -copy none.)
235 Additional switches recognized by jpegtran are:
237 -icc file
239 Embed ICC color management profile contained in the specified
240 file. Note that this will cause jpegtran to ignore any APP2
241 markers in the input file, even if -copy all or -copy icc is
242 specified.
243 -maxmemory N
245 Set limit for amount of memory to use in processing large im‐
246 ages. Value is in thousands of bytes, or millions of bytes if
247 "M" is attached to the number. For example, -max 4m selects
248 4000000 bytes. If more space is needed, an error will occur.
249 -maxscans N
251 Abort if the input image contains more than N scans. This fea‐
252 ture demonstrates a method by which applications can guard
253 against denial-of-service attacks instigated by specially-
254 crafted malformed JPEG images containing numerous scans with
255 missing image data or image data consisting only of "EOB runs"
256 (a feature of progressive JPEG images that allows potentially
257 hundreds of thousands of adjoining zero-value pixels to be rep‐
258 resented using only a few bytes.) Attempting to transform such
259 malformed JPEG images can cause excessive CPU activity, since
260 the decompressor must fully process each scan (even if the scan
261 is corrupt) before it can proceed to the next scan.
262 -outfile name
264 Send output image to the named file, not to standard output.
265 -report
267 Report transformation progress.
268 -strict
270 Treat all warnings as fatal. This feature also demonstrates a
271 method by which applications can guard against attacks insti‐
272 gated by specially-crafted malformed JPEG images. Enabling this
273 option will cause the decompressor to abort if the input image
274 contains incomplete or corrupt image data.
275 -verbose
277 Enable debug printout. More -v's give more output. Also, ver‐
278 sion information is printed at startup.
279 -debug Same as -verbose.
281 -version
283 Print version information and exit.
284
286 This example converts a baseline JPEG file to progressive form:
287 jpegtran -progressive foo.jpg > fooprog.jpg
289 This example rotates an image 90 degrees clockwise, discarding any un‐
291 rotatable edge pixels:
292 jpegtran -rot 90 -trim foo.jpg > foo90.jpg
294
296 JPEGMEM
297 If this environment variable is set, its value is the default
298 memory limit. The value is specified as described for the
299 -maxmemory switch. JPEGMEM overrides the default value speci‐
300 fied when the program was compiled, and itself is overridden by
301 an explicit -maxmemory.
302
304 cjpeg(1), djpeg(1), rdjpgcom(1), wrjpgcom(1)
305 Wallace, Gregory K. "The JPEG Still Picture Compression Standard",
306 Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.
307
309 Independent JPEG Group
310 This file was modified by The libjpeg-turbo Project to include only in‐
312 formation relevant to libjpeg-turbo and to wordsmith certain sections.
313
315 The transform options can't transform odd-size images perfectly. Use
316 -trim or -perfect if you don't like the results.
317 The entire image is read into memory and then written out again, even
319 in cases where this isn't really necessary. Expect swapping on large
320 images, especially when using the more complex transform options.
321 13 July 2021 JPEGTRAN(1)