To allow you to use the Framegrabber API in programs you create with Python, you are provided with a Python wrapper. The Python wrapper wraps the Framegrabber API functionality into a Python module.
All C/C++ Framgrabber API functions are wrapped in one Python module SiSoPyInterface.
The major part of the Pyton API works similar to the C/C++ API, so you can refer to the general C/C++ Framegrabber API documentation in most cases. All cases where the Python API differs from the C/C++ API are detailed in the following sections.
The Python wrapper is installed together with the Framegrabber SDK. You find the wrapper in the following subfolder of your Framgrabber SDK installation:
Basler offers wrapper versions that support Python versions 3.7, 3.8, 3.9 or 3.10 on Windows and Linux. You find the versions in the according subfolders python37, python38, python 39 and python310.
The Python Framegrabber API wrapper consists of 2 files, SiSoPyInterface.py and _SiSoPyRt_xx.pyd:
SiSoPyInterface.py is the wrapping module. You find this file in your Framegrabber SDK installation:
Before using the wrapper, download Python and install it if you don't already have it on your machine. Basler recommends to also install the NumPy package. Alternatively, you can directly use WinPython that already contains NumPy.
Install NumPy:
Pre-Requisite: Make sure Python is already installed on your host.
Download and install pip, the PyPA recommended tool for installing Python packages.
Import SiSoPyInterface.py in your Python project. The Framegrabber API can be accessed through the imported module.
Set the following environment variables before running your program as in the example below. Adapt the paths according to your installation. (In the example below, Python 3.9 has been installed to C:\Python\python39.)
To get started with the image acquisition using the wrapper most easily, you find two examples per Python version in your Framegrabber SDK installation:
Each function of the Framegrabber API has a corresponding function in the Python wrapper module (SiSoPyRt).
Since Python has no notion of output arguments, but can instead return multiple values, the C/C++ output arguments become additional return values in Python.
The mapping works as described in the following paragraphs.
C Function With Return Value and Output Arguments#
The return value of the C function (usually the error code) becomes the first return value of the Python function.
The output arguments of the C function become additional return values in the Python function. The first output argument of the original C function becomes the second return value in the Python function. The additional return values of the Python function (i.e., the former C output arguments) have in the Python function exactly the same order as the output arguments have in the original C function.
If the C function doesn't return a value, the output arguments of the C function become the return values of the Python function. The first output argument of the original C function becomes the first return value in the Python function. The return values of the Python function (i.e., the former C output arguments) have in the Python function exactly the same order as the output arguments have in the original C function.
Framegrabber API functions that create a reference to a struct and return an error code are modified such that they return both, the reference directly (or none if an error occurred), and the error code. For example, the function Fg_getAppletIterator is defined as:
The return values are the error code and the created reference.
Framegrabber API functions that modify their arguments are wrapped such that the modified values are returned together with the original return value. For example, the function Fg_getParameterInfoXML is defined as:
Framegrabber API functions that use some of their arguments as an out argument are wrapped such that those arguments aren't passed at all to the function, and only returned together with the original return value. For example, the function clGetNumSerialPorts is defined as:
Framegrabber API functions that require creating string buffer to be filled are wrapped such that the buffer is created internally and directly returned, with no need to create it from the Python code. For example, the function Fg_getSystemInformation is defined as:
Callback functions should be defined with the same number and types of arguments as defined in the C/C++ Framegrabber API call back functions. They can then be passed as an argument.
For example, the following code is used to register an APC handler (from AcqAPC.py example):
#Define FgApcControl instance to handle the callbackapcCtrl=s.FgApcControl(5,s.FG_APC_DEFAULTS)data=MyApcData(fg,camPort,memHandle,dispId0)s.setApcCallbackFunction(apcCtrl,apcCallback,data)#Register the FgApcControl instance to the Fg_Struct instanceerr=s.Fg_registerApcHandler(fg,camPort,apcCtrl,s.FG_APC_CONTROL_BASIC)
The function apcCallback must have the same signature as Fg_ApcFunc_t, an example implementation is:
# Callback function definitiondefapcCallback(imgNr,userData):s.DrawBuffer(userData.displayid,s.Fg_getImagePtrEx(userData.fg,imgNr,userData.port,userData.mem),imgNr,"")return0
The API of the wrapper is basically the same as that of the Framegrabber API. This section contains only the definitions of those functions that are renamed, or have a different order of arguments.
The functions provided here are grouped by library:
In the C API, image data is often held in a raw buffer (void, char). Since Python doesn't support raw memory access, those pointers are represented by an opaque handle. This opaque handle can be used in all places where the C API uses a void pointer to image data.
In this documentation, this opaque handle is referrred to as ImageDataHandle.
For detailed information about using a specific function, as well as for information regarding functions not listed here, refer to the Framegrabber API documentation.
List of overloaded functions that are used to get frame grabber parameters with information of different types. They replace the Framegrabber API function Fg_getParameterWithType, according to the passed type as follows:
List of overloaded functions that are used to set frame grabber parameters with information of different types. They replace the Framegrabber API function Fg_setParameterWithType, according to the passed type as following:
In the following function, the created handle is returned together with the error code from the function instead of being passed as an argument. If an error occurred, errorCode will have a value other than 0, and the return value will be None.
The following functions have changed with the Python wrapper in Framgrabber SDK release 5.6.1. The mentioned arguments expected a string value in earlier versions. Since Framgrabber SDK 5.6.1 (and higher), a bytearray value is required instead.
In the following functions, the result values are returned together with the error code from the function instead of being passed as arguments. If an error occurred, errorCode will have a value other than 0, and the return value will be None.
In DrawBuffer function, the ulpBuf argument type is changed from void pointer, which directly represents the image bytes, into an opaque handle, the ImageDataHandle.
(ImageDataHandle) = IoAllocateImageBuffer(width, height, bitsPerPixel Allocates a buffer for image data and returns a handle to that buffer. A manually allocated buffer must be freed using IoFreeImageBuffer.
IoFreeImageBuffer(ImageDataHandle) Frees a buffer that was allocated with IoAllocateImageBuffer.
In the following functions, the created handle is returned together with the error code from the function instead of being passed as an argument. If an error occurred, errorCode will have a value other than 0, and the return value will be None.
In the following functions, the return type is changed from void pointer, which directly represents the image bytes in the Framegrabber API, into an opaque handle (in the following referred to as ImageDataHandle).
To get again the bytearray from ImageDataHandle, the function SiSoPyInterface.getArrayFrom(image, width, height, intype, totype) (requires numpy) can be called (where the ImageDataHandle is passed as the image argument).