Provided by: gifsicle_1.64-1_amd64 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; higher levels take longer, but may have better  results.  There  are  currently
            three levels:

            -O1  Stores only the changed portion of each image. This is the default.
            -O2  Also uses transparency to shrink the file further.
            -O3  Try several optimization methods (usually slower, sometimes better results).

            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
       --resize-height height
            Like --resize widthx_ and --resize _xheight respectively.

       --resize-fit widthxheight
            Like --resize, but resizes the output GIF to fit within a rectangle  with  dimensions
            widthxheight.   The  GIF's  aspect ratio remains unchanged. No resize is performed if
            the GIF already fits within the given rectangle. Either width or  height  may  be  an
            underscore `_', which is treated as infinity.

       --resize-fit-width width
       --resize-fit-height height
            Like --resize-fit widthx_ and --resize-fit _xheight respectively.

       --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

       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

       Giving  -I  twice  forces  normal output to occur. With only one -I, the GIFs would not be
       modified.

       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.