[Doc] Update Android SDK usage docs (#727)

* [Doc] Update Android Usage docs * [Doc] Update Android en build docs * fix typos
2025-10-04 16:22:57 +08:00 · 2022-11-28 18:46:14 +08:00
parent b0eb9aa253
commit 205ead8f68
8 changed files with 226 additions and 123 deletions
--- a/README_CN.md
+++ b/README_CN.md
@@ -105,7 +105,7 @@

    - [1. 如何配置模型部署的推理后端](docs/cn/faq/how_to_change_backend.md)
    - [2. Windows上C++ SDK如何使用](docs/cn/faq/use_sdk_on_windows.md)
-    - [3. Android上如何使用FastDeploy](docs/cn/faq/use_sdk_on_android.md)(进行中)
+    - [3. Android上如何使用FastDeploy](java/android/README.md)
    - [4. TensorRT使用中的一些技巧](docs/cn/faq/tensorrt_tricks.md)
    - [5. 如何增加新的模型](docs/cn/faq/develop_a_new_model.md)(进行中)

--- a/README_EN.md
+++ b/README_EN.md
@@ -104,7 +104,7 @@ Including image classification, object detection, image segmentation, face detec

    - [1. How to Change Inference Backends](docs/en/faq/how_to_change_backend.md)
    - [2. How to Use FastDeploy C++ SDK on Windows Platform](docs/en/faq/use_sdk_on_windows.md)
-    - [3. How to Use FastDeploy C++ SDK on Android Platform](docs/en/faq/use_sdk_on_android.md)(To be Continued)
+    - [3. How to Use FastDeploy C++ SDK on Android Platform](java/android/README_EN.md)(To be Continued)
    - [4. Tricks of TensorRT](docs/en/faq/tensorrt_tricks.md)
    - [5. How to Develop a New Model](docs/en/faq/develop_a_new_model.md)(To be Continued)

--- a/docs/cn/faq/use_cpp_sdk_on_android.md
+++ b/docs/cn/faq/use_cpp_sdk_on_android.md
@@ -44,9 +44,9 @@ public class PicoDet {
    }
 }
 ```
-这些被标记为native的接口是需要通过JNI的方式实现，并在Java层供PicoDet类调用。完整的PicoDet Java代码请参考 [PicoDet.java](../../../examples/vision/detection/paddledetection/android/app/src/main/java/com/baidu/paddle/fastdeploy/vision/detection/PicoDet.java) 。各个函数说明如下：  
+这些被标记为native的接口是需要通过JNI的方式实现，并在Java层供PicoDet类调用。完整的PicoDet Java代码请参考 [PicoDet.java](../../../java/android/fastdeploy/src/main/java/com/baidu/paddle/fastdeploy/vision/detection/PicoDet.java) 。各个函数说明如下：  
 - `bindNative`: C++层初始化模型资源，如果成功初始化，则返回指向该模型的指针(long类型)，否则返回0指针  
- `predictNative`: 通过已经初始化好的模型指针，在C++层执行预测代码，如果预测成功则返回指向预测结果的指针，否则返回0指针。注意，该结果指针在当次预测使用完之后需要释放，具体操作请参考 [PicoDet.java](../../../examples/vision/detection/paddledetection/android/app/src/main/java/com/baidu/paddle/fastdeploy/vision/detection/PicoDet.java) 中的predict函数。  
+- `predictNative`: 通过已经初始化好的模型指针，在C++层执行预测代码，如果预测成功则返回指向预测结果的指针，否则返回0指针。注意，该结果指针在当次预测使用完之后需要释放，具体操作请参考 [PicoDet.java](../../../java/android/fastdeploy/src/main/java/com/baidu/paddle/fastdeploy/vision/detection/PicoDet.java) 中的predict函数。  
 - `releaseNative`: 根据传入的模型指针，在C++层释放模型资源。

 ## Android Studio 生成JNI函数定义  
@@ -70,89 +70,96 @@ Android Studio 生成 JNI 函数定义: 鼠标停留在Java中定义的native函

 以下为PicoDet JNI层实现的示例，相关的辅助函数不在此处赘述，完整的C++代码请参考 [android/app/src/main/cpp](../../../examples/vision/detection/paddledetection/android/app/src/main/cpp/).
 ```C++
+// Copyright (c) 2022 PaddlePaddle Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 #include <jni.h>  // NOLINT
-#include "fastdeploy_jni.h"  // NOLINT
+#include "fastdeploy_jni/convert_jni.h"  // NOLINT
+#include "fastdeploy_jni/assets_loader_jni.h" // NOLINT
+#include "fastdeploy_jni/runtime_option_jni.h"  // NOLINT
+#include "fastdeploy_jni/vision/results_jni.h"  // NOLINT
+#include "fastdeploy_jni/vision/detection/detection_utils_jni.h"  // NOLINT
+
+namespace fni = fastdeploy::jni;
+namespace vision = fastdeploy::vision;
+namespace detection = fastdeploy::vision::detection;

 #ifdef __cplusplus
 extern "C" {
 #endif

-// 绑定C++层的模型
 JNIEXPORT jlong JNICALL
 Java_com_baidu_paddle_fastdeploy_vision_detection_PicoDet_bindNative(
-    JNIEnv *env, jclass clazz, jstring model_file, jstring params_file,
-    jstring config_file, jint cpu_num_thread, jboolean enable_lite_fp16,
-    jint lite_power_mode, jstring lite_optimized_model_dir,
-    jboolean enable_record_time_of_runtime, jstring label_file) {
-  std::string c_model_file = fastdeploy::jni::ConvertTo<std::string>(env, model_file);
-  std::string c_params_file = fastdeploy::jni::ConvertTo<std::string>(env, params_file);
-  std::string c_config_file = astdeploy::jni::ConvertTo<std::string>(env, config_file);
-  std::string c_label_file = fastdeploy::jni::ConvertTo<std::string>(env, label_file);
-  std::string c_lite_optimized_model_dir = fastdeploy::jni::ConvertTo<std::string>(env, lite_optimized_model_dir);
-  auto c_cpu_num_thread = static_cast<int>(cpu_num_thread);
-  auto c_enable_lite_fp16 = static_cast<bool>(enable_lite_fp16);
-  auto c_lite_power_mode = static_cast<fastdeploy::LitePowerMode>(lite_power_mode);
-  fastdeploy::RuntimeOption c_option;
-  c_option.UseCpu();
-  c_option.UseLiteBackend();
-  c_option.SetCpuThreadNum(c_cpu_num_thread);
-  c_option.SetLitePowerMode(c_lite_power_mode);
-  c_option.SetLiteOptimizedModelDir(c_lite_optimized_model_dir);
-  if (c_enable_lite_fp16) {
-    c_option.EnableLiteFP16();
-  }
-  // 如果您实现的是其他模型，比如PPYOLOE，请注意修改此处绑定的C++类型
-  auto c_model_ptr = new fastdeploy::vision::detection::PicoDet(
-      c_model_file, c_params_file, c_config_file, c_option);
-  // Enable record Runtime time costs.
-  if (enable_record_time_of_runtime) {
+    JNIEnv *env, jobject thiz, jstring model_file, jstring params_file,
+    jstring config_file, jobject runtime_option, jstring label_file) {
+  auto c_model_file = fni::ConvertTo<std::string>(env, model_file);
+  auto c_params_file = fni::ConvertTo<std::string>(env, params_file);
+  auto c_config_file = fni::ConvertTo<std::string>(env, config_file);
+  auto c_label_file = fni::ConvertTo<std::string>(env, label_file);
+  auto c_runtime_option = fni::NewCxxRuntimeOption(env, runtime_option);
+  auto c_model_ptr = new detection::PicoDet(
+      c_model_file, c_params_file, c_config_file, c_runtime_option);
+  INITIALIZED_OR_RETURN(c_model_ptr)
+
+#ifdef ENABLE_RUNTIME_PERF
  c_model_ptr->EnableRecordTimeOfRuntime();
+#endif
+  if (!c_label_file.empty()) {
+    fni::AssetsLoader::LoadDetectionLabels(c_label_file);
  }
-  // Load detection labels if label path is not empty.
-  if ((!fastdeploy::jni::AssetsLoaderUtils::IsDetectionLabelsLoaded()) &&
-      (!c_label_file.empty())) {
-    fastdeploy::jni::AssetsLoaderUtils::LoadDetectionLabels(c_label_file);
-  }
-  // WARN: need to release manually in Java !
-  return reinterpret_cast<jlong>(c_model_ptr);  // native model context
+  vision::EnableFlyCV();
+  return reinterpret_cast<jlong>(c_model_ptr);
 }

-// 通过传入的模型指针在C++层进行预测
-JNIEXPORT jlong JNICALL
+JNIEXPORT jobject JNICALL
 Java_com_baidu_paddle_fastdeploy_vision_detection_PicoDet_predictNative(
-    JNIEnv *env, jclass clazz, jlong native_model_context,
-    jobject argb8888_bitmap, jboolean saved, jstring saved_image_path,
-    jfloat score_threshold, jboolean rendering) {
-  if (native_model_context == 0) {
-    return 0;
+    JNIEnv *env, jobject thiz, jlong cxx_context, jobject argb8888_bitmap,
+    jboolean save_image, jstring save_path, jboolean rendering,
+    jfloat score_threshold) {
+  if (cxx_context == 0) {
+    return NULL;
  }
  cv::Mat c_bgr;
-  if (!fastdeploy::jni::ARGB888Bitmap2BGR(env, argb8888_bitmap, &c_bgr)) {
-    return 0;
+  if (!fni::ARGB888Bitmap2BGR(env, argb8888_bitmap, &c_bgr)) {
+    return NULL;
  }
-  auto c_model_ptr = reinterpret_cast<fastdeploy::vision::detection::PicoDet *>(
-      native_model_context);
-  auto c_result_ptr = new fastdeploy::vision::DetectionResult();
-  t = fastdeploy::jni::GetCurrentTime();
-  if (!c_model_ptr->Predict(&c_bgr, c_result_ptr)) {
-    delete c_result_ptr;
-    return 0;
-  }
-  // ...
-  return reinterpret_cast<jlong>(c_result_ptr);  // native result context
+  auto c_model_ptr = reinterpret_cast<detection::PicoDet *>(cxx_context);
+  vision::DetectionResult c_result;
+  auto t = fni::GetCurrentTime();
+  c_model_ptr->Predict(&c_bgr, &c_result);
+  PERF_TIME_OF_RUNTIME(c_model_ptr, t)
+
+  if (rendering) {
+    fni::RenderingDetection(env, c_bgr, c_result, argb8888_bitmap, save_image,
+                            score_threshold, save_path);
+  }
+
+  return fni::NewJavaResultFromCxx(env, reinterpret_cast<void *>(&c_result),
+                                   vision::ResultType::DETECTION);
 }

-// 在C++层释放模型资源
 JNIEXPORT jboolean JNICALL
 Java_com_baidu_paddle_fastdeploy_vision_detection_PicoDet_releaseNative(
-    JNIEnv *env, jclass clazz, jlong native_model_context) {
-  if (native_model_context == 0) {
+    JNIEnv *env, jobject thiz, jlong cxx_context) {
+  if (cxx_context == 0) {
    return JNI_FALSE;
  }
-  auto c_model_ptr = reinterpret_cast<fastdeploy::vision::detection::PicoDet *>(
-      native_model_context);
-  // ...
+  auto c_model_ptr = reinterpret_cast<detection::PicoDet *>(cxx_context);
+  PERF_TIME_OF_RUNTIME(c_model_ptr, -1)
+
  delete c_model_ptr;
+  LOGD("[End] Release PicoDet in native !");
  return JNI_TRUE;
 }

@@ -184,6 +191,11 @@ android {
            version '3.10.2'
        }
    }
+    sourceSets {
+        main {
+            jniLibs.srcDirs = ['libs']
+        }
+    }
    ndkVersion '20.1.5948944'
 }
 ```  
@@ -192,7 +204,8 @@ android {
 cmake_minimum_required(VERSION 3.10.2)
 project("fastdeploy_jni")

-set(FastDeploy_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../libs/fastdeploy-android-0.4.0-shared")
+# 其中 xxx 表示对应C++ SDK的版本号
+set(FastDeploy_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../libs/fastdeploy-android-xxx-shared")

 find_package(FastDeploy REQUIRED)

@@ -221,7 +234,7 @@ target_link_libraries(
        ${log-lib}
 )
 ```
-完整的工程示例，请参考 [android/app/src/main/cpp/CMakelists.txt](../../../examples/vision/detection/paddledetection/android/app/src/main/cpp/) 以及 [android/app/build.gradle](../../../examples/vision/detection/paddledetection/android/app/build.gradle).
+完整的工程示例，请参考 [CMakelists.txt](../../../java/android/fastdeploy/src/main/cpp/CMakeLists.txt) 以及 [build.gradle](../../../java/android/fastdeploy/build.gradle).

 ## 更多FastDeploy Android 使用案例  
 <div id="Examples"></div>  
--- a/docs/cn/faq/use_java_sdk_on_android.md
+++ b/docs/cn/faq/use_java_sdk_on_android.md
@@ -1,2 +0,0 @@
-## 在 Android 中使用 FastDeploy Java SDK  
- TODO  
--- a/docs/cn/faq/use_sdk_on_android.md
+++ b/docs/cn/faq/use_sdk_on_android.md
@@ -1,3 +0,0 @@
-# Android平台使用FastDeploy部署
-
-进行中...
--- a/docs/en/build_and_install/android.md
+++ b/docs/en/build_and_install/android.md
@@ -1,3 +1,97 @@
-# How to Build Android Deployment Library
+# How to Build FastDeploy Android C++ SDK

-coming soon...
+FastDeploy supports Paddle-Lite backend on Android. It supports both armeabi-v7a and arm64-v8a cpu architectures, and supports fp16 precision inference on the armv8.2 architecture. The relevant compilation options are described as follows:
+
+|Option|Default|Description|Remark|  
+|:---|:---|:---|:---|  
+|ENABLE_LITE_BACKEND|OFF|It needs to be set to ON when compiling the Android library| - |
+|WITH_OPENCV_STATIC|OFF|Whether to use the OpenCV static library| - |
+|WITH_LITE_STATIC|OFF|Whether to use the Paddle-Lite static library| NOT Support now |
+
+Please reference [FastDeploy Compile Options](./README.md) for more details.
+
+## Build Android C++ SDK
+
+Prerequisite for Compiling on Android:  
+
+- Android SDK API >= 21  
+- Android NDK >= 20 (Only support clang toolchain now)
+- cmake >= 3.10.0  
+
+Please check if the Android SDK and NDK is ready or not before building：  
+```bash
+➜ echo $ANDROID_SDK  
+/Users/xxx/Library/Android/sdk  
+➜ echo $ANDROID_NDK
+/Users/xxx/Library/Android/sdk/ndk/25.1.8937393
+```
+It is recommended to use NDK>=20 for cross compilation, the compilation command is as follows：
+```bash
+# Download the latest source code
+git clone https://github.com/PaddlePaddle/FastDeploy.git
+cd FastDeploy  
+
+# Setting up Android toolchanin
+ANDROID_ABI=arm64-v8a  # 'arm64-v8a', 'armeabi-v7a'
+ANDROID_PLATFORM="android-21"  # API >= 21
+ANDROID_STL=c++_shared  # 'c++_shared', 'c++_static'
+ANDROID_TOOLCHAIN=clang  # 'clang' only
+TOOLCHAIN_FILE=${ANDROID_NDK}/build/cmake/android.toolchain.cmake
+
+# Create build directory
+BUILD_ROOT=build/Android
+BUILD_DIR=${BUILD_ROOT}/${ANDROID_ABI}-api-21
+FASDEPLOY_INSTALL_DIR="${BUILD_DIR}/install"
+mkdir build && mkdir ${BUILD_ROOT} && mkdir ${BUILD_DIR}
+cd ${BUILD_DIR}
+
+# CMake configuration with Android toolchain
+cmake -DCMAKE_TOOLCHAIN_FILE=${TOOLCHAIN_FILE} \
+      -DCMAKE_BUILD_TYPE=MinSizeRel \
+      -DANDROID_ABI=${ANDROID_ABI} \
+      -DANDROID_NDK=${ANDROID_NDK} \
+      -DANDROID_PLATFORM=${ANDROID_PLATFORM} \
+      -DANDROID_STL=${ANDROID_STL} \
+      -DANDROID_TOOLCHAIN=${ANDROID_TOOLCHAIN} \
+      -DENABLE_LITE_BACKEND=ON \
+      -DENABLE_VISION=ON \
+      -DCMAKE_INSTALL_PREFIX=${FASDEPLOY_INSTALL_DIR} \
+      -Wno-dev ../../..
+
+# Build FastDeploy Android C++ SDK
+make -j8
+make install  
+```  
+After the compilation is complete, the Android C++ SDK is saved in the `build/Android/arm64-v8a-api-21/install` directory, the directory structure is as follows：  
+```bash
+➜ tree . -d -L 3
+.
+├── examples
+├── include
+│   └── fastdeploy                   # FastDeploy headers
+├── lib
+│   └── arm64-v8a                    # FastDeploy Android libs
+└── third_libs                       # Third parties libs
+    └── install
+        ├── opencv
+        ├── flycv
+        └── paddlelite
+```
+You can check the Android C++ SDK use cases in the examples/vision directory：
+```bash  
+.
+├── classification
+│   ├── paddleclas
+│   │   ├── android                  #  classification demo for Android
+│   │   ├── cpp
+...
+├── detection
+│   ├── paddledetection
+│   │   ├── android                  #  object detection demo for Android
+│   │   ├── cpp
+...
+```
+About How to use FastDeploy Android C++ SDK, Please refer to the use case documentation:  
+- [Image Classification Android Documentation](../../../examples/vision/classification/paddleclas/android/README.md)  
+- [Object Detection Android Documentation](../../../examples/vision/detection/paddledetection/android/README.md)  
+- [Using FastDeploy C++ SDK in Android via JNI](../../en/faq/use_cpp_sdk_on_android.md)
--- a/docs/en/faq/use_cpp_sdk_on_android.md
+++ b/docs/en/faq/use_cpp_sdk_on_android.md
--- a/java/android/README_EN.md
+++ b/java/android/README_EN.md
@@ -0,0 +1 @@
+- TODO