Python wrapper for Pixman pixel-manipulation library
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
README
pixman.py
setup.py

README

**python_pixman** is a (partial) Python language binding for the
[Pixman](http://pixman.org/) pixel-manipulation library, for use with
Python 3.2 or later. Pixman is useful for applying low-level pixel
effects, like convolution filters.

Installation is explained in the `setup.py` script. This module also
requires Qahirah ([GitLab](https://gitlab.com/ldo/qahirah),
[GitHub](https://github.com/ldo/qahirah)), my Cairo graphics wrapper,
to be installed.

Unfortunately, there is no proper documentation for Pixman itself. I
have tried to make up for this by adding docstrings and other comments
in this Python wrapper. Thus, you can get some idea of the facilities
available from the Python interactive prompt:

    >>> import pixman
    >>> help(pixman)

The core is the `Image` object. This can not only hold an array of
pixels (a “bits image”), but Pixman also supports special `Image` types
which consist of indefinite extents of solid colours or colour
gradients. Of course, these non-bits image types can only be used as
sources for drawing operations, not destinations.

For convenience, the `Image` object provides a `create_cairo_surface`
method that returns a Cairo `ImageSurface` wrapping the same pixels as
the `Image`. Of course, this only works for bits images. Conversely,
there is also a `create_from_cairo_surface` method that takes a Cairo
`ImageSurface` and returns a Pixman bits `Image` wrapping the same
pixels.

These two interconversions allow you to mix Cairo drawing operations
with Pixman pixel manipulations, provided you follow the rules
explained in the Cairo documentation about using `flush()` and
`mark_dirty()`.

Another important object is the `Filter`. Whereas the underlying C
call looks like

    pixman_image_set_filter(image, filter_type, params, nr_params);

the Python version encapsulates all the filter settings into a single
object:

    image.set_filter(filter)

The filter types that take no parameters are represented by predefined
`Filter` objects: `FAST`, `GOOD`, `BEST`, `NEAREST` and `BILINEAR`.
Thus, whereas in C you would write

    pixman_image_set_filter(image, PIXMAN_FILTER_BEST, NULL, 0);

in Python this would become

    image.set_filter(pixman.Filter.BEST)

The `Filter` class provides methods for constructing filter types that
take parameters. What Pixman calls a “separable convolution”, I just
call a “resampler”, because that seems to be its purpose: to resample
an image in various high-quality ways when scaling.

Examples of python_pixman in action are available in the
python_pixman_examples
([GitLab](https://gitlab.com/ldo/python_pixman_examples),
[GitHub](https://github.com/ldo/python_pixman_examples))
repository.

Lawrence D'Oliveiro <ldo@geek-central.gen.nz>
2017 April 9