工业相机SDK接口设计说明书doc.docx
《工业相机SDK接口设计说明书doc.docx》由会员分享，可在线阅读，更多相关《工业相机SDK接口设计说明书doc.docx（51页珍藏版）》请在冰豆网上搜索。
工业相机SDK接口设计说明书doc
工业相机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文件
备注
该方法需要接收异常
示例
CNodeMapRef*m_Camera=newCNodeMapRef;
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内部定义的当前版本号返回
备注
无
示例
u
升级会员 