MNNKit

简介

MNNKit是基于端上推理引擎MNN提供的系列应用层解决方案，它是由MNN团队在阿里系应用大规模业务实践后的成熟方案，MNNKit主要面向Android/iOS移动应用开发者，使其能快速、方便地将通用场景的AI能力直接部署到移动应用中，从而基于它开发各种各样的业务能力和玩法。

• SDK开箱即用，接入方便，无需关心算法或模型
• 阿里系业务沉淀的稳定模型和算法，历经双十一等重大项目，端侧由MNN提供可靠的运行环境
• 高性能实时推理，不依赖于后端，更适合移动端应用场景

Demo快速体验

1. 扫码安装

Android

2. 源码安装

git clone https://github.com/alibaba/MNNKit.git

Android

1. 打开Android Studio，点击File->Open...，选择MNNKitDemo/Android目录
2. Gradle sync成功后，点击Run安装运行到真机上（Demo中视频检测依赖摄像头输入）

iOS

cd MNNKitDemo/iOS
pod update
open MNNKitDemo.xcworkspace

然后安装运行到真机上（Demo中视频检测依赖摄像头输入）

SDK安装

Kit依赖关系

MNNKit SDK组织结构如下图：

从底向上分为三层：

1. MNN引擎层，是MNN开源库在Android/iOS上编译好的二进制包的Relase版本，提供端侧AI运行的环境。
2. Core基础层，这一层主要抽象和封装与MNN c++接口调用粒度基本一致的上层API，iOS以OC接口提供，Android以Java接口提供（TODO）。同时也为上层SDK提供一些公共服务类或结构定义。
3. 业务Kit层，人脸检测、手势识别等都属于具体的一种算法能力在上层的封装，这一层的SDK称为业务Kit SDK，其中封装了若干模型和对应的算法处理。往后业务Kit层会不断扩展更多实用的Kit SDK。

安装

业务Kit层SDK相互独立，向下关联依赖无需显式指定，只需根据自身需求选择集成的SDK和版本即可。

Kit SDK	Android	iOS	License
FaceDetection	0.1.0	0.0.4	《MNN Kit Terms of Service》
HandGestureDetection	0.1.0	0.0.4	《MNN Kit Terms of Service》
PortraitSegmentation	0.1.0	0.0.4	《MNN Kit Terms of Service》

Android

• 系统最低API Level16（4.1版本）
• MNNKit官方库托管在Maven Central上

工程build.gradle配置maven仓库：

allprojects {
    repositories {
        google()
        jcenter()
        // 国内访问推荐使用阿里云镜像加速
        maven { url "https://maven.aliyun.com/nexus/content/groups/public" }
      	// Maven Central
//        mavenCentral()
//        mavenLocal()
    }
}

app的build.gradle添加依赖：

dependencies {
    implementation 'com.alibaba.android.mnnkit:facedetection:0.1.0'
    implementation 'com.alibaba.android.mnnkit:handgesturedetection:0.1.0'
    implementation 'com.alibaba.android.mnnkit:portraitsegmentation:0.1.0'
}

Proguard

-dontwarn com.alibaba.android.mnnkit.**
-keep class com.alibaba.android.mnnkit.**{*;}

iOS

• 系统最低版本ios 8.0
• 从0.0.4版本开始，MNNKit系列SDK均为静态库

source 'https://github.com/CocoaPods/Specs.git'
platform :ios

target 'MNNKitDemo' do
    platform :ios, '8.0'
    
    # 人脸检测
    pod 'MNNFaceDetection', '~> 0.0.4'
    # 手势识别
    pod 'MNNHandGestureDetection', '~> 0.0.4'
    # 人像分割
    pod 'MNNPortraitSegmentation', '~> 0.0.4'
    
end

Bitcode

目前MNNKit SDK均不支持bitcode，应用集成时候需关闭bitcode选项。

API

Kit的基本API只有三个，创建实例、推理、释放实例。使用流程也是按照这个顺序，如下图所示，其中推理时可输入视频、图片或其他格式的数据。

人脸检测API

手势识别API

人像分割API

隐私说明

默认情况下，MNNKit会收集SDK运行时的性能、稳定性等数据，帮助我们统计和分析问题，以在后续迭代中针对性地进行优化和改进。SDK不会收集其他任何无关的用户信息，相关协议请参考license。用户可以显式的调用API关闭该功能（不推荐）：

Android

MNNMonitor.java
/**
 * enable/disable collection of statistical information. Enable by default.
 * @param monitorEnable true or false
 */
public static void setMonitorEnable(boolean monitorEnable)

iOS

MNNMonitor.h
/// enable/disable collection of statistical information. Enable by default.
/// @param enable 
+ (void)setMonitorEnable:(BOOL)enable;

接入指南

MNNKit API中包含了inAngle和outAngle两个参数值，他们是用来做什么的？理解这个问题之前，我们不妨先了解下SDK处理的一般过程。

处理过程

如下是iOS和Android设备后置摄像头正向拍摄的场景，端上整个处理过程：

1. 设备预览和输出

这部分是从Camera获取数据，作为SDK的输入；同时在设备前端，要正确的预览给用户。

2. SDK检测

MNNKit SDK内部实现封装了算法的深度学习模型，运行在MNN引擎上，因此人脸检测也并非传统的图像处理，它有着机器学习所有的特性。算法在模型训练阶段使用的是正向的人脸数据集，因而这个模型只认识"正向"的人脸，如果输入是一张方向不对的人脸，可能就不会有检测结果，我们称之为"内容方向敏感"。MNNKit中人脸检测、手势识别、人像分割都属于"内容方向敏感"的类型。

1. 在MNN引擎执行推理之前，需要对原始的输入做预处理，保证输入数据中的人脸为正向
2. 推理完成后，产生了基于输入图像（预处理之后的）坐标系的关键点结果
3. 为了上层渲染方便，SDK会把关键点坐标变换到和屏幕渲染坐标系相同的方向

SDK参数中的inAngle参数就是用来控制将原始输入旋转到"内容正向"的角度，outAngle就是用来变换关键点坐标到屏幕渲染坐标系方向的角度！

从上图中可以看出，iOS在后置正向的情况下的输入角度为0，输出角度为0；而安卓输入角度为90，输出角度为0。

3. 结果渲染

SDK检测的结果是图像的特征描述，最简单的描述就是关键点的坐标，这些坐标都是在图像坐标系下产生的，也就是在最终输入到引擎的图片左上角为原点的坐标系下。比如输入的图像是1280*720，那么检测结果也是在这个坐标系下产生。

工程应用中，最后的结果关键点要显示在用户屏幕上，前端会使用一个用来渲染的"画布"，它可以是一个UI上用来显示的视图或其他组件，画布的尺寸由应用根据视觉设计自己定义。画布的坐标系我们统称为渲染坐标系，这一步要做的就是将关键点坐标从头像坐标系转换到渲染坐标系。

在SDK检测的最后一步，我们已经将关键点变换到和渲染坐标系相同的方向，因为两个坐标系的大小不一样，接下来只需要等比例映射坐标就行了。映射完后直接渲染到画布上，就完成了整个过程。

工程实践参考

上述我们以iOS和Android设备后置摄像头正向拍摄为例阐述，比较简单，实际的工程接入中，摄像头的正向角度会产生输出图像的角度，设备旋转会造成输出图片非内容正向，自动旋转开启会引起渲染坐标系的变化，等等，这些都是SDK之外工程上需要解决的问题。

MNNKit Demo中涵盖了工程实践中所有问题的综合解法，如输入角度、摄像头预览、结果渲染、自动旋转等等，是工程接入的最佳实践参考。如果不熟悉该如何处理，请阅读Demo中的代码示例，相信所有的问题都可以迎刃而解。

License

当您在软件中使用MNNKit相关SDK时，默认您已经阅读并同意协议《MNN Kit Terms of Service》

MNNKit 快速上手指南

MNNKit 是基于阿里开源推理引擎 MNN 的移动端 AI 应用层解决方案，提供人脸检测、手势识别、人像分割等开箱即用的 SDK，适用于 Android 和 iOS 开发。

环境准备

系统要求

• Android: 最低 API Level 16 (Android 4.1+)
• iOS: 最低 iOS 8.0
  • 注意: MNNKit SDK 不支持 Bitcode，集成时需在 Xcode 中关闭 Bitcode 选项。

前置依赖

• Android: Android Studio, Gradle
• iOS: CocoaPods, Xcode

安装步骤

MNNKit 的各业务 Kit（如人脸、手势、分割）相互独立，请根据需求选择集成。官方库托管在 Maven Central (Android) 和 CocoaPods (iOS)。

Android 集成

1. 配置仓库 在项目根目录的 build.gradle 中添加 Maven 仓库。国内开发者推荐使用阿里云镜像加速。

   allprojects {
       repositories {
           google()
           jcenter()
           // 国内访问推荐使用阿里云镜像加速
           maven { url "https://maven.aliyun.com/nexus/content/groups/public" }
           // Maven Central
           // mavenCentral()
           // mavenLocal()
       }
   }
   

2. 添加依赖 在 app 模块的 build.gradle 中添加所需 SDK 依赖（以 0.1.0 版本为例）：

   dependencies {
       implementation 'com.alibaba.android.mnnkit:facedetection:0.1.0'
       implementation 'com.alibaba.android.mnnkit:handgesturedetection:0.1.0'
       implementation 'com.alibaba.android.mnnkit:portraitsegmentation:0.1.0'
   }
   

3. 配置 Proguard 防止代码混淆导致 SDK 异常：

   -dontwarn com.alibaba.android.mnnkit.**
   -keep class com.alibaba.android.mnnkit.**{*;}
   

iOS 集成

1. 配置 Podfile 在项目的 Podfile 中添加以下配置（以 0.0.4 版本为例）：

   source 'https://github.com/CocoaPods/Specs.git'
   platform :ios
   
   target 'YourTargetName' do
       platform :ios, '8.0'
       
       # 人脸检测
       pod 'MNNFaceDetection', '~> 0.0.4'
       # 手势识别
       pod 'MNNHandGestureDetection', '~> 0.0.4'
       # 人像分割
       pod 'MNNPortraitSegmentation', '~> 0.0.4'
   end
   

2. 安装依赖 终端执行：

   pod update
   

基本使用

MNNKit 的核心 API 流程统一为三步：创建实例 -> 推理 -> 释放实例。

核心流程说明

1. 创建实例：初始化对应的 Detector 或 Segmenter。
2. 推理 (Inference)：
   • 输入数据可以是视频帧、图片等。
   • 关键参数 inAngle 与 outAngle：
     • inAngle: 用于将原始输入图像旋转至“内容正向”（模型训练时的标准方向）。
     • outAngle: 用于将推理得到的关键点坐标转换回屏幕渲染坐标系的方向。
     • 示例：Android 后置摄像头通常需设置 inAngle=90, outAngle=0；iOS 后置通常为 inAngle=0, outAngle=0。具体请参考 Demo 中的相机适配逻辑。
3. 释放实例：使用完毕后销毁对象，释放资源。

代码示例结构

Android (Java/Kotlin)

// 1. 创建实例 (以人脸检测为例)
FaceDetector detector = new FaceDetector();

// 2. 推理
// 准备输入数据及角度参数
// Result result = detector.detect(inputData, inAngle, outAngle);

// 3. 释放实例
detector.release();

iOS (Objective-C)

// 1. 创建实例
MNNFaceDetector *detector = [[MNNFaceDetector alloc] init];

// 2. 推理
// 准备输入数据及角度参数
// NSArray *results = [detector detect:image inAngle:0 outAngle:0];

// 3. 释放实例
[detector release];

隐私数据收集说明

默认情况下，SDK 会收集性能与稳定性数据以优化产品。如需关闭，可调用以下 API（不推荐）：

• Android: MNNMonitor.setMonitorEnable(false)
• iOS: [MNNMonitor setMonitorEnable:NO]

建议：初次接入请详细阅读并运行官方 Demo (MNNKitDemo)，其中包含了处理相机预览、自动旋转、坐标映射等工程最佳实践。