1Pamtopng User Manual(0) Pamtopng User Manual(0)
2
6 pamtopng - convert a Netpbm image to PNG
7
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] [-interlace] [pnm‐
14 file]
15
18 Minimum unique abbreviation of option is acceptable. You may use dou‐
19 ble hyphens instead of a single hyphen to denote options. You may use
20 white space in place of the equals sign to separate an option name from
21 its value.
22
25 This program is part of Netpbm(1).
26 pamtopng reads a Netpbm image as input and produces a PNG image as out‐
28 put.
29 Color component values in PNG files are either 8 or 16 bits wide, so
31 where necessary pamtopng scales colors to have a maxval of 255 or
32 65535. In that case, it will add an sBIT chunk to indicated the origi‐
33 nal bit-depth.
34 pamtopng works only on images with maxval 1, 3, 15, 255, or 65535. You
36 can use pamdepth to convert an image with some other maxval to one of
37 these.
38 pamtopng produces a color PNG from a color PAM, even if the only colors
40 in the image are shades of gray. To create a graycale PNG, from such
41 an image (which might be slightly smaller), you can use other Netpbm
42 programs to convert the input to grayscale.
43 Alternative: pnmtopng
46 Netpbm contains another program for generating PNG images: pnmtopng.
47 pnmtopng is a much older program - it is in fact the first program in
48 the world that could generate a PNG. pnmtopng is a complex, feature-
49 laden program. It lets you control various arcane aspects of the con‐
50 version and create PNGs with various arcane features. It does various
51 transformations on the image to create the greatest compression possi‐
52 ble, to a degree that probably doesn't make any difference in the mod‐
53 ern world.
54 The main advantage pamtopng has over pnmtopng is that the former can
56 use the transparency channel of a PAM image to generate the transpar‐
57 ency information in the PNG. In contrast, handling of the alpha chan‐
58 nel is very cumbersome with pnmotpng.
59 One difference that does not exist, that some people might incorrectly
61 infer from the names is the possible input formats. Both programs can
62 take PBM, PGM, PPM, and PAM input.
63 Because pnmtopng has been around virtually forever, programs and proce‐
65 dures that use it are more portable than those that use pamtopng. Its
66 age and popularity also probably make it have fewer bugs.
67 pamtopng does not have any way to do what the following do in pnmtopng:
69 • -palette
73 • -history
75 • -filter
77 • -size
79 • -paeth
81 • -hist
83 • -nofilter
85 • -sub
87 • -up
89 • -avg
91 • -force
93 • -libversion
95 • -compression
97 • -comp_xxx
99 These are some of the other functions of pnmtopng that pamtopng lacks:
102 • When you specify a transparent or background color that is not
106 in the image, pnmtopng can optionally choose the closest one
107 that is in the image. pamtopng always uses the exact color you
108 specify.
109 Features that exist in both programs are controlled by largely the same
112 command syntax. But there are these differences:
113 • pnmtopng's -rgb option is -chroma in pamtopng. -chroma is a
117 better name, and in fact was the name that pnmtopng used origi‐
118 nally, but we had to change it when we had to change the syntax
119 of the option value to conform to the rest of Netpbm.
120 • pnmtopng's -modtime option is -time in pamtopng. The origin of
123 -modtime is analogous to that of -rgb.
124
130 In addition to the options common to all programs based on libnetpbm
131 (most notably -quiet, see
132 Common Options ⟨index.html#commonoptions⟩ ), pamtopng recognizes the
133 following command line options:
134 -transparent=color
139 pamtopng marks the specified color as transparent in the PNG im‐
140 age -- Every pixel of this color is fully transparent. This
141 causes pamtopng to include a tRNS chunk in the image identifying
142 that color.
143 Specify the color (color) as described for the argument of the
145 pnm_parsecolor() library routine
146 ⟨libnetpbm_image.html#colorname⟩ . E.g. red or rgb:ff/00/0d.
147 -background=color
150 This causes pamtopng to create a background color chunk in the
151 PNG output which can be used for subsequent transparency channel
152 or transparent color conversions. Specify color the same as for
153 -transparent.
154 -gamma=value
159 This causes pamtopng to create a gAMA chunk. This information
160 helps describe how the color values in the PNG must be inter‐
161 preted. Without the gAMA chunk, whatever interprets the PNG
162 must get this information separately (or just assume something
163 standard). If your input is a true PPM or PGM image, you should
164 specify -gamma=.45. But sometimes people generate images which
165 are ostensibly PPM except the image uses a different gamma
166 transfer function than the one specified for PPM. A common case
167 of this is when the image is created by simple hardware that
168 doesn't have digital computational ability. Also, some simple
169 programs that generate images from scratch do it with a gamma
170 transfer in which the gamma value is 1.0.
171 -chroma=chroma_list
176 This option specifies how red, green, and blue component values
177 of a pixel specify a particular color, by telling the chromatic‐
178 ities of those 3 primary illuminants and of white (i.e. full
179 strength of all three).
180 The chroma_list value is a blank-separated list of 8 floating
182 point decimal numbers. The CIE-1931 X and Y chromaticities (in
183 that order) of each of white, red, green, and blue, in that or‐
184 der.
185 This information goes into the PNG's cHRM chunk.
187 In a shell command, make sure you use quotation marks so that
189 the blanks in chroma_list don't make the shell see multiple com‐
190 mand arguments.
191 -srgbintent=intent
194 This asserts that the input is a pseudo-Netpbm image that uses
195 an sRGB color space (unlike true Netpbm) and indicates how you
196 intend for the colors to be rendered. It causes pamtopng to in‐
197 clude an sRGB chunk in the PNG image that specifies that intent,
198 so see the PNG documentation for more information on what this
199 really means.
200 intent is one of:
202 • perceptual
206 • relativecolorimetric
208 • saturation
210 • absolutecolorimetric
212 -text=filename
216 This option lets you include arbitrary text strings in the PNG
217 output, as tEXt chunks.
218 filename is the name of a file that contains your text strings.
220 The output contains a distinct tEXt chunk for each entry in the
222 file.
223 Here is an example of a text string file:
225 Title PNG file
227 Author John Doe
228 Description how to include a text chunk
229 PNG file
230 "Creation Date" 2015-may-11
231 Software pamtopng
232 The file is divided into entries, each entry comprising consecu‐
235 tive lines of text. The first line of an entry starts in the
236 first column (i.e. the first column is not white space) and ev‐
237 ery other line has white space in the first column. The first
238 entry starts in the first line, so it is not valid for the first
239 line of the file to have white space in its first column.
240 The first word in an entry is the key of the text string (e.g.
242 'Title'). It begins in column one of the line and continues up
243 to, but not including, the first delimiter character or the end
244 of the line, whichever is first. You can enclose the key in
245 double quotes in which case the key can consists of multiple
246 words. The quotes are not part of the key. The text string per
247 se begins after the key and any delimiter characters after it,
248 plus the text in subsequent continuation lines.
249 There is no limit on the length of a file line or entry or key
251 or text string. There is no limit on the number of entries.
252 -ztxt=filename
255 The same as -text, except the text string is compressed in the
256 PNG output. pamtopng uses zTXt chunks instead of a tEXt chunks.
257 -itxt=filename
262 Similar to -text, but the text strings can be in a language
263 other than English. The PNG image indicates what language that
264 is and includes the text string key both in English and that
265 language. pamtopng uses iTXt chunks instead of tEXt chunks.
266 For each record, you must specify the language and give the key
268 both in English and in the text string language.
269 Example:
271 Language nl-NL Taal nl-NL
273 Title nl-NL Titel PNG file
274 Author nl-NL Auteur Pietje Puk
275 Description nl-NL Omschrijving Tekst in het Nederlands.
276 The language specification is based on the ISO 639-1 standard,
279 see http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for the
280 valid codes. The format is either a two character "nl" or an
281 extended code like "en-US".
282 -time='[yy]yy-mm-dd hh:mm:ss'
285 This option allows you to specify the modification time value to
286 be placed in the PNG output. You can specify the year parameter
287 either as a two or four digit value.
288 -interlace
293 This causes the PNG file to be interlaced, in Adam7 format. The
294 interlaced format is one in which the raster data starts with a
295 low-resolution representation of the entire image, then contin‐
296 ues with additional information for the entire image, then even
297 more information, etc. In Adam7 in particular, there are seven
298 such passes of the whole image. This is useful when you are re‐
299 ceiving the image over a slow communication line as someone is
300 waiting to see it. The simplest thing to do in that case is
301 wait for the entire image to arrive and then display it in‐
302 stantly, but then the user is wasting time staring at a blank
303 space until the whole image arrives. With the standard non-in‐
304 terlaced format, the data arrives row-by-row starting at the
305 top, so the displayer could display each row of the image as it
306 arrives and gradually paint down to the bottom. But with an in‐
307 terlaced image, the displayer can start by showing a low-resolu‐
308 tion version of the image, then gradually improve the display as
309 more data arrives.
310 When you specify this option, pamtopng must hold the entire im‐
312 age in memory at once, whereas without it, the program holds
313 only one raster row at a time. If you don't have enough memory
314 for that, you might suffer extreme slowdowns or failure - not
315 just in the process running pamtopng, but potentially throughout
316 the system that shares memory with it. pnmtopng does not have
317 this limitation (it holds only one row at a time in memory even
318 when generating an interlaced PNG).
319 This option was new in Netpbm 10.86 (March 2019).
321 -verbose
324 This causes the program to display various facts about the con‐
325 version.
326
334 pngtopam(1), pnmtopng(1), pam(1), pnm(1)
335 For information on the PNG format, see http://www.w3.org/TR/PNG/
337 ⟨http://www.w3.org/TR/PNG/⟩ , http://libpng.org/pub/png/
338 ⟨http://libpng.org/pub/png/⟩ ,
339 http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
340 ⟨http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes⟩ and
341 http://schaik.com/png/ ⟨http://schaik.com/png/⟩ .
342
345 pamtopng was new in Netpbm 10.70 (June 2015).
346 Before pamtopng, the two ways to create PNG images with Netpbm were pn‐
348 mtopng and pamrgbatopng. The history of the former is discussed above.
349 The latter was added to Netpbm in 2005 as a cheap way to fill a signif‐
350 icant need that pnmtopng did not: the ability to turn the alpha channel
351 in a PAM image into the alpha channel in a PNG image.
352 Handling of the alpha channel with pnmtopng is very cumbersome (as was
354 dealing with alpha channels in general before the introduction of the
355 PAM format). pamrgbatopng could do what people wanted with the alpha
356 channel, but nothing else. It was a very small program with literally
357 no command line options.
358 The goal in those days was eventually to expand pnmtopng to do the PAM
360 alpha channel thing, rename it to pamtopng, and retire pamrgbatopng.
361 But pnmtopng is such a complex program, because of its dizzying array
362 of features and its need for backward compatibility, that adding that
363 one capability to it was a daunting task and for ten years nobody at‐
364 tempted it.
365 In 2015, one of the authors of the original pnmtopng (from before it
367 was even part of Netpbm -- a program that shared essentially no lines
368 of code with pnmtopng of 2015) decided to go in a different direction.
369 While many features of pnmtopng were pretty important and easy to im‐
370 plement, many others were probably of no use in the modern world or at
371 least not important enough to justify the complexity they lent to the
372 code. (The features thought to be outdated were ones that were in‐
373 tended to make the PNG output slightly smaller - something considerably
374 less important with the declining cost of computer resources).
375 And there was an opportunity to drop those features: We could use the
377 new name 'pamtopng' for a new program, keep the existing program under
378 the name 'pnmtopng', and avoid most backward compatibility trouble.
379 Therefore, Willem van Schaik wrote an intermediate level program that
381 had all the most important features of pnmtopng, plus the alpha channel
382 handling of pamrgbatopng, with nice, simple code. That was pamtopng.
383 Because pamrgbatopng had no options, pamtopng was backward compatible
385 with it without even trying. Therefore, as soon as we added pamtopng
386 to Netpbm, we removed pamrgbatopng and recommended that pamrgbatopng be
387 installed as an alias for pamtopng.
388
392 Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
393 Copyright (C) 2015 by Willem van Schaik.
394
396 This manual page was generated by the Netpbm tool 'makeman' from HTML
397 source. The master documentation is at
398 http://netpbm.sourceforge.net/doc/pamtopng.html
400netpbm documentation 13 March 2019 Pamtopng User Manual(0)