跳至內容

Python 包裝函式#

為了讓您能在使用 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 一併安裝。您可以在 Framgrabber SDK 安裝目錄的以下子資料夾中找到該封裝程式：

Basler/FramegrabberSDK/SDKWrapper/PythonWrapper/pythonxx

資訊

Basler 提供支援 Python 3.9、3.10、3.11、3.12 或 3.13 版本的封裝程式，可於Windows 及Linux 取得。您可在相應的子資料夾 python39、python310、python311、python312 及 python313 中找到這些版本。

PythonFramegrabber 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. 在使用此封裝程式之前，請先下載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/範例

函數映射#

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 封裝 API 清單#

此封裝函式的 API 基本上與Framegrabber API 的 API 相同。本節僅列出那些已重新命名，或參數順序有所不同的函式定義。

此處提供的函式已依函式庫分組：

資訊

在 C API 中，影像資料通常儲存在原始緩衝區（void, char）中。由於 Python 不支援直接存取原始記憶體，因此這些指標會以不透明句柄來表示。在 C API 使用 void 指標指向影像資料的所有情況下，皆可使用此不透明句柄。

在本文件中，此不透明句柄被稱為 ImageDataHandle.

有關特定函數的使用詳情，以及此處未列出的函數相關資訊，請參閱Framegrabber API 文件。

fg#

Python 封裝函式庫中提供了一些功能，這些功能與 C/C++ API 並無完全對應：

(description) = Fg_getErrorDescription (errorNumber)

此函式取代了以下兩個函式：

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

const char *const getErrorDescription (int ErrorNumber)

(錯誤, 值) = Fg_getParameterWith… (Fg_Struct, 參數編號, DmaIndex)#

用於取得包含不同類型資訊的幀擷取卡參數的重載函式清單。這些函式取代了Framegrabber API 函式 Fg_getParameterWithType, 根據傳入的類型如下：

FgParamTypes Python 封裝函式
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 尚未實作

(錯誤) = Fg_setParameterWith…(Fg_Struct, ParameterNr, Value, DmaIndex)#

用於設定幀擷取卡參數並傳遞不同類型資料的重載函式清單。這些函式取代了Framegrabber API 函式 Fg_setParameterWithType, 根據傳入的類型，如下所示：

FgParamTypes Python 封裝函式
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.

PythonFramegrabber API 封裝函式 Framegrabber API
(errorCode, CLSerialRef) = clSerialInit(serialIndex) int clSerialInit(unsigned int serialIndex, void *serialRefPtr)

參數資料型別已變更的函式#

在 Framgrabber SDK 5.6.1 版本中，Python 封裝函式庫的以下函式已有所變更。在早期版本中，所述的參數預期接收字串值；自 Framgrabber SDK 5.6.1（及更高版本）起，則必須傳入 bytearray 值。

clSerialRead, argument buffer

clGetManufacturerInfo, argument manufacturerName

clGetSerialPortIdentifier, argument portID

clGetErrorText, argument errorText

siso_genicam#

參數順序重新排列的函式#

在以下函式中，結果值會連同錯誤碼一併由函式傳回，而非作為參數傳遞。若發生錯誤， errorCode 其值將不為 0，且回傳值將為 None.

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

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

封裝函式專屬功能#

以下函式用來替代（或作為變通方案）Python 中無法提供的 C/C++ 功能（例如：原始記憶體分配）。

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

PythonFramegrabber 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)。

要從 ImageDataHandle，該函式 SiSoPyInterface.getArrayFrom(image, width, height, intype, totype) （需要 numpy）可被呼叫（其中 ImageDataHandle （作為影像參數傳入）。

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