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
47         newer  GIF89  format.  It creates GIF89 when the output needs to have
48       features
49         that were new with GIF89, to wit transparency  or  comments.   Other‐
50       wise, it
51         creates  GIF87.   Really old GIF readers conceivably could not recog‐
52       nize
53         GIF89.  The output needs to have transparency when either  the  input
54       has a
55         transparency information or you specify the -transparent option.  It
56         needs to have comments when you specify the
57         -comment option.
58
59       pamtogif  generates  a GIF image with a single image block, which means
60       the image cannot have more than 256 colors in it (it contains a  single
61       color  map  with a maximum size of 256).  If the image you want to con‐
62       vert has more colors than that (ppmhist can tell you), you can use  pn‐
63       mquant  to reduce it to 256.  Or use the more complex but faster method
64       described under the -mapfile option.
65
66       If your input image is a PAM with  transparency  information,  pamtogif
67       uses  one  entry  in  the GIF colormap specifically for the transparent
68       pixels, so you can have at most 255 opaque colors.  In contrast, if you
69       use  the  -transparent option, one of the colors from the input becomes
70       transparent, so the limit is still 256.
71
72       pamtogif recognizes transparency information in the input by the
73         tuple type being RGB_ALPHA, GRAYSCALE_ALPHA, or
74         BLACKANDWHITE_ALPHA.  This is the case for any image that has
75         transparency information and was created by a Netpbm program that
76         manipulates visual images.  If, on the other hand,  you  have  a  PAM
77       generated
78         some  other way, but you know the planes have the same meaning as im‐
79       plied by
80         these tuple types, you can make pamtogif process the transparency
81         information by changing the tuple type accordingly before you pass it
82         to pamtogif.  You can use pamstack to change the tuple type.
83
84       pamtogif was new in Netpbm 10.37 (December 2006).  In older Netpbm, use
85       ppmtogif.
86
87

OPTIONS

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

SEE ALSO

307       giftopnm(1), pnmremap(1), ppmtogif(1),
308
309       gifsicle  http://www.lcdf.org/gifsiclehttp://www.lcdf.org/gifsicle⟩ ,
310       pnm(1), pam(1).
311
312

HISTORY

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

LICENSE

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

DOCUMENT SOURCE

367       This  manual  page was generated by the Netpbm tool 'makeman' from HTML
368       source.  The master documentation is at
369
370              http://netpbm.sourceforge.net/doc/pamtogif.html
371
372netpbm documentation             09 June 2021          Pamtogif User Manual(0)
Impressum