Debian Codegraph @

upstream/debian-unstable/man1/pnmtopng.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 "Pnmtopng User Manual" 1 "13 March 2019" "netpbm documentation"
7
8 .SH NAME
9 pnmtopng - convert a PNM image to PNG
10
11 .UN synopsis
12 .SH SYNOPSIS
13
14 \fBpnmtopng\fP
15 [\fB-verbose\fP]
16 [\fB-downscale\fP]
17 [\fB-interlace\fP]
18 [\fB-alpha=\fP\fIfile\fP]
19 [\fB-transparent=\fP[\fB=\fP]\fIcolor\fP]
20 [\fB-background=\fP\fIcolor\fP]
21 [\fB-palette=\fP\fIpalettefile\fP]
22 [\fB-gamma=\fP\fIvalue\fP]
23 [\fB-hist\fP]
24 [\fB-text=\fP\fIfile\fP]
25 [\fB-ztxt=\fP\fIfile\fP]
26 [\fB-rgb='\fP\fIwx\fP \fIwy\fP
27 \fIrx\fP \fIry\fP \fIgx\fP \fIgy\fP \fIbx\fP \fIby\fP\fB'\fP]
28 [\fB-size='\fP\fIx\fP \fIy\fP \fIunit\fP\fB'\fP]
29 [\fB-srgbintent=\fP\fIintent\fP]
30 [\fB-modtime='\fP[\fIyy\fP]\fIyy\fP\fB-\fP\fImm\fP\fB-\fP\fIdd\fP
31 \fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP\fB'\fP]
32 [\fB-nofilter\fP]
33 [\fB-sub\fP]
34 [\fB-up\fP]
35 [\fB-avg\fP]
36 [\fB-paeth\fP]
37 [\fB-compression=\fP\fIn\fP]
38 [\fB-comp_mem_level=\fP\fIn\fP]
39 [\fB-comp_strategy=\fP{\fBhuffman_only\fP|\fBfiltered\fP}]
40 [\fB-comp_method=\fP\fBdeflated\fP]
41 [\fB-comp_window_bits=\fP\fIn\fP]
42 [\fB-comp_buffer_size=\fP\fIn\fP]
43 [\fB-force\fP]
44 [\fB-libversion\fP]
45 [\fIpnmfile\fP]
46
47
48 .SH OPTION USAGE
49 .PP
50 Obsolete options:
51 .PP
52 [\fB-filter \fP\fIn\fP]
53 .PP
54 Options available only in older versions:
55 .PP
56 [\fB-chroma\fP \fIwx wy rx ry gx gy bx by\fP]
57 [\fB-phys\fP \fIx\fP \fIy\fP \fIunit\fP]
58 [\fB-time \fP[\fIyy\fP]\fIyy\fP\fB-\fP\fImm\fP\fB-\fP\fIdd\fP
59 \fIhh\fP\fB:\fP\fImm\fP\fB:\fP\fIss\fP]
60 .PP
61 Minimum unique abbreviation of option is acceptable. You may use double
62 hyphens instead of single hyphen to denote options. You may use white
63 space in place of the equals sign to separate an option name from its value.
64
65 .UN description
66 .SH DESCRIPTION
67 .PP
68 This program is part of
69 .BR "Netpbm" (1)\c
70 \&.
71 .PP
72 \fBpnmtopng\fP reads a PNM image as input and produces a PNG image as
73 output.
74 .PP
75 Color component values in PNG files are either eight or sixteen
76 bits wide, so \fBpnmtopng\fP will automatically scale colors to have
77 a maxval of 255 or 65535.
78 .PP
79 For a grayscale image, \fBpnmtopng\fP produces a PNG bit depth 1,
80 2, 4, 8 or 16. When the input image has a small maxval, the output
81 PNG image has a correspondingly small bit depth. But in mapping the
82 PNM maxval to the PNG maxval (which is by definition the maximum value
83 that can be represented in the number of bits), a fair amount of
84 distortion happens with these low maxvals. For example, with a PNM
85 maxval of 5 and a PNG maxval of 7, the input sample 2 becomes the
86 output sample 3. The input brightness is 2/5 = .40, while the output
87 brightness is 3/7 = .43. Note that this is not a problem if you view
88 the maxval as a precision, because in .4 and .43 are identical within
89 the precision implied by maxval 5. Indeed, if you convert this PNG
90 back to a maxval 5 PGM, the pixel's value will again be 2, exactly as
91 it was originally. But if you need precisely the same colors in the
92 output PNG as in the input PNM, make sure your input PNM has a maxval
93 which is a power of two minus one. If you can't do that, then convert
94 it with \fBpamdepth\fP to something with a large maxval that is a
95 power of two minus one (255 and 65535 are good choices) to minimize
96 the error.
97
98
99 .UN options
100 .SH OPTIONS
101
102 .UN notesyntax
103 .SS Note: Option Syntax of Older Versions
104 .PP
105 \fBpnmtopng\fP changed in Netpbm 10.30 (October 2005) to use the
106 standard Netpbm command line syntax. Before that, you could not
107 use double hyphens to denote an option and could not use an equal
108 sign to separate an option name from its value. And the options had
109 to come before the non-option program arguments.
110 .PP
111 Furthermore, the options \fB-chroma\fP, \fB-phys\fP, and
112 \fB-time\fP were replaced by \fB-rgb\fP, \fB-size\fP, and
113 \fB-modtime\fP, respectively. The only difference, taking
114 \fB-phys\fP/\fB-size\fP as an example, is that \fB-phys\fP takes
115 multiple program arguments as the option argument, whereas \fB-size\fP
116 takes a single program argument which is composed of multiple words.
117 E.g. the old shell command
118
119 .nf
120 \f(CW
121 pnmtopng -phys 800 800 0 input.pnm > output.png
122 \fP
123
124 .fi
125 .PP
126 is equivalent to the new shell command
127
128 .nf
129 \f(CW
130 pnmtopng -size "800 800 0" input.pnm > output.png
131 \fP
132
133 .fi
134 .PP
135 If you're writing a program that needs to work with both new and old
136 , have it first try with the new syntax, and if it fails
137 with "unrecognized option," fall back to the old syntax.
138
139 .UN curroptions
140 .SS Current Options
141 .PP
142 In addition to the options common to all programs based on libnetpbm
143 (most notably \fB-quiet\fP, see
144 .UR index.html#commonoptions
145 Common Options
146 .UE
147 \&), \fBpnmtopng\fP recognizes the following
148 command line options:
149
150
151 .TP
152 \fB-verbose\fP
153 This causes \fBpnmtopng\fP to display information about the format of the
154 output file.
155 .sp
156 \
157
158 .TP
159 \fB-downscale\fP
160 This enables \fBpnmtopng\fP to scale maxvalues of more then 65535 to 16
161 bits. Since this means loss of image data, \fBpnmtopng\fP does not do it by
162 default.
163 .sp
164 \
165
166 .TP
167 \fB-interlace\fP
168 This causes the PNG file to be interlaced, in Adam7 format. The interlaced
169 format is one in which the raster data starts with a low-resolution
170 representation of the entire image, then continues with additional information
171 for the entire image, then even more information, etc. In Adam7 in
172 particular, there are seven such passes of the whole image. This is useful
173 when you are receiving the image over a slow communication line as someone is
174 waiting to see it. The simplest thing to do in that case is wait for the
175 entire image to arrive and then display it instantly, but then the user is
176 wasting time staring at a blank space until the whole image arrives. With the
177 standard non-interlaced format, the data arrives row-by-row starting at the
178 top, so the displayer could display each row of the image as it arrives and
179 gradually paint down to the bottom. But with an interlaced image, the
180 displayer can start by showing a low-resolution version of the image, then
181 gradually improve the display as more data arrives.
182 .sp
183 \
184
185 .TP
186 \fB-alpha=\fP\fIfilename\fP
187 This specifies the transparency (alpha) channel of the image. You supply
188 the transparency channel as a standard PGM transparency mask (see
189 the
190 .BR "PGM" (1)\c
191 \& specification. \fBpnmtopng\fP does not
192 necessarily represents the transparency information as a transparency channel
193 in the PNG format. If it can represent the transparency information through a
194 palette, it will do so in order to make a smaller PNG file.
195 \fBpnmtopng\fP even sorts the palette so it can omit the opaque colors
196 from the transparency part of the palette and save space for the palette.
197 .sp
198 \
199
200 .TP
201 \fB-transparent=\fP\fIcolor\fP
202 \fBpnmtopng\fP marks the specified color as transparent in the PNG image.
203 .sp
204 Specify the color (\fIcolor\fP) as described for the
205 .UR libnetpbm_image.html#colorname
206 argument of the \fBpnm_parsecolor()\fP library routine
207 .UE
208 \&.
209 E.g. \fBred\fP or
210 \fBrgb:ff/00/0d\fP. If the color you specify is not present in the
211 image, \fBpnmtopng\fP selects instead the color in the image that is
212 closest to the one you specify. Closeness is measured as a Cartesian
213 distance between colors in RGB space. If multiple colors are
214 equidistant, \fBpnmtopng\fP chooses one of them arbitrarily.
215 .sp
216 However, if you prefix your color specification with
217 "=", e.g.
218
219 .nf
220 \f(CW
221 -transparent =red
222 \fP
223
224 .fi
225 .sp
226 only the exact color you specify will be transparent. If that
227 color does not appear in the image, there will be no transparency.
228 \fBpnmtopng\fP issues an information message when this is the case.
229
230 .TP
231 \fB-background=\fP\fIcolor\fP
232 Causes \fBpnmtopng\fP to create a background color chunk in the PNG output
233 which can be used for subsequent transparency channel or transparent color
234 conversions. Specify \fIcolor\fP the same as for \fB-transparent\fP.
235 .sp
236 \
237
238 .TP
239 \fB-palette=\fP\fIpalettefile\fP
240 This option specifies a palette to use in the PNG. It forces
241 \fBpnmtopng\fP to create the paletted (colormapped) variety of PNG --
242 if that isn't possible, \fBpnmtopng\fP fails. If the palette you
243 specify doesn't contain exactly the colors in the image,
244 \fBpnmtopng\fP fails. Since \fBpnmtopng\fP will automatically
245 generate a paletted PNG, with a correct palette, when appropriate, the
246 only reason you would specify the \fB-palette\fP option is if you care
247 in what order the colors appear in the palette. The PNG palette has colors
248 in the same order as the palette you specify.
249 .sp
250 You specify the palette by naming a PPM file that has one pixel for
251 each color in the palette.
252 .sp
253 Alternatively, consider the case that have a palette and you want
254 to make sure your PNG contains only colors from the palette,
255 approximating if necessary. You don't care what indexes the PNG uses
256 internally for the colors (i.e. the order of the PNG palette). In
257 this case, you don't need \fB-palette\fP. Pass the Netpbm input
258 image and your palette PPM through \fBpnmremap\fP. Though you might
259 think it would, using \fB-palette\fP in this case wouldn't even save
260 \fBpnmtopng\fP any work.
261
262 .TP
263 \fB-gamma=\fP\fIvalue\fP
264 Causes \fBpnmtopng\fP to create a gAMA chunk. This information helps
265 describe how the color values in the PNG must be interpreted. Without
266 the gAMA chunk, whatever interprets the PNG must get this information
267 separately (or just assume something standard). If your input is a true
268 PPM or PGM image, you should specify \fB-gamma=.52\fP. But sometimes
269 people generate images which are ostensibly PPM except the image uses a
270 different gamma transfer function than the one specified for PPM. A common
271 case of this is when the image is created by simple hardware that doesn't
272 have digital computational ability. Also, some simple programs that generate
273 images from scratch do it with a gamma transfer in which the gamma value is
274 1.0.
275 .sp
276 \
277
278 .TP
279 \fB-hist\fP
280 Use this parameter to create a chunk that specifies the frequency
281 (or histogram) of the colors in the image.
282 .sp
283 \
284
285 .TP
286 \fB-text=\fP\fIfilename\fP
287 This option lets you include arbitrary text strings in the PNG output, as tEXt
288 chunks.
289 .sp
290 \fIfilename\fP is the name of a file that contains your text strings.
291 .sp
292 The output contains a distinct tEXt chunk for each entry in the file.
293 .sp
294 Here is an example of a text string file:
295
296 .nf
297 Title PNG file
298 Author John Doe
299 Description how to include a text chunk
300 PNG file
301 "Creation Date" 2015-may-11
302 Software pamtopng
303
304 .fi
305 .sp
306 The file is divided into entries, each entry comprising consecutive lines
307 of text. The first line of an entry starts in the first column (i.e. the
308 first column is not white space) and every other line has white space in the
309 first column. The first entry starts in the first line, so it is not valid
310 for the first line of the file to have white space in its first column.
311 .sp
312 The first word in an entry is the key of the text string
313 (e.g. 'Title'). It begins in column one of the line and continues
314 up to, but not including, the first delimiter character or the end of the
315 line, whichever is first. You can enclose the key in double quotes in
316 which case the key can consists of multiple words. The quotes are not
317 part of the key. The text string per se begins after the key and any
318 delimiter characters after it, plus the text in subsequent continuation lines.
319 .sp
320 There is no limit on the length of a file line or entry or key or text
321 string. There is no limit on the number of entries.
322
323 .TP
324 \fB-ztxt=\fP\fIfilename\fP
325 The same as \fB-text\fP, except the text string is compressed in the PNG
326 output. \fBpnmtopng\fP uses zTXt chunks instead of a tEXt chunks, unless the
327 key for the text string starts with 'A' or 'T'. This
328 odd exception exists for backward compatibility; we don't know why the program
329 was originally designed this way, except that the distinction was meant to
330 roughly identify the keys 'Author' and 'Title'.
331 .sp
332 \
333
334 .TP
335 \fB-rgb=\fP\fIchroma_list\fP
336 This option specifies how red, green, and blue component values
337 of a pixel specify a particular color, by telling the chromaticities
338 of those 3 primary illuminants and of white (i.e. full strength of
339 all three).
340 .sp
341 The \fIchroma_list\fP value is a blank-separated list of 8 floating
342 point decimal numbers: the CIE-1931 X and Y chromaticities (in that
343 order) of each of white, red, green, and blue, in that order.
344 .sp
345 This information goes into the PNG's cHRM chunk.
346 .sp
347 In a shell command, make sure you use quotation marks so that the
348 blanks in \fIchroma_list\fP don't make the shell see multiple command
349 arguments.
350 .sp
351 This option was new in Netpbm 10.30 (October 2005). Before that,
352 the option \fB-chroma\fP does the same thing, but with slightly
353 different syntax.
354
355 .TP
356 \fB-size="\fP\fIx\fP \fIy\fP \fIunit\fP\fB"\fP
357 This option determines the aspect ratio of the individual pixels
358 of your image as well as the physical resolution of it.
359 .sp
360 \fIunit\fP is either \fB0\fP or \fI1\fP. When it is \fI1\fP,
361 the option specifies the physical resolution of the image in pixels
362 per meter. For example, \fB-size="10000 15000 1"\fP means
363 that when someone displays the image, he should make it so that 10,000
364 pixels horizontally occupy 1 meter and 15,000 pixels vertically occupy
365 one meter. And even if he doesn't take this advice on the overall
366 size of the displayed image, he should at least make it so that each
367 pixel displays as 1.5 times as high as wide.
368 .sp
369 When \fIunit\fP is \fB0\fP, that means there is no advice on
370 the absolute physical resolution; just on the ratio of horizontal to
371 vertical physical resolution.
372 .sp
373 This information goes into the PNG's pHYS chunk.
374 .sp
375 When you don't specify \fB-size\fP, \fBpnmtopng\fP creates the image
376 with no pHYS chunk, which means square pixels of no absolute resolution.
377 .sp
378 This option was new in Netpbm 10.30 (October 2005). Before that,
379 the option \fB-phys\fP does the same thing, but with slightly
380 different syntax.
381
382 .TP
383 \fB-srgbintent=\fP\fIintent\fP
384 This asserts that the input is a pseudo-Netpbm image that uses an
385 sRGB color space (unlike true Netpbm) and indicates how you intend for the
386 colors to be rendered. It causes \fBpnmtopng\fP to include an sRGB chunk
387 in the PNG image that specifies that intent, so see the PNG documentation for
388 more information on what this really means.
389 .sp
390 \fIintent\fP is one of:
391
392
393 .IP \(bu
394 \fBperceptual\fP
395 .IP \(bu
396 \fBrelativecolorimetric\fP
397 .IP \(bu
398 \fBsaturation\fP
399 .IP \(bu
400 \fBabsolutecolorimetric\fP
401
402 .sp
403 This option was new in Netpbm 10.71 (June 2015). Before that,
404 \fBpnmtopng\fP never generates an sRGB chunk.
405
406 .TP
407 \fB-modtime="\fP[\fIyy\fP]\fIyy-mm-dd hh:mm:ss\fP\fB"\fP
408 This option allows you to specify the modification time value to
409 be placed in the PNG output. You can specify the year parameter
410 either as a two digit or four digit value.
411 .sp
412 This option was new in Netpbm 10.30 (October 2005). Before that,
413 the option \fB-time\fP does the same thing, but with slightly
414 different syntax.
415
416 .TP
417 \fB-filter=\fP\fIn\fP
418 This option is obsolete. Before Netpbm 10.22 (April 2004), this was
419 the only way to specify a row filter. It specifies a single type of
420 row filter, by number, that \fBpnmtopng\fP must use on each row.
421 .sp
422 Use \fB-nofilter\fP, \fB-sub\fP, \fB-up\fP, \fB-avg\fP, and
423 \fB-paeth\fP in current Netpbm.
424
425 .TP
426 \fB-nofilter\fP
427 .TP
428 \fB-sub\fP
429 .TP
430 \fB-up\fP
431 .TP
432 \fB-avg\fP
433 .TP
434 \fB-paeth\fP
435 Each of these options permits \fBpnmtopng\fP to use one type of
436 row filter. \fBpnmtopng\fP chooses whichever of the permitted
437 filters it finds to be optimal. If you specify none of these options,
438 it is the same as specifying all of them -- \fBpnmtopng\fP uses any
439 row filter type it finds optimal.
440 .sp
441 These options were new with Netpbm 10.22 (April 2004). Before that,
442 you could use the \fB-filter\fP option to specify one permitted row
443 filter type. The default, when you specify no filter options, was the
444 same.
445
446 .TP
447 \fB-compression=\fP\fIn\fP
448 This option sets set the compression level of the zlib
449 compression. Select a level from 0 for no compression (maximum speed)
450 to 9 for maximum compression (minimum speed).
451 .sp
452 The default is the default of the zlib library.
453
454 .TP
455 \fB-comp_mem_level=\fP\fIn\fP
456 This option sets the memory usage level of the zlib compression.
457 Select a level from 1 for minimum memory usage (and minimum speed) to
458 9 for maximum memory usage (and speed).
459 .sp
460 The default is the default of the zlib library.
461 .sp
462 This option was new in Netpbm 10.30 (October 2005).
463
464 .TP
465 \fB-comp_strategy=\fP{\fBhuffman_only\fP|\fBfiltered\fP}
466 This options sets the compression strategy of the zlib compression.
467 See Zlib documentation for information on what these strategies are.
468 .sp
469 The default is the default of the zlib library.
470 .sp
471 This option was new in Netpbm 10.30 (October 2005).
472
473 .TP
474 \fB-comp_method=\fP\fBdeflated\fP
475 This option does nothing. It is here for mathematical
476 completeness and for possible forward compatibility. It theoretically
477 selects the compression method of the zlib compression, but the Z
478 library knows only one method today, so there's nothing to choose.
479 .sp
480 The default is the default of the zlib library.
481 .sp
482 This option was new in Netpbm 10.30 (October 2005).
483
484 .TP
485 \fB-comp_window_bits=\fP\fIN\fP
486 This option tells how big a window the zlib compression algorithm
487 uses. The value is the base 2 logarithm of the window size in bytes,
488 so 8 means 256 bytes. The value must be from 8 to 15 (i.e. 256 bytes
489 to 32K).
490 .sp
491 See Zlib documentation for details on what this window size is.
492 .sp
493 The default is the default of the zlib library.
494 .sp
495 This option was new in Netpbm 10.30 (October 2005).
496
497 .TP
498 \fB-comp_buffer_size\fP=\fIN\fP
499 This option determines in what size pieces \fBpnmtopng\fP does the
500 zlib compression. One compressed piece goes in each IDAT chunk in the
501 PNG. So the bigger this value, the fewer IDAT chunks your PNG will have.
502 Theoretically, this makes the PNG smaller because 1) you have less
503 per-IDAT-chunk overhead, and 2) the compression algorithm has more data
504 to work with. But in reality, the difference will probably not be
505 noticeable above about 8K, which is the default.
506 .sp
507 The value \fIn\fP is the size of the compressed piece (i.e. the
508 compression buffer) in bytes.
509 .sp
510 This option was new in Netpbm 10.30 (October 2005).
511
512
513 .TP
514 \fB-force\fP
515 When you specify this, \fBpnmtopng\fP limits its optimizations. The
516 resulting PNG output is as similar to the Netpbm input as possible. For
517 example, the PNG output will not be paletted and the transparency channel will
518 be represented as a full transparency channel even if the information could be
519 represented more succinctly with a transparency chunk.
520 .sp
521 \
522
523 .TP
524 \fB-libversion\fP
525 This option causes \fBpnmtopng\fP to display version information
526 about itself and the libraries it uses, \fBin addition to all its
527 normal function\fP. Do not confuse this with the Netpbm common
528 option \fB-version\fP, which causes the program to display version
529 information about the Netpbm library and do nothing else.
530 .sp
531 You can't really use this option in a program that invokes
532 \fBpnmtopng\fP and needs to know which version it is. Its function
533 has changed too much over the history of \fBpnmtopng\fP. The option
534 is good only for human eyes.
535
536
537
538 .UN seealso
539 .SH SEE ALSO
540 .BR "pngtopam" (1)\c
541 \&,
542 .BR "pamtopng" (1)\c
543 \&,
544 .BR "pnmremap" (1)\c
545 \&,
546 .BR "pnmgamma" (1)\c
547 \&,
548 .BR "pnm" (1)\c
549 \&
550 .PP
551 For information on the PNG format, see
552 .UR http://schaik.com/png
553 http://schaik.com/png
554 .UE
555 \&.
556
557 .UN author
558 .SH AUTHOR
559
560 Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
561 .SH DOCUMENT SOURCE
562 This manual page was generated by the Netpbm tool 'makeman' from HTML
563 source. The master documentation is at
564 .IP
565 .B http://netpbm.sourceforge.net/doc/pnmtopng.html
566 .PP