1Pnmtojpeg User Manual(0)                              Pnmtojpeg User Manual(0)
2
3
4

NAME

6       pnmtojpeg - convert PNM image to a JFIF ("JPEG") image
7
8

SYNOPSIS

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
17       filename
18
19       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
24
25

DESCRIPTION

27       This program is part of Netpbm(1).
28
29       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
32       pnmtojpeg uses the Independent JPEG Group's JPEG library to create  the
33       output  file.  See http://www.ijg.orghttp://www.ijg.orgfor infor‐
34       mation on the library.
35
36       "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
41       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
45

OPTIONS

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
52
53   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
62              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
75              The  contents  of  the  EXIF file after the length field are the
76              exact byte for byte contents of the APP1  marker,  not  counting
77              the length field, that constitutes the EXIF header.
78
79
80       -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
86
87       -grayscale
88
89       -greyscale
90
91       -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
97              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
101              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
108              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
110              experiment  pnmtojpeg took 16% more CPU time to convert it.  The
111              extra CPU time probably indicates that  processing  of  all  the
112              extra  compressed  data  consumed  all the CPU time saved by not
113              having to convert the RGB inputs to YCbCr.
114
115              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
119              The -rgb option was added in Netpbm 10.11 in October 2002.
120
121
122       -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
128              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
141              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
153              The default is 1x1 in unspecified units.
154
155              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
157              unspecified units.
158
159
160       -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
167
168       -progressive
169              Create a progressive JPEG file (see below).
170
171       -comment=text
172              Include a comment marker in the JFIF output, with  comment  text
173              text.
174
175              Without this option, there are no comment markers in the output.
176
177
178
179       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
190       -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
197       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
207       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
216       Caution: progressive JPEG  is  not  yet  widely  implemented,  so  many
217       decoders will be unable to view a progressive JPEG file at all.
218
219       If  you're  trying to control the quality/file size tradeoff, you might
220       consider the JPEG2000 format instead.  See pamtojpeg2k(1).
221
222
223   Advanced options
224       -dct=int
225              Use integer DCT method (default).
226
227
228       -dct=fast
229              Use fast integer DCT (less accurate).
230
231
232       -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
241
242       -arithmetic
243              Use arithmetic coding.  Default is Huffman encoding.  Arithmetic
244              coding tends to get you a smaller result.
245
246              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
250              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
254              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
263
264       -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
269
270       -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
273              default) means no smoothing.
274
275
276       -maxmemory=n
277              Set a limit for amount of memory  to  use  in  processing  large
278              images.  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
283
284       -verbose
285              Print to the Standard Error file messages about  the  conversion
286              process.  This can be helpful in debugging problems.
287
288
289       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
295       extra space.  We recommend -restart=1 for images that will be transmit‐
296       ted across unreliable networks such as Usenet.
297
298       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
302       image.  Too large a smoothing factor will visibly blur the image,  how‐
303       ever.
304
305
306   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
311              ensure that the output is actually baseline JPEG.  For  example,
312              you can use -baseline and -progressive together.)
313
314
315       -qtables=filespec
316              Use the quantization tables given in the specified text file.
317
318
319       -qslots=n[,...]
320              Select which quantization table to use for each color component.
321
322
323       -sample=HxV[,...]
324              Set JPEG sampling factors for each color component.
325
326
327       -scans=filespec
328              Use the scan script given in the specified text file.  See below
329              for information on scan scripts.
330
331
332       -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
338
339
340       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
345

EXAMPLES

347       This example compresses the PPM file foo.ppm with a quality  factor  of
348       60 and saves the output as foo.jpg:
349
350           pnmtojpeg -quality=60 foo.ppm > foo.jpg
351
352       Here's a more typical example.  It converts from BMP to JFIF:
353
354           cat foo.bmp | bmptoppm | pnmtojpeg > foo.jpg
355
356

JPEG LOSS

358       When you compress with JPEG, you lose information -- i.e. the resulting
359       image has somewhat lower quality than the original.  This is a  charac‐
360       teristic  of JPEG itself, not any particular program.  So if you do the
361       usual Netpbm thing and convert from JFIF to PNM, manipulate, then  con‐
362       vert back to JFIF, you will lose quality.  The more you do it, the more
363       you lose.  Drawings (charts, cartoons, line drawings, and such with few
364       colors and sharp edges) suffer the most.
365
366       To  avoid  this, you can use a compressed image format other than JPEG.
367       PNG and JPEG2000 are good choices, and Netpbm contains  converters  for
368       those.
369
370       If you need to use JFIF on a drawing, you should experiment with pnmto‐
371       jpeg's -quality and -smooth options to get a  satisfactory  conversion.
372       -smooth 10 or so is often helpful.
373
374       Because  of the loss, you should do all the manipulation you have to do
375       on the image in some other format and convert to JFIF as the last step.
376       And if you can keep a copy in the original format, so much the better.
377
378       The  -optimize option to pnmtojpeg is worth using when you are making a
379       "final" version for posting or archiving.  It's also a win when you are
380       using  low quality settings to make very small JFIF files; the percent‐
381       age improvement is often a lot more than it is on  larger  files.   (At
382       present,  -optimize mode is automatically in effect when you generate a
383       progressive JPEG file).
384
385       You can do flipping and rotating transformations  losslessly  with  the
386       program  jpegtran,  which is packaged with the Independent Jpeg Group's
387       JPEG library.  jpegtran exercises its intimate  knowledge  of  the  way
388       JPEG works to do the transformation without ever actually decompressing
389       the image.
390
391

OTHER PROGRAMS

393       Another program, cjpeg, is similar.  cjpeg is maintained by  the  Inde‐
394       pendent  JPEG  Group and packaged with the JPEG library which pnmtojpeg
395       uses for all its JPEG work.  Because of that,  you  may  expect  it  to
396       exploit  more  current JPEG features.  Also, since you have to have the
397       library to run pnmtojpeg, but not vice versa, cjpeg may  be  more  com‐
398       monly available.
399
400       On  the  other hand, cjpeg does not use the NetPBM libraries to process
401       its input, as all the NetPBM tools such as pnmtojpeg do.  This means it
402       is  less  likely to be consistent with all the other programs that deal
403       with the NetPBM formats.  Also, the command syntax of pnmtojpeg is con‐
404       sistent with that of the other Netpbm tools, unlike cjpeg.
405
406

SCAN SCRIPTS

408       Use the -scan option to specify a scan script.  Or use the -progressive
409       option to specify a particular built-in scan script.
410
411       Just what a scan script is, and the basic format  of  the  scan  script
412       file, is covered in the wizard.doc file that comes with the Independent
413       JPEG Group's JPEG library.  Scan scripts are same for pnmtojpeg as  the
414       are for cjpeg.
415
416       This  section  contains additional information that isn't, but probably
417       should be, in that document.
418
419       First, there are many restrictions on what is a valid scan script.  The
420       JPEG  library,  and  thus  pnmtojpeg, checks thoroughly for any lack of
421       compliance with these restrictions, but does little to tell you how the
422       script  fails  to  comply.  The messages are very general and sometimes
423       untrue.
424
425       To start with, the entries for the DC coefficient must come before  any
426       entries  for the AC coefficients.  The DC coefficient is Coefficient 0;
427       all the other coefficients are AC coefficients.  So in an entry for the
428       DC coefficient, the two numbers after the colon must be 0 and 0.  In an
429       entry for AC coefficients, the first number after the colon must not be
430       0.
431
432       In  a DC entry, the color components must be in increasing order.  E.g.
433       "0,2,1" before the colon is wrong.  So is "0,0,0".
434
435       In an entry for an AC coefficient, you must specify only one color com‐
436       ponent.  I.e. there can be only one number before the colon.
437
438       In  the first entry for a particular coefficient for a particular color
439       component, the "Ah" value must be zero, but the Al  value  can  be  any
440       valid  bit number.  In subsequent entries, Ah must be the Al value from
441       the previous entry (for that coefficient for that color component), and
442       the Al value must be one less than the Ah value.
443
444       The  script must ultimately specify at least some of the DC coefficient
445       for every color  component.   Otherwise,  you  get  the  error  message
446       "Script  does  not transmit all the data."  You need not specify all of
447       the bits of the DC coefficient, or any of the AC coefficients.
448
449       There is a standard option in building the JPEG library  to  omit  scan
450       script capability.  If for some reason your library was built with this
451       option, you get the message "Requested feature was omitted  at  compile
452       time."
453
454

ENVIRONMENT

456       JPEGMEM
457              If  this  environment  variable is set, its value is the default
458              memory limit.  The value  is  specified  as  described  for  the
459              -maxmemory option.  An explicit -maxmemory  option overrides any
460              JPEGMEM.
461
462
463
464

SEE ALSO

466       jpegtopnm(1), pnm(1), cjpeg man page,  djpeg  man  page,  jpegtran  man
467       page, rdjpgcom man page, wrjpgcom man page
468
469       Wallace,  Gregory  K.   "The  JPEG Still Picture Compression Standard",
470       Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44.
471
472
473

AUTHOR

475       pnmtojpeg and this manual were derived in large part from cjpeg, by the
476       Independent JPEG Group.  The program is otherwise by Bryan Henderson on
477       March 07, 2000.
478

DOCUMENT SOURCE

480       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
481       source.  The master documentation is at
482
483              http://netpbm.sourceforge.net/doc/pnmtojpeg.html
484
485netpbm documentation             23 April 2007        Pnmtojpeg User Manual(0)
Impressum