jwo.utils.gifutils
Class GIFImage

java.lang.Object
  jwo.utils.gifutils.GIFImage

public class GIFImage

extends Object

GIFImage represents an image as stored in a gif file. It can be used to load or save images from disk without using AWT components and can thus be run from a text console.

Before using this package, it may help to become familiar with the terminology used regarding gif images. Try looking at this page for more information. Alternatively, do a web search for "gif89a specification".

GIFImage is capable of reading all extensions and images in a gif89a file, but only the graphic control extension (used for transparency and time delay) is currently supported for image creation. Multiple images are available (as in an animated .gif). The term 'primary image' is taken to mean the first image in a file.

This package was originally built around GIFEncoder, by Adam Doppelt, which was in turn based on gifsave.c, by Sverre H. Huseby. None of the current incarnation bears much resemblance to these works, however.

GIFImage is currently very alpha-ish, and you may have to do some hacking if you want to take advantage of advanced features like time delays and looping. But it's free, so don't gripe too hard:) The ZIP file contains all the classes and source code. In all seriousness, if you find a bug, please let me know.

Examples

To extract the RGB pixels from a .gif image file:

   GIFInputStream gis = new GIFInputStream(
     new FileInputStream(myFileName) );
   GIFImage gi = new GIFImage(gis);
   int[] rgbPixels = gi.getRGBPixels();
 

To create a .gif file from an array of RGB pixel values:

   int[] rgbPixels = myPixelGenerationMethod();  // get pixels somehow
   GIFImage gi = new GIFImage(rgbPixels, imageWidth);
   GIFOutputStream gos = new GIFOutputStream(
     new FileOutputStream(args[0]) );
   gi.write(gos);
 

To create a GIFImage which makes grey pixels transparent:

   GIFImage gi = new GIFImage(rgbPixels, imageWidth);
   gi.setTransparentColor(Color.grey);
 

To create an animated .gif file using 3 images:

   GIFImage gi = new GIFImage(rgbPixels1, imageWidth);  // first image (0)
   gi.addImage(rgbPixels2, imageWidth);  // second image (1)
   gi.addImage(rgbPixels3, imageWidth);  // third image (2)
   gi.setDelay(50);     // delay in 100th sec - defaults to first image (0)
   gi.setDelay(1, 50);  // second image
   gi.setDelay(2, 50);  // third image
   gi.setIterationCount(0);  // infinite loop
   gi.write(myOutputStream);
 

Author:

Benjamin E. Norman. Very minor modifications, Jo Wood.

Nested Class Summary

class

GIFImage.NetscapeExtension Extension block for looping animations.

Field Summary

static int	APPLICATION
static int	COMMENT
protected jwo.utils.gifutils.GIFImage.GraphicControlExtension	currentGraphicControlExtension
static int	EXTENSION_INTRODUCER
static int	GIF87a
static int	GIF89a
static int	GRAPHIC_CONTROL
protected jwo.utils.gifutils.GIFImage.Header	header
static int	IMAGE_SEPARATOR
static int	LEAVE_IN_PLACE
protected jwo.utils.gifutils.GIFImage.LogicalScreen	logicalScreen
static String	NETSCAPE2_0
protected GIFImage.NetscapeExtension	netscapeExtension
static int	NONE
static int	PLAIN_TEXT
static int	RESTORE_TO_BACKGROUND
static int	RESTORE_TO_PREVIOUS
protected Vector	tableBasedImages
static int	TRAILER

Constructor Summary

GIFImage(GIFInputStream input)
Create a GIFImage from .gif image data on the given stream.

GIFImage(int[] pixels, int width)
As GIFImage(int[], int, boolean), using a global color table.

GIFImage(int[] pixels, int width, boolean localColorTable)
Create a GIFImage containing one table-based image formed from the given array of integer RGB raster data and the image width.

Method Summary

void	addImage(int[] pixels, int width) Adds a new table-based image to this GIFImage (at the end of the list).
void	addImage(int[] pixels, int width, boolean localColorTable) Adds a new table-based image to this GIFImage (at the end of the list).
protected int	bppForNumColors(int numColors) Calculates the minimum BPP for the given number of colors.
int	countImages() Return the number of table-based images present.
protected int	getBppForImage(jwo.utils.gifutils.GIFImage.TableBasedImage tbi) Return the color depth (bits/pixel) of the given table-based image.
protected jwo.utils.gifutils.GIFImage.ColorTable	getColorTableForImage(jwo.utils.gifutils.GIFImage.TableBasedImage tbi) Return the color table for the given table-based image.
int	getDelay() Get the time delay for the primary image in 1/100 s
int	getDelay(int imageIndex) Get the time delay for the image at the given index in 1/100 s
int	getHeight() Get the pixel height of the primary image.
int	getHeight(int imageIndex) Get the pixel height of the image at the given index.
int	getIterationCount() Return the number of times the images in this GIFImage will iterate, or 0 if they repeat indefinitely.
int[]	getRGBPixels() Return the RGB pixels of the primary image.
int[]	getRGBPixels(int imageIndex) Return the RGB pixels of the image at the given index.
Color	getTransparentColor() Get the RGB transparent color of the primary image.
Color	getTransparentColor(int imageIndex) Get the RGB transparent color of the image at the given index.
int	getWidth() Get the pixel width of the primary image.
int	getWidth(int imageIndex) Get the pixel width of the image at the given index.
boolean	isImageInterlaced() Return whether or not the primary image is interlaced.
boolean	isImageInterlaced(int imageIndex) Return whether or not the image at the given index is interlaced.
protected jwo.utils.gifutils.GIFImage.ColorTable	makeIndexedColor(int[] rgbPixels, byte[] indexedPixels, boolean localColorTable) Extract indexed color info from the given RGB pixels.
void	read(GIFInputStream input) Replace the current contents of this GIFImage with data from a .gif file present on the given input stream.
void	setDelay(int delay) Set the time delay for the primary image in 1/100 s
void	setDelay(int imageIndex, int delay) Set the time delay for the image at the given index in 1/100 s
void	setImageInterlaced(boolean interlaced) Set the primary image as interlaced or not.
void	setImageInterlaced(int imageIndex, boolean interlaced) Set or clear the interlaced state for the image at the given index.
void	setIterationCount(int iterationCount) Make the series of images in this file iterate the given number of times, or indefinitely if 0 is given.
void	setTransparentColor(Color trans) Set the RGB transparent color of the primary image.
void	setTransparentColor(int imageIndex, Color trans) Get the RGB transparent color of the image at the given index.
String	toString() Print the string representation of the gif file - includes all image data including actual pixels.
void	write(GIFOutputStream output) Write this GIFImage as a .gif file to the given stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

GIF87a

public static final int GIF87a

See Also:

Constant Field Values

GIF89a

public static final int GIF89a

See Also:

Constant Field Values

IMAGE_SEPARATOR

public static final int IMAGE_SEPARATOR

See Also:

Constant Field Values

EXTENSION_INTRODUCER

public static final int EXTENSION_INTRODUCER

See Also:

Constant Field Values

TRAILER

public static final int TRAILER

See Also:

Constant Field Values

PLAIN_TEXT

public static final int PLAIN_TEXT

See Also:

Constant Field Values

APPLICATION

public static final int APPLICATION

See Also:

Constant Field Values

COMMENT

public static final int COMMENT

See Also:

Constant Field Values

GRAPHIC_CONTROL

public static final int GRAPHIC_CONTROL

See Also:

Constant Field Values

NETSCAPE2_0

public static final String NETSCAPE2_0

See Also:

Constant Field Values

NONE

public static final int NONE

See Also:

Constant Field Values

LEAVE_IN_PLACE

public static final int LEAVE_IN_PLACE

See Also:

Constant Field Values

RESTORE_TO_BACKGROUND

public static final int RESTORE_TO_BACKGROUND

See Also:

Constant Field Values

RESTORE_TO_PREVIOUS

public static final int RESTORE_TO_PREVIOUS

See Also:

Constant Field Values

header

protected jwo.utils.gifutils.GIFImage.Header header

logicalScreen

protected jwo.utils.gifutils.GIFImage.LogicalScreen logicalScreen

netscapeExtension

protected GIFImage.NetscapeExtension netscapeExtension

tableBasedImages

protected Vector tableBasedImages

currentGraphicControlExtension

protected jwo.utils.gifutils.GIFImage.GraphicControlExtension currentGraphicControlExtension

Constructor Detail

GIFImage

public GIFImage(int[] pixels,
                int width)
         throws GIFFormatException

As GIFImage(int[], int, boolean), using a global color table.

GIFImage

public GIFImage(int[] pixels,
                int width,
                boolean localColorTable)
         throws GIFFormatException

Create a GIFImage containing one table-based image formed from the given array of integer RGB raster data and the image width. (The width should divide the length of the data array.) The first 256 colors encountered are added to the color table. The flag indicates whether this image should use a local color table (unique to the primary image) or the global color table, which is shared by all table-based images in this GIFImage.

Throws:

GIFFormatException - if more than 256 colors are encountered

GIFImage

public GIFImage(GIFInputStream input)
         throws IOException

Create a GIFImage from .gif image data on the given stream.

Method Detail

addImage

public void addImage(int[] pixels,
                     int width)
              throws GIFFormatException

Adds a new table-based image to this GIFImage (at the end of the list). The RGB pixels and image width are required. The global color table is used.

Throws:

GIFFormatException - if more than 256 colors are encountered

addImage

public void addImage(int[] pixels,
                     int width,
                     boolean localColorTable)
              throws GIFFormatException

Adds a new table-based image to this GIFImage (at the end of the list). The RGB pixels and image width are required. The flag indicates whether a local color table is used for this image. Otherwise, the image colors are added to the global color table, up to its capacity of 256.

Throws:

GIFFormatException - if more than 256 colors are encountered

getRGBPixels

public int[] getRGBPixels()

Return the RGB pixels of the primary image.

getRGBPixels

public int[] getRGBPixels(int imageIndex)

Return the RGB pixels of the image at the given index.

write

public void write(GIFOutputStream output)
           throws IOException

Write this GIFImage as a .gif file to the given stream.

Throws:

IOException

read

public void read(GIFInputStream input)
          throws IOException

Replace the current contents of this GIFImage with data from a .gif file present on the given input stream.

Throws:

IOException

toString

public String toString()

Print the string representation of the gif file - includes all image data including actual pixels. (Careful!)

countImages

public int countImages()

Return the number of table-based images present.

isImageInterlaced

public boolean isImageInterlaced()

Return whether or not the primary image is interlaced.

isImageInterlaced

public boolean isImageInterlaced(int imageIndex)

Return whether or not the image at the given index is interlaced.

setImageInterlaced

public void setImageInterlaced(boolean interlaced)

Set the primary image as interlaced or not.

setImageInterlaced

public void setImageInterlaced(int imageIndex,
                               boolean interlaced)

Set or clear the interlaced state for the image at the given index.

getTransparentColor

public Color getTransparentColor()

Get the RGB transparent color of the primary image.

getTransparentColor

public Color getTransparentColor(int imageIndex)

Get the RGB transparent color of the image at the given index.

setTransparentColor

public void setTransparentColor(Color trans)

Set the RGB transparent color of the primary image.

setTransparentColor

public void setTransparentColor(int imageIndex,
                                Color trans)

Get the RGB transparent color of the image at the given index.

getWidth

public int getWidth(int imageIndex)

Get the pixel width of the image at the given index.

getWidth

public int getWidth()

Get the pixel width of the primary image.

getHeight

public int getHeight(int imageIndex)

Get the pixel height of the image at the given index.

getHeight

public int getHeight()

Get the pixel height of the primary image.

getDelay

public int getDelay()

Get the time delay for the primary image in 1/100 s

getDelay

public int getDelay(int imageIndex)

Get the time delay for the image at the given index in 1/100 s

setDelay

public void setDelay(int delay)

Set the time delay for the primary image in 1/100 s

setDelay

public void setDelay(int imageIndex,
                     int delay)

Set the time delay for the image at the given index in 1/100 s

setIterationCount

public void setIterationCount(int iterationCount)

Make the series of images in this file iterate the given number of times, or indefinitely if 0 is given.

getIterationCount

public int getIterationCount()

Return the number of times the images in this GIFImage will iterate, or 0 if they repeat indefinitely.

getBppForImage

protected int getBppForImage(jwo.utils.gifutils.GIFImage.TableBasedImage tbi)

Return the color depth (bits/pixel) of the given table-based image. This is necessary for images not having a local color table.

getColorTableForImage

protected jwo.utils.gifutils.GIFImage.ColorTable getColorTableForImage(jwo.utils.gifutils.GIFImage.TableBasedImage tbi)

Return the color table for the given table-based image. This is necessary for images not having a local color table.

bppForNumColors

protected int bppForNumColors(int numColors)

Calculates the minimum BPP for the given number of colors.

makeIndexedColor

protected jwo.utils.gifutils.GIFImage.ColorTable makeIndexedColor(int[] rgbPixels,
                                                                  byte[] indexedPixels,
                                                                  boolean localColorTable)
                                                           throws GIFFormatException

Extract indexed color info from the given RGB pixels. The size of the resulting color table will be a power of 2, up to a maximum of 256. The color indices corresponding to the given RGB color values are placed in the byte array given. The final color table is returned. The flag indicates whether the colors in this image are unique to it (local) or should be added to the color table for the entire image (global). Note that this method can "grow" the global color table if it is less than 8 bits/pixel.

Throws:

GIFFormatException - if more than 256 colors are found