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

1、工业相机SDK接口设计说明书doc工业相机SDK接口设计说明书 编制 审核 批准1. 简介1.1 目标及范围本文档的目的是设计一套工业相机SDK的统一接口，兼容GigEVision、1394、U3V和CameraLink等标准协议。业务层软件可同时调用GenApi和这套接口，以实现对相机的控制。当前版本仅支持GigEVision和U3V两种传输协议，所以主要根据GigEVisionSDK产品需求规格说明书和USB3VisionSDK产品需求规格说明书进行设计，今后会在此版本的基础上逐渐完善。本文档的预期读者是项目经理、软件详细设计者、软件开发人员、测试人员和项目管理人员等。1.2 相关术语术语

2、/缩写含义GigEVisionGigE Vision是由自动化影像协会AIA(Automated Imaging Association)发起指定的一种基于千兆以太网的图像传输的标准。具有传输距离长（无中继时100米）、传输效率高并可向上升级到万兆网、通信控制方便、软硬件互换性强、可靠性高等优点，是未来数字图像领域的主要接口标准，必将被越来越多的商家多采用。U3V全称USB3 Vision，是一种基于USB3.0技术的传输协议，传输速度快。SDK应用软件开发包。GenICam通用相机接口，属于上层应用开发的通用接口协议。GenApiGenICam的相机接口部分1.3 参考资料1. GigEVi

3、sionSDK产品需求规格说明书.doc .2. USB3VisionSDK产品需求规格说明书.doc.3. GenICam_Standard_v2_0.pdf.4. eBUS SDK C+ API.chm.5. FlyCapture2 C Documentation.chm.6. FlyCapture2SDKHelp.chm7. JAI SDK.chm8. ImagingSource.chm.9. PylonCSDK.chm2. 分析设计2.1 设计思想工业相机SDK的设计首先考虑的是支持多个相机协议，提取共性后设计通用的接口和结构体，使得上层应用软件不需要关心具体的相机协议。其次要支持Ge

4、nICam，把GenApi引入作为SDK接口的一部分。但由于GenApi是C+类形式的接口，为保持接口风格的一致性和用户的需求，我们也需要设计一套C+接口。另外，为简化SDK的调用流程和上层软件的开发难度，我们还要设计一套C接口。最后遵循SDK的易扩展性设计了这套SDK。2.2 接口结构接口分C+和C两套：2.2.1 C+接口当前版本主要包含3个类：1. 传输层工厂类，通过该类获取单件实例，然后枚举在线设备，以及创建和销毁设备；2. 设备控制类，通过该类控制指定的设备，包括开启停止设备、获取图像等；3. GenApi，通过该模块可以获取和设置相机参数。2.2-1接口结构图2.2.2 C接口C接

5、口分为四个方向：1. 相机控制通用接口，包含创建句柄、连接设备、获取图像数据等；2. XML相关接口，内部封装了GenICam，实现XML解析和所有相机参数节点的获取及设置；3. GigEVision相机特有的接口，如强制IP、设置网络驱动模式等；4. U3V相机特有的接口。2.3 数据流分析2.3-1数据流图3. 接口描述（C+接口）C+接口以类形式提供，所以接口描述也按照类来划分，可划分为三大模块：3.1 传输层工厂类3.1.1 GetInstance功能说明获取传输层工厂单件接口所在位置TlFactory.h调用上下文或依赖对象描述调用SDK的其他功能接口前，需要先调用此接口函数方法st

6、aticCTlFactory&GetInstance();输入参数代码/名称数据类型参数说明无无无输出参数代码/名称数据类型参数说明无无无返回值返回传输层工厂单件处理过程把工厂内部定义的静态成员单件实例返回备注无示例 CTlFactory&tlFactory = CTlFactory:GetInstance();3.1.2 EnumerateTls功能说明枚举支持的传输层类型接口所在位置TlFactory.h调用上下文或依赖对象描述需要先获取工厂实例函数方法staticCTlFactory&GetInstance();输入参数代码/名称数据类型参数说明无无无输出参数代码/名称数据类型参数说明无

7、无无返回值返回支持的传输层类型处理过程略备注无示例 / 2.枚举支持的传输层类型unsignedintnSupportedTls = tlFactory.EnumerateTls();if (MV_GIGE_DEVICE = (nSupportedTls&MV_GIGE_DEVICE) MyGigETest();3.1.3 EnumDevices功能说明枚举子网内，指定的传输协议对应的所有设备接口所在位置TlFactory.h调用上下文或依赖对象描述需要先获取工厂实例，枚举设备获取设备信息后，可创建设备实例函数方法virtualintEnumDevices( unsignedintnTLaye

8、rType , MV_CC_DEVICE_INFO_LIST&stDevList );输入参数代码/名称数据类型参数说明nTLayerTypeunsigned int传输层协议类型stDevListMV_CC_DEVICE_INFO_LIST&设备信息列表输出参数代码/名称数据类型参数说明stDevListMV_CC_DEVICE_INFO_LIST&设备信息列表返回值成功，返回MV_OK；失败，返回错误码处理过程由指定的协议类型，广播相应的消息，发现设备并记录设备信息备注无示例 MV_CC_DEVICE_INFO_LISTstDevList;memset(&stDevList, 0, siz

9、eof(MV_CC_DEVICE_INFO_LIST);intnRet = tlFactory.EnumDevices(MV_GIGE_DEVICE, stDevList);if (MV_OK != nRet) printf(error: EnumDevices %xn, nRet);return 1;3.1.4 CreateDevice功能说明创建设备实例接口所在位置TlFactory.h调用上下文或依赖对象描述需要先获取设备信息后，才能创建设备实例函数方法virtualIMvDevice* CreateDevice( constMV_CC_DEVICE_INFO&device );输入参数

10、代码/名称数据类型参数说明deviceconst MV_CC_DEVICE_INFO&指定设备的信息输出参数代码/名称数据类型参数说明无无无返回值成功，返回设备实例；失败，返回NULL处理过程由输入的设备信息，创建相应类型的设备对象备注无示例 / 由设备信息创建设备实例CMvGigEDevice* MyDevice =dynamic_cast(tlFactory.CreateDevice(*(stDevList.pDeviceInfoi);if (NULL = MyDevice)printf(error: CreateDevicen);break;3.1.5 DestroyDevice功能说明

11、销毁设备实例及相应的资源接口所在位置TlFactory.h调用上下文或依赖对象描述前提是已创建设备实例函数方法virtualintDestroyDevice( IMvDevice* );输入参数代码/名称数据类型参数说明pDeviceIMvDevice设备实例输出参数代码/名称数据类型参数说明无无无返回值成功，返回设备实例；失败，返回错误码处理过程释放指定设备实例的内部资源，然后删除映射表内的设备信息备注无示例/ 从工厂中销毁设备intnRet = tlFactory.DestroyDevice(MyDevice);if (MV_OK != nRet) printf(warning: Dest

12、royDevice fail %xn, nRet); 3.2 设备控制类3.2.1 Open功能说明打开设备接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已创建设备实例函数方法virtualintOpen();输入参数代码/名称数据类型参数说明无无无输出参数代码/名称数据类型参数说明无无无返回值成功，返回MV_OK；失败，返回错误码处理过程连接设备，获取设备独占权限备注无示例 intnRet = MyDevice-Open();if (MV_OK != nRet) printf(error: Open %xn, nRet);continue;3.2.2 Close功能说明关闭

13、设备接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已打开设备函数方法virtualintClose();输入参数代码/名称数据类型参数说明无无无输出参数代码/名称数据类型参数说明无无无返回值成功，返回MV_OK；失败，返回错误码处理过程断开设备连接，释放独占权限备注无示例 intnRet = MyDevice-Close();if (MV_OK != nRet) printf(warning: Close fail %xn, nRet);3.2.3 StartGrabbing功能说明开始采集图像接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已打开设备函数方法

14、virtualintClose();输入参数代码/名称数据类型参数说明无无无输出参数代码/名称数据类型参数说明无无无返回值成功，返回MV_OK；失败，返回错误码处理过程控制设备按照指定的像素格式和方式开始采集图像备注无示例 intnRet = MyDevice-StartGrabbing ();if (MV_OK != nRet) printf(error: StartGrabbing %xn, nRet);break;3.2.4 StopGrabbing功能说明停止采集图像接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已开始采集图像函数方法virtualintClose()

15、;输入参数代码/名称数据类型参数说明无无无输出参数代码/名称数据类型参数说明无无无返回值成功，返回MV_OK；失败，返回错误码处理过程控制设备停止采集数据备注无示例 intnRet = MyDevice-StopGrabbing ();if (MV_OK != nRet) printf(warning: StopGrabbing fail %xn, nRet);3.2.5 GetGenICamXML功能说明获取设备的XML文件接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已开启设备函数方法virtualintGetGenICamXML(unsignedchar* pData,

16、 unsignedintnDataSize, unsignedint* pnDataLen);输入参数代码/名称数据类型参数说明pDataunsigned char*待拷入数据的缓存地址nDataSizeunsigned int缓存大小输出参数代码/名称数据类型参数说明pnDataLenunsigned int*输出的XML文件数据长度返回值成功，返回MV_OK；失败，返回错误码处理过程从设备读取XML文件，并输出备注当pData为NULL或nDataSize比实际的xml文件小时，不拷贝数据，由pnDataLen返回xml文件大小；当pData为有效缓存地址，且缓存足够大时，拷贝完整数据，并

17、由pnDataLen返回xml文件大小。示例 unsignedintnXMLDataLen = 0;intnRet = MyDevice-GetGenICamXML(pXMLBuf,MAX_XML_FILE_SIZE, &nXMLDataLen);if (MV_OK != nRet | nXMLDataLenMAX_XML_FILE_SIZE) printf(error: GetGenICamXML failed! %xn, nRet);break;3.2.6 GetTlProxy功能说明获取GenICam使用的传输层代理类接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已创建

18、设备实例，已打开设备函数方法virtualTlProxyGetTlProxy();输入参数代码/名称数据类型参数说明无无无输出参数代码/名称数据类型参数说明无无无返回值成功，返回传输层代理；失败，返回NULL处理过程创建传输层代理类，内部实现共享设备的独占权限备注无示例 TlProxym_pMyPortTl = MyDevice-GetTlProxy();if (NULL = m_pMyPortTl) printf(error: get gige transport layer failed!n);break;3.2.7 GetOneFrame功能说明获取一帧图像数据接口所在位置MvDevic

19、eBase.h调用上下文或依赖对象描述已创建设备实例，已打开设备，已开启抓图函数方法virtualintGetOneFrame(unsignedchar * pData , unsignedintnDataSize, MV_FRAME_OUT_INFO* pFrameInfo);输入参数代码/名称数据类型参数说明pDataunsigned char*待拷入数据的缓存地址nDataSizeunsigned int缓存大小输出参数代码/名称数据类型参数说明pFrameInfoMV_FRAME_OUT_INFO *输出的帧信息返回值成功，返回MV_OK；失败，返回错误码处理过程获取设备采集的图像数据

20、，按照指定的像素格式输出备注该接口为主动式获取帧数据，上层应用程序需要根据帧率，控制好调用该接口的频率示例 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.3 GenApi3.3.1 _Load

21、XMLFromFile功能说明加载设备XML文件接口所在位置NodeMapRef.h调用上下文或依赖对象描述已创建设备实例，已打开设备，已开启抓图函数方法void_LoadXMLFromFile(GenICam:gcstringFileName);输入参数代码/名称数据类型参数说明FileNameGenICam:gcstringxml 文件路径输出参数代码/名称数据类型参数说明无无无返回值无处理过程加载设备提供的xml文件备注该方法需要接收异常示例 CNodeMapRef* m_Camera = newCNodeMapRef;try/ 加载xmlm_Camera-_LoadXMLFromFil

22、e(testdevice.xml);/ 导入传输层代理类，连接设备m_Camera-_Connect(IPort*)m_pMyPortTl, Device);/ 获取指定字段对应的节点CIntegerPtr ptrNode = m_Camera-_GetNode(Width);if (NULL = ptrNode) printf(error: m_Camera-_GetNode fail!n);break; / 获取指定字段的值intnValue = ptrNode-GetValue();printf(get value %xn, nValue);/ 设定指定字段的值nValue = 1280

23、;ptrNode-SetValue(nValue);printf(set value %xn, nValue); catch (.) printf(warning: GenICam XML module error!n);3.3.2 _Connect功能说明导入传输层，连接设备接口所在位置NodeMapRef.h调用上下文或依赖对象描述已成功加载xml文件，已获取到传输层代理类函数方法virtualbool_Connect( IPort* pPort, constGenICam:gcstring&PortName) const;输入参数代码/名称数据类型参数说明pPortIPort*传输层代理

24、类PortNameconst GenICam:gcstring&端口名称输出参数代码/名称数据类型参数说明无无无返回值无处理过程略备注该方法需要接收异常示例 参考LoadXMLFromFile方法的示例代码3.3.3 _GetNode功能说明获取指定字段的节点接口所在位置NodeMapRef.h调用上下文或依赖对象描述已成功导入传输层代理类，已成功连接设备函数方法virtualINode* _GetNode( constGenICam:gcstring&key) const;输入参数代码/名称数据类型参数说明keyconst GenICam:gcstring&字段名称输出参数代码/名称数据类型

25、参数说明无无无返回值成功，返回指定字段的节点；失败，返回NULL，或抛出异常处理过程略备注该方法需要接收异常示例 参考LoadXMLFromFile方法的示例代码3.3.4 GetValue功能说明获取指定字段的值接口所在位置IValue.h、Pointer.h、IInteger.h等，视类型而定调用上下文或依赖对象描述已成功获取节点函数方法virtualint64_tGetValue();输入参数代码/名称数据类型参数说明无无无输出参数代码/名称数据类型参数说明无无无返回值成功，返回指定字段的值；失败，抛出异常处理过程略备注需要根据指定字段的类型，来确定使用的方法。常用的有CIntegerP

26、tr、CStringPtr、CRegisterPtr、CEnumerationPtr等，具体参照Pointer.h的定义示例 参考LoadXMLFromFile方法的示例代码3.3.5 SetValue功能说明获取指定字段的值接口所在位置IValue.h、Pointer.h、IInteger.h等，视类型而定调用上下文或依赖对象描述已成功获取节点函数方法virtualvoid SetValue(int64_tValue);输入参数代码/名称数据类型参数说明Valueint64_t设置的值输出参数代码/名称数据类型参数说明无无无返回值失败，抛出异常处理过程略备注需要根据指定字段的类型，来确定使用

27、的方法。常用的有CIntegerPtr、CStringPtr、CRegisterPtr、CEnumerationPtr等，具体参照Pointer.h的定义示例 参考LoadXMLFromFile方法的示例代码4. 接口描述（C接口）C接口按照逻辑功能，划分为四大模块。4.1 相机控制通用接口4.1.1 MV_CC_GetSDKVersion功能说明获取SDK版本号接口所在位置MvCameraControl.h调用上下文或依赖对象描述可独立随时调用函数方法MV_CAMCTRL_APIunsignedint_stdcallMV_CC_GetSDKVersion();输入参数代码/名称数据类型参数说明无无无输出参数代码/名称数据类型参数说明无无无返回值版本号：|主 |次 |修正 | 测试|8bits 8bits 8bits 8bits处理过程把SDK内部定义的当前版本号返回备注无示例 u