Debian Codegraph @

upstream/debian-unstable/man1/pngtopam.1

raw
1 \
2 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
3 .\" Do not hand-hack it! If you have bug fixes or improvements, please find
4 .\" the corresponding HTML page on the Netpbm website, generate a patch
5 .\" against that, and send it to the Netpbm maintainer.
6 .TH "Pngtopam User Manual" 1 "22 July 2008" "netpbm documentation"
7
8 .SH NAME
9 pngtopam - convert a PNG image into a Netpbm image
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpngtopam\fP
15 [\fB-verbose\fP]
16 [\fB-alphapam\fP | \fB-alpha\fP | \fB-mix\fP]
17 [\fB-background\fP=\fIcolor\fP]
18 [\fB-gamma\fP=\fIvalue\fP]
19 [\fB-text\fP=\fIfilename\fP]
20 [\fB-time\fP]
21 [\fB-byrow\fP]
22 [\fIpngfile\fP]
23 .PP
24 Minimum unique abbreviation of option is acceptable. You may use double
25 hyphens instead of single hyphen to denote options. You may use white
26 space in place of the equals sign to separate an option name from its value.
27
28 .UN description
29 .SH DESCRIPTION
30 .PP
31 This program is part of
32 .BR "Netpbm" (1)\c
33 \&.
34 .PP
35 \fBpngtopam\fP reads a PNG image (Portable Network Graphics) as
36 input and produces a Netpbm image as output. The type of the output file
37 depends on the input file - if it's black & white, \fBpngtopam\fP
38 creates a PBM file. If it's grayscale, \fBpngtopam\fP creates a PGM
39 file. Otherwise, it creates a PPM file. Except that with the
40 \fB-alphapam\fP option, it always creates a PAM file. That file has
41 tuple type GRAYSCALE_ALPHA or RGB_ALPHA depending on whether the input
42 has color or not.
43 .PP
44 To convert in the other direction, use \fBpamtopng\fP or
45 \fBpnmtopng\fP. The former is the more modern of the two and can recognize
46 transparency information in a PAM file, as you might generate with \fBpngtopam
47 -alphapam\fP. It has existed only since June 2015. The latter has more
48 features, but probably not ones that matter in the modern world.
49
50
51 .UN options
52 .SH OPTIONS
53 .PP
54 In addition to the options common to all programs based on libnetpbm
55 (most notably \fB-quiet\fP, see
56 .UR index.html#commonoptions
57 Common Options
58 .UE
59 \&), \fBpngtopam\fP recognizes the following
60 command line options:
61
62
63 .TP
64 \fB-verbose\fP
65 Display various information about the input PNG image and the
66 conversion process.
67 .sp
68 If you want even more information about the PNG image, use
69 \fBpngcheck\fP (not part of Netpbm).
70
71 .TP
72 \fB-alphapam\fP
73 Produce a single output image containing the main image (foreground)
74 and the transparency channel or transparency mask. This image is in the PAM
75 format with tuple type of either GRAYSCALE_ALPHA (which has a depth of
76 2 channels) or RGB_ALPHA (which has a depth of 4 channels).
77 .sp
78 You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and
79 \fB-mix\fP. With none of them, \fBpngtopam\fP produces an image of
80 the foreground of the input image and discards transparency information.
81 .sp
82 This option was new in Netpbm 10.44 (September 2008).
83
84 .TP
85 \fB-alpha\fP
86 Output the transparency channel or transparency mask of the image. The
87 result is either a PBM file or a PGM file, depending on whether
88 different levels of transparency appear.
89 .sp
90 \fBpngtopam\fP discards the main image (the foreground).
91 .sp
92 You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and
93 \fB-mix\fP. With none of them, \fBpngtopam\fP produces an image of
94 the foreground of the input image and discards transparency information.
95
96 .TP
97 \fB-mix\fP
98 Compose the image with the transparency or transparency mask against a
99 background. The background color is determined by the bKGD chunk in
100 the PNG, except that you can override it with \fB-background\fP.
101 If the PNG has no bKGD chunk and you don't specify \fB-background\fP,
102 the background color is white.
103 .sp
104 You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and
105 \fB-mix\fP. With none of them, \fBpngtopam\fP produces an image of
106 the foreground of the input image and discards transparency information.
107
108 .TP
109 \fB-background=\fP\fIcolor\fP
110 This option specifies the background color with which to mix the image
111 when you specify \fB-mix\fP.
112 .sp
113 \fIcolor\fP is as described for the
114 .UR libnetpbm_image.html#colorname
115 argument of the \fBpnm_parsecolor()\fP library routine
116 .UE
117 \&.
118 .sp
119 Examples:
120
121
122 .IP \(bu
123 \f(CW-background=rgb:01/ff/80\fP
124 .IP \(bu
125 \f(CW-background=rgbi:1/255/128\fP
126
127 .sp
128 If you don't specify \fB-background\fP, the background color is what
129 is specified in the PNG image, and if the PNG doesn't specify anything,
130 white.
131 .sp
132 You cannot specify \fB-background\fP unless you also specify
133 \fB-mix\fP. Before Netpbm 10.27 (March 2005), you could specify
134 \fB-background\fP without \fB-mix\fP and it was just ignored. (This
135 caused a usability problem).
136
137
138 .TP
139 \fB-gamma=\fP\fIvalue\fP
140 This option causes \fBpngtopam\fP to respect the image gamma information
141 in the PNG file (from the gAMA chunk). Probably by historical accident,
142 \fBpngtopam\fP ignores that information by default, assuming the image uses
143 the same gamma transformation as a Netpbm image, so the output image has
144 different colors than the PNG file actually represents if the PNG doesn't
145 actually do that. (However, it is rare for a PNG file to use a gamma
146 transformation different from what the Netpbm formats specify, or if it does,
147 to specify with a gAMA chuck what that is).
148 .sp
149 But when you \fIdo\fP specify \fB-gamma\fP, you get a rather strange
150 additional function, probably a historical mistake:
151 \fBpngtopam\fP incorporates the specified screen gamma value into the output
152 pixels, so that the samples in the Netpbm output deviate from the Netpbm
153 format specifications and are appropriate raw intensity values to send to the
154 display. This function essentially just exercises the ability of the PNG
155 library to make gamma corrections to the pixels as it reads them from the PNG
156 file to produce values appropriate for sending to a certain display in certain
157 viewing conditions. It's a strange function because it has nothing to do with
158 PNG and because in Netpbm, the normal way to make gamma corrections
159 appropriate for sending to a ceratin display in certain viewing conditions is
160 with the program \fBpngtopam\fP, applied to the normal output of
161 \fBpngtopam\fP.
162 .sp
163 If you specify \fB-gamma\fP, but the PNG image does not specify what gamma
164 transformation it uses (there is no gAMA chunk), \fBpngtopam\fP assumes a
165 simple power transformation with an image gamma of 1.0. That is probably not
166 not the actual image gamma; it is much more likely to be .45.
167 .sp
168 Because the gammas of uncompensated monitors are around 2.6, which results
169 in an image-gamma of 0.45, some typical situations are:
170 when the image-gamma is 0.45 (use -verbose to check) and the picture is too
171 light, your system is gamma-corrected, so convert with "-gamma 1.0".
172 When no gAMA chunk is present or the image-gamma is 1.0, use 2.2 to make the
173 picture lighter and 0.45 to make the picture darker.
174 .sp
175 One oddity to be aware of when using \fB-gamma\fP on an image with
176 transparency: The PNG image specifies that a certain color is
177 transparent, i.e. every pixel in the image of that color is
178 transparent. But \fBpngtopam\fP interprets this as applying to the
179 gamma-corrected space, and there may be less precision in that space
180 than in the original, which means multiple uncorrected colors map to
181 the same corrected color. So imagine that the image contains 3 shades
182 of white (gray) and specifies that one of them is transparent. After gamma
183 correction, those three shades are indistinguishable, so
184 \fBpngtopam\fP considers pixels of all three shades to be transparent.
185
186
187 .TP
188 \fB-text=\fP\fIfile\fP
189 Writes the tEXt and zTXt chunks to a file, in a format as
190 described in the \fBpnmtopng\fP user manual. These chunks contain
191 text comments or annotations.
192
193 .TP
194 \fB-time\fP
195 Prints the tIME chunk to stderr.
196
197 .TP
198 \fB-byrow\fP
199 This option can make \fBpngtopam\fP run faster or in environments
200 where it would otherwise fail.
201 .sp
202 \fBpngtopam\fP has two ways to do the conversion from PNG to PAM, using
203 respectively two facilities of the PNG library:
204
205
206
207 .TP
208 Whole Image
209 Decode the entire image into memory at once, using
210 \fBpng_read_image()\fP, then convert to PAM and output row by row.
211
212 .TP
213 Row By Row
214 Read, convert, and output one row at a time using \fBpng_read_row()\fP.
215
216
217 .sp
218 Whole Image is generally preferable because the PNG library does more of
219 the work, which means it understands more of the PNG format possibilities now
220 and in the future. Also, if the PNG is interlaced, \fBpngtopam\fP does
221 not know how to assemble the rows in the right order.
222 .sp
223 Row By Row uses far less memory, which means with large images, it
224 can run in environments where Whole Image cannot and may also run
225 faster. And because Netpbm code does more of the work, it's possible
226 that it can be more flexible or at least give better diagnostic
227 information if there's something wrong with the PNG.
228 .sp
229 The Netpbm native code may do something correctly that the PNG library does
230 incorrectly, or vice versa.
231 .sp
232 In Netpbm, we stress function over performance, so by default
233 \fBpngtopam\fP uses Whole Image. You can select Row By Row with
234 \fB-byrow\fP if you want the speed or resource requirement improvement.
235 .sp
236 \fB-byrow\fP was new in Netpbm 10.54 (March 2011).
237
238
239 .TP
240 \fB-orientraw\fP
241 A TIFF stream contains raster data which can be arranged in the
242 stream various ways. Most commonly, it is arranged by rows, with the
243 top row first, and the pixels left to right within each row, but many
244 other orientations are possible.
245 .sp
246 The common orientation is the same on the Netpbm formats use, so
247 \fBtifftopnm\fP can do its jobs quite efficiently when the TIFF raster
248 is oriented that way.
249 .sp
250 But if the TIFF raster is oriented any other way, it can take a
251 considerable amount of processing for \fBtifftopnm\fP to convert it to
252 Netpbm format.
253
254
255
256 .UN seealso
257 .SH SEE ALSO
258 .BR "pamtopng" (1)\c
259 \&,
260 .BR "pnmtopng" (1)\c
261 \&,
262 .BR "pngtopnm" (1)\c
263 \&,
264 \fBptot\fP,
265 .BR "pnmgamma" (1)\c
266 \&,
267 .BR "pnm" (1)\c
268 \&
269 .PP
270 For information on the PNG format, see
271 .UR http://schaik.com/png
272 http://schaik.com/png
273 .UE
274 \&.
275
276 .UN note
277 .SH NOTE
278 .PP
279 A PNG image contains a lot of information that can't be represented in
280 Netpbm formats. Therefore, you lose information when you convert to
281 another format with "pngtopam | pnmtoxxx". If there is a specialized
282 converter that converts directly to the other format, e.g. \fBptot\fP
283 to convert from PNG to TIFF, you'll get better results using that.
284
285 .UN limitations
286 .SH LIMITATIONS
287 .PP
288 There could be an option to include PNG comment chunks in the output
289 image as PNM comments instead of putting them in a separate file.
290 .PP
291 The program could be much faster, with a bit of code optimizing.
292 As with any Netpbm program, speed always takes a back seat to quick
293 present and future development.
294
295 .UN history
296 .SH HISTORY
297 .PP
298 \fBpngtopam\fP was new in Netpbm 10.44, as a replacement for
299 \fBpngtopnm\fP. The main improvement over \fBpngtopnm\fP was that
300 it could generate a PAM image with a transparency channel, whereas
301 with \fBpngtopnm\fP, you would have to extract the transparency
302 channel as a separate file, in a separate run.
303 .PP
304 \fBpngtopnm\fP was new in Netpbm 8.1 (March 2000), the first big
305 change to the package in Netpbm's renaissance. It and \fBpnmtopng\fP
306 were simply copied from the
307 .BR "
308 \fBpnmtopng\fP package" (1)\c
309 \& by Greg Roelofs. Those were based on
310 simpler reference applications by Alexander Lehmann
311 <[email protected]> and Willem van Schaik
312 <[email protected]> and distributed with their PNG library.
313 .PP
314 Nearly all of the code has changed since it was copied from the
315 \fBpnmtopng\fP package, most of it just to improve maintainability.
316
317
318 .UN authors
319 .SH AUTHORS
320
321 Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
322 .SH DOCUMENT SOURCE
323 This manual page was generated by the Netpbm tool 'makeman' from HTML
324 source. The master documentation is at
325 .IP
326 .B http://netpbm.sourceforge.net/doc/pngtopam.html
327 .PP