1JPEGTRAN(1)                 General Commands Manual                JPEGTRAN(1)
2
3
4

NAME

6       jpegtran - lossless transformation of JPEG files
7

SYNOPSIS

9       jpegtran [ options ] [ filename ]
10

DESCRIPTION

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
18       For  EXIF  files and JPEG files containing Exif data, you may prefer to
19       use exiftran instead.
20
21       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
30       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

OPTIONS

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
39       To specify the coded JPEG representation used in the output file, jpeg‐
40       tran accepts a subset of the switches recognized by cjpeg:
41
42       -optimize
43              Perform optimization of entropy encoding parameters.
44
45       -progressive
46              Create progressive JPEG file.
47
48       -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
52       -arithmetic
53              Use arithmetic coding.
54
55       -scans file
56              Use the scan script given in the specified text file.
57
58       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
62       The  image  can  be  losslessly  transformed  by  giving  one  of these
63       switches:
64
65       -flip horizontal
66              Mirror image horizontally (left-right).
67
68       -flip vertical
69              Mirror image vertically (top-bottom).
70
71       -rotate 90
72              Rotate image 90 degrees clockwise.
73
74       -rotate 180
75              Rotate image 180 degrees.
76
77       -rotate 270
78              Rotate image 270 degrees clockwise (or 90 ccw).
79
80       -transpose
81              Transpose image (across UL-to-LR axis).
82
83       -transverse
84              Transverse transpose (across UR-to-LL axis).
85
86       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
92       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
103       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
108       -trim  Drop non-transformable edge blocks.
109
110              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
117       -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
122              For example, you may want to do
123
124              (jpegtran  -rot  90  -perfect foo.jpg || djpeg foo.jpg | pnmflip
125              -r90 | cjpeg)
126
127              to do a perfect rotation, if available, or an  approximated  one
128              if not.
129
130       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
140       The image can be losslessly cropped by giving the switch:
141
142       -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
152       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
161       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
165       -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
169       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
177       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
181       -drop +X+Y filename
182              Drop (insert) another image at point X,Y
183
184       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
195       Other not-strictly-lossless transformation switches are:
196
197       -grayscale
198              Force grayscale output.
199
200              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
211       jpegtran also recognizes these switches that control what  to  do  with
212       "extra" markers, such as comment blocks:
213
214       -copy none
215              Copy no extra markers from source file.  This setting suppresses
216              all comments and other metadata in the source file.
217
218       -copy comments
219              Copy only comment markers.  This setting  copies  comments  from
220              the source file but discards any other metadata.
221
222       -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
229       The  default behavior is -copy comments.  (Note: in IJG releases v6 and
230       v6a, jpegtran always did the equivalent of -copy none.)
231
232       Additional switches recognized by jpegtran are:
233
234       -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
239       -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
245       -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
258       -outfile name
259              Send output image to the named file, not to standard output.
260
261       -report
262              Report transformation progress.
263
264       -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
271       -verbose
272              Enable  debug printout.  More -v's give more output.  Also, ver‐
273              sion information is printed at startup.
274
275       -debug Same as -verbose.
276
277       -version
278              Print version information and exit.
279

EXAMPLES

281       This example converts a baseline JPEG file to progressive form:
282
283              jpegtran -progressive foo.jpg > fooprog.jpg
284
285       This example rotates an image 90 degrees clockwise, discarding any  un‐
286       rotatable edge pixels:
287
288              jpegtran -rot 90 -trim foo.jpg > foo90.jpg
289

ENVIRONMENT

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

SEE ALSO

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

AUTHOR

304       Independent JPEG Group
305
306       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

BUGS

310       The  transform  options can't transform odd-size images perfectly.  Use
311       -trim or -perfect if you don't like the results.
312
313       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
317
318
319                                26 October 2020                    JPEGTRAN(1)
Impressum