# ArcFace.Net **Repository Path**: xtvj/ArcFace.Net ## Basic Information - **Project Name**: ArcFace.Net - **Description**: No description available - **Primary Language**: C# - **License**: MIT - **Default Branch**: dependabot/nuget/ColinChang.ArcFace.ImageSharp/SixLabors.ImageSharp-3.1.4 - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2024-10-08 - **Last Updated**: 2024-10-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ArcFace.Net 虹软人脸识别.NET(.Net 6)工具库。基于ArcFace 3.x C++ SDK, 支持Windows x86/x64和Linux x64. 支持人脸库属性检测、人脸特征提取、人脸库维护、人脸搜索、活体检测等功能。 ## 项目结构 * ArcFace.Core 人脸识别核心库，需要注入图像处理工具库后才可使用。 * ArcFace.ImageSharp 基于[ImageSharp](https://github.com/SixLabors/ImageSharp)图像处理的人脸识别库。 * ArcFace.SystemDrawing 基于[System.Drawing.Common](https://www.nuget.org/packages/System.Drawing.Common/)的图像处理的人脸识别库。 ## 版本差异 * 4.x 图像处理基于`System.Drawing.Common`开发，微软在 .Net 6 及之后版本已不再维护 * 5.x 图像处理基`ImageSharp`开发，仅支持.Net 6+ * 自定义实现。用户使用任意图像处理库（如` SkiaSharp`）实现`IImageProcessor`接口来自定义版本实现，此时仅需引用`ArcFace.Core`核心库即可。定制版本实现可以参照 4.x/5.x 版本代码。 ## 平台支持 1. Windows x86/x64 2. Linux x64 * 该程序基于ArcFace 3.x C++ SDK开发，`DllImport`引入C++动态库时依赖于Linux系统库(`libdl.so.2`)，因此低配Linux环境(如`alpine`等)可能存在兼容性问题。 经测试以下可以正常运行。 * `Debian 10 +` * `Ubuntu20.04 +` * `CentOS 8 +` 3. Docker 我们为本程序库的运行环境打包了Docker镜像，有需要的读者可以[点此获取](https://hub.docker.com/r/colinchang/arcface5)，也可以使用 [Dockerfiles](https://github.com/colin-chang/ArcFace.Net/tree/main/ColinChang.ArcFace.ImageSharp/Dockerfiles) 中的不同版本的 `Dockerfile` 文件自行编译。 ```bash # 5.x ImageSharp docker build -f ColinChang.ArcFace.ImageSharp/Dockerfiles/aspnet-6.0/Dockerfile -t colinchang/arcface5:aspnet-6.0 . docker build -f ColinChang.ArcFace.ImageSharp/Dockerfiles/runtime-6.0/Dockerfile -t colinchang/arcface5:runtime-6.0 . # 4.x SystemDrawing docker build -f ColinChang.ArcFace.SystemDrawing/Dockerfiles/aspnet-6.0/Dockerfile -t colinchang/arcface4:aspnet-6.0 . docker build -f ColinChang.ArcFace.SystemDrawing/Dockerfiles/runtime-6.0/Dockerfile -t colinchang/arcface4:runtime-6.0 . ``` ## Nuget * [ArcFace.Net.Core](https://www.nuget.org/packages/ArcFace.Net.Core/) * [ArcFace.Net](https://www.nuget.org/packages/ArcFace.Net/) ## SDK 从 [虹软开发者中心](https://ai.arcsoft.com.cn/ucenter/resource/build/index.html#/application)或[此处](https://github.com/colin-chang/ArcFace.Net/tree/main/ColinChang.ArcFace/Sdks)下载需要的SDK 3.x文件并放置同特定目录。 * Windows 需要将SDK dll文件拷贝到执行程序所在目录，或环境变量配置的目录 * **Linux 需要将SDK so文件拷贝到 `/lib` 系统程序目录，或环境变量配置的目录** 从 [虹软开发者中心](https://ai.arcsoft.com.cn/ucenter/resource/build/index.html#/application) 获取授权信息(AppId/SdkKey)，通过`ArcFaceOptions`传入配置。具体用法参见 [示例程序](https://github.com/colin-chang/ArcFace.Net/tree/main/ColinChang.ArcFace.Sample)。 ## 资源回收 * 工具中自动维护引擎池进行资源回收利用，无需手动管理。 * 工具支持多并发操作。 * 推荐使用**单例方式**使用。 * `ArcFace` 实现 `IDisposable`，使用完毕后需要 `Dispose()` 以销毁引擎回收其它相关内存。 ## 图像质量要求 * 图片尺寸大于2K且小于10MB * 图片格式支持 `.jpg`, `.png`, `.bmp` * 图片中人脸尺寸不小于50 x 50像素 * 建议待检测的图像人脸角度上、下、左、右转向小于30度 ## 人脸3D角度 俯仰角（pitch）， 横滚角（roll）， 偏航角（yaw） ![人脸3D角度](https://raw.githubusercontent.com/colin-chang/ArcFace.Net/main/3DAngle.png) ## 错误码 | 错误码名 | 十六进制 | 十进制 | 描述 | | :----------------------------------------- | :------- | :----- | :------------------------------------------------------- | | MOK | 0x0 | 0 | 成功 | | MERR_UNKNOWN | 0x1 | 1 | 错误原因不明 | | MERR_INVALID_PARAM | 0x2 | 2 | 无效的参数 | | MERR_UNSUPPORTED | 0x3 | 3 | 引擎不支持 | | MERR_NO_MEMORY | 0x4 | 4 | 内存不足 | | MERR_BAD_STATE | 0x5 | 5 | 状态错误 | | MERR_USER_CANCEL | 0x6 | 6 | 用户取消相关操作 | | MERR_EXPIRED | 0x7 | 7 | 操作时间过期 | | MERR_USER_PAUSE | 0x8 | 8 | 用户暂停操作 | | MERR_BUFFER_OVERFLOW | 0x9 | 9 | 缓冲上溢 | | MERR_BUFFER_UNDERFLOW | 0xA | 10 | 缓冲下溢 | | MERR_NO_DISKSPACE | 0xB | 11 | 存贮空间不足 | | MERR_COMPONENT_NOT_EXIST | 0xC | 12 | 组件不存在 | | MERR_GLOBAL_DATA_NOT_EXIST | 0xD | 13 | 全局数据不存在 | | MERR_FSDK_INVALID_APP_ID | 0x7001 | 28673 | 无效的 AppId | | MERR_FSDK_INVALID_SDK_ID | 0x7002 | 28674 | 无效的 SDKkey | | MERR_FSDK_INVALID_ID_PAIR | 0x7003 | 28675 | AppId 和 SDKKey 不匹配 | | MERR_FSDK_MISMATCH_ID_AND_SDK | 0x7004 | 28676 | SDKKey 和使用的 SDK 不匹配,请检查入参 | | MERR_FSDK_SYSTEM_VERSION_UNSUPPORTED | 0x7005 | 28677 | 系统版本不被当前 SDK 所支持 | | MERR_FSDK_LICENCE_EXPIRED | 0x7006 | 28678 | SDK 有效期过期，需要重新下载更新 | | MERR_FSDK_FR_INVALID_MEMORY_INFO | 0x12001 | 73729 | 无效的输入内存 | | MERR_FSDK_FR_INVALID_IMAGE_INFO | 0x12002 | 73730 | 无效的输入图像参数 | | MERR_FSDK_FR_INVALID_FACE_INFO | 0x12003 | 73731 | 无效的脸部信息 | | MERR_FSDK_FR_NO_GPU_AVAILABLE | 0x12004 | 73732 | 当前设备无 GPU 可用 | | MERR_FSDK_FR_MISMATCHED_FEATURE_LEVEL | 0x12005 | 73733 | 待比较的两个人脸特征的版本不一致 | | MERR_FSDK_FACEFEATURE_UNKNOWN | 0x14001 | 81921 | 人脸特征检测错误未知 | | MERR_FSDK_FACEFEATURE_MEMORY | 0x14002 | 81922 | 人脸特征检测内存错误 | | MERR_FSDK_FACEFEATURE_INVALID_FORMAT | 0x14003 | 81923 | 人脸特征检测格式错误 | | MERR_FSDK_FACEFEATURE_INVALID_PARAM | 0x14004 | 81924 | 人脸特征检测参数错误 | | MERR_FSDK_FACEFEATURE_LOW_CONFIDENCE_LEVEL | 0x14005 | 81925 | 人脸特征检测结果置信度低 | | MERR_ASF_EX_FEATURE_UNSUPPORTED_ON_INIT | 0x15001 | 86017 | Engine 不支持的检测属性 | | MERR_ASF_EX_FEATURE_UNINITED | 0x15002 | 86018 | 需要检测的属性未初始化 | | MERR_ASF_EX_FEATURE_UNPROCESSED | 0x15003 | 86019 | 待获取的属性未在 process 中处理过 | | MERR_ASF_EX_FEATURE_UNSUPPORTED_ON_PROCESS | 0x15004 | 86020 | PROCESS 不支持的检测属性，例如 FR，有自己独立的 处理函数 | | MERR_ASF_EX_INVALID_IMAGE_INFO | 0x15005 | 86021 | 无效的输入图像 | | MERR_ASF_EX_INVALID_FACE_INFO | 0x15006 | 86022 | 无效的脸部信息 | | MERR_ASF_ACTIVATION_FAIL | 0x16001 | 90113 | SDK 激活失败，请打开读写权限 | | MERR_ASF_ALREADY_ACTIVATED | 0x16002 | 90114 | SDK 已激活 | | MERR_ASF_NOT_ACTIVATED | 0x16003 | 90115 | SDK 未激活 | | MERR_ASF_SCALE_NOT_SUPPORT | 0x16004 | 90116 | detectFaceScaleVal 不支持 | | MERR_ASF_ACTIVEFILE_SDKTYPE_MISMATCH | 0x16005 | 90117 | 激活文件与 SDK 类型不匹配，请确认使用的 sdk | | MERR_ASF_DEVICE_MISMATCH | 0x16006 | 90118 | 设备不匹配 | | MERR_ASF_UNIQUE_IDENTIFIER_ILLEGAL | 0x16007 | 90119 | 唯一标识不合法 | ## 问题 * 人脸检测和特性提取目前进识别到的人脸角度不准确，目前识别到的角度均为0度。 * 视频模式人脸追踪未开发 * 活体检测未开发 * 如图运行提示激活失败或SDK已过期，尝试自行下载并更新替换C++ SDK对应`.so/.dll`动态库 ## 参考文档 https://github.com/colin-chang/ArcFace.Net/blob/main/sdk_3.0.pdf