Debian Codegraph @

upstream/debian-unstable/man1/pnmtojpeg.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pnmtojpeg User Manual" 1 "23 April 2007" "netpbm documentation"
7
8 .SH NAME
9 pnmtojpeg - convert PNM image to a JFIF ("JPEG") image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpnmtojpeg\fP
15 [\fB-exif=\fP\fIfilespec\fP]
16 [\fB-quality=\fP\fIn\fP]
17 [{\fB-grayscale\fP|\fB-greyscale\fP}]
18 [\fB-density=\fP\fIn\fP\fBx\fP\fIn\fP[\fBdpi\fP,\fBdpcm\fP]]
19 [\fB-optimize\fP|\fB-optimise\fP]
20 [\fB-rgb\fP]
21 [\fB-progressive\fP]
22 [\fB-comment=\fP\fItext\fP]
23 [\fB-dct=\fP{\fBint\fP|\fBfast\fP|\fBfloat\fP}]
24 [\fB-arithmetic\fP]
25 [\fB-restart=\fP\fIn\fP]
26 [\fB-smooth=\fP\fIn\fP]
27 [\fB-maxmemory=\fP\fIn\fP]
28 [\fB-verbose\fP]
29 [\fB-baseline\fP]
30 [\fB-qtables=\fP\fIfilespec\fP]
31 [\fB-qslots=n[,...]\fP]
32 [\fB-sample=\fP\fIH\fP\fBx\fP\fIV\fP[,...]]
33 [\fB-scans=\fP\fIfilespec\fP]
34 [\fB-tracelevel=\fP\fIN\fP]
35
36 \fIfilename\fP
37 .PP
38 Minimum unique abbreviation of option is acceptable. You may use double
39 hyphens instead of single hyphen to denote options. You may use white
40 space in place of the equals sign to separate an option name from its value.
41
42
43 .UN description
44 .SH DESCRIPTION
45 .PP
46 This program is part of
47 .BR "Netpbm" (1)\c
48 \&.
49 .PP
50 \fBpnmtojpeg\fP converts the named PBM, PGM, or PPM image file, or
51 the standard input if no file is named, to a JFIF file on the standard
52 output.
53 .PP
54 \fBpnmtojpeg\fP uses the Independent JPEG Group's JPEG library to
55 create the output file. See \fB
56 .UR http://www.ijg.org
57 http://www.ijg.org
58 .UE
59 \& \fP for information
60 on the library.
61 .PP
62 "JFIF" is the correct name for the image format commonly
63 known as "JPEG." Strictly speaking, JPEG is a method of
64 compression. The image format using JPEG compression that is by far
65 the most common is JFIF. There is also a subformat of TIFF that uses
66 JPEG compression.
67 .PP
68 EXIF is an image format that is a subformat of JFIF (to wit, a JFIF
69 file that contains an EXIF header as an APP1 marker).
70 \fBpnmtojpeg\fP creates an EXIF image when you specify the
71 \fB-exif\fP option.
72
73 .UN options
74 .SH OPTIONS
75 .PP
76 In addition to the options common to all programs based on libnetpbm
77 (most notably \fB-quiet\fP, see
78 .UR index.html#commonoptions
79 Common Options
80 .UE
81 \&), \fBpnmtojpeg\fP recognizes the following
82 command line options:
83
84 .UN basicopts
85 .SS Basic Options
86
87
88 .TP
89 \fB-exif=\fP\fIfilespec\fP
90 This option specifies that the output image is to be EXIF (a subformat
91 of JFIF), i.e. it will have an EXIF header as a JFIF APP1 marker.
92 The contents of that marker are the contents of the specified file.
93 The special value \fB-\fP
94 means to read the EXIF header contents from standard input. It is
95 invalid to specify standard input for both the EXIF header and the
96 input image.
97 .sp
98 The EXIF file starts with a two byte field which is the length of
99 the file, including the length field, in pure binary, most significant
100 byte first. The special value of zero for the length field means there
101 is to be no EXIF header, i.e. the same as no \fB-exif\fP
102 option. This is useful for when you convert a file from JFIF to PNM
103 using \fBjpegtopnm\fP,
104 then transform it, then convert it back to JFIF with
105 \fBpnmtojpeg\fP, and you don't know whether or not it includes an EXIF header.
106 \fBjpegtopnm\fP
107 creates an EXIF file containing nothing but two bytes of zero when
108 the input JFIF file has no EXIF header. Thus, you can transfer
109 any EXIF header from the input JFIF to the output JFIF without
110 worrying about whether an EXIF header actually exists.
111 .sp
112 The contents of the EXIF file after the length field are the exact
113 byte for byte contents of the APP1 marker, not counting the length
114 field, that constitutes the EXIF header.
115
116 .TP
117 \fB-quality=\fP\fIn\fP
118 Scale quantization tables to adjust image quality. \fIn\fP is 0
119 (worst) to 100 (best); default is 75. Below about 25 can produce images
120 some interpreters won't be able to interpret. See below for more info.
121
122 .TP
123 \fB-grayscale\fP
124 .TP
125 \fB-greyscale\fP
126 .TP
127 \fB-rgb\fP
128 These options determine the color space used in the JFIF output.
129 \fB-grayscale\fP (or \fB-greyscale\fP) means to create a gray scale
130 JFIF, converting from color PPM input if necessary. \fB-rgb\fP means to
131 create an RGB JFIF, and the program fails if the input is not PPM.
132 .sp
133 If you specify neither, The output file is in YCbCr format if the
134 input is PPM, and grayscale format if the input is PBM or PGM.
135 .sp
136 YCbCr format (a color is represented by an intensity value and two
137 chrominance values) usually compresses much better than RGB (a color
138 is represented by one red, one green, and one blue value). RGB is
139 rare. But you may be able to convert between JFIF and PPM faster with
140 RGB, since it's the same color space PPM uses.
141 .sp
142 The \fBtestimg.ppm\fP file that comes with Netpbm is 2.3 times
143 larger with the \fB-rgb\fP option than with the YCbCr default, and in
144 one experiment \fBpnmtojpeg\fP took 16% more CPU time to convert it.
145 The extra CPU time probably indicates that processing of all the extra
146 compressed data consumed all the CPU time saved by not having to
147 convert the RGB inputs to YCbCr.
148 .sp
149 Grayscale format takes up a lot less space and takes less time to create
150 and process than the color formats, even if the image contains nothing
151 but black, white, and gray.
152 .sp
153 The \fB-rgb\fP option was added in Netpbm 10.11 in October 2002.
154
155 .TP
156 \fB-density=\fP\fIdensity\fP
157 This option determines the density (aka resolution) information
158 recorded in the JFIF output image. It does not affect the raster in
159 any way; it just tells whoever reads the JFIF how to interpret the
160 raster.
161 .sp
162 The density value takes the form \fIx\fP\fBx\fP\fIy\fP followed
163 by an optional unit specifier of \fBdpi\fP or \fBdpcm\fP. Examples:
164 \fB1x1\fP, \fB3x2\fP, \fB300x300dpi\fP, \fB100x200dpcm\fP. The
165 first number is the horizontal density; the 2nd number is the vertical
166 density. Each may be any integer from 1 to 65535. The unit specifier
167 is \fBdpi\fP for dots per inch or \fBdpcm\fP for dots per
168 centimeter. If you don't specify the units, the density information
169 goes into the JFIF explicitly stating "density unspecified" (also
170 interpreted as "unknown"). This may seem pointless, but note that
171 even without specifying the units, the density numbers tell the aspect
172 ratio of the pixels. E.g. \fB1x1\fP tells you the pixels are square.
173 \fB3x2\fP tells you the pixels are vertical rectangles.
174 .sp
175 Note that if you specify different horizontal and vertical
176 densities, the resulting JFIF image is \fInot\fP a true
177 representation of the input PNM image, because \fBpnmtojpeg\fP
178 converts the raster pixel-for-pixel and the pixels of a PNM image are
179 defined to be square. Thus, if you start with a square PNM image and
180 specify \fB-density=3x2\fP, the resulting JFIF image is a horizontally
181 squashed version of the original. However, it is common to use an
182 input image which is a slight variation on PNM rather than true PNM
183 such that the pixels are not square. In that case, the appropriate
184 -density option yields a faithful reproduction of the input pseudo-PNM
185 image.
186 .sp
187 The default is 1x1 in unspecified units.
188 .sp
189 Before Netpbm 10.15 (April 2003), this option did not exist and the
190 \fBpnmtojpeg\fP always created a JFIF with a density of 1x1 in
191 unspecified units.
192
193 .TP
194 \fB-optimize\fP
195 Perform optimization of entropy encoding parameters. Without
196 this, \fBpnmtojpeg\fP uses default encoding parameters.
197 \fB-optimize\fP usually makes the JFIF file a little smaller, but
198 \fBpnmtojpeg\fP runs somewhat slower and needs much more memory.
199 Image quality and speed of decompression are unaffected by
200 \fB-optimize\fP.
201
202 .TP
203 \fB-progressive\fP
204 Create a progressive JPEG file (see below).
205 .TP
206 \fB-comment=\fP\fItext\fP
207 Include a comment marker in the JFIF output, with comment text
208 \fItext\fP.
209
210 Without this option, there are no comment markers in the output.
211
212
213 .PP
214 The \fB-quality\fP option lets you trade off compressed file size
215 against quality of the reconstructed image: the higher the quality
216 setting, the larger the JFIF file, and the closer the output image
217 will be to the original input. Normally you want to use the lowest
218 quality setting (smallest file) that decompresses into something
219 visually indistinguishable from the original image. For this purpose
220 the quality setting should be between 50 and 95 for reasonable
221 results; the default of 75 is often about right. If you see defects
222 at \fB-quality=75\fP, then go up 5 or 10 counts at a time until you
223 are happy with the output image. (The optimal setting will vary from
224 one image to another.)
225 .PP
226 \fB-quality=100\fP generates a quantization table of all 1's,
227 minimizing loss in the quantization step (but there is still
228 information loss in subsampling, as well as roundoff error). This
229 setting is of interest mainly for experimental purposes. Quality
230 values above about 95 are \fInot\fP recommended for normal use; the
231 compressed file size goes up dramatically for hardly any gain in
232 output image quality.
233 .PP
234 In the other direction, quality values below 50 will produce very
235 small files of low image quality. Settings around 5 to 10 might be
236 useful in preparing an index of a large image library, for example.
237 Try \fB-quality=2\fP (or so) for some amusing Cubist effects. (Note:
238 quality values below about 25 generate 2-byte quantization tables,
239 which are considered optional in the JFIF standard. \fBpnmtojpeg\fP
240 emits a warning message when you give such a quality value, because
241 some other JFIF programs may be unable to decode the resulting file.
242 Use \fB-baseline\fP if you need to ensure compatibility at low
243 quality values.)
244 .PP
245 The \fB-progressive\fP option creates a "progressive
246 JPEG" file. In this type of JFIF file, the data is stored in
247 multiple scans of increasing quality. If the file is being
248 transmitted over a slow communications link, the decoder can use the
249 first scan to display a low-quality image very quickly, and can then
250 improve the display with each subsequent scan. The final image is
251 exactly equivalent to a standard JFIF file of the same quality
252 setting, and the total file size is about the same -- often a little
253 smaller.
254 .PP
255 \fBCaution:\fP progressive JPEG is not yet widely
256 implemented, so many decoders will be unable to view a progressive
257 JPEG file at all.
258 .PP
259 If you're trying to control the quality/file size tradeoff, you
260 might consider the JPEG2000 format instead. See
261 .BR "pamtojpeg2k" (1)\c
262 \&.
263
264 .UN advancedopts
265 .SS Advanced options
266
267
268
269 .TP
270 \fB-dct=int\fP
271 Use integer DCT method (default).
272
273 .TP
274 \fB-dct=fast\fP
275 Use fast integer DCT (less accurate).
276
277 .TP
278 \fB-dct=float\fP
279 Use floating-point DCT method. The float method is very slightly
280 more accurate than the int method, but is much slower unless your
281 machine has very fast floating-point hardware. Also note that results
282 of the floating-point method may vary slightly across machines, while
283 the integer methods should give the same results everywhere. The fast
284 integer method is much less accurate than the other two.
285
286 .TP
287 \fB-arithmetic\fP
288 Use arithmetic coding. Default is Huffman encoding. Arithmetic coding
289 tends to get you a smaller result.
290 .sp
291 You may need patent licenses to use this option. According to
292 .UR http://www.faqs.org/faqs/jpeg-faq
293 the JPEG FAQ
294 .UE
295 \&,
296 This method is covered by patents owned by IBM, AT&T, and Mitsubishi.
297 .sp
298 The author of the FAQ recommends against using arithmetic coding (and
299 therefore this option) because the space savings is not great enough to
300 justify the legal hassles.
301 .sp
302 Most JPEG libraries, including any distributed by the Independent
303 JPEG Group since about 1998 are not capable of arithmetic encoding.
304 \fBpnmtojpeg\fP uses a JPEG library (either bound to it when the
305 \fBpnmtojpeg\fP executable was built or accessed on your system at
306 run time) to do the JPEG encoding. If \fBpnmtojpeg\fP terminates
307 with the message, "Sorry, there are legal restrictions on
308 arithmetic coding" or "Sorry, arithmetic coding not
309 supported," this is the problem.
310
311 .TP
312 \fB-restart=\fP\fIn\fP
313 Emit a JPEG restart marker every \fIn\fP MCU rows, or every \fIn\fP
314 MCU blocks if you append \fBB\fP to the number. \fB-restart 0\fP
315 (the default) means no restart markers.
316
317 .TP
318 \fB-smooth=\fP\fIn\fP
319 Smooth the input image to eliminate dithering noise. \fIn\fP,
320 ranging from 1 to 100, indicates the strength of smoothing. 0 (the
321 default) means no smoothing.
322
323 .TP
324 \fB-maxmemory=\fP\fIn\fP
325 Set a limit for amount of memory to use in processing large images. Value is
326 in thousands of bytes, or millions of bytes if you append
327 \fBM\fP to the number. For example, \fB-max=4m\fP
328 selects 4,000,000 bytes. If \fBpnmtojpeg\fP
329 needs more space, it will use temporary files.
330
331 .TP
332 \fB-verbose\fP
333 Print to the Standard Error file messages about the conversion process.
334 This can be helpful in debugging problems.
335
336 .PP
337 The \fB-restart\fP option tells \fBpnmtojpeg \fP to insert extra
338 markers that allow a JPEG decoder to resynchronize after a
339 transmission error. Without restart markers, any damage to a
340 compressed file will usually ruin the image from the point of the
341 error to the end of the image; with restart markers, the damage is
342 usually confined to the portion of the image up to the next restart
343 marker. Of course, the restart markers occupy extra space. We
344 recommend \fB-restart=1\fP for images that will be transmitted
345 across unreliable networks such as Usenet.
346 .PP
347 The \fB-smooth\fP option filters the input to eliminate
348 fine-scale noise. This is often useful when converting dithered
349 images to JFIF: a moderate smoothing factor of 10 to 50 gets rid of
350 dithering patterns in the input file, resulting in a smaller JFIF file
351 and a better-looking image. Too large a smoothing factor will visibly
352 blur the image, however.
353
354 .UN wizardopts
355 .SS Wizard Options
356
357
358 .TP
359 \fB-baseline\fP
360 Force baseline-compatible quantization tables to be generated.
361 This clamps quantization values to 8 bits even at low quality
362 settings. (This switch is poorly named, since it does not ensure that
363 the output is actually baseline JPEG. For example, you can use
364 \fB-baseline\fP and \fB-progressive\fP together.)
365
366 .TP
367 \fB-qtables=\fP\fIfilespec\fP
368 Use the quantization tables given in the specified text file.
369
370 .TP
371 \fB-qslots=n[,...]\fP
372 Select which quantization table to use for each color component.
373
374 .TP
375 \fB-sample=\fP\fIH\fP\fBx\fP\fIV\fP[,...]
376 Set JPEG sampling factors for each color component.
377
378 .TP
379 \fB-scans=\fP\fIfilespec\fP
380 Use the scan script given in the specified text file. See below
381 for information on scan scripts.
382
383 .TP
384 \fB-tracelevel=\fP\fIN\fP
385 This sets the level of debug tracing the program outputs as it runs.
386 0 means none, and is the default. This level primarily controls tracing
387 of the JPEG library, and you can get some pretty interesting information
388 about the compression process.
389
390
391 .PP
392 The "wizard" options are intended for experimentation
393 with JPEG. If you don't know what you are doing, \fBdon't use
394 them\fP. These switches are documented further in the file
395 wizard.doc that comes with the Independent JPEG Group's JPEG library.
396
397 .UN examples
398 .SH EXAMPLES
399 .PP
400 This example compresses the PPM file foo.ppm with a quality factor
401 of 60 and saves the output as foo.jpg:
402
403 .nf
404 \fBpnmtojpeg -quality=60 foo.ppm > foo.jpg\fP
405
406 .fi
407 .PP
408 Here's a more typical example. It converts from BMP to JFIF:
409
410 .nf
411 \fBcat foo.bmp | bmptoppm | pnmtojpeg > foo.jpg\fP
412
413 .fi
414
415 .UN loss
416 .SH JPEG LOSS
417 .PP
418 When you compress with JPEG, you lose information -- i.e. the resulting
419 image has somewhat lower quality than the original. This is a characteristic
420 of JPEG itself, not any particular program. So if you do the usual
421 Netpbm thing and convert from JFIF to PNM, manipulate, then convert back
422 to JFIF, you will lose quality. The more you do it, the more you lose.
423 Drawings (charts, cartoons, line drawings, and such with few colors
424 and sharp edges) suffer the most.
425 .PP
426 To avoid this, you can use a compressed image format other than
427 JPEG. PNG and JPEG2000 are good choices, and Netpbm contains converters
428 for those.
429 .PP
430 If you need to use JFIF on a drawing, you should experiment with
431 \fBpnmtojpeg\fP's \fB-quality\fP and \fB-smooth\fP options to get a
432 satisfactory conversion. \fB-smooth 10\fP or so is often helpful.
433 .PP
434 Because of the loss, you should do all the manipulation you have to
435 do on the image in some other format and convert to JFIF as the last
436 step. And if you can keep a copy in the original format, so much the
437 better.
438
439 The \fB-optimize\fP option to \fBpnmtojpeg\fP is worth using when
440 you are making a "final" version for posting or archiving.
441 It's also a win when you are using low quality settings to make very
442 small JFIF files; the percentage improvement is often a lot more than
443 it is on larger files. (At present, \fB-optimize\fP mode is
444 automatically in effect when you generate a progressive JPEG file).
445 .PP
446 You can do flipping and rotating transformations losslessly with
447 the program \fBjpegtran\fP, which is packaged with the Independent
448 Jpeg Group's JPEG library. \fBjpegtran\fP exercises its intimate
449 knowledge of the way JPEG works to do the transformation without ever
450 actually decompressing the image.
451
452 .UN otherprog
453 .SH OTHER PROGRAMS
454 .PP
455 Another program, \fBcjpeg\fP, is similar. \fBcjpeg\fP is
456 maintained by the Independent JPEG Group and packaged with the JPEG
457 library which \fBpnmtojpeg\fP uses for all its JPEG work. Because of
458 that, you may expect it to exploit more current JPEG features. Also,
459 since you have to have the library to run \fBpnmtojpeg\fP, but not
460 vice versa, \fBcjpeg\fP may be more commonly available.
461 .PP
462 On the other hand, \fBcjpeg\fP does not use the NetPBM libraries
463 to process its input, as all the NetPBM tools such as \fBpnmtojpeg\fP
464 do. This means it is less likely to be consistent with all the other
465 programs that deal with the NetPBM formats. Also, the command syntax
466 of \fBpnmtojpeg\fP is consistent with that of the other Netpbm tools,
467 unlike \fBcjpeg\fP.
468
469 .UN scanscripts
470 .SH SCAN SCRIPTS
471 .PP
472 Use the \fB-scan\fP option to specify a scan script. Or use the
473 \fB-progressive\fP option to specify a particular built-in scan
474 script.
475 .PP
476 Just what a scan script is, and the basic format of the scan script
477 file, is covered in the \fBwizard.doc\fP file that comes with the
478 Independent JPEG Group's JPEG library. Scan scripts are same for
479 \fBpnmtojpeg\fP as the are for \fBcjpeg\fP.
480 .PP
481 This section contains additional information that isn't, but
482 probably should be, in that document.
483 .PP
484 First, there are many restrictions on what is a valid scan script.
485 The JPEG library, and thus \fBpnmtojpeg\fP, checks thoroughly for any
486 lack of compliance with these restrictions, but does little to tell
487 you how the script fails to comply. The messages are very general and
488 sometimes untrue.
489 .PP
490 To start with, the entries for the DC coefficient must come before any
491 entries for the AC coefficients. The DC coefficient is Coefficient 0;
492 all the other coefficients are AC coefficients. So in an entry for
493 the DC coefficient, the two numbers after the colon must be 0 and 0.
494 In an entry for AC coefficients, the first number after the colon must
495 not be 0.
496 .PP
497 In a DC entry, the color components must be in increasing order.
498 E.g. "0,2,1" before the colon is wrong. So is "0,0,0".
499 .PP
500 In an entry for an AC coefficient, you must specify only one color
501 component. I.e. there can be only one number before the colon.
502 .PP
503 In the first entry for a particular coefficient for a particular color
504 component, the "Ah" value must be zero, but the Al value can be any
505 valid bit number. In subsequent entries, Ah must be the Al value from
506 the previous entry (for that coefficient for that color component),
507 and the Al value must be one less than the Ah value.
508 .PP
509 The script must ultimately specify at least some of the DC coefficient
510 for every color component. Otherwise, you get the error message
511 "Script does not transmit all the data." You need not specify all of
512 the bits of the DC coefficient, or any of the AC coefficients.
513 .PP
514 There is a standard option in building the JPEG library to omit scan
515 script capability. If for some reason your library was built with
516 this option, you get the message "Requested feature was omitted at
517 compile time."
518
519 .UN environment
520 .SH ENVIRONMENT
521
522
523 .TP
524 \fBJPEGMEM\fP
525 If this environment variable is set, its value is the default
526 memory limit. The value is specified as described for the
527 \fB-maxmemory\fP option. An explicit \fB-maxmemory \fP option
528 overrides any \fBJPEGMEM\fP.
529
530
531
532 .UN seealso
533 .SH SEE ALSO
534 .BR "jpegtopnm" (1)\c
535 \&,
536 .BR "pnm" (1)\c
537 \&,
538 \fBcjpeg\fP man page,
539 \fBdjpeg\fP man page,
540 \fBjpegtran\fP man page,
541 \fBrdjpgcom\fP man page,
542 \fBwrjpgcom\fP man page
543 .PP
544 Wallace, Gregory K. "The JPEG Still Picture Compression
545 Standard", Communications of the ACM, April 1991 (vol. 34,
546 no. 4), pp. 30-44.
547
548
549 .UN author
550 .SH AUTHOR
551
552 \fBpnmtojpeg\fP and this manual were derived in large part from
553 \fBcjpeg\fP, by the Independent JPEG Group. The program is otherwise
554 by Bryan Henderson on March 07, 2000.
555 .SH DOCUMENT SOURCE
556 This manual page was generated by the Netpbm tool 'makeman' from HTML
557 source. The master documentation is at
558 .IP
559 .B http://netpbm.sourceforge.net/doc/pnmtojpeg.html
560 .PP