1Pnmtojpeg User Manual(0) Pnmtojpeg User Manual(0)
2
6 pnmtojpeg - convert PNM image to a JFIF ("JPEG") image
7
10 pnmtojpeg [-exif=filespec] [-quality=n] [{-grayscale|-greyscale}]
11 [-density=nxn[dpi,dpcm]] [-optimize|-optimise] [-rgb] [-progressive]
12 [-comment=text] [-dct={int|fast|float}] [-arithmetic] [-restart=n]
13 [-smooth=n] [-maxmemory=n] [-verbose] [-baseline] [-qtables=filespec]
14 [-qslots=n[,...]] [-sample=HxV[,...]] [-scans=filespec]
15 [-tracelevel=N]
16 filename
18 Minimum unique abbreviation of option is acceptable. You may use dou‐
20 ble hyphens instead of single hyphen to denote options. You may use
21 white space in place of the equals sign to separate an option name from
22 its value.
23
27 This program is part of Netpbm(1).
28 pnmtojpeg converts the named PBM, PGM, or PPM image file, or the stan‐
30 dard input if no file is named, to a JFIF file on the standard output.
31 pnmtojpeg uses the Independent JPEG Group's JPEG library to create the
33 output file. See http://www.ijg.org ⟨http://www.ijg.org⟩ for infor‐
34 mation on the library.
35 "JFIF" is the correct name for the image format commonly known as
37 "JPEG." Strictly speaking, JPEG is a method of compression. The image
38 format using JPEG compression that is by far the most common is JFIF.
39 There is also a subformat of TIFF that uses JPEG compression.
40 EXIF is an image format that is a subformat of JFIF (to wit, a JFIF
42 file that contains an EXIF header as an APP1 marker). pnmtojpeg cre‐
43 ates an EXIF image when you specify the -exif option.
44
47 In addition to the options common to all programs based on libnetpbm
48 (most notably -quiet, see
49 Common Options ⟨index.html#commonoptions⟩ ), pnmtojpeg recognizes the
50 following command line options:
51 Basic Options
54 -exif=filespec
55 This option specifies that the output image is to be EXIF (a
56 subformat of JFIF), i.e. it will have an EXIF header as a JFIF
57 APP1 marker. The contents of that marker are the contents of
58 the specified file. The special value - means to read the EXIF
59 header contents from standard input. It is invalid to specify
60 standard input for both the EXIF header and the input image.
61 The EXIF file starts with a two byte field which is the length
63 of the file, including the length field, in pure binary, most
64 significant byte first. The special value of zero for the
65 length field means there is to be no EXIF header, i.e. the same
66 as no -exif option. This is useful for when you convert a file
67 from JFIF to PNM using jpegtopnm, then transform it, then con‐
68 vert it back to JFIF with pnmtojpeg, and you don't know whether
69 or not it includes an EXIF header. jpegtopnm creates an EXIF
70 file containing nothing but two bytes of zero when the input
71 JFIF file has no EXIF header. Thus, you can transfer any EXIF
72 header from the input JFIF to the output JFIF without worrying
73 about whether an EXIF header actually exists.
74 The contents of the EXIF file after the length field are the ex‐
76 act byte for byte contents of the APP1 marker, not counting the
77 length field, that constitutes the EXIF header.
78 -quality=n
81 Scale quantization tables to adjust image quality. n is 0
82 (worst) to 100 (best); default is 75. Below about 25 can pro‐
83 duce images some interpreters won't be able to interpret. See
84 below for more info.
85 -grayscale
88 -greyscale
90 -rgb These options determine the color space used in the JFIF output.
92 -grayscale (or -greyscale) means to create a gray scale JFIF,
93 converting from color PPM input if necessary. -rgb means to
94 create an RGB JFIF, and the program fails if the input is not
95 PPM.
96 If you specify neither, The output file is in YCbCr format if
98 the input is PPM, and grayscale format if the input is PBM or
99 PGM.
100 YCbCr format (a color is represented by an intensity value and
102 two chrominance values) usually compresses much better than RGB
103 (a color is represented by one red, one green, and one blue
104 value). RGB is rare. But you may be able to convert between
105 JFIF and PPM faster with RGB, since it's the same color space
106 PPM uses.
107 The testimg.ppm file that comes with Netpbm is 2.3 times larger
109 with the -rgb option than with the YCbCr default, and in one ex‐
110 periment pnmtojpeg took 16% more CPU time to convert it. The
111 extra CPU time probably indicates that processing of all the ex‐
112 tra compressed data consumed all the CPU time saved by not hav‐
113 ing to convert the RGB inputs to YCbCr.
114 Grayscale format takes up a lot less space and takes less time
116 to create and process than the color formats, even if the image
117 contains nothing but black, white, and gray.
118 The -rgb option was added in Netpbm 10.11 in October 2002.
120 -density=density
123 This option determines the density (aka resolution) information
124 recorded in the JFIF output image. It does not affect the
125 raster in any way; it just tells whoever reads the JFIF how to
126 interpret the raster.
127 The density value takes the form xxy followed by an optional
129 unit specifier of dpi or dpcm. Examples: 1x1, 3x2, 300x300dpi,
130 100x200dpcm. The first number is the horizontal density; the
131 2nd number is the vertical density. Each may be any integer
132 from 1 to 65535. The unit specifier is dpi for dots per inch or
133 dpcm for dots per centimeter. If you don't specify the units,
134 the density information goes into the JFIF explicitly stating
135 "density unspecified" (also interpreted as "unknown"). This may
136 seem pointless, but note that even without specifying the units,
137 the density numbers tell the aspect ratio of the pixels. E.g.
138 1x1 tells you the pixels are square. 3x2 tells you the pixels
139 are vertical rectangles.
140 Note that if you specify different horizontal and vertical den‐
142 sities, the resulting JFIF image is not a true representation of
143 the input PNM image, because pnmtojpeg converts the raster
144 pixel-for-pixel and the pixels of a PNM image are defined to be
145 square. Thus, if you start with a square PNM image and specify
146 -density=3x2, the resulting JFIF image is a horizontally
147 squashed version of the original. However, it is common to use
148 an input image which is a slight variation on PNM rather than
149 true PNM such that the pixels are not square. In that case, the
150 appropriate -density option yields a faithful reproduction of
151 the input pseudo-PNM image.
152 The default is 1x1 in unspecified units.
154 Before Netpbm 10.15 (April 2003), this option did not exist and
156 the pnmtojpeg always created a JFIF with a density of 1x1 in un‐
157 specified units.
158 -optimize
161 Perform optimization of entropy encoding parameters. Without
162 this, pnmtojpeg uses default encoding parameters. -optimize
163 usually makes the JFIF file a little smaller, but pnmtojpeg runs
164 somewhat slower and needs much more memory. Image quality and
165 speed of decompression are unaffected by -optimize.
166 -progressive
169 Create a progressive JPEG file (see below).
170 -comment=text
172 Include a comment marker in the JFIF output, with comment text
173 text.
174 Without this option, there are no comment markers in the output.
176 The -quality option lets you trade off compressed file size against
180 quality of the reconstructed image: the higher the quality setting, the
181 larger the JFIF file, and the closer the output image will be to the
182 original input. Normally you want to use the lowest quality setting
183 (smallest file) that decompresses into something visually indistin‐
184 guishable from the original image. For this purpose the quality set‐
185 ting should be between 50 and 95 for reasonable results; the default of
186 75 is often about right. If you see defects at -quality=75, then go up
187 5 or 10 counts at a time until you are happy with the output image.
188 (The optimal setting will vary from one image to another.)
189 -quality=100 generates a quantization table of all 1's, minimizing loss
191 in the quantization step (but there is still information loss in sub‐
192 sampling, as well as roundoff error). This setting is mainly of inter‐
193 est for experimental purposes. Quality values above about 95 are not
194 recommended for normal use; the compressed file size goes up dramati‐
195 cally for hardly any gain in output image quality.
196 In the other direction, quality values below 50 will produce very small
198 files of low image quality. Settings around 5 to 10 might be useful in
199 preparing an index of a large image library, for example. Try -qual‐
200 ity=2 (or so) for some amusing Cubist effects. (Note: quality values
201 below about 25 generate 2-byte quantization tables, which are consid‐
202 ered optional in the JFIF standard. pnmtojpeg emits a warning message
203 when you give such a quality value, because some other JFIF programs
204 may be unable to decode the resulting file. Use -baseline if you need
205 to ensure compatibility at low quality values.)
206 The -progressive option creates a "progressive JPEG" file. In this
208 type of JFIF file, the data is stored in multiple scans of increasing
209 quality. If the file is being transmitted over a slow communications
210 link, the decoder can use the first scan to display a low-quality image
211 very quickly, and can then improve the display with each subsequent
212 scan. The final image is exactly equivalent to a standard JFIF file of
213 the same quality setting, and the total file size is about the same --
214 often a little smaller.
215 Caution: progressive JPEG is not yet widely implemented, so many de‐
217 coders will be unable to view a progressive JPEG file at all.
218 If you're trying to control the quality/file size tradeoff, you might
220 consider the JPEG2000 format instead. See pamtojpeg2k(1).
221 Advanced options
224 -dct=int
225 Use integer DCT method (default).
226 -dct=fast
229 Use fast integer DCT (less accurate).
230 -dct=float
233 Use floating-point DCT method. The float method is very
234 slightly more accurate than the int method, but is much slower
235 unless your machine has very fast floating-point hardware. Also
236 note that results of the floating-point method may vary slightly
237 across machines, while the integer methods should give the same
238 results everywhere. The fast integer method is much less accu‐
239 rate than the other two.
240 -arithmetic
243 Use arithmetic coding. Default is Huffman encoding. Arithmetic
244 coding tends to get you a smaller result.
245 You may need patent licenses to use this option. According to
247 the JPEG FAQ ⟨http://www.faqs.org/faqs/jpeg-faq⟩ , This method
248 is covered by patents owned by IBM, AT&T, and Mitsubishi.
249 The author of the FAQ recommends against using arithmetic coding
251 (and therefore this option) because the space savings is not
252 great enough to justify the legal hassles.
253 Most JPEG libraries, including any distributed by the Indepen‐
255 dent JPEG Group since about 1998 are not capable of arithmetic
256 encoding. pnmtojpeg uses a JPEG library (either bound to it
257 when the pnmtojpeg executable was built or accessed on your sys‐
258 tem at run time) to do the JPEG encoding. If pnmtojpeg termi‐
259 nates with the message, "Sorry, there are legal restrictions on
260 arithmetic coding" or "Sorry, arithmetic coding not supported,"
261 this is the problem.
262 -restart=n
265 Emit a JPEG restart marker every n MCU rows, or every n MCU
266 blocks if you append B to the number. -restart 0 (the default)
267 means no restart markers.
268 -smooth=n
271 Smooth the input image to eliminate dithering noise. n, ranging
272 from 1 to 100, indicates the strength of smoothing. 0 (the de‐
273 fault) means no smoothing.
274 -maxmemory=n
277 Set a limit for amount of memory to use in processing large im‐
278 ages. Value is in thousands of bytes, or millions of bytes if
279 you append M to the number. For example, -max=4m selects
280 4,000,000 bytes. If pnmtojpeg needs more space, it will use
281 temporary files.
282 -verbose
285 Print to the Standard Error file messages about the conversion
286 process. This can be helpful in debugging problems.
287 The -restart option tells pnmtojpeg to insert extra markers that allow
290 a JPEG decoder to resynchronize after a transmission error. Without
291 restart markers, any damage to a compressed file will usually ruin the
292 image from the point of the error to the end of the image; with restart
293 markers, the damage is usually confined to the portion of the image up
294 to the next restart marker. Of course, the restart markers occupy ex‐
295 tra space. We recommend -restart=1 for images that will be transmitted
296 across unreliable networks such as Usenet.
297 The -smooth option filters the input to eliminate fine-scale noise.
299 This is often useful when converting dithered images to JFIF: a moder‐
300 ate smoothing factor of 10 to 50 gets rid of dithering patterns in the
301 input file, resulting in a smaller JFIF file and a better-looking im‐
302 age. Too large a smoothing factor will visibly blur the image, how‐
303 ever.
304 Wizard Options
307 -baseline
308 Force baseline-compatible quantization tables to be generated.
309 This clamps quantization values to 8 bits even at low quality
310 settings. (This switch is poorly named, since it does not en‐
311 sure that the output is actually baseline JPEG. For example,
312 you can use -baseline and -progressive together.)
313 -qtables=filespec
316 Use the quantization tables given in the specified text file.
317 -qslots=n[,...]
320 Select which quantization table to use for each color component.
321 -sample=HxV[,...]
324 Set JPEG sampling factors for each color component.
325 -scans=filespec
328 Use the scan script given in the specified text file. See below
329 for information on scan scripts.
330 -tracelevel=N
333 This sets the level of debug tracing the program outputs as it
334 runs. 0 means none, and is the default. This level primarily
335 controls tracing of the JPEG library, and you can get some
336 pretty interesting information about the compression process.
337 The "wizard" options are intended for experimentation with JPEG. If
341 you don't know what you are doing, don't use them. These switches are
342 documented further in the file wizard.doc that comes with the Indepen‐
343 dent JPEG Group's JPEG library.
344
347 This example compresses the PPM file foo.ppm with a quality factor of
348 60 and saves the output as foo.jpg:
349 pnmtojpeg -quality=60 foo.ppm > foo.jpg
351 Here's a more typical example. It converts from BMP to JFIF:
354 cat foo.bmp | bmptoppm | pnmtojpeg > foo.jpg
356
360 When you compress with JPEG, you lose information -- i.e. the resulting
361 image has somewhat lower quality than the original. This is a charac‐
362 teristic of JPEG itself, not any particular program. So if you do the
363 usual Netpbm thing and convert from JFIF to PNM, manipulate, then con‐
364 vert back to JFIF, you will lose quality. The more you do it, the more
365 you lose. Drawings (charts, cartoons, line drawings, and such with few
366 colors and sharp edges) suffer the most.
367 To avoid this, you can use a compressed image format other than JPEG.
369 PNG and JPEG2000 are good choices, and Netpbm contains converters for
370 those.
371 If you need to use JFIF on a drawing, you should experiment with pnmto‐
373 jpeg's -quality and -smooth options to get a satisfactory conversion.
374 -smooth 10 or so is often helpful.
375 Because of the loss, you should do all the manipulation you have to do
377 on the image in some other format and convert to JFIF as the last step.
378 And if you can keep a copy in the original format, so much the better.
379 The -optimize option to pnmtojpeg is worth using when you are making a
381 "final" version for posting or archiving. It's also a win when you are
382 using low quality settings to make very small JFIF files; the percent‐
383 age improvement is often a lot more than it is on larger files. (At
384 present, -optimize mode is automatically in effect when you generate a
385 progressive JPEG file).
386 You can do flipping and rotating transformations losslessly with the
388 program jpegtran, which is packaged with the Independent Jpeg Group's
389 JPEG library. jpegtran exercises its intimate knowledge of the way
390 JPEG works to do the transformation without ever actually decompressing
391 the image.
392
395 Another program, cjpeg, is similar. cjpeg is maintained by the Inde‐
396 pendent JPEG Group and packaged with the JPEG library which pnmtojpeg
397 uses for all its JPEG work. Because of that, you may expect it to ex‐
398 ploit more current JPEG features. Also, since you have to have the li‐
399 brary to run pnmtojpeg, but not vice versa, cjpeg may be more commonly
400 available.
401 On the other hand, cjpeg does not use the NetPBM libraries to process
403 its input, as all the NetPBM tools such as pnmtojpeg do. This means it
404 is less likely to be consistent with all the other programs that deal
405 with the NetPBM formats. Also, the command syntax of pnmtojpeg is con‐
406 sistent with that of the other Netpbm tools, unlike cjpeg.
407
410 Use the -scan option to specify a scan script. Or use the -progressive
411 option to specify a particular built-in scan script.
412 Just what a scan script is, and the basic format of the scan script
414 file, is covered in the wizard.doc file that comes with the Independent
415 JPEG Group's JPEG library. Scan scripts are same for pnmtojpeg as the
416 are for cjpeg.
417 This section contains additional information that isn't, but probably
419 should be, in that document.
420 First, there are many restrictions on what is a valid scan script. The
422 JPEG library, and thus pnmtojpeg, checks thoroughly for any lack of
423 compliance with these restrictions, but does little to tell you how the
424 script fails to comply. The messages are very general and sometimes
425 untrue.
426 To start with, the entries for the DC coefficient must come before any
428 entries for the AC coefficients. The DC coefficient is Coefficient 0;
429 all the other coefficients are AC coefficients. So in an entry for the
430 DC coefficient, the two numbers after the colon must be 0 and 0. In an
431 entry for AC coefficients, the first number after the colon must not be
432 0.
433 In a DC entry, the color components must be in increasing order. E.g.
435 "0,2,1" before the colon is wrong. So is "0,0,0".
436 In an entry for an AC coefficient, you must specify only one color com‐
438 ponent. I.e. there can be only one number before the colon.
439 In the first entry for a particular coefficient for a particular color
441 component, the "Ah" value must be zero, but the Al value can be any
442 valid bit number. In subsequent entries, Ah must be the Al value from
443 the previous entry (for that coefficient for that color component), and
444 the Al value must be one less than the Ah value.
445 The script must ultimately specify at least some of the DC coefficient
447 for every color component. Otherwise, you get the error message
448 "Script does not transmit all the data." You need not specify all of
449 the bits of the DC coefficient, or any of the AC coefficients.
450 There is a standard option in building the JPEG library to omit scan
452 script capability. If for some reason your library was built with this
453 option, you get the message "Requested feature was omitted at compile
454 time."
455
458 JPEGMEM
459 If this environment variable is set, its value is the default
460 memory limit. The value is specified as described for the
461 -maxmemory option. An explicit -maxmemory option overrides any
462 JPEGMEM.
463
468 jpegtopnm(1), pnm(1), cjpeg man page, djpeg man page, jpegtran man
469 page, rdjpgcom man page, wrjpgcom man page
470 Wallace, Gregory K. "The JPEG Still Picture Compression Standard",
472 Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.
473
477 pnmtojpeg and this manual were derived in large part from cjpeg, by the
478 Independent JPEG Group. The program is otherwise by Bryan Henderson on
479 March 07, 2000.
480
482 This manual page was generated by the Netpbm tool 'makeman' from HTML
483 source. The master documentation is at
484 http://netpbm.sourceforge.net/doc/pnmtojpeg.html
486netpbm documentation 23 April 2007 Pnmtojpeg User Manual(0)