jpegtran.1

   1 .TH JPEGTRAN 1 "18 March 2017"
   2 .SH NAME
   3 jpegtran \- 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
  16 performs various useful transformations of JPEG files.
  17 It can translate the coded representation from one variant of JPEG to another,
  18 for example from baseline JPEG to progressive JPEG or vice versa.  It can also
  19 perform some rearrangements of the image data, for example turning an image
  20 from landscape to portrait format by rotation.
  21 .PP
  22 For EXIF files and JPEG files containing Exif data, you may prefer to use
  23 .B exiftran
  24 instead.
  25 .PP
  26 .B jpegtran
  27 works by rearranging the compressed data (DCT coefficients), without
  28 ever fully decoding the image.  Therefore, its transformations are lossless:
  29 there is no image degradation at all, which would not be true if you used
  30 .B djpeg
  31 followed by
  32 .B cjpeg
  33 to accomplish the same conversion.  But by the same token,
  34 .B jpegtran
  35 cannot perform lossy operations such as changing the image quality.  However,
  36 while the image data is losslessly transformed, metadata can be removed.  See
  37 the
  38 .B \-copy
  39 option for specifics.
  40 .PP
  41 .B jpegtran
  42 reads the named JPEG/JFIF file, or the standard input if no file is
  43 named, and produces a JPEG/JFIF file on the standard output.
  44 .SH OPTIONS
  45 All switch names may be abbreviated; for example,
  46 .B \-optimize
  47 may be written
  48 .B \-opt
  49 or
  50 .BR \-o .
  51 Upper and lower case are equivalent.
  52 British spellings are also accepted (e.g.,
  53 .BR \-optimise ),
  54 though for brevity these are not mentioned below.
  55 .PP
  56 To specify the coded JPEG representation used in the output file,
  57 .B jpegtran
  58 accepts a subset of the switches recognized by
  59 .BR cjpeg :
  60 .TP
  61 .B \-optimize
  62 Perform optimization of entropy encoding parameters.
  63 .TP
  64 .B \-progressive
  65 Create progressive JPEG file.
  66 .TP
  67 .BI \-restart " N"
  68 Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is
  69 attached to the number.
  70 .TP
  71 .B \-arithmetic
  72 Use arithmetic coding.
  73 .TP
  74 .BI \-scans " file"
  75 Use the scan script given in the specified text file.
  76 .PP
  77 See
  78 .BR cjpeg (1)
  79 for more details about these switches.
  80 If you specify none of these switches, you get a plain baseline-JPEG output
  81 file.  The quality setting and so forth are determined by the input file.
  82 .PP
  83 The image can be losslessly transformed by giving one of these switches:
  84 .TP
  85 .B \-flip horizontal
  86 Mirror image horizontally (left-right).
  87 .TP
  88 .B \-flip vertical
  89 Mirror image vertically (top-bottom).
  90 .TP
  91 .B \-rotate 90
  92 Rotate image 90 degrees clockwise.
  93 .TP
  94 .B \-rotate 180
  95 Rotate image 180 degrees.
  96 .TP
  97 .B \-rotate 270
  98 Rotate image 270 degrees clockwise (or 90 ccw).
  99 .TP
 100 .B \-transpose
 101 Transpose image (across UL-to-LR axis).
 102 .TP
 103 .B \-transverse
 104 Transverse transpose (across UR-to-LL axis).
 105 .PP
 106 The transpose transformation has no restrictions regarding image dimensions.
 107 The other transformations operate rather oddly if the image dimensions are not
 108 a multiple of the iMCU size (usually 8 or 16 pixels), because they can only
 109 transform complete blocks of DCT coefficient data in the desired way.
 110 .PP
 111 .BR jpegtran 's
 112 default behavior when transforming an odd-size image is designed
 113 to preserve exact reversibility and mathematical consistency of the
 114 transformation set.  As stated, transpose is able to flip the entire image
 115 area.  Horizontal mirroring leaves any partial iMCU column at the right edge
 116 untouched, but is able to flip all rows of the image.  Similarly, vertical
 117 mirroring leaves any partial iMCU row at the bottom edge untouched, but is
 118 able to flip all columns.  The other transforms can be built up as sequences
 119 of transpose and flip operations; for consistency, their actions on edge
 120 pixels are defined to be the same as the end result of the corresponding
 121 transpose-and-flip sequence.
 122 .PP
 123 For practical use, you may prefer to discard any untransformable edge pixels
 124 rather than having a strange-looking strip along the right and/or bottom edges
 125 of a transformed image.  To do this, add the
 126 .B \-trim
 127 switch:
 128 .TP
 129 .B \-trim
 130 Drop non-transformable edge blocks.
 131 .IP
 132 Obviously, a transformation with
 133 .B \-trim
 134 is not reversible, so strictly speaking
 135 .B jpegtran
 136 with this switch is not lossless.  Also, the expected mathematical
 137 equivalences between the transformations no longer hold.  For example,
 138 .B \-rot 270 -trim
 139 trims only the bottom edge, but
 140 .B \-rot 90 -trim
 141 followed by
 142 .B \-rot 180 -trim
 143 trims both edges.
 144 .TP
 145 .B \-perfect
 146 If you are only interested in perfect transformations, add the
 147 .B \-perfect
 148 switch.  This causes
 149 .B jpegtran
 150 to fail with an error if the transformation is not perfect.
 151 .IP
 152 For example, you may want to do
 153 .IP
 154 .B (jpegtran \-rot 90 -perfect
 155 .I foo.jpg
 156 .B || djpeg
 157 .I foo.jpg
 158 .B | pnmflip \-r90 | cjpeg)
 159 .IP
 160 to do a perfect rotation, if available, or an approximated one if not.
 161 .PP
 162 This version of \fBjpegtran\fR also offers a lossless crop option, which
 163 discards data outside of a given image region but losslessly preserves what is
 164 inside.  Like the rotate and flip transforms, lossless crop is restricted by
 165 the current JPEG format; the upper left corner of the selected region must fall
 166 on an iMCU boundary.  If it doesn't, then it is silently moved up and/or left
 167 to the nearest iMCU boundary (the lower right corner is unchanged.)  Thus, the
 168 output image covers at least the requested region, but it may cover more.  The
 169 adjustment of the region dimensions may be optionally disabled by attaching an
 170 'f' character ("force") to the width or height number.
 171
 172 The image can be losslessly cropped by giving the switch:
 173 .TP
 174 .B \-crop WxH+X+Y
 175 Crop the image to a rectangular region of width W and height H, starting at
 176 point X,Y.  The lossless crop feature discards data outside of a given image
 177 region but losslessly preserves what is inside.  Like the rotate and flip
 178 transforms, lossless crop is restricted by the current JPEG format; the upper
 179 left corner of the selected region must fall on an iMCU boundary.  If it
 180 doesn't, then it is silently moved up and/or left to the nearest iMCU boundary
 181 (the lower right corner is unchanged.)
 182 .PP
 183 Other not-strictly-lossless transformation switches are:
 184 .TP
 185 .B \-grayscale
 186 Force grayscale output.
 187 .IP
 188 This option discards the chrominance channels if the input image is YCbCr
 189 (ie, a standard color JPEG), resulting in a grayscale JPEG file.  The
 190 luminance channel is preserved exactly, so this is a better method of reducing
 191 to grayscale than decompression, conversion, and recompression.  This switch
 192 is particularly handy for fixing a monochrome picture that was mistakenly
 193 encoded as a color JPEG.  (In such a case, the space savings from getting rid
 194 of the near-empty chroma channels won't be large; but the decoding time for
 195 a grayscale JPEG is substantially less than that for a color JPEG.)
 196 .PP
 197 .B jpegtran
 198 also recognizes these switches that control what to do with "extra" markers,
 199 such as comment blocks:
 200 .TP
 201 .B \-copy none
 202 Copy no extra markers from source file.  This setting suppresses all
 203 comments and other metadata in the source file.
 204 .TP
 205 .B \-copy comments
 206 Copy only comment markers.  This setting copies comments from the source file
 207 but discards any other metadata.
 208 .TP
 209 .B \-copy all
 210 Copy all extra markers.  This setting preserves miscellaneous markers
 211 found in the source file, such as JFIF thumbnails, Exif data, and Photoshop
 212 settings.  In some files, these extra markers can be sizable.  Note that this
 213 option will copy thumbnails as-is; they will not be transformed.
 214 .PP
 215 The default behavior is \fB-copy comments\fR.  (Note: in IJG releases v6 and
 216 v6a, \fBjpegtran\fR always did the equivalent of \fB-copy none\fR.)
 217 .PP
 218 Additional switches recognized by jpegtran are:
 219 .TP
 220 .BI \-icc " file"
 221 Embed ICC color management profile contained in the specified file.  Note that
 222 this will cause \fBjpegtran\fR to ignore any APP2 markers in the input file,
 223 even if \fB-copy all\fR is specified.
 224 .TP
 225 .BI \-maxmemory " N"
 226 Set limit for amount of memory to use in processing large images.  Value is
 227 in thousands of bytes, or millions of bytes if "M" is attached to the
 228 number.  For example,
 229 .B \-max 4m
 230 selects 4000000 bytes.  If more space is needed, an error will occur.
 231 .TP
 232 .BI \-outfile " name"
 233 Send output image to the named file, not to standard output.
 234 .TP
 235 .B \-verbose
 236 Enable debug printout.  More
 237 .BR \-v 's
 238 give more output.  Also, version information is printed at startup.
 239 .TP
 240 .B \-debug
 241 Same as
 242 .BR \-verbose .
 243 .TP
 244 .B \-version
 245 Print version information and exit.
 246 .SH EXAMPLES
 247 .LP
 248 This example converts a baseline JPEG file to progressive form:
 249 .IP
 250 .B jpegtran \-progressive
 251 .I foo.jpg
 252 .B >
 253 .I fooprog.jpg
 254 .PP
 255 This example rotates an image 90 degrees clockwise, discarding any
 256 unrotatable edge pixels:
 257 .IP
 258 .B jpegtran \-rot 90 -trim
 259 .I foo.jpg
 260 .B >
 261 .I foo90.jpg
 262 .SH ENVIRONMENT
 263 .TP
 264 .B JPEGMEM
 265 If this environment variable is set, its value is the default memory limit.
 266 The value is specified as described for the
 267 .B \-maxmemory
 268 switch.
 269 .B JPEGMEM
 270 overrides the default value specified when the program was compiled, and
 271 itself is overridden by an explicit
 272 .BR \-maxmemory .
 273 .SH SEE ALSO
 274 .BR cjpeg (1),
 275 .BR djpeg (1),
 276 .BR rdjpgcom (1),
 277 .BR wrjpgcom (1)
 278 .br
 279 Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",
 280 Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.
 281 .SH AUTHOR
 282 Independent JPEG Group
 283 .PP
 284 This file was modified by The libjpeg-turbo Project to include only information
 285 relevant to libjpeg-turbo and to wordsmith certain sections.
 286 .SH BUGS
 287 The transform options can't transform odd-size images perfectly.  Use
 288 .B \-trim
 289 or
 290 .B \-perfect
 291 if you don't like the results.
 292 .PP
 293 The entire image is read into memory and then written out again, even in
 294 cases where this isn't really necessary.  Expect swapping on large images,
 295 especially when using the more complex transform options.