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

NAME

6       pamtopng - convert a Netpbm image to PNG
7
8

SYNOPSIS

10       pamtopng     [-verbose]     [-transparent=color]    [-background=color]
11       [-gamma=value] [-chroma='wx wy
12         rx ry gx gy bx by'] [-srgbintent=intent] [-time=[yy]yy-mm-dd
13         hh:mm:ss] [-text=file] [-ztxt=file] [-itxt=file] [pnmfile]
14
15

OPTION USAGE

17       Minimum unique abbreviation of option is acceptable.  You may use  dou‐
18       ble  hyphens instead of a single hyphen to denote options.  You may use
19       white space in place of the equals sign to separate an option name from
20       its value.
21
22

DESCRIPTION

24       This program is part of Netpbm(1).
25
26       pamtopng reads a Netpbm image as input and produces a PNG image as out‐
27       put.
28
29       Color component values in PNG files are either 8 or 16  bits  wide,  so
30       where  necessary  pamtopng  scales  colors  to  have a maxval of 255 or
31       65535.  In that case, it will add an sBIT chunk to indicated the origi‐
32       nal bit-depth.
33
34       pamtopng works only on images with maxval 1, 3, 15, 255, or 65535.  You
35       can use pamdepth to convert an image with some other maxval to  one  of
36       these.
37
38       pamtopng produces a color PNG from a color PAM, even if the only colors
39       in the image are shades of gray.  To create a graycale PNG,  from  such
40       an  image  (which  might be slightly smaller), you can use other Netpbm
41       programs to convert the input to grayscale.
42
43
44   Alternative: pnmtopng
45       Netpbm contains another program for generating  PNG  images:  pnmtopng.
46       pnmtopng  is  a much older program - it is in fact the first program in
47       the world that could generate a PNG.  pnmtopng is a  complex,  feature-
48       laden  program.  It lets you control various arcane aspects of the con‐
49       version and create PNGs with various arcane features.  It does  various
50       transformations  on the image to create the greatest compression possi‐
51       ble, to a degree that probably doesn't make any difference in the  mod‐
52       ern world.
53
54       The  main  advantage  pamtopng has over pnmtopng is that the former can
55       use the transparency channel of a PAM  image  to  generate  the  trans‐
56       parency  information  in  the  PNG.  In contrast, handling of the alpha
57       channel is very cumbersome with pnmotpng.
58
59       One difference that does not exist, that some people might  incorrectly
60       infer  from the names is the possible input formats.  Both programs can
61       take PBM, PGM, PPM, and PAM input.
62
63       Because pnmtopng has been around virtually forever, programs and proce‐
64       dures  that use it are more portable than those that use pamtopng.  Its
65       age and popularity also probably make it have fewer bugs.
66
67       pamtopng does not have any way to do what the following do in pnmtopng:
68
69
70
71       ·      -palette
72
73       ·      -history
74
75       ·      -filter
76
77       ·      -size
78
79       ·      -paeth
80
81       ·      -hist
82
83       ·      -nofilter
84
85       ·      -sub
86
87       ·      -up
88
89       ·      -avg
90
91       ·      -force
92
93       ·      -libversion
94
95       ·      -compression
96
97       ·      -comp_xxx
98
99
100       These are some of the other functions of pnmtopng that pamtopng lacks:
101
102
103
104       ·      When you specify a transparent or background color that  is  not
105              in  the  image,  pnmtopng  can optionally choose the closest one
106              that is in the image.  pamtopng always uses the exact color  you
107              specify.
108
109
110       Features that exist in both programs are controlled by largely the same
111       command syntax.  But there are these differences:
112
113
114
115       ·      pnmtopng's -rgb option is -chroma in  pamtopng.   -chroma  is  a
116              better  name, and in fact was the name that pnmtopng used origi‐
117              nally, but we had to change it when we had to change the  syntax
118              of the option value to conform to the rest of Netpbm.
119
120
121       ·      pnmtopng's  -modtime option is -time in pamtopng.  The origin of
122              -modtime is analogous to that of -rgb.
123
124
125
126
127

OPTIONS

129       -transparent=color
130              pamtopng marks the specified color as  transparent  in  the  PNG
131              image.
132
133              Specify  the  color (color) as described for the argument of the
134              ppm_parsecolor() library routine ⟨libppm.html#colorname⟩ .  E.g.
135              red or rgb:ff/00/0d.
136
137
138       -background=color
139              This  causes  pamtopng to create a background color chunk in the
140              PNG output which can be used for subsequent transparency channel
141              or transparent color conversions.  Specify color the same as for
142              -transparent.
143
144
145       -gamma=value
146              This causes pnmtopng to create a gAMA chunk.   This  information
147              helps  describe  how  the color values in the PNG must be inter‐
148              preted.  Without the gAMA chunk,  whatever  interprets  the  PNG
149              must  get  this information separately (or just assume something
150              standard).  If your input is a true PPM or PGM image, you should
151              specify  -gamma=.45.  But sometimes people generate images which
152              are ostensibly PPM except  the  image  uses  a  different  gamma
153              transfer function than the one specified for PPM.  A common case
154              of this is when the image is created  by  simple  hardware  that
155              doesn't  have  digital computational ability.  Also, some simple
156              programs that generate images from scratch do it  with  a  gamma
157              transfer in which the gamma value is 1.0.
158
159
160       -chroma=chroma_list
161              This  option specifies how red, green, and blue component values
162              of a pixel specify a particular color, by telling the chromatic‐
163              ities  of  those  3  primary illuminants and of white (i.e. full
164              strength of all three).
165
166              The chroma_list value is a blank-separated list  of  8  floating
167              point  decimal numbers.  The CIE-1931 X and Y chromaticities (in
168              that order) of each of white, red,  green,  and  blue,  in  that
169              order.
170
171              This information goes into the PNG's cHRM chunk.
172
173              In  a  shell  command, make sure you use quotation marks so that
174              the blanks in chroma_list don't make the shell see multiple com‐
175              mand arguments.
176
177
178       -srgbintent=intent
179              This  asserts  that the input is a pseudo-Netpbm image that uses
180              an sRGB color space (unlike true Netpbm) and indicates  how  you
181              intend  for  the  colors  to be rendered.  It causes pamtopng to
182              include an sRGB chunk in  the  PNG  image  that  specifies  that
183              intent,  so  see  the  PNG documentation for more information on
184              what this really means.
185
186              intent is one of:
187
188
189
190       ·      perceptual
191
192       ·      relativecolorimetric
193
194       ·      saturation
195
196       ·      absolutecolorimetric
197
198
199
200       -text=filename
201              This option lets you include arbitrary text strings in  the  PNG
202              output, as tEXt chunks.
203
204              filename is the name of a file that contains your text strings.
205
206              The  output contains a distinct tEXt chunk for each entry in the
207              file.
208
209              Here is an example of a text string file:
210
211                   Title           PNG file
212                   Author          John Doe
213                   Description     how to include a text chunk
214                                      PNG file
215                   "Creation Date" 2015-may-11
216                   Software        pamtopng
217
218              The file is divided into entries, each entry comprising consecu‐
219              tive  lines  of  text.  The first line of an entry starts in the
220              first column (i.e. the first column  is  not  white  space)  and
221              every other line has white space in the first column.  The first
222              entry starts in the first line, so it is not valid for the first
223              line of the file to have white space in its first column.
224
225              The  first  word in an entry is the key of the text string (e.g.
226              'Title').  It begins in column one of the line and continues  up
227              to,  but not including, the first delimiter character or the end
228              of the line, whichever is first.  You can  enclose  the  key  in
229              double  quotes  in  which  case the key can consists of multiple
230              words.  The quotes are not part of the key.  The text string per
231              se  begins  after the key and any delimiter characters after it,
232              plus the text in subsequent continuation lines.
233
234              There is no limit on the length of a file line or entry  or  key
235              or text string.  There is no limit on the number of entries.
236
237
238       -ztxt=filename
239              The  same  as -text, except the text string is compressed in the
240              PNG output.  pnmtopng uses zTXt chunks instead of a tEXt chunks.
241
242
243       -itxt=filename
244              Similar to -text, but the text strings  can  be  in  a  language
245              other  than English.  The PNG image indicates what language that
246              is and includes the text string key both  in  English  and  that
247              language.  pnmtopng uses iTXt chunks instead of tEXt chunks.
248
249              For  each record, you must specify the language and give the key
250              both in English and in the text string language.
251
252              Example:
253
254                   Language        nl-NL  Taal             nl-NL
255                      Title           nl-NL  Titel            PNG file
256                      Author          nl-NL  Auteur           Pietje Puk
257                      Description     nl-NL  Omschrijving     Tekst in het Nederlands.
258
259              The language specification is based on the ISO  639-1  standard,
260              see http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for the
261              valid codes.  The format is either a two character  "nl"  or  an
262              extended code like "en-US".
263
264
265       -time='[yy]yy-mm-dd hh:mm:ss'
266              This option allows you to specify the modification time value to
267              be placed in the PNG output.  You can specify the year parameter
268              either as a two or four digit value.
269
270
271       -verbose
272              This  causes the program to display various facts about the con‐
273              version.
274
275
276
277
278

SEE ALSO

280       pngtopam(1), pnmtopng(1), pam(1), pnm(1)
281
282       For  information  on  the  PNG  format,  see  http://www.w3.org/TR/PNG/
283http://www.w3.org/TR/PNG/⟩         ,        http://libpng.org/pub/png/
284http://libpng.org/pub/png/⟩                                          ,
285       http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
286http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes⟩              and
287       http://schaik.com/png/http://schaik.com/png/⟩ .
288
289

HISTORY

291       pamtopng was new in Netpbm 10.70 (June 2015).
292
293       Before  pamtopng,  the  two  ways to create PNG images with Netpbm were
294       pnmtopng and pamrgbatopng.  The history  of  the  former  is  discussed
295       above.  The latter was added to Netpbm in 2005 as a cheap way to fill a
296       significant need that pnmtopng did not: the ability to turn  the  alpha
297       channel in a PAM image into the alpha channel in a PNG image.
298
299       Handling  of the alpha channel with pnmtopng is very cumbersome (as was
300       dealing with alpha channels in general before the introduction  of  the
301       PAM  format).   pamrgbatopng could do what people wanted with the alpha
302       channel, but nothing else.  It was a very small program with  literally
303       no command line options.
304
305       The  goal in those days was eventually to expand pnmtopng to do the PAM
306       alpha channel thing, rename it to pamtopng,  and  retire  pamrgbatopng.
307       But  pnmtopng  is such a complex program, because of its dizzying array
308       of features and its need for backward compatibility, that  adding  that
309       one  capability  to  it  was  a  daunting task and for ten years nobody
310       attempted it.
311
312       In 2015, one of the authors of the original pnmtopng  (from  before  it
313       was  even  part of Netpbm -- a program that shared essentially no lines
314       of code with pnmtopng of 2015) decided to go in a different  direction.
315       While  many  features  of  pnmtopng  were  pretty important and easy to
316       implement, many others were probably of no use in the modern  world  or
317       at  least  not  important enough to justify the complexity they lent to
318       the code.  (The features thought to be outdated  were  ones  that  were
319       intended  to make the PNG output slightly smaller - something consider‐
320       ably less important with the declining cost of computer resources).
321
322       And there was an opportunity to drop those features: We could  use  the
323       new  name 'pamtopng' for a new program, keep the existing program under
324       the name 'pnmtopng', and avoid most backward compatibility trouble.
325
326       Therefore, Willem van Schaik wrote an intermediate level  program  that
327       had all the most important features of pnmtopng, plus the alpha channel
328       handling of pamrgbatopng, with nice, simple code.  That was pamtopng.
329
330       Because pamrgbatopng had no options, pamtopng was  backward  compatible
331       with  it  without even trying.  Therefore, as soon as we added pamtopng
332       to Netpbm, we removed pamrgbatopng and recommended that pamrgbatopng be
333       installed as an alias for pamtopng.
334
335
336

AUTHOR

338       Copyright  (C)  1995-1997  by  Alexander Lehmann and Willem van Schaik.
339       Copyright (C) 2015 by Willem van Schaik.
340

DOCUMENT SOURCE

342       This manual page was generated by the Netpbm tool 'makeman'  from  HTML
343       source.  The master documentation is at
344
345              http://netpbm.sourceforge.net/doc/pamtopng.html
346
347netpbm documentation             12 March 2017         Pamtopng User Manual(0)
Impressum