工业相机SDK接口设计项目说明指导书.doc

工业相机SDK接口设计阐明书 编制 审核 批准目录1.简介31.1目的及范畴31.2有关术语31.3参照资料32.分析设计52.1设计思想52.2接口构造52.3数据流分析63.接口描述（C+接口）83.1传播层工厂类83.2设备控制类113.3GenApi164.接口描述（C接口）214.1相机控制通用接口214.2XML有关接口374.3GigEVision相机特有接口414.4U3V相机特有接口435.数据构造描述445.1MV_GIGE_DEVICE_INFO （GigE设备信息）445.2MV_USB3_DEVICE_INFO （USB3设备信息）455.3MV_CC_DEVICE_INFO（相机信息统一构造体）455.4MV_FRAME_OUT_INFO（输出帧信息）465.5MV_XML_NODE_FEATURE（xml节点基本信息）476.修订记录481. 简介1.1 目的及范畴本文档目是设计一套工业相机SDK统一接口，兼容GigEVision、1394、U3V和CameraLink等原则合同。业务层软件可同步调用GenApi和这套接口，以实现对相机控制。当前版本仅支持GigEVision和U3V两种传播合同，因此重要依照GigEVisionSDK产品需求规格阐明书和USB3VisionSDK产品需求规格阐明书进行设计，此后会在此版本基本上逐渐完善。本文档预期读者是项目经理、软件详细设计者、软件开发人员、测试人员和项目管理人员等。1.2 有关术语术语/缩写含义GigEVisionGigE Vision是由自动化影像协会AIA(Automated Imaging Association)发起指定一种基于千兆以太网图像传播原则。具备传播距离长（无中继时100米）、传播效率高并可向上升级到万兆网、通信控制以便、软硬件互换性强、可靠性高等长处，是将来数字图像领域重要接口原则，必将被越来越多商家多采用。U3V全称USB3 Vision，是一种基于USB3.0技术传播合同，传播速度快。SDK应用软件开发包。GenICam通用相机接口，属于上层应用开发通用接口合同。GenApiGenICam相机接口某些1.3 参照资料1. GigEVisionSDK产品需求规格阐明书.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设计一方面考虑是支持各种相机合同，提取共性后设计通用接口和构造体，使得上层应用软件不需要关怀详细相机合同。另一方面要支持GenICam，把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接口分为四个方向：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其她功能接口前，需要先调用此接口函数办法staticCTlFactory&GetInstance();输入参数代码/名称数据类型参数阐明无无无输出参数代码/名称数据类型参数阐明无无无返回值返回传播层工厂单件解决过程把工厂内部定义静态成员单件实例返回备注无示例CTlFactory&tlFactory = CTlFactory:GetInstance();3.1.2 EnumerateTls功能阐明枚举支持传播层类型接口所在位置TlFactory.h调用上下文或依赖对象描述需要先获取工厂实例函数办法staticCTlFactory&GetInstance();输入参数代码/名称数据类型参数阐明无无无输出参数代码/名称数据类型参数阐明无无无返回值返回支持传播层类型解决过程略备注无示例/ 2.枚举支持传播层类型unsignedintnSupportedTls = tlFactory.EnumerateTls();if (MV_GIGE_DEVICE = (nSupportedTls&MV_GIGE_DEVICE) MyGigETest();3.1.3 EnumDevices功能阐明枚举子网内，指定传播合同相应所有设备接口所在位置TlFactory.h调用上下文或依赖对象描述需要先获取工厂实例，枚举设备获取设备信息后，可创立设备实例函数办法virtualintEnumDevices( unsignedintnTLayerType ，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，sizeof(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 );输入参数代码/名称数据类型参数阐明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功能阐明销毁设备实例及相应资源接口所在位置TlFactory.h调用上下文或依赖对象描述前提是已创立设备实例函数办法virtualintDestroyDevice( IMvDevice* );输入参数代码/名称数据类型参数阐明pDeviceIMvDevice设备实例输出参数代码/名称数据类型参数阐明无无无返回值成功，返回设备实例；失败，返回错误码解决过程释放指定设备实例内部资源，然后删除映射表内设备信息备注无示例/ 从工厂中销毁设备intnRet = tlFactory.DestroyDevice(MyDevice);if (MV_OK != nRet) printf(warning：DestroyDevice 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功能阐明关闭设备接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已打开设备函数办法virtualintClose();输入参数代码/名称数据类型参数阐明无无无输出参数代码/名称数据类型参数阐明无无无返回值成功，返回MV_OK；失败，返回错误码解决过程断开设备连接，释放独占权限备注无示例intnRet = MyDevice-Close();if (MV_OK != nRet) printf(warning：Close fail %xn，nRet);3.2.3 StartGrabbing功能阐明开始采集图像接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已打开设备函数办法virtualintClose();输入参数代码/名称数据类型参数阐明无无无输出参数代码/名称数据类型参数阐明无无无返回值成功，返回MV_OK；失败，返回错误码解决过程控制设备按照指定像素格式和方式开始采集图像备注无示例intnRet = MyDevice-StartGrabbing ();if (MV_OK != nRet) printf(error：StartGrabbing %xn，nRet);break;3.2.4 StopGrabbing功能阐明停止采集图像接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已开始采集图像函数办法virtualintClose();输入参数代码/名称数据类型参数阐明无无无输出参数代码/名称数据类型参数阐明无无无返回值成功，返回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，unsignedintnDataSize，unsignedint* pnDataLen);输入参数代码/名称数据类型参数阐明pDataunsigned char*待拷入数据缓存地址nDataSizeunsigned int缓存大小输出参数代码/名称数据类型参数阐明pnDataLenunsigned int*输出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 | nXMLDataLenMAX_XML_FILE_SIZE) printf(error：GetGenICamXML failed！%xn，nRet);break;3.2.6 GetTlProxy功能阐明获取GenICam使用传播层代理类接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已创立设备实例，已打开设备函数办法virtualTlProxyGetTlProxy();输入参数代码/名称数据类型参数阐明无无无输出参数代码/名称数据类型参数阐明无无无返回值成功，返回传播层代理；失败，返回NULL解决过程创立传播层代理类，内部实现共享设备独占权限备注无示例TlProxym_pMyPortTl = MyDevice-GetTlProxy();if (NULL = m_pMyPortTl) printf(error：get gige transport layer failed!n);break;3.2.7 GetOneFrame功能阐明获取一帧图像数据接口所在位置MvDeviceBase.h调用上下文或依赖对象描述已创立设备实例，已打开设备，已启动抓图函数办法virtualintGetOneFrame(unsignedchar * pData ，unsignedintnDataSize，MV_FRAME_OUT_INFO* pFrameInfo);输入参数代码/名称数据类型参数阐明pDataunsigned char*待拷入数据缓存地址nDataSizeunsigned int缓存大小输出参数代码/名称数据类型参数阐明pFrameInfoMV_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.3 GenApi3.3.1 _LoadXMLFromFile功能阐明加载设备XML文献接口所在位置NodeMapRef.h调用上下文或依赖对象描述已创立设备实例，已打开设备，已启动抓图函数办法void_LoadXMLFromFile(GenICam:gcstringFileName);输入参数代码/名称数据类型参数阐明FileNameGenICam:gcstringxml 文献途径输出参数代码/名称数据类型参数阐明无无无返回值无解决过程加载设备提供xml文献备注该办法需要接受异常示例CNodeMapRef* m_Camera = newCNodeMapRef;try/ 加载xmlm_Camera-_LoadXMLFromFile(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;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*传播层代理类PortNameconst GenICam:gcstring&端口名称输出参数代码/名称数据类型参数阐明无无无返回值无解决过程略备注该办法需要接受异常示例参照LoadXMLFromFile办法示例代码3.3.3 _GetNode功能阐明获取指定字段节点接口所在位置NodeMapRef.h调用上下文或依赖对象描述已成功导入传播层代理类，已成功连接设备函数办法virtualINode* _GetNode( constGenICam:gcstring&key) const;输入参数代码/名称数据类型参数阐明keyconst GenICam:gcstring&字段名称输出参数代码/名称数据类型参数阐明无无无返回值成功，返回指定字段节点；失败，返回NULL，或抛出异常解决过程略备注该办法需要接受异常示例参照LoadXMLFromFile办法示例代码3.3.4 GetValue功能阐明获取指定字段值接口所在位置IValue.h、Pointer.h、IInteger.h等，视类型而定调用上下文或依赖对象描述已成功获取节点函数办法virtualint64_tGetValue();输入参数代码/名称数据类型参数阐明无无无输出参数代码/名称数据类型参数阐明无无无返回值成功，返回指定字段值；失败，抛出异常解决过程略备注需要依照指定字段类型，来拟定用法。惯用有CIntegerPtr、CStringPtr、CRegisterPtr、CEnumerationPtr等，详细参照Pointer.h定义示例参照LoadXMLFromFile办法示例代码3.3.5 SetValue功能阐明获取指定字段值接口所在位置IValue.h、Pointer.h、IInteger.h等，视类型而定调用上下文或依赖对象描述已成功获取节点函数办法virtualvoid SetValue(int64_tValue);输入参数代码/名称数据类型参数阐明Valueint64_t设立值输出参数代码/名称数据类型参数阐明无无无返回值失败，抛出异常解决过程略备注需要依照指定字段类型，来拟定用法。惯用有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内部定义当前版本号返回备注无示例unsignedintnVersion = MV_CC_GetSDKVersion();4.1.2 MV_CC_EnumerateTls功能阐明枚举支持设备类型（传播层类型）接口所在位置MvCameraControl.h调用上下文或依赖对象描述可独立随时调用函数办法MV_CAMCTRL_APIint_stdcallMV_CC_EnumerateTls ();输入参数代码/名称数据类型参数阐明无无无输出参数代码/名称数据类型参数阐明无无无返回值支持传播层类型解决过程备注无示例intnSupportedTls = MV_CC_EnumerateTls();4.1.3 MV_CC_EnumDevices功能阐明设备枚举接口所在位置MvCameraControl.h调用上下文或依赖对象描述已成功加载SDK函数办法MV_CAMCTRL_APIint_stdcallMV_CC_EnumDevices(INunsignedintnTLayerType，IN OUTMV_CC_DEVICE_INFO_LIST* pstDevList);输入参数代码/名称数据类型参数阐明nTLayerTypeunsigned int相机合同类型输出参数代码/名称数据类型参数阐明pstDevListMV_CC_DEVICE_INFO_LIST*枚举到设备信息列表指针返回值无解决过程依照输入相机合同，把发现设备信息保存到设备列表pstDevList中备注无示例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 %xn，nRet);return 1;4.1.4 MV_CC_CreateHandle功能阐明创立句柄接口所在位置MvCameraControl.h调用上下文或依赖对象描述无函数办法MV_CAMCTRL_APIint_stdcallMV_CC_CreateHandle(OUTvoid * handle，INconst MV_CC_DEVICE_INFO* pstDevInfo);输入参数代码/名称数据类型参数阐明pstDevInfoMV_CC_DEVICE_INFO*设备信息输出参数代码/名称数据类型参数阐明handlevoid *句柄返回值成功，返回MV_OK；失败，返回错误码解决过程创立库内部必要资源和初始化内部模块备注无示例4.1.5 MV_CC_DestroyHandle功能阐明销毁句柄接口所在位置MvCameraControl.h调用上下文或依赖对象描述已创立有效句柄函数办法MV_CAMCTRL_APIint_stdcallMV_CC_DestroyHandle(void * handle);输入参数代码/名称数据类型参数阐明handlevoid *句柄输出参数代码/名称数据类型参数阐明无无无返回值成功，返回MV_OK；失败，返回错误码解决过程释放资源备注无示例4.1.6 MV_CC_IsDeviceAccessible功能阐明设备与否可访问接口所在位置MvCameraControl.h调用上下文或依赖对象描述已创立句柄函数办法MV_CAMCTRL_APIbool_stdcallMV_CC_IsDeviceAccessible (INvoid * handle，MV_CC_DEVICE_INFO* pstDevInfo，unsignedintnAccessMode);输入参数代码/名称数据类型参数阐明handlevoid *句柄pstDevInfoMV_CC_DEVICE_INFO设备信息nAccessModeunsigned int访问类型输出参数代码/名称数据类型参数阐明无无无返回值true或false解决过程读取设备CCP寄存器值，判断当前状态与否具备某种访问权限。备注无示例4.1.7 MV_CC_OpenDevice功能阐明打开设备接口所在位置MvCameraControl.h调用上下文或依赖对象描述已创立有效句柄函数办法MV_CAMCTRL_APIint_stdcallMV_CC_OpenDevice(IN void* handle，INunsigned int nPrivilegeMode = MV_ExclusivePrivilege,INunsigned short nSwitchoverKey = 0);输入参数代码/名称数据类型参数阐明handlevoid *句柄nPrivilegeModeunsigned int设备访问模式，默认独占模式nSwitchoverKeyunsigned short切换权限时密钥，默认无输出参数代码/名称数据类型参数阐明无无无返回值成功，返回MV_OK；失败，返回错误码解决过程依照设立设备参数，找到相应设备，连接。备注无示例4.1.8 MV_CC_CloseDevice功能阐明关闭设备接口所在位置MvCameraControl.h调用上下文或依赖对象描述已打开设备函数办法MV_CAMCTRL_APIint_stdcallMV_CC_CloseDevice (void * handle);输入参数代码/名称数据类型参数阐明handlevoid *句柄输出参数代码/名称数据类型参数阐明无无无返回值成功，返回MV_OK；失败，返回错误码解决过程断开相机连接，释放资源备注无示例4.1.9 MV_CC_StartGrabbing功能阐明启动抓图接口所在位置MvCameraControl.h调用上下文或依赖对象描述已打开设备函数办法MV_CAMCTRL_APIint_stdcallMV_CC_StartGrabbing(void * handle);输入参数代码/名称数据类型参数阐明handlevoid *句柄输出参数代码/名称数据类型参数阐明无无无返回值成功，返回MV_OK；失败，返回错误码解决过程发送启动抓图命令给相机，启动接受数据。备注无示例4.1.10 MV_CC_StopGrabbing功能阐明停止抓图接口所在位置MvCameraControl.h调用上下文或依赖对象描述已启动抓图函数办法MV_CAMCTRL_APIint_stdcallMV_CC_StopGrabbing(void * handle);输入参数代码/名称数据类型参数阐明handlevoid *句柄输出参数代码/名称数据类型参数阐明无无无返回值成功，返回MV_OK；失败，返回错误码解决过程发送停止抓图命令给相机，停止接受数据。备注无示例4.1.11 MV_CC_GetOneFrame功能阐明获取一帧图像数据接口所在位置MvCameraControl.h调用上下文或依赖对象描述已启动抓图函数办法MV_CAMCTRL_APIint_stdcallMV_CC_GetOneFrame(void * handle，IN OUTunsigned char * pData ，INunsigned int nDataSize，IN OUTMV_FRAME_OUT_INFO* pFrameInfo);输入参数代码/名称数据类型参数阐明handlevoid *句柄pDataunsigned char*待输出数据缓存nDataSizeunsigned int缓存大小输出参数代码/名称数据类型参数阐明pDataunsigned char*输出数据缓存pFrameInfoMV_FRAME_OUT_INFO当前一帧图像信息返回值成功，返回MV_OK；失败，返回错误码解决过程从相机或内部缓存链表中获取一帧图像备注无示例4.1.12 MV_CC_GetImageInfo功能阐明获取相机图像基本信息接口所在位置MvCameraControl.h调用上下文或依赖对象描述已连接设备函数办法MV_CAMCTRL_APIint_stdcallMV_CC_GetImageInfo(void * handle，IN OUTMV_IMAGE_BASIC_INFO* pstInfo);输入参数代码/名称数据类型参数阐明handlevoid *句柄pstInfoMV_IMAGE_BASIC_INFO待输出信息构造输出参数代码/名称数据类型参数阐明pstInfoMV_IMAGE_BASIC_INFO图像基本信息返回值成功，返回MV_OK；失败，返回错误码解决过程访问设备，获取当前设立备注无示例4.1.13 MV_CC_SetWidth功能阐明设立相机图像宽度接口所在位置MvCameraControl.h调用上下文或依赖对象描述已连接设备函数办法MV_CAMCTRL_APIint_stdcallMV_CC_SetWidth (void * handle，IN OUTunsigned intnValue);输入参数代码/名称数据类型参数阐明handlevoid *句柄nValueunsigned int宽值输出参数代码/名称数据类型参数阐