==============
qimage2ndarray
==============
qimage2ndarray is a small python extension for quickly converting
between QImages_ and numpy.ndarrays_ (in both directions). These are
very common tasks when programming e.g. scientific visualizations in
Python using PyQt4_ as the GUI library.
Similar code was found in Qwt and floating around on mailing lists,
but qimage2ndarray has the following unique feature set:
* Supports conversion of scalar and RGB data, with arbitrary dtypes
and memory layout, with and without alpha channels, into QImages
(e.g. for display or saving using Qt).
* Using a tiny C++ extension, qimage2ndarray makes it possible to
create ndarrays_ that are *views* into a given QImage_'s memory.
This allows for very efficient data handling and makes it possible
to modify Qt image data in-place (e.g. for brightness/gamma or alpha
mask modifications).
* qimage2ndarray is stable and unit-tested:
* proper reference counting even with views (ndarray.base_ points to
the underlying QImage_)
* handles non-standard widths and respects QImage's 32-bit row
alignment
* `Masked arrays`_ are also supported and are converted into QImages
with transparent pixels.
* Supports recarrays_ (and comes with an appropriate dtype) for
convenient access to RGB(A) channels.
* Supports value scaling / normalization to 0..255 for convenient
display of arbitrary NumPy arrays.
.. _masked arrays: http://docs.scipy.org/doc/numpy/reference/maskedarray.generic.html
.. _recarrays: http://docs.scipy.org/doc/numpy/reference/generated/numpy.recarray.html
Documentation
=============
API documentation can be found `in the doc/ subdirectory
`_.
Code
====
The extension is open source, BSD-licensed__, and the mercurial
repository can be `browsed online`_ or cloned using Mercurial_::
hg clone http://www.informatik.uni-hamburg.de/~meine/hg/qimage2ndarray/
__ http://www.opensource.org/licenses/bsd-license.php
Installation
------------
The current release (version 1.0) is available for download below or `via
PyPI `_, i.e. you might
just issue::
easy_install qimage2ndarray
to compile and install the extension.
Hint: If you want to specify another compiler, e.g. in order to use
MinGW instead of the Microsoft compiler on Windows, you can do it like
this::
python setup.py build -c mingw32 install
Latest Stable Release
---------------------
.. download:: software/qimage2ndarray/dist/qimage2ndarray-1.0*
Changelog
---------
Version 1.0:
- Let array2qimage support 2 channels (gray + alpha)
- Fixed installation on OS X (where Qt libs come as "Frameworks")
Version 0.2:
- Fixed endianness issues (tested on PowerPC arch)
- Simplified installation on Windows (e.g. with Qt DLLs bundled with PyQt)
Version 0.1:
- Initial Relase
.. _browsed online: http://www.informatik.uni-hamburg.de/~meine/hg/qimage2ndarray/
.. _Mercurial: http://mercurial.selenic.com/wiki/
.. _PyQt4: http://www.riverbankcomputing.co.uk/software/pyqt/
.. _QImage: http://doc.trolltech.com/qimage.html
.. _QImages: http://doc.trolltech.com/qimage.html
.. _numpy.ndarray: http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html
.. _numpy.ndarrays: http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html
.. _ndarray: http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html
.. _ndarrays: http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html
.. _ndarray.base: http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.base.html