Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/libjpeg/cjpeg.1 @ 2:b50eed0cc0ef upstream

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