InspireFace-商用级的跨平台开源人脸分析SDK

InspireFaceSDK是由insightface开发的⼀款⼈脸识别软件开发⼯具包（SDK）。它提供了⼀系列功能，可以满⾜各种应⽤场景下的⼈脸识别需求，包括但不限于闸机、⼈脸⻔禁、⼈脸验证等。

该SDK包含了多种常⽤的⼈脸识别算法，涵盖了⼈脸检测、⼈脸属性分析、⼈脸特征提取和⼈脸⽐对等功能。这些算法经过精⼼设计，具备业界领先的⼈脸识别能⼒和算法精度⽔平。为了满⾜不同的部署需求，InspireFaceSDK提供了四种不同平台的部署选项。

这些选项涵盖了各种推理场景，包括闸机芯⽚、端侧设备（如智能⼿机、平板电脑）、CPU（中央处理器）和服务器（CUDA）、NPU（神经处理单元）等。开发⼈员可以根据实际情况选择适合⾃⼰应⽤的部署⽅案。

如何获取

你可以直接从insightface.ai进入到仓库中获取到InspireFaceSDK的稳定版本的源代码；
如果你持续关注代码更新动态，你可以从InspireFace的开发仓库进入获取到开发版本的资源；

功能介绍

InspireFaceSDK目前支持以下的功能，并且有更多的功能正在开发中：

Index	Function	Adaptation	Note
1	人脸检测	支持	支持多种尺度图像的输入
2	稠密关键点检测	支持
3	人脸识别	支持	基于arcface的高精度模型
4	人脸跟踪	支持	拥有多种跟踪模式
5	口罩检测	支持
6	静默人脸活体检测	支持	MiniVision
7	质量分析	支持
8	头部姿态估计	支持
9	属性分析	支持	年龄、种族、性别等等
10	表情与动作分析	开发中	眨眼、摇头、点头
11	人脸红外活体检测	开发中

平台与架构的支持

我们已经完成了跨各种操作系统和CPU架构的软件适配和测试。这包括对Linux、macOS、iOS和Android等平台的兼容性验证，以及对特定硬件如Rockchip部分设备支持的测试，以确保在不同环境下稳定运行。

No.	Operating System	CPU Architecture	Special Device Support	Adapted	Passed Tests
1	Linux	ARMv7	-	已适配	通过离线测试
2		ARMv8	-	已适配	通过离线测试
3		x86/x86_64	-	已适配	通过在线测试
4		ARMv7	RV1109RV1126	已适配	通过离线测试
5		x86/x86_64	CUDA	已适配	通过离线测试
6	macOS	Intel x86	-	已适配	通过离线测试
7		Apple Silicon	-	已适配	通过离线测试
8	iOS	ARM	-	已适配	通过离线测试
9	Android	ARMv7	-	已适配
10		ARMv8	-	已适配

[编译]准备工作

安装OpenCV

如果您打算在本地或服务器上使用SDK，请确保已经在主机设备上安装了OpenCV ，以便在编译过程中成功链接。对于交叉编译目标，如Android或ARM嵌入式板，您可以使用3rdparty/ inspirreface -precompile/ OpenCV /提供的预编译OpenCV库，所以可以跳过此步骤。

安装MNN

3rdparty 目录已经包含了MNN库，并指定了一个特定的版本作为稳定版本。如果您需要在编译期间启用或禁用其他配置选项，您可以参考MNN提供的CMake选项。如果您需要使用自己的预编译版本，请随意替换它，如果不需要请跳过此步骤。

获取工程

您可以拉取稳定版本或开发版的工程代码到本地：

bash 复制代码

# Pull the stable version
git clone https://github.com/deepinsight/insightface
cd insightface/cpp-package/inspireface/

# or, Pull the develop version
git clone https://github.com/HyperInspire/InspireFace

拉取第三方依赖

在编译前必须要拉取第三方依赖库到inspireface的根目录下：

bash 复制代码

# Must enter this directory
cd InspireFace
# Clone the repository and pull submodules
git clone --recurse-submodules https://github.com/HyperInspire/3rdparty.git

如果你需要更新3rdpart仓库以确保它是最新的，或者如果你在初始拉取时没有使用------recursive 参数，你可以运行git submodule update------init------recursive:

bash 复制代码

# Must enter this directory
cd InspireFace
# If you're not using recursive pull
git clone https://github.com/HyperInspire/3rdparty.git

cd 3rdparty
git pull
# Update submodules
git submodule update --init --recursive

环境要求

目前InspireFace支持的宿主机设备仅有Linux和MacOS两个系统，请确保您的计算机符合以下配置需求：

CMake (version 3.10 or higher)
OpenCV (version 4.20 or higher)
- Use the specific OpenCV-SDK supported by each target platform such as Android, iOS, and Linux.
NDK (version 16 or higher, only required for Android)
MNN (version 1.4.0 or higher)
C++ Compiler
- Either GCC or Clang can be used (macOS does not require additional installation as Xcode is included)
  - Recommended GCC version is 4.9 or higher
    - Note that in some distributions, GCC (GNU C Compiler) and G++ (GNU C++ Compiler) are installed separately.
    - For instance, on Ubuntu, you need to install both gcc and g++
  - Recommended Clang version is 3.9 or higher
- arm-linux-gnueabihf (for RV1109/RV1126)
  - Prepare the cross-compilation toolchain in advance, such as gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf
CUDA (version 10.1 or higher)
- GPU-based inference requires installing NVIDIA's CUDA dependencies on the device.
Eigen3
- If you need to use the tracking-by-detection feature, you must have Eigen3 installed in advance.
RKNN
- Adjust and select versions currently supported for specific requirements.

[编译]开始编译

工程采用CMake作为构建工具，CMake的选项用于控制编译阶段的各种细节。请根据您的实际需求进行选择。您可以查看参数表CMake Option。

Linux/MacOS编译

确保安装了OpenCV，就可以开始编译过程了。如果您使用的是macOS或Linux，您可以使用项目根目录下command 文件夹中提供的shell脚本快速编译:

bash 复制代码

cd InspireFace/
# Execute the local compilation script
bash command/build.sh

编译之后，您可以在构建目录中找到包含编译结果的本地文件。安装目录结构如下:

bash 复制代码

inspireface-linux
   ├── include
   │   ├── herror.h
   │   └── inspireface.h
   └── lib
       └── libInspireFace.so

libInspireFace.so：编译的动态链接库.
inspireface.h：头文件定义
herror.h：引用错误号定义

++Note: 更多平台的相关的详细编译过程您可以直接进入源代码仓库中。++

[示例]如何使用

C/C++ API

要将InspireFace集成到C/ c++项目中，您只需要链接InspireFace库并包含适当的头文件。下面是一个展示人脸检测的基本例子:

c 复制代码

HResult ret;
// The resource file must be loaded before it can be used
ret = HFLaunchInspireFace(packPath);
if (ret != HSUCCEED) {
    std::cout << "Load Resource error: " << ret << std::endl;
    return ret;
}

// Enable the functions in the pipeline: mask detection, live detection, and face quality detection
HOption option = HF_ENABLE_QUALITY | HF_ENABLE_MASK_DETECT | HF_ENABLE_LIVENESS;
// Non-video or frame sequence mode uses IMAGE-MODE, which is always face detection without tracking
HFDetectMode detMode = HF_DETECT_MODE_IMAGE;
// Maximum number of faces detected
HInt32 maxDetectNum = 5;
// Handle of the current face SDK algorithm context
HFSession session = {0};
ret = HFCreateInspireFaceSessionOptional(option, detMode, maxDetectNum, -1, -1, &session);
if (ret != HSUCCEED) {
    std::cout << "Create FaceContext error: " << ret << std::endl;
    return ret;
}

// Load a image
cv::Mat image = cv::imread(sourcePath);
if (image.empty()) {
    std::cout << "The source entered is not a picture or read error." << std::endl;
    return 1;
}
// Prepare an image parameter structure for configuration
HFImageData imageParam = {0};
imageParam.data = image.data;       // Data buffer
imageParam.width = image.cols;      // Target view width
imageParam.height = image.rows;      // Target view width
imageParam.rotation = HF_CAMERA_ROTATION_0;      // Data source rotate
imageParam.format = HF_STREAM_BGR;      // Data source format

// Create an image data stream
HFImageStream imageHandle = {0};
ret = HFCreateImageStream(&imageParam, &imageHandle);
if (ret != HSUCCEED) {
    std::cout << "Create ImageStream error: " << ret << std::endl;
    return ret;
}

// Execute HF_FaceContextRunFaceTrack captures face information in an image
HFMultipleFaceData multipleFaceData = {0};
ret = HFExecuteFaceTrack(session, imageHandle, &multipleFaceData);
if (ret != HSUCCEED) {
    std::cout << "Execute HFExecuteFaceTrack error: " << ret << std::endl;
    return ret;
}
// Print the number of faces detected
auto faceNum = multipleFaceData.detectedNum;
std::cout << "Num of face: " << faceNum << std::endl;

ret = HFReleaseImageStream(imageHandle);
if (ret != HSUCCEED) {
    printf("Release image stream error: %lu\n", ret);
}
// The memory must be freed at the end of the program
ret = HFReleaseInspireFaceSession(session);
if (ret != HSUCCEED) {
    printf("Release session error: %lu\n", ret);
    return ret;
}

Note: 更多使用相关的详细方法您可以直接进入源代码仓库中查看。

Python Native API

InspireFace提供了一个Python API，允许更有效地使用InspireFace库。编译完动态链接库后，你需要将其符号链接或复制到根目录下的python/inspireface/modules/core 目录下。然后你可以通过导航到**<python/>**目录开始测试。你的Python环境需要安装一些依赖项:

python 复制代码

import cv2
import inspireface as ifac
from inspireface.param import *

# Step 1: Initialize the SDK and load the algorithm resource files.
resource_path = "pack/Pikachu"
ret = ifac.launch(resource_path)
assert ret, "Launch failure. Please ensure the resource path is correct."

# Optional features, loaded during session creation based on the modules specified.
opt = HF_ENABLE_NONE
session = ifac.InspireFaceSession(opt, HF_DETECT_MODE_IMAGE)

# Load the image using OpenCV.
image = cv2.imread(image_path)
assert image is not None, "Please check that the image path is correct."

# Perform face detection on the image.
faces = session.face_detection(image)
print(f"face detection: {len(faces)} found")

# Copy the image for drawing the bounding boxes.
draw = image.copy()
for idx, face in enumerate(faces):
    print(f"{'==' * 20}")
    print(f"idx: {idx}")
    # Print Euler angles of the face.
    print(f"roll: {face.roll}, yaw: {face.yaw}, pitch: {face.pitch}")
    # Draw bounding box around the detected face.
    x1, y1, x2, y2 = face.location
    cv2.rectangle(draw, (x1, y1), (x2, y2), (0, 0, 255), 2)

Note: 仓库中的会提供更多的其他平台下的使用方法，我们推荐您使用最新的代码进行集成

[快捷]直接下载预编译的库

如果你想快速体验来节约编译的时间你可以跳过编译步骤，直接通过开发仓库的Release页面下载我们提供的最新的发行版SDK，其中涵盖了大部分的平台支持，所有的预编译库均是通过Github Actions进行持续集成发布，已经通过了测试。

模型列表

InspireFace目前提供了多款模型应对不同的使用场景，目前涵盖了移动端、服务端和部分嵌入式设备端，您可以进入到我们的Github页面进行更详细的了解和下载体验：

Name	Supported Devices	Note
Pikachu	CPU	适合移动端设备部署
Megatron	CPU, GPU	适合移动端、服务端和携GPU设备部署
Gundam-RV1109	RKNPU	支持RK1109/1126设备部署

InspireFace-商用级的跨平台开源人脸分析SDK