GifComponents
From SimonDotException
Contents |
[edit] Update in progress!
Please note that a large update is under way here. Significant changes have been committed to the repository to improve performance, particularly in the colour quantizing stage of encoding. As a result, the contents of this web site are not necessarily up to date. The installer currently available for download in the Files section still contains the previous version of GifComponents. I'll be working over the coming weeks to both build a new installer and bring this web site up to date.
[edit] About GifComponents
[edit] Why GifComponents?
The .net framework does provide ways of creating Graphic Interchange Format files from images in other formats, but the quality of the resulting images leaves quite a lot to be desired (see the ColourQuantizing page), so I started looking for open source .net libraries to perform this task. The best I found was NGif, published by gOODiDEA.NET at CodeProject, with a small enhancement by Phil Garcia to encode to a stream rather than a file. NGif includes methods for both encoding and decoding GIF data streams.
GifComponents is a derived work based on NGif. The important changes are:
- Each of the components of a GIF file, as defined in the W3C GIF89a specification, has been refactored into its own class.
- When decoding GIF data streams, every effort is made to handle corrupt streams gracefully, setting an ErrorState property and continuing to decode where possible, rather than throwing an unhandled exception.
- The GifDecoder class can optionally populate a DebugXml property which can help to identify any issues with corrupt GIF data streams.
- If you find a GIF file which causes the GifDecoder to throw an unhandled exception, please create a bug tracker and attach the file and the message and stack trace of the exception.
- GIF files can be encoded with local colour tables (one palette per frame) or global colour tables (one palette for the whole animation).
- Choice of three different colour quantizing algorithms when encoding GIF files:
- Neural network - the algorithm originally used by NGif.
- Octree - faster than a neural network but image quality isn't quite as good.
- User-supplied palette - the slowest, but handy if you want your GIFs to follow a particular colour scheme.
- Performance improvements in the AnimatedGifEncoder:
- Calls to Bitmap.GetPixel and Bitmap.SetPixel replaced with unsafe code encapsulated in the FastBitmap class.
- AnimatedGifEncoder and the classes which perform colour quantizing are all derived from the AsynchronousOperation class in the GetFeedback assembly, allowing them to be run on a separate thread from the UI whilst providing meaningful progress information to the user whilst running.
[edit] Technical info
GifComponents and ImageTools are class libraries, and GifInspector and GifBuilder are Windows Forms applications provided primarily to demonstrate usage of the GifDecoder and AnimatedGifEncoder classes respectively. All are written in C# targeting version 2.0 of the .net framework.
The project files in the repository were created using SharpDevelop so users of Visual Studio may find that they can't open them. If this is the case for you, then create a new project in Visual Studio and add each of the source code files to it.
The project files in the repository reference a .snk file which isn't in the repository, and attempting to build them will result in a cryptographic failure because the file is not found. To resolve this, either turn assembly signing off in the project options, or create your own strong name key file if you want to be able to install your build of the assembly in the GAC.
[edit] Installing GifComponents
[edit] Windows installer
I haven't built an installer for the latest version of GifComponents yet, but I will soon. The installers available on the downloads page are all for previous versions, which have some serious performance issues.
[edit] Build from source
Download the GifComponents and ImageTools projects (and if you want, the GifBuilder and/or GifInspector projects) from the SVN browse page, either as tarballs or using your favourite Subversion client.
Don't download the GifComponents.NUnit and ImageTools.NUnit projects unless you actually want to run the unit tests. Those projects contain a number of bitmaps which are the expected results of various image manipulation operations, so are rather large. At the time of writing, a tarball of the entire repository stands at 30MB, mainly due to those bitmap files.
The GifComponents project is dependent on the following external projects:
If you want to build the unit test projects from source then you will also need NUnit.Extensions.
Each of these assemblies can also be built from source if you choose, or running the CommonForms installer will install them all into the Global Assembly Cache.
[edit] Using GifComponents
For more detailed usage information, see the Sandcastle-built help file which will be included in the installer once I've built it.
[edit] GifFrame class
The GifFrame is the basic building block of a GIF file. Every GIF file contains one or more frames. To instantiate a GifFrame, you need a System.Drawing.Bitmap object. This must be passed to the constructor along with the number of hundredths of a second that the frame should be displayed before the next frame in the animation is displayed. For example:
Bitmap myBitmap = Bitmap.FromFile( "myBitmap.bmp" ); GifFrame myFrame = new GifFrame( myBitmap, 100 );
The above example will create a frame containing the image myBitmap.bmp which will display for 1 second when added to a GIF file.
After decoding a GIF file using the GifDecoder class, its Frames property will contain the frames which make up the file, and each frame's TheImage property will contain a Bitmap of the image in that frame.
[edit] Encoding (creating) GIF files
The AnimatedGifEncoder class creates a GIF data stream from one or more supplied images, using the specified type of quantizer to reduce the palette of each frame to 256 colours or less. For example, the following will create an animation called myGif.gif, consisting of the two images myBitmap.bmp and myJpeg.jpg:
// If running within a Windows form or control, do this: AnimatedGifEncoder encoder = new AnimatedGifEncoder( this ); // If running within a batch job or unit test, do these: SynchronizeInvokeStub target = new SynchronizeInvokeStub(); AnimatedGifEncoder encoder = new AnimatedGifEncoder( target ); // Do these regardless: encoder.FileName = "myGif.Gif"; // Set output filename // Set images to add to the animation Image image1 = Image.FromFile( "myBitmap.bmp" ); GifFrame frame1 = new GifFrame( image1 ); encoder.AddFrame( frame1 ); Image image2 = Image.FromFile( "myJpeg.jpg" ); GifFrame frame2 = new GifFrame( image2 ); encoder.AddFrame( frame2 ); // If running within a Windows Form which is derived from ResponsiveForm, do this: // Starts encoding on a separate thread and returns immediately. // ResponsiveForm will track the other thread and display progress bars to the user. StartAsynchronousOperation( encoder, "Encoding...", false ); // If running in a different context, do these encoder.Start(); // Starts encoding on a separate thread and returns immediately. encoder.WaitUntilDone(); // Blocks the current thread until the encoder has completed
AnimatedGifEncoder is derived from GetFeedback.AsynchronousOperation. See that page for more information on how to call AsynchronousOperations.
[edit] Decoding (reading) GIF files
The GifDecoder class reads a GIF data stream and decodes it. For example, the following will decode a GIF file and save each of its frames as a bitmap file:
GifDecoder decoder = new GifDecoder ( "myGif.gif" );
decoder.Decode();
for( int i = 0; i < decoder.Frames.Count; i++ )
{
decoder.Frames[i].TheImage.Save( "frame" + i + ".bmp", ImageFormat.Bmp );
}
[edit] Sample applications
[edit] GifBuilder
GifBuilder is a simple Windows Forms application which allows the user to select one or more static image files and create a GIF animation from them. It allows the user to edit the properties of the GifFrame and AnimatedGifEncoder classes to control how the animation is encoded.
[edit] GifInspector
GifInspector is a simple Windows Forms application which decodes an existing GIF file and exposes the properties of the GifDecoder and GifFrame classes to the user. It also allows the user to save the individual frames of a GIF animation as bitmap files.
[edit] GIF links
[edit] GIF software links
GifComponents project on SourceForge.net.
NGif - the library upon which GifComponents is based.
Phil Garcia's enhancement to NGif.
[edit] General GIF links
The Graphics Interchange Format version 89a specification.
