콘텐츠로 바로 가기

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. 래퍼를 사용하기 전에 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. 가져오기 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 출력 인수)은 원래 C 함수의 출력 인수와 정확히 동일한 순서를 가집니다.

반환 값이 없는 C 함수#

C 함수가 값을 반환하지 않는 경우, C 함수의 출력 인수가 Python 함수의 반환 값이 됩니다. 원래 C 함수의 첫 번째 출력 인수는 Python 함수의 첫 번째 반환 값이 됩니다. Python 함수의 반환 값(즉, 이전 C 출력 인수)은 원래 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 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와 동일합니다. 이 섹션에서는 이름이 변경되었거나 인자의 순서가 다른 함수들의 정의만 다룹니다.

여기서 제공되는 함수들은 라이브러리별로 그룹화되어 있습니다:

정보

C API에서는 이미지 데이터가 주로 로우 버퍼(void, char)에 저장됩니다. Python은 로우 메모리 접근을 지원하지 않으므로, 이러한 포인터는 불투명 핸들(opaque handle)로 표현됩니다. 이 불투명 핸들은 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 함수
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.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#

Wrapper 전용 함수#

다음 함수들은 Python에서 사용할 수 없는 C/C++ 기능(예: raw 메모리 할당)의 대체(우회) 역할을 합니다.

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 이(가) 이미지 인자로 전달됩니다).

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)