From 9b0106b52b3fc6823ab9bf87052e56030939c3b3 Mon Sep 17 00:00:00 2001
From: guanyuankai <whistle_op@hotmail.com>
Date: Fri, 31 Oct 2025 14:05:06 +0800
Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84readme?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...†åˆ« Android SDK 集æˆ�指å�— (V1.0) => Readme.md} |   0
 README.md                                     | 246 +++++++++++++++++-
 2 files changed, 245 insertions(+), 1 deletion(-)
 rename Distribution/{人脸识别 Android SDK 集�指� (V1.0) => Readme.md} (100%)

diff --git a/Distribution/人脸识别 Android SDK 集�指� (V1.0) b/Distribution/Readme.md
similarity index 100%
rename from Distribution/人脸识别 Android SDK 集�指� (V1.0)
rename to Distribution/Readme.md
diff --git a/README.md b/README.md
index b5a538c..4400513 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,245 @@
-# FaceSDK_Project
\ No newline at end of file
+人脸识别 Android SDK 集�指� (V1.0)
+本文档为人脸识别 C++ 核心库 (libface_sdk_jni.so) �供了详尽的 Android 集�步骤和 API 使用说明。
+
+1. 概述
+本 SDK �供了在 Android 设备上本地�行的高性能人脸识别功能。SDK 核心基于 C++ 实现，1:1 转译自 Python 端的 7 模型推�管线，确�了特���的完全兼容。
+
+SDK �供的主� Java API 接�包括：
+
+特���: extractFeature(Bitmap bitmap)
+
+特�比较: compare(float[] feat1, float[] feat2)
+
+关键特性
+C++ 核心: 所有计算�在 C++ 层完�，性能高，内存�控。
+
+7 模型管线: 完整�现了 Python 端的 7 模型管线（旋转�检测�姿��关键点�对��识别），��了高识别精度。
+
+质�过滤: 内置姿�角（Yaw/Pitch）过滤，自动拒�低质�人脸。
+
+手动�绑: SDK 手动�绑了所有必�的�赖库 (ONNX Runtime, OpenCV, C++ STL)，确�了在��设备上的一致性，��了因 Gradle �赖版本�匹�导致的崩溃。
+
+2. SDK 包内容
+分�的 SDK 包�三个部分：
+
+1. Java 接�
+SDK_Wrapper/
+└── com/
+    └── facesdk/
+        └── wrapper/
+            └── FaceSDKWrapper.java  (SDK 公开的 Java API)
+2. Native 库 (C++)
+SDK_Libs/
+└── arm64-v8a/
+    ├── libface_sdk_jni.so     (✅ 您的核心 SDK 库)
+    ├── libonnxruntime.so      (�赖: ONNX 1.23.2 完整版)
+    ├── libopencv_java4.so     (�赖: OpenCV 4.12.0)
+    └── libc++_shared.so       (�赖: C++ 标准库)
+注�: 本 SDK 目�仅支� arm64-v8a 架构。这覆盖了市�上 99% 以上的现代 Android 设备。
+
+3. AI 模型
+SDK_Models/
+├── faceboxesv2-640x640.onnx
+├── face_landmarker_pts5_net1.onnx
+├── face_landmarker_pts5_net2.onnx
+├── face_recognizer.onnx
+├── fsanet-conv.onnx
+├── fsanet-var.onnx
+└── model_gray_mobilenetv2_rotcls.onnx
+3. 集�指�
+请按照以下步骤将 SDK 集�到您的 Android Studio 项目中。
+
+步骤 1: �制 Java 接�
+在 Android Studio 的 "Project" 视图中，导航到 app/src/main/java/。
+
+将 FaceSDKWrapper.java 文件�制到您项目的 Java ��目录中（例如，com.yourcompany.yourapp.sdk/）。
+
+��: 打开 FaceSDKWrapper.java 文件，将其顶部的 package com.facesdk.wrapper; 声明修改为您自己的包�，例如 package com.yourcompany.yourapp.sdk;。
+
+步骤 2: �制 Native 库 (.so)
+在 Android Studio 的 "Project" 视图中，导航到 app/src/main/。
+
+�键点击 main -> New -> Directory。
+
+创建 jniLibs 文件夹。
+
+�键点击 jniLibs -> New -> Directory。
+
+创建 arm64-v8a 文件夹。
+
+将 SDK_Libs/arm64-v8a/ 目录下的所有 4 个 .so 文件�制到您刚创建的 app/src/main/jniLibs/arm64-v8a/ 目录中。
+
+步骤 3: �制 AI 模型 (.onnx)
+在 Android Studio 的 "Project" 视图中，导航到 app/src/main/。
+
+�键点击 main -> New -> Directory。
+
+创建 assets 文件夹。
+
+将 SDK_Models/ 目录下的所有 7 个 .onnx 文件�制到您刚创建的 app/src/main/assets/ 目录中。
+
+步骤 4: �置 build.gradle.kts (或 build.gradle)
+这是最关键的一步。我们需�告诉 Gradle 在打包 App 时包�我们的手动库。
+
+打开您的 app/build.gradle.kts (或 build.gradle) 文件。
+
+移除 (或��添加) onnxruntime 和 opencv 的 implementation �赖。我们已�手动�供了它们。
+
+在 android { ... } 代��中，添加 sourceSets 和 ndk �置：
+
+如果是 build.gradle.kts (Kotlin 脚本):
+
+Kotlin
+```
+android {
+    // ... (namespace, compileSdk, ç­‰)
+
+    defaultConfig {
+        // ... (applicationId, minSdk, targetSdk, ç­‰)
+    }
+
+    // (��这个 sourceSets ���，�使它看起�是空的)
+    sourceSets {
+        getByName("main") {
+            // 明确告知 Gradle 我们的 jniLibs 目录在哪里
+            jniLibs.srcDirs("src/main/jniLibs")
+        }
+    }
+
+    // 强制 Gradle �打包和使用 arm64-v8a 架构的库
+    // 这�以防止在 x86 模拟器上�生库�匹�的崩溃
+    ndk {
+        abiFilters.add("arm64-v8a")
+    }
+
+    // ... (buildTypes, compileOptions, ç­‰)
+}
+```
+如果是 build.gradle (Groovy 脚本):
+
+Groovy
+```
+android {
+    // ... (namespace, compileSdk, ç­‰)
+
+    defaultConfig {
+        // ... (applicationId, minSdk, targetSdk, ç­‰)
+    }
+
+    sourceSets {
+        main {
+            // 明确告知 Gradle 我们的 jniLibs 目录在哪里
+            jniLibs.srcDirs = ['src/main/jniLibs']
+        }
+    }
+
+    // 强制 Gradle �打包和使用 arm64-v8a 架构的库
+    ndk {
+        abiFilters 'arm64-v8a'
+    }
+
+    // ... (buildTypes, compileOptions, ç­‰)
+}
+```
+点击 "Sync Now" �步您的项目。
+
+至此，集�已全部完��
+
+4. API 使用指� (Java)
+FaceSDKWrapper.java 会自动处�模型�制和 C++ 库加载。
+
+1. �始化 SDK
+您必须在��线程中�始化 SDK，因为它包�耗时的模型�制�作（仅�首次�动）。
+
+Java
+```
+import com.facesdk.wrapper.FaceSDKWrapper; // 确�导入您修改了包�的类
+
+public class MyApplication extends Application {
+    
+    private FaceSDKWrapper sdkWrapper;
+    private volatile boolean isSdkInitialized = false;
+
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        
+        // 在��线程�始化 SDK
+        new Thread(() -> {
+            sdkWrapper = new FaceSDKWrapper();
+            boolean success = sdkWrapper.init(getApplicationContext());
+            if (success) {
+                isSdkInitialized = true;
+                Log.i("MyApplication", "人脸识别 SDK �始化�功�");
+            } else {
+                Log.e("MyApplication", "人脸识别 SDK �始化失败�");
+            }
+        }).start();
+    }
+
+    // �供一个全局获� SDK 实例的方法
+    public FaceSDKWrapper getSdkWrapper() {
+        return (isSdkInitialized) ? sdkWrapper : null;
+    }
+}
+```
+(您也�以�在 Application 中�始化，而是在 Activity 中，如我们的测试项目所示)
+
+2. ��特� (必须在��线程)
+特���是一个CPU 密集型�作（�行 7 个模型）。严�在 UI 主线程上调用它，�则会导致 App 冻结。
+
+Java
+```
+// (在您的 Activity 或 ViewModel 中)
+// �设您已从 Application 中获�了 sdkWrapper 实例
+
+public void runExtraction(Bitmap faceBitmap) {
+    if (sdkWrapper == null) {
+        Log.e("MyActivity", "SDK 尚未�始化。");
+        return;
+    }
+
+    // 必须在��线程中�行
+    new Thread(() -> {
+        // 1. 调用 C++ 核心库
+        final float[] features = sdkWrapper.extractFeature(faceBitmap);
+
+        // 2. 在 UI 线程上处�结果
+        runOnUiThread(() -> {
+            if (features != null) {
+                Log.i("MyActivity", "特����功�维度: " + features.length);
+                // TODO: 使用特��� (例如，与数�库比对)
+            } else {
+                Log.w("MyActivity", "特���失败 (未检测到�格人脸或出错)");
+                // TODO: �示用户
+            }
+        });
+    }).start();
+}
+```
+3. 比较特�
+这是一个�常快速的�作，�以在任何线程上调用。
+
+Java
+```
+float[] featureA = ... // (�自 extractFeature)
+float[] featureB = ... // (�自数�库)
+
+float similarity = sdkWrapper.compare(featureA, featureB);
+
+// 相似度是一个 -1.0 到 1.0 之间的浮点数 (余弦相似度)
+Log.i("MyActivity", "人脸相似度: " + similarity);
+```
+4. 释放 SDK
+在您的主 Activity (或 Application) 退出时，调用 release() �释放 C++ �用的内存。
+
+Java
+```
+// (在您的 MainActivity 中)
+@Override
+protected void onDestroy() {
+    super.onDestroy();
+    if (sdkWrapper != null) {
+        sdkWrapper.release();
+    }
+}```
\ No newline at end of file