コンテンツにスキップ

Python Wrapper#

Pythonで作成したプログラムでFramegrabber APIを使用できるように、Pythonラッパーが提供されています。Pythonラッパーは、Framegrabber APIの機能をPythonモジュールにラップします。

すべてのC/C++ Framegrabber API関数は1つのPythonモジュールにラップされます SiSoPyInterface.

Python APIの主要部分はC/C++ APIと同様に動作するため、ほとんどの場合、一般的なC/C++ Framegrabber APIのドキュメントを参照できます。Python APIがC/C++ APIと異なるすべてのケースについては、次のセクションで詳しく説明します。

ラッパーのコンポーネント#

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. ラッパーを使用する前に、Pythonをダウンロードして、お使いのPCにまだインストールされていない場合はインストールしてください。Baslerでは、NumPyパッケージもインストールすることを推奨しています。または、すでにNumPyが含まれているWinPythonを直接使用することもできます。

  2. NumPyのインストール:

    1. 前提条件：ホストにPythonがすでにインストールされていることを確認してください。
    2. PythonパッケージのインストールにPyPAが推奨するツールであるpipをダウンロードしてインストールします。
    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のバージョンごとに2つのサンプルがあります：

Basler/FramegrabberSDK/SDKWrapper/PythonWrapper/pythonXX/Examples

関数マッピング#

Framegrabber APIの各関数には、Pythonラッパーモジュールに対応する関数があります（SiSoPyRtを使用します。

Pythonには出力引数の概念がなく、代わりに複数の値を返すことができるため、C/C++の出力引数はPythonでは追加の戻り値になります。

マッピングは、以下の段落で説明するように機能します。

戻り値と出力引数を持つC関数#

C関数の戻り値（通常はエラーコード）がPython関数の最初の戻り値になります。

C関数の出力引数は、Python関数では追加の戻り値になります。元のC関数の最初の出力引数が、Python関数の2番目の戻り値になります。Python関数の追加の戻り値（つまり、元のCの出力引数）は、元のC関数の出力引数とまったく同じ順序でPython関数内に存在します。

戻り値を持たないC関数#

C関数が値を返さない場合、C関数の出力引数がPython関数の戻り値になります。元のC関数の最初の出力引数が、Python関数の最初の戻り値になります。Python関数の戻り値（つまり、元のCの出力引数）は、元のC関数の出力引数とまったく同じ順序でPython関数内に存在します。

例#

例のタイプ 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 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()

Fillする必要のある文字列バッファの作成を必要とする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リスト#

ラッパーの API は、基本的には Framegrabber API のものと同じです。このセクションには、名前が変更された関数、または引数の順序が異なる関数の定義のみが含まれています。

ここで提供される関数は、ライブラリごとにグループ化されています：

情報

C APIでは、画像データは多くの場合生バッファ（void, char）に保持されます。Pythonは生のMemoryアクセスをサポートしていないため、これらのポインタは不透明なハンドルで表現されます。この不透明なハンドルは、C APIが画像データに対してvoidポインタを使用するすべての場所で使用できます。

このドキュメントでは、この不透明なハンドルを次のように呼びます： ImageDataHandle.

特定の関数の使用方法の詳細、およびここに記載されていない関数に関する情報については、Framegrabber API documentationを参照してください。

fg#

Python wrapperには、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 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ポインターから、不透明なハンドルである ImageDataHandle.

SisoIo.h#

ラッパー固有の関数#

次の関数は、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
画像データのバッファを割り当て、そのバッファへのハンドルを返します。手動で割り当てられたバッファは、次のものを使用して解放する必要があります： IoFreeImageBuffer.
IoFreeImageBuffer(ImageDataHandle)
で割り当てられたバッファを解放します： IoAllocateImageBuffer.

引数が並べ替えられた関数#

次の関数では、作成されたハンドルは引数として渡されるのではなく、関数からのエラーコードとともに返されます。エラーが発生した場合、 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ポインタから、不透明なハンドル（以下、 ImageDataHandleを使用します。

から再度バイト配列を取得するには、 ImageDataHandle、関数 SiSoPyInterface.getArrayFrom(image, width, height, intype, totype) （numpyが必要）を呼び出すことができます（ここで、 ImageDataHandle がimage引数として渡されます）。

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)