4.3.1 联合开发：集成HALCON第三方算子到VM工具箱的方法

描述
环境：VM4.0及以上 + VS2013
问题：有的用户在使用VisionMaster软件在开发视觉项目时，可能同时也使用HALCON，OpenCV等视觉算法库做一些图像的处理，并且希望能将HALCON等第三方算子集成到VM工具箱，能够在VM工具箱中拖拽出来，就像VisionMaster中的其他算法模块工具一样，可以通过弹出窗口配置运行参数，通过连线订阅其他模块传递的参数，设置ROI，通过图像窗口查看算法直接结果的渲染效果。实际上是可行的，VisionMaster是一个开放平台，可以接入第三方生态，这也是VisionMaster的一大亮点。这里以封装HALCON的动态阈值算子Dyn_Threshold来举例说明如何集成第三方算法库中的算子到VM工具箱中。
解答
1 开始之前的准备工作
在编写自定义算子之前，首先必须了解以下几个概念：
1.1 VM软件中所有的算法模块工具的参数调试界面都是依赖XML文件，VM软件在启动时会在加载工具的XML配置文件，根据XML配置文件配置的输入输出参数来呈现用户界面。每个算法模块的XML配置文件存放在VM安装目录下的Module(sp)文件夹内，例如，以高精度匹配为例，XML配置文件存放在下面的目录：（打开XML文件夹的快捷键方式：在VM中选中模块后，点击Ctrl+m） C:\Program Files\VisionMaster4.0.0\Applications\Module(sp)\x64\Location\IMVSHPFeatureMatchModu，其中Location是表示在工具箱的定位工具组。
1.2 算法模块的输入输出是由基础的数据类型组成，例如Int，Float，string, bool, enum类型等。
在这里插入图片描述

对应的在该模块的XML文件中，是由XML的树形节点来描述的。
在XXXAlgorithmTab.xml（XXX指代模块的名称）文件中的Tab_Run_Params（模块运行参数）中可以找到对这些运行的参数的描述。如下图所示：
在这里插入图片描述

1.3 算法模块一般都要包含ROI输入，模块是否要接受ROI输入，位置修正由XML配置决定。
在这里插入图片描述

如图所示的Blob模块，它的ROI类型，在IMVSBlobFindModuAlrorithemTab.xml配置文件有相关的Item决定，如下图所示：
在这里插入图片描述

事实上，我们并不需要非常清楚XML配置文件中的每一项对应界面上哪些元素，才能开发出自定义算法模块，我们只需要了解一个事实：XML配置决定界面上显示的内容。所以VM开发组给我们提供了一个便捷的工具来配置工具模块的输入输出配置。这个工具在VM软件工具菜单下可以找到。
在这里插入图片描述

1.4 集成自定义算法模块需要完成3个工作

通过自定义模块生成工具生成界面
生成自定义算法模块的界面需要用到C# DLL
生成自定义算法模块的算法流程需要用到的C++ DLL

定义好输入输出之后，执行生成XML，生成C++工程，生成C# 工程这3步，就初步完成了准备工作，执行了上面3个步骤，应该会生成以模块名字命名开头的3个文件夹，例如：
在这里插入图片描述

2 举例说明
我们集成一个Halcon中的算子DynThreshold到VM的图像处理工具箱中，DynThreshold算子的定义如下：

DynThreshold（ 
HObject inputImage,
HTuple darkLight, 
HTuple maskWidth, 
HTuple maskHeight,
HTuple offset, 
HTuple minArea,
HTuple maxArea, 
HTuple *area）

由于输入图像可以订阅VM流程中的图像源模块，用户输入的ROI可以从界面交互获得，所以它的输入对应在VM中的输入如下：
在这里插入图片描述

对应在VM中的输出：
在这里插入图片描述

第一步：根据上面的定义得输入输出，使用AlgorithmXMLGenerator工具生成XML文件夹，如上图1-6所示。接着生成模块参数界面的C#工程和模块算法流程的C++工程。生成工程之后会有以模块名称为前缀的3个文件夹，如上面图1-7所示。这3个文件夹，其中，DynThreshold文件夹是需要用户最终拷贝到VM的Applications\Module(sp)\x64目录下的模块类别下。
以Cs开头的文件夹，是生成界面相关资源的C#工程，我们只需要打开其中的工程，编译其中的以模块名称命名的工程即可（注意：选择Release模式，只需要编译以模块名称命名的工程，不需要编译工程名+Control的那个工程）。如图2-1所示：
在这里插入图片描述

编译完成后，将生成的模块名称+cs.dll和模块名称.pdb文件拷贝到DynThreshold文件夹中。
第二步：编写C++工程，工程是上一步自动生成的C++工程，工程名是Proj_+模块名称命名，就本例来说，就是Proj_DynThreshold工程。建议使用VS2013来编写这个工程。因为VM中使用的算子基本都是msvc2013编译器。（注意：选择Release、x64，禁用优化。）针对本例是VM联合Halcon开发算子模块，所以需要在项目中配置halcon环境，如附加包含目录，附加库目录，附加依赖项。
这一步是重头戏，算子封装的绝大部分工作量就在这一步：
不过幸运的是，开发者并不需要从头到尾了解一遍工程的源代码结构，源码的各个部分的作用，集成算子的开发者只需要关注一个Process函数即可，封装算子的代码其实就是将Process具体的实现一遍。
在这里插入图片描述

开发者需要获取的输入就在modu_input 中，比如我们要获取定制模块的订阅的图像源的图像，将此图像原始字节数据转成Halcon可以处理的HImage 格式，实现的代码如下所示：
在这里插入图片描述

我们从modu_input 拿到了Halcon可以处理的图像HObject类型的HImage, 那接着用Halcon算子处理算法流就可以了。比如使用Halcon的动态阈值，典型的代码如下所示：
在这里插入图片描述

第三步：如何获取模块的输入。自动生成的C++工程已经帮我们生成好了类库的成员变量，例如，以本例来说，定义的输入就是成员变量：
在这里插入图片描述

我们在Process中可以直接使用，当用户界面设置了某个参数，比如说最小过滤面积，通过参数配置界面设置成了1000，那么当模块执行的时候，m_nMinArea的值就会是1000。无需开发者写代码从界面去拿，这一切都是自动的。
当然这其中并没有什么高深复杂的内部机制，实际上，获取输入参数和设置输出参数，都是靠VM代理模块在后台去执行GetParam和SetParam做到的。GetParam和SetParam的代码清楚的显示了，它是如何做到这一点的。
这里摘取其中的代码片段，如下：
获取输入参数
在这里插入图片描述

设置运行参数
在这里插入图片描述

第四步：如何设置模块的输出
设置算法工具的输出主要靠下面几个接口函数：
在这里插入图片描述

我们举例说明，例如我有一个结果输出，输出的是Blob结果中最大的那个团块的面积，我们就需要用到VM_M_SetFloat这个接口函数，示例代码如下：
在这里插入图片描述

示例代码中“MaxArea”等，就是模块的XML文件中描述的算法模块的输出名称，也是这个模块的结果输出Tab页中显示的结果名称。
如果要一次性设置多个输出，可以使用VM_M_BatchSetXXX(XXX代指数据类型)
在这里插入图片描述

让我们举例说明，例如我有一个结果输出，输出的是Blob得到的最小外接矩形结果，显然这个结果是包含多种结果的，我们就需要用到VM_M_BatchSetFloat这个接口函数，示例代码如下
在这里插入图片描述

示例代码中“BlobResultRectX”等，就是模块的XML文件中描述的算法模块的输出名称，也是这个模块的结果输出Tab页中显示的结果名称。
3 调试方法
将生成好的算法模块DLL拷贝到DynThreshold文件夹中，再将DynThreshold文件夹拷贝到VM的Applications\Module(sp)\x64目录下的模块类别下。我们运行VisionMaster软件，在VM软件中加载用户自定义的模块之后，可以在VS中附加进程，这个进程是“VmModuleProxy”,附加了进程后就可以设置断点调试了。
如下图所示：
在这里插入图片描述

接着选择VmModuleProxy进程
在这里插入图片描述

如果发现调试时，发现不能命中断点，一定是没有将算法模块DLL对于的调试信息pdb文件拷贝到Module(sp)目录下的工具组目录下的算法模块目录。拷贝过去就可以命中断点了。
4 写在最后
在VM中集成第三个的算法工具，展示的是VM的开放性，VM可以集成第三方的算法，用来增强和扩展VM的能力集，这是VM一个比较好的特性。但开发者一定要注意，第三方的算法会涉及到版权和授权的问题，这个需要开发者遵循相关的版权协议及相应的法律条款，与VisionMaster算法平台无关。
问题根因