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选项。如果您需要使用自己的预编译版本，请随意替换它，如果不需要请跳过此步骤。
获取工程
您可以拉取稳定版本或开发版的工程代码到本地：
# 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的根目录下：
# 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:
# 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
- Recommended GCC version is 4.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
- Either GCC or Clang can be used (macOS does not require additional installation as Xcode is included)
- 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脚本快速编译:
cd InspireFace/
# Execute the local compilation script
bash command/build.sh
编译之后，您可以在构建目录中找到包含编译结果的本地文件。安装目录结构如下:
inspireface-linux
├── include
│ ├── herror.h
│ └── inspireface.h
└── lib
└── libInspireFace.so
- libInspireFace.so：编译的动态链接库.
- inspireface.h：头文件定义
- herror.h：引用错误号定义
Note: 更多平台的相关的详细编译过程您可以直接进入源代码仓库中。
[示例]如何使用
C/C++ API
要将InspireFace集成到C/ c++项目中，您只需要链接InspireFace库并包含适当的头文件。下面是一个展示人脸检测的基本例子:
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环境需要安装一些依赖项:
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设备部署 |
测试实例
