工业相机SDK接口设计说明书.docx

工业相机SDK接口设计说明书.docx

《工业相机SDK接口设计说明书.docx》由会员分享，可在线阅读，更多相关《工业相机SDK接口设计说明书.docx（50页珍藏版）》请在冰豆网上搜索。

工业相机SDK接口设计说明书

工业相机SDK

接口设计说明书

编制

审核

批准

1.简介

1.1目标及围

本文档的目的是设计一套工业相机SDK的统一接口，兼容GigEVision、1394、U3V和CameraLink等标准协议。

业务层软件可同时调用GenApi和这套接口，以实现对相机的控制。

当前版本仅支持GigEVision和U3V两种传输协议，所以主要根据?

GigEVisionSDK产品需求规格说明书?

和?

USB3VisionSDK产品需求规格说明书?

进展设计，今后会在此版本的根底上逐渐完善。

本文档的预期读者是工程经理、软件详细设计者、软件开发人员、测试人员和工程管理人员等。

1.2相关术语

术语/缩写

含义

GigEVision

GigEVision是由自动化影像协会AIA（AutomatedImagingAssociation）发起指定的一种基于千兆以太网的图像传输的标准。

具有传输距离长〔无中继时100米〕、传输效率高并可向上升级到万兆网、通信控制方便、软硬件互换性强、可靠性高等优点，是未来数字图像领域的主要接口标准，必将被越来越多的商家多采用。

U3V

全称USB3Vision，是一种基于USB3.0技术的传输协议，传输速度快。

SDK

应用软件开发包。

GenICam

通用相机接口，属于上层应用开发的通用接口协议。

GenApi

GenICam的相机接口局部

1.3参考资料

1.?

GigEVisionSDK产品需求规格说明书.doc?

.

2.?

USB3VisionSDK产品需求规格说明书.doc?

.

3.?

GenICam_Standard_v2_0.pdf?

.

4.eBUSSDKC++API.chm.

5.FlyCapture2CDocumentation.chm.

6.FlyCapture2SDKHelp.chm

7.JAISDK.chm

8.ImagingSource.chm.

9.PylonCSDK.chm

2.分析设计

2.1设计思想

工业相机SDK的设计首先考虑的是支持多个相机协议，提取共性后设计通用的接口和构造体，使得上层应用软件不需要关心具体的相机协议。

其次要支持GenICam，把GenApi引入作为SDK接口的一局部。

但由于GenApi是C++类形式的接口，为保持接口风格的一致性和用户的需求，我们也需要设计一套C++接口。

另外，为简化SDK的调用流程和上层软件的开发难度，我们还要设计一套C接口。

最后遵循SDK的易扩展性设计了这套SDK。

2.2接口构造

接口分C++和C两套：

2.2.1C++接口

当前版本主要包含3个类：

1.传输层工厂类，通过该类获取单件实例，然后枚举在线设备，以及创立和销毁设备；

2.设备控制类，通过该类控制指定的设备，包括开启停顿设备、获取图像等；

3.GenApi，通过该模块可以获取和设置相机参数。

2.2-1接口构造图

2.2.2C接口

C接口分为四个方向：

1.相机控制通用接口，包含创立句柄、连接设备、获取图像数据等；

2.XML相关接口，部封装了GenICam，实现XML解析和所有相机参数节点的获取及设置；

3.GigEVision相机特有的接口，如强制IP、设置网络驱动模式等；

4.U3V相机特有的接口。

2.3数据流分析

2.3-1数据流图

3.接口描述〔C++接口〕

C++接口以类形式提供，所以接口描述也按照类来划分，可划分为三大模块：

3.1传输层工厂类

3.1.1GetInstance

功能说明

获取传输层工厂单件

接口所在位置

TlFactory.h

调用上下文或依赖对象描述

调用SDK的其他功能接口前，需要先调用此接口

函数方法

staticCTlFactory&GetInstance（）;

输入

参数代码/名称

数据类型

参数说明

无

无

无

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

返回传输层工厂单件

处理过程

把工厂部定义的静态成员单件实例返回

备注

无

例如

CTlFactory&tlFactory=CTlFactory:

:

GetInstance（）;

3.1.2EnumerateTls

功能说明

枚举支持的传输层类型

接口所在位置

TlFactory.h

调用上下文或依赖对象描述

需要先获取工厂实例

函数方法

staticCTlFactory&GetInstance（）;

输入

参数代码/名称

数据类型

参数说明

无

无

无

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

返回支持的传输层类型

处理过程

略

备注

无

例如

//2.枚举支持的传输层类型

unsignedintnSupportedTls=tlFactory.EnumerateTls（）;

if（MV_GIGE_DEVICE==（nSupportedTls&MV_GIGE_DEVICE））

{

MyGigETest（）;

}

3.1.3EnumDevices

功能说明

枚举子网，指定的传输协议对应的所有设备

接口所在位置

TlFactory.h

调用上下文或依赖对象描述

需要先获取工厂实例，枚举设备获取设备信息后，可创立设备实例

函数方法

virtualintEnumDevices（unsignedintnTLayerType,MV_CC_DEVICE_INFO_LIST&stDevList）;

输入

参数代码/名称

数据类型

参数说明

nTLayerType

unsignedint

传输层协议类型

stDevList

MV_CC_DEVICE_INFO_LIST&

设备信息列表

输出

参数代码/名称

数据类型

参数说明

stDevList

MV_CC_DEVICE_INFO_LIST&

设备信息列表

返回值

成功，返回MV_OK；失败，返回错误码

处理过程

由指定的协议类型，播送相应的消息，发现设备并记录设备信息

备注

无

例如

MV_CC_DEVICE_INFO_LISTstDevList;

memset（&stDevList,0,sizeof（MV_CC_DEVICE_INFO_LIST））;

intnRet=tlFactory.EnumDevices（MV_GIGE_DEVICE,stDevList）;

if（MV_OK!

=nRet）

{

printf（"error:

EnumDevices[%x]\n",nRet）;

return1;

}

3.1.4CreateDevice

功能说明

创立设备实例

接口所在位置

TlFactory.h

调用上下文或依赖对象描述

需要先获取设备信息后，才能创立设备实例

函数方法

virtualIMvDevice*CreateDevice（constMV_CC_DEVICE_INFO&device）;

输入

参数代码/名称

数据类型

参数说明

device

constMV_CC_DEVICE_INFO&

指定设备的信息

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

成功，返回设备实例；失败，返回NULL

处理过程

由输入的设备信息，创立相应类型的设备对象

备注

无

例如

//由设备信息创立设备实例

CMvGigEDevice*MyDevice=dynamic_cast（tlFactory.CreateDevice（*（stDevList.pDeviceInfo[i]）））;

if（NULL==MyDevice）

{

printf（"error:

CreateDevice\n"）;

break;

}

3.1.5DestroyDevice

功能说明

销毁设备实例及相应的资源

接口所在位置

TlFactory.h

调用上下文或依赖对象描述

前提是已创立设备实例

函数方法

virtualintDestroyDevice（IMvDevice*）;

输入

参数代码/名称

数据类型

参数说明

pDevice

IMvDevice

设备实例

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

成功，返回设备实例；失败，返回错误码

处理过程

释放指定设备实例的部资源，然后删除映射表的设备信息

备注

无

例如

//从工厂中销毁设备

intnRet=tlFactory.DestroyDevice（MyDevice）;

if（MV_OK!

=nRet）

{

printf（"warning:

DestroyDevicefail[%x]\n",nRet）;

}

3.2设备控制类

3.2.1Open

功能说明

翻开设备

接口所在位置

MvDeviceBase.h

调用上下文或依赖对象描述

已创立设备实例

函数方法

virtualintOpen（）;

输入

参数代码/名称

数据类型

参数说明

无

无

无

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

成功，返回MV_OK；失败，返回错误码

处理过程

连接设备，获取设备独占权限

备注

无

例如

intnRet=MyDevice->Open（）;

if（MV_OK!

=nRet）

{

printf（"error:

Open[%x]\n",nRet）;

continue;

}

3.2.2Close

功能说明

关闭设备

接口所在位置

MvDeviceBase.h

调用上下文或依赖对象描述

已翻开设备

函数方法

virtualintClose（）;

输入

参数代码/名称

数据类型

参数说明

无

无

无

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

成功，返回MV_OK；失败，返回错误码

处理过程

断开设备连接，释放独占权限

备注

无

例如

intnRet=MyDevice->Close（）;

if（MV_OK!

=nRet）

{

printf（"warning:

Closefail[%x]\n",nRet）;

}

3.2.3StartGrabbing

功能说明

开场采集图像

接口所在位置

MvDeviceBase.h

调用上下文或依赖对象描述

已翻开设备

函数方法

virtualintClose（）;

输入

参数代码/名称

数据类型

参数说明

无

无

无

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

成功，返回MV_OK；失败，返回错误码

处理过程

控制设备按照指定的像素格式和方式开场采集图像

备注

无

例如

intnRet=MyDevice->StartGrabbing（）;

if（MV_OK!

=nRet）

{

printf（"error:

StartGrabbing[%x]\n",nRet）;

break;

}

3.2.4StopGrabbing

功能说明

停顿采集图像

接口所在位置

MvDeviceBase.h

调用上下文或依赖对象描述

已开场采集图像

函数方法

virtualintClose（）;

输入

参数代码/名称

数据类型

参数说明

无

无

无

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

成功，返回MV_OK；失败，返回错误码

处理过程

控制设备停顿采集数据

备注

无

例如

intnRet=MyDevice->StopGrabbing（）;

if（MV_OK!

=nRet）

{

printf（"warning:

StopGrabbingfail[%x]\n",nRet）;

}

3.2.5GetGenICamXML

功能说明

获取设备的XML文件

接口所在位置

MvDeviceBase.h

调用上下文或依赖对象描述

已开启设备

函数方法

virtualintGetGenICamXML（unsignedchar*pData,unsignedintnDataSize,unsignedint*pnDataLen）;

输入

参数代码/名称

数据类型

参数说明

pData

unsignedchar*

待拷入数据的缓存地址

nDataSize

unsignedint

缓存大小

输出

参数代码/名称

数据类型

参数说明

pnDataLen

unsignedint*

输出的XML文件数据长度

返回值

成功，返回MV_OK；失败，返回错误码

处理过程

从设备读取XML文件，并输出

备注

当pData为NULL或nDataSize比实际的xml文件小时，不拷贝数据，由pnDataLen返回xml文件大小；

当pData为有效缓存地址，且缓存足够大时，拷贝完整数据，并由pnDataLen返回xml文件大小。

例如

unsignedintnXMLDataLen=0;

intnRet=MyDevice->GetGenICamXML（pXMLBuf,MAX_XML_FILE_SIZE,&nXMLDataLen）;

if（MV_OK!

=nRet||nXMLDataLen>MAX_XML_FILE_SIZE）

{

printf（"error:

GetGenICamXMLfailed!

[%x]\n",nRet）;

break;

}

3.2.6GetTlProxy

功能说明

获取GenICam使用的传输层代理类

接口所在位置

MvDeviceBase.h

调用上下文或依赖对象描述

已创立设备实例，已翻开设备

函数方法

virtualTlProxyGetTlProxy（）;

输入

参数代码/名称

数据类型

参数说明

无

无

无

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

成功，返回传输层代理；失败，返回NULL

处理过程

创立传输层代理类，部实现共享设备的独占权限

备注

无

例如

TlProxym_pMyPortTl=MyDevice->GetTlProxy（）;

if（NULL==m_pMyPortTl）

{

printf（"error:

getgigetransportlayerfailed!

\n"）;

break;

}

3.2.7GetOneFrame

功能说明

获取一帧图像数据

接口所在位置

MvDeviceBase.h

调用上下文或依赖对象描述

已创立设备实例，已翻开设备，已开启抓图

函数方法

virtualintGetOneFrame（unsignedchar*pData,unsignedintnDataSize,MV_FRAME_OUT_INFO*pFrameInfo）;

输入

参数代码/名称

数据类型

参数说明

pData

unsignedchar*

待拷入数据的缓存地址

nDataSize

unsignedint

缓存大小

输出

参数代码/名称

数据类型

参数说明

pFrameInfo

MV_FRAME_OUT_INFO*

输出的帧信息

返回值

成功，返回MV_OK；失败，返回错误码

处理过程

获取设备采集的图像数据，按照指定的像素格式输出

备注

该接口为主动式获取帧数据，上层应用程序需要根据帧率，控制好调用该接口的频率

例如

intnRet=MyDevice->GetOneFrame（g_pFrameBuf,MAX_BUF_SIZE,&stInfo）;

if（MV_OK!

=nRet）

{

Sleep（10）;

}

else

{

SR_UpdateFrameData（hRenderHandle,g_pFrameBuf,stInfo.nWidth,stInfo.nHeight,0）;

SR_Display（hRenderHandle,0,display）;

}

3.3GenApi

3.3.1_LoadXMLFromFile

功能说明

加载设备XML文件

接口所在位置

NodeMapRef.h

调用上下文或依赖对象描述

已创立设备实例，已翻开设备，已开启抓图

函数方法

void_LoadXMLFromFile（GenICam:

:

gcstringFileName）;

输入

参数代码/名称

数据类型

参数说明

FileName

GenICam:

:

gcstring

xml文件路径

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

无

处理过程

加载设备提供的xml文件

备注

该方法需要接收异常

例如

odeMapRef*m_Camera=newodeMapRef;

try

{

//加载xml

m_Camera->_LoadXMLFromFile（"testdevice.xml"）;

//导入传输层代理类，连接设备

m_Camera->_Connect（（IPort*）m_pMyPortTl,"Device"）;

//获取指定字段对应的节点

CIntegerPtrptrNode=m_Camera->_GetNode（"Width"）;

if（NULL==ptrNode）

{

printf（"error:

m_Camera->_GetNodefail!

\n"）;

break;

}

//获取指定字段的值

intnValue=ptrNode->GetValue（）;

printf（"getvalue[%x]\n",nValue）;

//设定指定字段的值

nValue=1280;

ptrNode->SetValue（nValue）;

printf（"setvalue[%x]\n",nValue）;

}

catch（...）

{

printf（"warning:

GenICamXMLmoduleerror!

\n"）;

}

3.3.2_Connect

功能说明

导入传输层，连接设备

接口所在位置

NodeMapRef.h

调用上下文或依赖对象描述

已成功加载xml文件，已获取到传输层代理类

函数方法

virtualbool_Connect（IPort*pPort,constGenICam:

:

gcstring&PortName）const;

输入

参数代码/名称

数据类型

参数说明

pPort

IPort*

传输层代理类

PortName

constGenICam:

:

gcstring&

端口名称

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

无

处理过程

略

备注

该方法需要接收异常

例如

参考LoadXMLFromFile方法的例如代码

3.3.3_GetNode

功能说明

获取指定字段的节点

接口所在位置

NodeMapRef.h

调用上下文或依赖对象描述

已成功导入传输层代理类，已成功连接设备

函数方法

virtualINode*_GetNode（constGenICam:

:

gcstring&key）const;

输入

参数代码/名称

数据类型

参数说明

key

constGenICam:

:

gcstring&

字段名称

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

成功，返回指定字段的节点；失败，返回NULL，或抛出异常

处理过程

略

备注

该方法需要接收异常

例如

参考LoadXMLFromFile方法的例如代码

3.3.4GetValue

功能说明

获取指定字段的值

接口所在位置

IValue.h、Pointer.h、IInteger.h等，视类型而定

调用上下文或依赖对象描述

已成功获取节点

函数方法

virtualint64_tGetValue（）;

输入

参数代码/名称

数据类型

参数说明

无

无

无

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

成功，返回指定字段的值；失败，抛出异常

处理过程

略

备注

需要根据指定字段的类型，来确定使用的方法。

常用的有CIntegerPtr、CStringPtr、CRegisterPtr、CEnumerationPtr等，具体参照Pointer.h的定义

例如

参考LoadXMLFromFile方法的例如代码

3.3.5SetValue

功能说明

获取指定字段的值

接口所在位置

IValue.h、Pointer.h、IInteger.h等，视类型而定

调用上下文或依赖对象描述

已成功获取节点

函数方法

virtualvoidSetValue（int64_tValue）;

输入

参数代码/名称

数据类型

参数说明

Value

int64_t

设置的值

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

失败，抛出异常

处理过程

略

备注

需要根据指定字段的类型，来确定使用的方法。

常用的有CIntegerPtr、CStringPtr、CRegisterPtr、CEnumerationPtr等，具体参照Pointer.h的定义

例如

参考LoadXMLFromFile方法的例如代码

4.接口描述〔C接口〕

C接口按照逻辑功能，划分为四大模块。

4.1相机控制通用接口

4.1.1MV_CC_GetSDKVersion

功能说明

获取SDK版本号

接口所在位置

MvCameraControl.h

调用上下文或依赖对象描述

可独立随时调用

函数方法

MV_CAMCTRL_APIunsignedint__stdcallMV_CC_GetSDKVersion（）;

输入

参数代码/名称

数据类型

参数说明

无

无

无

输出

参数代码/名称

数据类型

参数说明

无

无

无

返回值

版本号：

|主|次|修正|测试|

8bits8bits8bits8bits

处理过程

把SDK部定义的当前版本号返回

备注

无

例如

unsignedintnVersion=MV_CC_GetSDKVersion（）;

4.1.2MV_CC_EnumerateTls

功能说明

枚举支持的设备类型〔传输层类型〕

接口所在位置

MvCameraCon