Skip to content

Python Wrapper#

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.

Components of the Wrapper#

The Python wrapper is installed together with the Framegrabber SDK. You find the wrapper in the following subfolder of your Framgrabber SDK installation:

Basler/FramegrabberSDK/SDKWrapper/PythonWrapper/pythonxx

Info

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:

    Basler/FramegrabberSDK/SDKWrapper/PythonWrapper/pythonxx/lib

  • _SiSoPyRt_xx.pyd is the dll that communicates with the Framegrabber API. You find this file in your Framegrabber SDK installation:

    Basler/FramegrabberSDK/bin

Installation#

To get started using the wrapper:

  1. 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.

  2. Install NumPy:

    1. Pre-Requisite: Make sure Python is already installed on your host.
    2. Download and install pip, the PyPA recommended tool for installing Python packages.
    3. Download the numpy package from https://pypi.org/.

    4. In the command line tool, enter:

      python -m pip install --user numpy

    For more details, see https://scipy.org/install.html or https://packaging.python.org/tutorials/installing-packages/

  3. Import SiSoPyInterface.py in your Python project. The Framegrabber API can be accessed through the imported module.

  4. 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.)
set PYTHON_ROOT=C:\Python\python39

set PATH=%PYTHON_ROOT%;%BASLER_FG_SDK_DIR%\bin;%BASLER_FG_SDK_DIR%\SDKWrapper\PythonWrapper\python39\bin;%BASLER_FG_SDK_DIR%\SDKWrapper\PythonWrapper\python39\lib;%PATH%

set PYTHONPATH=%PYTHON_ROOT%;%PYTHON_ROOT%\Lib;%BASLER_FG_SDK_DIR%\SDKWrapper\PythonWrapper\python39\bin;%BASLER_FG_SDK_DIR%\SDKWrapper\PythonWrapper\python39\lib;%BASLER_FG_SDK_DIR%\bin;%APPDATA%\Python\Python39\site-packages

Examples#

To get started with the image acquisition using the wrapper most easily, you find two examples per Python version in your Framegrabber SDK installation:

Basler/FramegrabberSDK/SDKWrapper/PythonWrapper/pythonXX/Examples

Function Mapping#

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.

C Function Without Return Value#

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.

Examples#

Example Type C Function Python Function
With return value and output arguments: int Fg_getAppletIterator(int boardIndex, const enum FgAppletIteratorSource src, Fg_AppletIteratorType * iter, int flags); iter, err = s.Fg_getAppletIterator(boardIndex, s.FG_AIS_FILESYSTEM, s.FG_AF_IS_LOADABLE)
Return value only: Fg_Struct *Fg_Init(const char *FileName, unsigned int BoardIndex); fg_struct = Fg_Init(fileName, boardIndex)

Special Cases#

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:

  • Framegrabber API definition:
int Fg_getAppletIterator(int boardIndex, const enum FgAppletIteratorSource src, Fg_AppletIteratorType * iter, int flags);

The return value is the result error code, and iter is the created reference.

  • Python Wrapper definition:
(iter , errorCode) = Fg_getAppletIterator (boardIndex, src, flags)

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 definition:
int Fg_getParameterInfoXML(Fg_Struct *Fg, int port, char * infoBuffer, size_t *infoBufferSize);
  • Python Wrapper definition:
(errorCode, infoBufferSize) = Fg_getParameterInfoXML(Fg_Struct, port, infoBuffer, infoBufferSize)

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 definition:
int clGetNumSerialPorts(unsigned int *numSerialPorts);
  • Python Wrapper definition:
(errorCode, numSerialPorts) = clGetNumSerialPorts()

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:

  • Framegrabber API definition:
int Fg_getSystemInformation(Fg_Struct *Fg, const enum Fg_Info_Selector selector, const enum FgProperty propertyId, int param1, void* buffer, unsigned int* bufLen);
  • Python Wrapper definition:
(errorCode, buffer, bufLen) = Fg_getSystemInformation(Fg_Struct, selector, propertyId, param1)

Callback Functions#

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 callback
apcCtrl = 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 instance
err = 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 definition
def apcCallback(imgNr, userData):
s.DrawBuffer(userData.displayid,
s.Fg_getImagePtrEx(userData.fg, imgNr,
userData.port, userData.mem), imgNr, "")
return 0

The declaration of Fg_ApcFunc_t looks as follows:

typedef int(* Fg_ApcFunc_t)(frameindex_t imgNr, struct fg_apc_data *data)

Python Wrapper API List#

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:

Info

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.

fg#

There are some functions available in the Python wrapper that aren't a 1:1 counterpart to the C/C++ API:

(description) = Fg_getErrorDescription (errorNumber)

This function replaces both of the following functions:

const char *const Fg_getErrorDescription (Fg_Struct *Fg, int ErrorNumber)

const char *const getErrorDescription (int ErrorNumber)

(error, Value) = Fg_getParameterWith… (Fg_Struct, ParameterNr, DmaIndex)#

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:

FgParamTypes Python Wrapper Function
FG_PARAM_TYPE_INT32_T Fg_getParameterWithInt
FG_PARAM_TYPE_UINT32_T Fg_getParameterWithUInt
FG_PARAM_TYPE_INT64_T Fg_getParameterWithLong
FG_PARAM_TYPE_UINT64_T Fg_getParameterWithULong
FG_PARAM_TYPE_DOUBLE Fg_getParameterWithDouble
FG_PARAM_TYPE_CHAR_PTR Fg_getParameterWithString
FG_PARAM_TYPE_SIZE_T Fg_getParameterWithUInt /
Fg_getParameterWithULong
FG_PARAM_TYPE_STRUCT_FIELDPARAMACCESS Fg_getParameterWithIntArray /
Fg_getParameterWithUIntArray /
Fg_getParameterWithLongArray /
Fg_getParameterWithULongArray
FG_PARAM_TYPE_STRUCT_FIELDPARAMINT Fg_getParameterWithFieldParameterInt
FG_PARAM_TYPE_STRUCT_FIELDPARAMDOUBLE Fg_getParameterWithFieldParameterDouble
FG_PARAM_TYPE_COMPLEX_DATATYPE Not implemented

(error) = Fg_setParameterWith…(Fg_Struct, ParameterNr, Value, DmaIndex)#

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:

FgParamTypes Python Wrapper Function
FG_PARAM_TYPE_INT32_T Fg_setParameterWithInt
FG_PARAM_TYPE_UINT32_T Fg_setParameterWithUInt
FG_PARAM_TYPE_INT64_T Fg_setParameterWithLong
FG_PARAM_TYPE_UINT64_T Fg_setParameterWithULong
FG_PARAM_TYPE_DOUBLE Fg_setParameterWithDouble /
Fg_setParameterWithFloat
FG_PARAM_TYPE_CHAR_PTR Fg_setParameterWithString
FG_PARAM_TYPE_SIZE_T Fg_setParameterWithUInt /
Fg_setParameterWithULong
FG_PARAM_TYPE_STRUCT_FIELDPARAMACCESS Fg_setParameterWithIntArray /
Fg_setParameterWithUIntArray /
Fg_setParameterWithLongArray /
Fg_setParameterWithULongArray
FG_PARAM_TYPE_STRUCT_FIELDPARAMACCESS Fg_setParameterWithFieldParameterInt
FG_PARAM_TYPE_STRUCT_FIELDPARAMDOUBLE Fg_setParameterWithFieldParameterDouble
FG_PARAM_TYPE_COMPLEX_DATATYPE Not implemented

clser#

Functions with Reordered Arguments#

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.

Python Framegrabber API Wrapper Framegrabber API
(errorCode, CLSerialRef) = clSerialInit(serialIndex) int clSerialInit(unsigned int serialIndex, void *serialRefPtr)

Functions with Changed Data Types in Arguments#

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.

clSerialRead, argument buffer

clGetManufacturerInfo, argument manufacturerName

clGetSerialPortIdentifier, argument portID

clGetErrorText, argument errorText

siso_genicam#

Functions with Reordered Arguments#

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.

Python Framgrabber API Wrapper Framegrabber API
(errorCode, SgcBoardHandle) = Sgc_initBoard(Fg_Struct, initFlag) int Sgc_initBoard(Fg_Struct* fg, int initFlag, SgcBoardHandle* boardHandle)
(errorCode, SgcBoardHandle) =Sgc_initBoardEx(Fg_Struct, initFlag, portMask, slaveMode) int Sgc_initBoardEx(Fg_Struct* fg, unsigned int initFlag, SgcBoardHandle* boardHandle, unsigned int portMask, unsigned int slaveMode)
(errorCode, SgcCameraHandle) = Sgc_getCamera(boardHandle, port) int Sgc_getCamera(SgcBoardHandle* boardHandle, const unsigned int port, SgcCameraHandle* cameraHandle)
(errorCode, SgcCameraHandle) = Sgc_getCameraByIndex(boardHandle, index) int Sgc_getCameraByIndex(SgcBoardHandle* boardHandle, const unsigned int index, SgcCameraHandle* cameraHandle)
(errorCode, SgcConnectionProfile) = Sgc_LoadConnectionProfile(Fg_Struct, boardConfigurationFilePath) int Sgc_LoadConnectionProfile(Fg_Struct* fg, const char* boardConfigurationFilePath, SgcConnectionProfile* connectionProfilePtr)
(errorCode, stringValue) = Sgc_getStringValue(cameraHandle, name) int Sgc_getStringValue(SgcCameraHandle* cameraHandle, const char* name, const char* stringValuePtr)
(errorCode, stringValue) = Sgc_getEnumerationValueAsString(cameraHandle, name) int Sgc_getEnumerationValueAsString(SgcCameraHandle* cameraHandle, const char* name, const char* stringValuePtr)

SisoDisplay#

Python Framegrabber API Wrapper Framegrabber API
DrawBuffer(nId, ulpBuf, nNr, cpStr) void DrawBuffer(int nId, const void *ulpBuf, const int nNr, const char *cpStr)

In DrawBuffer function, the ulpBuf argument type is changed from void pointer, which directly represents the image bytes, into an opaque handle, the ImageDataHandle.

SisoIo.h#

Wrapper-Specific Functions#

The following functions serve as substitutes (workarounds) for C/C++ features that aren't available in Python (i.e., raw memory allocation).

Python Framegrabber API Wrapper
(TiffHandle, ImageDataHandle (resp. SisoImage), width, height, bitsPerSample, samplesPerPixel) = IoReadTiff(filename)
(TiffHandle, ImageDataHandle (resp. SisoImage), width, height, bitsPerSample, samplesPerPixel) = IoReadTiffW(filename)
(TiffHandle, ImageDataHandle (resp. SisoImage), width, height, bitsPerSample, samplesPerPixel) = IoReadTiffEx(filename, RGBSequence)
(TiffHandle, ImageDataHandle (resp. SisoImage), width, height, bitsPerSample, samplesPerPixel) = IoReadTiffExW(filename, RGBSequence)
(BMPHandle, ImageDataHandle, width, height, bits) = IoReadBmp(filename)
(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.

Functions with Reordered Arguments#

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.

Python Framegrabber API Wrapper Framegrabber API
(errorCode, AviRef) = IoCreateAVIGray(filename, width, height, fps) int IoCreateAVIGray(void *AviRef, const char *filename, int width, int height, double fps)
(errorCode, AviRef) = IoCreateAVIGrayW(filename, width, height, fps) int IoCreateAVIGrayW(void *AviRef, const LPCWSTR filename, int width, int height, double fps)
(errorCode, AviRef) = IoCreateAVIColor(filename, width, height, fps) int IoCreateAVIColor(void *AviRef, const char *filename, int width, int height, double fps)
(errorCode, AviRef) = IoCreateAVIColorW(filename, width, height, fps) int IoCreateAVIColorW(void *AviRef, const LPCWSTR filename, int width, int height, double fps)
(errorCode, AviRef, width, height, bitDepth) = IoOpenAVI(fileName) int IoOpenAVI(void *AviRef, const char *fileName, int *width, int *height, int *bitDepth)
(errorCode, SeqRef) = IoCreateSeq(string pFilename, width, height, bitdepth, format) int IoCreateSeq(void *SeqRef, const char *pFilename, int width, int height, int bitdepth, int format)
(errorCode, SeqRef, width, height, bitDepth) = IoOpenSeq(pFilename, mode) int IoOpenSeq(void *SeqRef, const char *pFilename, int* width, int* height, int* bitdepth, int mode)
(errorCode, SisoIoImageEngine) = IoImageOpen(filename) int IoImageOpen(const char *filename, SisoIoImageEngine *handle)
(errorCode, SisoIoImageEngine) = IoImageOpenEx(filename, RGBSequence) int IoImageOpenEx(const char *filename, SisoIoImageEngine *handle, int RGBSequence)

Functions with Different Return Data Types#

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).

Python Framegrabber API Wrapper Framegrabber API
(TiffHandle, ImageDataHandle, width, height, bitPerSample, samplePerPixel) = IoReadTiff(filename) void *IoReadTiff(const char *filename, unsigned char*data, int *width, int *height, int *bitPerSample, int *samplePerPixel)
(TiffHandle, ImageDataHandle, width, height, bitPerSample, samplePerPixel) = IoReadTiffW(filename) void *IoReadTiffW(const LPCWSTR filename, unsigned char*data, int *width, int *height, int *bitPerSample, int *samplePerPixel)
(TiffHandle, ImageDataHandle, width, height, bitPerSample, samplePerPixel) = IoReadTiffEx(filename, RGBSequence) void *IoReadTiffEx(const char *filename, unsigned char*data, int *width, int *height, int *bitPerSample, int *samplePerPixel, int RGBSequence)
(TiffHandle, ImageDataHandle, width, height, bitPerSample, samplePerPixel) = IoReadTiffExW(filename, RGBSequence) void *IoReadTiffExW(const LPCWSTR filename, unsigned char*data, int *width, int *height, int *bitPerSample, int *samplePerPixel, int RGBSequence)
(TiffHandle, ImageDataHandle, width, height, bits) = IoReadBmp(filename) void *IoReadBmp(const char *filename,unsigned char *data,int *width,int *height,int *bits)