leon
184c3a9f16
- 添加注册按钮，点击生成随机人脸ID（格式：F + 8位数字） - 实时显示检测到的人脸对应的ID - 使用彩色标签区分已注册（绿色）和未注册（橙色）状态 Quick task: 260330-ld1
163 lines
4.7 KiB
Markdown
163 lines
4.7 KiB
Markdown
# Phase 1: 新增虹软人脸注册接口
|
||
|
||
## 目标
|
||
在Android端新增虹软SDK的1:N人脸注册功能，支持单张和批量注册人脸特征到人脸库，供后续人脸搜索使用。
|
||
|
||
## 背景
|
||
|
||
### 现有代码结构
|
||
```
|
||
Flutter层 (lib/arc.dart)
|
||
↓ MethodChannel
|
||
Android插件层 (ArcPlugin.java)
|
||
↓
|
||
人脸引擎管理 (FaceEngineManager.java)
|
||
↓
|
||
虹软SDK (FaceEngine)
|
||
```
|
||
|
||
### 已实现功能
|
||
- ✅ `activeOnline` - SDK在线激活
|
||
- ✅ `init` - 引擎初始化
|
||
- ✅ `detectFaces` - 人脸检测 + RGB活体
|
||
- ✅ `extractFaceFeature` - 特征提取
|
||
- ✅ `compareFaceFeature` - 1:1特征比对
|
||
|
||
### 待实现功能
|
||
- ❌ `registerFaceFeature` - 注册人脸到1:N库
|
||
- ❌ 批量注册支持
|
||
|
||
---
|
||
|
||
## 虹软SDK接口说明
|
||
|
||
根据虹软文档（`docs/虹软人脸识别接口文档.md`）：
|
||
|
||
### registerFaceFeature（单张）
|
||
```java
|
||
int registerFaceFeature(FaceFeatureInfo faceFeatureInfo)
|
||
```
|
||
|
||
**参数说明：**
|
||
| 参数 | 类型 | 描述 |
|
||
|------|------|------|
|
||
| faceFeatureInfo | FaceFeatureInfo | 人脸搜索信息 |
|
||
|
||
**FaceFeatureInfo 结构：**
|
||
- `searchId` - 唯一标识符
|
||
- `featureData` - 人脸特征数据
|
||
- `faceTag` - 附属信息（可选）
|
||
|
||
**返回值：** 成功返回 `ErrorInfo.MOK`（0）
|
||
|
||
### registerFaceFeature（批量）
|
||
```java
|
||
int registerFaceFeature(List<FaceFeatureInfo> faceFeatureInfoList)
|
||
```
|
||
|
||
---
|
||
|
||
## 实现任务
|
||
|
||
### Task 1: FaceEngineManager.java 新增人脸注册方法
|
||
|
||
**文件：** `android/src/main/java/com/xiarui/arc/FaceEngineManager.java`
|
||
|
||
**新增方法：**
|
||
|
||
```java
|
||
/**
|
||
* 注册单张人脸特征到人脸库
|
||
* @param searchId 唯一标识符（用于后续搜索匹配）
|
||
* @param featureData 人脸特征数据（从extractFaceFeature获取）
|
||
* @param faceTag 附属信息（可选，如用户名、员工ID等）
|
||
* @return 错误码（0表示成功）
|
||
*/
|
||
public int registerFaceFeature(int searchId, byte[] featureData, String faceTag)
|
||
|
||
/**
|
||
* 批量注册人脸特征到人脸库
|
||
* @param faceInfoList 人脸信息列表，每项包含searchId、featureData、faceTag
|
||
* @return 错误码（0表示成功）
|
||
*/
|
||
public int registerFaceFeatureBatch(List<Map<String, Object>> faceInfoList)
|
||
```
|
||
|
||
### Task 2: ArcPlugin.java 新增MethodChannel处理
|
||
|
||
**文件：** `android/src/main/java/com/xiarui/arc/ArcPlugin.java`
|
||
|
||
**新增处理：**
|
||
|
||
1. 在 `onMethodCall` 的 switch 中添加：
|
||
- `registerFaceFeature` - 单张注册
|
||
- `registerFaceFeatureBatch` - 批量注册
|
||
|
||
2. 实现处理方法：
|
||
```java
|
||
private void handleRegisterFaceFeature(MethodCall call, Result result)
|
||
private void handleRegisterFaceFeatureBatch(MethodCall call, Result result)
|
||
```
|
||
|
||
### Task 3: Flutter层API暴露
|
||
|
||
**文件：** `lib/arc.dart`
|
||
|
||
**新增方法：**
|
||
|
||
```dart
|
||
/// 注册单张人脸特征到人脸库
|
||
/// [searchId] 唯一标识符（用于后续搜索匹配）
|
||
/// [featureData] 人脸特征数据（从extractFaceFeature获取）
|
||
/// [faceTag] 附属信息（可选）
|
||
/// 返回包含 success, errorCode, message 的 Map
|
||
Future<Map<String, dynamic>?> registerFaceFeature({
|
||
required int searchId,
|
||
required Uint8List featureData,
|
||
String? faceTag,
|
||
})
|
||
|
||
/// 批量注册人脸特征到人脸库
|
||
/// [faceList] 人脸列表，每项包含 searchId, featureData, faceTag(可选)
|
||
/// 返回包含 success, errorCode, message 的 Map
|
||
Future<Map<String, dynamic>?> registerFaceFeatureBatch({
|
||
required List<Map<String, dynamic>> faceList,
|
||
})
|
||
```
|
||
|
||
### Task 4: 更新 arc_method_channel.dart
|
||
|
||
**文件：** `lib/arc_method_channel.dart`
|
||
|
||
新增对应的 MethodChannel 调用实现。
|
||
|
||
---
|
||
|
||
## 验收标准
|
||
|
||
1. ✅ 单张人脸注册成功后，可通过 `searchId` 在人脸库中找到对应特征
|
||
2. ✅ 批量注册支持一次注册多张人脸
|
||
3. ✅ 重复 `searchId` 注册时返回适当的错误提示（虹软SDK会忽略重复）
|
||
4. ✅ 参数校验：`searchId` 有效、`featureData` 非空
|
||
5. ✅ Flutter层可正常调用并获取返回结果
|
||
6. ✅ 代码包含完整的方法级注释
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **重复注册**：根据虹软文档，如果底库中已存在相同 `searchId`，SDK会忽略。如需更新，需调用 `updateFaceFeature` 接口。
|
||
|
||
2. **引擎初始化**：人脸注册功能需要引擎初始化时包含 `ASF_FACE_RECOGNITION` 属性（当前默认掩码 `0x85` 已包含）。
|
||
|
||
3. **特征数据来源**：`featureData` 需要通过 `extractFaceFeature` 接口获取，且建议使用 `extractType=0`（REGISTER模式）提取的特征。
|
||
|
||
4. **人脸库规模**：虹软推荐人脸库在1万以内效果更佳。
|
||
|
||
---
|
||
|
||
## 依赖文件
|
||
|
||
- 虹软SDK: `android/libs/arcsoft_face.jar`
|
||
- 错误码定义: `android/src/main/java/com/xiarui/arc/FaceErrorCode.java`
|
||
- 接口文档: `docs/虹软人脸识别接口文档.md` |