AnimatedGifEncoder (Unidata IDV API v6.3)

java.lang.Object
- ucar.unidata.ui.AnimatedGifEncoder

public class AnimatedGifEncoder
extends java.lang.Object

Class AnimatedGifEncoder - Encodes a GIF file consisting of one or more frames.

Extensively Modified for ImagePlus
Extended to handle 8 bit Images with more complex Color lookup tables with transparency index

Ryan Raz March 2002
raz@rraz.ca
Version 1.01
Extensively Modified for ImagePlus
Extended to handle 8 bit Images with more complex Color lookup tables with transparency index

Ryan Raz March 2002
ryan@rraz.ca
Version 1.01 Please report any bugs

Operation Manual

1) Load stack with 8 bit or RGB images it is possible to use the animated gif reader but because the color
table is lost it is best to also load a separate copy of the first image in the series this will allow
extraction of the original image color look up table (see 1below)
2)Check the option list to bring up the option list.
3)Experiment with the option list. I usually use a global color table to save space, set to do not dispose if
each consecutive image is overlayed on the previous image.
4)Color table can be imported from another image or extracted from 8bit stack images or loaded as the
first 256 RGB triplets from a RGB images, the last mode takes either a imported image or current
stack and creates the color table from scratch.

To do list

1) Modify existing Animated Gif reader plug in to import in 8 bit mode (currently only works in
RGB mode. Right now the best way to alter an animated gif is to save the first image separately
and then read the single gif and use the plugin animated reader to read the animated gif to the
stack. Let this plugin encode the stack using the single gif's color table.
2) Add support for background colors easy but I have no use for them
3) RGB to 8 bit converter is a linear search. Needs to be replaced with sorted list and fast search. But
this update could cause problems with some types of gifs. Easy fix get a faster computer.
4) Try updating NN color converter seems to be heavily weighted towards quantity of pixels.
example:
if there is 90% of the image covered in shades of one color or grey the 10% of other colors tend
to be poorly represented it over fits the shades and under fits the others. Works well if the
distribution is balanced.
5) Add support for all sizes of Color Look Up tables.
6) Re-code to be cleaner. This is my second Java program and I started with some code with too
many global variables and I added more switches so its a bit hard to follow.

Credits for the base conversion codes
No copyright asserted on the source code of this class. May be used
for any purpose, however, refer to the Unisys LZW patent for restrictions
on use of the associated LZWEncoder class. Please forward any corrections
to kweiner@fmsware.com.

Version:: 1.0 December 2000 Example: AnimatedGifEncoder e = new AnimatedGifEncoder(); e.start(outputFileName); e.addFrame(image1); e.addFrame(image2); " " " e.finish();
Author:: Kevin Weiner, FM Software

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`autotransparent` autotransparency flag
`protected boolean`	`closeStream` closeStream flag
`protected int`	`colorDepth` number of bit planes
`protected byte[]`	`colorTab` RGB palette
`protected int`	`delay` frame delay
`protected int`	`dispose` disposal code
`protected boolean`	`firstFrame` first frame flag
`protected byte[]`	`gct` global color table
`protected int`	`GCTbl` blue color
`protected int`	`GCTcindex` global color table index
`protected boolean`	`GCTextracted` flag for extracting global color table
`protected int`	`GCTgrn` green color
`protected boolean`	`GCTloadedExternal` flag for global color table from external image
`protected boolean`	`GCToverideColor` gct overide color flag
`protected boolean`	`GCToverideIndex` gct overide index flag
`protected int`	`GCTred` red color
`protected boolean`	`GCTsetTransparent` gct transparency flag
`protected boolean`	`gctused` use global color table flag
`protected int`	`height` image height
`protected ij.ImagePlus`	`image` current frame
`protected byte[]`	`indexedPixels` converted frame indexed to palette
`protected int`	`lctSize` local color table size
`protected java.io.OutputStream`	`out` output stream
`protected byte[]`	`pixels` BGR byte array from frame
`protected int`	`repeat` repeat factor
`static int`	`REPEAT_FOREVER` Repeat forever flag
`protected int`	`sample` default sample interval
`protected boolean`	`sizeSet` set size flag
`protected boolean`	`started` started flag
`protected int`	`transIndex` transparency index
`protected boolean`	`transparent` transparent flag
`protected int`	`width` image width

Constructor Summary

Constructors
Constructor and Description

AnimatedGifEncoder()

Constructors
Constructor and Description
`AnimatedGifEncoder()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`addFrame(ij.ImagePlus image)` Adds next GIF frame.
`boolean`	`addFrame(ij.ImagePlus image, int theDelay)` Adds next GIF frame.
`protected void`	`analyzePixels()` Analyzes image colors and creates color map.
`static void`	`createGif(java.io.OutputStream outputStream, java.awt.Image image)` Create a GIF
`static void`	`createGif(java.lang.String filename, java.awt.Image image)` Create a GIF
`static void`	`createGif(java.lang.String filename, java.util.List images)` Create an animated GIF
`static void`	`createGif(java.lang.String filename, java.util.List images, int repeat, int delay)` Create an animated GIF
`static void`	`createGif(java.lang.String filename, java.util.List images, int repeat, int delay, int endDelay)` Create an animated GIF
`static void`	`createGif(java.lang.String filename, java.util.List images, int repeat, int delay, int endDelay, boolean useGlobalTable)` Create an animated GIF
`void`	`extractGCTrgb(ij.ImagePlus image)` Function to extract Global Color Table from RGB ImagePlus This function has to be called before addFrame
`protected int`	`findClosest(byte[] colorTab, int r, int g, int b)` Returns index of palette color closest to c
`boolean`	`finish()` Flushes any pending data and closes output file.
`void`	`GlobalColorTableused(boolean gtu)` Set True for Global Color Table use This saves space in the output file but colors may not be so goodif the stack uses True color images
`void`	`loadGCT8bit(ij.ImagePlus image)` Function to load Global Color Table from 8 bit ImagePlus This function has to be called before addFrame
`void`	`loadGCTrgb(ij.ImagePlus image)` Function to use the first up to 255 elements of a RGB ImagePlus to construct a global color table.
`void`	`OverRideQuality(int npixs)` Sets Net sample size depending on image size
`void`	`setDelay(int ms)` Sets the delay time between each frame, or changes it for subsequent frames (applies to last frame added).
`void`	`setDispose(int code)` Sets the GIF frame disposal code for the last added frame and any subsequent frames.
`void`	`setFrameRate(float fps)` Sets frame rate in frames per second.
`void`	`setGCT(boolean flag)` If gct = true then a global color table is use
`void`	`setoptions()` Set the options
`void`	`setQuality(int quality)` Sets quality of color quantization (conversion of images to the maximum 256 colors allowed by the GIF specification).
`void`	`setRepeat(int iter)` Sets the number of times the set of GIF frames should be played.
`void`	`setSize(int w, int h)` Sets the GIF frame size.
`void`	`setTransparent(boolean c)` Sets the transparent color for the last added frame and any subsequent frames.
`boolean`	`start(java.io.OutputStream os)` Initiates GIF file creation on the given stream.
`boolean`	`start(java.lang.String file)` Initiates writing of a GIF file with the specified name.
`protected void`	`writeGraphicCtrlExt(int delay)` Writes Graphic Control Extension
`protected void`	`writeImageDesc()` Writes Image Descriptor
`protected void`	`writeLSD()` Writes Logical Screen Descriptor without global color table
`protected void`	`writeLSDgct()` Writes Logical Screen Descriptor with global color table
`protected void`	`writeNetscapeExt()` Writes Netscape application extension to define repeat count.
`protected void`	`writePalette()` Writes color table
`protected void`	`writePixels()` Encodes and writes pixel data
`protected void`	`writeShort(int value)` Write 16-bit value to output stream, LSB first
`protected void`	`writeString(java.lang.String s)` Writes string to output stream

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - REPEAT_FOREVER
```
public static final int REPEAT_FOREVER
```
    Repeat forever flag
    
    See Also:
    
    Constant Field Values
  - width
```
protected int width
```
    image width
  - height
```
protected int height
```
    image height
  - transparent
```
protected boolean transparent
```
    transparent flag
  - transIndex
```
protected int transIndex
```
    transparency index
  - repeat
```
protected int repeat
```
    repeat factor
  - delay
```
protected int delay
```
    frame delay
  - started
```
protected boolean started
```
    started flag
  - out
```
protected java.io.OutputStream out
```
    output stream
  - image
```
protected ij.ImagePlus image
```
    current frame
  - pixels
```
protected byte[] pixels
```
    BGR byte array from frame
  - indexedPixels
```
protected byte[] indexedPixels
```
    converted frame indexed to palette
  - colorDepth
```
protected int colorDepth
```
    number of bit planes
  - colorTab
```
protected byte[] colorTab
```
    RGB palette
  - lctSize
```
protected int lctSize
```
    local color table size
  - dispose
```
protected int dispose
```
    disposal code
  - closeStream
```
protected boolean closeStream
```
    closeStream flag
  - firstFrame
```
protected boolean firstFrame
```
    first frame flag
  - sizeSet
```
protected boolean sizeSet
```
    set size flag
  - sample
```
protected int sample
```
    default sample interval
  - gct
```
protected byte[] gct
```
    global color table
  - gctused
```
protected boolean gctused
```
    use global color table flag
  - autotransparent
```
protected boolean autotransparent
```
    autotransparency flag
  - GCTextracted
```
protected boolean GCTextracted
```
    flag for extracting global color table
  - GCTloadedExternal
```
protected boolean GCTloadedExternal
```
    flag for global color table from external image
  - GCTred
```
protected int GCTred
```
    red color
  - GCTgrn
```
protected int GCTgrn
```
    green color
  - GCTbl
```
protected int GCTbl
```
    blue color
  - GCTcindex
```
protected int GCTcindex
```
    global color table index
  - GCTsetTransparent
```
protected boolean GCTsetTransparent
```
    gct transparency flag
  - GCToverideIndex
```
protected boolean GCToverideIndex
```
    gct overide index flag
  - GCToverideColor
```
protected boolean GCToverideColor
```
    gct overide color flag
- Constructor Detail
  - AnimatedGifEncoder
```
public AnimatedGifEncoder()
```
- Method Detail
  - createGif
```
public static void createGif(java.lang.String filename,
                             java.awt.Image image)
```
    Create a GIF
    
    Parameters:
    
    filename - output file name
    
    image - the image object
  - createGif
```
public static void createGif(java.io.OutputStream outputStream,
                             java.awt.Image image)
```
    Create a GIF
    
    Parameters:
    
    outputStream - the output stream
    
    image - the image object
  - createGif
```
public static void createGif(java.lang.String filename,
                             java.util.List images)
```
    Create an animated GIF
    
    Parameters:
    
    filename - output file name
    
    images - list of images
  - createGif
```
public static void createGif(java.lang.String filename,
                             java.util.List images,
                             int repeat,
                             int delay)
```
    Create an animated GIF
    
    Parameters:
    
    filename - output file name
    
    images - list of images
    
    repeat - number of times to repeat
    
    delay - delay between images
  - createGif
```
public static void createGif(java.lang.String filename,
                             java.util.List images,
                             int repeat,
                             int delay,
                             int endDelay)
```
    Create an animated GIF
    
    Parameters:
    
    filename - output file name
    
    images - list of images
    
    repeat - number of times to repeat
    
    delay - delay between images
    
    endDelay - delay on last image
  - createGif
```
public static void createGif(java.lang.String filename,
                             java.util.List images,
                             int repeat,
                             int delay,
                             int endDelay,
                             boolean useGlobalTable)
```
    Create an animated GIF
    
    Parameters:
    
    filename - output file name
    
    images - list of images
    
    repeat - number of times to repeat
    
    delay - delay between images
    
    endDelay - delay on last image
    
    useGlobalTable - true to use a global color table
  - addFrame
```
public boolean addFrame(ij.ImagePlus image)
```
    Adds next GIF frame. The frame is not written immediately, but is actually deferred until the next frame is received so that timing data can be inserted. Invoking finish() flushes all frames. If setSize was not invoked, the size of the first image is used for all subsequent frames.
    
    Parameters:
    
    image - the image to add
    
    Returns:
    
    true if successful.
  - addFrame
```
public boolean addFrame(ij.ImagePlus image,
                        int theDelay)
```
    Adds next GIF frame.
    
    Parameters:
    
    image - the image to add
    
    theDelay - delay in loop
    
    Returns:
    
    true if successful.
  - setoptions
```
public void setoptions()
```
    Set the options
  - finish
```
public boolean finish()
```
    Flushes any pending data and closes output file. If writing to an OutputStream, the stream is not closed.
    
    Returns:
    
    true if successful
  - loadGCT8bit
```
public void loadGCT8bit(ij.ImagePlus image)
```
    Function to load Global Color Table from 8 bit ImagePlus This function has to be called before addFrame
    
    Parameters:
    
    image - the image
  - extractGCTrgb
```
public void extractGCTrgb(ij.ImagePlus image)
```
    Function to extract Global Color Table from RGB ImagePlus This function has to be called before addFrame
    
    Parameters:
    
    image - the image
  - loadGCTrgb
```
public void loadGCTrgb(ij.ImagePlus image)
```
    Function to use the first up to 255 elements of a RGB ImagePlus to construct a global color table. This function has to be called before addFrame
    
    Parameters:
    
    image - the image
  - setGCT
```
public void setGCT(boolean flag)
```
    If gct = true then a global color table is use
    
    Parameters:
    
    flag - the gct flag
  - setDelay
```
public void setDelay(int ms)
```
    Sets the delay time between each frame, or changes it for subsequent frames (applies to last frame added).
    
    Parameters:
    
    ms - int delay time in milliseconds
  - setDispose
```
public void setDispose(int code)
```
    Sets the GIF frame disposal code for the last added frame and any subsequent frames. Default is 0 if no transparent color has been set, otherwise 2.
    
    Parameters:
    
    code - int disposal code.
  - setFrameRate
```
public void setFrameRate(float fps)
```
    Sets frame rate in frames per second. Equivalent to setDelay(1000/fps).
    
    Parameters:
    
    fps - float frame rate (frames per second)
  - setQuality
```
public void setQuality(int quality)
```
    Sets quality of color quantization (conversion of images to the maximum 256 colors allowed by the GIF specification). Lower values (minimum = 1) produce better colors, but slow processing significantly. 10 is the default, and produces good color mapping at reasonable speeds. Values greater than 20 do not yield significant improvements in speed.
    
    Parameters:
    
    quality - int greater than 0.
  - GlobalColorTableused
```
public void GlobalColorTableused(boolean gtu)
```
    Set True for Global Color Table use This saves space in the output file but colors may not be so goodif the stack uses True color images
    
    Parameters:
    
    gtu - the gtu flag
  - setRepeat
```
public void setRepeat(int iter)
```
    Sets the number of times the set of GIF frames should be played. Default is 1; 0 means play indefinitely. Must be invoked before the first image is added.
    
    Parameters:
    
    iter - int number of iterations.
  - setSize
```
public void setSize(int w,
                    int h)
```
    Sets the GIF frame size. The default size is the size of the first frame added if this method is not invoked.
    
    Parameters:
    
    w - int frame width.
    
    h - int frame width.
  - setTransparent
```
public void setTransparent(boolean c)
```
    Sets the transparent color for the last added frame and any subsequent frames. Since all colors are subject to modification in the quantization process, the color in the final palette for each frame closest to the given color becomes the transparent color for that frame. May be set to null to indicate no transparent color.
    
    Parameters:
    
    c - Color to be treated as transparent on display.
  - start
```
public boolean start(java.io.OutputStream os)
```
    Initiates GIF file creation on the given stream. The stream is not closed automatically.
    
    Parameters:
    
    os - OutputStream on which GIF images are written.
    
    Returns:
    
    false if initial write failed.
  - start
```
public boolean start(java.lang.String file)
```
    Initiates writing of a GIF file with the specified name.
    
    Parameters:
    
    file - String containing output file name.
    
    Returns:
    
    false if open or initial write failed.
  - OverRideQuality
```
public void OverRideQuality(int npixs)
```
    Sets Net sample size depending on image size
    
    Parameters:
    
    npixs - the number of pixels
  - analyzePixels
```
protected void analyzePixels()
```
    Analyzes image colors and creates color map.
  - findClosest
```
protected int findClosest(byte[] colorTab,
                          int r,
                          int g,
                          int b)
```
    Returns index of palette color closest to c
    
    Parameters:
    
    colorTab - the table
    
    r - red
    
    g - green
    
    b - blue
    
    Returns:
    
    the index
  - writeGraphicCtrlExt
```
protected void writeGraphicCtrlExt(int delay)
                            throws java.io.IOException
```
    Writes Graphic Control Extension
    
    Parameters:
    
    delay - the delay
    
    Throws:
    
    java.io.IOException - problem writing
  - writeImageDesc
```
protected void writeImageDesc()
                       throws java.io.IOException
```
    Writes Image Descriptor
    
    Throws:
    
    java.io.IOException - problem writing
  - writeLSDgct
```
protected void writeLSDgct()
                    throws java.io.IOException
```
    Writes Logical Screen Descriptor with global color table
    
    Throws:
    
    java.io.IOException - problem writing
  - writeLSD
```
protected void writeLSD()
                 throws java.io.IOException
```
    Writes Logical Screen Descriptor without global color table
    
    Throws:
    
    java.io.IOException - problem writing
  - writeNetscapeExt
```
protected void writeNetscapeExt()
                         throws java.io.IOException
```
    Writes Netscape application extension to define repeat count.
    
    Throws:
    
    java.io.IOException - problem writing
  - writePalette
```
protected void writePalette()
                     throws java.io.IOException
```
    Writes color table
    
    Throws:
    
    java.io.IOException - problem writing
  - writePixels
```
protected void writePixels()
                    throws java.io.IOException
```
    Encodes and writes pixel data
    
    Throws:
    
    java.io.IOException - problem writing
  - writeShort
```
protected void writeShort(int value)
                   throws java.io.IOException
```
    Write 16-bit value to output stream, LSB first
    
    Parameters:
    
    value - the value
    
    Throws:
    
    java.io.IOException - problem writing
  - writeString
```
protected void writeString(java.lang.String s)
                    throws java.io.IOException
```
    Writes string to output stream
    
    Parameters:
    
    s - the string
    
    Throws:
    
    java.io.IOException - problem writing

Class AnimatedGifEncoder

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

REPEAT_FOREVER

width

height

transparent

transIndex

repeat

delay

started

out

image

pixels

indexedPixels

colorDepth

colorTab

lctSize

dispose

closeStream

firstFrame

sizeSet

sample

gct

gctused

autotransparent

GCTextracted

GCTloadedExternal

GCTred

GCTgrn

GCTbl

GCTcindex

GCTsetTransparent

GCToverideIndex

GCToverideColor

Constructor Detail

AnimatedGifEncoder

Method Detail

createGif

createGif

createGif

createGif

createGif

createGif

addFrame

addFrame

setoptions

finish

loadGCT8bit

extractGCTrgb

loadGCTrgb

setGCT

setDelay

setDispose

setFrameRate

setQuality

GlobalColorTableused

setRepeat

setSize

setTransparent

start

start

OverRideQuality

analyzePixels

findClosest

writeGraphicCtrlExt

writeImageDesc

writeLSDgct

writeLSD

writeNetscapeExt

writePalette

writePixels

writeShort

writeString