Using pi2 from Python

Pi2 can be used from Python scripts and from iPython console. In order to initialize Pi2, the package pi2py must be imported and a Pi2 object created:

import sys
sys.path.append("path/to/pi2/folder")

from pi2py2 import *
pi = Pi2()

Note The 'path/to/pi2/folder' should point to the folder of the compiled binary distribution of pi2, not to the source code repository. Typically, the correct folder will be pi2/bin-linux64/release-nocl or something similar, where the first folder is the root of the source code repository.

Note Windows users should beware that Python uses the standard directory separator backslash -character as escape character. This means you need to specify the path either using forward slashes “/” ("path/to/folder"), double -characters ("path\\to\\folder"), or a raw string (r"path\to\folder").

If the pi2py2.py file is in the current working directory, then the sys.path.append command does not need to be run. Pi2py is written for Python versions >= 3.6.

After initialization, all the functionality of Pi2 can be accessed through the Pi2 object:

img = pi.newimage(ImageDataType.UINT8, 100, 100, 100)
pi.noise(img, 100, 25)
pi.writetif(img, './noise')

For reference on the available functionality, use either iPython help or the Command reference page. Note that there are some small differences between arguments specified in the Command reference and what pi2py2 expects. The largest difference is that instead of image name, you can pass object returned by the newimage command.

There are many Python examples available here: https://github.com/arttumiettinen/pi2/blob/master/python_scripts/pi2py2_examples.py Most of them are documented in the Examples page.

The Python bindings in the pi2py2.py file are (mostly) self-generating so they are always (mostly) up-to-date.

Pi2 and NumPy

NumPy arrays can be used together with Pi2 in a few ways.

1. NumPy arrays can be passed to Pi2 functions as input images. Outputting to NumPy arrays is not supported at the moment. Additionally, 3-element NumPy arrays can be used in all occasions where a 3-element vector is required.

2. Image data can be retrieved as a Numpy array using Pi2Image.to_numpy() function. The function returns the data in the image as NumPy array of appropriate shape and data type. The NumPy array is a copy of the original image data so changes made to it are not reflected in the Pi2 system.

Retrieving image data as a NumPy array causes it to be read into RAM in its entirety. This might not be desirable in distributed computing mode, if the image is large.

3. NumPy array can be copied into a Pi2 image using Pi2Image.from_numpy(array) function. The data of the array is copied from NumPy into the Pi2 system, so changes made by Pi2 are not reflected in the NumPy array.

For ‘power users’ there is also a method Pi2Image.to_numpy_pointer() that returns reference to the image data in the Pi2 system as a NumPy array. Changes made to the array are reflected in the Pi2 system and vice versa. However, please note that Pi2 commands that change the size of the image will re-allocate the memory reserved for the image and this process invalidates any NumPy arrays returned by the to_numpy_pointer() method. Accessing invalidated array might result in program crash. Arrays returned by the to_numpy() method are not affected by this problem.

If Pi2 is in distributed computing mode, calling Pi2Image.to_numpy_pointer() will cause the image to be read into RAM in its entirety. In this mode, changes made to the NumPy array are not reflected to the image until Pi2Image.flush_pointer() method is called.