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 Application extension label.
static int	COMMENT Comment extension label.
static int	EXTENSION_INTRODUCER Extension introducer block label.
static int	GIF87a Indicates GIF87a file version.
static int	GIF89a Indicates GIF89a file version.
static int	GRAPHIC_CONTROL Graphic control extension label.
static int	IMAGE_SEPARATOR Image separator block label.
static int	LEAVE_IN_PLACE Disposal type identifier.
static String	NETSCAPE2_0 Application extension identifier.
static int	NONE Disposal type identifier.
static int	PLAIN_TEXT Plain text extension label.
static int	RESTORE_TO_BACKGROUND Disposal type identifier.
static int	RESTORE_TO_PREVIOUS Disposal type identifier.
static int	TRAILER Trailer block label.

Constructor Summary

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

GIFImage(int[] pixels, int width)
Creates a GIF image using a global color table.

GIFImage(int[] pixels, int width, boolean localColorTable)
Creates 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 (colour depth) for the given number of colours.
int	countImages() Reports the number of table-based images present.
protected int	getBppForImage(jwo.utils.gifutils.GIFImage.TableBasedImage tbi) Reports the colour depth (bits/pixel) of the given table-based image.
protected jwo.utils.gifutils.GIFImage.ColorTable	getColorTableForImage(jwo.utils.gifutils.GIFImage.TableBasedImage tbi) Reports the colour table for the given table-based image.
int	getDelay() Reports the time delay for the primary image in 1/100 s
int	getDelay(int imageIndex) Reports the time delay for the image at the given index in 1/100 s
int	getHeight() Reports the pixel height of the primary image.
int	getHeight(int imageIndex) Reports the pixel height of the image at the given index.
int	getIterationCount() Reports the number of times the images in this GIFImage will iterate, or 0 if they repeat indefinitely.
int[]	getRGBPixels() Returns the RGB pixels of the primary image.
int[]	getRGBPixels(int imageIndex) Returns the RGB pixels of the image at the given index.
Color	getTransparentColor() Reports the RGB transparent colour of the primary image.
Color	getTransparentColor(int imageIndex) Reports the RGB transparent colour of the image at the given index.
int	getWidth() Reports the pixel width of the primary image.
int	getWidth(int imageIndex) Reports the pixel width of the image at the given index.
boolean	isImageInterlaced() Reports whether or not the primary image is interlaced.
boolean	isImageInterlaced(int imageIndex) Reports whether or not the image at the given index is interlaced.
protected jwo.utils.gifutils.GIFImage.ColorTable	makeIndexedColor(int[] rgbPixels, byte[] indexedPixels, boolean localColorTable) Extracts indexed color info from the given RGB pixels.
void	read(GIFInputStream input) Replaces the current contents of this GIFImage with data from a .gif file present on the given input stream.
void	setDelay(int delay) Sets the time delay for the primary image in 1/100 s
void	setDelay(int imageIndex, int delay) Sets the time delay for the image at the given index in 1/100 s
void	setImageInterlaced(boolean isInterlaced) Sets the primary image as either interlaced or non-interlaced.
void	setImageInterlaced(int imageIndex, boolean isInterlaced) Sets the image at the given index as either interlaced or non-interlaced.
void	setIterationCount(int iterationCount) Makes the series of images in this file iterate the given number of times, or indefinitely if 0 is given.
void	setTransparentColor(Color trans) Sets the RGB transparent colour of the primary image.
void	setTransparentColor(int imageIndex, Color trans) Sets the RGB transparent colour of the image at the given index.
String	toString() Provides a string representation of the gif file - includes all image data including actual pixels.
void	write(GIFOutputStream output) Writes 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

Indicates GIF87a file version.

See Also:

Constant Field Values

GIF89a

public static final int GIF89a

Indicates GIF89a file version.

See Also:

Constant Field Values

IMAGE_SEPARATOR

public static final int IMAGE_SEPARATOR

Image separator block label.

See Also:

Constant Field Values

EXTENSION_INTRODUCER

public static final int EXTENSION_INTRODUCER

Extension introducer block label.

See Also:

Constant Field Values

TRAILER

public static final int TRAILER

Trailer block label.

See Also:

Constant Field Values

PLAIN_TEXT

public static final int PLAIN_TEXT

Plain text extension label.

See Also:

Constant Field Values

APPLICATION

public static final int APPLICATION

Application extension label.

See Also:

Constant Field Values

COMMENT

public static final int COMMENT

Comment extension label.

See Also:

Constant Field Values

GRAPHIC_CONTROL

public static final int GRAPHIC_CONTROL

Graphic control extension label.

See Also:

Constant Field Values

NETSCAPE2_0

public static final String NETSCAPE2_0

Application extension identifier.

See Also:

Constant Field Values

NONE

public static final int NONE

Disposal type identifier.

See Also:

Constant Field Values

LEAVE_IN_PLACE

public static final int LEAVE_IN_PLACE

Disposal type identifier.

See Also:

Constant Field Values

RESTORE_TO_BACKGROUND

public static final int RESTORE_TO_BACKGROUND

Disposal type identifier.

See Also:

Constant Field Values

RESTORE_TO_PREVIOUS

public static final int RESTORE_TO_PREVIOUS

Disposal type identifier.

See Also:

Constant Field Values

Constructor Detail

GIFImage

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

Creates a GIF image using a global color table.

Parameters:

pixels - Array storing pixel values.

width - Width of image to create.

Throws:

GIFFormatException - if more than 256 colours encountered.

GIFImage

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

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

Parameters:

pixels - Array storing pixel values.

width - Width of image to create.

localColorTable - True if local colour table to be used.

Throws:

GIFFormatException - if more than 256 colours are encountered.

GIFImage

public GIFImage(GIFInputStream input)
         throws IOException

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

Parameters:

input - Input stream from which to read image data.

Throws:

IOException - if problem reading from input 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 colour table is used.

Parameters:

pixels - Array storing pixel values.

width - Width of image to create.

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.

Parameters:

pixels - Array storing pixel values.

width - Width of image to add.

localColorTable - True if local colour table to be used.

Throws:

GIFFormatException - if more than 256 colours are encountered.

getRGBPixels

public int[] getRGBPixels()

Returns the RGB pixels of the primary image.

Returns:

Primary image pixels.

getRGBPixels

public int[] getRGBPixels(int imageIndex)

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

Parameters:

imageIndex - Index of image to return.

Returns:

Image pixels.

write

public void write(GIFOutputStream output)
           throws IOException

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

Parameters:

output - Output stream to write to.

Throws:

IOException - if problem writing to stream.

read

public void read(GIFInputStream input)
          throws IOException

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

Parameters:

input - Input stream from which to read image data.

Throws:

IOException - if problem reading from input stream.

toString

public String toString()

Provides a string representation of the gif file - includes all image data including actual pixels. This is likely to be a large string so care should be exercised when calling this method.

Overrides:

toString in class Object

Returns:

Textual representation of the image.

countImages

public int countImages()

Reports the number of table-based images present.

Returns:

Number of images.

isImageInterlaced

public boolean isImageInterlaced()

Reports whether or not the primary image is interlaced.

Returns:

True if interlaced.

isImageInterlaced

public boolean isImageInterlaced(int imageIndex)

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

Parameters:

imageIndex - Index of image to examine.

Returns:

True if given image is interlaced.

setImageInterlaced

public void setImageInterlaced(boolean isInterlaced)

Sets the primary image as either interlaced or non-interlaced.

Parameters:

isInterlaced - If true, primary image will be interlaced.

setImageInterlaced

public void setImageInterlaced(int imageIndex,
                               boolean isInterlaced)

Sets the image at the given index as either interlaced or non-interlaced.

Parameters:

imageIndex - Index of image to change.

isInterlaced - If true, image will be interlaced.

getTransparentColor

public Color getTransparentColor()

Reports the RGB transparent colour of the primary image.

Returns:

The transparent colour.

getTransparentColor

public Color getTransparentColor(int imageIndex)

Reports the RGB transparent colour of the image at the given index.

Parameters:

imageIndex - Index of image to examine.

Returns:

The transparent colour.

setTransparentColor

public void setTransparentColor(Color trans)

Sets the RGB transparent colour of the primary image.

Parameters:

trans - The colour which will become transparent.

setTransparentColor

public void setTransparentColor(int imageIndex,
                                Color trans)

Sets the RGB transparent colour of the image at the given index.

Parameters:

imageIndex - Index of image to set transparency for.

trans - The colour which will become transparent.

getWidth

public int getWidth(int imageIndex)

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

Parameters:

imageIndex - Index of image to examine.

Returns:

Width of image.

getWidth

public int getWidth()

Reports the pixel width of the primary image.

Returns:

Width of image.

getHeight

public int getHeight(int imageIndex)

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

Parameters:

imageIndex - Index of image to examine.

Returns:

Height of the image.

getHeight

public int getHeight()

Reports the pixel height of the primary image.

Returns:

Height of the image.

getDelay

public int getDelay()

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

Returns:

Time delay of the primary image.

getDelay

public int getDelay(int imageIndex)

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

Parameters:

imageIndex - Index of image to examine.

Returns:

Time delay of the selected image.

setDelay

public void setDelay(int delay)

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

Parameters:

delay - Time delay in 1/100s of a second.

setDelay

public void setDelay(int imageIndex,
                     int delay)

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

Parameters:

imageIndex - Index of image to manipulate.

delay - Time delay in 1/100s of a second.

setIterationCount

public void setIterationCount(int iterationCount)

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

Parameters:

iterationCount - Number of times to repeat, or 0 if indefinite repitition.

getIterationCount

public int getIterationCount()

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

Returns:

Number of iterations.

getBppForImage

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

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

Parameters:

tbi - Table based image to examine.

Returns:

Colour depth of the given table based image.

getColorTableForImage

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

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

Parameters:

tbi - Table based image to examine.

Returns:

Colour table of the given table-based image.

bppForNumColors

protected int bppForNumColors(int numColors)

Calculates the minimum BPP (colour depth) for the given number of colours.

Parameters:

numColors - Number of colours upon which to base calculation.

Returns:

Colour depth required to represent given number of colours.

makeIndexedColor

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

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

Parameters:

rgbPixels - Pixels of un-indexed image.

indexedPixels - Array to contain indexed image.

localColorTable - Local colour table used if true, otherwise global.

Returns:

Colour table used by the indexed pixel image.

Throws:

GIFFormatException - if more than 256 colors are found