Usage Models


Android supports two main methods for application development: in Java using the Android SDK, and in C/C++ using the Android Native Development Kit (NDK). It is also possible to combine these two modes in a single application. Analogously, there are two ways to access functions from the OpenCV for Tegra libraries in Android: through its native API and its Java API.

Native

Intrinsically, the OpenCV for Tegra libraries are compiled in native form (C/C++), which can be called in Android native applications/libraries. The native user libraries can, in turn, be accessed from Java through the Java Native Interface (JNI).

Java

The other method for accessing OpenCV for Tegra functions is through its Java API. In addition to their C/C++ interface, there are Java wrappers for most of the OpenCV for Tegra functions. These can be accessed directly by Android applications in Java.

Note, however, that even for calls to OpenCV functions through their Java interface, all computations are internally performed at the native level. Hence the overhead of a call to an OpenCV for Tegra function through its Java interface is equal to the cost of one or several JNI calls.

The following illustration presents the software stacks for Android applications that use OpenCV for Tegra functions (a) directly in native code, and (b) in Java code via their Java wrapper interfaces.

There are pros and cons to both approaches of using OpenCV for Tegra in Android application. Using native calls can result in fewer overheads for JNI calls, but requires more programming effort. Conversely, using the Java interface requires less programming effort, but the overhead of JNI calls can quickly add up if many calls to individual OpenCV functions are made.

Note: If, in an application, you anticipate processing an image/video frame with a number of consecutive computer vision functions, it might be advantageous to write one native C/C++ library that calls all these functions. This native library can be accessed by the Android application via one JNI call per frame.

Interface

API

OpenCV for Tegra has the same native (C/C++) and Java API as OpenCV, and OpenCV for Android.

For detailed documentation on the OpenCV native API, see the following site: http://docs.opencv.org/modules/refman.html

For detailed documentation on the OpenCV Java interface, see the following site: http://docs.opencv.org/java/

For the OpenCV User Guide, see: http://docs.opencv.org/doc/user_guide/user_guide.html

For tutorials on OpenCV modules, see: http://docs.opencv.org/doc/tutorials/tutorials.html

OpenCV Manager

Android applications link OpenCV for Tegra (or OpenCV for Android) dynamically. Each application can maintain individual copies for the OpenCV shared libraries (.so files) inside their application packages or they can all use one copy of a shared library installed on the system. The latter strategy helps to keep end-user applications small and avoids duplication of the OpenCV libraries. However, in order for the latter to work correctly, the unique, device-specific OpenCV for Tegra libraries must be available on the user’s device. This can be achieved via the OpenCV Manager.

The OpenCV Manager Android service can be employed to asynchronously initialize OpenCV in applications at run-time. This service helps to dynamically manage OpenCV library binaries on end user devices. It provides a mechanism to check for the presence of and correctly initialize the unique platform-, operating system-, and version-specific OpenCV libraries that are required by an Android application.

The OpenCV Manager has the following advantages:

The OpenCV Manager service is packaged as an .apk file (OpenCV_2.4.8.2_Manager_2.17_armv7a-neon.apk), which can be downloaded, free of cost, from Google Play. It is also included in the TADP in the OpenCV-2.4.8.2-Tegra-sdk/apk/ folder. It can be installed manually on to a Tegra device using the following command from a terminal window:

$ adb install <TADP DIR>/apk/OpenCV_2.4.8.2_Manager_2.17_armv7a-neon.apk

In order for an application to use the OpenCV Manager, it must explicitly bind to its Service upon startup. This can be achieved by importing the necessary Java classes for the OpenCV Manager into your Android application and by modifying its code slightly as described here.

The events that occur when a user runs an Android application with asynchronous initialization of OpenCV for Tegra with the OpenCV Manager are illustrated in the diagram below.



Image courtesy of OpenCV.org

The Android application first attempts to bind to the OpenCV Manager service. If the OpenCV Manager is not already installed on the device, the binding is unsuccessful and the application attempts to download the OpenCV Manager service from Google Play. If Google Play is not accessible, the user must manually install the .apk package for the OpenCV Manager using adb install as described earlier. On the other hand, if Google Play is accessible, the OpenCV Manager is automatically downloaded from Google Play and installed. The service then determines if the specific OpenCV for Tegra libraries required by the application are available on the device. If they are available, they are correctly initialized and the application runs successfully by linking dynamically to them.

Note: This initialization happens on a device only once when an application requests the OpenCV Manager for the very first time. All subsequent applications successfully bind to OpenCV Manager in a single attempt.

OpenCV for Tegra Library Package

NVIDIA provides extended versions of the OpenCV for Android libraries that contain Tegra-specific optimizations. All libraries are provided in binary form and are packaged into the OpenCV Manager for ARM-v7a with NEON package (OpenCV_2.4.8.2_Manager_2.17_armv7a-neon.apk). This .apk can be downloaded, free of cost, from the Google Play store and is also included into the TADP package in the OpenCV-2.4.8.2-Tegra-sdk/apk/ folder.

When installed on a non-Tegra device with an ARM-v7a CPU with NEON, the optimizations are not available and applications can use the non-optimized OpenCV for Android functions. However, on Tegra devices, the optimized OpenCV functions are used by default instead of non-optimized ones.

Important Note for Tegra 2 Devices: If you are developing on a Tegra 2 device, the OpenCV_2.4.8.2_Manager_2.17_armv7a-neon.apk does not work correctly. The Google Play store and the TADP package provide OpenCV Manager and OpenCV for Tegra Library packages that are compatible with Tegra 2 devices. Please use the following two packages from the <path to TADP dir>/OpenCV-2.4.8.2-Tegra-sdk/apk/ or from Google Play:

  • OpenCV_2.4.8.2_Manager_2.17_armeabi.apk, and
  • OpenCV_2.4.8.2_binary_pack_armv7a.apk

instead of the OpenCV_2.4.8.2_Manager_2.17_armv7a-neon.apk for Tegra 2 devices.

You can obtain more information about the appropriate OpenCV .apk files to install on your specific device from <path to TADP dir>/OpenCV-2.4.8.2-Tegra-sdk/apk/readme.txt.

To determine whether the Tegra optimized functions are indeed being used in your application, check for the presence of the following message in the Android systems logs. You can use the adb logcat command to write out the system logs.

E/OpenCV_for_Tegra(28465): Tegra platform detected, optimizations are switched ON!

Additionally, the OpenCV Manager installed on your device will display the information about your detected Tegra hardware as illustrated below.

 

 

 

 


NVIDIA® GameWorks™ Documentation Rev. 1.0.200608 ©2014-2020. NVIDIA Corporation. All Rights Reserved.