EasyEdge平台Android系统SDK开发文档
简介
1.1 Android SDK 硬件要求
通常您下载的SDK只支持固定的某一类芯片。
- 通用ARM: 支持大部分ARM 架构的手机、平板及开发板。通常选择这个引擎进行推理。
- 通用ARM GPU:支持骁龙、麒麟、联发科等带GPU的手机、平板及开发板。
-
高端芯片AI加速模块:
- 高通骁龙引擎SNPE: 高通骁龙高端SOC,利用自带的DSP加速。其中 660 之后的型号可能含有 Hexagon DSP模块,具体列表见snpe 高通骁龙引擎官网。
- 华为NPU引擎DDK:华为麒麟970、980的arm-v8a的soc。 具体手机机型为mate10,mate10pro,P20,mate20,荣耀v20等。
- 华为达芬奇NPU引擎DAVINCI: 华为NPU的后续版本,华为麒麟810,820,990的arm-v8a的soc。具体手机机型为华为mate30,p40,nova6,荣耀v30等。
通用ARM有额外的加速版,但是有一定的精度损失。 因GPU硬件限制,通用ARM GPU物体检测模型输入尺寸较大时会运行失败,可以在训练的时候将输入尺寸设为300*300。 高端芯片AI加速模块, 一般情况下推理速度较快。 运行内存不能过小,一般大于demo的assets目录大小的3倍。
1.2 功能支持
引擎 | 图像分类 | 物体检测 | 图像分割 | 文字识别 只支持EasyEdge |
姿态估计 |
---|---|---|---|---|---|
通用ARM | √ | √ | √ | √ | √ |
通用ARM GPU | √ | √ | |||
高通骁龙引擎SNPE | √ | √ | |||
华为NPU引擎DDK | √ | √ | |||
华为达芬奇NPU引擎DAVINCI | √ | √ |
1.3 Release Notes
时间 | 版本 | 说明 |
---|---|---|
2021.10.20 | 0.10.0 | 更新鉴权;更新达芬奇NPU、SNPE、通用ARM及ARM-GPU引擎;新增达芬奇NPU对检测模型的支持;支持更多姿态估计模型 |
2021.07.29 | 0.9.17 | 迭代优化 |
2021.06.29 | 0.9.16 | 迭代优化 |
2021.05.13 | 0.9.15 | 更新鉴权,更新通用arm及通用arm gpu引擎 |
2021.04.02 | 0.9.14 | 修正bug |
2021.03.09 | 0.9.13 | 更新android arm的预处理加速 |
2020.12.18 | 0.9.12 | 通用ARM引擎升级;新增ARM GPU引擎 |
2020.10.29 | 0.9.10 | 迭代优化 |
2020.9.01 | 0.9.9 | 迭代优化 |
2020.8.11 | 0.9.8 | 更新ddk 达芬奇引擎 |
2020.7.14 | 0.9.7 | 支持arm版ocr模型,模型加载优化 |
2020.6.23 | 0.9.6 | 支持arm版fasterrcnn模型 |
2020.5.14 | 0.9.5 | 新增华为新的达芬奇架构npu的部分图像分类模型 |
2020.4.17 | 0.9.4 | 新增arm通用引擎量化模型支持 |
2020.1.17 | 0.9.3 | 新增arm通用引擎图像分割模型支持 |
2019.12.26 | 0.9.2 | 新增华为kirin麒麟芯片的物体检测支持 |
2019.12.04 | 0.9.1 | 使用paddleLite作为arm预测引擎 |
2019.08.30 | 0.9.0 | 支持EasyDL专业版 |
2019.08.30 | 0.8.2 | 支持华为麒麟980的物体检测模型 |
2019.08.29 | 0.8.1 | 修复相机在开发版调用奔溃的问题 |
2019.06.20 | 0.8.0 | 高通手机引擎优化 |
2019.05.24 | 0.7.0 | 升级引擎 |
2019.05.14 | 0.6.0 | 优化demo程序 |
2019.04.12 | 0.5.0 | 新增华为麒麟980支持 |
2019.03.29 | 0.4.0 | 引擎优化,支持sd卡模型读取 |
2019.02.28 | 0.3.0 | 引擎优化,性能与效果提升; |
2018.11.30 | 0.2.0 | 第一版! |
快速开始
2.1 安装软件及硬件准备
扫描模型下载SDK处的网页上的二维码,无需任何依赖,直接体验
如果需要源码方式测试:
打开AndroidStudio, 点击 "Import Project..."。在一台较新的手机上测试。
详细步骤如下:
- 准备一台较新的手机,如果不是通用arm版本,请参见本文的“硬件要求”,确认是否符合SDK的要求
- 安装较新版本的AndroidStudio ,下载地址
- 新建一个HelloWorld项目, Android Studio会自动下载依赖, 在这台较新的手机上测试通过这个helloworld项目。注意不支持模拟器。
- 解压下载的SDK。
- 打开AndroidStudio, 点击 "Import Project..."。 即:File->New-> "Import Project...", 选择解压后的目录。
- 此时点击运行按钮(同第3步),手机上会有新app安装完毕,运行效果和二维码扫描的一样。
- 手机上UI界面显示后,如果点击UI界面上的“开始使用”按钮,可能会报序列号错误。请参见下文修改
2.2 使用序列号激活
如果使用的是EasyEdge的开源模型,无需序列号,可以跳过本段直接测试。
建议申请包名为"com.baidu.ai.easyaimobile.demo"的序列号用于测试。
本文假设已经获取到序列号,并且这个序列号已经绑定包名。
2.2.1 填写序列号
打开Android Studio的项目,修改MainActivity类的开头SERIAL_NUM字段。 MainActivity 位于app\src\main\java\com\baidu\ai\edge\demo\MainActivity.java文件内。
// 请替换为您的序列号
private static final String SERIAL_NUM = "XXXX-XXXX-XXXX-XXXX"; //这里填您的序列号
2.2.2 修改包名
如果申请的包名为"com.baidu.ai.easyaimobile.demo",这个是demo的包名,可以不用修改
打开app/build.gradle文件,修改"com.baidu.ai.easyaimobile.demo"为申请的包名
defaultConfig {
applicationId "com.baidu.ai.easyaimobile.demo" // 修改为比如“com.xxx.xxx"
}
修改序列号和包名后,可以运行测试,效果同扫描二维码的一致
2.2.3 测试精简版
对于通用ARM、高通骁龙引擎SNPE、华为NPU引擎DDK和达芬奇NPU引擎Davinci的常见功能,项目内自带精简版,可以忽略开发板不兼容的摄像头。 此外,由于实时摄像开启,会导致接口的耗时变大,此时也可以使用精简版测试。
目前以下硬件环境有精简版测试:
- 通用ARM:图像分类(Classify),物体检测(Detection),文字识别(OCR),图像分割(Segmentation),姿态估计(Pose)
- 高通骁龙引擎SNPE:图像分类(Classify),物体检测(Detection)
- 华为NPU引擎DDK:图像分类(Classify),物体检测(Detection)
- 华为达芬奇NPU引擎Davinci:图像分类(Classify),物体检测(Detection)
具体代码分别在infertest、snpetest、ddktest和davincitest目录下。 修改方法为(以通用ARM为例):更改app/main/AndroidManifest.xml中的启动Activity。
<activity android:name=".infertest.MainActivity"> <!-- 原始的是".MainActivity" -->
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
开启后会自动选择图像分类(Classify),物体检测(Detection),文字识别(OCR),图像分割(Segmentation)或姿态估计(Pose)测试。
使用说明
3.1 代码目录结构
集成时需要“复制到自己的项目里”的目录或者文件:
- app/libs
- app/src/main/assets/xxxx-xxxxx 如app/src/main/assets/infer
+app 简单的设置,模拟用户的项目
|---+libs 实际使用时需要复制到自己的项目里
|----arm64-v8a v8a的so
|----armeabi-v7a v7a的so
|----easyedge-sdk.jar jar库文件
|---+src/main
|---+assets
|----demo demo项目的配置,实际集成不需要
|----infer 也可能是其它命名,infer表示通用arm。实际使用时可以复制到自己的项目里
|---+java/com.baidu.ai.edge/demo
|---+infertest 通用Arm精简版测试,里面有SDK的集成逻辑
|--- MainActivity 通用Arm精简版启动Activity,会根据assets目录判断当前的模型类型,并运行同目录的一个Task。使用时需要修改里面的序列号
|--- TestInferClassifyTask 通用Arm精简版分类
|--- TestInferDetectionTask 通用Arm精简版检测
|--- TestInferOcrTask 通用Arm精简版OCR
|--- TestInferPoseTask 通用Arm精简版姿态
|--- TestInferSegmentTask 通用Arm精简版分割
|---+snpetest SNPE精简版测试
|--- MainActivity SNPE精简版启动Activity,会根据assets目录判断当前的模型类型,并运行同目录的一个Task。使用时需要修改里面的序列号
|--- TestSnpeClassifyTask SNPE精简版分类
|--- TestSnpeDetectionTask SNPE精简版检测
|---+ddktest DDK精简版测试
|--- MainActivity DDK精简版启动Activity,会根据assets目录判断当前的模型类型,并运行同目录的一个Task。使用时需要修改里面的序列号
|--- TestDDKClassifyTask DDK精简版分类
|--- TestDDKDetectionTask DDK精简版检测
|---+davincitest Davinci精简版测试
|--- MainActivity Davinci精简版启动Activity,会根据assets目录判断当前的模型类型,并运行同目录的一个Task。使用时需要修改里面的序列号
|--- TestDavinciClassifyTask Davinci精简版分类
|--- TestDavinciDetectionTask Davinci精简版检测
|----CameraActivity 摄像头扫描示例,里面有SDK的集成逻辑
|----MainActivity 启动Activity,使用时需要修改里面的序列号
|---- build.gradle 这里修改包名
+camera_ui UI模块,集成时可以忽略
3.2 调用流程
以通用ARM的检测模型功能为例, 代码可以参考TestInferDetectionTask
- 准备配置类,如InferConfig,输入:通常为一个assets目录下的文件夹,如infer。
- 初始化Manager,比如InferManager。输入:第1步的配置类和序列号
- 推理图片,可以多次调用 3.1 准备图片,作为Bitmap输入 3.2 调用对应的推理方法,比如detect 3.3 解析结果,结果通常是一个List,调用结果类的Get方法,通常能获取想要的结果
- 直到长时间不再使用我们的SDK,调用Manger的destroy方法释放资源。
3.3 具体接口说明
下文的示例部分以通用ARM的检测模型功能为例 即接口为InferConfig, InferManager,InferManager.detect。 其它引擎和模型调用方法类似。
下文假设已有序列号及对应的包名
3.3.1 . 准备配置类
- INFER:通用ARM,
InferConfig
- ARM GPU:
ArmGpuConfig
- SNPE:高通骁龙DSP,
SnpeConfig
- SNPE GPU:高通骁龙GPU,
SnpeGpuConfig
- DDK:华为NPU,
DDKConfig
- DDKDAVINCI:华为达芬奇NPU,
DDKDaVinciConfig
InferConfig mInferConfig = new InferConfig(getAssets(),
"infer");
// assets 目录下的infer,infer表示通用arm
输入:assets下的配置
输出:具体的配置类
3.3.2. 初始化Manager类
- INFER:通用ARM,
InferManager
- ARM GPU:通用ARM GPU,
InferManager
- SNPE:高通骁龙DSP,
SnpeManager
- SNPE GPU:高通骁龙GPU,
SnpeManager
- DDK:华为NPU,
DDKManager
- DDKDAVINCI:华为达芬奇NPU,
DavinciManager
String SERIAL_NUM = "XXXX-XXXX-XXXX-XXXX";
// InferManager 为例:
new InferManager(this, config, SERIAL_NUM)); // config为上一步的InferConfig
注意要点
- 同一个时刻只能有唯一有效的InferManager。旧的InferManager必须调用destory后,才能新建一个new InferManager() 。
- InferManager的任何方法,都不能在UI线程中调用。
- new InferManager() 及InferManager成员方法由于线程同步数据可见性问题,都必须在一个线程中执行。如使用android自带的ThreadHandler类。
输入: 1.配置类 ; 2.序列号
输出: Manager类
3.3.3. 推理图片
- 接口可以多次调用,但是必须在一个线程里,不能并发
- confidence, 置信度[0-1],小于confidence的结果不返回。 填confidence=0,返回所有结果
- confidence可以不填,默认用模型推荐的。
准备图片, 作为Bitmap输入,
- 输入为Bitmap,其中Bitmap的options为默认。如果强制指定的话,必须使用Bitmap.Config.ARGB_8888
调用对应的推理方法及结果解析
见下文的各个模型方法
3.3.4 分类Classify
public interface ClassifyInterface {
List<ClassificationResultModel> classify(Bitmap bitmap, float confidence) throws BaseException;
// 如InferManger 继承 ClassifyInterface
输入 Bitmap 默认格式或者指定Bitmap.Config.ARGB_8888
输出 ClassificationResultModel
异常:一般首次出现。可以打印出异常错误码。
ClassificationResultModel
- label:分类标签,定义在label_list.txt中
- confidence:置信度,0-1
- lableIndex:标签对应的序号
3.3.5 检测Detect
对于EasyDL口罩检测模型请注意输入图片中人脸大小建议保持在88到9696像素,可根据场景远近程度缩放图片后传入
public interface DetectInterface {
List<DetectionResultModel> detect(Bitmap bitmap, float confidence) throws BaseException;
// 如InferManger 继承 DetectInterface
输入 Bitmap 默认格式或者指定Bitmap.Config.ARGB_8888
输出 DetectionResultModel List
异常:一般首次出现。可以打印出异常错误码。
DetectionResultModel
- label:标签,定义在label_list.txt中
- confidence:置信度
- bounds:Rect,左上角和右下角坐标
3.3.6 图像分割Segmentation
暂时只支持通用ARM引擎,不支持其它引擎
public interface SegmentInterface {
List<SegmentationResultModel> segment(Bitmap bitmap, float confidence) throws BaseException;
// 如InferManger 继承 SegmentInterface
输入 Bitmap 默认格式或者指定Bitmap.Config.ARGB_8888
输出 SegmentationResultModel
异常:一般首次出现。可以打印出异常错误码。
SegmentationResultModel
- label:标签,定义在label_list.txt中
- confidence:置信度
- lableIndex:标签对应的序号
- box: Rect对象表示的对象框
- mask:byte[]表示的原图大小的0,1掩码,绘制1的像素即可得到当前对象区域
mask 字段说明, 如何绘制掩码也可参考demo工程
1 0 1
image 1 1 0 => mask(byte[]) 101 110 011
0 1 1
3.3.7 文字识别OCR
暂时只支持通用ARM引擎,不支持其它引擎,暂时只支持EasyEdge的开源OCR模型。
public interface OcrInterface {
List<OcrResultModel> ocr(Bitmap bitmap, float confidence) throws BaseException;
// 如InferManger 继承 OcrInterface
输入 Bitmap 默认格式或者指定Bitmap.Config.ARGB_8888
输出 OcrResultModel List,每个OcrResultModel对应结果里的一个四边形。
异常:一般首次出现。可以打印出异常错误码。
OcrResultModel
- label:识别出的文字
- confidence:置信度
- List<Point>:4个点构成四边形
3.3.8 姿态估计Pose
暂时只支持通用ARM引擎,不支持其它引擎
public interface PoseInterface {
List<PoseResultModel> pose(Bitmap bitmap) throws BaseException;
// 如InferManger 继承 PoseInterface
输入 Bitmap 默认格式或者指定Bitmap.Config.ARGB_8888
输出 PoseResultModel List
异常:一般首次出现。可以打印出异常错误码。
PoseResultModel
- label:标签,定义在label_list.txt中
- confidence:置信度
- Pair<Point, Point>:2个点构成一条线
3.3.9 释放
释放后这个对象不能再使用,如果需要使用可以重新new一个出来。
public void destory() throws BaseException
3.3.10 整体示例
以下以InferManager为例子, 检测assets目录下一张图片的整体流程
// 在新线程且同一线程中运行以下代码
private void testImageFile() throws IOException, BaseException {
try {
// 1. 准备配置类
InferConfig config = new InferConfig(context.getAssets(), "infer");
// 2. 初始化Manager类
InferManager manager = new InferManager(context, config, SERIAL_NUM);
// 3.1 准备图片, 作为Bitmap输入,
InputStream is2 = context.getAssets().open("test.jpg");
Bitmap image = BitmapFactory.decodeStream(is2);
is2.close();
// 在模型销毁前可以不断调用。但是不支持多线程。
// 3.2 调用对应的推理方法
List<DetectionResultModel> results = manager.detect(image, 0.3f);
// 3.3 解析结果
for (DetectionResultModel result : results) {
Log.i("TestInferDectionTask", result.getLabelIndex() + ":" + result.getConfidence() + ":" + result.getBounds());
}
// 4. 释放
manager.destroy();
} catch (Exception e) {
Log.e("TestInferDetectionTask", "error", e);
}
}
3.3.11 高通骁龙引擎的额外配置
"autocheck_qcom": true, // 如果改成false, sdk跳过检查手机是否是高通的Soc,非高通的Soc会奔溃直接导致app闪退
"snpe_runtimes_order": [],
// 不填写为自动,按照 {DSP, GPU, GPU_FLOAT16, CPU}次序尝试初始化,也可以手动指定如[2,1,3,0], 具体数字的定义见下段
public interface SnpeRuntimeInterface {
int CPU = 0;
int GPU = 1;
int DSP = 2;
int GPU_FLOAT16 = 3;
}
// SnpeManager 中,使用public static ArrayList<Integer> getAvailableRuntimes(Context context) 方法可以获取高通SOC支持的运行方式
集成指南
- 复制库文件libs
- 添加Manifest权限
- 复制模型文件
- 添加调用代码(见上一步具体接口说明)
4.1 复制库文件libs
A. 如果项目里没有自己的jar文件和so文件:
复制app/libs 至自己项目的app/libs目录。
参照demo的app/build.gradle 中添加
android {
....
defaultConfig {
ndk {
abiFilters 'armeabi-v7a', 'arm64-v8a'
}
}
sourceSets {
main {
jniLibs.srcDirs = ['libs']
}
}
}
B. 如果项目里有自己的jar文件,但没有so文件
easyedge.jar文件同自己的jar文件放一起
arm64-v8a和armeabi-v7a放到app/src/main/jniLibs目录下
参照demo的app/build.gradle 中添加
android {
....
defaultConfig {
ndk {
abiFilters 'armeabi-v7a', 'arm64-v8a'
}
}
C. 如果项目里有自己的jar文件和so文件
easyedge.jar文件同自己的jar文件放一起
arm64-v8a和armeabi-v7a取交集和自己的so放一起,交集的意思是比如自己的项目里有x86目录,必须删除x86。
参照demo的app/build.gradle 中添加
android {
....
defaultConfig {
ndk {
abiFilters 'armeabi-v7a', 'arm64-v8a' // abiFilter取交集,即只能少不能多
}
}
jar文件库如果没有设置成功的,编译的时候可以发现报错。
so库如果没有编译进去的话,也可以通过解压apk文件确认。运行的时候会有类似jni方法找不到的报错。
4.2 添加Manifest权限
参考app/src/main/AndroidManifest.xml文件,添加:
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
-permission android:name="android.permission.INTERNET" />
-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
混淆规则(可选)
请不要混淆SDK里的jar文件。
-keep class com.baidu.ai.edge.core.*.*{ *; }
错误码
报错信息收集
正常情况下logcat下可以看见日志及崩溃信息。如果遇见某些开发版无法获取,可以使用demo中的xcrash,日志保存在如下位置
String basePath = Environment.getExternalStorageDirectory().toString() + "/" + context.getPackageName();
params.setLogDir(basePath + "/xCrash");
// sd卡下 /sdcard/com.baidu.ai.edge.demo/xCrash
错误码 | 错误描述 | 详细描述及解决方法 |
---|---|---|
1001 | assets 目录下用户指定的配置文件不存在 | SDK可以使用assets目录下config.json作为配置文件。如果传入的config.json不在assets目录下,则有此报错 |
1002 | 用户传入的配置文件作为json解析格式不准确,如缺少某些字段 | 正常情况下,demo中的config.json不要修改 |
19xx | Sdk内部错误 | 请与百度人员联系 |
2001 | XxxxMANAGER 只允许一个实例 | 如已有XxxxMANAGER对象,请调用destory方法 |
2002 | XxxxMANAGER 已经调用过destory方法 | 在一个已经调用destory方法的DETECT_MANAGER对象上,不允许再调用任何方法 |
2003 | 传入的assets下模型文件路径为null | XxxxConfig.getModelFileAssetPath() 返回为null。由setModelFileAssetPath(null)导致 |
2011 | libedge-xxxx.so 加载失败 | System.loadLibrary("edge-xxxx"); libedge-xxxx.so 没有在apk中。CPU架构仅支持armeabi-v7a arm-v8a |
2012 | JNI内存错误 | heap的内存不够 |
2103 | license过期 | license失效或者系统时间有异常 |
2601 | assets 目录下模型文件打开失败 | 请根据报错信息检查模型文件是否存在 |
2611 | 检测图片时,传递至引擎的图片二进制与长宽不符合 | 具体见报错信息 |
27xx | Sdk内部错误 | 请与百度人员联系 |
28xx | 引擎内部错误 | 请与百度人员联系 |
29xx | Sdk内部错误 | 请与百度人员联系 |
3000 | so加载错误 | 请确认所有so文件存在于apk中 |
3001 | 模型加载错误 | 请确认模型放置于能被加载到的合法路径中,并确保config.json配置正确 |
3002 | 模型卸载错误 | 请与百度人员联系 |
3003 | 调用模型错误 | 在模型未加载正确或者so库未加载正确的情况下调用了分类接口 |
50xx | 在线模式调用异常 | 请与百度人员联系 |