콘텐츠로 건너뛰기

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와 함께 설치됩니다. 래퍼는 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를 사용하기 전에 PC에 Python이 설치되어 있지 않다면 다운로드하여 설치하세요. 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. Python 프로젝트에서 SiSoPyInterface.py 을(를) 가져옵니다(Import). 가져온 모듈을 통해 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 출력 인자)은 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()

채워질 문자열 버퍼를 생성해야 하는 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은 로우 메모리 접근을 지원하지 않기 때문에, 이러한 포인터는 불투명 핸들(opaque handle)로 표현됩니다. 이 불투명 핸들은 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 함수
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 함수
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.11.1 릴리스의 Python 래퍼에서 변경되었습니다. 이전 버전에서는 언급된 인수로 문자열 값을 사용했습니다. Framegrabber SDK 5.11.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#

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
이미지 데이터를 위한 버퍼를 할당하고 해당 버퍼에 대한 핸들을 반환합니다. 수동으로 할당된 버퍼는 다음을 사용하여 해제해야 합니다. 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).

에서 bytearray를 다시 가져오려면 ImageDataHandle, 함수 SiSoPyInterface.getArrayFrom(image, width, height, intype, totype) (numpy 필요)를 호출할 수 있습니다 (여기서 ImageDataHandle 이(가) 이미지 인수로 전달됩니다).

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)