3D肢体关键点SDK-原生Android
更新时间：2021-08-09
1 简介
当前3D肢体SDK共计输出16个人体关键点，点位顺序以MPII顺序为参考，具体点位顺序0-右脚踝、1-右膝、2-右股、3-左股、4-左膝、5-左脚踝、6-盆骨、7-胸部、8-脖子、9-头部、10-右手腕、11-右手肘、12-右肩、13-左肩、14-左手肘、15-左手腕
当前SDK输出为人体16个关键点的3D坐标，其中x，y为屏幕坐标归一化值，z为相对于人体根节点（人为规定关键点6为根节点）的相对深度，单位为mm。
2 快速入门
- 系统：支持 Android 5.1到 Android 10系统。需要开发者通过minSdkVersion来保证支持系统的检测。
- CPU架构：armeabi-v7a，arm64-v8a
- 硬件要求：要求设备上有相机模块。
- 网络：支持WIFI及移动网络，移动网络支持使用NET网关及WAP网关（CMWAP、CTWAP、UNIWAP、3GWAP）。
3 SDK集成步骤
第1步：添加授权文件
您可以通过“合作咨询”联系相关接口人申请授权。
- 将LICENSE文件
dumixar.license放置于工程assets目录下
第2步：导入相关库
- 将 dumixar.jar 拷贝到您的工程的 libs 文件夹中，并检查编译依赖。 将 arm64-v8a 和 armeabi-v7a 文件夹拷贝到 Android Studio 工程src/main/jniLibs目录中。
- 确认
person_detector.nb,person_cls.nb,3dpose.nb三个模型文件的路径位置 - 确认包名为申请时填写的包名
第3步：配置Manifest文件，添加必要的权限
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />第4步：初始化
SDK初始化分为两步
- SDK鉴权
注意：SDK的初始化必须要最先进行
使用能力前，务必先调用Authenticator.init初始化，否则能力无法正常使用。初始化示例如下
// 需要预先加载动态库，否则将无法初始化
System.loadLibrary("auth");
Authenticator.init(getApplicationContext(), new IAuthCallback() {
@Override
public void onSuccess() {}
@Override
public void onError(String errorMessage, int featureCode) {}
});- SDK加载模型
目前提供两种初始化方式，从SD卡路径加载模型以及从assets路径加载模型，接口如下
/** 从SD卡初始化
* @param detectDir 检测模型路径
* @param clsDir 分类模型路径
* @param poseDir 肢体点模型路径
**/
public static native int initPose(String detectDir, String clsDir, String poseDir);
/** 从asstes初始化
* @param detectDir 检测模型路径
* @param clsDir 分类模型路径
* @param poseDir 肢体点模型路径
**/
public static native int initPoseFromAsset(String detectDir, String clsDir, String poseDir);调用示例如下
// 从SD卡路径初始化，下面示例中模型文件位于SD卡/sdcard/HumanPose/mdlModels文件夹下
ARMdlHumanPoseJNI.initPose("/sdcard/HumanPose/mdlModels", "/sdcard/HumanPose/mdlModels", "/sdcard/HumanPose/mdlModels");
// 从asstes路径初始化，下面示例中模型文件位于工程assets中mdlModels文件夹下
ARMdlHumanPoseJNI.setAssetManager(getAssets());
ARMdlHumanPoseJNI.initPoseFromAsset("mdlModels", "mdlModels", "mdlModels");第5步：3D肢体关键点预测
肢体点预测接口输入数据以nv21图像格式为准
/** 关键点预测
* @param data 摄像头nv21数据
* @param width 图像宽
* @param height 图像高
* @param angle 图像顺时针旋转为正所需的角度
* @param isFront 是否前置
* @param bodyKeyPoints 3D肢体点返回数组，大小为16 * 3 * 人数, 格式为x0,y0,z0,x1,...
* @return int 返回值为人数
**/
public static native int predictPose(byte[] data, int width, int height, int angle, boolean isFront, float[] bodyKeyPoints);调用示例如下：
int num = ARMdlHumanPoseJNI.predictPose(nv21, previewSize.getWidth(), previewSize.getHeight(), 90, iFront, kpnts);返回的num为人数，kpnts大小为num*16*3
动作识别接口开放
当前共支持跳绳、开合跳、左右体侧、引体向上、深蹲、深蹲跳、高抬腿、左右横跳、开合深蹲跳和侧弓步交换压腿等10种动作，如需进行动作识别可在关键点预测接口调用之后调用以下接口进行动作识别
/**
* @param kpoints 关键点检测SDK输出的关键点坐标数组
* @param num 关键点检测SDK输出的人数
* @param wide 屏幕宽度
* @param high 屏幕高度
* @return boolean 表示在该帧是否完成了一个特定动作
**/
// 跳绳识别
public static native boolean posedist(float[] kpoints, int num);
// 开合跳识别
public static native boolean jumpjacks(float[] kpoints, int num);
// 右体侧识别
public static native boolean RightBodySide(float[] kpoints, int num, int wide, int high);
// 左体侧识别
public static native boolean LeftBodySide(float[] kpoints, int num, int wide, int high);
// 引体向上识别
public static native boolean Pullup(float[] kpoints, int num);
// 深蹲识别
public static native boolean Squat(float[] kpoints, int num);
// 深蹲跳识别
public static native boolean SquatJump(float[] kpoints, int num);
//高抬腿识别
public static native boolean HighKnees(float[] kpoints, int num);
// 左右横跳识别
public static native boolean Horizontal(float[] kpoints, int num);
// 开合深蹲跳识别
public static native boolean SquatJackJump(float[] kpoints, int num);
// 左右弓步压腿识别
public static native boolean PushLeg(float[] kpoints, int num);第6步：资源释放
SDK 使用结束后，应进行资源释放，以避免内存泄露
// 鉴权模块资源释放
Authenticator.release();
// SDK模块资源释放
ARMdlHumanPoseJNI.releasePose();4 关于Demo展示
本SDK附带提供一个调用SDK及展示SDK 效果的基础Demo，在Demo中会有2D可视化及3D可视化两个展示方式：
- 2D展示为取3D关键点中的XY屏幕坐标进行可视化，与画面中人物关键点位置匹配
- 3D展示为在SceneKit 3D坐标系中对3D关键点的展示，由于3D坐标系与屏幕坐标系无法统一对应，所以Demo中展示时对3D关键点的坐标进行了缩放，且在3D坐标系中无法与2D屏幕画面中的人物关键点匹配位置。
- 3D展示视图中触控屏幕可对坐标系进行旋转，以查看不同角度的人物展示。