huangsheng/arc

Fork 0

Files

leon 3c2bb02e33 docs: map existing codebase

2026-03-30 15:21:07 +08:00

5.1 KiB

Raw Permalink Blame History

External Integrations

Analysis Date: 2026-03-30

APIs & External Services

人脸识别 SDK:

虹软 (ArcSoft) 人脸识别 SDK - 离线人脸检测、特征提取、活体检测
- SDK 库: arcsoft_face.jar, libarcsoft_face.so
- 版本: 基于 2024年1月版本
- Auth: 需要 AppId、SdkKey、ActiveKey（从虹软开放平台获取）
- 激活方式: 在线激活（FaceEngine.activeOnline()）
- 官方文档: https://ai.arcsoft.com.cn

图像处理工具:

虹软图像处理工具库 - 图像格式转换和处理
- SDK 库: arcsoft_image_util.jar, libarcsoft_image_util.so

Data Storage

Databases:

无数据库集成 - 人脸特征数据存储在内存中（人脸库）

Face Feature Database (In-Memory):

人脸库存储: 通过 FaceEngine.registerFaceFeature() 注册到 SDK 内部内存
数据结构: FaceFeatureInfo(searchId, featureData, faceTag)
搜索能力: 1:N 人脸搜索（SDK 内置）
注意: 人脸库数据在引擎释放后丢失，不持久化

File Storage:

虹软 SDK 激活文件存储于设备本地（SDK 自动管理）
位置: Android 设备内部存储（SDK 控制）

Caching:

None - 无缓存层

Authentication & Identity

Auth Provider:

虹软 SDK 激活机制 - 设备绑定激活
- Implementation: 在线激活验证 AppId + SdkKey + ActiveKey
- 激活文件: 设备指纹绑定，单设备单激活
- 错误处理: FaceErrorCode 枚举定义完整错误码映射

激活状态检查:

// 激活成功条件: errorCode == 0 或 errorCode == 90114 (已激活)
result['success'] = errorCode == 0 || errorCode == 90114;

激活流程:

调用 Arc.activeOnline(appId, sdkKey, activeKey)
Flutter MethodChannel 传递参数到 Android
Android 调用 FaceEngine.activeOnline(context, activeKey, appId, sdkKey)
SDK 与虹软服务器验证并生成激活文件
返回激活结果 Map

Monitoring & Observability

Error Tracking:

错误码枚举系统 - FaceErrorCode.java（完整错误码映射）
分类: 通用错误、SDK基础错误、人脸识别错误、激活错误、网络错误、离线授权错误

Logs:

Android Logcat 输出（FaceEngineManager.java 使用 android.util.Log）
Flutter debugPrint 输出（示例应用）
日志级别: Info, Error

关键日志点:

SDK 初始化结果: FaceEngineManager.init()
人脸检测结果: FaceEngineManager.detectFaces()
RGB 活体检测结果: FaceEngineManager.getLiveness()
特征提取结果: FaceEngineManager.extractFaceFeature()
人脸比对结果: FaceEngineManager.compareFaceFeature()

CI/CD & Deployment

Hosting:

本地 Flutter 插件包 - 不发布到 pub.dev（私有包）
publish_to: 'none'（示例应用）

CI Pipeline:

None - 无 CI 配置文件

Build Commands:

flutter pub get          # 获取依赖
flutter test             # 运行 Flutter 单元测试
flutter build apk        # 构建 Android APK
cd android && ./gradlew test  # 运行 Android 单元测试

Environment Configuration

Required env vars (SDK 激活):

AppId: 虹软开放平台申请的应用 ID
SdkKey: 虹软开放平台申请的 SDK 密钥
ActiveKey: 激活密钥（可选，部分场景需要）

示例应用配置（硬编码）:

// example/lib/main.dart
final String _appId = '4nPFuS2TYAQh9werHL2qbKjtTH9nnoixk7G6yqSUyjVH';
final String _sdkKey = 'aWMTT3coxNQFETg9f3BGHCiBznAApXmcHFF3J5yQbsZ';
final String _activeKey = 'NEAT7AU4KLCEK682';

Secrets location:

当前: 硬编码在示例应用（不推荐生产使用）
建议: 通过环境变量或安全存储传递

Webhooks & Callbacks

Incoming:

None - 无外部 webhook

Outgoing:

None - 无外部 API 调用（SDK 激活除外）

Flutter-Native Communication

Method Channel:

Channel 名称: 'arc'
定义文件: lib/arc_method_channel.dart
实现: MethodChannelArc 类

支持的方法:

方法名	功能	参数
`getPlatformVersion`	获取平台版本	无
`activeOnline`	SDK 在线激活	appId, sdkKey, activeKey
`init`	初始化人脸引擎	detectMode, orient, maxFaceNum, combinedMask
`detectFaces`	人脸检测+RGB活体	data, width, height, format
`extractFaceFeature`	特征提取	data, width, height, rect, faceId, extractType, mask
`compareFaceFeature`	特征比对	featureData1, featureData2, compareModel
`registerFaceFeature`	单张人脸注册	searchId, featureData, faceTag
`registerFaceFeatureBatch`	批量人脸注册	faceList

数据格式:

图像数据: NV21 格式（Uint8List）
特征数据: SDK 定义长度（Uint8List）
返回值: Map<String, dynamic> 格式统一

Image Format Requirements

NV21 格式约束:

图像宽度必须是 4 的倍数
图像高度必须是 2 的倍数（NV21 格式）
格式码: 2050 (FaceEngine.CP_PAF_NV21)

Camera Integration (Example):

使用 camera 插件获取摄像头图像流
ImageFormatGroup.nv21 设置图像格式
CameraPreviewScreen 处理实时图像流检测

Integration audit: 2026-03-30

5.1 KiB Raw Permalink Blame History Unescape Escape