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

NAME

6       pnmtopng - convert a PNM image to PNG
7
8

SYNOPSIS

10       pnmtopng [-verbose] [-downscale] [-interlace] [-alpha=file] [-transpar‐
11       ent=[=]color] [-background=color] [-palette=palettefile] [-gamma=value]
12       [-hist] [-text=file] [-ztxt=file] [-rgb='wx wy
13         rx  ry  gx  gy bx by'] [-size='x y unit'] [-srgbintent=intent] [-mod‐
14       time='[yy]yy-mm-dd
15         hh:mm:ss'] [-nofilter] [-sub] [-up] [-avg] [-paeth]  [-compression=n]
16       [-comp_mem_level=n]            [-comp_strategy={huffman_only|filtered}]
17       [-comp_method=deflated]   [-comp_window_bits=n]   [-comp_buffer_size=n]
18       [-force] [-libversion] [pnmfile]
19
20
21

OPTION USAGE

23       Obsolete options:
24
25       [-filter n]
26
27       Options available only in older versions:
28
29       [-chroma wx wy rx ry gx gy bx by] [-phys x y unit] [-time [yy]yy-mm-dd
30         hh:mm:ss]
31
32       Minimum  unique abbreviation of option is acceptable.  You may use dou‐
33       ble hyphens instead of single hyphen to denote options.   You  may  use
34       white space in place of the equals sign to separate an option name from
35       its value.
36
37

DESCRIPTION

39       This program is part of Netpbm(1).
40
41       pnmtopng reads a PNM image as input and produces a PNG image as output.
42
43       Color component values in PNG files are either eight  or  sixteen  bits
44       wide,  so  pnmtopng will automatically scale colors to have a maxval of
45       255 or 65535.
46
47       For a grayscale image, pnmtopng produces a PNG bit depth 1, 2, 4, 8  or
48       16.   When the input image has a small maxval, the output PNG image has
49       a correspondingly small bit depth.  But in mapping the  PNM  maxval  to
50       the  PNG  maxval  (which is by definition the maximum value that can be
51       represented in the number of bits), a fair amount of distortion happens
52       with  these low maxvals.  For example, with a PNM maxval of 5 and a PNG
53       maxval of 7, the input sample 2 becomes the output sample 3.  The input
54       brightness  is  2/5  =  .40,  while the output brightness is 3/7 = .43.
55       Note that this is not a problem if you view the maxval as a  precision,
56       because  in  .4  and  .43 are identical within the precision implied by
57       maxval 5.  Indeed, if you convert this PNG back to a maxval 5 PGM,  the
58       pixel's  value  will  again be 2, exactly as it was originally.  But if
59       you need precisely the same colors in the output PNG as  in  the  input
60       PNM,  make  sure  your  input  PNM has a maxval which is a power of two
61       minus one.  If you can't do that, then  convert  it  with  pamdepth  to
62       something with a large maxval that is a power of two minus one (255 and
63       65535 are good choices) to minimize the error.
64
65
66

OPTIONS

68   Note: Option Syntax of Older Versions
69       pnmtopng changed in Netpbm 10.30 (October 2005)  to  use  the  standard
70       Netpbm  command  line  syntax.   Before  that, you could not use double
71       hyphens to denote an option and could not use an equal sign to separate
72       an  option name from its value.  And the options had to come before the
73       non-option program arguments.
74
75       Furthermore, the options -chroma, -phys, and  -time  were  replaced  by
76       -rgb,  -size,  and -modtime, respectively.  The only difference, taking
77       -phys/-size as an example, is that -phys takes multiple  program  argu‐
78       ments  as  the  option  argument,  whereas -size takes a single program
79       argument which is composed of multiple words.  E.g.  The old shell com‐
80       mand
81
82          pnmtopng -phys 800 800 0 input.pnm > output.png
83
84       is equivalent to the new shell command
85
86          pnmtopng -size "800 800 0" input.pnm > output.png
87
88       If  you're writing a program that needs to work with both new and old ,
89       have it first try with the new syntax, and if it fails  with  "unrecog‐
90       nized option," fall back to the old syntax.
91
92
93   Current Options
94       In  addition  to  the options common to all programs based on libnetpbm
95       (most notably -quiet, see
96        Common Options ⟨index.html#commonoptions⟩ ), pnmtopng  recognizes  the
97       following command line options:
98
99
100
101       -verbose
102              This  causes pnmtopng to display information about the format of
103              the output file.
104
105
106       -downscale
107              This enables pnmtopng to scale maxvalues of more then  65535  to
108              16  bits. Since this means loss of image data, pnmtopng does not
109              do it by default.
110
111
112       -interlace
113              This causes the PNG file to be interlaced, in Adam7 format.  The
114              interlaced  format is one in which the raster data starts with a
115              low-resolution representation of the entire image, then  contin‐
116              ues  with additional information for the entire image, then even
117              more information, etc.  In Adam7 in particular, there are  seven
118              such  passes  of  the  whole image.  This is useful when you are
119              receiving the image over a slow communication line as someone is
120              waiting  to  see  it.   The simplest thing to do in that case is
121              wait for  the  entire  image  to  arrive  and  then  display  it
122              instantly,  but then the user is wasting time staring at a blank
123              space until the whole image arrives.   With  the  standard  non-
124              interlaced  format,  the data arrives row-by-row starting at the
125              top, so the displayer could display each row of the image as  it
126              arrives  and  gradually  paint  down to the bottom.  But with an
127              interlaced image, the displayer can start by showing a low-reso‐
128              lution  version of the image, then gradually improve the display
129              as more data arrives.
130
131
132
133       -alpha=filename
134              This specifies the transparency (alpha) channel  of  the  image.
135              You  supply  the  transparency  channel as a standard PGM trans‐
136              parency mask (see the PGM(1) specification.  pnmtopng  does  not
137              necessarily  represents the transparency information as a trans‐
138              parency channel in the PNG format.   If  it  can  represent  the
139              transparency  information  through  a  palette, it will do so in
140              order to make a smaller PNG file.  pnmtopng even sorts the  pal‐
141              ette so it can omit the opaque colors from the transparency part
142              of the palette and save space for the palette.
143
144
145       -transparent=color
146              pnmtopng marks the specified color as  transparent  in  the  PNG
147              image.
148
149              Specify  the  color (color) as described for the argument of the
150              pnm_parsecolor()                 library                 routine
151              ⟨libnetpbm_image.html#colorname⟩  .   E.g.  red or rgb:ff/00/0d.
152              If the color you specify is not present in the  image,  pnmtopng
153              selects  instead  the  color in the image that is closest to the
154              one you specify.  Closeness is measured as a Cartesian  distance
155              between  colors  in  RGB space.  If multiple colors are equidis‐
156              tant, pnmtopng chooses one of them arbitrarily.
157
158              However, if you prefix your color specification with "=", e.g.
159
160                                  -transparent =red
161
162               only the exact color you specify will be transparent.  If  that
163              color  does  not  appear  in  the image, there will be no trans‐
164              parency.  pnmtopng issues an information message  when  this  is
165              the case.
166
167
168       -background=color
169              Causes  pnmtopng  to  create a background color chunk in the PNG
170              output which can be used for subsequent transparency channel  or
171              transparent  color  conversions.   Specify color the same as for
172              -transparent.
173
174
175       -palette=palettefile
176              This option specifies a palette to use in the  PNG.   It  forces
177              pnmtopng  to create the paletted (colormapped) variety of PNG --
178              if that isn't possible, pnmtopng  fails.   If  the  palette  you
179              specify  doesn't  contain  exactly the colors in the image, pnm‐
180              topng fails.   Since  pnmtopng  will  automatically  generate  a
181              paletted PNG, with a correct palette, when appropriate, the only
182              reason you would specify the -palette option is if you  care  in
183              what  order  the  colors appear in the palette.  The PNG palette
184              has colors in the same order as the palette you specify.
185
186              You specify the palette by naming a PPM file that has one  pixel
187              for each color in the palette.
188
189              Alternatively,  consider  the  case  that have a palette and you
190              want to make sure your PNG contains only colors  from  the  pal‐
191              ette,  approximating  if necessary.  You don't care what indexes
192              the PNG uses internally for the colors (i.e. the  order  of  the
193              PNG  palette).  In this case, you don't need -palette.  Pass the
194              Netpbm input  image  and  your  palette  PPM  through  pnmremap.
195              Though  you  might  think  it would, using -palette in this case
196              wouldn't even save pnmtopng any work.
197
198
199       -gamma=value
200              Causes pnmtopng to create a gAMA chunk.  This information  helps
201              describe  how  the  color values in the PNG must be interpreted.
202              Without the gAMA chunk, whatever interprets  the  PNG  must  get
203              this information separately (or just assume something standard).
204              If your input is a true PPM or PGM  image,  you  should  specify
205              -gamma=.52.   But  sometimes  people  generate  images which are
206              ostensibly PPM except the image uses a different gamma  transfer
207              function  than the one specified for PPM.  A common case of this
208              is when the image is created by  simple  hardware  that  doesn't
209              have  digital computational ability.  Also, some simple programs
210              that generate images from scratch do it with a gamma transfer in
211              which the gamma value is 1.0.
212
213
214       -hist  Use  this  parameter  to  create a chunk that specifies the fre‐
215              quency (or histogram) of the colors in the image.
216
217
218       -text=filename
219              This option lets you include arbitrary text strings in  the  PNG
220              output, as tEXt chunks.
221
222              filename is the name of a file that contains your text strings.
223
224              The  output contains a distinct tEXt chunk for each entry in the
225              file.
226
227              Here is an example of a text string file:
228
229                   Title           PNG file
230                   Author          John Doe
231                   Description     how to include a text chunk
232                                      PNG file
233                   "Creation Date" 2015-may-11
234                   Software        pamtopng
235
236              The file is divided into entries, each entry comprising consecu‐
237              tive  lines  of  text.  The first line of an entry starts in the
238              first column (i.e. the first column  is  not  white  space)  and
239              every other line has white space in the first column.  The first
240              entry starts in the first line, so it is not valid for the first
241              line of the file to have white space in its first column.
242
243              The  first  word in an entry is the key of the text string (e.g.
244              'Title').  It begins in column one of the line and continues  up
245              to,  but not including, the first delimiter character or the end
246              of the line, whichever is first.  You can  enclose  the  key  in
247              double  quotes  in  which  case the key can consists of multiple
248              words.  The quotes are not part of the key.  The text string per
249              se  begins  after the key and any delimiter characters after it,
250              plus the text in subsequent continuation lines.
251
252              There is no limit on the length of a file line or entry  or  key
253              or text string.  There is no limit on the number of entries.
254
255
256       -ztxt=filename
257              The  same  as -text, except the text string is compressed in the
258              PNG output.  pnmtopng uses zTXt chunks instead of a tEXt chunks,
259              unless the key for the text string starts with 'A' or 'T'.  This
260              odd exception exists for backward compatibility; we  don't  know
261              why  the  program  was originally designed this way, except that
262              the distinction was meant to roughly identify the keys  'Author'
263              and 'Title'.
264
265
266       -rgb=chroma_list
267              This  option specifies how red, green, and blue component values
268              of a pixel specify a particular color, by telling the chromatic‐
269              ities  of  those  3  primary illuminants and of white (i.e. full
270              strength of all three).
271
272              The chroma_list value is a blank-separated list  of  8  floating
273              point  decimal numbers.  The CIE-1931 X and Y chromaticities (in
274              that order) of each of white, red,  green,  and  blue,  in  that
275              order.
276
277              This information goes into the PNG's cHRM chunk.
278
279              In  a  shell  command, make sure you use quotation marks so that
280              the blanks in chroma_list don't make the shell see multiple com‐
281              mand arguments.
282
283              This  option  was  new  in  Netpbm 10.30 (October 2005).  Before
284              that, the option -chroma does the same thing, but with  slightly
285              different syntax.
286
287
288       -size="x y unit"
289              This option determines the aspect ratio of the individual pixels
290              of your image as well as the physical resolution of it.
291
292              unit is either 0 or 1.  When it is 1, the option  specifies  the
293              physical resolution of the image in pixels per meter.  For exam‐
294              ple, -size="10000 15000 1" means that when someone displays  the
295              image,  he  should  make  it  so that 10,000 pixels horizontally
296              occupy 1 meter and 15,000 pixels vertically  occupy  one  meter.
297              And  even  if he doesn't take this advice on the overall size of
298              the displayed image, he should at least make  it  so  that  each
299              pixel displays as 1.5 times as high as wide.
300
301              When  unit  is  0, that means there is no advice on the absolute
302              physical resolution; just on the ratio of horizontal to vertical
303              physical resolution.
304
305              This information goes into the PNG's pHYS chunk.
306
307              When you don't specify -size, pnmtopng creates the image with no
308              pHYS chunk, which means square pixels of no absolute resolution.
309
310              This option was new in  Netpbm  10.30  (October  2005).   Before
311              that,  the  option  -phys does the same thing, but with slightly
312              different syntax.
313
314
315       -srgbintent=intent
316              This asserts that the input is a pseudo-Netpbm image  that  uses
317              an  sRGB  color space (unlike true Netpbm) and indicates how you
318              intend for the colors to be rendered.   It  causes  pnmtopng  to
319              include  an  sRGB  chunk  in  the  PNG image that specifies that
320              intent, so see the PNG documentation  for  more  information  on
321              what this really means.
322
323              intent is one of:
324
325
326
327       ·      perceptual
328
329       ·      relativecolorimetric
330
331       ·      saturation
332
333       ·      absolutecolorimetric
334
335
336              This  option  was new in Netpbm 10.71 (June 2015).  Before that,
337              pnmtopng never generates an sRGB chunk.
338
339
340       -modtime="[yy]yy-mm-dd hh:mm:ss"
341              This option allows you to specify the modification time value to
342              be placed in the PNG output.  You can specify the year parameter
343              either as a two digit or four digit value.
344
345              This option was new in  Netpbm  10.30  (October  2005).   Before
346              that,  the  option  -time does the same thing, but with slightly
347              different syntax.
348
349
350       -filter=n
351              This option is obsolete.  Before Netpbm 10.22 (April 2004), this
352              was the only way to specify a row filter.  It specifies a single
353              type of row filter, by number, that pnmtopng must  use  on  each
354              row.
355
356              Use -nofilter, -sub, -up, -avg, and -paeth in current Netpbm.
357
358
359       -nofilter
360
361       -sub
362
363       -up
364
365       -avg
366
367       -paeth Each  of  these  options permits pnmtopng to use one type of row
368              filter.  pnmtopng chooses whichever of the permitted filters  it
369              finds  to  be optimal.  If you specify none of these options, it
370              is the same as specifying all of them -- pnmtopng uses  any  row
371              filter type it finds optimal.
372
373              These  options  were new with Netpbm 10.22 (April 2004).  Before
374              that, you could use the -filter option to specify one  permitted
375              row  filter  type.   The  default,  when  you  specify no filter
376              options, was the same.
377
378
379       -compression=n
380              This option sets set the compression level of the zlib  compres‐
381              sion.   Select a level from 0 for no compression (maximum speed)
382              to 9 for maximum compression (minimum speed).
383
384              The default is the default of the zlib library.
385
386
387       -comp_mem_level=n
388              This option sets the memory usage level of the zlib compression.
389              Select  a  level  from  1  for minimum memory usage (and minimum
390              speed) to 9 for maximum memory usage (and speed).
391
392              The default is the default of the zlib library.
393
394              This option was new in Netpbm 10.30 (October 2005).
395
396
397       -comp_strategy={huffman_only|filtered}
398              This options sets the compression strategy of the zlib  compres‐
399              sion.   See  Zlib  documentation  for  information on what these
400              strategies are.
401
402              The default is the default of the zlib library.
403
404              This option was new in Netpbm 10.30 (October 2005).
405
406
407       -comp_method=deflated
408              This option does nothing.  It is here for mathematical complete‐
409              ness  and  for possible forward compatibility.  It theoretically
410              selects the compression method of the zlib compression, but  the
411              Z  library  knows  only  one method today, so there's nothing to
412              choose.
413
414              The default is the default of the zlib library.
415
416              This option was new in Netpbm 10.30 (October 2005).
417
418
419       -comp_window_bits=N
420              This option tells how big a window the  zlib  compression  algo‐
421              rithm  uses.   The  value  is the base 2 logarithm of the window
422              size in bytes, so 8 means 256 bytes.  The value must be  from  8
423              to 15 (i.e. 256 bytes to 32K).
424
425              See Zlib documentation for details on what this window size is.
426
427              The default is the default of the zlib library.
428
429              This option was new in Netpbm 10.30 (October 2005).
430
431
432       -comp_buffer_size=N
433              This  option  determines  in  what size pieces pnmtopng does the
434              zlib compression.  One compressed piece goes in each IDAT  chunk
435              in  the  PNG.   So  the bigger this value, the fewer IDAT chunks
436              your PNG will have.  Theoretically, this makes the  PNG  smaller
437              because  1)  you  have  less per-IDAT-chunk overhead, and 2) the
438              compression algorithm has more data to work with.  But in  real‐
439              ity,  the difference will probably not be noticeable above about
440              8K, which is the default.
441
442              The value n is the size of the compressed piece (i.e.  the  com‐
443              pression buffer) in bytes.
444
445              This option was new in Netpbm 10.30 (October 2005).
446
447
448
449       -force When  you  specify this, pnmtopng limits its optimizations.  The
450              resulting PNG output is as similar to the Netpbm input as possi‐
451              ble.   For  example, the PNG output will not be paletted and the
452              transparency channel will be represented as a full  transparency
453              channel  even  if the information could be represented more suc‐
454              cinctly with a transparency chunk.
455
456
457       -libversion
458              This option causes pnmtopng to display version information about
459              itself  and the libraries it uses, in addition to all its normal
460              function.  Do not confuse this with  the  Netpbm  common  option
461              -version,  which  causes the program to display version informa‐
462              tion about the Netpbm library and do nothing else.
463
464              You can't really use this option in a program that invokes  pnm‐
465              topng  and  needs to know which version it is.  Its function has
466              changed too much over the history of pnmtopng.   The  option  is
467              good only for human eyes.
468
469
470
471

SEE ALSO

473       pngtopam(1), pamtopng(1), pnmremap(1), pnmgamma(1), pnm(1)
474
475       For   information   on   the   PNG  format,  see  http://schaik.com/png
476http://schaik.com/png⟩ .
477
478

AUTHOR

480       Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
481

DOCUMENT SOURCE

483       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
484       source.  The master documentation is at
485
486              http://netpbm.sourceforge.net/doc/pnmtopng.html
487
488netpbm documentation             13 March 2019         Pnmtopng User Manual(0)
Impressum