com.gif4j
Class GifEncoder

java.lang.Object
  com.gif4j.GifEncoder

public class GifEncoder

extends java.lang.Object

GifEncoder is a java class which takes as image(-s), encodes and saves it(them) out to a file or output stream using the GIF file format (GIF89a version). It can be used to save BufferedImage instances as non-animated GIF image files or prepared from the images sequence GifImage instances as animated GIF image files. If an encoding BufferedImage image instance has more than 256 colors then before writing it as a GIF to the specified output stream it's automatically quantized using the Quantizer by default. GifEncoder java class is thread safe and can be used without addittional synchronization.

The following 2 java examples demostrate common ways to use this java gif image encoder. Please peruse the API, tutorial and external examples for additional features.

Save image as a GIF file using Java

 import com.gif4j.GifEncoder;
 import com.gif4j.ImageUtils;

 import java.awt.Image;
 import java.awt.image.BufferedImage;
 import java.io.File;
 import java.io.IOException;

 // ...

     void saveImageAsGif(Image image, File fileToSave) throws IOException {
         // convert Image to the BufferedImage
         BufferedImage bufferedImage = ImageUtils.toBufferedImage(image);
         // save image
         GifEncoder.encode(bufferedImage, fileToSave);
     }
 

Save array of images as an animated GIF file using Java

 import com.gif4j.GifEncoder;
 import com.gif4j.GifFrame;
 import com.gif4j.GifImage;

 import java.awt.image.BufferedImage;
 import java.io.File;
 import java.io.IOException;

    // ...

    void saveImageArrayAsAnimatedGif(BufferedImage[] images, File fileToSave) throws IOException {
        // create new GifImage instance
        GifImage gifImage = new GifImage();
        // set default delay between gif frames
        gifImage.setDefaultDelay(500);
        // add comment to gif image
        gifImage.addComment("Animated GIF image example");
        // add images wrapped by GifFrame
        for (int i = 0; i < images.length; i++)
            gifImage.addGifFrame(new GifFrame(images[i]));
        // save animated gif image
        GifEncoder.encode(gifImage, fileToSave);
    }
 

Note: Use ImageUtils.toBufferedImage(java.awt.Image) to convert java.awt.Image instances to java.awt.image.BufferedImage instances.

Note: After encoding a GifImage instance and its' internal GifFrame(-s) are disposed to free memory and can't be reused!

The following specification "GRAPHICS INTERCHANGE FORMAT(sm) Version 89a" was referenced for the development of this encoder.
Some of the naming conventions and clarification of some aspects of GIF file format and LZW compression were obtained from the following:
LZW.C (Copyright 1989 Mark R. Nelson)
LZW data compression/expansion demonstration program (May 12, 1997)

Version:

1.0

Author:

Gif4J Software - Java GIF image processing solutions

See Also:

GifImage, GifFrame, BufferedImage

Method Summary

static void	encode(java.awt.image.BufferedImage image, java.io.DataOutput dataOutput) Encode and write out the data contained in the BufferedImage to the specified data output in the GIF image file format ('89a' version).
static void	encode(java.awt.image.BufferedImage image, java.io.File output) Encode and write out the data contained in the BufferedImage to a File in the GIF output format ('89a' version).
static void	encode(java.awt.image.BufferedImage image, java.io.OutputStream outputStream) Encode and write out the data contained in the BufferedImage to the specified output stream in the GIF image file format ('89a' version).
static void	encode(GifImage gifImage, java.io.File output) Encode and write out the data contained in the GifImage to a File in the GIF output format ('89a' version).
static void	encode(GifImage gifImage, java.io.File output, boolean forceGlobalColorTableUsage) Encode and write out the data contained in the GifImage to a File in the GIF output format ('89a' version).
static void	encode(GifImage gifImage, java.io.OutputStream outputStream) Encode and write out the data contained in the GifImage to the specified output stream in the GIF image file format ('89a' version).
static void	encode(GifImage gifImage, java.io.OutputStream outputStream, boolean forceGlobalColorTableUsage) Encode and write out the data contained in the GifImage to the specified output stream in the GIF file format ('89a' version).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

encode

public static final void encode(java.awt.image.BufferedImage image,
                                java.io.DataOutput dataOutput)
                         throws java.io.IOException

Encode and write out the data contained in the BufferedImage to the specified data output in the GIF image file format ('89a' version).

Parameters:

image - image to encode and write out

dataOutput - the specified output to write

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If image is null

java.lang.NullPointerException - If output is null

encode

public static final void encode(java.awt.image.BufferedImage image,
                                java.io.File output)
                         throws java.io.IOException

Encode and write out the data contained in the BufferedImage to a File in the GIF output format ('89a' version). If there is already a File present, its contents are discarded.

Parameters:

image - image to encode and write out

output - a File to be written to.

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If GifImage is null

java.lang.NullPointerException - If output is null

Since:

2.0

encode

public static final void encode(java.awt.image.BufferedImage image,
                                java.io.OutputStream outputStream)
                         throws java.io.IOException

Encode and write out the data contained in the BufferedImage to the specified output stream in the GIF image file format ('89a' version). Running this method is equal to running encode(GifImage gifImage, java.io.OutputStream outputStream) where GifImage instance contains the only one GifFrame instance wrapped the specified image.

Parameters:

image - image to encode and write out

outputStream - the specified stream to output

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If image is null

java.lang.NullPointerException - If output stream is null

encode

public static final void encode(GifImage gifImage,
                                java.io.File output)
                         throws java.io.IOException

Encode and write out the data contained in the GifImage to a File in the GIF output format ('89a' version). If there is already a File present, its contents are discarded.

Parameters:

gifImage - GifImage to encode and write out

output - a File to be written to.

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If GifImage is null

java.lang.NullPointerException - If output is null

Since:

2.0

encode

public static final void encode(GifImage gifImage,
                                java.io.File output,
                                boolean forceGlobalColorTableUsage)
                         throws java.io.IOException

Encode and write out the data contained in the GifImage to a File in the GIF output format ('89a' version). If there is already a File present, its contents are discarded.

Parameters:

gifImage - GifImage to encode and write out

output - a File to be written to.

forceGlobalColorTableUsage - force Global Color Table usage. If true local color tables from all frames will be union to one global color table. It's useful to optimize final image size (every Local Color Table takes up to 768 bytes).

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If GifImage is null

java.lang.NullPointerException - If output is null

Since:

2.0

encode

public static final void encode(GifImage gifImage,
                                java.io.OutputStream outputStream)
                         throws java.io.IOException

Encode and write out the data contained in the GifImage to the specified output stream in the GIF image file format ('89a' version).

Parameters:

gifImage - GifImage to encode and write out

outputStream - the specified stream to output

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If gifImage is null

java.lang.NullPointerException - If output stream is null

encode

public static final void encode(GifImage gifImage,
                                java.io.OutputStream outputStream,
                                boolean forceGlobalColorTableUsage)
                         throws java.io.IOException

Encode and write out the data contained in the GifImage to the specified output stream in the GIF file format ('89a' version).

Parameters:

gifImage - GifImage to encode and write out

outputStream - the specified stream to output

forceGlobalColorTableUsage - force Global Color Table usage. If true local color tables from all frames will be union to one global color table. It's useful to optimize final image size (every Local Color Table takes up to 768 bytes).

Throws:

java.io.IOException - If write operation fails

java.lang.NullPointerException - If GifImage is null

java.lang.NullPointerException - If output stream is null