Pamtopng User Manual(1) General Commands Manual Pamtopng User Manual(1)
NAME
pamtopng - convert a Netpbm image to PNG
SYNOPSIS
pamtopng [-verbose] [-transparent=color] [-background=color]
[-gamma=value] [-chroma='wx wy
rx ry gx gy bx by'] [-srgbintent=intent] [-time=[yy]yy-mm-dd
hh:mm:ss] [-text=file] [-ztxt=file] [-itxt=file] [-interlace] [pnm-
file]
OPTION USAGE
Minimum unique abbreviation of option is acceptable. You may use dou-
ble 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.
DESCRIPTION
This program is part of Netpbm(1).
pamtopng reads a Netpbm image as input and produces a PNG image as out-
put.
Color component values in PNG files are either 8 or 16 bits wide, so
where necessary pamtopng scales colors to have a maxval of 255 or
65535. In that case, it will add an sBIT chunk to indicated the origi-
nal bit-depth.
pamtopng works only on images with maxval 1, 3, 15, 255, or 65535. You
can use pamdepth to convert an image with some other maxval to one of
these.
pamtopng 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.
Alternative: pnmtopng
Netpbm contains another program for generating PNG images: pnmtopng.
pnmtopng is a much older program - it is in fact the first program in
the world that could generate a PNG. pnmtopng is a complex, feature-
laden program. It lets you control various arcane aspects of the con-
version and create PNGs with various arcane features. It does various
transformations on the image to create the greatest compression possi-
ble, to a degree that probably doesn't make any difference in the mod-
ern world.
The main advantage pamtopng has over pnmtopng is that the former can
use the transparency channel of a PAM image to generate the transpar-
ency information in the PNG. In contrast, handling of the alpha chan-
nel is very cumbersome with pnmotpng.
One difference that does not 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.
Because pnmtopng has been around virtually forever, programs and proce-
dures that use it are more portable than those that use pamtopng. Its
age and popularity also probably make it have fewer bugs.
pamtopng does not have any way to do what the following do in pnmtopng:
• -palette
• -history
• -filter
• -size
• -paeth
• -hist
• -nofilter
• -sub
• -up
• -avg
• -force
• -libversion
• -compression
• -comp_xxx
These are some of the other functions of pnmtopng that pamtopng lacks:
• When you specify a transparent or background color that is not
in the image, pnmtopng can optionally choose the closest one
that is in the image. pamtopng always uses the exact color you
specify.
Features that exist in both programs are controlled by largely the same
command syntax. But there are these differences:
• pnmtopng's -rgb option is -chroma in pamtopng. -chroma is a
better name, and in fact was the name that pnmtopng used origi-
nally, but we had to change it when we had to change the syntax
of the option value to conform to the rest of Netpbm.
• pnmtopng's -modtime option is -time in pamtopng. The origin of
-modtime is analogous to that of -rgb.
OPTIONS
In addition to the options common to all programs based on libnetpbm
(most notably -quiet, see
Common Options ⟨index.html#commonoptions⟩ ), pamtopng recognizes the
following command line options:
-transparent=color
pamtopng marks the specified color as transparent in the PNG im-
age -- Every pixel of this color is fully transparent. This
causes pamtopng to include a tRNS chunk in the image identifying
that color.
Specify the color (color) as described for the argument of the
pnm_parsecolor() library routine
⟨libnetpbm_image.html#colorname⟩ . E.g. red or rgb:ff/00/0d.
-background=color
This causes pamtopng to create a background color chunk in the
PNG output which can be used for subsequent transparency channel
or transparent color conversions. Specify color the same as for
-transparent.
-gamma=value
This causes pamtopng to create a gAMA chunk. This information
helps describe how the color values in the PNG must be inter-
preted. 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 -gamma=.45. 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.
-chroma=chroma_list
This option specifies how red, green, and blue component values
of a pixel specify a particular color, by telling the chromatic-
ities of those 3 primary illuminants and of white (i.e. full
strength of all three).
The chroma_list 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 or-
der.
This information goes into the PNG's cHRM chunk.
In a shell command, make sure you use quotation marks so that
the blanks in chroma_list don't make the shell see multiple com-
mand arguments.
-srgbintent=intent
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 pamtopng to in-
clude an sRGB chunk in the PNG image that specifies that intent,
so see the PNG documentation for more information on what this
really means.
intent is one of:
• perceptual
• relativecolorimetric
• saturation
• absolutecolorimetric
-text=filename
This option lets you include arbitrary text strings in the PNG
output, as tEXt chunks.
filename is the name of a file that contains your text strings.
The output contains a distinct tEXt chunk for each entry in the
file.
Here is an example of a text string file:
Title PNG file
Author John Doe
Description how to include a text chunk
PNG file
"Creation Date" 2015-may-11
Software pamtopng
The file is divided into entries, each entry comprising consecu-
tive lines of text. The first line of an entry starts in the
first column (i.e. the first column is not white space) and ev-
ery 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.
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.
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.
-ztxt=filename
The same as -text, except the text string is compressed in the
PNG output. pamtopng uses zTXt chunks instead of a tEXt chunks.
-itxt=filename
Similar to -text, 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. pamtopng uses iTXt chunks instead of tEXt chunks.
For each record, you must specify the language and give the key
both in English and in the text string language.
Example:
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.
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".
-time='[yy]yy-mm-dd hh:mm:ss'
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.
-interlace
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 contin-
ues 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 re-
ceiving 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 in-
stantly, but then the user is wasting time staring at a blank
space until the whole image arrives. With the standard non-in-
terlaced 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 in-
terlaced image, the displayer can start by showing a low-resolu-
tion version of the image, then gradually improve the display as
more data arrives.
When you specify this option, pamtopng must hold the entire im-
age 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 pamtopng, but potentially throughout
the system that shares memory with it. pnmtopng does not have
this limitation (it holds only one row at a time in memory even
when generating an interlaced PNG).
This option was new in Netpbm 10.86 (March 2019).
-verbose
This causes the program to display various facts about the con-
version.
SEE ALSO
pngtopam(1), pnmtopng(1), pam(1), pnm(1)
For information on the PNG format, see http://www.w3.org/TR/PNG/
⟨http://www.w3.org/TR/PNG/⟩ , http://libpng.org/pub/png/
⟨http://libpng.org/pub/png/⟩ ,
http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
⟨http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes⟩ and
http://schaik.com/png/ ⟨http://schaik.com/png/⟩ .
HISTORY
pamtopng was new in Netpbm 10.70 (June 2015).
Before pamtopng, the two ways to create PNG images with Netpbm were pn-
mtopng and pamrgbatopng. The history of the former is discussed above.
The latter was added to Netpbm in 2005 as a cheap way to fill a signif-
icant need that pnmtopng did not: the ability to turn the alpha channel
in a PAM image into the alpha channel in a PNG image.
Handling of the alpha channel with pnmtopng is very cumbersome (as was
dealing with alpha channels in general before the introduction of the
PAM format). pamrgbatopng could do what people wanted with the alpha
channel, but nothing else. It was a very small program with literally
no command line options.
The goal in those days was eventually to expand pnmtopng to do the PAM
alpha channel thing, rename it to pamtopng, and retire pamrgbatopng.
But pnmtopng 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 at-
tempted it.
In 2015, one of the authors of the original pnmtopng (from before it
was even part of Netpbm -- a program that shared essentially no lines
of code with pnmtopng of 2015) decided to go in a different direction.
While many features of pnmtopng were pretty important and easy to im-
plement, 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 in-
tended to make the PNG output slightly smaller - something considerably
less important with the declining cost of computer resources).
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.
Therefore, Willem van Schaik wrote an intermediate level program that
had all the most important features of pnmtopng, plus the alpha channel
handling of pamrgbatopng, with nice, simple code. That was pamtopng.
Because pamrgbatopng had no options, pamtopng was backward compatible
with it without even trying. Therefore, as soon as we added pamtopng
to Netpbm, we removed pamrgbatopng and recommended that pamrgbatopng be
installed as an alias for pamtopng.
AUTHOR
Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
Copyright (C) 2015 by Willem van Schaik.
DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source. The master documentation is at
http://netpbm.sourceforge.net/doc/pamtopng.html
netpbm documentation 13 March 2019 Pamtopng User Manual(1)
Generated by dwww version 1.15 on Sat Jun 29 02:39:39 CEST 2024.