Python Wrapper Silicon Software Runtime

Python Wrapper
Silicon Software Runtime
V 5.5.0
Documentation
Imprint
Silicon Software GmbH
Steubenstraße 46
68163 Mannheim, Germany
Tel.: +49 (0) 621 789507 0
Fax: +49 (0) 621 789507 10
© 2017 Silicon Software GmbH. All rights reserved.
Document Version: 1.0
Document Language: en (US)
Last Change: March 2017
SiliconSoftware
2
Python SDK Wrapper
Contents
1
2
3
Introduction ............................................................................................................................ 5
1.1
Overview .......................................................................................................................... 5
1.2
Getting Started ................................................................................................................. 5
1.3
Supported Python Versions............................................................................................... 5
SDK Wrapping ......................................................................................................................... 6
2.1
Function Mapping ............................................................................................................. 6
2.2
Call back ........................................................................................................................... 7
Python Wrapper API List.......................................................................................................... 8
3.1
fgrab ................................................................................................................................. 8
3.1.1 New defined functions ................................................................................................. 8
3.1.1.1
(description) = Fg_getErrorDescription (errorNumber) .......................................... 8
3.1.1.2
(error, Value) = Fg_getParameterWith… (Fg_Struct, ParameterNr, DmaIndex) ...... 8
3.1.1.3
(error) = Fg_setParameterWith…(Fg_Struct, ParameterNr, Value, DmaIndex) ....... 9
3.1.2 Functions with different arguments ........................................................................... 10
3.2
gbe.................................................................................................................................. 10
3.2.1 Functions with reordered arguments ......................................................................... 10
3.3
clser ................................................................................................................................ 11
3.3.1 Functions with reordered arguments ......................................................................... 11
3.4
siso_auxport ................................................................................................................... 12
3.4.1 Functions with reordered arguments ......................................................................... 12
3.4.2 New defined functions ............................................................................................... 12
3.5
3.4.2.1
(error, value) = SisoAuxPortGetPropertyWith…( handle, property, size) .............. 12
3.4.2.2
(error) = SisoAuxPortSetPropertyWith…( handle, property, value, size) ............... 12
siso_genicam .................................................................................................................. 13
3.5.1 Functions with reordered arguments ......................................................................... 13
SiliconSoftware
3
Python SDK Wrapper
3.6
SisoDisplay ...................................................................................................................... 14
3.6.1 Functions with different arguments ........................................................................... 14
3.7
SisoIo.h ........................................................................................................................... 14
3.7.1 Functions with reordered arguments ......................................................................... 14
3.7.2 Functions with different return data types................................................................. 16
SiliconSoftware
4
Python SDK Wrapper
1 Introduction
1.1 Overview
Python Wrapper wraps the Software Development Kit (SDK) functionality into a Python module.
It is created such that all C SDK functions are wrapped in one Python module SiSoPyInterface.
The main usage and function declaration is defined mostly as described in the SDK documentation,
the differences are detailed in this document.
1.2 Getting Started
Before using the wrapper, you may need to download Python and install it if you do not already
have it on your machine. NumPy package is also required for using the wrapper. WinPython,
containing already NumPy, can be used directly instead.
The Python SDK Wrapper consists of 2 files; SiSoPyInterface.py and _SiSoPyRt.pyd.
SiSoPyInterface.py is the wrapping module. _SiSoPyRt.pyd is the dll that communicates with the
SDK.
To get started using the wrapper:
 Import SiSoPyInterface.py in your Python project. The SDK can be accessed through
the imported module.
 Make sure that _SiSoPyRt.pyd is in your path directory before running your
program.
Some python examples are provided to easily get started with the image acquisition using the
wrapper.
1.3 Supported Python Versions
Different Wrapper versions are available to support Python versions 2.7, 3.5, 3.6 on Windows.
Both 32-bit and 64-bit compilations of Python are supported.
SiliconSoftware
5
Python SDK Wrapper
2 SDK Wrapping
2.1 Function Mapping
 Each function of the SDK has a corresponding function in the Module SiSoPyRt.
 SDK functions that creates a reference to a struct and returns 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 Gbe_initBoard is defined as:
 SDK definition:
int Gbe_initBoard(int board, int init_flag, struct BoardHandle**
board_handle_ptr);
Where the return value is the result error code, and board_handle_ptr is the
created reference.
 Python Wrapper definition:
(BoardHandle, errorCode) = Gbe_initBoard(board, init_flag)
Where the return values are the created reference and the error code.
 SDK functions that modifies 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:
 SDK 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)
 SDK functions that uses some if their arguments just as an out argument, are wrapped such
that those arguments are not passed at all to the function, and only returned together with
the original return value. For example the function clGetNumSerialPorts is defined as:
 SDK definition:
int clGetNumSerialPorts(unsigned int *numSerialPorts);
 Python Wrapper definition:
SiliconSoftware
6
Python SDK Wrapper
(errorCode, numSerialPorts) = clGetNumSerialPorts()
 SDK functions that require creating string buffer to be filled, are wrapped such that the
buffer is created internally and directly returned, without need to create it from the Python
code. It’s done this way because passing the buffer from Python to C is not possible with
Python versions 3.x.
For example the function Fg_getSystemInformation is defined as:
 SDK 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)
2.2 Call back
Call Back functions should be defined with same number and types of arguments as defined in the
SDK call back functions. They can then be simply 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, "")
SiliconSoftware
7
Python SDK Wrapper
return 0
The declaration of Fg_ApcFunc_t looks as follows,
typedef int(* Fg_ApcFunc_t)(frameindex_t imgNr, struct fg_apc_data
*data)
3 Python Wrapper API List
Basically the API of the Wrapper is the same as that of the SDK. This chapter contains only the
definitions of the functions that are renamed or have different order of arguments. For the
detailed usage, as well as for the rest of the API, refer to the SDK documentation.
3.1 fgrab
3.1.1 New defined functions
3.1.1.1 (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)
3.1.1.2 (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 SDK function Fg_getParameterWithType, according to the
passed type as following:
FgParamTypes
FG_PARAM_TYPE_INT32_T
FG_PARAM_TYPE_UINT32_T
FG_PARAM_TYPE_INT64_T
FG_PARAM_TYPE_UINT64_T
FG_PARAM_TYPE_DOUBLE
FG_PARAM_TYPE_CHAR_PTR
Python Wrapper function
Fg_getParameterWithInt
Fg_getParameterWithUInt
Fg_getParameterWithLong
Fg_getParameterWithULong
Fg_getParameterWithDouble
Fg_getParameterWithString
Fg_getParameterWithUInt /
Fg_getParameterWithULong
Fg_getParameterWithIntArray /
FG_PARAM_TYPE_SIZE_T
FG_PARAM_TYPE_STRUCT_SiliconSoftware
8
Python SDK Wrapper
FIELDPARAMACCESS
Fg_getParameterWithUIntArray /
Fg_getParameterWithLongArray /
Fg_getParameterWithULongArray
FG_PARAM_TYPE_STRUCT_Fg_getParameterWithFieldParameterInt
FIELDPARAMINT
FG_PARAM_TYPE_STRUCT_Fg_getParameterWithFieldParameterDouble
FIELDPARAMDOUBLE
FG_PARAM_TYPE_COMPLEX_DATATYPE Not implemented
3.1.1.3 (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 SDK function Fg_setParameterWithType, according to the
passed type as following:
FgParamTypes
FG_PARAM_TYPE_INT32_T
FG_PARAM_TYPE_UINT32_T
FG_PARAM_TYPE_INT64_T
FG_PARAM_TYPE_UINT64_T
FG_PARAM_TYPE_DOUBLE
FG_PARAM_TYPE_CHAR_PTR
Python Wrapper function
Fg_setParameterWithInt
Fg_setParameterWithUInt
Fg_setParameterWithLong
Fg_setParameterWithULong
Fg_setParameterWithDouble
Fg_setParameterWithString
Fg_setParameterWithUInt /
Fg_setParameterWithULong
Fg_setParameterWithIntArray /
Fg_setParameterWithUIntArray /
Fg_setParameterWithLongArray /
Fg_setParameterWithULongArray
FG_PARAM_TYPE_SIZE_T
FG_PARAM_TYPE_STRUCT_FIELDPARAMACCESS
FG_PARAM_TYPE_STRUCT_Fg_setParameterWithFieldParameterInt
FIELDPARAMINT
FG_PARAM_TYPE_STRUCT_Fg_setParameterWithFieldParameterDouble
FIELDPARAMDOUBLE
FG_PARAM_TYPE_COMPLEX_DATATYPE Not implemented
SiliconSoftware
9
Python SDK Wrapper
3.1.2 Functions with different arguments
Python SDK Wrapper
SDK
SisoImage Fg_getImagePtr(Fg_Struct,
void *Fg_getImagePtr(Fg_Struct *Fg, const
PicNr, DmaIndex)
frameindex_t PicNr, const unsigned int
DmaIndex)
SisoImage
void *Fg_getImagePtrEx(Fg_Struct *Fg,
Fg_getImagePtrEx(Fg_Struct, PicNr,
const frameindex_t PicNr, const unsigned
DmaIndex, memHandle)
int DmaIndex, dma_mem *pMem)
In Fg_getImagePtr and Fg_getImagePtrEx function, the return type is changed from void
pointer, which directly represents the image bytes, in the SDK into SisoImage instance.
To get again the byte array (NumPy array) from SisoImage, the function (imageArray) =
SiSoPyInterface. getArrayFrom(img, width, height) can be called.
SisoImage can be used directly with DrawBuffer function.
3.2 gbe
3.2.1 Functions with reordered arguments
In the following functions, The created handle/string 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 null.
Python SDK Wrapper
SDK
(BoardHandle, errorCode) =
int Gbe_initBoard(int board, int
Gbe_initBoard(board, init_flag)
init_flag, struct BoardHandle**
board_handle_ptr)
(CameraHandle, errorCode) =
int Gbe_getFirstCamera(struct BoardHandle
Gbe_getFirstCamera(board_handle, port)
*board_handle, int port, struct CameraHandle
**camera_handle_ptr)
(CameraHandle, errorCode) =
int Gbe_getCameraByIndex(struct
Gbe_getCameraByIndex(board_handle,
BoardHandle *board_handle, int port,
port, index)
SiliconSoftware
unsigned int index, struct CameraHandle
10
Python SDK Wrapper
**camera_handle_ptr);
(CameraHandle, errorCode) =
int Gbe_getCameraByMac(struct
Gbe_getCameraByMac(board_handle, port,
BoardHandle *board_handle, int port,
mac)
uint8_t mac[6], struct CameraHandle
**camera_handle_ptr)
(CameraHandle, errorCode) =
int Gbe_getCameraByIp(struct
Gbe_getCameraByIp(board_handle, port,
BoardHandle *board_handle, int port,
ip)
uint32_t ip, struct CameraHandle
**camera_handle_ptr)
(CameraHandle, errorCode) =
int Gbe_getCameraByUserName(struct
Gbe_getCameraByUserName(board_handle,
BoardHandle *board_handle, int port,
port, user_name)
char* user_name, struct CameraHandle
**camera_handle_ptr)
(string, errorCode) =
int Gbe_getStringValue(struct
Gbe_getStringValue(camera_handle,
CameraHandle *camera_handle, const
name)
char* name, const char** value_ptr)
(string, errorCode) =
int Gbe_setEnumerationValue(struct
Gbe_getEnumerationValue(camera_handle,
CameraHandle *camera_handle, const
name)
char* name, const char* value)
3.3 clser
3.3.1 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 null.
Python SDK Wrapper
SDK
(CLSerialRef, errorCode) =
int clSerialInit(unsigned int
clSerialInit(serialIndex)
serialIndex, void **serialRefPtr)
SiliconSoftware
11
Python SDK Wrapper
3.4 siso_auxport
3.4.1 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 null.
Python SDK Wrapper
SDK
(SisoAuxPort, errorCode) =
int SisoAuxPortInit(unsigned int
SisoAuxPortInit(board_id, port_num,
board_id, unsigned int port_num,
type)
SisoAuxPortType type, SisoAuxPort *
handle_ptr)
3.4.2 New defined functions
3.4.2.1 (error, value) = SisoAuxPortGetPropertyWith…( handle, property, size)
List of overloaded functions that are used to get port properties with information of different
types. They are replacing the SDK function SisoAuxPortGetProperty, according to the passed
type as following:
Python Wrapper function
SisoAuxPortGetPropertyWithInt
SisoAuxPortGetPropertyWithFloat
SisoAuxPortGetPropertyWithString
SisoAuxPortGetPropertyWithByteArray
SisoAuxPortPropertyType_Enum
SISO_AUX_PORT_PROPERTY_TYPE_INT
SISO_AUX_PORT_PROPERTY_TYPE_FLOAT
SISO_AUX_PORT_PROPERTY_TYPE_STRING
SISO_AUX_PORT_PROPERTY_TYPE_BINARY
3.4.2.2 (error) = SisoAuxPortSetPropertyWith…( handle, property, value, size)
List of overloaded functions that are used to set port properties with information of different
types. They are replacing the SDK function SisoAuxPortSetProperty, according to the passed
type as following:
Python Wrapper function
SisoAuxPortSetPropertyWithInt
SisoAuxPortSetPropertyWithFloat
SisoAuxPortSetPropertyWithString
SisoAuxPortSetPropertyWithByteArray
SiliconSoftware
12
SisoAuxPortPropertyType_Enum
SISO_AUX_PORT_PROPERTY_TYPE_INT
SISO_AUX_PORT_PROPERTY_TYPE_FLOAT
SISO_AUX_PORT_PROPERTY_TYPE_STRING
SISO_AUX_PORT_PROPERTY_TYPE_BINARY
Python SDK Wrapper
3.5 siso_genicam
3.5.1 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.
Python SDK Wrapper
SDK
(SgcBoardHandle, errorCode) =
int Sgc_initBoard(Fg_Struct* fg, int
Sgc_initBoard(Fg_Struct, initFlag)
initFlag, SgcBoardHandle** boardHandle)
(SgcBoardHandle, errorCode)
int Sgc_initBoardEx(Fg_Struct* fg,
=Sgc_initBoardEx(Fg_Struct, initFlag,
unsigned int initFlag, SgcBoardHandle**
portMask, slaveMode)
boardHandle, unsigned int portMask,
unsigned int slaveMode)
(SgcCameraHandle, errorCode) =
int Sgc_getCamera(SgcBoardHandle*
Sgc_getCamera(boardHandle, port)
boardHandle, const unsigned int port,
SgcCameraHandle** cameraHandle)
(SgcCameraHandle, errorCode) =
int Sgc_getCameraByIndex(SgcBoardHandle*
Sgc_getCameraByIndex(boardHandle,
boardHandle, const unsigned int index,
index)
SgcCameraHandle** cameraHandle)
(SgcConnectionProfile, errorCode) =
int Sgc_LoadConnectionProfile(Fg_Struct*
Sgc_LoadConnectionProfile(Fg_Struct,
fg, const char*
boardConfigurationFilePath)
boardConfigurationFilePath,
SgcConnectionProfile**
connectionProfilePtr)
(stringValue, errorCode) =
int Sgc_getStringValue(SgcCameraHandle*
Sgc_getStringValue(cameraHandle,
cameraHandle, const char* name, const
name)
char** stringValuePtr)
(stringValue, errorCode) =
int
Sgc_getEnumerationValueAsString(camer
Sgc_getEnumerationValueAsString(SgcCamer
aHandle, name)
aHandle* cameraHandle, const char* name,
const char** stringValuePtr)
SiliconSoftware
13
Python SDK Wrapper
3.6 SisoDisplay
3.6.1 Functions with different arguments
Python SDK Wrapper
SDK
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, in the SDK into SisoImage instance.
SisoImage is created using Fg_getImagePtr and Fg_getImagePtrEx functions.
3.7 SisoIo.h
3.7.1 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 null.
Python SDK Wrapper
SDK
(AviRef, errorCode) =
int IoCreateAVIGray(void **AviRef,
IoCreateAVIGray(filename, width,
const char *filename, int width, int
height, fps)
height, double fps)
(AviRef, errorCode) =
int IoCreateAVIGrayW(void **AviRef,
IoCreateAVIGrayW(filename, width,
const LPCWSTR filename, int width, int
height, fps)
height, double fps)
(AviRef, errorCode) =
int IoCreateAVIColor(void **AviRef,
IoCreateAVIColor(filename, width,
const char *filename, int width, int
height, fps)
height, double fps)
(AviRef, errorCode) =
int IoCreateAVIColorW(void **AviRef,
IoCreateAVIColorW(filename, width,
const LPCWSTR filename, int width, int
height, fps)
height, double fps)
(AviRef, width, height, bitDepth,
int IoOpenAVI(void **AviRef, const
errorCode) = IoOpenAVI(fileName)
char *fileName, int *width, int
*height, int *bitDepth)
SiliconSoftware
14
Python SDK Wrapper
(SeqRef, errorCode) =
int IoCreateSeq(void **SeqRef, const
IoCreateSeq(string pFilename, width,
char *pFilename, int width, int
height, bitdepth, format)
height, int bitdepth, int format)
(SeqRef, width, height, bitDepth,
int IoOpenSeq(void **SeqRef, const
errorCode) = IoOpenSeq(pFilename,
char *pFilename, int* width, int*
mode)
height, int* bitdepth, int mode)
(SisoIoImageEngine, errorCode) =
int IoImageOpen(const char *filename,
IoImageOpen(filename)
SisoIoImageEngine **handle)
(SisoIoImageEngine, errorCode) =
int IoImageOpenEx(const char
IoImageOpenEx(filename, RGBSequence)
*filename, SisoIoImageEngine **handle,
int RGBSequence)
SiliconSoftware
15
Python SDK Wrapper
3.7.2 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 SDK, into SisoImage instance.
To get again the byte array from SisoImage, the function SisoImage.toByteArray(uint
imageSize) can be called.
Python SDK Wrapper
SDK
(SisoImage, width, height, bitPerSample,
void *IoReadTiff(const char
samplePerPixel) = IoReadTiff(filename,
*filename, unsigned char**data, int
data)
*width, int *height, int
*bitPerSample, int *samplePerPixel)
(SisoImage, width, height, bitPerSample,
void *IoReadTiffW(const LPCWSTR
samplePerPixel) = IoReadTiffW(filename,
filename, unsigned char**data, int
data)
*width, int *height, int
*bitPerSample, int *samplePerPixel)
(SisoImage, width, height, bitPerSample,
void *IoReadTiffEx(const char
samplePerPixel) = IoReadTiffEx(filename,
*filename, unsigned char**data, int
data, RGBSequence)
*width, int *height, int
*bitPerSample, int *samplePerPixel,
int RGBSequence)
(SisoImage, width, height, bitPerSample,
void *IoReadTiffExW(const LPCWSTR
samplePerPixel) =
filename, unsigned char**data, int
IoReadTiffExW(filename, data,
*width, int *height, int
RGBSequence)
*bitPerSample, int *samplePerPixel,
int RGBSequence)
(SisoImage, width, height, bits) =
void *IoReadBmp(const char
IoReadBmp(filename, data)
*filename,unsigned char **data,int
*width,int *height,int *bits)
SiliconSoftware
16
Python SDK Wrapper
Contact Details
SiliconSoftware GmbH
SiliconSoftware Inc.
Steubenstrasse 46
1 Tara Boulevard, Suite 200
D - 68163 Mannheim, Germany
Nashua, NH 03062, USA
Phone: +49(0)621.789 507 0
Phone: +1 603 324 7172
Fax:
Fax:
+49(0)621.789 507 10
+1 603 324 7101
Email: [email protected]
Email: [email protected]
Web: www.silicon.software
Web: www.silicon.software
Disclaimer
While every precaution has been taken in the preparation of this manual, Silicon Software GmbH
assumes no responsibility for errors or omissions. Silicon Software GmbH reserves the right to
change the specification of the product described within this manual and the manual itself at any
time without notice and without obligation of Silicon Software GmbH to notify any person of such
revisions or changes.
Trademarks
All trademarks and registered trademarks are the property of their respective owners.
Copyright Note
© Copyright 2017 Silicon Software GmbH. All rights reserved. This document may not in whole or
in part, be reproduced, transmitted, transcribed, stored in any electronic medium or machine
readable form, or translated into any language or computer language without the prior written
consent of Silicon Software GmbH.
SiliconSoftware
17
Python SDK Wrapper