Man Linux: Main Page and Category List

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.