net.sourceforge.jiu.codecs

Class GIFCodec


public class GIFCodec
extends ImageCodec

A codec to write Compuserve GIF (Graphics Interchange Format) files.

Only writing GIF files is supported right now. Reading GIF files with JIU can be done with the ToolkitLoader class which uses the image reader built into the Java runtime library (java.awt.Toolkit class). That reader has supported GIF since Java 1.0.

Supported image types

When saving, classes implementing the following image data interfaces are supported: BilevelImage, Gray8Image and Paletted8Image. GIF only supports up to 256 colors in an image, so you will have to use one of the quantization classes to reduce a truecolor image to 256 or less colors before you can save it with this codec.

Supported I/O classes

This codec supports java.io.OutputStream, java.io.DataOutput and java.io.RandomAccessFile.

Bounds

ImageCodec's bounds concept is supported. A user of this codec can specify a rectangular part of the input image that will be saved instead of the complete image.

Comments

GIF - at least in its 89a version - allows for the inclusion of textual comments. When saving an image to a GIF file, each comment given to a codec will be stored in a comment extension block of its own.

Usage example

Save an image using this codec:
 GIFCodec codec = new GIFCodec();
 codec.appendComment("Bob and Susan at the Munich airport (2002-06-13).");
 codec.setImage(image); // BilevelImage, Gray8Image or Paletted8Image
 codec.setInterlacing(true);
 codec.setFile("output.gif", CodecMode.SAVE);
 codec.process();
 codec.close();
 

Interlaced storage

This codec allows creating interlaced and non-interlaced GIF files. The default is non-interlaced storage. Non-interlaced files store the rows top-to-bottom.

Interlaced files store the image in four passes, progressively adding rows until the complete image is stored. When decoding, the progressive display of interlaced files makes it supposedly quicker to find out what's displayed in the image.

On the other hand, transmission typically takes longer, because interlacing often leads to slightly larger files. When using interlaced mode, lines that get stored one after another have some room between them in the image, so there are less similarities between consecutive lines, which worsens compression ratio (compression works better with a lot of similarities in the data to be compressed).

GIF versions

There are two versions of GIF, 87a and 89a. In 89a, several things were added to the file format specification. From the 89a features this codec only uses the possibility of storing textual comments in GIF files. Thus, the version used for writing depends on the return value of getNumComments(). If there is at least one comment to be written to the file, version 89a will be used, 87a otherwise.

Licensing of the LZW algorithm

Unisys Corp. had a patent in several countries on the LZW algorithm used within GIF. However, this patent has expired (Japan being the last country where the patent expired, on July 7th 2004) so that LZW can be used freely.

Licensing of the file format

GIF was defined by Compuserve. In a technical document file called Gif89a.txt that I found somewhere on the Net they grant a royalty-free license for use of the format to anyone - in order to improve the popularity of the format, I guess. I don't think that it should be possible to put a file format under a copyright, but all that Compuserve asks for in exchange for freely using the format is the inclusion of a message. So, here is that message:
"The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated."

Animated GIFs

GIF allows for animations to be stored. This codec only supports storing a single image, though.

File format background

I've compiled a web page with technical information on GIF.
Author:
Marco Schmidt

Field Summary

private static int
CODE_ARRAY_LENGTH
private static int[]
INTERLACING_FIRST_ROW
private static int[]
INTERLACING_INCREMENT
private static byte[]
MAGIC_GIF87A
private static byte[]
MAGIC_GIF89A
private static int
NUM_INTERLACING_PASSES
private int
backgroundColor
private int
bitOffset
private int
bitsPerPixel
private byte[]
block
private int
blockLength
private int
clearCode
private int
codeSize
private int[]
currentCode
private int
currentColumn
private int
currentInterlacingPass
private int
currentRow
private int
endOfInformationCode
private int
freeCode
private int
height
private IntegerImage
imageToBeSaved
private int
initialCodeSize
private boolean
interlaced
private int
maxCode
private int[]
newCode
private boolean
notFinished
private int[]
oldCode
private DataOutput
out
private int
processedRows
private int
width

Fields inherited from class net.sourceforge.jiu.codecs.ImageCodec

boundsAvail, boundsHeight, boundsWidth, boundsX1, boundsX2, boundsY1, boundsY2, comments, din, dout, dpiX, dpiY, image, imageIndex, in, mode, out, raf

Fields inherited from class net.sourceforge.jiu.ops.Operation

abort, progressListeners

Method Summary

int
getBackgroundColor()
Returns the index of the background color.
String[]
getFileExtensions()
String
getFormatName()
String[]
getMimeTypes()
private int
getNextSample()
private void
initEncoding()
boolean
isInterlaced()
Returns if the image will be stored in interlaced (true) or non-interlaced mode (false).
boolean
isLoadingSupported()
boolean
isSavingSupported()
void
process()
This method does the actual work of the operation.
private void
resetBlock()
private void
resetEncoder()
private void
save()
void
setBackgroundColor(int colorIndex)
Specify the value of the background color.
void
setInterlacing(boolean useInterlacing)
Specifies whether the image will be stored in interlaced mode (true) or non-interlaced mode (false).
private void
writeBlock()
private void
writeCode(int code)
private void
writeComments()
private void
writeHeader()
Writes a global header, a global palette and an image descriptor to output.
private void
writeImage()
private void
writePalette()
private void
writeShort(int value)
private void
writeStream()
private void
writeTrailer()

Methods inherited from class net.sourceforge.jiu.codecs.ImageCodec

appendComment, checkBounds, checkImageResolution, close, getBoundsHeight, getBoundsWidth, getBoundsX1, getBoundsX2, getBoundsY1, getBoundsY2, getComment, getDataInput, getDataOutput, getDpiX, getDpiY, getFileExtensions, getFormatName, getImage, getImageIndex, getInputAsDataInput, getInputStream, getMimeTypes, getMode, getNumComments, getOutputAsDataOutput, getOutputStream, getRandomAccessFile, hasBounds, initModeFromIOObjects, isLoadingSupported, isRowRequired, isSavingSupported, isTileRequired, removeAllComments, removeBounds, setBounds, setBoundsIfNecessary, setDataInput, setDataOutput, setDpi, setFile, setFile, setImage, setImageIndex, setInputStream, setOutputStream, setRandomAccessFile, suggestFileExtension

Methods inherited from class net.sourceforge.jiu.ops.Operation

addProgressListener, addProgressListeners, getAbort, process, removeProgressListener, setAbort, setProgress, setProgress

Field Details

CODE_ARRAY_LENGTH

private static final int CODE_ARRAY_LENGTH
Field Value:
5020

INTERLACING_FIRST_ROW

private static final int[] INTERLACING_FIRST_ROW

INTERLACING_INCREMENT

private static final int[] INTERLACING_INCREMENT

MAGIC_GIF87A

private static final byte[] MAGIC_GIF87A

MAGIC_GIF89A

private static final byte[] MAGIC_GIF89A

NUM_INTERLACING_PASSES

private static final int NUM_INTERLACING_PASSES
Field Value:
4

backgroundColor

private int backgroundColor

bitOffset

private int bitOffset

bitsPerPixel

private int bitsPerPixel

block

private byte[] block

blockLength

private int blockLength

clearCode

private int clearCode

codeSize

private int codeSize

currentCode

private int[] currentCode

currentColumn

private int currentColumn

currentInterlacingPass

private int currentInterlacingPass

currentRow

private int currentRow

endOfInformationCode

private int endOfInformationCode

freeCode

private int freeCode

height

private int height

imageToBeSaved

private IntegerImage imageToBeSaved

initialCodeSize

private int initialCodeSize

interlaced

private boolean interlaced

maxCode

private int maxCode

newCode

private int[] newCode

notFinished

private boolean notFinished

oldCode

private int[] oldCode

out

private DataOutput out

processedRows

private int processedRows

width

private int width

Method Details

getBackgroundColor

public int getBackgroundColor()
Returns the index of the background color.
Returns:
int value with the color (index into the palette) of the background color

getFileExtensions

public String[] getFileExtensions()
Overrides:
getFileExtensions in interface ImageCodec

getFormatName

public String getFormatName()
Overrides:
getFormatName in interface ImageCodec

getMimeTypes

public String[] getMimeTypes()
Overrides:
getMimeTypes in interface ImageCodec

getNextSample

private int getNextSample()

initEncoding

private void initEncoding()
            throws IOException

isInterlaced

public boolean isInterlaced()
Returns if the image will be stored in interlaced (true) or non-interlaced mode (false).
Returns:
interlacing mode

isLoadingSupported

public boolean isLoadingSupported()
Overrides:
isLoadingSupported in interface ImageCodec

isSavingSupported

public boolean isSavingSupported()
Overrides:
isSavingSupported in interface ImageCodec

process

public void process()
            throws MissingParameterException,
                   OperationFailedException
This method does the actual work of the operation. It must be called after all parameters have been given to the operation object.
Overrides:
process in interface Operation
Throws:
MissingParameterException - if any mandatory parameter was not given to the operation
OperationFailedException -

resetBlock

private void resetBlock()

resetEncoder

private void resetEncoder()

save

private void save()
            throws MissingParameterException,
                   OperationFailedException,
                   UnsupportedTypeException,
                   WrongParameterException

setBackgroundColor

public void setBackgroundColor(int colorIndex)
Specify the value of the background color. Default is 0.
Parameters:
colorIndex - int value with the color (index into the palette) of the background color

setInterlacing

public void setInterlacing(boolean useInterlacing)
Specifies whether the image will be stored in interlaced mode (true) or non-interlaced mode (false).
Parameters:
useInterlacing - boolean, if true interlaced mode, otherwise non-interlaced mode

writeBlock

private void writeBlock()
            throws IOException

writeCode

private void writeCode(int code)
            throws IOException

writeComments

private void writeComments()
            throws IOException

writeHeader

private void writeHeader()
            throws IOException
Writes a global header, a global palette and an image descriptor to output.

writeImage

private void writeImage()
            throws IOException

writePalette

private void writePalette()
            throws IOException

writeShort

private void writeShort(int value)
            throws IOException

writeStream

private void writeStream()
            throws IOException

writeTrailer

private void writeTrailer()
            throws IOException