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

NAME

6       pngtopam - convert a PNG image into a Netpbm image
7
8

SYNOPSIS

10       pngtopam  [-verbose]  [-alphapam  |  -alpha | -mix] [-background=color]
11       [-gamma=value] [-text=filename] [-time] [-byrow] [pngfile]
12
13       Minimum unique abbreviation of option is acceptable.  You may use  dou‐
14       ble  hyphens  instead  of single hyphen to denote options.  You may use
15       white space in place of the equals sign to separate an option name from
16       its value.
17
18

DESCRIPTION

20       This program is part of Netpbm(1).
21
22       pngtopam  reads  a  PNG  image (Portable Network Graphics) as input and
23       produces a Netpbm image as output.  The type of the output file depends
24       on the input file - if it's black & white, pngtopam creates a PBM file.
25       If it's grayscale, pngtopam creates a PGM file.  Otherwise, it  creates
26       a PPM file.  Except that with the -alphapam option, it always creates a
27       PAM file.  That  file  has  tuple  type  GRAYSCALE_ALPHA  or  RGB_ALPHA
28       depending on whether the input has color or not.
29
30       To  convert in the other direction, use pamtopng or pnmtopng.  The for‐
31       mer is the more modern of the two and can recognize transparency infor‐
32       mation  in  a  PAM file, as you might generate with pngtopam -alphapam.
33       It has existed only since June 2015.  The latter has more features, but
34       probably not ones that matter in the modern world.
35
36
37

OPTIONS

39       -verbose
40              Display  various  information  about the input PNG image and the
41              conversion process.
42
43              If you want even more  information  about  the  PNG  image,  use
44              pngcheck (not part of Netpbm).
45
46
47       -alphapam
48              Produce  a  single output image containing the main image (fore‐
49              ground) and the transparency channel or transparency mask.  This
50              image   is   in  the  PAM  format  with  tuple  type  of  either
51              GRAYSCALE_ALPHA (which has a depth of 2 channels)  or  RGB_ALPHA
52              (which has a depth of 4 channels).
53
54              You  can  specify only one of -alphapam, -alpha, and -mix.  With
55              none of them, pngtopam produces an image of  the  foreground  of
56              the input image and discards transparency information.
57
58              This option was new in Netpbm 10.44 (September 2008).
59
60
61       -alpha Output  the  transparency  channel  or  transparency mask of the
62              image. The result is either a PBM file or a PGM file,  depending
63              on whether different levels of transparency appear.
64
65              pngtopam discards the main image (the foreground).
66
67              You  can  specify only one of -alphapam, -alpha, and -mix.  With
68              none of them, pngtopam produces an image of  the  foreground  of
69              the input image and discards transparency information.
70
71
72       -mix   Compose  the  image  with  the transparency or transparency mask
73              against a background.  The background color is determined by the
74              bKGD  chunk  in  the  PNG,  except that you can override it with
75              -background.  If the PNG has no bKGD chunk and you don't specify
76              -background, the background color is white.
77
78              You  can  specify only one of -alphapam, -alpha, and -mix.  With
79              none of them, pngtopam produces an image of  the  foreground  of
80              the input image and discards transparency information.
81
82
83       -background=color
84              This option specifies the background color with which to mix the
85              image when you specify -mix.
86
87              color is as described for the argument of  the  ppm_parsecolor()
88              library routine ⟨libppm.html#colorname⟩ .
89
90              Examples:
91
92
93
94       ·      -background=rgb:01/ff/80
95
96       ·      -background=rgbi:1/255/128
97
98
99              If  you  don't specify -background, the background color is what
100              is specified in the PNG image, and if the  PNG  doesn't  specify
101              anything, white.
102
103              You  cannot  specify  -background  unless you also specify -mix.
104              Before Netpbm 10.27 (March 2005), you could specify  -background
105              without  -mix and it was just ignored.  (This caused a usability
106              problem).
107
108
109
110       -gamma=value
111              This option causes pngtopam to respect the image gamma  informa‐
112              tion in the PNG file (from the gAMA chunk).  Probably by histor‐
113              ical accident, pngtopam ignores  that  information  by  default,
114              assuming  the  image  uses  the  same  gamma transformation as a
115              Netpbm image, so the output image has different colors than  the
116              PNG  file  actually  represents  if  the PNG doesn't actually do
117              that.  (However, it is rare for a PNG file to use a gamma trans‐
118              formation  different from what the Netpbm formats specify, or if
119              it does, to specify with a gAMA chuck what that is).
120
121              But when you do specify -gamma, you get a rather  strange  addi‐
122              tional  function, probably a historical mistake: pngtopam incor‐
123              porates the specified screen gamma value into the output pixels,
124              so that the samples in the Netpbm output deviate from the Netpbm
125              format specifications and are appropriate raw  intensity  values
126              to  send  to  the display.  This function essentially just exer‐
127              cises the ability of the PNG library to make  gamma  corrections
128              to the pixels as it reads them from the PNG file to produce val‐
129              ues appropriate for sending to  a  certain  display  in  certain
130              viewing  conditions.   It's  a  strange  function because it has
131              nothing to do with PNG and because in Netpbm, the normal way  to
132              make gamma corrections appropriate for sending to a ceratin dis‐
133              play in certain viewing conditions is with the program pngtopam,
134              applied to the normal output of pngtopam.
135
136              If  you  specify -gamma, but the PNG image does not specify what
137              gamma transformation it uses (there is no gAMA chunk),  pngtopam
138              assumes  a  simple  power  transformation with an image gamma of
139              1.0.  That is probably not not the actual  image  gamma;  it  is
140              much more likely to be .45.
141
142              Because  the  gammas  of  uncompensated monitors are around 2.6,
143              which results in an image-gamma of 0.45, some typical situations
144              are:  when  the  image-gamma is 0.45 (use -verbose to check) and
145              the picture is too light, your  system  is  gamma-corrected,  so
146              convert with "-gamma 1.0".  When no gAMA chunk is present or the
147              image-gamma is 1.0, use 2.2 to make the picture lighter and 0.45
148              to make the picture darker.
149
150              One  oddity  to  be  aware of when using -gamma on an image with
151              transparency: The PNG image specifies that a  certain  color  is
152              transparent,  i.e.  every  pixel  in  the image of that color is
153              transparent.  But pngtopam interprets this as  applying  to  the
154              gamma-corrected  space,  and there may be less precision in that
155              space than in the original,  which  means  multiple  uncorrected
156              colors  map  to  the  same corrected color.  So imagine that the
157              image contains 3 shades of white (gray) and specifies  that  one
158              of  them  is  transparent.   After gamma correction, those three
159              shades are indistinguishable, so pngtopam  considers  pixels  of
160              all three shades to be transparent.
161
162
163
164       -text=file
165              Writes  the  tEXt  and  zTXt  chunks  to  a file, in a format as
166              described in the pnmtopng user  manual.   These  chunks  contain
167              text comments or annotations.
168
169
170       -time  Prints the tIME chunk to stderr.
171
172
173       -byrow This  option  can  make  pngtopam  run faster or in environments
174              where it would otherwise fail.
175
176              pngtopam has two ways to do the  conversion  from  PNG  to  PAM,
177              using respectively two facilities of the PNG library:
178
179
180
181
182       Whole Image
183              Decode   the   entire   image   into   memory   at  once,  using
184              png_read_image(), then convert to PAM and output row by row.
185
186
187       Row By Row
188              Read,  convert,  and  output   one   row   at   a   time   using
189              png_read_row().
190
191
192
193              Whole Image is generally preferable because the PNG library does
194              more of the work, which means it understands  more  of  the  PNG
195              format possibilities now and in the future.  Also, if the PNG is
196              interlaced, pngtopam does not know how to assemble the  rows  in
197              the right order.
198
199              Row  By Row uses far less memory, which means with large images,
200              it can run in environments where Whole Image cannot and may also
201              run faster.  And because Netpbm code does more of the work, it's
202              possible that it can be more flexible or at  least  give  better
203              diagnostic information if there's something wrong with the PNG.
204
205              The  Netpbm  native code may do something correctly that the PNG
206              library does incorrectly, or vice versa.
207
208              In Netpbm, we stress function over performance,  so  by  default
209              pngtopam  uses  Whole  Image.   You  can  select Row By Row with
210              -byrow if you want the speed or  resource  requirement  improve‐
211              ment.
212
213              -byrow was new in Netpbm 10.54 (March 2011).
214
215
216
217       -orientraw
218              A  TIFF stream contains raster data which can be arranged in the
219              stream various ways.  Most commonly, it  is  arranged  by  rows,
220              with the top row first, and the pixels left to right within each
221              row, but many other orientations are possible.
222
223              The common orientation is the same on the Netpbm formats use, so
224              tifftopnm can do its jobs quite efficiently when the TIFF raster
225              is oriented that way.
226
227              But if the TIFF raster is oriented any other way, it can take  a
228              considerable amount of processing for tifftopnm to convert it to
229              Netpbm format.
230
231
232
233

SEE ALSO

235       pamtopng(1), pnmtopng(1), pngtopnm(1), ptot, pnmgamma(1), pnm(1)
236
237       For  information  on  the   PNG   format,   see   http://schaik.com/png
238http://schaik.com/png⟩ .
239
240

NOTE

242       A  PNG image contains a lot of information that can't be represented in
243       Netpbm formats.  Therefore, you lose information when  you  convert  to
244       another  format  with "pngtopam | pnmtoxxx".  If there is a specialized
245       converter that converts directly to the other format, e.g. ptot to con‐
246       vert from PNG to TIFF, you'll get better results using that.
247
248

LIMITATIONS

250       There  could  be  an option to include PNG comment chunks in the output
251       image as PNM comments instead of putting them in a separate file.
252
253       The program could be much faster, with a bit of  code  optimizing.   As
254       with  any  Netpbm  program,  speed  always  takes  a back seat to quick
255       present and future development.
256
257

HISTORY

259       pngtopam was new in Netpbm 10.44, as a replacement for  pngtopnm.   The
260       main  improvement  over pngtopnm was that it could generate a PAM image
261       with a transparency channel, whereas with pngtopnm, you would  have  to
262       extract the transparency channel as a separate file, in a separate run.
263
264       pngtopnm  was  new  in Netpbm 8.1 (March 2000), the first big change to
265       the package in Netpbm's  renaissance.   It  and  pnmtopng  were  simply
266       copied  from  the    pnmtopng package" (1) by Greg Roelofs.  Those were
267       based  on  simpler  reference   applications   by   Alexander   Lehmann
268       <alex@hal.rhein-main.de>  and Willem van Schaik <willem@schaik.com> and
269       distributed with their PNG library.
270
271       Nearly all of the code has changed since it was copied  from  the  pnm‐
272       topng package, most of it just to improve maintainability.
273
274
275

AUTHORS

277       Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
278

DOCUMENT SOURCE

280       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
281       source.  The master documentation is at
282
283              http://netpbm.sourceforge.net/doc/pngtopam.html
284
285netpbm documentation             22 July 2008          Pngtopam User Manual(0)
Impressum