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

NAME

6       cjpeg - compress an image file to a JPEG file
7

SYNOPSIS

9       cjpeg [ options ] [ filename ]
10

DESCRIPTION

12       cjpeg compresses the named image file, or the standard input if no file
13       is named, and produces a JPEG/JFIF file on the  standard  output.   The
14       currently supported input file formats are: PPM (PBMPLUS color format),
15       PGM (PBMPLUS grayscale format), BMP, GIF, and Targa.
16

OPTIONS

18       All switch names may be abbreviated; for  example,  -grayscale  may  be
19       written  -gray or -gr.  Most of the "basic" switches can be abbreviated
20       to as little as one letter.  Upper and lower case are equivalent  (thus
21       -BMP  is the same as -bmp).  British spellings are also accepted (e.g.,
22       -greyscale), though for brevity these are not mentioned below.
23
24       The basic switches are:
25
26       -quality N[,...]
27              Scale quantization tables to adjust image quality.  Quality is 0
28              (worst)  to  100  (best);  default  is  75.  (See below for more
29              info.)
30
31       -grayscale
32              Create  monochrome  JPEG  file  from  color  input.   By  saying
33              -grayscale,  you'll get a smaller JPEG file that takes less time
34              to process.
35
36       -rgb   Create RGB JPEG file.  Using this switch suppresses the  conver‐
37              sion  from  RGB  colorspace input to the default YCbCr JPEG col‐
38              orspace.
39
40       -optimize
41              Perform optimization of entropy  encoding  parameters.   Without
42              this,  default  encoding parameters are used.  -optimize usually
43              makes the JPEG file a little smaller, but  cjpeg  runs  somewhat
44              slower  and  needs much more memory.  Image quality and speed of
45              decompression are unaffected by -optimize.
46
47       -progressive
48              Create progressive JPEG file (see below).
49
50       -targa Input file is Targa format.  Targa files that contain an  "iden‐
51              tification" field will not be automatically recognized by cjpeg;
52              for such files you must specify -targa to make cjpeg  treat  the
53              input  as  Targa  format.   For most Targa files, you won't need
54              this switch.
55
56       The -quality switch lets you trade off  compressed  file  size  against
57       quality of the reconstructed image: the higher the quality setting, the
58       larger the JPEG file, and the closer the output image will  be  to  the
59       original  input.   Normally  you want to use the lowest quality setting
60       (smallest file) that decompresses  into  something  visually  indistin‐
61       guishable  from  the original image.  For this purpose the quality set‐
62       ting should generally be between 50 and 95 (the default is 75) for pho‐
63       tographic  images.   If you see defects at -quality 75, then go up 5 or
64       10 counts at a time until you are happy with the  output  image.   (The
65       optimal setting will vary from one image to another.)
66
67       -quality  100 will generate a quantization table of all 1's, minimizing
68       loss in the quantization step (but there is still information  loss  in
69       subsampling, as well as roundoff error.)  For most images, specifying a
70       quality value above about 95 will increase the size of  the  compressed
71       file dramatically, and while the quality gain from these higher quality
72       values is measurable (using metrics such as PSNR or SSIM), it is rarely
73       perceivable by human vision.
74
75       In the other direction, quality values below 50 will produce very small
76       files of low image quality.  Settings around 5 to 10 might be useful in
77       preparing an index of a large image library, for example.  Try -quality
78       2 (or so) for some amusing Cubist effects.  (Note: quality values below
79       about  25 generate 2-byte quantization tables, which are considered op‐
80       tional in the JPEG standard.  cjpeg emits a warning  message  when  you
81       give  such a quality value, because some other JPEG programs may be un‐
82       able to decode the resulting file.  Use -baseline if you need to ensure
83       compatibility at low quality values.)
84
85       The  -quality option has been extended in this version of cjpeg to sup‐
86       port separate quality settings for luminance and  chrominance  (or,  in
87       general,  separate  settings  for  every quantization table slot.)  The
88       principle is the same as chrominance subsampling:  since the human  eye
89       is more sensitive to spatial changes in brightness than spatial changes
90       in color, the chrominance components can be quantized more than the lu‐
91       minance  components  without  incurring any visible image quality loss.
92       However, unlike subsampling, this feature reduces data in the frequency
93       domain  instead  of  the  spatial  domain,  which allows for more fine-
94       grained control.  This option is useful in  quality-sensitive  applica‐
95       tions,  for  which  the artifacts generated by subsampling may be unac‐
96       ceptable.
97
98       The -quality option accepts a comma-separated list of parameters, which
99       respectively refer to the quality levels that should be assigned to the
100       quantization table slots.  If there are more q-table slots than parame‐
101       ters, then the last parameter is replicated.  Thus, if only one quality
102       parameter is given, this is used for  both  luminance  and  chrominance
103       (slots  0 and 1, respectively), preserving the legacy behavior of cjpeg
104       v6b and prior.  More (or customized) quantization  tables  can  be  set
105       with  the  -qtables  option and assigned to components with the -qslots
106       option (see the "wizard" switches below.)
107
108       JPEG files generated with separate luminance  and  chrominance  quality
109       are fully compliant with standard JPEG decoders.
110
111       CAUTION:  For this setting to be useful, be sure to pass an argument of
112       -sample 1x1 to cjpeg to disable  chrominance  subsampling.   Otherwise,
113       the default subsampling level (2x2, AKA "4:2:0") will be used.
114
115       The  -progressive  switch  creates  a "progressive JPEG" file.  In this
116       type of JPEG file, the data is stored in multiple scans  of  increasing
117       quality.   If  the file is being transmitted over a slow communications
118       link, the decoder can use the first scan to display a low-quality image
119       very  quickly,  and  can  then improve the display with each subsequent
120       scan.  The final image is exactly equivalent to a standard JPEG file of
121       the same quality setting, and the total file size is about the same ---
122       often a little smaller.
123
124       Switches for advanced users:
125
126       -arithmetic
127              Use arithmetic coding.  Caution: arithmetic coded  JPEG  is  not
128              yet  widely implemented, so many decoders will be unable to view
129              an arithmetic coded JPEG file at all.
130
131       -dct int
132              Use accurate integer DCT method (default).
133
134       -dct fast
135              Use less accurate integer DCT method [legacy feature].  When the
136              Independent  JPEG  Group's  software was first released in 1991,
137              the compression time for a 1-megapixel JPEG  image  on  a  main‐
138              stream  PC  was measured in minutes.  Thus, the fast integer DCT
139              algorithm provided noticeable performance benefits.   On  modern
140              CPUs  running libjpeg-turbo, however, the compression time for a
141              1-megapixel JPEG image is measured in milliseconds, and thus the
142              performance benefits of the fast algorithm are much less notice‐
143              able.  On modern x86/x86-64 CPUs that support AVX2 instructions,
144              the  fast  and  int  methods have similar performance.  On other
145              types of CPUs, the fast method is generally about  5-15%  faster
146              than the int method.
147
148              For quality levels of 90 and below, there should be little or no
149              perceptible quality difference between the two algorithms.   For
150              quality  levels  above  90,  however, the difference between the
151              fast and int methods becomes more pronounced.  With  quality=97,
152              for  instance,  the  fast method incurs generally about a 1-3 dB
153              loss in PSNR relative to the int method, but this can be  larger
154              for some images.  Do not use the fast method with quality levels
155              above 97.  The algorithm often  degenerates  at  quality=98  and
156              above  and can actually produce a more lossy image than if lower
157              quality levels had been used.  Also, in libjpeg-turbo, the  fast
158              method  is not fully accelerated for quality levels above 97, so
159              it will be slower than the int method.
160
161       -dct float
162              Use floating-point  DCT  method  [legacy  feature].   The  float
163              method does not produce significantly more accurate results than
164              the int method, and it is much slower.   The  float  method  may
165              also give different results on different machines due to varying
166              roundoff behavior, whereas the integer methods should  give  the
167              same results on all machines.
168
169       -icc file
170              Embed  ICC  color  management profile contained in the specified
171              file.
172
173       -restart N
174              Emit a JPEG restart marker every N MCU  rows,  or  every  N  MCU
175              blocks  if  "B"  is attached to the number.  -restart 0 (the de‐
176              fault) means no restart markers.
177
178       -smooth N
179              Smooth the input image to eliminate dithering noise.  N, ranging
180              from  1 to 100, indicates the strength of smoothing.  0 (the de‐
181              fault) means no smoothing.
182
183       -maxmemory N
184              Set limit for amount of memory to use in  processing  large  im‐
185              ages.   Value  is in thousands of bytes, or millions of bytes if
186              "M" is attached to the number.  For  example,  -max  4m  selects
187              4000000 bytes.  If more space is needed, an error will occur.
188
189       -outfile name
190              Send output image to the named file, not to standard output.
191
192       -memdst
193              Compress  to  memory instead of a file.  This feature was imple‐
194              mented mainly as a way of testing the in-memory destination man‐
195              ager  (jpeg_mem_dest()), but it is also useful for benchmarking,
196              since it reduces the I/O overhead.
197
198       -report
199              Report compression progress.
200
201       -strict
202              Treat all warnings as fatal.  Enabling this  option  will  cause
203              the  compressor  to  abort  if an LZW-compressed GIF input image
204              contains incomplete or corrupt image data.
205
206       -verbose
207              Enable debug printout.  More -v's give more output.  Also,  ver‐
208              sion information is printed at startup.
209
210       -debug Same as -verbose.
211
212       -version
213              Print version information and exit.
214
215       The  -restart option inserts extra markers that allow a JPEG decoder to
216       resynchronize after a transmission error.  Without restart markers, any
217       damage  to a compressed file will usually ruin the image from the point
218       of the error to the end of the image; with restart markers, the  damage
219       is  usually confined to the portion of the image up to the next restart
220       marker.  Of course, the restart markers occupy extra space.  We  recom‐
221       mend  -restart  1 for images that will be transmitted across unreliable
222       networks such as Usenet.
223
224       The -smooth option filters the input  to  eliminate  fine-scale  noise.
225       This  is often useful when converting dithered images to JPEG: a moder‐
226       ate smoothing factor of 10 to 50 gets rid of dithering patterns in  the
227       input  file,  resulting in a smaller JPEG file and a better-looking im‐
228       age.  Too large a smoothing factor will visibly blur  the  image,  how‐
229       ever.
230
231       Switches for wizards:
232
233       -baseline
234              Force  baseline-compatible  quantization tables to be generated.
235              This clamps quantization values to 8 bits even  at  low  quality
236              settings.   (This  switch is poorly named, since it does not en‐
237              sure that the output is actually baseline  JPEG.   For  example,
238              you can use -baseline and -progressive together.)
239
240       -qtables file
241              Use the quantization tables given in the specified text file.
242
243       -qslots N[,...]
244              Select which quantization table to use for each color component.
245
246       -sample HxV[,...]
247              Set JPEG sampling factors for each color component.
248
249       -scans file
250              Use the scan script given in the specified text file.
251
252       The  "wizard"  switches are intended for experimentation with JPEG.  If
253       you don't know what you are doing, don't use them.  These switches  are
254       documented further in the file wizard.txt.
255

EXAMPLES

257       This  example  compresses the PPM file foo.ppm with a quality factor of
258       60 and saves the output as foo.jpg:
259
260              cjpeg -quality 60 foo.ppm > foo.jpg
261

HINTS

263       Color GIF files are not the ideal input for JPEG; JPEG  is  really  in‐
264       tended  for  compressing  full-color  (24-bit)  images.  In particular,
265       don't try to convert cartoons, line drawings,  and  other  images  that
266       have  only  a few distinct colors.  GIF works great on these, JPEG does
267       not.  If you want to convert a GIF to JPEG, you should experiment  with
268       cjpeg's  -quality and -smooth options to get a satisfactory conversion.
269       -smooth 10 or so is often helpful.
270
271       Avoid running an image through a series of JPEG  compression/decompres‐
272       sion  cycles.   Image quality loss will accumulate; after ten or so cy‐
273       cles the image may be noticeably worse than it  was  after  one  cycle.
274       It's  best  to  use a lossless format while manipulating an image, then
275       convert to JPEG format when you are ready to file the image away.
276
277       The -optimize option to cjpeg is worth using when you are making a "fi‐
278       nal"  version  for  posting or archiving.  It's also a win when you are
279       using low quality settings to make very small JPEG files; the  percent‐
280       age  improvement  is  often a lot more than it is on larger files.  (At
281       present, -optimize mode is always selected when generating  progressive
282       JPEG files.)
283

ENVIRONMENT

285       JPEGMEM
286              If  this  environment  variable is set, its value is the default
287              memory limit.  The value  is  specified  as  described  for  the
288              -maxmemory  switch.   JPEGMEM overrides the default value speci‐
289              fied when the program was compiled, and itself is overridden  by
290              an explicit -maxmemory.
291

SEE ALSO

293       djpeg(1), jpegtran(1), rdjpgcom(1), wrjpgcom(1)
294       ppm(5), pgm(5)
295       Wallace,  Gregory  K.   "The  JPEG Still Picture Compression Standard",
296       Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.
297

AUTHOR

299       Independent JPEG Group
300
301       This file was modified by The libjpeg-turbo Project to include only in‐
302       formation relevant to libjpeg-turbo, to wordsmith certain sections, and
303       to describe features not present in libjpeg.
304

ISSUES

306       Not all variants of BMP and Targa file formats are supported.
307
308       The -targa switch is not a bug, it's a feature.  (It would be a bug  if
309       the Targa format designers had not been clueless.)
310
311
312
313                               30 November 2021                       CJPEG(1)
Impressum