Debian Codegraph @

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