更新README
This commit is contained in:
parent
9b0106b52b
commit
290360c4f0
|
|
@ -1,7 +1,9 @@
|
|||
人脸识别 Android SDK 集成指南 (V1.0)
|
||||
|
||||
# 人脸识别 Android SDK 集成指南 (V1.0)
|
||||
|
||||
本文档为人脸识别 C++ 核心库 (libface_sdk_jni.so) 提供了详尽的 Android 集成步骤和 API 使用说明。
|
||||
|
||||
1. 概述
|
||||
## 1. 概述
|
||||
本 SDK 提供了在 Android 设备上本地运行的高性能人脸识别功能。SDK 核心基于 C++ 实现，1:1 转译自 Python 端的 7 模型推理管线，确保了特征向量的完全兼容。
|
||||
|
||||
SDK 提供的主要 Java API 接口包括：
|
||||
|
|
@ -19,7 +21,7 @@ C++ 核心: 所有计算均在 C++ 层完成，性能高，内存可控。
|
|||
|
||||
手动捆绑: SDK 手动捆绑了所有必要的依赖库 (ONNX Runtime, OpenCV, C++ STL)，确保了在不同设备上的一致性，避免了因 Gradle 依赖版本不匹配导致的崩溃。
|
||||
|
||||
2. SDK 包内容
|
||||
## 2. SDK 包内容
|
||||
分发的 SDK 包含三个部分：
|
||||
|
||||
1. Java 接口
|
||||
|
|
@ -46,7 +48,8 @@ SDK_Models/
|
|||
├── fsanet-conv.onnx
|
||||
├── fsanet-var.onnx
|
||||
└── model_gray_mobilenetv2_rotcls.onnx
|
||||
3. 集成指南
|
||||
|
||||
## 3. 集成指南
|
||||
请按照以下步骤将 SDK 集成到您的 Android Studio 项目中。
|
||||
|
||||
步骤 1: 复制 Java 接口
|
||||
|
|
@ -90,12 +93,18 @@ SDK_Models/
|
|||
如果是 build.gradle.kts (Kotlin 脚本):
|
||||
|
||||
Kotlin
|
||||
```
|
||||
android {
|
||||
|
||||
```android {
|
||||
// ... (namespace, compileSdk, 等)
|
||||
|
||||
defaultConfig {
|
||||
// ... (applicationId, minSdk, targetSdk, 等)
|
||||
|
||||
// 强制 Gradle 只打包和使用 arm64-v8a 架构的库
|
||||
// 这可以防止在 x86 模拟器上发生库不匹配的崩溃
|
||||
ndk {
|
||||
abiFilters.add("arm64-v8a")
|
||||
}
|
||||
}
|
||||
|
||||
// (保持这个 sourceSets 块不变，即使它看起来是空的)
|
||||
|
|
@ -106,20 +115,14 @@ android {
|
|||
}
|
||||
}
|
||||
|
||||
// 强制 Gradle 只打包和使用 arm64-v8a 架构的库
|
||||
// 这可以防止在 x86 模拟器上发生库不匹配的崩溃
|
||||
ndk {
|
||||
abiFilters.add("arm64-v8a")
|
||||
}
|
||||
|
||||
|
||||
// ... (buildTypes, compileOptions, 等)
|
||||
}
|
||||
```
|
||||
}```
|
||||
如果是 build.gradle (Groovy 脚本):
|
||||
|
||||
Groovy
|
||||
```
|
||||
android {
|
||||
```android {
|
||||
// ... (namespace, compileSdk, 等)
|
||||
|
||||
defaultConfig {
|
||||
|
|
@ -140,8 +143,7 @@ android {
|
|||
|
||||
// ... (buildTypes, compileOptions, 等)
|
||||
}
|
||||
```
|
||||
点击 "Sync Now" 同步您的项目。
|
||||
```点击 "Sync Now" 同步您的项目。
|
||||
|
||||
至此，集成已全部完成！
|
||||
|
||||
|
|
@ -152,8 +154,7 @@ FaceSDKWrapper.java 会自动处理模型复制和 C++ 库加载。
|
|||
您必须在后台线程中初始化 SDK，因为它包含耗时的模型复制操作（仅限首次启动）。
|
||||
|
||||
Java
|
||||
```
|
||||
import com.facesdk.wrapper.FaceSDKWrapper; // 确保导入您修改了包名的类
|
||||
```import com.facesdk.wrapper.FaceSDKWrapper; // 确保导入您修改了包名的类
|
||||
|
||||
public class MyApplication extends Application {
|
||||
|
||||
|
|
@ -181,16 +182,14 @@ public class MyApplication extends Application {
|
|||
public FaceSDKWrapper getSdkWrapper() {
|
||||
return (isSdkInitialized) ? sdkWrapper : null;
|
||||
}
|
||||
}
|
||||
```
|
||||
}```
|
||||
(您也可以不在 Application 中初始化，而是在 Activity 中，如我们的测试项目所示)
|
||||
|
||||
2. 提取特征 (必须在后台线程)
|
||||
特征提取是一个CPU 密集型操作（运行 7 个模型）。严禁在 UI 主线程上调用它，否则会导致 App 冻结。
|
||||
|
||||
Java
|
||||
```
|
||||
// (在您的 Activity 或 ViewModel 中)
|
||||
```// (在您的 Activity 或 ViewModel 中)
|
||||
// 假设您已从 Application 中获取了 sdkWrapper 实例
|
||||
|
||||
public void runExtraction(Bitmap faceBitmap) {
|
||||
|
|
@ -215,31 +214,27 @@ public void runExtraction(Bitmap faceBitmap) {
|
|||
}
|
||||
});
|
||||
}).start();
|
||||
}
|
||||
```
|
||||
}```
|
||||
3. 比较特征
|
||||
这是一个非常快速的操作，可以在任何线程上调用。
|
||||
|
||||
Java
|
||||
```
|
||||
float[] featureA = ... // (来自 extractFeature)
|
||||
```float[] featureA = ... // (来自 extractFeature)
|
||||
float[] featureB = ... // (来自数据库)
|
||||
|
||||
float similarity = sdkWrapper.compare(featureA, featureB);
|
||||
|
||||
// 相似度是一个 -1.0 到 1.0 之间的浮点数 (余弦相似度)
|
||||
Log.i("MyActivity", "人脸相似度: " + similarity);
|
||||
```
|
||||
Log.i("MyActivity", "人脸相似度: " + similarity);```
|
||||
4. 释放 SDK
|
||||
在您的主 Activity (或 Application) 退出时，调用 release() 来释放 C++ 占用的内存。
|
||||
|
||||
Java
|
||||
```
|
||||
// (在您的 MainActivity 中)
|
||||
```// (在您的 MainActivity 中)
|
||||
@Override
|
||||
protected void onDestroy() {
|
||||
super.onDestroy();
|
||||
if (sdkWrapper != null) {
|
||||
sdkWrapper.release();
|
||||
}
|
||||
}```
|
||||
}```
|
||||
|
|
|
|||
59
README.md
59
README.md
|
|
@ -1,7 +1,9 @@
|
|||
人脸识别 Android SDK 集成指南 (V1.0)
|
||||
|
||||
# 人脸识别 Android SDK 集成指南 (V1.0)
|
||||
|
||||
本文档为人脸识别 C++ 核心库 (libface_sdk_jni.so) 提供了详尽的 Android 集成步骤和 API 使用说明。
|
||||
|
||||
1. 概述
|
||||
## 1. 概述
|
||||
本 SDK 提供了在 Android 设备上本地运行的高性能人脸识别功能。SDK 核心基于 C++ 实现，1:1 转译自 Python 端的 7 模型推理管线，确保了特征向量的完全兼容。
|
||||
|
||||
SDK 提供的主要 Java API 接口包括：
|
||||
|
|
@ -19,7 +21,7 @@ C++ 核心: 所有计算均在 C++ 层完成，性能高，内存可控。
|
|||
|
||||
手动捆绑: SDK 手动捆绑了所有必要的依赖库 (ONNX Runtime, OpenCV, C++ STL)，确保了在不同设备上的一致性，避免了因 Gradle 依赖版本不匹配导致的崩溃。
|
||||
|
||||
2. SDK 包内容
|
||||
## 2. SDK 包内容
|
||||
分发的 SDK 包含三个部分：
|
||||
|
||||
1. Java 接口
|
||||
|
|
@ -46,7 +48,8 @@ SDK_Models/
|
|||
├── fsanet-conv.onnx
|
||||
├── fsanet-var.onnx
|
||||
└── model_gray_mobilenetv2_rotcls.onnx
|
||||
3. 集成指南
|
||||
|
||||
## 3. 集成指南
|
||||
请按照以下步骤将 SDK 集成到您的 Android Studio 项目中。
|
||||
|
||||
步骤 1: 复制 Java 接口
|
||||
|
|
@ -90,12 +93,18 @@ SDK_Models/
|
|||
如果是 build.gradle.kts (Kotlin 脚本):
|
||||
|
||||
Kotlin
|
||||
```
|
||||
android {
|
||||
|
||||
```android {
|
||||
// ... (namespace, compileSdk, 等)
|
||||
|
||||
defaultConfig {
|
||||
// ... (applicationId, minSdk, targetSdk, 等)
|
||||
|
||||
// 强制 Gradle 只打包和使用 arm64-v8a 架构的库
|
||||
// 这可以防止在 x86 模拟器上发生库不匹配的崩溃
|
||||
ndk {
|
||||
abiFilters.add("arm64-v8a")
|
||||
}
|
||||
}
|
||||
|
||||
// (保持这个 sourceSets 块不变，即使它看起来是空的)
|
||||
|
|
@ -106,20 +115,14 @@ android {
|
|||
}
|
||||
}
|
||||
|
||||
// 强制 Gradle 只打包和使用 arm64-v8a 架构的库
|
||||
// 这可以防止在 x86 模拟器上发生库不匹配的崩溃
|
||||
ndk {
|
||||
abiFilters.add("arm64-v8a")
|
||||
}
|
||||
|
||||
|
||||
// ... (buildTypes, compileOptions, 等)
|
||||
}
|
||||
```
|
||||
}```
|
||||
如果是 build.gradle (Groovy 脚本):
|
||||
|
||||
Groovy
|
||||
```
|
||||
android {
|
||||
```android {
|
||||
// ... (namespace, compileSdk, 等)
|
||||
|
||||
defaultConfig {
|
||||
|
|
@ -140,8 +143,7 @@ android {
|
|||
|
||||
// ... (buildTypes, compileOptions, 等)
|
||||
}
|
||||
```
|
||||
点击 "Sync Now" 同步您的项目。
|
||||
```点击 "Sync Now" 同步您的项目。
|
||||
|
||||
至此，集成已全部完成！
|
||||
|
||||
|
|
@ -152,8 +154,7 @@ FaceSDKWrapper.java 会自动处理模型复制和 C++ 库加载。
|
|||
您必须在后台线程中初始化 SDK，因为它包含耗时的模型复制操作（仅限首次启动）。
|
||||
|
||||
Java
|
||||
```
|
||||
import com.facesdk.wrapper.FaceSDKWrapper; // 确保导入您修改了包名的类
|
||||
```import com.facesdk.wrapper.FaceSDKWrapper; // 确保导入您修改了包名的类
|
||||
|
||||
public class MyApplication extends Application {
|
||||
|
||||
|
|
@ -181,16 +182,14 @@ public class MyApplication extends Application {
|
|||
public FaceSDKWrapper getSdkWrapper() {
|
||||
return (isSdkInitialized) ? sdkWrapper : null;
|
||||
}
|
||||
}
|
||||
```
|
||||
}```
|
||||
(您也可以不在 Application 中初始化，而是在 Activity 中，如我们的测试项目所示)
|
||||
|
||||
2. 提取特征 (必须在后台线程)
|
||||
特征提取是一个CPU 密集型操作（运行 7 个模型）。严禁在 UI 主线程上调用它，否则会导致 App 冻结。
|
||||
|
||||
Java
|
||||
```
|
||||
// (在您的 Activity 或 ViewModel 中)
|
||||
```// (在您的 Activity 或 ViewModel 中)
|
||||
// 假设您已从 Application 中获取了 sdkWrapper 实例
|
||||
|
||||
public void runExtraction(Bitmap faceBitmap) {
|
||||
|
|
@ -215,31 +214,27 @@ public void runExtraction(Bitmap faceBitmap) {
|
|||
}
|
||||
});
|
||||
}).start();
|
||||
}
|
||||
```
|
||||
}```
|
||||
3. 比较特征
|
||||
这是一个非常快速的操作，可以在任何线程上调用。
|
||||
|
||||
Java
|
||||
```
|
||||
float[] featureA = ... // (来自 extractFeature)
|
||||
```float[] featureA = ... // (来自 extractFeature)
|
||||
float[] featureB = ... // (来自数据库)
|
||||
|
||||
float similarity = sdkWrapper.compare(featureA, featureB);
|
||||
|
||||
// 相似度是一个 -1.0 到 1.0 之间的浮点数 (余弦相似度)
|
||||
Log.i("MyActivity", "人脸相似度: " + similarity);
|
||||
```
|
||||
Log.i("MyActivity", "人脸相似度: " + similarity);```
|
||||
4. 释放 SDK
|
||||
在您的主 Activity (或 Application) 退出时，调用 release() 来释放 C++ 占用的内存。
|
||||
|
||||
Java
|
||||
```
|
||||
// (在您的 MainActivity 中)
|
||||
```// (在您的 MainActivity 中)
|
||||
@Override
|
||||
protected void onDestroy() {
|
||||
super.onDestroy();
|
||||
if (sdkWrapper != null) {
|
||||
sdkWrapper.release();
|
||||
}
|
||||
}```
|
||||
}```
|
||||
|
|
|
|||
Loading…
Reference in New Issue