1Pngtopam User Manual(0) Pngtopam User Manual(0)
2
6 pngtopam - convert a PNG image into a Netpbm image
7
10 pngtopam [-verbose] [-alphapam | -alpha | -mix] [-background=color]
11 [-gamma=value] [-text=filename] [-time] [-byrow] [pngfile]
12 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
20 This program is part of Netpbm(1).
21 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 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
39 In addition to the options common to all programs based on libnetpbm
40 (most notably -quiet, see
41 Common Options ⟨index.html#commonoptions⟩ ), pngtopam recognizes the
42 following command line options:
43 -verbose
47 Display various information about the input PNG image and the
48 conversion process.
49 If you want even more information about the PNG image, use
51 pngcheck (not part of Netpbm).
52 -alphapam
55 Produce a single output image containing the main image (fore‐
56 ground) and the transparency channel or transparency mask. This
57 image is in the PAM format with tuple type of either
58 GRAYSCALE_ALPHA (which has a depth of 2 channels) or RGB_ALPHA
59 (which has a depth of 4 channels).
60 You can specify only one of -alphapam, -alpha, and -mix. With
62 none of them, pngtopam produces an image of the foreground of
63 the input image and discards transparency information.
64 This option was new in Netpbm 10.44 (September 2008).
66 -alpha Output the transparency channel or transparency mask of the
69 image. The result is either a PBM file or a PGM file, depending
70 on whether different levels of transparency appear.
71 pngtopam discards the main image (the foreground).
73 You can specify only one of -alphapam, -alpha, and -mix. With
75 none of them, pngtopam produces an image of the foreground of
76 the input image and discards transparency information.
77 -mix Compose the image with the transparency or transparency mask
80 against a background. The background color is determined by the
81 bKGD chunk in the PNG, except that you can override it with
82 -background. If the PNG has no bKGD chunk and you don't specify
83 -background, the background color is white.
84 You can specify only one of -alphapam, -alpha, and -mix. With
86 none of them, pngtopam produces an image of the foreground of
87 the input image and discards transparency information.
88 -background=color
91 This option specifies the background color with which to mix the
92 image when you specify -mix.
93 color is as described for the argument of the pnm_parsecolor()
95 library routine ⟨libnetpbm_image.html#colorname⟩ .
96 Examples:
98 · -background=rgb:01/ff/80
102 · -background=rgbi:1/255/128
104 If you don't specify -background, the background color is what
107 is specified in the PNG image, and if the PNG doesn't specify
108 anything, white.
109 You cannot specify -background unless you also specify -mix.
111 Before Netpbm 10.27 (March 2005), you could specify -background
112 without -mix and it was just ignored. (This caused a usability
113 problem).
114 -gamma=value
118 This option causes pngtopam to respect the image gamma informa‐
119 tion in the PNG file (from the gAMA chunk). Probably by histor‐
120 ical accident, pngtopam ignores that information by default,
121 assuming the image uses the same gamma transformation as a
122 Netpbm image, so the output image has different colors than the
123 PNG file actually represents if the PNG doesn't actually do
124 that. (However, it is rare for a PNG file to use a gamma trans‐
125 formation different from what the Netpbm formats specify, or if
126 it does, to specify with a gAMA chuck what that is).
127 But when you do specify -gamma, you get a rather strange addi‐
129 tional function, probably a historical mistake: pngtopam incor‐
130 porates the specified screen gamma value into the output pixels,
131 so that the samples in the Netpbm output deviate from the Netpbm
132 format specifications and are appropriate raw intensity values
133 to send to the display. This function essentially just exer‐
134 cises the ability of the PNG library to make gamma corrections
135 to the pixels as it reads them from the PNG file to produce val‐
136 ues appropriate for sending to a certain display in certain
137 viewing conditions. It's a strange function because it has
138 nothing to do with PNG and because in Netpbm, the normal way to
139 make gamma corrections appropriate for sending to a ceratin dis‐
140 play in certain viewing conditions is with the program pngtopam,
141 applied to the normal output of pngtopam.
142 If you specify -gamma, but the PNG image does not specify what
144 gamma transformation it uses (there is no gAMA chunk), pngtopam
145 assumes a simple power transformation with an image gamma of
146 1.0. That is probably not not the actual image gamma; it is
147 much more likely to be .45.
148 Because the gammas of uncompensated monitors are around 2.6,
150 which results in an image-gamma of 0.45, some typical situations
151 are: when the image-gamma is 0.45 (use -verbose to check) and
152 the picture is too light, your system is gamma-corrected, so
153 convert with "-gamma 1.0". When no gAMA chunk is present or the
154 image-gamma is 1.0, use 2.2 to make the picture lighter and 0.45
155 to make the picture darker.
156 One oddity to be aware of when using -gamma on an image with
158 transparency: The PNG image specifies that a certain color is
159 transparent, i.e. every pixel in the image of that color is
160 transparent. But pngtopam interprets this as applying to the
161 gamma-corrected space, and there may be less precision in that
162 space than in the original, which means multiple uncorrected
163 colors map to the same corrected color. So imagine that the
164 image contains 3 shades of white (gray) and specifies that one
165 of them is transparent. After gamma correction, those three
166 shades are indistinguishable, so pngtopam considers pixels of
167 all three shades to be transparent.
168 -text=file
172 Writes the tEXt and zTXt chunks to a file, in a format as
173 described in the pnmtopng user manual. These chunks contain
174 text comments or annotations.
175 -time Prints the tIME chunk to stderr.
178 -byrow This option can make pngtopam run faster or in environments
181 where it would otherwise fail.
182 pngtopam has two ways to do the conversion from PNG to PAM,
184 using respectively two facilities of the PNG library:
185 Whole Image
190 Decode the entire image into memory at once, using
191 png_read_image(), then convert to PAM and output row by row.
192 Row By Row
195 Read, convert, and output one row at a time using
196 png_read_row().
197 Whole Image is generally preferable because the PNG library does
201 more of the work, which means it understands more of the PNG
202 format possibilities now and in the future. Also, if the PNG is
203 interlaced, pngtopam does not know how to assemble the rows in
204 the right order.
205 Row By Row uses far less memory, which means with large images,
207 it can run in environments where Whole Image cannot and may also
208 run faster. And because Netpbm code does more of the work, it's
209 possible that it can be more flexible or at least give better
210 diagnostic information if there's something wrong with the PNG.
211 The Netpbm native code may do something correctly that the PNG
213 library does incorrectly, or vice versa.
214 In Netpbm, we stress function over performance, so by default
216 pngtopam uses Whole Image. You can select Row By Row with
217 -byrow if you want the speed or resource requirement improve‐
218 ment.
219 -byrow was new in Netpbm 10.54 (March 2011).
221 -orientraw
225 A TIFF stream contains raster data which can be arranged in the
226 stream various ways. Most commonly, it is arranged by rows,
227 with the top row first, and the pixels left to right within each
228 row, but many other orientations are possible.
229 The common orientation is the same on the Netpbm formats use, so
231 tifftopnm can do its jobs quite efficiently when the TIFF raster
232 is oriented that way.
233 But if the TIFF raster is oriented any other way, it can take a
235 considerable amount of processing for tifftopnm to convert it to
236 Netpbm format.
237
242 pamtopng(1), pnmtopng(1), pngtopnm(1), ptot, pnmgamma(1), pnm(1)
243 For information on the PNG format, see http://schaik.com/png
245 ⟨http://schaik.com/png⟩ .
246
249 A PNG image contains a lot of information that can't be represented in
250 Netpbm formats. Therefore, you lose information when you convert to
251 another format with "pngtopam | pnmtoxxx". If there is a specialized
252 converter that converts directly to the other format, e.g. ptot to con‐
253 vert from PNG to TIFF, you'll get better results using that.
254
257 There could be an option to include PNG comment chunks in the output
258 image as PNM comments instead of putting them in a separate file.
259 The program could be much faster, with a bit of code optimizing. As
261 with any Netpbm program, speed always takes a back seat to quick
262 present and future development.
263
266 pngtopam was new in Netpbm 10.44, as a replacement for pngtopnm. The
267 main improvement over pngtopnm was that it could generate a PAM image
268 with a transparency channel, whereas with pngtopnm, you would have to
269 extract the transparency channel as a separate file, in a separate run.
270 pngtopnm was new in Netpbm 8.1 (March 2000), the first big change to
272 the package in Netpbm's renaissance. It and pnmtopng were simply
273 copied from the pnmtopng package" (1) by Greg Roelofs. Those were
274 based on simpler reference applications by Alexander Lehmann
275 <alex@hal.rhein-main.de> and Willem van Schaik <willem@schaik.com> and
276 distributed with their PNG library.
277 Nearly all of the code has changed since it was copied from the pnm‐
279 topng package, most of it just to improve maintainability.
280
284 Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
285
287 This manual page was generated by the Netpbm tool 'makeman' from HTML
288 source. The master documentation is at
289 http://netpbm.sourceforge.net/doc/pngtopam.html
291netpbm documentation 22 July 2008 Pngtopam User Manual(0)