1Pamtogif User Manual(0)                                Pamtogif User Manual(0)
2
3
4

NAME

6       pamtogif - convert a Netpbm image to a GIF image
7
8

SYNOPSIS

10       pamtogif
11
12       [-interlace]
13
14       [-sort]
15
16       [-mapfile=mapfile] [-transparent=[=]color]
17
18       [-alphacolor=color]
19
20       [-comment=text]
21
22       [-noclear]
23
24       [-nolzw]
25
26       [-aspect=fraction]
27
28       [-verbose] [netpbmfile]
29
30       All  options  can  be abbreviated to their shortest unique prefix.  You
31       may use two hyphens instead of one to designate an option.  You may use
32       either  white  space  or  an equals sign between an option name and its
33       value.
34
35

DESCRIPTION

37       This program is part of Netpbm(1).
38
39       pamtogif reads a Netpbm image as input and produces a GIF file as  out‐
40       put.
41
42       This  program  creates only individual GIF images.  To combine multiple
43       GIF    images    into     an     animated     GIF,     use     gifsicle
44http://www.lcdf.org/gifsicle/⟩  (not part of the Netpbm package).
45
46       pamtogif  creates either an original GIF87 format GIF file or the newer
47       GIF89 format.  It creates GIF89 when you request features that were new
48       with GIF89, to wit the -transparent or -comment options.  Otherwise, it
49       creates GIF87.  Really old GIF readers conceivably could not  recognize
50       GIF89.
51
52       The  GIF  format is not capable of representing an image with more than
53       256 colors in it (it contains a color map with a maximum size of  256).
54       If the image you want to convert has more colors than that (ppmhist can
55       tell you), you can use pnmquant to reduce it to 256.  Or use  the  more
56       complex but faster method described under the -mapfile option.
57
58       If  your  input  image is a PAM with transparency information, ppmtogif
59       uses one entry in the GIF colormap  specifically  for  the  transparent
60       pixels, so you can have at most 255 opaque colors.  In contrast, if you
61       use the -transparent option, one of the colors from the  input  becomes
62       transparent, so the limit is still 256.
63
64       pamtogif was new in Netpbm 10.37 (December 2006).  In older Netpbm, use
65       ppmtogif.
66
67

OPTIONS

69       In addition to the options common to all programs  based  on  libnetpbm
70       (most notably -quiet, see
71        Common  Options  ⟨index.html#commonoptions⟩ ), pamtogif recognizes the
72       following command line options:
73
74
75
76
77       -interlace
78              Produce an interlaced GIF file.
79
80
81       -sort  Produce a GIF file with a color  map  sorted  in  a  predictable
82              order.
83
84              This  does not produce the sorted color map which is part of the
85              GIF format.  That kind of sorted color map is one where the col‐
86              ors  are sorted according to how important they are, and the GIF
87              header tells the viewer that it is sorted that way.  Its purpose
88              is to allow the viewer to use fewer colors than are in the color
89              map if it is not capable of displaying all the colors.
90
91              What this option produces is a color map sorted  by  red  value,
92              then  green,  then  blue.   That  can be useful in analyzing GIF
93              images, particularly those made with two versions  of  the  pro‐
94              gram, because it removes some of the variability.
95
96
97
98       -mapfile=mapfile
99
100              Use  the colors found in the file mapfile to create the colormap
101              in the GIF file, instead of the colors from netpbmfile.  mapfile
102              can  be  any PPM file; all that matters is the colors in it.  If
103              the colors in netpbmfile do not match those in mapfile, pamtogif
104              matches  them  to  a  "best match." You can obtain a much better
105              result by using pnmremap to change the colors in  the  input  to
106              those in the map file.
107
108              The mapfile file is not a palette file, just an image whose col‐
109              ors you want to use.  The order of colors  in  the  GIF  palette
110              have  nothing to do with where they appear in the mapfile image,
111              and duplication of colors in the image is irrelevant.
112
113              The map file's depth must match the number of  color  components
114              in  the  input (which is not necessarily the same as the input's
115              depth -- the input might have a transparency plane in addition).
116              If  your  map  file  does  not,  or it might not, run your input
117              through pnmremap using the same map file so that it does.
118
119              You can use -mapfile to speed up conversion of  an  image  where
120              you  already  have  a  map file because of earlier processing of
121              your image.  For example, it is common to start  with  an  image
122              that  has  more than 256 colors and remap its colors to a set of
123              256 colors so that pamgtogif can convert it (a GIF can have only
124              256  colors;  pamtogif  without -mapfile fails on any image that
125              has more than that) with pnmquant.  When you do  this,  pnmquant
126              generates  a palette to do the color quantization, then pamtogif
127              generates an identical palette from the  quantized  image.   You
128              can save computation by generating the palette once:
129
130                  $ pnmcolormap 256 myimage.ppm >/tmp/colormap.ppm
131                  $ pamtogif myimage.ppm -mapfile=/tmp/colormap.ppm >output.gif
132
133
134
135       -transparent=color
136              pamtogif  marks  the  specified  color as transparent in the GIF
137              image.
138
139              If you don't specify -transparent, pamtogif does  not  mark  any
140              color  transparent  (except  as  indicated  by  the transparency
141              information in the input file).
142
143              Specify the color (color) as described for the argument  of  the
144              pnm_parsecolor()                 library                 routine
145              ⟨libnetpbm_image.html#colorname⟩ .
146
147              If the color you specify is not present in the  image,  pamtogif
148              selects  instead  the  color in the image that is closest to the
149              one you specify.  Closeness is measured as a Cartesian  distance
150              between  colors  in  RGB space.  If multiple colors are equidis‐
151              tant, pamtogif chooses one of them arbitrarily.
152
153              However, if you prefix your color specification with  "=",  e.g.
154              -transparent==red,  only  the  exact  color  you specify will be
155              transparent.  If that color does not appear in the image,  there
156              will be no transparency.  pamtogif issues an information message
157              when this is the case.
158
159              When you specify -transparent, pamtogif ignores explicit  trans‐
160              parency information (the "alpha channel") in the input image.
161
162
163       -alpha=pgmfile
164              There  is  no -alpha option.  pamtogif's predecessor had such an
165              option because it was not capable of taking PAM input that  con‐
166              tains  a  transparency (alpha) plane, so one used this option to
167              supply a transparency plane as a separate PGM file.
168
169               This option names a PGM file that contains a transparency  mask
170              for  the image.  pamtogif creates fully transparent pixels wher‐
171              ever the transparency mask indicates transparency  greater  than
172              50%.  The color of those pixels is that specified by the -alpha‐
173              color option, or black by default.
174
175              To do this, pamtogif creates an entry in  the  GIF  colormap  in
176              addition  to  the  entries  for  colors that are actually in the
177              image.  It marks that colormap entry  as  transparent  and  uses
178              that  colormap index in the output image to create a transparent
179              pixel.
180
181               The transparency image must be the same dimensions as the input
182              image,  but  may  have any maxval.  White means opaque and black
183              means transparent.
184
185               You cannot specify both -transparent and -alpha.
186
187
188       -alphacolor=color
189              This specifies the foreground color for transparent  pixels.   A
190              viewer  may  use the foreground color for a transparent pixel if
191              it chooses not to  have  another  color  "show  through.".   The
192              default is black.
193
194              This  applies  only  to  pixels  that are transparent in the GIF
195              because they are transparent in the  Netpbm  input.   If  a  GIF
196              pixel  is  transparent  because  of the -transparent option, the
197              foreground color is the color indicated by that option.
198
199              Note that in GIF, all transparent pixels  have  the  same  fore‐
200              ground  color.  (There is only one entry in the GIF colormap for
201              transparent pixels).
202
203              Specify the color (color) as described for the argument  of  the
204              pnm_parsecolor()                 library                 routine
205              ⟨libnetpbm_image.html#colorname⟩ .
206
207
208       -comment=text
209              Include a comment in the GIF output with comment text text.
210
211              Without this option, there are no comments in the output.
212
213              Note that in a command shell, you'll have to use quotation marks
214              around  text  if  it contains characters (e.g. space) that would
215              make the shell think it is multiple arguments:
216              $ pamtogif -comment "this is a comment" <xxx.ppm >xxx.gif
217
218
219       -noclear
220
221              This option causes the output  not  to  contain  any  GIF  clear
222              codes.
223
224              In  GIF, the stream defines codes that represent strings of pix‐
225              els as it goes.  The stream contains definitions of codes  mixed
226              in  with  the references to those codes that describe the pixels
227              of the image.  GIF specifies a maximum number of codes that  can
228              be  defined;  when  the stream has defined that many, the stream
229              can either just use those for the rest of the image or include a
230              clear code, deleting all the string codes so that the stream can
231              start over defining new ones.
232
233              By far the most common choice is the clear code.   This  usually
234              results in a smaller stream because the set of strings of pixels
235              that occur in an image vary over the parts of the image.  Hardly
236              any GIF encoders produce streams that don't use the clear code.
237
238              But it is conceivable that a stream could be smaller without the
239              use of the clear code because it  saves  the  stream  having  to
240              redefine  the  same  string  codes over and over.  It could even
241              avoid a thrashing situation where the stream continually defines
242              a set of strings that never get used again before the maximum is
243              reached.
244
245              The default is to use the clear codes.
246
247              This option was new in Netpbm 10.82 (March 2018).  Before  that,
248              the program aways uses the clear codes.
249
250
251       -nolzw
252
253              This  option is mainly of historical interest -- it involves use
254              of a patent that is now expired.
255
256              This option causes the GIF output, and thus pamtogif, not to use
257              LZW  (Lempel-Ziv)  compression.   As a result, the image file is
258              larger and, before the patent expired,  no  royalties  would  be
259              owed  to  the  holder  of  the  patent  on LZW.  See the section
260              LICENSE below.
261
262              LZW is a method for combining the information from multiple pix‐
263              els  into  a  single GIF code.  With the -nolzw option, pamtogif
264              creates one GIF code per pixel, so it is not doing any  compres‐
265              sion  and  not  using LZW.  However, any GIF decoder, whether it
266              uses an LZW decompressor or  not,  will  correctly  decode  this
267              uncompressed  format.   An  LZW decompressor would see this as a
268              particular case of LZW compression.
269
270              Note that if someone uses an LZW decompressor such as the one in
271              giftopnm  or pretty much any graphics display program to process
272              the output of pamtogif -nolzw , he is then using the LZW patent.
273              But  the  patent holder expressed far less interest in enforcing
274              the patent on decoding than on encoding.
275
276
277       -aspect=fraction
278              This is the aspect ratio of the pixels of the image.   Its  only
279              effect is to record that information in the GIF for use by what‐
280              ever interprets the GIF.  Note  that  this  feature  of  GIF  is
281              hardly  ever  used and most GIF decoders ignore this information
282              and assume pixels are square.
283
284              Pixels in a Netpbm image do not have  aspect  ratios;  there  is
285              always  a  one-one  correspondence between GIF pixels and Netpbm
286              pixels.
287
288              The aspect ratio is the quotient of  width  divided  by  height.
289              GIF  allows  aspect  ratios from 0.25 (1:4) to 4 (4:1) in incre‐
290              ments of 1/64.  pamtogif implements a natural extension  of  GIF
291              that  allows an aspect ratio up to 4 14/64.  If you specify any‐
292              thing outside this range, pamtogif fails.  pamtogif rounds frac‐
293              tion to the nearest 1/64.
294
295              The default is square (1.0).
296
297              This  option was new in Netpbm 10.38 (March 2007).  Before that,
298              the pixels are always square.
299
300
301
302       -verbose
303              This option causes pamtogif to  display  information  about  the
304              conversion process and the image it produces.
305
306
307
308

SEE ALSO

310       giftopnm(1), pnmremap(1), ppmtogif(1),
311
312       gifsicle  http://www.lcdf.org/gifsiclehttp://www.lcdf.org/gifsicle⟩ ,
313       pnm(1), pam(1).
314
315

HISTORY

317       pamtogif was new in Netpbm 10.37 (December  2006).   It  replaced  ppm‐
318       togif, which created GIF images for Pbmplus/Netpbm users since 1989.
319
320       The main outward change in the conversion from ppmtogif to pamtogif was
321       that pamtogif was able to use transparency  information  ("alpha  chan‐
322       nel") in PAM input, whereas with ppmtogif, one had to supply the trans‐
323       parency mask in a separate pseudo-PGM image (via the -alpha option).
324
325       Jef Poskanzer wrote ppmtogif in 1989, and it has always been a  corner‐
326       stone  of  Pbmplus/Netpbm  because  GIF is such a popular image format.
327       Jef based the LZW encoding on GIFENCOD by  David  Rowley  <mgardi@watd‐
328       csu.waterloo.edu>.  Jef included GIFENCOD's GIFCOMPR.C file pretty much
329       whole.  Rowley, in turn, adapted the LZW compression code from  classic
330       Unix  compress,  which used techniques described in IEEE Computer, June
331       1984.
332
333       Jef's ppmtogif notably lacked the ability to use  a  transparency  mask
334       with  it.   You could create transparent pixels in a GIF, but only with
335       the -transparent option, which allowed one to specify that  all  pixels
336       of  a certain color in the input were to be transparent.  Bryan Hender‐
337       son added the -alpha option in July 2001 so you  could  supply  a  mask
338       image  that  indicates  exactly which pixels are to be transparent, and
339       those pixels could have the same color as other opaque ones.
340
341       Bryan Henderson added another significant piece of code and function in
342       October  2001:  the  ability  to  generate  a GIF without using the LZW
343       patent -- an uncompressed GIF.  This was very important to many  people
344       at the time because the GIF patent was still in force, and this allowed
345       them to make an image that any GIF viewer could display,  royalty-free.
346       Bryan adapted code from the Independent JPEG Group's djpeg for that.
347
348       There  is  no  code  in pamtogif from Jef's original, but Jef may still
349       hold copyright over it because of the way in which it evolved.   Virtu‐
350       ally  all  of  the  code in pamtogif was written by Bryan Henderson and
351       contributed to the public domain.
352
353
354

LICENSE

356       If you use pamtogif without the -nolzw option, you are using  a  patent
357       on the LZW compression method which is owned by Unisys.  The patent has
358       expired (in 2003 in the US and in 2004 elsewhere), so it  doesn't  mat‐
359       ter.   While the patent was in force, most people who used pamtogif and
360       similar programs did so without a license from Unisys to do so.  Unisys
361       typically  asked  $5000  for  a  license for trivial use of the patent.
362       Unisys never enforced the patent against trivial users.
363
364       Rumor has it that IBM also owns or owned a patent covering pamtogif.
365
366       A replacement for the GIF format that never required any patents to use
367       is the PNG format.
368

DOCUMENT SOURCE

370       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
371       source.  The master documentation is at
372
373              http://netpbm.sourceforge.net/doc/pamtogif.html
374
375netpbm documentation             22 March 2007         Pamtogif User Manual(0)
Impressum