6.4 KiB
6.4 KiB
Face SDK 接口文档 (Java)
本文档详细说明了 face-sdk-v1.0.0.aar 提供的 Java 接口，供 Android 开发人员集成使用。
1. 核心类概览
| 类名 | 说明 |
|---|---|
com.bonuos.facesdk.FaceRecognizer |
人脸识别核心类。负责特征提取、人脸比对和识别。 |
com.bonuos.facesdk.LivenessDetector |
活体检测类。负责检测摄像头预览或图片中的人脸是否为活体。 |
com.bonuos.facesdk.SyncManager |
数据同步管理类。负责从服务器拉取最新的人脸数据库。 |
com.bonuos.facesdk.FaceRepository |
本地数据库仓库。提供对本地 SQLite 数据库的直接访问（通常不需要直接使用）。 |
2. 接口详解
2.1 FaceRecognizer (人脸识别)
负责加载本地人脸库并对输入的图像进行识别。
构造方法
public FaceRecognizer(Context context)
- 参数:
context- 应用程序上下文。 - 说明: 初始化 SDK 引擎，并从本地数据库加载所有人脸特征到内存缓存。
方法
recognize
public RecognitionResult recognize(Bitmap bitmap)
- 说明: 对输入图片进行人脸检测、特征提取，并与本地库进行比对。
- 参数:
bitmap- 包含人脸的图片（建议预处理为正向人脸）。 - 返回:
RecognitionResult对象。
setThreshold
public void setThreshold(float threshold)
- 说明: 设置识别的相似度阈值。
- 参数:
threshold- 浮点数 (0.0 - 1.0)。默认约为 0.65，建议根据实际场景微调。
reloadUsers
public synchronized void reloadUsers()
- 说明: 重新从数据库加载用户数据到内存。
- 场景: 当
SyncManager完成数据同步后调用，以刷新内存缓存。
extractFeature
public float[] extractFeature(Bitmap bitmap)
- 说明: 仅提取人脸特征向量，不进行比对。
- 返回: 特征数组
float[]，如果提取失败返回null。
release
public void release()
- 说明: 释放底层算法引擎资源。建议在
Activity.onDestroy()中调用。
2.2 LivenessDetector (活体检测)
基于 Silent-Face-Anti-Spoofing 模型的静默活体检测。
方法
init
public void init(Context context)
- 说明: 初始化活体检测模型。建议在子线程执行，因为加载模型可能耗时。
detect
public LivenessResult detect(Bitmap bitmap)
- 说明: 检测输入图片中的人脸活体得分。
- 参数:
bitmap- 待检测图片。 - 返回:
LivenessResult对象。包含活体得分和人脸位置。
release
public void release()
- 说明: 释放模型资源。
2.3 SyncManager (数据同步)
负责与后端服务器通信，更新本地人脸库。
构造方法
public SyncManager(Context context)
方法
syncData
public void syncData()
- 说明: 阻塞式方法（需要在子线程调用）。从服务器下载最新的用户列表和特征数据，并更新到本地数据库。
- 注意: 若需修改服务器地址，请修改源码中的
SYNC_URL常量或扩展该类。
3. 数据模型
3.1 RecognitionResult
识别结果封装类。
| 字段 | 类型 | 说明 |
|---|---|---|
success |
boolean |
识别是否成功。 |
user |
FaceRepository.FaceUser |
识别到的用户信息（仅当 success=true 时有效）。 |
similarity |
float |
相似度得分 (0.0 - 1.0)。 |
message |
String |
错误信息或提示。 |
3.2 LivenessResult
活体检测结果。
| 字段 | 类型 | 说明 |
|---|---|---|
score |
float |
活体得分。一般 > 0.9 可认为是活体，根据实际模型调整。 |
faceBox |
FaceBox |
检测到的人脸框坐标信息。 |
3.3 FaceRepository.FaceUser
单一用户实体。
| 字段 | 类型 | 说明 |
|---|---|---|
userId |
String |
用户唯一 ID。 |
name |
String |
用户姓名。 |
feature |
float[] |
512维人脸特征向量。 |
featureVersion |
String |
特征版本号。 |
4. 集成示例
步骤 1: 引入 AAR
将 face-sdk-v1.0.0.aar 放入 libs 目录，并在 build.gradle 中配置：
[!IMPORTANT] 关键依赖说明 由于 AAR 以本地文件方式引入，无法自动解析传递性依赖。必须手动添加以下 Gson 和 WebSocket 库，否则运行时会发生 Crash (ClassNotFoundException)。
dependencies {
implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.aar"))))
// [必须] JSON 解析库
implementation("com.google.code.gson:gson:2.10.1")
// [必须] 数据同步需要的 WebSocket
implementation("org.java-websocket:Java-WebSocket:1.5.4")
}
步骤 2: 完整调用流程
public class FaceAuthActivity extends AppCompatActivity {
private FaceRecognizer recognizer;
private LivenessDetector livenessDetector;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// 1. 初始化
recognizer = new FaceRecognizer(this);
livenessDetector = new LivenessDetector();
livenessDetector.init(this);
// 2. 开启线程进行识别
new Thread(() -> {
Bitmap captureInfo = getCameraFrame(); // 获取摄像头帧
// 2.1 活体检测
LivenessResult liveResult = livenessDetector.detect(captureInfo);
if (liveResult.score > 0.9f) {
// 2.2 人脸识别
RecognitionResult result = recognizer.recognize(captureInfo);
runOnUiThread(() -> {
if (result.success) {
Toast.makeText(this, "欢迎, " + result.user.name, Toast.LENGTH_SHORT).show();
} else {
Toast.makeText(this, "识别失败: " + result.message, Toast.LENGTH_SHORT).show();
}
});
}
}).start();
}
@Override
protected void onDestroy() {
super.onDestroy();
// 3. 释放资源
if (recognizer != null) recognizer.release();
if (livenessDetector != null) livenessDetector.release();
}
}