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

SEE ALSO

302       giftopnm(1), pnmremap(1), ppmtogif(1),
303
304       gifsicle  http://www.lcdf.org/gifsiclehttp://www.lcdf.org/gifsicle⟩ ,
305       pnm(1), pam(1).
306
307

HISTORY

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

LICENSE

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

DOCUMENT SOURCE

362       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
363       source.  The master documentation is at
364
365              http://netpbm.sourceforge.net/doc/pamtogif.html
366
367netpbm documentation             22 March 2007         Pamtogif User Manual(0)
Impressum