1GIFSICLE(1) General Commands Manual GIFSICLE(1)
2
6 gifsicle - manipulates GIF images and animations
7
9 gifsicle [options, frames, and filenames]...
10
12 gifsicle is a powerful command-line program for creating, editing,
13 manipulating, and getting information about GIF images and animations.
14
16 Without options, gifsicle acts like a filter: you feed it a GIF on
17 standard input, and it writes that GIF on standard output. That means
18 these two commands do the same thing:
19 % gifsicle < in.gif > out.gif
21 % gifsicle < in.gif | gifsicle | gifsicle > out.gif
22 Not too interesting. Most times you'll tell gifsicle to alter its
24 inputs by giving it command line options. The -i option, for example,
25 tells it to interlace its input files:
26 % gifsicle -i < pic.gif > interlaced-pic.gif
28 To modify GIF files in place, you should use the --batch option. With
30 --batch, gifsicle will modify the files you specify instead of writing
31 a new file to the standard output. To interlace all the GIFs in the
32 current directory, you could say:
33 % gifsicle --batch -i *.gif
35 gifsicle is good at creating and manipulating GIF animations. The sim‐
37 plest way to create an animation is to give more than one input file,
38 which gifsicle will combine to create a ``flipbook'' animation:
39 % gifsicle pic1.gif pic2.gif pic3.gif > animation.gif
41 Use options like --delay, --loopcount, and --optimize to tune your ani‐
43 mations; see their descriptions for more details.
44 The bulk of this manual page indexes gifsicle's options and describes
46 them in gory detail. New users may want to skip to the Examples section
47 at the end.
48
50 This index is meant to help you find options that do what you want.
51 Concepts are on the left, relevant gifsicle options are on the right.
52 Animations, changing frame selections, frame changes, etc.
54 disposal --disposal
55 looping --loopcount
56 portions of frame selections
57 smaller --optimize, --colors
58 speed --delay
59 Bad output --careful
60 Background color --background
61 Colors, changing --change-color, --use-colormap, --dither,
62 --transform-colormap
63 reducing number --colors, --dither
64 Comments --comment
65 Extensions --extension, --app-extension, --extension-info
66 File size --optimize, --unoptimize, --colors
67 Image transformations
68 cropping --crop, --crop-transparency
70 flipping --flip-*
71 resizing --resize, --scale
72 rotating --rotate-*
73 Grayscale --use-colormap
74 Interlacing --interlace
75 Positioning frames --position
76 Screen, logical --logical-screen
77 Selecting frames frame selections (like '#0')
78 Transparency --transparent
79 Warnings --no-warnings
80 Web-safe palette --use-colormap
81
83 gifsicle's command line consists of GIF input files and options. Most
84 options start with a dash (-) or plus (+); frame selections, a kind of
85 option, start with a number sign (#). Anything else is a GIF input
86 file.
87 gifsicle reads and processes GIF input files in order. If no GIF input
89 file is given, or you give the special filename `-', it reads from the
90 standard input.
91 gifsicle exits with status 0 if there were no errors and status 1 oth‐
93 erwise.
94
96 Every option has a long form, `--long-descriptive-name'. You don't
97 need to type the whole long descriptive name, just enough to make it
98 unambiguous.
99 Some options also have a short form, `-X'. You can combine short op‐
101 tions if they don't take arguments: `-IIb' is the same as `-I -I -b'.
102 But be careful with options that do take arguments: `-cblah' means `-c
103 blah', not `-c -b -l -a -h'.
104 Many options also have a converse, `--no-option', which turns off the
106 option. You can turn off a short option `-X' by saying `+X' instead.
107 Mode Options
109 Mode options tell gifsicle what kind of output to generate. There can
110 be at most one, and it must precede any GIF inputs.
111 --merge, -m
113 Combine all GIF inputs into one file with multiple frames and
114 write that file to the standard output. This is the default mode.
115 --batch, -b
117 Modify each GIF input in place by reading and writing to the same
118 filename. (GIFs read from the standard input are written to the
119 standard output.)
120 --explode, -e
122 Create an output GIF for each frame of each input file. The output
123 GIFs are named `xxx.000', `xxx.001', and so on, where `xxx' is the
124 name of the input file (or whatever you specified with `--output')
125 and the numeric extension is the frame number.
126 --explode-by-name, -E
128 Same as --explode, but write any named frames to files `xxx.name'
129 instead of `xxx.frame-number'. Frames are named using the
130 `--name' option.
131 General Options
133 General options control the information gifsicle prints and where it
134 writes its output. The info options and --verbose can be turned off
135 with `--no-X'.
136 --color-info
138 Like --info, but also print information about input files' col‐
139 ormaps. --cinfo is a synonym for --color-info.
140 --extension-info
142 Like --info, but also print any unrecognized GIF extensions in a
143 hexdump(1)-like format. --xinfo is a synonym for
144 --extension-info.
145 --help, -h
147 Print usage information and exit.
148 --info, -I
150 Print a human-readable description of each input GIF to the stan‐
151 dard output, or whatever file you specify with -o. This option
152 suppresses normal output, and cannot be combined with mode options
153 like --batch. If you give two --info or -I options, however, nor‐
154 mal output is not suppressed; information will be printed on stan‐
155 dard error, and you can supply a mode option.
156 -o file
158 --output file
159 Send output to file. The special filename `-' means the standard
160 output.
161 --verbose, -V
163 Print progress information (files read and written) to standard
164 error.
165 --no-warnings, -w
167 Suppress all warning messages.
168 --version
170 Print the version number and some short non-warranty information
171 and exit.
172 --conserve-memory
174 Conserve memory usage at the expense of processing time. This may
175 be useful if you are processing large GIFs on a computer without
176 very much memory.
177 --nextfile
179 Allow input files to contain multiple concatenated GIF images. If
180 a filename appears multiple times on the command line, gifsicle
181 will read a new image from the file each time. This option can
182 help scripts avoid the need for temporary files. For example, to
183 create an animated GIF with three frames with different delays,
184 you might run "gifsicle --nextfile -d10 - -d20 - -d30 - > out.gif"
185 and write the three GIF images, in sequence, to gifsicle's stan‐
186 dard input.
187 --multifile
189 Like --nextfile, but read as many GIF images as possible from each
190 file. This option is intended for scripts. For example, to merge
191 an unknown number of GIF images into a single animation, run "gif‐
192 sicle --multifile - > out.gif" and write the GIF images, in se‐
193 quence, to gifsicle's standard input. Any frame selections apply
194 only to the last file in the concatenation.
195 Frame Selections
197 A frame selection tells gifsicle which frames to use from the current
198 input file. They are useful only for animations, as non-animated GIFs
199 only have one frame. Here are the acceptable forms for frame specifica‐
200 tions.
201 #num Select frame num. (The first frame is `#0'. Negative num‐
203 bers count backwards from the last frame, which is `#-1'.)
204 #num1-num2 Select frames num1 through num2.
205 #num1- Select frames num1 through the last frame.
206 #name Select the frame named name.
207 For example,
209 gifsicle happy.gif
210 will use all of `happy.gif's frames, while
211 gifsicle happy.gif "#0"
212 will only use the first. (Note the quotes around the frame specifica‐
213 tion. The `#' character has special meaning for many shells, so you may
214 need to quote it.)
215 The action performed with the selected frames depends on the current
217 mode. In merge mode, only the selected frames are merged into the out‐
218 put GIF. In batch mode, only the selected frames are modified; other
219 frames remain unchanged. In explode mode, only the selected frames are
220 exploded into output GIFs.
221 Frame Change Options
223 Frame change options insert new frames into an animation or replace or
224 delete frames that already exist. Some things -- for example, changing
225 one frame in an animation -- are difficult to express with frame selec‐
226 tions, but easy with frame changes.
227 --delete frames [frames...]
229 Delete frames from the input GIF.
230 --insert-before frame other-GIFs
232 Insert other-GIFs before frame in the input GIF.
233 --append other-GIFs
235 Append other-GIFs to the input GIF.
236 --replace frames other-GIFs
238 Replace frames from the input GIF with other-GIFs.
239 --done
241 Complete the current set of frame changes.
242 The frames arguments are frame selections (see above). These arguments
244 always refer to frames from the original input GIF. So, if `a.gif' has
245 3 frames and `b.gif' has one, this command
246 gifsicle a.gif --delete "#0" --replace "#2" b.gif
247 will produce an output animation with 2 frames: `a.gif' frame 1, then
248 `b.gif'.
249 The other-GIFs arguments are any number of GIF input files and frame
251 selections. These images are combined in merge mode and added to the
252 input GIF. The other-GIFs last until the next frame change option, so
253 this command replaces the first frame of `in.gif' with the merge of
254 `a.gif' and `b.gif':
255 gifsicle -b in.gif --replace "#0" a.gif b.gif
256 This command, however, replaces the first frame of `in.gif' with
258 `a.gif' and then processes `b.gif' separately:
259 gifsicle -b in.gif --replace "#0" a.gif --done b.gif
260 Warning: You shouldn't use both frame selections and frame changes on
262 the same input GIF.
263 Image Options
265 Image options modify input images -- by changing their interlacing,
266 transparency, and cropping, for example. Image options have three
267 forms: `--X', `--no-X', and `--same-X'. The `--X' form selects a value
268 for the feature, the `--no-X' form turns off the feature, and the
269 `--same-X' form means that the feature's value is copied from each in‐
270 put. The default is always `--same-X'. For example, -back‐
271 ground="#0000FF" sets the background color to blue, --no-background
272 turns the background color off (by setting it to 0), and --same-back‐
273 ground uses input images' existing background colors. You can give each
274 option multiple times; for example,
275 gifsicle -b -O2 -i a.gif --same-interlace b.gif c.gif
276 will make `a.gif' interlaced, but leave `b.gif' and `c.gif' interlaced
277 only if they were already.
278 -B color
280 --background color
281 Set the output GIF's background to color. The argument can have
282 the same forms as in the --transparent option below.
283 --crop x1,y1-x2,y2
285 --crop x1,y1+widthxheight
286 Crop the following input frames to a smaller rectangular area. The
287 top-left corner of this rectangle is (x1,y1); you can give either
288 the lower-right corner, (x2,y2), or the width and height of the
289 rectangle. In the x1,y1+widthxheight form, width and height can be
290 zero or negative. A zero dimension means the cropping area goes to
291 the edge of the image; a negative dimension brings the cropping
292 area that many pixels back from the image edge. For example,
293 --crop 2,2+-2x-2 will shave 2 pixels off each side of the input
294 image. Cropping takes place before any rotation, flipping, resiz‐
295 ing, or positioning.
296 --crop-transparency
298 Crop any transparent borders off the following input frames. This
299 happens after any cropping due to the --crop option. It works on
300 the raw input images; for example, any transparency options have
301 not yet been applied.
302 --flip-horizontal
304 --flip-vertical
305 Flip the following frames horizontally or vertically.
306 -i
308 --interlace
309 Turn interlacing on.
310 -S widthxheight
312 --logical-screen widthxheight
313 Set the output logical screen to widthxheight. --no-logi‐
314 cal-screen sets the output logical screen to the size of the
315 largest output frame, while --same-logical-screen sets the output
316 logical screen to the largest input logical screen. --screen is a
317 synonym for --logical-screen.
318 -p x,y
320 --position x,y
321 Set the following frames' positions to (x,y). --no-position means
322 --position 0,0. Normally, --position x,y places every succeeding
323 frame exactly at x,y. However, if an entire animation is input,
324 x,y is treated as the position for the animation.
325 --rotate-90
327 --rotate-180
328 --rotate-270
329 Rotate the following frames by 90, 180, or 270 degrees. --no-ro‐
330 tate turns off any rotation.
331 -t color
333 --transparent color
334 Make color transparent in the following frames. Color can be a
335 colormap index (0-255), a hexadecimal color specification (like
336 "#FF00FF" for magenta), or slash- or comma-separated red, green
337 and blue values (each between 0 and 255).
338 Extension Options
340 Extension options add non-visual information to the output GIF. This
341 includes names, comments, and generic extensions.
342 -x app-name extension
344 --app-extension app-name extension
345 Add an application extension named app-name and with the value ex‐
346 tension to the output GIF.
347 -c text
349 --comment text
350 Add a comment, text, to the output GIF. The comment will be placed
351 before the next frame in the stream.
352 --no-comments and --same-comments affect all the images following,
354 and apply only to input GIF comments, not ones added with --com‐
355 ment.
356 --extension number extension
358 Add an extension numbered number and with the value extension to
359 the output GIF. Number can be in decimal, octal, hex, or it can
360 be a single character like `n', whose ASCII value is used.
361 --no-extensions (or +x) and --same-extensions affect all the im‐
363 ages following, and apply only to input GIF extensions.
364 -n text
366 --name text
367 Set the next frame's name to text. This name is stored as an ex‐
368 tension in the output GIF (extension number 0xCE, followed by the
369 characters of the frame name).
370 --no-names and --same-names affect all the images following. They
372 apply only to input GIF names, not ones added with --name.
373 Animation Options
375 Animation options apply to GIF animations, or to individual frames in
376 GIF animations. As with image options, most animation options have
377 three forms, `--X', `--no-X', and `--same-X', and you can give anima‐
378 tion options multiple times; for example,
379 gifsicle -b a.gif -d50 "#0" "#1" -d100 "#2" "#3"
380 sets the delays of frames 0 and 1 to 50, and frames 2 and 3 to 100.
381 -d time
383 --delay time
384 Set the delay between frames to time in hundredths of a second.
385 -D method
387 --disposal method
388 Set the disposal method for the following frames to method. A
389 frame's disposal method determines how a viewer should remove the
390 frame when it's time to display the next. Method can be a number
391 between 0 and 7 (although only 0 through 3 are generally meaning‐
392 ful), or one of these names: none (leave the frame visible for fu‐
393 ture frames to build upon), asis (same as "none"), background (or
394 bg) (replace the frame with the background), or previous (replace
395 the frame with the area from the previous displayed frame).
396 --no-disposal means --disposal=none.
397 -l[count]
399 --loopcount[=count]
400 Set the Netscape loop extension to count. Count is an integer, or
401 forever to loop endlessly. If you supply a --loopcount option
402 without specifying count, Gifsicle will use forever. --no-loop‐
403 count (the default) turns off looping.
404 Set the loop count to one less than the number of times you want
406 the animation to run. An animation with --no-loopcount will show
407 every frame once; --loopcount=1 will loop once, thus showing every
408 frame twice; and so forth. Note that --loopcount=0 is equivalent
409 to --loopcount=forever, not --no-loopcount.
410 -O[level]
412 --optimize[=level]
413 Optimize output GIF animations for space. Level determines how
414 much optimization is done. There are currently two levels:
415 -O1 Stores only the changed portion of each image. This is the
417 default.
418 -O2 Also uses transparency to shrink the file further.
419 There is no --same-optimize option.
421 -U
423 --unoptimize
424 Unoptimize GIF animations into an easy-to-edit form.
425 GIF animations are often optimized (see --optimize) to make them
427 smaller and faster to load, which unfortunately makes them diffi‐
428 cult to edit. --unoptimize changes optimized input GIFs into un‐
429 optimized GIFs, where each frame is a faithful representation of
430 what a user would see at that point in the animation.
431 There is no --same-unoptimize option.
433 Whole-GIF Options
435 Whole-GIF options effect entire GIFs as they are read or written. They
436 can be turned off with `--no-option'.
437 --careful
439 Write slightly larger GIFs that avoid bugs in some other GIF im‐
440 plementations. Some Java and Internet Explorer versions cannot
441 display the correct, minimal GIFs that Gifsicle produces. Use the
442 --careful option if you are having problems with a particular im‐
443 age.
444 --change-color color1 color2
446 Change color1 to color2 in the following input GIFs. (The color
447 arguments have the same forms as in the -t option.) You can change
448 multiple colors by giving the option multiple times. Color changes
449 don't interfere with one another, so you can safely swap two col‐
450 ors with `--change-color color1 color2 --change-color color2 col‐
451 or1'. They all take effect as an input GIF is read.
452 --no-change-color cancels all color changes.
453 -k num
455 --colors num
456 Reduce the number of distinct colors in each output GIF to num or
457 less. Num must be between 2 and 256. This can be used to shrink
458 output GIFs or eliminate any local color tables.
459 Unless you give --use-colormap, an adaptive group of colors is
461 chosen from the existing color table. You can affect this process
462 with the --color-method option. Gifsicle may need to add an addi‐
463 tional color (making num+1 in all) if there is transparency in the
464 image.
465 --color-method method
467 Determine how a smaller colormap is chosen. There are three choic‐
468 es: diversity, the default, is xv(1)'s diversity algorithm, which
469 uses a strict subset of the existing colors. blend-diversity is a
470 modification of this: some color values are blended from a group
471 of the existing colors. median-cut is the median cut algorithm
472 described by Heckbert. --method is a synonym for --color-method.
473 -f
475 --dither
476 This option only matters if the colormap was changed. With
477 --dither on, Floyd-Steinberg error diffusion is used to approxi‐
478 mate any colors that were removed. This looks better, but makes
479 bigger files and can cause animation artifacts, so it is off by
480 default.
481 --resize widthxheight
483 Resize the output GIF to widthxheight. Either width or height may
484 be an underscore `_'. If the argument is widthx_, then the output
485 GIF is scaled to width pixels wide without changing its aspect ra‐
486 tio. An analogous operation is performed for _xheight. Resizing
487 happens after all input frames have been combined and before opti‐
488 mization. Gifsicle's resize algorithm is designed for speed, not
489 quality; for best-looking results you will need to use other
490 tools.
491 --resize-width width
493 Same as --resize widthx_.
494 --resize-height height
496 Same as --resize _xheight.
497 --scale Xfactor[xYfactor]
499 Scale the output GIF's width and height by Xfactor and Yfactor.
500 If Yfactor is not given, it defaults to Xfactor. Scaling happens
501 after all input frames have been combined and before optimization.
502 --transform-colormap command
504 Command should be a shell command that reads from standard input
505 and writes to standard output. Each colormap in the output GIF is
506 translated into text colormap format (see --use-colormap below)
507 and piped to the command. The output that command generates (which
508 should also be in text colormap format) will be used as the col‐
509 ormap instead.
510 --use-colormap colormap
512 Set the image's colormap to colormap. Colormap can be web for the
513 216-color ``Web-safe palette''; gray for grayscale; bw for black-
514 and-white; or the name of a file. That file should either be a
515 text file (the format is described below) or a GIF file, whose
516 global colormap will be used. If --colors=N is also given, an
517 N-sized subset of colormap will be used.
518 Text colormap files have a very simple format:
520 # each non-comment line represents one color, "red green blue"
522 # each component should be between 0 and 255
523 0 0 0 # like this
524 255 255 255
526 Here are a bunch of examples showing how gifsicle is commonly used.
527 First, let's create an animation, `anim.gif':
529 % gifsicle a.gif b.gif c.gif d.gif > anim.gif
531 This animation will move very quickly: since we didn't specify a delay,
533 a browser will cycle through the frames as fast as it can. Let's slow
534 it down and pause .5 seconds between frames, using the --delay option.
535 % gifsicle --delay 50 a.gif b.gif c.gif d.gif > anim.gif
537 If we also want the GIF to loop three times, we can use --loopcount:
539 % gifsicle -d 50 --loop=3 a.gif b.gif c.gif d.gif > anim.gif
541 (Rather than type --delay again, we used its short form, -d. Many op‐
543 tions have short forms; you can see them by running `gifsicle --help'.
544 We also abbreviated --loopcount to --loop, which is OK since no other
545 option starts with `loop'.)
546 To explode `anim.gif' into its component frames:
548 % gifsicle --explode anim.gif
550 % ls anim.gif*
551 anim.gif anim.gif.000 anim.gif.001 anim.gif.002 anim.gif.003
552 To optimize `anim.gif':
554 % gifsicle -b -O2 anim.gif
556 To change the second frame of `anim.gif' to `x.gif':
558 % gifsicle -b --unoptimize -O2 anim.gif --replace "#1" x.gif
560 --unoptimize is used since `anim.gif' was optimized in the last step.
562 Editing individual frames in optimized GIFs is dangerous without --un‐
563 optimize; frames following the changed frame could be corrupted by the
564 change. Of course, this might be what you want.
565 Note that --unoptimize and --optimize can be on simultaneously. --un‐
567 optimize affects input GIF files, while --optimize affects output GIF
568 files.
569 To print information about the first and fourth frames of `anim.gif':
571 % gifsicle -I "#0" "#3" < anim.gif
573 (information printed)
574 To make black the transparent color in all the GIFs in the current di‐
576 rectory, and also print information about each:
577 % gifsicle -bII --trans "#000000" *.gif
579 (information printed)
580 Giving -I twice forces normal output to occur. With only one -I, the
582 GIFs would not have changed on disk.
583 To change `anim.gif' to use a 64-color subset of the Web-safe palette:
585 % gifsicle -b --colors=64 --use-col=web anim.gif
587 To make a dithered black-and-white version of `anim.gif':
589 % gifsicle --dither --use-col=bw anim.gif > anim-bw.gif
591 To overlay one GIF atop another -- producing a one-frame output GIF
593 that looks like the superposition of the two inputs -- use gifsicle
594 twice:
595 % gifsicle bottom.gif top.gif | gifsicle -U "#1" > result.gif
597
599 Some optimized output GIFs may appear incorrectly on some GIF implemen‐
600 tations (for example, Java's); see the --careful option.
601 Please email suggestions, additions, patches and bugs to
603 kohler@cs.ucla.edu.
604
606 For a tutorial on GIF images and animations, you might try some of the
607 resources listed on-line at webreference.com: http://www.webrefer‐
608 ence.com/authoring/graphics/animation.html
609
611 Eddie Kohler <ekohler@gmail.com>
612 http://www.cs.ucla.edu/~kohler/
613 He wrote it.
614 Anne Dudfield <annied@frii.com>
616 http://www.frii.com/~annied/
617 She named it.
618 Hans Dinsen-Hansen <dino@danbbs.dk>
620 http://www.danbbs.dk/~dino/
621 Adaptive tree method for GIF writing.
622 http://www.lcdf.org/gifsicle/
624 The gifsicle home page.
625Version 1.60 2 May 2008 GIFSICLE(1)