ppmtogif

   Updated: 15 September 2002
   Table Of Contents

NAME

   ppmtogif - convert a PPM image to a GIF image

SYNOPSIS

   ppmtogif [-interlace] [-sort] [-mapfile mapfile]
   [-transparent=[=]color]    [-alpha=pgmfile]	  [-comment=text]
[-nolzw]
   [ppmfile]

   All options can be abbreviated to their shortest  unique  pre-
fix. You may use
   two hyphens instead of one to designate an option. You may use
either white
   space or equals signs between an option name and its value.

DESCRIPTION

   This program is part of Netpbm.

   ppmtogif reads a PPM iamge as input and produces a GIF file as
output.

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

   ppmtogif  creates  either an original GIF87 format GIF file or
the newer GIF89
   format. It creates GIF89 when you request features  that  were
new with GIF89,
   to  wit  the	 -transparent  or -comment options. Otherwise, it
creates GIF87.
   Really old GIF readers conceivably could not recognize  GIF89.

OPTIONS

   -interlace
	  Produce an interlaced GIF file.
   -sort
	  Produce a GIF file with a sorted color map.
   -mapfile=mapfile
	  Use  the colors found in the file mapfile to create the
colormap in
	  the GIF file, instead of the colors from ppmfile.  map-
file can be any
	  PPM  file; all that matters is the colors in it. If the
colors in
	  ppmfile do not match those in mapfile, ppmtogif 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.
   -transparent=color
	  ppmtogif marks the specified color  as  transparent  in
the GIF image.
	  If  you  don't  specify -transparent, ppmtogif does not
mark any color
	  transparent (except as indicated by the -alpha option).
	  Specify   the	 color (color) as described for the argu-
ment of the
	  ppm_parsecolor() library  routine.  If  the  color  you
specify is not
	  present in the image, ppmtogif selects instead the col-
or in the image
	  that is closest to the one you  specify.  Closeness  is
measured as a
	  cartesian distance between colors in RGB space. If mul-
tiple colors
	  are equidistant, ppmtogif chooses one of them arbitrar-
ily.
	  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 im-
age, there will
	  be no transparency. ppmtogif issues an information mes-
sage when this
	  is the case.
	  You cannot specify both -transparent and -alpha.
   -alpha=pgmfile
	  This	option	names  a  PGM file that contains an alpha
mask for the
	  image. ppmtogif creates fully transparent pixels  wher-
ever the alpha
	  mask indicates transparency greater than 50%. The color
of those
	  pixels is that specified by the -alphacolor option,  or
black by
	  default.
	  To  do  this, ppmtogif creates an entry in the GIF col-
ormap in addition
	  to the entries for colors that are actually in the  im-
age. It marks
	  that	colormap  entry as transparent and uses that col-
ormap index in
	  the output image to create a transparent pixel.
	  The alpha image must be the same dimensions as the  in-
put image, but
	  may have any maxval. White means opaque and black means
transparent.
	  You cannot specify both -transparent and -alpha.
   -alphacolor
	  See -alpha.
   -comment=text
	  Include a comment in the GIF output with  comment  text
text.
	  Without  this option, there are no comments in the out-
put.
	  Note that in a command shell, you'll have to use quota-
tion marks
	  around text if it contains characters (e.g. space) that
would make
	  the shell think it is multiple  arguments:  $	 ppmtogif
-comment "this is a comment" xxx.gif
   -nolzw
	  This	option	causes the GIF output, and thus ppmtogif,
not to use LZW
	  (Lempel-Ziv) compression. As a result, the  image  file
is larger and
	  no  royalties	 are  owed to the holder of the patent on
LZW. See the
	  section LICENSE below.
	  LZW is a method for combining the information from mul-
tiple pixels
	  into	a  single  GIF code. With the -nolzw option, ppm-
togif 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  for-
mat. An LZW
	  decompressor 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 ppmtogif -nolzw , he is then  using	 the  LZW
patent. But the
	  patent  holder  has  expressed far less interest in en-
forcing the patent
	  on decoding than on encoding.



SEE ALSO

   giftopnm,	     ppmquant,	       pngtopnm,	 gifsicle
, ppm.


AUTHOR

   Based  on  GIFENCOD	by  David  Rowley  . Lempel-Ziv
   compression based on "compress".

   The non-LZW format is generated by code based on djpeg by  the
Independent
   Jpeg Group.

   Copyright (C) 1989 by Jef Poskanzer.

LICENSE

   If you use ppmtogif without the -nolzw option, you are using a
patent on the
   LZW compression method which is owned by Unisys,  and  in  all
probability you
   do  not  have a license from Unisys to do so. Unisys typically
asks $5000 for
   a license for trivial use of the patent. Unisys has never  en-
forced the
   patent  against trivial users. The patent expired in the US in
2003 and is
   due to expire in other countries in 2004.

   Rumor has it that IBM also owns a patent covering ppmtogif.

   A replacement for the GIF format that  does	not  require  any
patents to use is
   the PNG format.
     _________________________________________________________________



Table Of Contents

     * NAME
     * SYNOPSIS
     * DESCRIPTION
     * OPTIONS
     * SEE ALSO
     * AUTHOR
     * LICENSE

UNIX/Linux commands referenced on this page:

1. convert
2. as
3. file
4. giftopnm
5. display
6. less
7. djpeg
8. which