VIGRA Python Bindings

When you configure VIGRA with the option -DWITH_VIGRANUMPY=1 while running cmake, a Python module vigra will be compiled and installed. It exposes most of VIGRA's functionality for easy scripting and prototyping in Python. Most importantly, VIGRA's Python bindings are fully integrated with the popular 'numpy' package so that you can call vigra functions directly with numpy ndarrays. No explicit or implicit conversion of data formats is required.

The syntax of the Python version is usually very similar to the C++ syntax, with one important difference: You do not have to pass pre-allocated result images to the functions. That is, while in C++ you write

MultiArray<2, float> inputImage(Shape2(width, height)), 
                     resultImage(inputImage.shape());  // pre-allocate result with correct shape
... // fill inputImage

// smooth image with Gaussian filter with sigma=1.5
// (pre-allocated resultImage must be passed to the function)
gaussianSmoothing(inputImage, resultImage, 1.5);

the corresponding Python call is

>>> import numpy, vigra

>>> inputImage = numpy.zeros((width, height), dtype=numpy.float32)
...  # fill inputImage

# smooth image with Gaussian filter with sigma=1.5
# (resultImage is automatically allocated and returned) 
>>> resultImage = vigra.filters.gaussianSmoothing(inputImage, 1.5);

However, it is still possible to pass a result array of appropriate shape explicitly by means of the out parameter:

>>> resultImage = numpy.zeros(inputImage.shape, dtype=numpy.float32)
>>> vigra.filters.gaussianSmoothing(inputImage, 1.5, out=resultImage)

If the C++ function provides options, they are exposed on the Python side as keyword arguments:

>>> labeling, max_label = vigra.analysis.watersheds(inputImage, seeds=seedImage, method='UnionFind')

In general, the correspondence between a Python function and its C++ counterpart is straightforward, and the Python documentation frequently refers to the C++ documentation for details. However, there is an important caveat: the default axis interpretation is different in VIGRA's MultiArray (which uses 'Fortran order') and in numpy's ndarray (which uses 'C-order). To help you deal with this difficulty, vigranumpy provides a subclass VigraArray of ndarray and the concept of axistags.

The full Python documentation is available via HTML or can be obtained directly from the Python prompt by the help() command:

>>> help(vigra.filters.gaussianSmoothing)

An important