218 lines
6.4 KiB
Markdown
218 lines
6.4 KiB
Markdown
# 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 (人脸识别)
|
|
|
|
负责加载本地人脸库并对输入的图像进行识别。
|
|
|
|
**构造方法**
|
|
|
|
```java
|
|
public FaceRecognizer(Context context)
|
|
```
|
|
- **参数**: `context` - 应用程序上下文。
|
|
- **说明**: 初始化 SDK 引擎，并从本地数据库加载所有人脸特征到内存缓存。
|
|
|
|
**方法**
|
|
|
|
#### recognize
|
|
```java
|
|
public RecognitionResult recognize(Bitmap bitmap)
|
|
```
|
|
- **说明**: 对输入图片进行人脸检测、特征提取，并与本地库进行比对。
|
|
- **参数**: `bitmap` - 包含人脸的图片（建议预处理为正向人脸）。
|
|
- **返回**: `RecognitionResult` 对象。
|
|
|
|
#### setThreshold
|
|
```java
|
|
public void setThreshold(float threshold)
|
|
```
|
|
- **说明**: 设置识别的相似度阈值。
|
|
- **参数**: `threshold` - 浮点数 (0.0 - 1.0)。默认约为 0.65，建议根据实际场景微调。
|
|
|
|
#### reloadUsers
|
|
```java
|
|
public synchronized void reloadUsers()
|
|
```
|
|
- **说明**: 重新从数据库加载用户数据到内存。
|
|
- **场景**: 当 `SyncManager` 完成数据同步后调用，以刷新内存缓存。
|
|
|
|
#### extractFeature
|
|
```java
|
|
public float[] extractFeature(Bitmap bitmap)
|
|
```
|
|
- **说明**: 仅提取人脸特征向量，不进行比对。
|
|
- **返回**: 特征数组 `float[]`，如果提取失败返回 `null`。
|
|
|
|
#### release
|
|
```java
|
|
public void release()
|
|
```
|
|
- **说明**: 释放底层算法引擎资源。建议在 `Activity.onDestroy()` 中调用。
|
|
|
|
---
|
|
|
|
### 2.2 LivenessDetector (活体检测)
|
|
|
|
基于 Silent-Face-Anti-Spoofing 模型的静默活体检测。
|
|
|
|
**方法**
|
|
|
|
#### init
|
|
```java
|
|
public void init(Context context)
|
|
```
|
|
- **说明**: 初始化活体检测模型。建议在子线程执行，因为加载模型可能耗时。
|
|
|
|
#### detect
|
|
```java
|
|
public LivenessResult detect(Bitmap bitmap)
|
|
```
|
|
- **说明**: 检测输入图片中的人脸活体得分。
|
|
- **参数**: `bitmap` - 待检测图片。
|
|
- **返回**: `LivenessResult` 对象。包含活体得分和人脸位置。
|
|
|
|
#### release
|
|
```java
|
|
public void release()
|
|
```
|
|
- **说明**: 释放模型资源。
|
|
|
|
---
|
|
|
|
### 2.3 SyncManager (数据同步)
|
|
|
|
负责与后端服务器通信，更新本地人脸库。
|
|
|
|
**构造方法**
|
|
|
|
```java
|
|
public SyncManager(Context context)
|
|
```
|
|
|
|
**方法**
|
|
|
|
#### syncData
|
|
```java
|
|
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)**。
|
|
|
|
```kotlin
|
|
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: 完整调用流程
|
|
|
|
```java
|
|
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();
|
|
}
|
|
}
|
|
```
|