Provided by: gifsicle_1.60-1_i386 bug

NAME

       gifsicle - manipulates GIF images and animations

SYNOPSIS

       gifsicle [options, frames, and filenames]...

DESCRIPTION

       gifsicle  is  a  powerful  command-line  program for creating, editing,
       manipulating, and getting information about GIF images and animations.

INTRODUCTION

       Without options, gifsicle acts like a filter: you  feed  it  a  GIF  on
       standard  input,  and it writes that GIF on standard output. That means
       these two commands do the same thing:

            % gifsicle < in.gif > out.gif
            % gifsicle < in.gif | gifsicle | gifsicle > out.gif

       Not too interesting. Most times  you'll  tell  gifsicle  to  alter  its
       inputs  by  giving it command line options. The -i option, for example,
       tells it to interlace its input files:

            % gifsicle -i < pic.gif > interlaced-pic.gif

       To modify GIF files in place, you should use the --batch  option.  With
       --batch,  gifsicle will modify the files you specify instead of writing
       a new file to the standard output. To interlace all  the  GIFs  in  the
       current directory, you could say:

            % gifsicle --batch -i *.gif

       gifsicle  is  good  at  creating  and  manipulating GIF animations. The
       simplest way to create an animation is to  give  more  than  one  input
       file, which gifsicle will combine to create a ``flipbook'' animation:

            % gifsicle pic1.gif pic2.gif pic3.gif > animation.gif

       Use  options  like  --delay,  --loopcount,  and --optimize to tune your
       animations; see their descriptions for more details.

       The bulk of this manual page indexes gifsicle's options  and  describes
       them in gory detail. New users may want to skip to the Examples section
       at the end.

CONCEPT INDEX

       This index is meant to help you find options that  do  what  you  want.
       Concepts are on the left, relevant gifsicle options are on the right.

       Animations, changing     frame selections, frame changes, etc.
          disposal              --disposal
          looping               --loopcount
          portions of           frame selections
          smaller               --optimize, --colors
          speed                 --delay
       Bad output               --careful
       Background color         --background
       Colors, changing         --change-color,    --use-colormap,   --dither,
                                --transform-colormap
          reducing number       --colors, --dither
       Comments                 --comment
       Extensions               --extension, --app-extension, --extension-info
       File size                --optimize, --unoptimize, --colors
       Image transformations

          cropping              --crop, --crop-transparency
          flipping              --flip-*
          resizing              --resize, --scale
          rotating              --rotate-*
       Grayscale                --use-colormap
       Interlacing              --interlace
       Positioning frames       --position
       Screen, logical          --logical-screen
       Selecting frames         frame selections (like '#0')
       Transparency             --transparent
       Warnings                 --no-warnings
       Web-safe palette         --use-colormap

COMMAND LINE

       gifsicle's command line consists of GIF input files and  options.  Most
       options  start with a dash (-) or plus (+); frame selections, a kind of
       option, start with a number sign (#). Anything  else  is  a  GIF  input
       file.

       gifsicle  reads and processes GIF input files in order. If no GIF input
       file is given, or you give the special filename `-', it reads from  the
       standard input.

       gifsicle  exits  with  status  0  if  there were no errors and status 1
       otherwise.

OPTIONS

       Every option has a long  form,  `--long-descriptive-name'.   You  don't
       need  to  type  the whole long descriptive name, just enough to make it
       unambiguous.

       Some options also have a short  form,  `-X'.   You  can  combine  short
       options if they don't take arguments: `-IIb' is the same as `-I -I -b'.
       But be careful with options that do take arguments: `-cblah' means  `-c
       blah', not `-c -b -l -a -h'.

       Many  options  also have a converse, `--no-option', which turns off the
       option. You can turn off a short option `-X' by saying `+X' instead.

   Mode Options
       Mode options tell gifsicle what kind of output to generate.  There  can
       be at most one, and it must precede any GIF inputs.

       --merge, -m
            Combine  all  GIF  inputs  into  one file with multiple frames and
            write that file to the standard output. This is the default mode.

       --batch, -b
            Modify each GIF input in place by reading and writing to the  same
            filename.   (GIFs  read from the standard input are written to the
            standard output.)

       --explode, -e
            Create an output GIF for each frame of each input file. The output
            GIFs are named `xxx.000', `xxx.001', and so on, where `xxx' is the
            name of the input file (or whatever you specified with `--output')
            and the numeric extension is the frame number.

       --explode-by-name, -E
            Same  as --explode, but write any named frames to files `xxx.name'
            instead  of  `xxx.frame-number'.   Frames  are  named  using   the
            `--name' option.

   General Options
       General  options  control  the information gifsicle prints and where it
       writes its output. The info options and --verbose  can  be  turned  off
       with `--no-X'.

       --color-info
            Like  --info,  but  also  print  information  about  input  files'
            colormaps.  --cinfo is a synonym for --color-info.

       --extension-info
            Like --info, but also print any unrecognized GIF extensions  in  a
            hexdump(1)-like    format.     --xinfo    is    a    synonym   for
            --extension-info.

       --help, -h
            Print usage information and exit.

       --info, -I
            Print a human-readable  description  of  each  input  GIF  to  the
            standard  output,  or  whatever  file  you  specify with -o.  This
            option suppresses normal output, and cannot be combined with  mode
            options  like  --batch.   If  you  give  two --info or -I options,
            however, normal output is  not  suppressed;  information  will  be
            printed on standard error, and you can supply a mode option.

       -o file
       --output file
            Send  output to file.  The special filename `-' means the standard
            output.

       --verbose, -V
            Print progress information (files read and  written)  to  standard
            error.

       --no-warnings, -w
            Suppress all warning messages.

       --version
            Print  the  version number and some short non-warranty information
            and exit.

       --conserve-memory
            Conserve memory usage at the expense of processing time. This  may
            be  useful  if you are processing large GIFs on a computer without
            very much memory.

       --nextfile
            Allow input files to contain multiple concatenated GIF images.  If
            a  filename  appears  multiple times on the command line, gifsicle
            will read a new image from the file each  time.  This  option  can
            help  scripts  avoid the need for temporary files. For example, to
            create an animated GIF with three frames  with  different  delays,
            you might run "gifsicle --nextfile -d10 - -d20 - -d30 - > out.gif"
            and write  the  three  GIF  images,  in  sequence,  to  gifsicle's
            standard input.

       --multifile
            Like --nextfile, but read as many GIF images as possible from each
            file. This option is intended for scripts. For example,  to  merge
            an  unknown  number  of  GIF  images  into a single animation, run
            "gifsicle --multifile - > out.gif" and write the  GIF  images,  in
            sequence,  to  gifsicle's  standard  input.   Any frame selections
            apply only to the last file in the concatenation.

   Frame Selections
       A frame selection tells gifsicle which frames to use from  the  current
       input  file.  They are useful only for animations, as non-animated GIFs
       only  have  one  frame.  Here  are  the  acceptable  forms  for   frame
       specifications.

       #num         Select  frame  num.  (The  first  frame is `#0'.  Negative
                    numbers count backwards from  the  last  frame,  which  is
                    `#-1'.)
       #num1-num2   Select frames num1 through num2.
       #num1-       Select frames num1 through the last frame.
       #name        Select the frame named name.

       For example,
            gifsicle happy.gif
       will use all of `happy.gif's frames, while
            gifsicle happy.gif "#0"
       will   only   use   the  first.  (Note  the  quotes  around  the  frame
       specification. The `#' character has special meaning for  many  shells,
       so you may need to quote it.)

       The  action  performed  with the selected frames depends on the current
       mode. In merge mode, only the  selected  frames  are  merged  into  the
       output GIF. In batch mode, only the selected frames are modified; other
       frames remain unchanged. In explode mode, only the selected frames  are
       exploded into output GIFs.

   Frame Change Options
       Frame  change options insert new frames into an animation or replace or
       delete frames that already exist. Some things -- for example,  changing
       one  frame  in  an  animation  --  are  difficult to express with frame
       selections, but easy with frame changes.

       --delete frames [frames...]
            Delete frames from the input GIF.

       --insert-before frame other-GIFs
            Insert other-GIFs before frame in the input GIF.

       --append other-GIFs
            Append other-GIFs to the input GIF.

       --replace frames other-GIFs
            Replace frames from the input GIF with other-GIFs.

       --done
            Complete the current set of frame changes.

       The frames arguments are frame selections (see above). These  arguments
       always  refer to frames from the original input GIF. So, if `a.gif' has
       3 frames and `b.gif' has one, this command
            gifsicle a.gif --delete "#0" --replace "#2" b.gif
       will produce an output animation with 2 frames: `a.gif' frame  1,  then
       `b.gif'.

       The  other-GIFs  arguments  are any number of GIF input files and frame
       selections.  These images are combined in merge mode and added  to  the
       input  GIF.  The other-GIFs last until the next frame change option, so
       this command replaces the first frame of `in.gif'  with  the  merge  of
       `a.gif' and `b.gif':
            gifsicle -b in.gif --replace "#0" a.gif b.gif

       This  command,  however,  replaces  the  first  frame  of `in.gif' with
       `a.gif' and then processes `b.gif' separately:
            gifsicle -b in.gif --replace "#0" a.gif --done b.gif

       Warning: You shouldn't use both frame selections and frame  changes  on
       the same input GIF.

   Image Options
       Image  options  modify  input  images -- by changing their interlacing,
       transparency, and cropping,  for  example.  Image  options  have  three
       forms: `--X', `--no-X', and `--same-X'.  The `--X' form selects a value
       for the feature, the `--no-X' form  turns  off  the  feature,  and  the
       `--same-X'  form  means  that  the  feature's value is copied from each
       input.   The   default   is   always    `--same-X'.     For    example,
       -background="#0000FF"    sets    the    background   color   to   blue,
       --no-background turns the background color off (by setting  it  to  0),
       and  --same-background  uses  input images' existing background colors.
       You can give each option multiple times; for example,
            gifsicle -b -O2 -i a.gif --same-interlace b.gif c.gif
       will make `a.gif' interlaced, but leave `b.gif' and `c.gif'  interlaced
       only if they were already.

       -B color
       --background color
            Set  the  output GIF's background to color.  The argument can have
            the same forms as in the --transparent option below.

       --crop x1,y1-x2,y2
       --crop x1,y1+widthxheight
            Crop the following input frames to a smaller rectangular area. The
            top-left  corner of this rectangle is (x1,y1); you can give either
            the lower-right corner, (x2,y2), or the width and  height  of  the
            rectangle. In the x1,y1+widthxheight form, width and height can be
            zero or negative. A zero dimension means the cropping area goes to
            the  edge  of  the image; a negative dimension brings the cropping
            area that many pixels back  from  the  image  edge.  For  example,
            --crop  2,2+-2x-2  will  shave 2 pixels off each side of the input
            image.  Cropping  takes  place  before  any  rotation,   flipping,
            resizing, or positioning.

       --crop-transparency
            Crop  any transparent borders off the following input frames. This
            happens after any cropping due to the --crop option. It  works  on
            the  raw  input images; for example, any transparency options have
            not yet been applied.

       --flip-horizontal
       --flip-vertical
            Flip the following frames horizontally or vertically.

       -i
       --interlace
            Turn interlacing on.

       -S widthxheight
       --logical-screen widthxheight
            Set    the    output    logical    screen     to     widthxheight.
            --no-logical-screen  sets the output logical screen to the size of
            the largest output frame,  while  --same-logical-screen  sets  the
            output  logical  screen  to  the  largest  input  logical  screen.
            --screen is a synonym for --logical-screen.

       -p x,y
       --position x,y
            Set the following frames' positions to (x,y).  --no-position means
            --position  0,0.  Normally, --position x,y places every succeeding
            frame exactly at x,y. However, if an entire  animation  is  input,
            x,y is treated as the position for the animation.

       --rotate-90
       --rotate-180
       --rotate-270
            Rotate   the   following  frames  by  90,  180,  or  270  degrees.
            --no-rotate turns off any rotation.

       -t color
       --transparent color
            Make color transparent in the following frames.  Color  can  be  a
            colormap  index  (0-255),  a hexadecimal color specification (like
            "#FF00FF" for magenta), or slash- or  comma-separated  red,  green
            and blue values (each between 0 and 255).

   Extension Options
       Extension  options  add  non-visual information to the output GIF. This
       includes names, comments, and generic extensions.

       -x app-name extension
       --app-extension app-name extension
            Add an application extension named app-name  and  with  the  value
            extension to the output GIF.

       -c text
       --comment text
            Add a comment, text, to the output GIF. The comment will be placed
            before the next frame in the stream.

            --no-comments and --same-comments affect all the images following,
            and  apply  only  to  input  GIF  comments,  not  ones  added with
            --comment.

       --extension number extension
            Add an extension numbered number and with the value  extension  to
            the  output  GIF.  Number can be in decimal, octal, hex, or it can
            be a single character like `n', whose ASCII value is used.

            --no-extensions (or  +x)  and  --same-extensions  affect  all  the
            images following, and apply only to input GIF extensions.

       -n text
       --name text
            Set  the  next  frame's  name  to text.  This name is stored as an
            extension in the output GIF (extension number  0xCE,  followed  by
            the characters of the frame name).

            --no-names  and --same-names affect all the images following. They
            apply only to input GIF names, not ones added with --name.

   Animation Options
       Animation options apply to GIF animations, or to individual  frames  in
       GIF  animations.  As  with  image  options, most animation options have
       three  forms,  `--X',  `--no-X',  and  `--same-X',  and  you  can  give
       animation options multiple times; for example,
            gifsicle -b a.gif -d50 "#0" "#1" -d100 "#2" "#3"
       sets the delays of frames 0 and 1 to 50, and frames 2 and 3 to 100.

       -d time
       --delay time
            Set the delay between frames to time in hundredths of a second.

       -D method
       --disposal method
            Set  the  disposal  method  for the following frames to method.  A
            frame's disposal method determines how a viewer should remove  the
            frame  when it's time to display the next.  Method can be a number
            between  0  and  7  (although  only  0  through  3  are  generally
            meaningful),  or one of these names: none (leave the frame visible
            for  future  frames  to  build  upon),  asis  (same  as   "none"),
            background  (or  bg)  (replace  the frame with the background), or
            previous (replace the  frame  with  the  area  from  the  previous
            displayed frame).  --no-disposal means --disposal=none.

       -l[count]
       --loopcount[=count]
            Set the Netscape loop extension to count.  Count is an integer, or
            forever to loop endlessly. If  you  supply  a  --loopcount  option
            without    specifying    count,   Gifsicle   will   use   forever.
            --no-loopcount (the default) turns off looping.

            Set the loop count to one less than the number of times  you  want
            the  animation  to run. An animation with --no-loopcount will show
            every frame once; --loopcount=1 will loop once, thus showing every
            frame  twice; and so forth.  Note that --loopcount=0 is equivalent
            to --loopcount=forever, not --no-loopcount.

       -O[level]
       --optimize[=level]
            Optimize output GIF animations for space.   Level  determines  how
            much optimization is done. There are currently two levels:

            -O1  Stores  only  the  changed portion of each image. This is the
                 default.
            -O2  Also uses transparency to shrink the file further.

            There is no --same-optimize option.

       -U
       --unoptimize
            Unoptimize GIF animations into an easy-to-edit form.

            GIF animations are often optimized (see --optimize) to  make  them
            smaller  and  faster  to  load,  which  unfortunately  makes  them
            difficult to edit.  --unoptimize changes optimized input GIFs into
            unoptimized GIFs, where each frame is a faithful representation of
            what a user would see at that point in the animation.

            There is no --same-unoptimize option.

   Whole-GIF Options
       Whole-GIF options effect entire GIFs as they are read or written.  They
       can be turned off with `--no-option'.

       --careful
            Write  slightly  larger  GIFs  that  avoid  bugs in some other GIF
            implementations. Some Java and Internet Explorer  versions  cannot
            display  the correct, minimal GIFs that Gifsicle produces. Use the
            --careful option if you are  having  problems  with  a  particular
            image.

       --change-color color1 color2
            Change  color1  to  color2 in the following input GIFs. (The color
            arguments have the same forms as in the -t option.) You can change
            multiple colors by giving the option multiple times. Color changes
            don't interfere with one another,  so  you  can  safely  swap  two
            colors  with  `--change-color  color1 color2 --change-color color2
            color1'.   They  all  take  effect  as  an  input  GIF  is   read.
            --no-change-color cancels all color changes.

       -k num
       --colors num
            Reduce  the number of distinct colors in each output GIF to num or
            less.  Num must be between 2 and 256. This can be used  to  shrink
            output GIFs or eliminate any local color tables.

            Unless  you  give  --use-colormap,  an adaptive group of colors is
            chosen from the existing color table.  You can affect this process
            with  the  --color-method  option.  Gifsicle  may  need  to add an
            additional color (making num+1 in all) if there is transparency in
            the image.

       --color-method method
            Determine  how  a  smaller  colormap  is  chosen.  There are three
            choices: diversity, the default, is xv(1)'s  diversity  algorithm,
            which   uses   a   strict   subset   of   the   existing   colors.
            blend-diversity is a modification of this: some color  values  are
            blended  from  a  group of the existing colors.  median-cut is the
            median cut algorithm described by Heckbert.  --method is a synonym
            for --color-method.

       -f
       --dither
            This  option  only  matters  if  the  colormap  was  changed. With
            --dither  on,  Floyd-Steinberg  error   diffusion   is   used   to
            approximate  any  colors that were removed. This looks better, but
            makes bigger files and can cause animation artifacts, so it is off
            by default.

       --resize widthxheight
            Resize the output GIF to widthxheight.  Either width or height may
            be an underscore `_'. If the argument is widthx_, then the  output
            GIF  is  scaled  to  width pixels wide without changing its aspect
            ratio. An analogous operation is performed for _xheight.  Resizing
            happens  after  all  input  frames  have  been combined and before
            optimization. Gifsicle's resize algorithm is designed  for  speed,
            not  quality;  for best-looking results you will need to use other
            tools.

       --resize-width width
            Same as --resize widthx_.

       --resize-height height
            Same as --resize _xheight.

       --scale Xfactor[xYfactor]
            Scale the output GIF's width and height by  Xfactor  and  Yfactor.
            If  Yfactor is not given, it defaults to Xfactor.  Scaling happens
            after all input frames have been combined and before optimization.

       --transform-colormap command
            Command should be a shell command that reads from  standard  input
            and  writes to standard output. Each colormap in the output GIF is
            translated into text colormap format  (see  --use-colormap  below)
            and piped to the command. The output that command generates (which
            should also be in text  colormap  format)  will  be  used  as  the
            colormap instead.

       --use-colormap colormap
            Set the image's colormap to colormap.  Colormap can be web for the
            216-color ``Web-safe palette''; gray for grayscale; bw for  black-
            and-white;  or  the  name  of a file. That file should either be a
            text file (the format is described below) or  a  GIF  file,  whose
            global  colormap  will  be  used.  If --colors=N is also given, an
            N-sized subset of colormap will be used.

            Text colormap files have a very simple format:

            # each non-comment line represents one color, "red green blue"
            # each component should be between 0 and 255
            0 0 0            # like this
            255 255 255

EXAMPLES

       Here are a bunch of examples showing how gifsicle is commonly used.

       First, let's create an animation, `anim.gif':

            % gifsicle a.gif b.gif c.gif d.gif > anim.gif

       This animation will move very quickly: since we didn't specify a delay,
       a  browser  will cycle through the frames as fast as it can. Let's slow
       it down and pause .5 seconds between frames, using the --delay option.

            % gifsicle --delay 50 a.gif b.gif c.gif d.gif > anim.gif

       If we also want the GIF to loop three times, we can use --loopcount:

            % gifsicle -d 50 --loop=3 a.gif b.gif c.gif d.gif > anim.gif

       (Rather than type --delay again, we used  its  short  form,  -d.   Many
       options  have  short  forms;  you  can  see  them  by running `gifsicle
       --help'.  We also abbreviated --loopcount to --loop, which is OK  since
       no other option starts with `loop'.)

       To explode `anim.gif' into its component frames:

            % gifsicle --explode anim.gif
            % ls anim.gif*
            anim.gif      anim.gif.000  anim.gif.001  anim.gif.002  anim.gif.003

       To optimize `anim.gif':

            % gifsicle -b -O2 anim.gif

       To change the second frame of `anim.gif' to `x.gif':

            % gifsicle -b --unoptimize -O2 anim.gif --replace "#1" x.gif

       --unoptimize  is  used since `anim.gif' was optimized in the last step.
       Editing individual  frames  in  optimized  GIFs  is  dangerous  without
       --unoptimize;  frames following the changed frame could be corrupted by
       the change.  Of course, this might be what you want.

       Note  that  --unoptimize  and  --optimize  can  be  on  simultaneously.
       --unoptimize  affects  input GIF files, while --optimize affects output
       GIF files.

       To print information about the first and fourth frames of `anim.gif':

            % gifsicle -I "#0" "#3" < anim.gif
            (information printed)

       To make black the transparent color in all  the  GIFs  in  the  current
       directory, and also print information about each:

            % gifsicle -bII --trans "#000000" *.gif
            (information printed)

       Giving  -I  twice  forces normal output to occur. With only one -I, the
       GIFs would not have changed on disk.

       To change `anim.gif' to use a 64-color subset of the Web-safe palette:

            % gifsicle -b --colors=64 --use-col=web anim.gif

       To make a dithered black-and-white version of `anim.gif':

            % gifsicle --dither --use-col=bw anim.gif > anim-bw.gif

       To overlay one GIF atop another -- producing  a  one-frame  output  GIF
       that  looks  like  the  superposition of the two inputs -- use gifsicle
       twice:

            % gifsicle bottom.gif top.gif | gifsicle -U "#1" > result.gif

BUGS

       Some  optimized  output  GIFs  may  appear  incorrectly  on  some   GIF
       implementations (for example, Java's); see the --careful option.

       Please    email   suggestions,   additions,   patches   and   bugs   to
       kohler@cs.ucla.edu.

SEE ALSO

       For a tutorial on GIF images and animations, you might try some of  the
       resources        listed        on-line       at       webreference.com:
       http://www.webreference.com/authoring/graphics/animation.html

AUTHORS

       Eddie Kohler <ekohler@gmail.com>
       http://www.cs.ucla.edu/~kohler/
       He wrote it.

       Anne Dudfield <annied@frii.com>
       http://www.frii.com/~annied/
       She named it.

       Hans Dinsen-Hansen <dino@danbbs.dk>
       http://www.danbbs.dk/~dino/
       Adaptive tree method for GIF writing.

       http://www.lcdf.org/gifsicle/
       The gifsicle home page.