jwo.utils.gifutils
Class GIFImage

java.lang.Object
  extended by 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


Copyright Jo Wood, 1996-2009, last modified, 17th April, 2009