1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.3//EN">
<html><head><title>Pamtopng User Manual</title></head>
<body>
<h1>pamtopng</h1>
Updated: 13 March 2019
<br>
<a href="#index">Table Of Contents</a>
<h2>NAME</h2>
pamtopng - convert a Netpbm image to PNG
<h2 id="synopsis">SYNOPSIS</h2>
<b>pamtopng</b>
[<b>-verbose</b>]
[<b>-transparent=</b><i>color</i>]
[<b>-background=</b><i>color</i>]
[<b>-gamma=</b><i>value</i>]
[<b>-chroma="</b><i>wx</i> <i>wy</i>
<i>rx</i> <i>ry</i> <i>gx</i> <i>gy</i> <i>bx</i> <i>by</i><b>"</b>]
[<b>-srgbintent=</b><i>intent</i>]
[<b>-time=</b>[<i>yy</i>]<i>yy</i><b>-</b><i>mm</i><b>-</b><i>dd</i>
<i>hh</i><b>:</b><i>mm</i><b>:</b><i>ss</i>]
[<b>-text=</b><i>file</i>]
[<b>-ztxt=</b><i>file</i>]
[<b>-itxt=</b><i>file</i>]
[<b>-interlace</b>]
[<i>pnmfile</i>]
<?makeman .SH OPTION USAGE ?>
<p>Minimum unique abbreviation of option is acceptable. You may use double
hyphens instead of a single hyphen to denote options. You may use white space
in place of the equals sign to separate an option name from its value.
<h2 id="description">DESCRIPTION</h2>
<p>This program is part of <a href="index.html">Netpbm</a>.
<p><b>pamtopng</b> reads a Netpbm image as input and produces a PNG image as
output.
<p>Color component values in PNG files are either 8 or 16 bits wide, so where
necessary <b>pamtopng</b> scales colors to have a maxval of 255 or 65535.
In that case, it will add an sBIT chunk to indicated the original bit-depth.
<p><b>pamtopng</b> works only on images with maxval 1, 3, 15, 255, or 65535.
You can use <b>pamdepth</b> to convert an image with some other maxval to one
of these.
<p><b>pamtopng</b> produces a color PNG from a color PAM, even if the
only colors in the image are shades of gray. To create a graycale PNG,
from such an image (which might be slightly smaller), you can use other
Netpbm programs to convert the input to grayscale.
<h3 id="pnmtopng">Alternative: <b>pnmtopng</b></h3>
<p>Netpbm contains another program for generating PNG images: <b>pnmtopng</b>.
<b>pnmtopng</b> is a much older program - it is in fact the first program in
the world that could generate a PNG. <b>pnmtopng</b> is a complex,
feature-laden program. It lets you control various arcane aspects of the
conversion and create PNGs with various arcane features. It does various
transformations on the image to create the greatest compression possible, to a
degree that probably doesn't make any difference in the modern world.
<p>The main advantage <b>pamtopng</b> has over <b>pnmtopng</b> is that the
former can use the transparency channel of a PAM image to generate the
transparency information in the PNG. In contrast, handling of the alpha
channel is very cumbersome with <b>pnmotpng</b>.
<p>One difference that <em>does not</em> exist, that some people might
incorrectly infer from the names is the possible input formats. Both programs
can take PBM, PGM, PPM, and PAM input.
<p>Because <b>pnmtopng</b> has been around virtually forever, programs and
procedures that use it are more portable than those that use <b>pamtopng</b>.
Its age and popularity also probably make it have fewer bugs.
<p><b>pamtopng</b> does not have any way to do what the following do in
<b>pnmtopng</b>:
<ul>
<li><b>-palette</b>
<li><b>-history</b>
<li><b>-filter</b>
<li><b>-size</b>
<li><b>-paeth</b>
<li><b>-hist</b>
<li><b>-nofilter</b>
<li><b>-sub</b>
<li><b>-up</b>
<li><b>-avg</b>
<li><b>-force</b>
<li><b>-libversion</b>
<li><b>-compression</b>
<li><b>-comp_</b><i>xxx</i>
</ul>
<p>These are some of the other functions of <b>pnmtopng</b> that
<b>pamtopng</b> lacks:
<ul>
<li>When you specify a transparent or background color that is not in the
image, <b>pnmtopng</b> can optionally choose the closest one that is in the
image. <b>pamtopng</b> always uses the exact color you specify.
</ul>
<p>Features that exist in both programs are controlled by largely the same
command syntax. But there are these differences:
<ul>
<li><b>pnmtopng</b>'s <b>-rgb</b> option is <b>-chroma</b> in <b>pamtopng</b>.
<b>-chroma</b> is a better name, and in fact was the name that <b>pnmtopng</b>
used originally, but we had to change it when we had to change the syntax
of the option value to conform to the rest of Netpbm.
<li><b>pnmtopng</b>'s <b>-modtime</b> option is <b>-time</b> in
<b>pamtopng</b>. The origin of <b>-modtime</b> is analogous to that of
<b>-rgb</b>.
</ul>
<h2 id="options">OPTIONS</h2>
<p>In addition to the options common to all programs based on libnetpbm
(most notably <b>-quiet</b>, see <a href="index.html#commonoptions">
Common Options</a>), <b>pamtopng</b> recognizes the following
command line options:
<dl compact>
<dt><b>-transparent=</b><i>color</i>
<dd>
<b>pamtopng</b> marks the specified color as transparent in the PNG image --
Every pixel of this color is fully transparent. This causes <b>pamtopng</b> to
include a tRNS chunk in the image identifying that color.
<p>Specify the color (<i>color</i>) as described for
the <a href="libnetpbm_image.html#colorname">argument of the <b>pnm_parsecolor()</b>
library routine</a>. E.g. <b>red</b> or <b>rgb:ff/00/0d</b>.
<dt><b>-background=</b><i>color</i>
<dd>
This causes <b>pamtopng</b> to create a background color chunk in the PNG
output which can be used for subsequent transparency channel or transparent
color conversions. Specify <i>color</i> the same as for <b>-transparent</b>.
<p>
<dt><b>-gamma=</b><i>value</i>
<dd>This causes <b>pamtopng</b> to create a gAMA chunk. This information
helps describe how the color values in the PNG must be interpreted. Without
the gAMA chunk, whatever interprets the PNG must get this information
separately (or just assume something standard). If your input is a true PPM
or PGM image, you should specify <b>-gamma=.45</b>. But sometimes people
generate images which are ostensibly PPM except the image uses a different
gamma transfer function than the one specified for PPM. A common case of this
is when the image is created by simple hardware that doesn't have digital
computational ability. Also, some simple programs that generate images from
scratch do it with a gamma transfer in which the gamma value is 1.0.
<p>
<dt><b>-chroma=</b><i>chroma_list</i>
<dd>This option specifies how red, green, and blue component values
of a pixel specify a particular color, by telling the chromaticities
of those 3 primary illuminants and of white (i.e. full strength of
all three).
<p>The <i>chroma_list</i> value is a blank-separated list of 8 floating
point decimal numbers. The CIE-1931 X and Y chromaticities (in that
order) of each of white, red, green, and blue, in that order.
<p>This information goes into the PNG's cHRM chunk.
<p>In a shell command, make sure you use quotation marks so that the
blanks in <i>chroma_list</i> don't make the shell see multiple command
arguments.
<dt><b>-srgbintent=</b><i>intent</i>
<dd>This asserts that the input is a pseudo-Netpbm image that uses an
sRGB color space (unlike true Netpbm) and indicates how you intend for the
colors to be rendered. It causes <b>pamtopng</b> to include an sRGB chunk
in the PNG image that specifies that intent, so see the PNG documentation for
more information on what this really means.
<p><i>intent</i> is one of:
<ul>
<li><b>perceptual</b>
<li><b>relativecolorimetric</b>
<li><b>saturation</b>
<li><b>absolutecolorimetric</b>
</ul>
<dt><b>-text=</b><i>filename</i>
<dd>
This option lets you include arbitrary text strings in the PNG output, as tEXt
chunks.
<i>filename</i> is the name of a file that contains your text strings.
<p>The output contains a distinct tEXt chunk for each entry in the file.
<p>Here is an example of a text string file:
<pre>
Title PNG file
Author John Doe
Description how to include a text chunk
PNG file
"Creation Date" 2015-may-11
Software pamtopng
</pre>
<p>The file is divided into entries, each entry comprising consecutive lines
of text. The first line of an entry starts in the first column (i.e. the
first column is not white space) and every other line has white space in the
first column. The first entry starts in the first line, so it is not valid
for the first line of the file to have white space in its first column.
<p>The first word in an entry is the key of the text string
(e.g. "Title"). It begins in column one of the line and continues
up to, but not including, the first delimiter character or the end of the
line, whichever is first. You can enclose the key in double quotes in
which case the key can consists of multiple words. The quotes are not
part of the key. The text string per se begins after the key and any
delimiter characters after it, plus the text in subsequent continuation lines.
<p>There is no limit on the length of a file line or entry or key or text
string. There is no limit on the number of entries.
<dt><b>-ztxt=</b><i>filename</i>
<dd>The same as <b>-text</b>, except the text string is compressed in the
PNG output. <b>pamtopng</b> uses zTXt chunks instead of a tEXt chunks.
<p>
<dt><b>-itxt=</b><i>filename</i>
<dd>Similar to <b>-text</b>, but the text strings can be in a language other
than English. The PNG image indicates what language that is and includes the
text string key both in English and that language. <b>pamtopng</b> uses
iTXt chunks instead of tEXt chunks.
<p>For each record, you must specify the language and give the key both in
English and in the text string language.
<p>Example:
<pre>
Language nl-NL Taal nl-NL
Title nl-NL Titel PNG file
Author nl-NL Auteur Pietje Puk
Description nl-NL Omschrijving Tekst in het Nederlands.
</pre>
<p>The language specification is based on the ISO 639-1 standard, see
http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes for the valid codes.
The format is either a two character "nl" or an extended code like "en-US".
<dt><b>-time="</b>[<i>yy</i>]<i>yy-mm-dd hh:mm:ss</i><b>"</b>
<dd>This option allows you to specify the modification time value to be placed
in the PNG output. You can specify the year parameter either as a two or four
digit value.
<p>
<dt><b>-interlace</b>
<dd>
This causes the PNG file to be interlaced, in Adam7 format. The interlaced
format is one in which the raster data starts with a low-resolution
representation of the entire image, then continues with additional information
for the entire image, then even more information, etc. In Adam7 in
particular, there are seven such passes of the whole image. This is useful
when you are receiving the image over a slow communication line as someone is
waiting to see it. The simplest thing to do in that case is wait for the
entire image to arrive and then display it instantly, but then the user is
wasting time staring at a blank space until the whole image arrives. With the
standard non-interlaced format, the data arrives row-by-row starting at the
top, so the displayer could display each row of the image as it arrives and
gradually paint down to the bottom. But with an interlaced image, the
displayer can start by showing a low-resolution version of the image, then
gradually improve the display as more data arrives.
<p>When you specify this option, <b>pamtopng</b> must hold the entire image in
memory at once, whereas without it, the program holds only one raster row at a
time. If you don't have enough memory for that, you might suffer extreme
slowdowns or failure - not just in the process running <b>pamtopng</b>, but
potentially throughout the system that shares memory with it. <b>pnmtopng</b>
does not have this limitation (it holds only one row at a time in memory even
when generating an interlaced PNG).
<p>This option was new in Netpbm 10.86 (March 2019).
<dt><b>-verbose</b>
<dd>
This causes the program to display various facts about the conversion.
<p>
</dl>
<h2 id="seealso">SEE ALSO</h2>
<a href="pngtopam.html">pngtopam</a>,
<a href="pnmtopng.html">pnmtopng</a>,
<a href="pam.html">pam</a>,
<a href="pnm.html">pnm</a>
<p>For information on the PNG format, see
<a href="http://www.w3.org/TR/PNG/">http://www.w3.org/TR/PNG/</a>,
<a href="http://libpng.org/pub/png/">http://libpng.org/pub/png/</a>,
<a href="http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes</a> and
<a href="http://schaik.com/png/">http://schaik.com/png/</a>.
<h2 id="history">HISTORY</h2>
<p><b>pamtopng</b> was new in Netpbm 10.70 (June 2015).
<p>Before <b>pamtopng</b>, the two ways to create PNG images with Netpbm
were <b>pnmtopng</b> and <b>pamrgbatopng</b>. The history of the former is
discussed above. The latter was added to Netpbm in 2005 as a cheap way to
fill a significant need that <b>pnmtopng</b> did not: the ability to turn the
alpha channel in a PAM image into the alpha channel in a PNG image.
<p>Handling of the alpha channel with <b>pnmtopng</b> is very cumbersome (as
was dealing with alpha channels in general before the introduction of the PAM
format). <b>pamrgbatopng</b> could do what people wanted with the alpha
channel, but nothing else. It was a very small program with literally no
command line options.
<p>The goal in those days was eventually to expand <b>pnmtopng</b> to do the
PAM alpha channel thing, rename it to <b>pamtopng</b>, and retire
<b>pamrgbatopng</b>. But <b>pnmtopng</b> is such a complex program, because
of its dizzying array of features and its need for backward compatibility,
that adding that one capability to it was a daunting task and for ten years
nobody attempted it.
<p>In 2015, one of the authors of the original <b>pnmtopng</b> (from before it
was even part of Netpbm -- a program that shared essentially no lines of code
with <b>pnmtopng</b> of 2015) decided to go in a different direction. While
many features of <b>pnmtopng</b> were pretty important and easy to implement,
many others were probably of no use in the modern world or at least not
important enough to justify the complexity they lent to the code. (The
features thought to be outdated were ones that were intended to make the PNG
output slightly smaller - something considerably less important with the
declining cost of computer resources).
<p>And there was an opportunity to drop those features: We could use the new
name "pamtopng" for a new program, keep the existing program under
the name "pnmtopng", and avoid most backward compatibility trouble.
<p>Therefore, Willem van Schaik wrote an intermediate level program that had
all the most important features of <b>pnmtopng</b>, plus the alpha channel
handling of <b>pamrgbatopng</b>, with nice, simple code. That was
<b>pamtopng</b>.
<p>Because <b>pamrgbatopng</b> had no options, <b>pamtopng</b> was backward
compatible with it without even trying. Therefore, as soon as we
added <b>pamtopng</b> to Netpbm, we removed <b>pamrgbatopng</b> and
recommended that <b>pamrgbatopng</b> be installed as an alias for
<b>pamtopng</b>.
<h2 id="author">AUTHOR</h2>
Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
<br>
Copyright (C) 2015 by Willem van Schaik.
<hr>
<h2 id="index">Table Of Contents</h2>
<ul>
<li><a href="#synopsis">SYNOPSIS</a>
<li><a href="#description">DESCRIPTION</a>
<ul>
<li><a href="#pnmtopng">Alternative: pnmtopng</a>
</ul>
<li><a href="#options">OPTIONS</a>
<li><a href="#seealso">SEE ALSO</a>
<li><a href="#history">HISTORY</a>
<li><a href="#author">AUTHOR</a>
</ul>
</body>
</html>
|
