• 1 准备工作
• 2 申请Licence
• 3 添加SDK到工程
• 4 DEMO说明
• 5 SDK初始化
• 6 获取摄像头数据
• 7 获取摄像头预览数据
• 8 会员注册
• 9 会员实时查询

1.准备工作

1.1 申请API对接所需的材料

步骤一：联系商米售前技术团队，申请对接API所需要的账号信息，需要向售前技术支持团队提供如下软件开发商信息

客户提供的信息	说明
客户名称	软件商公司名称
对接摄像头型号	对接API的型号，如SS（Store Sense）、FS（Face Sense）
收银设备硬件指纹	获取到SDK后，通过SDK获取硬件指纹信息，用于申请Licence

步骤二：售前技术团队根据客户的需求信息，返回软件商对接API所需的账号信息，包括:

返回给客户的信息	说明
SaaS代号	商米内部管理SaaS软件商信息的代号
设备激活码	激活设备端所需的激活码，用于签名校对软件商是否有权调用
SDK开发包	用于人脸识别以及AI识客设备开发的SDK，目前只支持安卓版本

SDK开发包：

序号	文件/文件名	说明
1	FaceDemo	Demo工程源码
2	face-release.aar	商米人脸识别SDK
3	libipcsdk-release.aar	IPC联动版sdk
4	asset	商米 人脸识别资源文件

2、申请Licence

登陆开发者网站，提供 以下信息申请Licence

提供的信息	说明
收银设备硬件指纹	通过SDK API获取设备硬件信息
人脸库	人脸库的限制大小

商米开发者网站会生成一个Licence文件。SaaS开发者获取到Licence后即使用SDK。

3、添加SDK到工程

3.1 导入SDK

右键点击app，选择New->Module->Import .JAR/.AAR Package

点击Finish即导入aar模块

3.2 权限申明

在AndroidManifest.xml文件里添加如下权限：

	‹uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/›
	‹uses-permission android:name="android.permission.INTERNET" /›
	‹uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /›
	‹uses-permission android:name="android.permission.CHANGE_WIFI_STATE" /›
	‹uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" /›
	‹uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /›
	‹uses-permission android:name="android.permission.CAMERA" /›

3.3 导入asset资源

导入提供的assets资源

说明：资源文件需要APP启动的时候复制到APP的运行目录，以方便SDK后续初始化。

3.4 导入licence文件

获取到licence_valid.txt文件，可以放到assets资源目录，也可以放到sdcard目录。

1）放到assets资源目录，则需要把licence_valid.txt文件从资源文件复制到app的工作目录。

2）如果放到sdcard目录，则需要app申请sdcard读取权限。

无论哪一种情况，最后使用的时候，需要传递licence_valid.txt文件的路径，以激活人脸识别SDK。详细见SDK初始化代码

4、DEMO说明

4.1 工程目录结构

4.1.1 app Module

app Module是DEMO的入口。其中包含了各个模块的入口函数调用。

4.1.2 commonlib

commonlib Module包含了整个DEMO通用的接口。其中包含摄像头管理，工具类。如下图：

4.1.2.1 FaceCameraManager

FaceCameraManager统一管理设备自带摄像头和USB摄像头。设备自带摄像头的流程是使用Android系统提供的摄像头通用方法。USB摄像头则使用UVC库提供的操作摄像头的方法。FaceCameraManager对上层应用提供统一的方法： startPreview和 stopPreview。

4.1.2.2 NormalCameraManager

NormalCameraManager使用Android系统提供的摄像头方法，实现startPreview和stopPreview。并在内部实现回调接口用于返回每一帧摄像头获得的数据。

4.1.2.3 UVCCameraManager

UVCCameraManager使用第三方库UVClib提供的方法用于操作USB摄像头，实现startPreview和stopPreview。 并在内部实现回调接口用于返回每一帧摄像头获得的数据 。

4.1.2.4 ByteUtils

ByteUtils提供Byte操作的一些通用方法。

4.1.2.5 DBHelper

DBHelper提供创建数据的方法。

4.1.2.6 ImageUtils

ImageUtils提供图片操作的一些方法。

4.1.3 libuvccamera

libuvccamera Module采用第三方库开源库libuvccamera

4.1.4 facedemo

facedemo Module是DEMO实现功能的主要模块。其包含：会员注册、会员管理、会员查询、IPC配置等功能。

5、SDK初始化

详细代码见 商米AI识客SDK示例代码-> SDK初始化

6、获取摄像头数据

详细代码见 商米AI识客SDK示例代码->获取摄像头信息

7、获取摄像头预览数据

详细代码见 商米AI识客SDK示例代码->获取摄像头预览信息

8、会员注册

详细代码见 商米AI识客SDK示例代码-> 会员注册

9、会员实时查询

会员实时查询，需要使用到，实时获取摄像头预览数据以及人脸特征提取两个功能

详细代码见 商米AI识客SDK示例代码->获取摄像头预览信息

详细代码见 商米AI识客SDK示例代码->人脸特征提取

10、配置摄像机

见IPC配置页面

1. SDK 初始化
2. 获取摄像头预览信息
3. 获取摄像头拍照数据
4. 获取特征值
5. 人脸特征值比较
6. 人脸会员库添加
7. 删除特征记录
8. 会员注册
9. IPC 回调接口

1. SDK初始化

public boolean initFaceSdkInstance(Context context, String licencePath) {
         //初始化配置文件
        int ret = SunmiFaceSDK.init(confPath);
        if (licencePath == null) {
            Log.d(TAG, "Please input licence");
            return false;
        }
        File f = new File(licencePath);
        if (!f.exists()) {
            Log.d(TAG, "licence is not exist");
            return false;
        }
        String licence = readToString(licencePath);
        //验证Licence
        ret = SunmiFaceSDK.verifyLicence(context, licence);
        if (ret != 0) {
            Log.d(TAG, "Licence is not OK ErrorCode " + ret);
            return false;
        }
        //设置配置参数
        SunmiFaceConfigParam param = new SunmiFaceConfigParam();
        SunmiFaceSDK.getConfig(param);
        param.setDistance_threshold_(1.3f);
        param.setYaw_threshold_(50.0f);
        param.setPitch_threshold_(50.0f);
        param.setRoll_threshold_(50.0f);
        param.setMin_face_size(60);
        param.setImage_quality_threshold_(10);
        param.setMin_luminance_(10);
        param.setMax_luminance_(180);
        param.setLiveness_on_(false);
        param.setThread_num_(1);
        //设置配置参数
        ret = SunmiFaceSDK.setConfig(param);

        if (ret != 0) {
            Log.d(TAG, "param is not init");
            return false;
        }
        return true;
    }

public void init(Context context) {
      //设置licence_valid.txt为sd卡路径，也可以换成app运行工作目录。
      String licencePath = Environment.getExternalStorageDirectory() + File.separator + "licence_valid.txt";
      initFaceSdkInstance(context, licence_path);
     // 调用IPCameraManager静态类getInstance初始化IPCManger对象
     mIPCManager = IPCameraManager.getInstance(context);
}

2. 获取摄像头预览信息

//摄像头数据回调接口	
CameraDataCallback cameraDataCallback = new CameraDataCallback() {
    @Override
    public void onImageDataArrival(Bitmap bitmap, int width, int height) {
        if (mBackgroundHandler != null) {
            if (mClickAction == 1 && !faceDetectState.get()) {
                mBackgroundHandler.post(new MotionDetector(bitmap, width, height));
            } else {
                bitmap.recycle();
            }
        }

    }
};
//开启摄像头预览
FaceCameraManager.getInstance().startPreview(getApplicationContext(), this, FaceCameraManager.getInstance().getCurCamera(), cameraView, PREVIEW_WIDTH, PREVIEW_HEIGHT, cameraDataCallback);

3. 获取摄像头拍照数据

{
//根据摄像头是USB还是系统摄像头，调用不同的方法，获取bitmap数据
if (FaceCameraManager.getInstance().getCurCamera() == FaceCameraManager.CAMERA_USB)
    bitmap = mUVCCameraView.captureStillImage();
else
    bitmap = mTextureView.getBitmap();

}

4. 获取特征值

说明：通过bitmap获取特征值

    public ArrayList‹SunmiFaceFeature› getFeatures(Bitmap bitmap, int maxFace) {

        int ret = 0;
        //bitmap的RGB数据转化成BGR数据
        byte[] srcData = ImageUtils.getPixelsBGR(bitmap);
        //通过BGR数据构造SunmifaceImage对象
        SunmiFaceImage image = new SunmiFaceImage(srcData, bitmap.getHeight(), bitmap.getWidth(), maxFace);
        SunmiFaceImageFeatures features = new SunmiFaceImageFeatures();
        //从SunmifaceImage数据中提取人脸特征
        ret = SunmiFaceSDK.getImageFeatures(image, features);
        //返回人脸特征数组
        SunmiFaceFeature feature_ary = features.getFeatures_();
        ArrayList‹SunmiFaceFeature› arrayList = new ArrayList‹›();
        if (features.getFeatures_count_() == 0) {
            SunmiFaceSDK.releaseImageFeatures(features);
            return arrayList;
        }

        for (int i = 0; i ‹ features.getFeatures_count_(); i++) {
            SunmiFaceFeature sunmiFaceFeature = SunmiFaceLib.SunmiFaceFeatureArray_getitem(feature_ary, i);
            arrayList.add(sunmiFaceFeature);
        }
        SunmiFaceSDK.releaseImageFeatures(features);
        return arrayList;
        // return getFeature(srcData, bitmap.getWidth(),bitmap.getHeight(), 1);
    }

5. 人脸特征值比较

    public SunmiFaceCompareResult compareFeature1V1(float similar, float[] feature1, float[] feature2) {
        //构造SunmiFaceFeature对象
        SunmiFaceFeature feat1 = new SunmiFaceFeature();
        SunmiFaceFeature feat2 = new SunmiFaceFeature();
        feat1.setFeature_(feature1);
        feat2.setFeature_(feature2);
        SunmiFaceCompareResult result = new SunmiFaceCompareResult();
        //调用compare1v1进行比较
        int ret = SunmiFaceSDK.compare1v1(feat1, feat2, result);
        return result;
    }

6. 人脸会员库添加

说明: 添加人脸时，同时要向IPC注册人脸信息。向IPC传递信息包括：人脸会员库（GVIP），人脸照片、人脸会员唯一识别ID。

{
        //使用faceFeature构建record
        SunmiFaceDBRecord record =     SunmiFaceSDK.faceFeature2FaceDBRecord(faceFeature);
        record.setId_(user.getUserId());
        record.setName_(user.getUserName());
        //把record添加到人脸库
        int ret = SunmiFaceSDK.addDBRecord(record);
        //把人脸照片传递给IPC，向IPC添加人脸记录   
         if (mIPCManager != null) {
                    mIPCManager.addFaceRecord("GVIP", picPath, uid, new RPCCallback‹RPCResponse›() {
                        //IPC人脸添加记录完成后回调接口
                        @Override
                        public void onComplete(RPCResponse result) {
                            Log.i(TAG, "addFaceRecord, code:" + result.code());
                        }
                        //IPC人脸添加记录失败时回调接口
                        @Override
                        public void onAbort(int httpStatus) {
                            Log.i(TAG, "addFaceRecord, httpStatus:" + httpStatus);
                        }
                        //IPC人脸添加记录异常时回调接口
                        @Override
                        public void onException(Throwable t) {
                            Log.i(TAG, "addFaceRecord, Exception:" + t.getMessage());
                        }
                    });
                }

}

7. 删除特征记录

说明: 删除会员信息时，需要把删除的人脸会员信息同步到IPC。向IPC传递用户的唯一识别ID

{
//删除人脸库记录
int result = SunmiFaceSDK.deleteDBRecord(user.getImageName());
//同步删除IPC人脸记录
if (mIPCManager != null) {
    mIPCManager.deleteFaceRecord("GVIP", userId, new RPCCallback‹RPCResponse‹RPCResponse.FaceDeleteSubResult››() {
         //IPC人脸删除记录完成后回调接口
        @Override
        public void onComplete(RPCResponse‹RPCResponse.FaceDeleteSubResult› result) {
            Log.i(TAG, "deleteFaceRecord, code:" + result.code());
        }
    });
}
}

8 会员注册

/*
 *向系统注册会员信息
 *@groupname, 会员组
 *@userNanem, 会员名
 *@picPath,   会员照片存放路劲
 *@userInfo,  会员详情
 *@faceFeature, 会员照片提取的特征值
 */
public boolean registerUserIntoDBmanager(String groupName, String userName, String picPath, String userInfo, SunmiFaceFeature faceFeature) {
        boolean isSuccess = false;
        Group group = new Group();
        group.setGroupId(groupName);
        //创建会员
        User user = new User();
        user.setGroupId(groupName);
        //final String uid = UUID.randomUUID().toString();
        String uid = String.valueOf(System.currentTimeMillis());
        user.setUserId(uid);
        user.setUserName(userName);
        user.setFeature(faceFeature.getFeature_());
        //创建人脸库记录信息
        SunmiFaceDBRecord record = SunmiFaceSDK.faceFeature2FaceDBRecord(faceFeature);
        record.setId_(user.getUserId());
        record.setName_(user.getUserName());
        //像人脸库添加记录
        int ret = SunmiFaceSDK.addDBRecord(record);
        if (ret != 0) {
            Log.d(TAG, "addDBRecord failed " + SunmiFaceSDK.getErrorString(ret));
            return false;
        }
        //在会员数据库中记录，特征值对应的图片在人脸数据中的ID
        user.setImageName(record.getImg_id_());
        if (userInfo != null) {
            user.setUserInfo(userInfo);
        }
        // 添加用户信息到数据库
        boolean importUserSuccess = FaceManager.getInstance().userAdd(user);
        if (importUserSuccess) {
            // 如果添加到数据库成功，则添加用户组信息到数据库
            // 如果当前图片组名和上一张图片组名相同，则不添加数据库到组表
            if (FaceManager.getInstance().groupAdd(group)) {
                isSuccess = true;
                if (mIPCManager != null) {
                    Log.i(TAG, "picPath: " + picPath);
                    Log.i(TAG, "uid: " + uid);
                    //把会员照片同步发送到IPC，同步会员信息到IPC
                    mIPCManager.addFaceRecord("GVIP", picPath, uid, new RPCCallback‹RPCResponse›() {
                        @Override
                        public void onComplete(RPCResponse result) {
                            Log.i(TAG, "addFaceRecord, code:" + result.code());
                        }

                        @Override
                        public void onAbort(int httpStatus) {
                            Log.i(TAG, "addFaceRecord, httpStatus:" + httpStatus);
                        }

                        @Override
                        public void onException(Throwable t) {
                            Log.i(TAG, "addFaceRecord, Exception:" + t.getMessage());
                        }
                    });
                }
            } else {
                isSuccess = false;
            }

        } else {
            isSuccess = false;
        }
        return isSuccess;
    }

9. IPC 回调接口

说明：用户获取IPC的状态、返回信息等。

{
                    //获取IPC信息
                    IPCameraManager manager = IPCameraManager.getInstance(getApplicationContext());
                    //IPC初始化
                    manager.init("test", "123456", "123456");
                    //注册IPC回调
                    manager.registerListener(new IPCameraListener() {
                        //IPC设备在线时回调接口
                        @Override
                        public void onDeviceOnline(IPCameraInfo device) {
                            showToast("[ " + device.getDeviceid() + " ]上线");
                        }
                        //IPC设备离线时回调接口
                        @Override
                        public void onDeviceOffline(IPCameraInfo device) {
                            showToast("[ " + device.getDeviceid() + " ]离线");
                        }
                        //IPC设备获取到进店信息后回调接口
                        @Override
                        public void onFaceDetect(String userId) {
                            String userName = null;
                            List‹User› users = DBManager.getInstance().queryUserByUserId(userId);
                            if (users != null && users.size() › 0) {
                                userName = users.get(0).getUserName();
                            }
                            if (userName == null) {
                                showToast("未注册的用户进店");
                            } else {
                                User user = users.get(0);
                                UserEvent userEvent = new UserEvent();
                                userEvent.setUserId(user.getUserId());
                                userEvent.setEnterTime(System.currentTimeMillis());
                                userEvent.setDesc("Enter Store");
                                DBManager.getInstance().addUserEvent(userEvent);
                                showToast("用户[ " + userName + " ]进店");
                            }
                        }
                    }
}

1. 商米人脸识别接口

见《商米人脸识别会员接口文档》，该文档在申请开发包的时候一并提供。

2. IPC联动接口

见IPCManager页面

• 简介

1 简介

商米AI识客SDK （Android版）是一种面向SUNMI OS设备的人脸识别开发包，配套商米AI识客摄像头使用，SDK主要包含人脸采集、人脸识别、人脸特征数据管理、摄像头配置激活、会员进店提醒等功能，以aar包形式发布。如下是SDK整体框架以及Demo APP架构。

SDK框架图如下：

• 主要包含四层结构
• 1、C/C++ library实现人脸特征提取，人脸特征对比等算法功能，并提供人脸库管理（人脸库的添加、查询、删除等操作）
• 2、JNI层主要是封装C/C++实现的人脸识别的功能，为Java上层提供native接口
• 3、Java API层使用native层提供的接口为上层 APP提供SunmiFace接口，并提供IPC配置管理、通讯交互的功能
• 4、Demo APP，使用SDK提供的功能实现人脸识别、人脸库的管理、IPC配置管理、IPC通讯等功能。

2 业务场景

通过此SDK您可以完成类似如下的应用场景开发。