Ubuntu Manpage: pamtopng - convert a Netpbm image to PNG

Provided by: netpbm_11.05.02-1.1build1_amd64

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] [pnmfile]

OPTION USAGE

       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.

DESCRIPTION

This program is part of Netpbm(1).

pamtopng reads a Netpbm image as input and produces a PNG image as output.

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
original 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 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.

The main advantage pamtopng has over pnmtopng 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 pnmtopng.

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 procedures 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 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.

• 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 ), pamtopng recognizes the following command line options:

-transparent=color
pamtopng marks the specified color as transparent in the PNG image -- 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 .
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 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 -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 chromaticities 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 order.

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 command 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 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.

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 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.

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 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.

When you specify this option, pamtopng 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 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 conversion.

HISTORY

pamtopng was new in Netpbm 10.70 (June 2015).

Before pamtopng, the two ways to create PNG images with Netpbm were pnmtopng 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 significant 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 attempted 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 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).

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)