grub2: bring back build of aros-side grub2 tools
[AROS.git] / workbench / libs / jpeg / cjpeg.1
blobe0b8d4302e763045718f780d3db3207d4d6b38ac
1 .TH CJPEG 1 "4 May 2012"
2 .SH NAME
3 cjpeg \- compress an image file to a JPEG file
4 .SH SYNOPSIS
5 .B cjpeg
7 .I options
10 .I filename
12 .LP
13 .SH DESCRIPTION
14 .LP
15 .B cjpeg
16 compresses the named image file, or the standard input if no file is
17 named, and produces a JPEG/JFIF file on the standard output.
18 The currently supported input file formats are: PPM (PBMPLUS color
19 format), PGM (PBMPLUS gray-scale format), BMP, Targa, and RLE (Utah Raster
20 Toolkit format).  (RLE is supported only if the URT library is available.)
21 .SH OPTIONS
22 All switch names may be abbreviated; for example,
23 .B \-grayscale
24 may be written
25 .B \-gray
27 .BR \-gr .
28 Most of the "basic" switches can be abbreviated to as little as one letter.
29 Upper and lower case are equivalent (thus
30 .B \-BMP
31 is the same as
32 .BR \-bmp ).
33 British spellings are also accepted (e.g.,
34 .BR \-greyscale ),
35 though for brevity these are not mentioned below.
36 .PP
37 The basic switches are:
38 .TP
39 .BI \-quality " N[,...]"
40 Scale quantization tables to adjust image quality.  Quality is 0 (worst) to
41 100 (best); default is 75.  (See below for more info.)
42 .TP
43 .B \-grayscale
44 Create monochrome JPEG file from color input.  Be sure to use this switch when
45 compressing a grayscale BMP file, because
46 .B cjpeg
47 isn't bright enough to notice whether a BMP file uses only shades of gray.
48 By saying
49 .BR \-grayscale ,
50 you'll get a smaller JPEG file that takes less time to process.
51 .TP
52 .B \-rgb
53 Create RGB JPEG file.
54 Using this switch suppresses the conversion from RGB
55 colorspace input to the default YCbCr JPEG colorspace.
56 You can use this switch in combination with the
57 .BI \-block " N"
58 switch (see below) for lossless JPEG coding.
59 See also the
60 .B \-rgb1
61 switch below.
62 .TP
63 .B \-optimize
64 Perform optimization of entropy encoding parameters.  Without this, default
65 encoding parameters are used.
66 .B \-optimize
67 usually makes the JPEG file a little smaller, but
68 .B cjpeg
69 runs somewhat slower and needs much more memory.  Image quality and speed of
70 decompression are unaffected by
71 .BR \-optimize .
72 .TP
73 .B \-progressive
74 Create progressive JPEG file (see below).
75 .TP
76 .BI \-scale " M/N"
77 Scale the output image by a factor M/N.  Currently supported scale factors are
78 M/N with all N from 1 to 16, where M is the destination DCT size, which is 8
79 by default (see
80 .BI \-block " N"
81 switch below).
82 .TP
83 .B \-targa
84 Input file is Targa format.  Targa files that contain an "identification"
85 field will not be automatically recognized by
86 .BR cjpeg ;
87 for such files you must specify
88 .B \-targa
89 to make
90 .B cjpeg
91 treat the input as Targa format.
92 For most Targa files, you won't need this switch.
93 .PP
94 The
95 .B \-quality
96 switch lets you trade off compressed file size against quality of the
97 reconstructed image: the higher the quality setting, the larger the JPEG file,
98 and the closer the output image will be to the original input.  Normally you
99 want to use the lowest quality setting (smallest file) that decompresses into
100 something visually indistinguishable from the original image.  For this
101 purpose the quality setting should be between 50 and 95; the default of 75 is
102 often about right.  If you see defects at
103 .B \-quality
104 75, then go up 5 or 10 counts at a time until you are happy with the output
105 image.  (The optimal setting will vary from one image to another.)
107 .B \-quality
108 100 will generate a quantization table of all 1's, minimizing loss in the
109 quantization step (but there is still information loss in subsampling, as well
110 as roundoff error).  This setting is mainly of interest for experimental
111 purposes.  Quality values above about 95 are
112 .B not
113 recommended for normal use; the compressed file size goes up dramatically for
114 hardly any gain in output image quality.
116 In the other direction, quality values below 50 will produce very small files
117 of low image quality.  Settings around 5 to 10 might be useful in preparing an
118 index of a large image library, for example.  Try
119 .B \-quality
120 2 (or so) for some amusing Cubist effects.  (Note: quality
121 values below about 25 generate 2-byte quantization tables, which are
122 considered optional in the JPEG standard.
123 .B cjpeg
124 emits a warning message when you give such a quality value, because some
125 other JPEG programs may be unable to decode the resulting file.  Use
126 .B \-baseline
127 if you need to ensure compatibility at low quality values.)
130 .B \-quality
131 option has been extended in IJG version 7 for support of separate quality
132 settings for luminance and chrominance (or in general, for every provided
133 quantization table slot).  This feature is useful for high-quality
134 applications which cannot accept the damage of color data by coarse
135 subsampling settings.  You can now easily reduce the color data amount more
136 smoothly with finer control without separate subsampling.  The resulting file
137 is fully compliant with standard JPEG decoders.
138 Note that the
139 .B \-quality
140 ratings refer to the quantization table slots, and that the last value is
141 replicated if there are more q-table slots than parameters.  The default
142 q-table slots are 0 for luminance and 1 for chrominance with default tables as
143 given in the JPEG standard.  This is compatible with the old behaviour in case
144 that only one parameter is given, which is then used for both luminance and
145 chrominance (slots 0 and 1).  More or custom quantization tables can be set
146 with
147 .B \-qtables
148 and assigned to components with
149 .B \-qslots
150 parameter (see the "wizard" switches below).
151 .B Caution:
152 You must explicitly add
153 .BI \-sample " 1x1"
154 for efficient separate color
155 quality selection, since the default value used by library is 2x2!
158 .B \-progressive
159 switch creates a "progressive JPEG" file.  In this type of JPEG file, the data
160 is stored in multiple scans of increasing quality.  If the file is being
161 transmitted over a slow communications link, the decoder can use the first
162 scan to display a low-quality image very quickly, and can then improve the
163 display with each subsequent scan.  The final image is exactly equivalent to a
164 standard JPEG file of the same quality setting, and the total file size is
165 about the same --- often a little smaller.
167 Switches for advanced users:
169 .B \-arithmetic
170 Use arithmetic coding.
171 .B Caution:
172 arithmetic coded JPEG is not yet widely implemented, so many decoders will
173 be unable to view an arithmetic coded JPEG file at all.
175 .BI \-block " N"
176 Set DCT block size.  All N from 1 to 16 are possible.
177 Default is 8 (baseline format).
178 Larger values produce higher compression,
179 smaller values produce higher quality
180 (exact DCT stage possible with 1 or 2; with the default quality of 75 and
181 default Luminance qtable the DCT+Quantization stage is lossless for N=1).
182 .B Caution:
183 An implementation of the JPEG SmartScale extension is required for this
184 feature.  SmartScale enabled JPEG is not yet widely implemented, so many
185 decoders will be unable to view a SmartScale extended JPEG file at all.
187 .B \-rgb1
188 Create RGB JPEG file with reversible color transform.
189 Works like the
190 .B \-rgb
191 switch (see above) and inserts a simple reversible color transform
192 into the processing which significantly improves the compression.
193 Use this switch in combination with the
194 .BI \-block " N"
195 switch (see above) for lossless JPEG coding.
196 .B Caution:
197 A decoder with inverse color transform support is required for
198 this feature.  Reversible color transform support is not yet
199 widely implemented, so many decoders will be unable to view
200 a reversible color transformed JPEG file at all.
202 .B \-dct int
203 Use integer DCT method (default).
205 .B \-dct fast
206 Use fast integer DCT (less accurate).
208 .B \-dct float
209 Use floating-point DCT method.
210 The float method is very slightly more accurate than the int method, but is
211 much slower unless your machine has very fast floating-point hardware.  Also
212 note that results of the floating-point method may vary slightly across
213 machines, while the integer methods should give the same results everywhere.
214 The fast integer method is much less accurate than the other two.
216 .B \-nosmooth
217 Don't use high-quality downsampling.
219 .BI \-restart " N"
220 Emit a JPEG restart marker every N MCU rows, or every N MCU blocks if "B" is
221 attached to the number.
222 .B \-restart 0
223 (the default) means no restart markers.
225 .BI \-smooth " N"
226 Smooth the input image to eliminate dithering noise.  N, ranging from 1 to
227 100, indicates the strength of smoothing.  0 (the default) means no smoothing.
229 .BI \-maxmemory " N"
230 Set limit for amount of memory to use in processing large images.  Value is
231 in thousands of bytes, or millions of bytes if "M" is attached to the
232 number.  For example,
233 .B \-max 4m
234 selects 4000000 bytes.  If more space is needed, temporary files will be used.
236 .BI \-outfile " name"
237 Send output image to the named file, not to standard output.
239 .B \-verbose
240 Enable debug printout.  More
241 .BR \-v 's
242 give more output.  Also, version information is printed at startup.
244 .B \-debug
245 Same as
246 .BR \-verbose .
249 .B \-restart
250 option inserts extra markers that allow a JPEG decoder to resynchronize after
251 a transmission error.  Without restart markers, any damage to a compressed
252 file will usually ruin the image from the point of the error to the end of the
253 image; with restart markers, the damage is usually confined to the portion of
254 the image up to the next restart marker.  Of course, the restart markers
255 occupy extra space.  We recommend
256 .B \-restart 1
257 for images that will be transmitted across unreliable networks such as Usenet.
260 .B \-smooth
261 option filters the input to eliminate fine-scale noise.  This is often useful
262 when converting dithered images to JPEG: a moderate smoothing factor of 10 to
263 50 gets rid of dithering patterns in the input file, resulting in a smaller
264 JPEG file and a better-looking image.  Too large a smoothing factor will
265 visibly blur the image, however.
267 Switches for wizards:
269 .B \-baseline
270 Force baseline-compatible quantization tables to be generated.  This clamps
271 quantization values to 8 bits even at low quality settings.  (This switch is
272 poorly named, since it does not ensure that the output is actually baseline
273 JPEG.  For example, you can use
274 .B \-baseline
276 .B \-progressive
277 together.)
279 .BI \-qtables " file"
280 Use the quantization tables given in the specified text file.
282 .BI \-qslots " N[,...]"
283 Select which quantization table to use for each color component.
285 .BI \-sample " HxV[,...]"
286 Set JPEG sampling factors for each color component.
288 .BI \-scans " file"
289 Use the scan script given in the specified text file.
291 The "wizard" switches are intended for experimentation with JPEG.  If you
292 don't know what you are doing, \fBdon't use them\fR.  These switches are
293 documented further in the file wizard.txt.
294 .SH EXAMPLES
296 This example compresses the PPM file foo.ppm with a quality factor of
297 60 and saves the output as foo.jpg:
299 .B cjpeg \-quality
300 .I 60 foo.ppm
301 .B >
302 .I foo.jpg
303 .SH HINTS
304 Color GIF files are not the ideal input for JPEG; JPEG is really intended for
305 compressing full-color (24-bit) images.  In particular, don't try to convert
306 cartoons, line drawings, and other images that have only a few distinct
307 colors.  GIF works great on these, JPEG does not.  If you want to convert a
308 GIF to JPEG, you should experiment with
309 .BR cjpeg 's
310 .B \-quality
312 .B \-smooth
313 options to get a satisfactory conversion.
314 .B \-smooth 10
315 or so is often helpful.
317 Avoid running an image through a series of JPEG compression/decompression
318 cycles.  Image quality loss will accumulate; after ten or so cycles the image
319 may be noticeably worse than it was after one cycle.  It's best to use a
320 lossless format while manipulating an image, then convert to JPEG format when
321 you are ready to file the image away.
324 .B \-optimize
325 option to
326 .B cjpeg
327 is worth using when you are making a "final" version for posting or archiving.
328 It's also a win when you are using low quality settings to make very small
329 JPEG files; the percentage improvement is often a lot more than it is on
330 larger files.  (At present,
331 .B \-optimize
332 mode is always selected when generating progressive JPEG files.)
333 .SH ENVIRONMENT
335 .B JPEGMEM
336 If this environment variable is set, its value is the default memory limit.
337 The value is specified as described for the
338 .B \-maxmemory
339 switch.
340 .B JPEGMEM
341 overrides the default value specified when the program was compiled, and
342 itself is overridden by an explicit
343 .BR \-maxmemory .
344 .SH SEE ALSO
345 .BR djpeg (1),
346 .BR jpegtran (1),
347 .BR rdjpgcom (1),
348 .BR wrjpgcom (1)
350 .BR ppm (5),
351 .BR pgm (5)
353 Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",
354 Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.
355 .SH AUTHOR
356 Independent JPEG Group
357 .SH BUGS
358 GIF input files are no longer supported, to avoid the Unisys LZW patent.
359 (Conversion of GIF files to JPEG is usually a bad idea anyway.)
361 Not all variants of BMP and Targa file formats are supported.
364 .B \-targa
365 switch is not a bug, it's a feature.  (It would be a bug if the Targa format
366 designers had not been clueless.)