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¶
-
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.