Provided by: netpbm_11.01.00-2build1_amd64 bug

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 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 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 ⟨index.html#commonoptions⟩ ), 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 ⟨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 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:

       •      perceptualrelativecolorimetricsaturationabsolutecolorimetric

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

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_codeshttp://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 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