V5版本

Last updated: ... / Reads: 30 Edit

元芒数字 i 识别系统（WmAceKG）

Windows端 DLL 接口说明文档

Version Release v5.0.0.0

更新时间: 2023.5.12

上海元芒数字科技有限公司

[TOC]

Windows端DLL接口文档

一、文档说明

1.1 版本说明

文档版本号	SDK 版本号	发布日期	更新内容
v5.0.0.0	v5.0.0.0	2023.05.12	发布新版本

1.2 ⽂档概述

此文档用于说明元芒数字（WM）i 识别（AceKG）系统(简称 WmAceKG)的 Windows 系统接口，需配合元芒数字的智能摄像头设备使用，集成相关软件包，以实现相关功能。

1.3 术语定义及说明

术语说明

DLL：集成在 Windows 端的软件包；
商品ID：用来唯一标识商品信息，可以是商品条码plu、商品code、商品id等，但在接口中要统一使用。

本文中所有传输内容无特殊说明均使用 ANSI 编码;
本文中的 DLL 适用于操作系统 Windows 7以上的版本，支持32或64位操作系统

二、调用方法说明

2.1 集成方法说明

将压缩包内所有 DLL 放在程序可执行目录下即可
客户端加载WmAceKG-x86.dll (32位)
加载DLL中的函数即可
我方提供调用 demo ：下载链接：https://ai-wmdigit.oss-cn-shanghai.aliyuncs.com/windows%E7%89%88%E6%9C%ACdll%E5%AF%B9%E6%8E%A5%E7%A4%BA%E4%BE%8B%E4%BB%A3%E7%A0%81/%E5%85%83%E8%8A%92windows%E7%89%88dll%E5%90%84%E8%AF%AD%E8%A8%80%E5%AF%B9%E6%8E%A5%E7%A4%BA%E4%BE%8B%E4%BB%A3%E7%A0%81.zip

2.2 接口调用流程描述

初始化dll接口：Init
设备初次使用，注册 pos 机：initpos
设置摄像头序号 SetCameraId
获取秤盘裁剪坐标 GetScaleSetting 如果为空进入第5 否则进入第7
首先调用 GetScaleBitmap 获得一张原图根据原图裁剪左上角 xy 坐标和长宽
设置秤盘裁剪坐标 SaveScaleSetting
调用AutoDetect 接口（其他说明放到对应的接口中了）
用户做出选择后，调用setFeedBack 接口，优化算法

2.3 接口时序图

三、接⼝说明

所有接口皆返回错误码不为0的情况皆是错误

具体业务返回值都在参数里面作为引用传递最后修改传入参数为最终结果

设备初始化

3.1 Init （初始化）

使用场景：初始化dll所需参数
函数原型：在使用dll时(在程序最开始的时候首先调用此接口)，先完成初始化，再调用其他接口
```
Init() 
```
请求参数：

请求参数必填类型描述
返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int Init();

Init();

3.2 InitPos （注册 POS 接口）

使用场景：初始化识别所需要的内容，以及验证sncode是否正确，该接口需要连接互联网。注册成功后则无需再次调用。
(注)：posCode:3-30位，不可重复

函数原型：

InitPos(char* tenant,char* posCode,char* snNo)

请求参数：

请求参数必填类型描述

tenant Y char* 租户代码，线上申请后邮件发送

posCode Y char* pos机的编号，可自己编辑，一旦对应不可更改

snNo Y char* sdk 码必填
返回值：0代表成功其他皆为失败

请求参数	必填	类型	描述
tenant	Y	char*	租户代码，线上申请后邮件发送
posCode	Y	char*	pos机的编号，可自己编辑，一旦对应不可更改
snNo	Y	char*	sdk 码必填

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int InitPos(StringBuilder tenant, StringBuilder posCode, StringBuilder snNo);

// 关于这几个参数 请咨询运维人员
StringBuilder tenant = new StringBuilder("demo");
StringBuilder posCode = new StringBuilder("zyx");
StringBuilder snNo = new StringBuilder("123");
InitPos(tenant, posCode, snNo);

3.3 SetCameraId (初始化摄像头)

使用场景：初始化ai摄像头设备，参数传 0 即可。
(注)：当close()之后，都必须再次调用此接口。
函数原型：

SetCameraId (int num)

参数说明：

请求参数	必填	类型	描述
num	Y	int	0 即可

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int SetCameraId(int num);

SetCameraId(0);

3.4 GetScaleBitmap (初始化秤盘信息-获取全景照片)

使用场景：AI识别的是秤盘上的物品，需要提前标定好秤盘的位置，在标定秤盘位置前，获取全景照片准备开始标定（裁剪）秤盘。

！!注意：调用之前，请设置摄像头序号。

如果未设置裁剪坐标，不会返回裁剪后的cropPath，只会返回原图路径。

如果设置了裁剪坐标，原图和裁剪后的图都会返回
函数原型：

GetScaleBitmap (char* rawPath,char* cropPath);

参数说明：

请求参数	必填	类型	描述
rawPath	Y	char*	原图路径该值为引用传递调用后会修改成最终结果
cropPath	Y	char*	裁剪后的图片路径该值为引用传递调用后会修改成最终结果

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int GetScaleBitmap(StringBuilder path1, StringBuilder path2);

// 原图路径
StringBuilder path1 = new StringBuilder(128);
// 裁剪后的图片路径
StringBuilder path2 = new StringBuilder(128);
int code = GetScaleBitmap(path1, path2);

3.5 SaveScaleSetting (初始化秤盘信息-标定秤盘并保存坐标信息)

使用场景：AI识别的是秤盘上的物品，在识别商品时，AI只识别标定内的物品，该接口用来传递秤盘位置信息。
秤盘必须为矩形，推荐宽高比例为4:3，比例为4：3的时识别的精度最高，识别最准。默认像素为640*480,所以x+width <640 y+height <480 并且 x！=0，y！=0。
函数原型：

SaveScaleSetting (int x,int y,int width,int height);

参数说明：

请求参数	必填	类型	描述
x	Y	int	左上角 x 坐标值
y	Y	int	左上角 y 坐标值
width	Y	int	宽度
height	Y	int	高度

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int SaveScaleSetting(int x, int y, int width, int height);

SaveScaleSetting(1, 1, 512, 384);

3.6 GetScaleSetting (判断秤盘是否已标定）

使用场景：AI识别的是秤盘上的物品，在识别商品时，会提前判断本次秤盘是否已被标定，如果没有被标定，请重新初始化秤盘。
函数原型：

GetScaleSetting(int& x,int& y,int& width,int& height);

参数说明：

请求参数	必填	类型	描述
x	Y	int&	左上角 x 坐标值该值为引用传递调用后会修改成最终结果
y	Y	int&	左上角 y 坐标值该值为引用传递调用后会修改成最终结果
width	Y	int&	宽度该值为引用传递调用后会修改成最终结果
height	Y	int&	高度该值为引用传递调用后会修改成最终结果

返回值：0代表成功, 其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int GetScaleSetting(ref int x, ref int y, ref int width, ref int height);

int x = 0;
int y = 0;
int width = 0;
int height = 0;
int code = GetScaleSetting(ref x, ref y, ref width, ref height);

3.7 AutoDetect （商品识别）

使用场景：开始识别商品，调用此接口；建议在重量触发时，秤盘稳定读数且读数>30g后调用
函数原型：

AutoDetect(char* productcode, char* sessionId)

请求参数：

请求参数	必填	类型	描述
Productcode	Y	char*	最匹配的商品代码用逗号分割该值为引用传递调用后会修改成最终结果
sessionId	Y	char*	打称记录的 id 该 id 随机生成该值为引用传递调用后会修改成最终结果

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int AutoDetect(StringBuilder productcode, StringBuilder sessionId);

// 商品代码
StringBuilder productCodes = new StringBuilder(500);
StringBuilder sessionId = new StringBuilder(20);
AutoDetect(productCodes, sessionId);

3.8 SetFeedBack （保存识别结果)

使用场景：识别后传入选中结果(正确商品的code)和是否选中(hit)，调用此接口，用于优化算法。
关于hit字段详解：

第一次使用dll 里面是没有任何商品信息的这个时候你调用AutoDetect会返回你一个空字符串你需要自己搜索一个商品然后使用保存函数 hit=false

再次使用AutoDetect这个时候会把你上次保存的商品代码返回因为本次识别,已经将商品对应的代码返回所以使用保存函数的时候 hit=true

总结:商品代码AutoDetect只返回一个正确结果就是true,其他都为false

函数原型：

SetFeedBack (const char* code, char* sessionId, bool hit,char* productName)

参数说明：

请求参数	必填	类型	描述
code	Y	const char*	选择的商品代码
sessionId	Y	char*	打称记录 Id
hit	Y	bool	是否命中
productName	Y	char*	商品名称

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int SetFeedBack(byte[] code, StringBuilder sessionId,bool hit,byte[] productName);

SetFeedBack(System.Text.Encoding.UTF8.GetBytes("00174"), sessionId, false,System.Text.Encoding.UTF8.GetBytes("FF散称商品"));

3.9 SetNoRecommend（删除商品学习结果）

使用场景：删除商品学习结果
函数原型：

SetNoRecommend (const char* code)

参数说明：

请求参数	必填	类型	描述
code	Y	const char*	商品代码

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int SetNoRecommend(byte[] code);

SetNoRecommend(System.Text.Encoding.UTF8.GetBytes("00174"));

3.10 ImportData（导入学习数据)

使用场景：如果拥有另一台机器已经学习完毕可以使用该函数将学习数据导入

导入之后必须重启程序导入的文件名不能带有中文字符
函数原型：

ImportData(char* path);

参数说明：

请求参数	必填	类型	描述
path	Y	const char*	导入的文件路径

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int ImportData(StringBuilder path);

StringBuilder path = new StringBuilder(20);
path = "/xxxx";
ImportData(path);

3.11 ExportData（导出学习数据)

使用场景：如果该机器已经学习完毕可以使用该函数将学习数据导出
函数原型：

ExportData(char* path);

参数说明：

请求参数	必填	类型	描述
path	Y	const char*	导出的文件路径该值为引用传递调用后会修改成最终结果

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int ExportData(StringBuilder path);

StringBuilder path = new StringBuilder(20);
ExportData(path);

3.12 Close（关闭资源)

使用场景：程序退出时请使用该函数释放资源
调用此函数后，进程没有退出，若需要再次使用dll的接口，需重新进行初始化流程
备用函数 : 为了防止部分语言自带函数Close() 提供一个备选函数WMrelease() 供使用
函数原型：

Close()

参数说明：

请求参数	必填	类型	描述

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int Close();

Close();

3.13 UnBindPos（解绑POS)

使用场景：解绑SN码
函数原型：

UnBindPos(char* tenant, char* snNo);

参数说明：

请求参数	必填	类型	描述
tenant	y	char*	租户
snNo	y	char*	注册码

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int UnBindPos(StringBuilder tenant, StringBuilder snNo);

UnBindPos(new StringBuilder("demo"),new StringBuilder("123"));

3.14 ClearTrainedData（清空学习记录)

使用场景：清空学习记录
使用此函数后，需要重启程序
函数原型：

ClearTrainedData();

返回值：0代表成功其他皆为失败

调用示例:

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int ClearTrainedData();

ClearTrainedData();

3.15 FreshChangeError(图片纠错)

使用场景：识别的时候出现多个结果，想要删除不想看到的结果，使识别更精确时使用此功能
注：谨慎使用，可能会导致其他商品识别不准
函数原型：

FreshChangeError(const char* code)

参数说明：

请求参数	必填	类型	描述
code	Y	char*	商品plu

返回值： 0代表成功，其他代表失败

调用示例

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int FreshChangeError(byte[] name);

3.16 SnCodeVerification(校验sn码)

使用场景：获取sn码的状态，校验是否与本机绑定的一致。
函数原型：

SnCodeVerification(char* snNo,int timeOut = 15)

参数说明：

请求参数	必填	类型	描述
code	Y	char*	sn码
timeOut	N	int	网络请求超时时间

返回值： 0代表成功，其他代表失败

调用示例

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int SnCodeVerification(byte[] name,int timeOut = 15);

3.17 Probation(试用接口)

使用场景：在未注册的情况下试用sdk，试用期为15天
函数原型：

Probation()

参数说明：

请求参数	必填	类型	描述

返回值： 0代表成功，其他代表失败

调用示例

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int Probation();

3.18 BatchMatchImages(批量匹配商品的图片)

使用场景：支持批量请求配图接口，需要本地提前准备一份配图商品文件，该文件可以是txt或json类型。
注：网络不好会导致配图时间延长，超时时间为30s，但断网无法进行匹配商品图片。
函数原型：

int BatchMatchImages(char* inPath, char* outPath);

参数说明：

请求参数	必填	类型	描述
inpath	Y	char*	商品列表文件路径
outpath	Y	char*	匹配结果列表文件路径

返回值： 0代表成功，其他代表失败

注：本地配图商品文件内容如下

inpath:

{"productList":[{"productName":"苹果","productNumber":"123"},{"productName":"香蕉","productNumber":"456"}]}

outpath:

{"productList":[{"productName":"苹果","productNumber":"123","matchProductUrl":"http://standard-product-picture-test.oss-cn-beijing.aliyuncs.com/wmsaas-prod/苹果.jpg"},{"productName":"香蕉","productNumber":"456","matchProductUrl":"http://standard-product-picture-test.oss-cn-beijing.aliyuncs.com/wmsaas-prod/香蕉.jpg"}]}

调用示例

[DllImport(NativeLibrary, CallingConvention = CallingConvention.StdCall, CharSet = CharSet.Ansi)]
private unsafe extern static int BatchMatchImages(byte[] inPath,byte[] outPath);

附录 1：商品识别返回错误码

错误码	描述	解决方案
0	成功
-1002	正在导入学习资料	导入学习资料时请要使用识别和学习功能，并在导入完成后重新启动程序
-1003	初始化未完成	检查是否成功调用Init函数
-1004	学习资料为空	请检查识别是否成功
-2001	验证失败	检查是否成功调用InitPos函数
-2002	读取图片失败	检查摄像头设备是否正常
-2003	摄像头打开失败	检查摄像头连接是否正常，系统自带相机是否能打开
-2004	商品记录未找到	检查是否成功调用AutoDetect函数
-2005	sessionId未找到	检查是否成功调用AutoDetect函数
-2006	初始化pos失败	检查执行目录是否有dev.ini 如果存在联系运维人员
-2007	打开文件失败	检查传入传入路径是否正确
-2008	保存坐标,像素长宽失败	默认像素为640*480 请确认x+w <640 y+h<480
-2009	没有设置摄像头剪辑坐标	请使用SaveScaleSetting函数保存下坐标
-3001	该名称没有匹配到照片	请检查名称是否合理
-3002	请求照片失败	请检查传入的名字是否合法
-4001	snCode没有找到	snCode没有找到
-4002	poscode错误，该posCode已绑定其他mac地址	该posCode已绑定其他mac地址，请更换posCode
-4003	mac地址错误，该设备已被绑定	该设备的mac地址已被绑定，请解绑后再绑定
-4004	租户没找到	tenantCode没有找到
-4005	snCode没有绑定设备	snCode并未绑定
-4006	解绑失败	该pos现在的mac地址和服务器记录的mac地址不一致无法解绑
-4007	sn错误，该sn码已绑定其他设备	该sn码已绑定其他设备，请更换sn码
-5001	打开文件失败	检查传的的文件路径参数是否正确

附录 2：用例说明

1.有重量变化即识别

定义个布尔变量，当重量小于 10g 的时候，该变量为 false，

当重量有变化大于 30g 的时候且同时该变量为 false，进行识别，并把该变量设置为 true

附录 3：配置文件参数说明

配置文件dev.ini(无特殊解释的不用去修改)

1.openSync

此参数位局域网同步控制参数，0为关闭局域网同步，1为开启局域网同步，如果两台机器都开启了局域网同步，A机器再次学习后的数据会同步到B机器上。

2.saveImage

1.为保存识别图片，0 为不保存识别图片

注：每次重新初始化dll，都会对之前的识别图像进行清理，不会积存。

3.driveAi

这个参数为识别时使用的物理驱动，1.为使用GPU,0为使用cpu

4.dataLevel

此参数为学习数据存储上限，1为50000，2为70000，其他为120000

5.usingAi

这个参数为视频流识别所使用的物理驱动，1.为使用GPU,0为使用cpu

V5版本

元芒数字 i 识别系统（WmAceKG）

Windows端 DLL 接口说明文档

Version Release v5.0.0.0

更新时间: 2023.5.12

上海元芒数字科技有限公司

Windows端DLL接口文档

一、文档说明

1.1 版本说明

1.2 ⽂档概述

1.3 术语定义及说明

二、 调用方法说明

2.1 集成方法说明

2.2 接口调用流程描述

2.3 接口时序图

三、 接⼝说明

设备初始化

3.1 Init （ 初始化 ）

3.2 InitPos （注册 POS 接口 ）

3.3 SetCameraId (初始化摄像头)

3.4 GetScaleBitmap (初始化秤盘信息-获取全景照片)

3.5 SaveScaleSetting (初始化秤盘信息-标定秤盘并保存坐标信息)

3.6 GetScaleSetting (判断秤盘是否已标定）

3.7 AutoDetect （商品识别）

3.8 SetFeedBack （保存识别结果)

3.9 SetNoRecommend（删除商品学习结果）

3.10 ImportData（导入学习数据)

3.11 ExportData（导出学习数据)

3.12 Close（关闭资源)

3.13 UnBindPos（解绑POS)

3.14 ClearTrainedData（清空学习记录)

3.15 FreshChangeError(图片纠错)

3.16 SnCodeVerification(校验sn码)

3.17 Probation(试用接口)

3.18 BatchMatchImages(批量匹配商品的图片)

附录 1：商品识别返回错误码

附录 2：用例说明

1.有重量变化即识别

附录 3：配置文件参数说明

配置文件dev.ini(无特殊解释的不用去修改)

1.openSync

2.saveImage

3.driveAi

4.dataLevel

5.usingAi

Comments

Make a comment

二、调用方法说明

三、接⼝说明

3.1 Init （初始化）

3.2 InitPos （注册 POS 接口）