Previous section To contents Next section

12.13 Image.GIF

DESCRIPTION
This submodule keep the GIF encode/decode capabilities of the Image module.

GIF is a common image storage format, usable for a limited color palette - a GIF image can only contain as most 256 colors - and animations.

Simple encoding: encode, encode_trans

Advanced stuff: render_block, header_block, end_block, netscape_loop_block

Very advanced stuff: _render_block, _gce_block

SEE ALSO
Image, Image.Image and Image.Colortable

METHOD
Image.GIF.decode

SYNTAX
object decode(string data)
object decode(array _decoded)
object decode(array __decoded)

DESCRIPTION
Decodes GIF data and creates an image object.

RETURNS
the decoded image as an image object

NOTE
This function may throw errors upon illegal GIF data. This function uses __decode, _decode, Image.Image->paste and Image.Image->paste_alpha internally.

SEE ALSO
encode

METHOD
Image.GIF.decode_layers,
Image.GIF.decode_layer

SYNTAX
object decode_layers(string data)
object decode_layers(array _decoded)
object decode_layer(string data)
object decode_layer(array _decoded)

DESCRIPTION
Decodes GIF data and creates an array of layers or the resulting layer.

NOTE
The resulting layer may not have the same size as the gif image, but the resulting bounding box of all render chunks in the gif file. The offset should be correct, though.

SEE ALSO
encode and decode_map

METHOD
Image.GIF.decode_map

SYNTAX
mapping decode_map(INT32 args)

DESCRIPTION
Returns a mapping similar to other decoders _decode function. 

"image":the image
"alpha":the alpha channel


"xsize":int
"ysize":int
size of image
"type":"image/gif"
file type information as MIME type

NOTE
The wierd name of this function (not _decode as the other decoders) is because gif was the first decoder and was written before the API was finally defined. Sorry about that. /Mirar

METHOD
Image.GIF.encode,
Image.GIF.encode_trans

SYNTAX
string encode(object img);
string encode(object img, int colors);
string encode(object img, object colortable);
string encode_trans(object img, object alpha);
string encode_trans(object img, int tr_r, int tr_g, int tr_b);
string encode_trans(object img, int colors, object alpha);
string encode_trans(object img, int colors, int tr_r, int tr_g, int tr_b);
string encode_trans(object img, int colors, object alpha, int tr_r, int tr_g, int tr_b);
string encode_trans(object img, object colortable, object alpha);
string encode_trans(object img, object colortable, int tr_r, int tr_g, int tr_b);
string encode_trans(object img, object colortable, object alpha, int a_r, int a_g, int a_b);
string encode_trans(object img, object colortable, int transp_index);

DESCRIPTION
Create a complete GIF file.

The latter (encode_trans) functions add transparency capabilities.

Example: 

img=Image.Image([...]);
[...] // make your very-nice image
write(Image.GIF.encode(img)); // write it as GIF on stdout

ARGUMENTS
argument(s)description
object img
The image which to encode.
int colors
object colortable
These arguments decides what colors the image should be encoded with. If a number is given, a colortable with be created with (at most) that amount of colors. Default is '256' (GIF maximum amount of colors).
object alpha
Alpha channel image (defining what is transparent); black color indicates transparency. GIF has only transparent or nontransparent (no real alpha channel). You can always dither a transparency channel: Image.Colortable(my_alpha, ({({0,0,0}),({255,255,255})})) ->full()->floyd_steinberg()->map(my_alpha)
int tr_r
int tr_g
int tr_b
Use this (or the color closest to this) color as transparent pixels.
int a_r
int a_g
int a_b
Encode transparent pixels (given by alpha channel image) to have this color. This option is for making GIFs for the decoders that doesn't support transparency.
int transp_index
Use this color no in the colortable as transparent color.

NOTE
For advanced users: 
Image.GIF.encode_trans(img,colortable,alpha);
is equivalent of using 
Image.GIF.header_block(img->xsize(),img->ysize(),colortable)+
Image.GIF.render_block(img,colortable,0,0,0,alpha)+
Image.GIF.end_block();
and is actually implemented that way.

METHOD
Image.GIF.end_block

SYNTAX
string end_block();

DESCRIPTION
This function gives back a GIF end (trailer) block.

RETURNS
the end block as a string.

NOTE
This is in the advanced sector of the GIF support; please read some about how GIFs are packed.

The result of this function is always ";" or "\x3b", but I recommend using this function anyway for code clearity.

SEE ALSO
header_block and end_block

METHOD
Image.GIF.header_block

SYNTAX
string header_block(int xsize, int ysize, int numcolors);
string header_block(int xsize, int ysize, object colortable);
string header_block(int xsize, int ysize, object colortable, int background_color_index, int gif87a, int aspectx, int aspecty);
string header_block(int xsize, int ysize, object colortable, int background_color_index, int gif87a, int aspectx, int aspecty, int r, int g, int b);

DESCRIPTION
This function gives back a GIF header block.

Giving a colortable to this function includes a global palette in the header block.

ARGUMENTS
argument(s)description
int xsize
int ysize
Size of drawing area. Usually same size as in the first (or only) render block(s).
int background_color_index
This color in the palette is the background color. Background is visible if the following render block(s) doesn't fill the drawing area or are transparent. Most decoders doesn't use this value, though.
int gif87a
If set, write 'GIF87a' instead of 'GIF89a' (default 0 == 89a).
int aspectx
int aspecty
Aspect ratio of pixels, ranging from 4:1 to 1:4 in increments of 1/16th. Ignored by most decoders. If any of aspectx or aspecty is zero, aspectratio information is skipped.
int r
int g
int b
Add this color as the transparent color. This is the color used as transparency color in case of alpha-channel given as image object. This increases (!) the number of colors by one.

RETURNS
the created header block as a string

NOTE
This is in the advanced sector of the GIF support; please read some about how GIFs are packed.

This GIF encoder doesn't support different size of colors in global palette and color resolution.

SEE ALSO
header_block and end_block

METHOD
Image.GIF.netscape_loop_block

SYNTAX
string netscape_loop_block();
string netscape_loop_block(int number_of_loops);

DESCRIPTION
Creates a application-specific extention block; this block makes netscape and compatible browsers loop the animation a certain amount of times.

ARGUMENTS
argument(s)description
int number_of_loops
Number of loops. Max and default is 65535.

METHOD
Image.GIF.render_block

SYNTAX
string render_block(object img, object colortable, int x, int y, int localpalette);
string render_block(object img, object colortable, int x, int y, int localpalette, object alpha);
string render_block(object img, object colortable, int x, int y, int localpalette, object alpha, int r, int g, int b);
string render_block(object img, object colortable, int x, int y, int localpalette, int delay, int transp_index, int interlace, int user_input, int disposal);
string render_block(object img, object colortable, int x, int y, int localpalette, object alpha, int r, int g, int b, int delay, int interlace, int user_input, int disposal);

DESCRIPTION
This function gives a image block for placement in a GIF file, with or without transparency. The some options actually gives two blocks, the first with graphic control extensions for such things as delay or transparency.

Example: 

img1=Image.Image([...]);
img2=Image.Image([...]);
[...] // make your very-nice images
nct=Image.Colortable([...]); // make a nice colortable
write(Image.GIF.header_block(xsize,ysize,nct)); // write a GIF header
write(Image.GIF.render_block(img1,nct,0,0,0,10)); // write a render block
write(Image.GIF.render_block(img2,nct,0,0,0,10)); // write a render block
[...]
write(Image.GIF.end_block()); // write end block
// voila! A GIF animation on stdout.

The above animation is thus created: 

object nct=colortable(lena,32,({({0,0,0})}));
string s=GIF.header_block(lena->xsize(),lena->ysize(),nct);
foreach ( ({lena->xsize(),
(int)(lena->xsize()*0.75),
(int)(lena->xsize()*0.5),
(int)(lena->xsize()*0.25),
(int)(1),
(int)(lena->xsize()*0.25),
(int)(lena->xsize()*0.5),
(int)(lena->xsize()*0.75)}),int xsize)
{
object o=lena->scale(xsize,lena->ysize());
object p=lena->clear(0,0,0);
p->paste(o,(lena->xsize()-o->xsize())/2,0);
s+=GIF.render_block(p,nct,0,0,0,25);
}
s+=GIF.netscape_loop_block(200);
s+=GIF.end_block();
write(s);

ARGUMENTS
argument(s)description
object img
The image.
object colortable
Colortable with colors to use and to write as palette.
int x
int y
Position of this image.
int localpalette
If set, writes a local palette.
object alpha
Alpha channel image; black is transparent.
int r
int g
int b
Color of transparent pixels. Not all decoders understands transparency. This is ignored if localpalette isn't set.
int delay
View this image for this many centiseconds. Default is zero.
int transp_index
Index of the transparent color in the colortable. -1 indicates no transparency.
int user_input
If set: wait the delay or until user input. If delay is zero, wait indefinitely for user input. May sound the bell upon decoding. Default is non-set.
int disposal
Disposal method number;
0
No disposal specified. The decoder is not required to take any action. (default)
1
Do not dispose. The graphic is to be left in place.
2
Restore to background color. The area used by the graphic must be restored to the background color.
3
Restore to previous. The decoder is required to restore the area overwritten by the graphic with what was there prior to rendering the graphic.
4-7
To be defined.

NOTE
This is in the advanced sector of the GIF support; please read some about how GIFs are packed.

The user_input and disposal method are unsupported in most decoders.

SEE ALSO
encode, header_block and end_block

METHOD
Image.GIF._decode

SYNTAX
array _decode(string gifdata);
array _decode(array __decoded);

DESCRIPTION
Decodes a GIF image structure down to chunks, and also decode the images in the render chunks. 

({int xsize,int ysize,    // 0: size of image drawing area
void|object colortable, // 2: opt. global colortable
({ int aspx, int aspy,  // 3 0: aspect ratio or 0, 0 if not set
int background }),   //   2: index of background color
followed by any number these blocks in any order (gce chunks are decoded and incorporated in the render chunks): 
({ GIF.RENDER,          //   0: block identifier
int x, int y,         //   1: position of render
object image,         //   3: render image
void|object alpha,    //   4: 0 or render alpha channel
object colortable,    //   5: colortable (may be same as global)


int interlace,        //   6: interlace flag
int trans_index,      //   7: 0 or transparent color index
int delay,            //   8: 0 or delay in centiseconds
int user_input,       //   9: user input flag
int disposal})        //  10: disposal method number (0..7)


({ GIF.EXTENSION,       //   0: block identifier
int extension,       //   1: extension number
string data })       //   2: extension data
and possibly ended with one of these: 
({ GIF.ERROR_PREMATURE_EOD })   // premature end-of-data


({ GIF.ERROR_TOO_MUCH_DATA,     // data following end marker
string data })               // (rest of file)


({ GIF.ERROR_UNKNOWN_DATA,      // unknown data
string data })               // (rest of file)

The decode method uses this data in a way similar to this program: 

import Image;


object my_decode_gif(string data)
{
array a=GIF._decode(data);
object img=image(a[0],a[1]);
foreach (a[4..],array b)
if (b[0]==GIF.RENDER)
if (b[4]) img->paste_alpha(b[3],b[4],b[1],b[2]);
else img->paste(b[3],b[1],b[2]);
return img;
}

ARGUMENTS
argument(s)description
string gifdata
GIF data (with header and all)
array __decoded
GIF data as from __decode

RETURNS
the above array

NOTE
May throw errors if the GIF header is incomplete or illegal.

This is in the very advanced sector of the GIF support; please read about how GIF files works.

METHOD
Image.GIF._encode

SYNTAX
string _encode(array data)

DESCRIPTION
Encodes GIF data; reverses _decode.

ARGUMENTS
argument(s)description
array data
data as returned from _encode

NOTE
Some given values in the array are ignored. This function does not give the _exact_ data back!

METHOD
Image.GIF._gce_block

SYNTAX
string _gce_block(int transparency, int transparency_index, int delay, int user_input, int disposal);

DESCRIPTION
This function gives back a Graphic Control Extension block. A GCE block has the scope of the following render block.

ARGUMENTS
argument(s)description
int transparency
int transparency_index
The following image has transparency, marked with this index.
int delay
View the following rendering for this many centiseconds (0..65535).
int user_input
Wait the delay or until user input. If delay is zero, wait indefinitely for user input. May sound the bell upon decoding.
int disposal
Disposal method number;
0
No disposal specified. The decoder is not required to take any action.
1
Do not dispose. The graphic is to be left in place.
2
Restore to background color. The area used by the graphic must be restored to the background color.
3
Restore to previous. The decoder is required to restore the area overwritten by the graphic with what was there prior to rendering the graphic.
4-7
To be defined.

NOTE
This is in the very advanced sector of the GIF support; please read about how GIF files works.

Most decoders just ignore some or all of these parameters.

SEE ALSO
_render_block and render_block

METHOD
Image.GIF._render_block

SYNTAX
string _render_block(int x, int y, int xsize, int ysize, int bpp, string indices, 0|string colortable, int interlace);

DESCRIPTION
Advanced (!) method for writing renderblocks for placement in a GIF file. This method only applies LZW encoding on the indices and makes the correct headers.

ARGUMENTS
argument(s)description
int x
int y
Position of this image.
int xsize
int ysize
Size of the image. Length if the indices string must be xsize*ysize.
int bpp
Bits per pixels in the indices. Valid range 1..8.
string indices
The image indices as an 8bit indices.
string colortable
Colortable with colors to write as palette. If this argument is zero, no local colortable is written. Colortable string len must be 1<<bpp.
int interlace
Interlace index data and set interlace bit. The given string should _not_ be pre-interlaced.

NOTE
This is in the very advanced sector of the GIF support; please read about how GIF files works.

SEE ALSO
encode, _encode, header_block and end_block

METHOD
Image.GIF.__decode

SYNTAX
array __decode();

DESCRIPTION
Decodes a GIF image structure down to chunks and 

({int xsize,int ysize,      // 0: size of image drawing area
int numcol,               // 2: suggested number of colors
void|string colortable,   // 3: opt. global colortable
({ int aspx, int aspy,    // 4,0: aspect ratio or 0, 0 if not set
int background }),     //   1: index of background color
followed by any number these blocks in any order: 
({ GIF.EXTENSION,         //   0: block identifier
int extension,         //   1: extension number
string data })         //   2: extension data


({ GIF.RENDER,            //   0: block identifier
int x, int y,          //   1: position of render
int xsize, int ysize,  //   3: size of render
int interlace,         //   5: interlace flag
void|string colortbl,  //   6: opt. local colortable
int lzwsize,           //   7: lzw code size
string lzwdata })      //   8: packed lzw data
and possibly ended with one of these: 
({ GIF.ERROR_PREMATURE_EOD })   // premature end-of-data


({ GIF.ERROR_TOO_MUCH_DATA,     // data following end marker
string data })               // (rest of file)


({ GIF.ERROR_UNKNOWN_DATA,      // unknown data
string data })               // (rest of file)

RETURNS
the above array

NOTE
May throw errors if the GIF header is incomplete or illegal.

This is in the very advanced sector of the GIF support; please read about how GIF files works.

Previous section To contents Next section