跳至內容

Python 包裝函式#

為了讓您能在使用 Python 建立的程式中使用 Framegrabber API，系統提供了 Python wrapper。此 Python wrapper 將 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 wrapper 與 Framegrabber SDK 一同安裝。您可以在 Framegrabber SDK 安裝目錄的下列子資料夾中找到 wrapper：

Basler/FramegrabberSDK/SDKWrapper/PythonWrapper/pythonxx

資訊

Basler 提供支援 Windows 與 Linux 上 Python 3.9、3.10、3.11、3.12 或 3.13 版本的 wrapper 版本。您可以在對應的子資料夾 python39、python310、python311、python312 和 python313 中找到這些版本。

Python Framegrabber API wrapper 由 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. 在使用此封裝之前，請先下載 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 Function
具有回傳值與輸出引數： 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 Wrapper 定義：
(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 Wrapper 定義：
(errorCode, infoBufferSize) = Fg_getParameterInfoXML(Fg_Struct, port, infoBuffer, infoBufferSize)

將部分引數作為 out 引數使用的 Framegrabber API 函式經過包裝，使這些引數完全不會傳遞至函式中，而是僅與原始回傳值一同回傳。例如，函式 clGetNumSerialPorts 定義為：

  • Framegrabber API 定義：
int clGetNumSerialPorts(unsigned int *numSerialPorts);
  • Python Wrapper 定義：
(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 Wrapper 定義：
(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 清單#

Wrapper 的 API 基本上與 Framegrabber API 相同。本節僅包含已重新命名或具有不同引數順序之函式的定義。

此處提供的函式依 library 分組：

資訊

在 C API 中，影像資料通常儲存在原始緩衝區（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#

引數順序重排的函式#

在以下函式中，建立的代辦代碼（Handle）會與函式的錯誤碼一起傳回，而不是作為引數傳遞。如果發生錯誤， errorCode 將具有大於 0 的值，且傳回值將會是 None.

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

引數資料類型變更的函式#

以下函式已在 Framegrabber SDK 5.6.1 發行版本的 Python wrapper 中變更。早期版本中的上述引數需要字串值。自 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 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)

在 DrawBuffer 函式中， ulpBuf 引數類型已從直接表示影像位元組的 void 指標變更為不透明代辦代碼（Handle），即 ImageDataHandle.

SisoIo.h#

Wrapper 專用函式#

以下函式作為 Python 中無法使用的 C/C++ 功能（即原始記憶體配置）的替代方案（變通方法）。

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
分配用於影像資料的緩衝區並傳回該緩衝區的代辦代碼 (handle)。手動分配的緩衝區必須使用 IoFreeImageBuffer.
IoFreeImageBuffer(ImageDataHandle)
釋放使用以下項目分配的緩衝區： IoAllocateImageBuffer.

引數順序重排的函式#

在下列函數中，建立的代辦代碼 (handle) 會與函數的錯誤代碼一同傳回，而不是作為引數傳遞。如果發生錯誤， errorCode 將具有大於 0 的值，且傳回值將會是 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)

回傳資料類型不同的函式#

在下列函數中，傳回型別從直接表示 Framegrabber API 中影像位元組的 void 指標變更為不透明代辦代碼 (opaque handle，以下簡稱為 ImageDataHandle)。

若要再次從 ImageDataHandle取得 bytearray， SiSoPyInterface.getArrayFrom(image, width, height, intype, totype) 可以呼叫函數 ImageDataHandle （需要 numpy，其中將

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)