leon
2a1cfd230d
- 集成虹软 ArcSoft Face SDK，提供人脸检测、识别、活体检测功能 - 实现 Android 平台原生插件，包含 ArcPlugin 和 FaceEngineManager - 添加完整的人脸错误码枚举（586个错误码），覆盖 SDK 所有错误情况 - 创建人脸信息数据模型 FaceInfo，封装检测结果和特征数据 - 配置 Android 权限和依赖，包括相机、存储、网络等必要权限 - 添加方法通道实现，连接 Flutter 层与原生层通信 - 配置项目基础文件，包含 .gitignore、分析选项和元数据配置 - 实现单元测试框架，包含 Dart 和 Java 层的基本测试用例 - 添加示例应用配置，验证插件集成和基本功能使用 - 提供详细的开发指导文档 CLAUDE.md，说明架构和 API 使用方法
121 lines
5.4 KiB
Markdown
121 lines
5.4 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
Flutter 人脸识别插件，封装虹软 (ArcSoft) Face SDK，提供 Android 平台的人脸检测、识别、活体检测功能。
|
||
|
||
## Build Commands
|
||
|
||
```bash
|
||
# Analyze Dart code
|
||
flutter analyze
|
||
|
||
# Run Dart unit tests
|
||
flutter test
|
||
|
||
# Analyze example app
|
||
cd example && flutter analyze lib/main.dart
|
||
|
||
# Run example app on Android device
|
||
cd example && flutter run
|
||
|
||
# Build example APK
|
||
cd example && flutter build apk
|
||
```
|
||
|
||
## Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Flutter (Dart) │
|
||
│ ┌─────────────┐ ┌──────────────────┐ │
|
||
│ │ arc.dart │───▶│ ArcPlatform │ (abstract) │
|
||
│ │ (Public API)│ └────────┬─────────┘ │
|
||
│ └─────────────┘ │ │
|
||
│ ┌────────▼─────────┐ │
|
||
│ │ MethodChannelArc │ │
|
||
│ │ (Method Channel) │ │
|
||
│ └────────┬─────────┘ │
|
||
└─────────────────────────────┼───────────────────────────────┘
|
||
│ Method Channel: "arc"
|
||
┌─────────────────────────────┼───────────────────────────────┐
|
||
│ Android (Java) │
|
||
│ ┌────────▼─────────┐ │
|
||
│ │ ArcPlugin │ │
|
||
│ │ (Method Handler) │ │
|
||
│ └────────┬─────────┘ │
|
||
│ ┌────────▼─────────┐ │
|
||
│ │ FaceEngineManager│ (Singleton) │
|
||
│ └────────┬─────────┘ │
|
||
│ ┌────────▼─────────┐ │
|
||
│ │ ArcSoft SDK │ │
|
||
│ │ (arcsoft_face.jar)│ │
|
||
│ └──────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## Key Files
|
||
|
||
| Layer | File | Purpose |
|
||
|-------|------|---------|
|
||
| Public API | `lib/arc.dart` | 用户调用的主要接口 |
|
||
| Platform Interface | `lib/arc_platform_interface.dart` | 平台抽象接口定义 |
|
||
| Method Channel | `lib/arc_method_channel.dart` | Flutter 与原生通信 |
|
||
| Android Plugin | `android/src/.../ArcPlugin.java` | 处理 Method Channel 调用 |
|
||
| Engine Manager | `android/src/.../FaceEngineManager.java` | 虹软 SDK 单例管理 |
|
||
| Data Model | `android/src/.../FaceInfo.java` | 人脸信息数据模型 |
|
||
| Error Codes | `android/src/.../FaceErrorCode.java` | 586个错误码枚举 |
|
||
|
||
## Adding New API
|
||
|
||
1. **Dart Interface**: Add method to `arc_platform_interface.dart`
|
||
2. **Dart Implementation**: Add method to `arc_method_channel.dart`
|
||
3. **Public API**: Expose method in `arc.dart`
|
||
4. **Android Handler**: Add case in `ArcPlugin.java` `onMethodCall()`
|
||
5. **Android Logic**: Add method in `FaceEngineManager.java`
|
||
|
||
## ArcSoft SDK Configuration
|
||
|
||
SDK 需要三个密钥（从虹软控制台获取）:
|
||
- `appId`: 应用 ID
|
||
- `sdkKey`: SDK 密钥
|
||
- `activeKey`: 激活密钥
|
||
|
||
## API Methods
|
||
|
||
| Method | Purpose |
|
||
|--------|---------|
|
||
| `activeOnline()` | 在线激活 SDK |
|
||
| `init()` | 初始化人脸识别引擎 |
|
||
| `detectFaces()` | 人脸检测 + RGB 活体检测 |
|
||
| `extractFaceFeature()` | 提取人脸特征 (512字节) |
|
||
| `compareFaceFeature()` | 1:1 特征比对，返回相似度 |
|
||
| `registerFaceFeature()` | 注册特征到人脸库 (1:N) |
|
||
|
||
## Thresholds (Recommended by ArcSoft)
|
||
|
||
| 功能 | 阈值 |
|
||
|------|------|
|
||
| 人脸比对 (生活照) | 0.8 |
|
||
| 人脸比对 (证件照) | 0.82 |
|
||
| RGB 活体检测 | 0.5 |
|
||
| IR 活体检测 | 0.5 |
|
||
|
||
## Combined Mask Values
|
||
|
||
```java
|
||
ASF_FACE_DETECT = 0x00000001 // 人脸检测
|
||
ASF_FACE_RECOGNITION= 0x00000004 // 人脸识别
|
||
ASF_AGE = 0x00000008 // 年龄检测
|
||
ASF_GENDER = 0x00000010 // 性别检测
|
||
ASF_LIVENESS = 0x00000080 // RGB 活体检测
|
||
// 组合: 0x9D = 人脸检测 + 识别 + 年龄 + 性别 + 活体
|
||
```
|
||
|
||
## Image Format
|
||
|
||
- 格式: NV21 (Android camera default)
|
||
- 格式代码: 2050
|
||
- 宽度必须是4的倍数，高度必须是2的倍数 |