images2gif module

Module images2gif

Provides functionality for reading and writing animated GIF images. Use writeGif to write a series of numpy arrays or PIL images as an animated GIF. Use readGif to read an animated gif as a series of numpy arrays.

Note that since July 2004, all patents on the LZW compression patent have expired. Therefore the GIF format may now be used freely.

Acknowledgements

Many thanks to Ant1 for: * noting the use of “palette=PIL.Image.ADAPTIVE”, which significantly

improves the results.

• the modifications to save each image with its own palette, or optionally the global palette (if its the same).

Many thanks to Marius van Voorden for porting the NeuQuant quantization algorithm of Anthony Dekker to Python (See the NeuQuant class for its license).

Many thanks to Alex Robinson for implementing the concept of subrectangles, which (depening on image content) can give a very significant reduction in file size.

This code is based on gifmaker (in the scripts folder of the source distribution of PIL)

Usefull links

• http://tronche.com/computer-graphics/gif/
• http://en.wikipedia.org/wiki/Graphics_Interchange_Format
• http://www.w3.org/Graphics/GIF/spec-gif89a.txt

class images2gif.GifWriter

Class that contains methods for helping write the animated GIF file.

convertImagesToPIL(images, nq=0)

Convert images to Paletted PIL images, which can then be written to a single animaged GIF.

getAppExt(loops=float('inf'))

Application extention. This part specifies the amount of loops. If loops is 0 or inf, it goes on infinitely.

getGraphicsControlExt(duration=0.1, dispose=2)

Graphics Control Extension. A sort of header at the start of each image. Specifies duration and transparancy.

• 0 - No disposal specified.
• 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.

getImageDescriptor(im, xy=None)

Used for the local color table properties per image. Otherwise global color table applies to all frames irrespective of whether additional colors comes in play that require a redefined palette. Still a maximum of 256 color per frame, obviously.

Written by Ant1 on 2010-08-22 Modified by Alex Robinson in Janurari 2011 to implement subrectangles.

getSubRectangles(ims)

Calculate the minimal rectangles that need updating each frame. Returns a two-element tuple containing the cropped images and a list of x-y positions.

Calculating the subrectangles takes extra time, obviously. However, if the image sizes were reduced, the actual writing of the GIF goes faster. In some cases applying this method produces a GIF faster.

getheaderAnim(im)

Get animation header. To replace PILs getheader()[0]

handleSubRectangles(images)

Handle the sub-rectangle stuff. If the rectangles are given by the user, the values are checked. Otherwise the subrectangles are calculated automatically.

writeGifToFile(fp, images, durations, loops, xys, disposes)

Given a set of images writes the bytes to the specified stream.

class images2gif.NeuQuant(image, samplefac=10, colors=256)

samplefac should be an integer number of 1 or higher, 1 being the highest quality, but the slowest performance. With avalue of 10, one tenth of all pixels are used during training. This value seems a nice tradeof between speed and quality.

colors is the amount of colors to reduce the image to. This should best be a power of two.

See also: http://members.ozemail.com.au/~dekker/NEUQUANT.HTML

Copyright (c) 1994 Anthony Dekker Ported to python by Marius van Voorden in 2010

NEUQUANT Neural-Net quantization algorithm by Anthony Dekker, 1994. See “Kohonen neural networks for optimal colour quantization” in “network: Computation in Neural Systems” Vol. 5 (1994) pp 351-367. for a discussion of the algorithm. See also http://members.ozemail.com.au/~dekker/NEUQUANT.HTML

Any party obtaining a copy of these files from the author, directly or indirectly, is granted, free of charge, a full and unrestricted irrevocable, world-wide, paid up, royalty-free, nonexclusive right and license to deal in this software and documentation files (the “Software”), including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons who receive copies from any such party to do so, with the only requirement being that this copyright notice remain intact.

ALPHABIASSHIFT = None

BETA = None

BETAGAMMA = None

BGCOLOR = None

CUTNETSIZE = None

GAMMA = None

INITALPHA = None

INITBIASRADIUS = None

INITRAD = None

MAXNETPOS = None

MAXPRIME = 503

NCYCLES = None

NETSIZE = None

PRIME1 = 499

PRIME2 = 491

PRIME3 = 487

PRIME4 = 503

RADIUSBIAS = None

RADIUSBIASSHIFT = None

RADIUSDEC = None

SPECIALS = None

a_s = None

alterneigh(alpha, rad, i, b, g, r)

altersingle(alpha, i, b, g, r)

Move neuron i towards biased (b,g,r) by factor alpha

bias = None

colormap = None

contest(b, g, r)

Search for biased BGR values Finds closest neuron (min dist) and updates self.freq finds best neuron (min dist-self.bias) and returns position for frequently chosen neurons, self.freq[i] is high and self.bias[i] is negative self.bias[i] = self.GAMMA*((1/self.NETSIZE)-self.freq[i])

convert(*color)

fix()

freq = None

geta(alpha, rad)

inxbuild()

inxsearch(r, g, b)

Search for BGR values 0..255 and return colour index

learn()

netindex = None

network = None

paletteImage()

PIL weird interface for making a paletted image: create an image which already has the palette, and use that in Image.quantize. This function returns this palette image.

pimage = None

pixels = None

quantize(image)

Use a kdtree to quickly find the closest palette colors for the pixels

quantize_with_scipy(image)

quantize_without_scipy(image)

” This function can be used if no scipy is availabe. It’s 7 times slower though.

samplefac = None

setUpArrays()

setconstants(samplefac, colors)

specialFind(b, g, r)

writeColourMap(rgb, outstream)

images2gif.checkImages(images)

Check numpy images and correct intensity range etc. The same for all movie formats.

images2gif.encode(x)

images2gif.get_cKDTree()

images2gif.intToBin(i)

Integer to two bytes

images2gif.readGif(filename, asNumpy=True)

Read images from an animated GIF file. Returns a list of numpy arrays, or, if asNumpy is false, a list if PIL images.

images2gif.writeGif(filename, images, duration=0.1, repeat=True, dither=False, nq=0, subRectangles=True, dispose=None)

writeGif(filename, images, duration=0.1, repeat=True, dither=False,

nq=0, subRectangles=True, dispose=None)

Write an animated gif from the specified images.

filename : string

The name of the file to write the image to.

images : list

Should be a list consisting of PIL images or numpy arrays. The latter should be between 0 and 255 for integer types, and between 0 and 1 for float types.

duration : scalar or list of scalars

The duration for all frames, or (if a list) for each frame.

repeat : bool or integer

The amount of loops. If True, loops infinitetely.

dither : bool

Whether to apply dithering

nq : integer

If nonzero, applies the NeuQuant quantization algorithm to create the color palette. This algorithm is superior, but slower than the standard PIL algorithm. The value of nq is the quality parameter. 1 represents the best quality. 10 is in general a good tradeoff between quality and speed. When using this option, better results are usually obtained when subRectangles is False.

subRectangles : False, True, or a list of 2-element tuples

Whether to use sub-rectangles. If True, the minimal rectangle that is required to update each frame is automatically detected. This can give significant reductions in file size, particularly if only a part of the image changes. One can also give a list of x-y coordinates if you want to do the cropping yourself. The default is True.

dispose : int

How to dispose each frame. 1 means that each frame is to be left in place. 2 means the background color should be restored after each frame. 3 means the decoder should restore the previous frame. If subRectangles==False, the default is 2, otherwise it is 1.