Extension Options

--app-extension app-name extension

Add an application extension named app-name and with the value extension to the output GIF. [--no-app-extensions] removes application extensions from the input images.

-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] removes comments from the input images.

--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 oqncq, whose ASCII value is used. [--no-extensions] (or [+x] removes extensions from the input images.

-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] removes name extensions from the input images.

Animation Options

gifsicle -b a.gif -d50 "#0" "#1" -d100 "#2" "#3"

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

Other optimization flags provide finer-grained control.

[-Okeep-empty]

Preserve empty transparent frames (they are dropped by default).

You may also be interested in other options for shrinking GIFs, such as [-k] and [--no-extensions]

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

Image Transformation Options

--resize widthxheight

Resize the output GIF to the given width and height. If width or height is an underscore oq_cq, that dimension is chosen so that the aspect ratio remains unchanged. Resizing happens after all input frames have been combined and before optimization. Resizing uses logical screen dimensions; if the input stream has an unusual logical screen (many GIF displayers ignore logical screens), you may want to provide [--no-logical-screen] (or [+S] to reset it so gifsicle uses image dimensions instead. See also [--resize-method]

--resize-width width

--resize-height height

Resize to a given width or height, preserving aspect ratio. Equivalent to --resize widthx_ or --resize _xheight.

--resize-fit widthxheight

--resize-touch widthxheight

Resize the output GIF to fit within a rectangle with dimensions widthxheight. The aspect ratio remains unchanged. The [--resize-fit] option only shrinks the image---no resize is performed if the GIF already fits within the rectangle. Either width or height may be an underscore oq_cq, which leaves that dimension unconstrained.

--resize-fit-width width

--resize-fit-height height

--resize-touch-width width

--resize-touch-height height

Like --resize-fit and [--resize-touch] but constrains only one dimension.

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

--resize-method method

Set the method used to resize images. The oqsamplecq method runs very quickly, but when shrinking images, it produces noisy results. The oqmixcq method is somewhat slower, but produces better-looking results. The default method is currently oqmixcq.

Details: The resize methods differ most when shrinking images. The oqsamplecq method is a point sampler: each pixel position in the output image maps to exactly one pixel position in the input. When shrinking, full rows and columns from the input are dropped. The other methods use all input pixels, which generally produces better-looking images. The oqboxcq method, a box sampler, is faster than the more complex filters and produces somewhat sharper results, but there will be anomalies when shrinking images by a small amount in one dimension. (Some output pixels will correspond to exactly 1 input row or column, while others will correspond to exactly 2 input rows or columns.) The oqmixcq method is a full bilinear interpolator. This is slower and produces somewhat blurrier results, but avoids anomalies.

Gifsicle also supports more complex resamplers, including Catmull-Rom cubic resampling (oqcatromcq), the Mitchell-Netravali filter (oqmitchellcq), a 2-lobed Lanczos filter (oqlanczos2cq), and a 3-lobed Lanczos filter (oqlanczos3cq). These filters are slower still, but can give sharper, better results.

--resize-colors n

Allow Gifsicle to add intermediate colors when resizing images. Normally, Gifsicle's resize algorithms use input images' color palettes without changes. When shrinking images with very few colors (e.g., pure black-and-white images), adding intermediate colors can improve the results. Example: --resize-colors 64 allows Gifsicle to add intermediate colors for images that have fewer than 64 input colors.

Color Options

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

Normally, an adaptive group of colors is chosen from the existing color table. You can affect this process with the [--color-method] option or by giving your own colormap with [--use-colormap] 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. oqdiversitycq, the default, is xv(1)'s diversity algorithm, which uses a strict subset of the existing colors and generally produces good results. oqblend-diversitycq is a modification of this: some color values are blended from groups of existing colors. oqmedian-cutcq is the median cut algorithm described by Heckbert. [--method] is a synonym for [--color-method]

-f

[--dither [=method]]

When [--dither] is on and the colormap is changed, combinations of colors are used to approximate missing colors. This looks better, but makes bigger files and can cause animation artifacts, so it is off by default.

Specify a dithering algorithm with the optional method argument. The default, oqfloyd-steinbergcq, uses Floyd-Steinberg error diffusion. This usually looks best, but can cause animation artifacts, because dithering choices will vary from frame to frame. Gifsicle also supports ordered dithering algorithms that avoid animation artifacts. The oqro64cq mode uses a large, random-looking pattern and generally produces good results. The oqo3cq, oqo4cq, and oqo8cq modes use smaller, more regular patterns. The oqorderedcq mode chooses a good ordered dithering algorithm. For special effects, try the halftone modes oqhalftonecq, oqsquarehalftonecq, and oqdiagonalcq. Some modes take optional parameters using commas. The halftone modes take a cell size and a color limit: oqhalftone,10,3cq creates 10-pixel wide halftone cells where each cell uses up to 3 colors.

--gamma gamma

Set the gamma correction to gamma, which can be a real number or oqsrgbcq. Roughly speaking, higher numbers exaggerate shadows and lower numbers exaggerate highlights. The default is the function defined by the standard sRGB color space, which usually works well. (Its effects are similar to --gamma=2.2.) Gifsicle uses gamma correction when choosing a color palette (--colors) and when dithering (--dither).

--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.) 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 oq--change-color color1 color2 --change-color color2 color1cq. They all take effect as an input GIF is read. [--no-change-color] cancels all color changes.

--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 replace the input colormap. The replacement doesn't consider color matching, so pixels that used color slot n in the input will still use color slot n in the output.

--use-colormap colormap

Change the image to use colormap. Each pixel in the image is changed to the closest match in colormap (or, if [--dither] is on, to a dithered combination of colors in colormap). Colormap can be web for the 216-color lqWeb-safe paletterq; 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 use this 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
; or use web hex notation
#ffffff          ; like this

EXAMPLES

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 oqgifsicle --helpcq. We also abbreviated [--loopcount] to [--loop] which is OK since no other option starts with oqloopcq.)

To explode oqanim.gifcq 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 oqanim.gifcq:

gifsicle -b -O2 anim.gif

To change the second frame of oqanim.gifcq to oqx.gifcq:

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

[--unoptimize] is used since oqanim.gifcq 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 oqanim.gifcq:

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 oqanim.gifcq 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 oqanim.gifcq:

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

Please email suggestions, additions, patches and bugs to ekohler@gmail.com.

SEE ALSO

AUTHORS

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

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

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