kaa.imlib2 provides thread-safe Python bindings for Imlib2, a featureful and efficient image processing library, which produces high quality, anti-aliased output.
Although kaa.imlib2 does not yet provide complete coverage of the Imlib2 library, most common functions are implemented. It also implements some custom functionality not found in Imlib2, such as Image.draw_mask.
In addition to Imlib2 itself, kaa.imlib2, as with all kaa modules, requires kaa.base.
The easiest and recommended way to install kaa.imlib2 is using pip (available as the python-pip package in Ubuntu and Fedora):
sudo pip install --upgrade kaa-imlib2
Or, if you prefer to install kaa.imlib2 as an egg using setuptools (package python-setuptools on Ubuntu and Fedora):
sudo easy_install -U kaa-imlib2
The most up-to-date tree can be cloned with git:
git clone git://github.com/freevo/kaa-imlib2.git
cd kaa-imlib2
sudo python setup.py install
The project is hosted at GitHub, so if you’d like to contribute, you can can fork it and send pull requests.
Your distribution might already have kaa.imlib2 included in its standard repositories, but be aware that these are almost certainly very out of date:
# For Ubuntu and Debian
sudo apt-get install python-kaa-imlib2
# For Fedora
yum install python-kaa-imlib2
Finally, source packages are available on GitHub.
Here are some examples to give you a feeling for basic usage.
First, import the module:
>>> from kaa import imlib2
Imlib2 supports most common image formats (jpeg, png, gif, tiff, bmp, etc.), and can be loaded with imlib2.open(), which returns an Image object:
>>> img = imlib2.open('file.png')
>>> img
<kaa.imlib2.Image object size=1920x1080 at 0xb74c470c>
By default, decoded images are cached internally so that subsequent loads pull from the cache. If for some reason you want to bypass the cache, you can use imlib2.open_without_cache():
>>> img = imlib2.open_without_cache('file.png')
Or, you can disable caching altogether:
>>> imlib2.set_cache_size(0)
>>> imlib2.get_cache_size()
0L
There are a number of useful properties:
>>> img.filename, img.format, img.width, img.height
('file.png', 'png', 1920, 1080)
Rasterizing SVG into Image objects is supported (provided libsvg support is compiled into kaa.imlib2). You can render the SVG at the native resolution (if one is stored in the SVG) or at a custom resolution:
>>> img = imlib2.open('file.svg', (1920, 1080))
If you have an image file in memory, you can decode directly from the buffer using imlib2.open_from_memory().
Lastly, you can create a new() image, optionally with a pixel buffer (in some RGB colorspace, e.g. BGRA, RGB, ARGB, etc.):
>>> img = imlib2.new((1920, 1080))
Many manipulations to Image objects are possible. Some return new objects, while others return self (to allow for convenient chaining of manipulations); you’ll need to consult the method documentation to see what the return value is.
>>> img.draw_rectangle((10, 10), (-10, -10), '#ff0000aa')
<kaa.imlib2.Image object size=1920x1080 at 0x8571c0c>
Notice that sizes can be negative (and zero), in which case they produce a width or height relative to the far edge of the image. Negative positions are also relative to the edge. Also notice that colors can be specified as the familiar hex color code used in HTML. 3- or 4-tuples of RGB[A] values are also supported.
You can overlay other images using the flexible blend() method, which lets you scale, crop, and composite simultaneously:
>>> watermark = imlib2.open('watermark.png')
>>> img.blend(watermark, dst_pos=(-watermark.width, -watermark.height), alpha=180)
Imlib2 can render text from TrueType fonts. You first need to tell Imlib2 where to find fonts, but kaa.imlib2 offers a convenience function to initialize the font path from what Fontconfig knows:
>>> imlib2.auto_set_font_path()
Then you reference the font names based on the (case-sensitive) filename of the .ttf file. Assuming you had VeraBd in your font path:
>>> img.draw_text((50, 50), 'Hello world!', '#ffffff', 'VeraBd/60')
(546, 92, 546, 93)
The return value shows the metrics of the rendered text. imlib2.Image.draw_text() has many options to render text. It also supports text styles such as drop shadows and outlines. Rather than specifying the font name, size, style, color, etc. each time, you can instead create a Font object and assign it to the image’s font property:
>>> img.font = imlib2.Font('VeraBd/60', '#ffffff')
>>> img.font.set_style(imlib2.TEXT_STYLE_SOFT_SHADOW, shadow='#558855')
>>> img.draw_text((50, 200), 'Uses the default style')
(989, 92, 989, 93)
>>> img.draw_text((50, 400), 'But you can still override', color='#ff000055',
... shadow='#00ff00aa')
(1134, 92, 1134, 93)
One benefit of using Font objects is access to the method get_text_size(), to precompute the metrics of the text as it would be rendered. This is useful if, for example, you want to center text, or otherwise position it where you’d need to know the rendered size beforehand.
>>> img.font.size = 90
>>> w, h = img.font.get_text_size('Centered')[:2]
>>> img.draw_text(((img.width - w) / 2, (img.height - h) / 2), 'Centered')
(618, 139, 618, 139)
The above is just a small sample of what can be done with kaa.imlib2. Refer to the library documentation for full details and more examples.