man > pamtogif(1)

Pamtogif User Manual(1)                General Commands Manual               Pamtogif User Manual(1)

NAME
       pamtogif - convert a Netpbm image to a GIF image


SYNOPSIS
       pamtogif

       [-interlace]

       [-sort]

       [-mapfile=mapfile] [-transparent=[=]color]

       [-alphacolor=color]

       [-comment=text]

       [-noclear]

       [-nolzw]

       [-aspect=fraction]

       [-verbose] [netpbmfile]

       All  options can be abbreviated to their shortest unique prefix.  You may use two hyphens in‐
       stead of one to designate an option.  You may use either white space or an  equals  sign  be‐
       tween an option name and its value.


DESCRIPTION
       This program is part of Netpbm(1).

       pamtogif reads a Netpbm image as input and produces a GIF file as output.

       This program creates only individual GIF images.  To combine multiple GIF images into an ani‐
       mated GIF, use gifsicle  (not part of the Netpbm package).

       pamtogif creates either an original GIF87 format GIF file or the
         newer GIF89 format.  It creates GIF89 when the output needs to have features
         that were new with GIF89, to wit transparency or comments.  Otherwise, it
         creates GIF87.  Really old GIF readers conceivably could not recognize
         GIF89.  The output needs to have transparency when either the input has a
         transparency information or you specify the -transparent option.  It
         needs to have comments when you specify the
         -comment option.

       pamtogif  generates  a GIF image with a single image block, which means the image cannot have
       more than 256 colors in it (it contains a single color map with a maximum size of  256).   If
       the  image  you want to convert has more colors than that (ppmhist can tell you), you can use
       pnmquant to reduce it to 256.  Or use the more complex but faster method described under  the
       -mapfile option.

       If  your  input  image is a PAM with transparency information, pamtogif uses one entry in the
       GIF colormap specifically for the transparent pixels, so you can have at most 255 opaque col‐
       ors.  In contrast, if you use the -transparent option, one of the colors from the  input  be‐
       comes transparent, so the limit is still 256.

       pamtogif recognizes transparency information in the input by the
         tuple type being RGB_ALPHA, GRAYSCALE_ALPHA, or
         BLACKANDWHITE_ALPHA.  This is the case for any image that has
         transparency information and was created by a Netpbm program that
         manipulates visual images.  If, on the other hand, you have a PAM generated
         some other way, but you know the planes have the same meaning as implied by
         these tuple types, you can make pamtogif process the transparency
         information by changing the tuple type accordingly before you pass it
         to pamtogif.  You can use pamstack to change the tuple type.

       pamtogif was new in Netpbm 10.37 (December 2006).  In older Netpbm, use ppmtogif.


OPTIONS
       In  addition  to  the options common to all programs based on libnetpbm (most notably -quiet,
       see  Common Options ), pamtogif recognizes the following command line options:




       -interlace
              Produce an interlaced GIF file.


       -sort  Produce a GIF file with a color map sorted in a predictable order.

              This does not produce the sorted color map which is part of the GIF format.  That kind
              of sorted color map is one where the colors are sorted according to how important they
              are, and the GIF header tells the viewer that it is sorted that way.  Its  purpose  is
              to allow the viewer to use fewer colors than are in the color map if it is not capable
              of displaying all the colors.

              What  this  option produces is a color map sorted by red value, then green, then blue.
              That can be useful in analyzing GIF images, particularly those made with two  versions
              of the program, because it removes some of the variability.



       -mapfile=mapfile

              Use  the  colors found in the file mapfile to create the colormap in the GIF file, in‐
              stead of the colors from netpbmfile.  mapfile can be any PPM file; all that matters is
              the colors in it.  If the colors in netpbmfile do not match those in mapfile, pamtogif
              matches them to a "best match." You can obtain a much better result by using  pnmremap
              to change the colors in the input to those in the map file.

              The  mapfile  file  is not a palette file, just an image whose colors you want to use.
              The order of colors in the GIF palette have nothing to do with where  they  appear  in
              the mapfile image, and duplication of colors in the image is irrelevant.

              The  map file's depth must match the number of color components in the input (which is
              not necessarily the same as the input's depth -- the input might have  a  transparency
              plane  in  addition).   If  your  map  file  does not, or it might not, run your input
              through pnmremap using the same map file so that it does.

              You can use -mapfile to speed up conversion of an image where you already have  a  map
              file  because of earlier processing of your image.  For example, it is common to start
              with an image that has more than 256 colors and remap its colors to a set of 256  col‐
              ors so that pamgtogif can convert it (a GIF can have only 256 colors; pamtogif without
              -mapfile fails on any image that has more than that) with pnmquant.  When you do this,
              pnmquant  generates a palette to do the color quantization, then pamtogif generates an
              identical palette from the quantized image.  You can save  computation  by  generating
              the palette once:

                  $ pnmcolormap 256 myimage.ppm >/tmp/colormap.ppm
                  $ pamtogif myimage.ppm -mapfile=/tmp/colormap.ppm >output.gif




       -transparent=color
              pamtogif marks the specified color as transparent in the GIF image.

              If  you  don't specify -transparent, pamtogif does not mark any color transparent (ex‐
              cept as indicated by the transparency information in the input file).

              Specify the color (color) as described  for  the  argument of the pnm_parsecolor() li‐
              brary routine .

              If  the  color  you  specify is not present in the image, pamtogif selects instead the
              color in the image that is closest to the one you specify.  Closeness is measured as a
              Cartesian distance between colors in RGB space.  If multiple colors  are  equidistant,
              pamtogif chooses one of them arbitrarily.

              However, if you prefix your color specification with "=", e.g. -transparent==red, only
              the exact color you specify will be transparent.  If that color does not appear in the
              image,  there  will  be  no transparency.  pamtogif issues an information message when
              this is the case.

              When you specify -transparent, pamtogif ignores explicit transparency information (the
              "alpha channel") in the input image.


       -alphacolor=color
              This specifies the foreground color for transparent pixels.   A  viewer  may  use  the
              foreground color for a transparent pixel if it chooses not to have another color "show
              through.".  The default is black.

              This applies only to pixels that are transparent in the GIF because they are transpar‐
              ent  in  the  Netpbm input.  If a GIF pixel is transparent because of the -transparent
              option, the foreground color is the color indicated by that option.

              Note that in GIF, all transparent pixels have the same foreground  color.   (There  is
              only one entry in the GIF colormap for transparent pixels).

              Specify  the  color  (color) as described for the argument of the pnm_parsecolor() li‐
              brary routine .


       -comment=text
              Include a comment in the GIF output with comment text text.

              Without this option, there are no comments in the output.

              Note that in a command shell, you'll have to use quotation marks  around  text  if  it
              contains  characters (e.g. space) that would make the shell think it is multiple argu‐
              ments:
              $ pamtogif -comment "this is a comment" <xxx.ppm >xxx.gif



       -noclear

              This option causes the output not to contain any GIF clear codes.

              In GIF, the stream defines codes that represent strings of pixels  as  it  goes.   The
              stream  contains definitions of codes mixed in with the references to those codes that
              describe the pixels of the image.  GIF specifies a maximum number of codes that can be
              defined; when the stream has defined that many, the stream can either just  use  those
              for  the  rest  of the image or include a clear code, deleting all the string codes so
              that the stream can start over defining new ones.

              By far the most common choice is the clear code.  This usually results  in  a  smaller
              stream because the set of strings of pixels that occur in an image vary over the parts
              of the image.  Hardly any GIF encoders produce streams that don't use the clear code.

              But it is conceivable that a stream could be smaller without the use of the clear code
              because  it  saves  the stream having to redefine the same string codes over and over.
              It could even avoid a thrashing situation where the stream continually defines  a  set
              of strings that never get used again before the maximum is reached.

              The default is to use the clear codes.

              This option was new in Netpbm 10.82 (March 2018).  Before that, the program aways uses
              the clear codes.


       -nolzw

              This  option  is  mainly of historical interest -- it involves use of a patent that is
              now expired.

              This option causes the GIF output, and thus pamtogif, not to use LZW (Lempel-Ziv) com‐
              pression.  As a result, the image file is larger and, before the  patent  expired,  no
              royalties  would  be owed to the holder of the patent on LZW.  See the section LICENSE
              below.

              LZW is a method for combining the information from multiple pixels into a  single  GIF
              code.   With  the -nolzw option, pamtogif creates one GIF code per pixel, so it is not
              doing any compression and not using LZW.  However, any GIF decoder, whether it uses an
              LZW decompressor or not, will correctly decode this uncompressed format.  An  LZW  de‐
              compressor would see this as a particular case of LZW compression.

              Note  that  if  someone uses an LZW decompressor such as the one in giftopnm or pretty
              much any graphics display program to process the output of pamtogif  -nolzw  ,  he  is
              then  using  the LZW patent.  But the patent holder expressed far less interest in en‐
              forcing the patent on decoding than on encoding.


       -aspect=fraction
              This is the aspect ratio of the pixels of the image.  Its only  effect  is  to  record
              that  information  in  the GIF for use by whatever interprets the GIF.  Note that this
              feature of GIF is hardly ever used and most GIF decoders ignore this  information  and
              assume pixels are square.

              Pixels  in  a Netpbm image do not have aspect ratios; there is always a one-one corre‐
              spondence between GIF pixels and Netpbm pixels.

              The aspect ratio is the quotient of width divided by height.  GIF allows aspect ratios
              from 0.25 (1:4) to 4 (4:1) in increments of 1/64.  pamtogif implements a  natural  ex‐
              tension  of  GIF  that  allows an aspect ratio up to 4 14/64.  If you specify anything
              outside this range, pamtogif fails.  pamtogif rounds fraction to the nearest 1/64.

              The default is square (1.0).

              This option was new in Netpbm 10.38 (March 2007).  Before that, the pixels are  always
              square.



       -verbose
              This  option  causes  pamtogif to display information about the conversion process and
              the image it produces.




SEE ALSO
       giftopnm(1), pnmremap(1), ppmtogif(1),

       gifsicle http://www.lcdf.org/gifsicle , pnm(1), pam(1).


HISTORY
       pamtogif was new in Netpbm 10.37 (December 2006).  It replaced ppmtogif,  which  created  GIF
       images for Pbmplus/Netpbm users since 1989.

       The  main  outward  change  in the conversion from ppmtogif to pamtogif was that pamtogif was
       able to use transparency information ("alpha channel") in PAM input, whereas  with  ppmtogif,
       one  had  to  supply the transparency mask in a separate pseudo-PGM image (via the -alpha op‐
       tion).

       Jef Poskanzer wrote ppmtogif in 1989, and it has always been a cornerstone of  Pbmplus/Netpbm
       because  GIF is such a popular image format.  Jef based the LZW encoding on GIFENCOD by David
       Rowley <mgardi AT watdcsu.edu>.  Jef included GIFENCOD's GIFCOMPR.C  file  pretty  much
       whole.   Rowley,  in turn, adapted the LZW compression code from classic Unix compress, which
       used techniques described in IEEE Computer, June 1984.

       Jef's ppmtogif notably lacked the ability to use a transparency mask with it.  You could cre‐
       ate transparent pixels in a GIF, but only with the -transparent option, which allowed one  to
       specify  that  all pixels of a certain color in the input were to be transparent.  Bryan Hen‐
       derson added the -alpha option in July 2001 so you could supply a mask image  that  indicates
       exactly  which  pixels  are  to be transparent, and those pixels could have the same color as
       other opaque ones.

       Bryan Henderson added another significant piece of code and function  in  October  2001:  the
       ability to generate a GIF without using the LZW patent -- an uncompressed GIF.  This was very
       important  to many people at the time because the GIF patent was still in force, and this al‐
       lowed them to make an image that any GIF viewer could display, royalty-free.   Bryan  adapted
       code from the Independent JPEG Group's djpeg for that.

       There  is  no  code in pamtogif from Jef's original, but Jef may still hold copyright over it
       because of the way in which it evolved.  Virtually all of the code in pamtogif was written by
       Bryan Henderson and contributed to the public domain.



LICENSE
       If you use pamtogif without the -nolzw option, you are using a patent on the LZW  compression
       method which is owned by Unisys.  The patent has expired (in 2003 in the US and in 2004 else‐
       where),  so  it doesn't matter.  While the patent was in force, most people who used pamtogif
       and similar programs did so without a license from Unisys to do so.  Unisys  typically  asked
       $5000  for a license for trivial use of the patent.  Unisys never enforced the patent against
       trivial users.

       Rumor has it that IBM also owns or owned a patent covering pamtogif.

       A replacement for the GIF format that never required any patents to use is the PNG format.

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/pamtogif.html

netpbm documentation                        09 June 2021                     Pamtogif User Manual(1)