GifBuilder 1.0
Documentation
If you don't read this document, please read at least the shortcuts and tips by
choosing GifBuilder Shortcuts in the Help menu ('?' at the right of the menu
bar).
The tutorial in the Tutorial folder is also a good way to learn step by step
how to create basic animations and use them on the Web.
GifBuilder is a scriptable utility for creating animated GIF files. Its input
is an existing animated GIF, a bunch of PICT, GIF, TIFF and/or Photoshop files,
a QuickTime movie, a PICS file, an Adobe Premiere FilmStrip 1.0 file, or the
layers of an RGB or grayscale Adobe Photoshop 3.0 file, and its output is a
GIF89a file with multiple images.
Options include pixel depth, color palette, interlacing, transparency,
interframe delay, disposal method, frame offset, looping and dithering.
GifBuilder should ultimately be placed onto many ftp archives, including
Info-Mac (in gst/grf), Umich (in graphics/graphicsutil) and their mirrors.
Please read this document carefully if you want to get the best of GifBuilder.
There are several shortcuts which can make your work much easier.
Basic Usage
1) Draw each frame
Use any drawing program able to save as PICT, GIF, TIFF or Photoshop 2.5/3.0.
Save frames in a new folder to make
their retrieval easier. If you name them in alphabetical order (e.g. 0001.tiff,
0002.tiff, etc.), you can easily sort them later.
2) Collect frames in GifBuilder Launch GifBuilder, be sure that there aren't
frames from a previous animation in the Frames window (if that's the case,
choose New in the File menu), and drag the frames from the Finder into the
Frames window. Supported files are PICT, GIF, TIFF (baseline) and Photoshop 2.5
or 3 (bitmap, grayscale (or duotone, which are read as grayscale), indexed or
RGB). If you don't have the Drag Manager (standard since MacOS 7.5), you can
add each frame by choosing Add Frame in the File menu. You can also copy a
picture from another application, or drag it. Then, check that they're in the
correct order and, if necessary, change their order by dragging frames. You can
also remove the selected frame(s) by choosing Clear in the Edit menu or hitting
Backspace, sort them and reverse their order. Double-clicking a frame will open
it in its own application; if you modify it, save it and choose Reload Frames
in the File menu to update your changes (the Save command always use the disk
copy).
3) Set the options
Set the standard graphic options (pixel depth, color palette and dithering);
the GIF options (size, interlacing, transparency); and the animation options
(interframe delay, disposal method, frames position and looping). Some of these
properties (transparency, interframe delay, disposal method and position) are
attached to individual frames; select the frame or group of frames before
changing them. If no frame is selected, the settings will apply to the default
values used for images you import. See below for more details. You can save the
default options by choosing Save Options in the Options menu. Tip: Most options
displayed in the Frames window can be changed by clicking or double-clicking
them.
4) Check the animation
Choose Run in the Animation menu. To display a specific frame, stop the
animation and select it in the Frames window. You can also use the Home, End,
Up and Down keys. To start from the first selected frame, choose Continue. In
the Animation window, you can move a frame by dragging it (the frame will be
drawn on an onion skin if you hold down the Option key), or select the
transparent color by Shift-clicking it (you can do it even when the animation
is running, but depending on the speed, you'd better stop it first!). To
position precisely the selected frames, choose Frame Position in the Options
menu, or use the arrow keys (hold down the Option key if the Frames window is
active).
5) Build the animation
Choose Save As in the File menu. Alternatively, you can drag the Animated GIF
icon from the animation window to any location in the Finder.
6) Add an image tag to your HTML page
Choose Copy HTML Image Tag in the Edit menu, and paste the resulting IMG tag in
your HTML page. IMG fields contain a relative URL with the current name of the
animation as well as the width and height. Of course, you can edit the tag to
change the path of the image or add optional fields like ALT and ALIGN.
Alternatively, you can drag the symbol from the animation window to your
HTML editor if it accepts drag-and-drop.
Options
Interlaced: With interlacing, a first rough image is loaded first, and then the
vertical resolution improves in three additional passes. It isn't very useful
for animations.
Suggested setting: off
Colors and Depth: For cross-platform web animations, the 6x6x6 color table is
recommended. The system (or grayscale) 1 bit/pixel table should be used for
black and white images. Images created with other settings are likely to be
dithered on color-table-based machines. Set the Remove Unused Colors option in
the Colors submenu to let GifBuilder keep only the colors present in the
animation; this may reduce the file size a bit.
Suggested setting: 6x6x6 Palette and Remove Unused Colors.
Dithering: Dithering is a way to simulate intermediate color shades with clouds
of points. It should be used with continuous-tone images. With dithering, the
color table should be chosen so that the image isn't dithered a second time on
the target machine (see above), and transparency should be off.
Suggested setting: on for photographic images, off for drawings with few colors.
Image Size: When Minimum Size is on, the size is calculated so that the
animation's bottom right corner corresponds to the rightest lowest frame.
Frames are always cropped to fit in the animation bounding box.
Suggested setting: Minimum Size
Background Color: The Background Color is the color used to paint the animation
bounding box where no frame is displayed. With some Web browsers, the page
background is used instead.
Suggested setting: any
Loop: The Loop option specifies how many times the animation is repeated. Some
browsers don't recognize this option, while others loop an unlimited number of
times if the setting is more than 1.
Suggested setting: No or Forever
Transparent Background: All pixels which have the color specified by the
Transparent Background are left untouched when the frame is rendered.
Suggested setting: No or First Pixel
Frame Position: Each frame can be shifted by an arbitrary amount. The Frame
Position specifies the horizontal and vertical distances between the top left
animation corner and the top left frame corner. Positive values push the frame
to the left and to the lower part. Negative values result in a cropped frame.
Relative positions are relative with respect to their previous values. One can
also specify velocities, i.e. offsets between each frame position.
Suggested setting: create whole frames at (0,0) and use Frame Optimization to
do the work for you
Interframe Delay: The Interframe Delay is the delay between the current frame
and the following frame renderings. It's specified in hundredths of seconds
(i.e. 100 means 1 second).
Suggested setting: don't use As Fast As Possible, because it might be really to
fast on fast machines.
Disposal Method: The Disposal Method specifies what each frame becomes once the
interframe delay is elapsed. Use Unspecified when transparency is off and each
frame covers the whole animation, Do Not Dispose when you want to add some bits
of image to the previous animation state, Revert to Background for moving
objects on a transparent background, and Revert to Previous for moving objects
on a background you've drawn with an earlier large frame. Note that Revert to
Background isn't supported by some browsers.
Suggested setting: Do Not Dispose for opaque animations, Revert to Background
for transparent ones.
Frame Optimization: The Frame Optimization option crops each frame (but the
first one) to the part that has changed. This can result in tremendous file
size savings. If some, but not all, of the frames have the Disposal Method set
to Revert to Background, you are warned that this may give unexpected results.
Suggested setting: on (unless you need compatibility with primitive GIF
decoders; see "Compatibility with Other Programs" below)
Frame Expansion: The Frame Expansion option does the opposite of Frame
Optimization, i.e. it saves only whole frames. You shouldn't have to use it,
but it can help with some GIF decoders (like old versions of Internet Explorer)
that don't interpret correctly the frame position.
Suggested setting: off (unless you need compatibility with primitive GIF
decoders; see "Compatibility with Other Programs" below)
Remarks
New: After asking you if you want to save your previous animation, New removes
all the frames and reads the default settings from the Preference file.
Open: You can open an existing animation, or append to the end of the current
animation by holding down the Shift key and choosing Open in the File menu or
typing Command-Shift-O.
Frames displayed in italic are loaded in memory, while those displayed in
roman correspond to separate files.
Save Selection: only the selected frames are saved. Equivalent to Clear what is
not selected, Save As, and Undo. Can be used to export single frames as GIF
files.
Convert: You can convert a QuickTime movie, a PICS or a FilmStrip directly to
an animated GIF without opening it, by choosing Convert in the File menu. This
saves a lot of memory, but is less flexible: the current options are used, all
the frames are saved, and no frame optimization is performed.
Clear: Clear (in the Edit menu) or the Backspace key deletes the selected
frames. To preserve the timing, hold down the Shift key and choose Special
Clear or type Backspace. Example: Before Clear: Clear: Shift-Clear:
Undo: Undo allows to return to the state just before the last operation which
changed the frames or frame order.
Color palette: System Palette and Gray Shades are fixed palette. Best Palette
is optimized for all the frames simultaneously. 6x6x6 Palette is a subset of
the System palette where each component takes the six values 0, 51, 102, 153,
204 and 255; it has 6x6x6 = 216 entries. It's the palette used by NetScape for
Windows, so you might want to choose it to avoid additional dithering on both
Macintosh and Windows machines. Load Palette allows to use a Photoshop-
compatible palette file or the global palette of any GIF file. Three such
palettes are included with GifBuilder: "Gray from 6x6x6 Palette" (six gray
values of the 6x6x6 palette), "2x2x2 Palette" (eight basic colors where each
component is 0 or 255), or "16 from 6x6x6 Palette", superset of the previous
one with eight additional colors: (153,153,153), (0,153,255), (255,51,0),
(51,153,0), (255,153,255), (153,204,255), (255,255,153) and (204,204,204) (see
below). All of them should give good results on both the Mac and Windows.
Note that the 4-bits-per-pixel System palette has some intermediate colors and
shouldn't be used if you're concerned about cross-platform issues.
To reuse the color palette of an existing GIF, open the GIF file with Open (in
the File menu) and save the palette with Save Palette (in the Colors submenu
of the Options menu). The GIF file doesn't have to contain multiple frames.
The format of palette files is 256 entries of three bytes which represent the
red, green and blue values of the corresponding index. 0 is black, and 255 is
the maximum intensity. For palettes of less than 256 colors, fill the unused
entries with the last used one. The file type is '8BCT', and the file creator
should be 'gfBr' (GifBuilder's) to have a nice icon. Note that in AppleScript,
RGB values are in the range 0-65535; to convert them from a byte value,
multiply them by 257.
When you load a palette, you can't choose the depth anymore. Choose a System,
grayscale or best palette before changing the depth.
You can examine the current palette by choosing Show Colors in the Window menu,
and load one by dragging a palette file or a GIF file in the Colors window.
Drag and Drop: Drag and Drop is an easy way to move information from one
program to another. GifBuilder supports this feature as a shortcut for several
operations:
- You can drag frame files from the Finder or frame pictures from any program
supporting it (e.g. the ScrapBook) into the Frames window.
- You can drag a palette file or a GIF file to the Colors window; in the case
of a GIF file, its global color palette is used.
- You can drag the Animated GIF icon from the Animation window to any location
in the Finder to create an animated GIF there.
- You can drag the icon from the Animation window to text editors and HTML
editors that support Drag and Drop (e.g. SimpleText, BBEdit, and Adobe
PageMill 2). An ![]()
HTML tag is inserted, like what you get with Copy HTML
Image Tag.
Effects
Effects are commands whose purpose is to modify the animation to achieve some
visual enhancement. They apply to the selected frames by modifying them (static
filters) or inserting new frames (dynamic filters and transitions). Selected
frames are expanded to the area of the animation. They are rendered using the
current color palette. Consequently, to have the desired effect, check that the
size and palette of the animation before making a transition. In some rare
cases, depending on the disposal method, this may modify the animation in
unexpected ways. You may also want to check the transparency and interframe
delay, which is set to the default values. Since only the new frames are
selected, you can change these settings very easily.
Static Filters
You can apply one of the static filters of the Effect menu to the selected
frames.
Dynamic Filters
You can apply one of the dynamic filters of the Effect menu to the selected
frames. A dynamic filter is a filter that adds frames with a more and more
dramatic effect. You can put them either before the existing frames to reveal
them, or after them to hide them. The number of new frames which are inserted
before the first selected frame is one less than the number of steps.
Transitions
To create a transition between two frames, select the second frame and choose
one of the transitions in the Effects menu. The number of new frames which are
inserted before the first selected frame is one less than the number of steps.
The transition frames have the size of the animation. To create a transition
from or to a plain color, use Add Color Matte (also in the Effects menu) to
insert a plain frame first.
Scripting
Warning: scripting support is experimental. Some functionality is missing.
This should be fixed in future releases. The core AppleEvents and a
rudimentary object model are partially implemented, allowing to create new and
modify existing animations. Here is an example of what can be done:
tell application "GifBuilder"
open file "animation.gif" -- opens an existing animation
make new frame at the beginning Â
with data {contents:somePictObject} -- prepends a new frame with default frame options
make new frame at the end Â
with data {contents:file "lastFrame.tiff",
translation:{10, 10},
transparency:first pixel,
disposal method:restore to background,
interframe delay:50} -- appends another frame, with specified options
make new frame before 5th frame with data {contents:file "newFrame.pict"}
-- inserts a frame
save in file "animation2.gif" -- saves the animation in a new file
end tell
The color values are in the range 0 (black) - 65535 (maximum intensity). The
PICTs can be created by any good graphic (and many other) applications.
And here is a "real" example that creates a bouncing ball on a transparent
black background with clip2gif:
property w : 10
property h : 95
tell application "GifBuilder"
new
repeat with t from -13 to 12
set y to t * t / 2
tell application "clip2gif-ppc" to set p to save {w, h} in picture
drawing {{rectangle:{0, 0, w, h}}, {disk:{0, y, w, y + w}, color:{65535, 0, 0}}}
make new frame at end
with data {contents:p, transparency:first pixel, disposal method:restore to background}
end repeat
set loop to 0
save in new file
run animation
end tell
Results
Some option combinations can give unexpected results; this may be caused by
strange features, viewer bugs, or GifBuilder bugs. If you don't succeed in
creating files that load correctly in NetScape, choose Reset to Factory
Settings in the Options menu and import your frames again.
One of the main goals of GifBuilder is to stick as closely as possible to the
GIF 89a specifications, not to reproduce the way animations are performed on some particular browser.
Requirements
GifBuilder requires System 7 or above and 32-bit Color Quickdraw. The Drag
Manager (which comes with PowerTalk and System 7.5) is recommended. AppleScript
(as well as ObjectSupportLib on PowerMacs) is obviously needed to
Apple-script GifBuilder. QuickTime is needed for importing QuickTime movie. If
Convert (in the File menu) is dimmed, QuickTime is not correctly installed. The
animation, as well as the individual frames if they're loaded, must fit in RAM;
set the application memory partition appropriately (Get Info in the Finder).
GifBuilder shouldn't crash in low memory conditions; but if it does, try to
increase the memory partition to some high value (if you can) before sending me
a bug report.
Frequently Asked Questions
About Animated GIF
Local animations are ok, but when I use an HTTP server, they don't loop and the
end of the last frame is corrupted. What happens?
You probably corrupted the file when you uploaded it to the server. Be sure
that you choose the binary (or raw) mode (not MacBinary) for your file
transfer.
Can I choose which frame is displayed by old browsers?
No. Some GIF decoders display only the first frame, while others render all the
images but don't recognize the looping NetScape 2.0 extension.
Netscape doesn't display correctly transparent animations. Is there a trick?
Try to set the Disposal Method of all the frames to Revert to Background, and
specify a background GIF to be tiled behind the HTML page with the tag:
.
There is a flash when the animation loops. What can I do?
Try to remove interlacing and to use a cross-platform color palette (e.g. the
6x6x6 Palette).
Is it possible to have an animated background?
Not with the current versions of Netscape (2.0(x)).
Should I put the original images on my server?
No. Animated GIFs are completely self-contained. They don't contain any
references to the original files.
How can I stop animations in NetScape 2.0 for the Mac?
You should hold down the Command key and hit the dot key exactly when NetScape
reloads the image from its cache.
Why can't I {go back and forth | repeat only some frames}?
Because these features wouldln't be supported by any other browser. Animations
created by GifBuilder have to stick with the GIF specifications.
About GifBuilder
I want to keep the color palette of my frames, which are GIF files. What should
I do?
Open one of your frames in GifBuilder with Open, add the other frames and set
their options, and save the result.
Why can't I choose a System Palette with a depth of 3, 5, 6 or 7 bits/pixel, or
a 6x6x6 Palette with a depth smaller than 8?
Because there is no such palettes.
Why is the transparency set to First Pixel even if I specify a color?
In GIF files, the transparency is always based on a color. When GifBuilder
reads an animation, it looks at the first pixel to see if it's the transparent
color, and if so reports that the transparency is based on it.
Why do I get the error "File not found" when I save the animation?
For disk-based frames (whose name is displayed in roman), GifBuilder uses the
content of the files when it builds the animation or when you choose Reload
Frames in the File menu. You should leave the files where they were when you
imported them.
Why do I get an error message saying that a feature isn't supported when I
import a TIFF or Photoshop image?
Because GifBuilder supports only the most common, publicly documented and
patent-free formats. Supported TIFF files include bitmap, grayscale, indexed
and RGB, uncompressed or compressed with Packbits. Supported Photoshop files
include bitmap, grayscale, indexed, RGB and duotone (read as grayscale),
version 2.5 or 3.0.
How can I choose the comment displayed by JPEGView and other utilities?
You can't. GifBuilder adds a fixed comment containing its and my names. This is
deliberate.
I've found a GifBuilder bug! Revert to Previous doesn't work!
If your browser doesn't handle correctly a feature, this isn't necessarily a
GifBuilder bug. This one, for instance, is most probably not.
Images are dithered even if I don't select it in GifBuilder! Why?
Images are usually dithered by the browser if its palette isn't the same as the
GIF's. You'd better use the 6x6x6 palette provided with GifBuilder, which is
used by several browsers on the Mac as well as on alien machines, and let
GifBuilder do the dithering if you need to.
When will GifBuilder support a sound track? GifBuilder sticks to the GIF
specifications as close as possible. This permits the animations it creates to
be displayed by many browsers without the help of any plug-in. While it would
be possible to add a custom GIF extension for sound, it wouldn't be recognized
by most browsers.
The blur filter posterizes the frames. Why?
Filters and transitions render the frames using the current color palette, then
create new intermediate frames with 24 bits/pixel. The result is displayed in
the Preview window and saved as GIF using the current palette again. Usual
palettes have only a limited number of shades, and that's especially visible
with blurred images. You can use the Best Palette or Gray Shades, or set
dithering on, to avoid posterizing.
The peal transition doesn't use the color I choose for the back of the sheet.
Why?
The color you choosed must not be in the current color palette (see question
above). Use a darker color or a less transparent alpha value (larger).
I don't use Windows 3.1 anymore. Are you working on a Windows NT version?
GifBuilder runs on the Mac. I don't intend to port it to any currently
available operating system (I might have ideas about new ones, however).
So give me the source, I'll port it. First, I don't make the source code
available. Second, even if it was, the GIF part is a very small part of the
whole program. The remaining is closely tied to the Mac user interface and
graphical model.
Compatibility with Other Programs
Programs are mentionned here for information only. Some of them are quite good
(imo), others aren't (imho); don't try to deduce which ones I like or love.
Netscape Navigator 2.01 for Mac
Netscape Navigator 2.01 for Mac doesn't support all the GIF89a features.
Features not supported include Revert to Previous, all the transparency
specifications except the one for the first frame (which is applied globally to
all the frames), transparency without a background GIF in the tag (use
), and the number of loops.
Microsoft Internet Explorer 2.1 for Mac
Much better support than in previous versions. The number of loops is taken
into account.
NCSA Mosaic 2.0.1 for Mac
Only the last frame is displayed. Partial frames result in corrupted images
(version 3.0A2 has the same problems); use Expand Frames.
Apple Cyberdog 1.0
Neither the looping nor the timing info is taken into account. At the end, the
last frame is displayed.
Adobe Photoshop 3.0
You can create individual frames in Photoshop and save them as Photoshop
bitmap, grayscale or RGB files, and drag them from the Finder to the GifBuilder
Frames window (duotone files can also be imported, but color information is
lost). PICT, GIF and TIFF files are of course also possible. GifBuilder can
also load the layers of a grayscale or RGB Photoshop 3.0 file. Each layer is
rendered onto a white opaque background. To create the animation, you can draw
the first frame on the Background layer. Then for each new frame, choose
Duplicate Layer, hide the other layers, and edit the new one.
Adobe Premiere 4.0
You can save animations as QuickTime movies, FilmStrips or bunches of numbered
PICT files. The FilmStrip format is recommended, because it's more convenient
that several PICT files and guarranties that no lossy compression method is
used. You can also edit it in Photoshop.
Adobe PageMill 2.0
You can drag the icon from the Animation Window to a PageMill window to
insert a tag. You should save the animated GIF in the same folder as the HTML
document, or edit the URL.
Specular Infini-D 3.0 and LogoMotion 2.0
You can save animations either as QuickTime movies or PICS, and open them in
GifBuilder to save them as animated GIF. The PICS format is recommended,
because it guarranties that no lossy compression method is used.
Other animated GIF utilities
You can load animated GIF files created with other utilities to study and
change the settings.
Small Print
This document is Copyright 1995-1997, Yves Piguet. All rights reserved. The
author makes no warranty with respect to this document, its quality, accuracy,
or fitness for a particular purpose. As a result, this document is provided
"as is", and the user is assuming the entire risk as to its quality and
accuracy.
Marks mentionned here are for information only; most of them are trade marks or
registered trade marks.
Author
Yves Piguet
Av. de la Chablire 35
1004 Lausanne
Switzerland