kaa.imlib2 --- Image Processing Library ======================================= What is kaa.imlib2? ------------------- 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 :meth:`Image.draw_mask `. In addition to Imlib2 itself, kaa.imlib2, as with all kaa modules, requires `kaa.base `_. Where do I get kaa.imlib2? -------------------------- The easiest and recommended way to install kaa.imlib2 is using *pip* (available as the ``python-pip`` package in Ubuntu and Fedora): .. code-block:: bash 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): .. code-block:: bash sudo easy_install -U kaa-imlib2 The most up-to-date tree can be cloned with git: .. code-block:: bash 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: .. code-block:: bash # 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 `_. API Documentation ================= .. toctree:: :maxdepth: 2 image font How do I use kaa.imlib2? ------------------------ 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 :func:`imlib2.open`, which returns an :class:`~imlib2.Image` object: >>> img = imlib2.open('file.png') >>> img 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 :func:`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 :class:`~imlib2.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 :func:`imlib2.open_from_memory`. Lastly, you can create a :func:`~imlib2.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 :class:`~imlib2.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') 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 :meth:`~imlib2.Image.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. :meth:`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 :class:`~imlib2.Font` object and assign it to the image's :attr:`~imlib2.Image.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 :func:`~imlib2.Font.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.