跳转到内容

Python Wrapper#

为了让您能够在用 Python 创建的程序中使用 Framegrabber API，我们为您提供了一个 Python 包装器。该 Python 包装器将 Framegrabber API 的功能包装到了一个 Python 模块中。

所有 C/C++ Framegrabber API 函数均被包装在一个 Python 模块中 SiSoPyInterface.

Python API 的主要部分与 C/C++ API 类似，因此在大多数情况下，您可以参考通用的 C/C++ Framegrabber API 文档。Python API 与 C/C++ API 不同的所有情况都在以下章节中详细介绍。

Wrapper 组件#

Python 包装器与 Framegrabber SDK 一同安装。您可以在 Framegrabber SDK 安装目录的以下子文件夹中找到该包装器：

Basler/FramegrabberSDK/SDKWrapper/PythonWrapper/pythonxx

信息

Basler 提供的包装器版本在 Windows 和 Linux 上支持 Python 3.9、3.10、3.11、3.12 或 3.13。您可以在相应的子文件夹 python39、python310、python311、python312 和 python313 中找到这些版本。

Python Framegrabber API 包装器由 2 个文件组成， SiSoPyInterface.py 和 _SiSoPyRt_xx.pyd:

  • SiSoPyInterface.py 是封装模块。您可以在 Framegrabber SDK 安装路径中找到该文件：

    Basler/FramegrabberSDK/SDKWrapper/PythonWrapper/pythonxx/lib

  • _SiSoPyRt_xx.pyd 是与 Framegrabber API 进行通信的 DLL。您可以在 Framegrabber SDK 安装路径中找到该文件：

    Basler/FramegrabberSDK/bin

安装#

要开始使用此封装：

  1. 在使用 Wrapper 之前，请下载并安装 Python（如果您的计算机上尚未安装）。Basler 建议同时安装 NumPy 软件包。或者，您也可以直接使用已包含 NumPy 的 WinPython。

  2. 安装 NumPy：

    1. 前提条件：请确保您的主机上已安装 Python。
    2. 下载并安装 pip，这是 PyPA 推荐用于安装 Python 软件包的工具。
    3. 从 https://pypi.org/ 下载 numpy 软件包。

    4. 在命令行工具中，输入：

      python -m pip install --user numpy

    有关更多详细信息，请参阅 https://scipy.org/install.html 或 https://packaging.python.org/tutorials/installing-packages/

  3. 导入 SiSoPyInterface.py 在您的 Python 项目中。可以通过导入的模块访问 Framegrabber API。

  4. 在运行程序之前，请设置以下环境变量（如以下示例所示）。请根据您的安装路径调整路径。（在以下示例中，Python 3.9 已安装到 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

示例#

为了最轻松地开始使用包装器进行图像采集，您可以在 Framegrabber SDK 安装目录中找到每个 Python 版本对应的两个示例：

Basler/FramegrabberSDK/SDKWrapper/PythonWrapper/pythonXX/Examples

函数映射#

Framegrabber API 的每个函数在 Python 包装器模块中都有一个对应的函数（SiSoPyRt）。

由于 Python 没有输出参数的概念，但可以返回多个值，因此 C/C++ 输出参数在 Python 中变成了附加的返回值。

映射方式如以下段落所述。

带返回值和输出参数的 C 函数#

C 函数的返回值（通常是错误代码）成为 Python 函数的第一个返回值。

C 函数的输出参数在 Python 函数中变为附加的返回值。原始 C 函数的第一个输出参数成为 Python 函数中的第二个返回值。Python 函数的附加返回值（即以前的 C 输出参数）在 Python 函数中的顺序与原始 C 函数中输出参数的顺序完全相同。

不带返回值的 C 函数#

如果 C 函数不返回值，则 C 函数的输出参数将成为 Python 函数的返回值。原始 C 函数的第一个输出参数将成为 Python 函数中的第一个返回值。Python 函数的返回值（即原 C 的输出参数）在 Python 函数中的顺序与它们在原始 C 函数中的输出参数顺序完全相同。

示例#

示例类型 C 函数 Python 函数
带返回值和输出参数： 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)
仅返回值： Fg_Struct *Fg_Init(const char *FileName, unsigned int BoardIndex); fg_struct = Fg_Init(fileName, boardIndex)

特殊情况#

创建对以下内容的引用的 Framegrabber API 函数： struct 并且返回错误代码经过修改，使其既能直接返回引用（或 none 如果发生错误），以及错误代码。例如，函数 Fg_getAppletIterator 定义为：

  • Framegrabber API 定义：
int Fg_getAppletIterator(int boardIndex, const enum FgAppletIteratorSource src, Fg_AppletIteratorType * iter, int flags);

返回值是结果错误代码，并且 iter 是所创建的引用。

  • Python 包装器定义：
(iter , errorCode) = Fg_getAppletIterator (boardIndex, src, flags)

返回值是错误代码和所创建的引用。

修改其参数的 Framegrabber API 函数进行了封装，以便将修改后的值与原始返回值一起返回。例如，函数 Fg_getParameterInfoXML 定义为：

  • Framegrabber API 定义：
int Fg_getParameterInfoXML(Fg_Struct *Fg, int port, char * infoBuffer, size_t *infoBufferSize);
  • Python 包装器定义：
(errorCode, infoBufferSize) = Fg_getParameterInfoXML(Fg_Struct, port, infoBuffer, infoBufferSize)

将某些参数用作输出参数的 Framegrabber API 函数经过了包装，使得这些参数根本不会传递给函数，而是仅与原始返回值一起返回。例如，函数 clGetNumSerialPorts 定义为：

  • Framegrabber API 定义：
int clGetNumSerialPorts(unsigned int *numSerialPorts);
  • Python 包装器定义：
(errorCode, numSerialPorts) = clGetNumSerialPorts()

需要创建要填充的字符串缓冲区的 Framegrabber API 函数进行了封装，以便在内部创建缓冲区并直接返回，无需在 Python 代码中创建。例如，函数 Fg_getSystemInformation 定义为：

  • Framegrabber API 定义：
int Fg_getSystemInformation(Fg_Struct *Fg, const enum Fg_Info_Selector selector, const enum FgProperty propertyId, int param1, void* buffer, unsigned int* bufLen);
  • Python 包装器定义：
(errorCode, buffer, bufLen) = Fg_getSystemInformation(Fg_Struct, selector, propertyId, param1)

回调函数#

回调函数的定义应具有与 C/C++ Framegrabber API 回调函数中定义的相同数量和类型的参数。然后，它们可以作为参数传递。

例如，以下代码用于注册 APC 处理程序（来自 AcqAPC.py 示例）：

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

函数 apcCallback 必须具有相同的签名 Fg_ApcFunc_t，一个示例实现为：

# Callback function definition
def apcCallback(imgNr, userData):
s.DrawBuffer(userData.displayid,
s.Fg_getImagePtrEx(userData.fg, imgNr,
userData.port, userData.mem), imgNr, "")
return 0

声明 Fg_ApcFunc_t 外观如下：

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

Python Wrapper API 列表#

包装器的 API 与 Framegrabber API 基本相同。本节仅包含重命名或参数顺序不同的函数的定义。

此处提供的函数按库进行分组：

信息

在 C API 中，图像数据通常保存在原始 buffer（void, char）中。由于 Python 不支持原始 Memory 访问，这些指针由一个不透明句柄表示。在 C API 使用 void 指针指向图像数据的所有地方，都可以使用此不透明句柄。

在本文档中，此不透明句柄被称为 ImageDataHandle.

有关使用特定函数的详细信息以及此处未列出的函数的信息，请参阅 Framegrabber API documentation。

fg#

Python 包装器中提供了一些与 C/C++ API 没有 1:1 对应关系的函数：

(description) = Fg_getErrorDescription (errorNumber)

此函数替代了以下两个函数：

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

const char *const getErrorDescription (int ErrorNumber)

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

用于获取具有不同类型信息的采集卡参数的重载函数列表。它们替换了 Framegrabber API 函数 Fg_getParameterWithType，根据传递的类型如下：

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 未实现

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

用于通过不同类型的信息设置采集卡参数的重载函数列表。它们替代了 Framegrabber API 函数 Fg_setParameterWithType，根据传递的类型如下：

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 未实现

clser#

参数重新排序的函数#

在以下函数中，创建的句柄与函数返回的错误代码一起返回，而不是作为参数传递。如果发生错误， errorCode 将具有除 0 以外的值，并且返回值将是 None.

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

参数数据类型更改的函数#

以下函数在 Framegrabber SDK 5.10.0（应为 5.6.1，按原文）版 Python 封装中有所更改。早期版本中提到的参数需要字符串值。自 Framegrabber SDK 5.6.1（及更高版本）起，改为需要 bytearray 值。

clSerialRead, argument buffer

clGetManufacturerInfo, argument manufacturerName

clGetSerialPortIdentifier, argument portID

clGetErrorText, argument errorText

siso_genicam#

参数重新排序的函数#

在以下函数中，结果值与函数的错误代码一起返回，而不是作为参数传递。如果发生错误， errorCode 将具有除 0 以外的值，并且返回值将是 None.

Python Framegrabber API 包装器 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 包装器 Framegrabber API
DrawBuffer(nId, ulpBuf, nNr, cpStr) void DrawBuffer(int nId, const void *ulpBuf, const int nNr, const char *cpStr)

在 DrawBuffer 函数中， ulpBuf 参数类型从直接表示图像字节的 void 指针更改为不透明句柄， ImageDataHandle.

SisoIo.h#

Wrapper 专用函数#

以下函数用作 Python 中不可用的 C/C++ 功能（即原始 Memory 分配）的替代方案（变通方法）。

Python Framegrabber API 包装器
(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
为图像数据分配缓冲区并返回指向该缓冲区的句柄。手动分配的缓冲区必须使用以下工具释放： IoFreeImageBuffer.
IoFreeImageBuffer(ImageDataHandle)
释放使用以下项分配的缓冲区： IoAllocateImageBuffer.

参数重新排序的函数#

在以下函数中，创建的句柄与函数的错误代码一起返回，而不是作为参数传递。如果发生错误， errorCode 将具有除 0 以外的值，并且返回值将是 None.

Python Framegrabber API 包装器 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)

返回数据类型不同的函数#

在以下函数中，返回类型从 Framegrabber API 中直接表示图像字节的 void 指针更改为不透明句柄（以下称为 ImageDataHandle）。

要再次从获取 bytearray ImageDataHandle中，函数 SiSoPyInterface.getArrayFrom(image, width, height, intype, totype) （需要 numpy）可以调用（其中 ImageDataHandle 作为图像参数传递）。

Python Framegrabber API 包装器 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)