GIFSICLE(1)GIFSICLE(1)NAMEgifsicle - manipulates GIF images and animations
SYNOPSISgifsicle [options, frames, and filenames]...
DESCRIPTIONgifsicle 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 stan-
dard 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 out-
put. To interlace all the GIFs in the current directory,
you could say:
% gifsicle--batch -i *.gif
gifsicle is good at creating and manipulating GIF anima-
tions. 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 file-
name `-', 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 com-
bine 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 gener-
ate. 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 named frames to files
`xxx.name' instead of `xxx.frame-number'.
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 ex-
tensions 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. If
you give two --info or -I options, however, the de-
scription will be printed on standard error and out-
put will occur as usual.
-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.
--multifile
Accept concatenated GIF files (multiple GIF image
files concatenated into one big file; each image file
may, of course, contain multiple frames). This op-
tion is intended for scripts. For example, to merge
an unknown number of GIF images into a single anima-
tion, 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 anima-
tions, 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 single quotes around
the frame specification. The `#' character has special
meaning for many shells, so you may need to quote it.)
What gifsicle does 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 se-
lected frames are modified; other frames remain unchanged.
In explode mode, only the selected frames are exploded in-
to 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 un-
til 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' separate-
ly:
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 in-
terlacing, transparency, and cropping, for example). Each
image option stays in effect until the next image option
in the same category. They have three forms: `--X',
`--no-X', and `--same-X'. The default is `--same-X',
which means that X's value is copied from each input. The
converse, `--no-X', erases X; for instance, --no-interlace
turns interlacing off, while --no-comments strips com-
ments. Only the `--X' form is generally described.
-B color
--background color
Set the output GIF's background to color. The argu-
ment 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 rectan-
gular 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 dimen-
sion 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.
(Note: This behavior is different from versions 1.30
and before.) Cropping takes place on the raw input
image, 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 image; 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, --po-
sition 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 de-
grees. --no-rotate turns off any rotation.
-t color
--transparent color
Make color transparent in the following frames. Col-
or 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 exten-
sions.
-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 im-
ages 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 deci-
mal, 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 are image options applying only to GIF
animations. Most of them act like image options, and have
the same three forms (see above).
-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. Method can be a number between 0 and 7 (al-
though only 0 through 3 are generally meaningful), or
one of these names: none, asis, background (or bg),
previous. --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. The default
is forever. --no-loopcount 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.
-O[level]
--optimize[=level]
Optimize output GIF animations for space. Level de-
termines 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 fur-
ther.
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 unfor-
tunately 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 Ex-
plorer 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 op-
tion. 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 di-
versity 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 syn-
onym 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. Re-
sizing happens after all input frames have been com-
bined and before optimization.
--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 glob-
al colormap will be used. If --colors=N is also giv-
en, 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 com-
monly 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 --loop-
count 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 simultane-
ously. --unoptimize affects input GIF files, while --op-
timize 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 --care-
ful option.
Please email suggestions, additions, patches and bugs to
kohler@icir.org.
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/anima-
tion.html
AUTHORS
Eddie Kohler <kohler@icir.org>
http://www.icir.org/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.
Version 1.37 11 Feb 2002 GIFSICLE(1)
