The Android way is writing all your code in Java. But sometimes it is not enough and you need to go to the native level and write some parts of your application in C/C++.
This is especially important when you already have some computer vision code which is written in C++ and uses OpenCV, and you want to reuse it in your Android application,
but do not want to rewrite the C++ code to Java.
In this case the only way is to use JNI - a Java framework for interaction with native code.
The Android way is writing all your code in Java. But sometimes, it is not enough and you need to go to the native level and write some parts of your application in C/C++.
This is especially important when you already have some computer vision code which is written in C++ and uses OpenCV, and you want to reuse it in your Android application.
In this case the only way is to use `JNI <http://java.sun.com/docs/books/jni/>`_ - a Java framework for interaction with native code.
It means, that you should add a Java class with native methods exposing your C++ functionality to the Java part of your Android application.
This tutorial describes a fast way to create and build Android applications containing OpenCV code written in C++. It shows how to build an application which uses OpenCV inside its JNI calls. Tutorial 3 and 4 from the OpenCV for Android SDK can be used as examples. OpenCV Sample "face-detect" also contain a call to C++ class.
Please note that before starting this tutorial you should fulfill all the steps, described in the tutorial :ref:`Android_Binary_Package`.
Please note that before starting this tutorial you should go through all the steps, described in the tutorial :ref:`Android_Binary_Package`.
This tutorial was tested using Ubuntu 10.04 and Windows 7 SP1 operating systems.
Nevertheless, it should also work on Mac OS X.
If you encounter errors after following the steps described here, feel free to contact us via
`OpenCV4Android <https://groups.google.com/group/android-opencv/>`_ discussion group or
OpenCV `Q&A forum <http://answers.opencv.org>`_ and we will try to help you.
However, it should also work on Mac OS X.
If you encounter any error after thoroughly following these steps, feel free to contact us via `OpenCV4Android <https://groups.google.com/group/android-opencv/>`_ discussion group or OpenCV `Q&A forum <http://answers.opencv.org>`_ . We'll do our best to help you out.
Prerequisites: Setup Android NDK
================================
...
...
@@ -56,17 +53,17 @@ Usually code of an Android application has the following structure:
- :file:`... other files ...`
where
where:
+ the :file:`src` folder contains Java code of the application,
+ the :file:`res` folder contains resources of the application (images, xml files describing UI layout , etc),
+ the :file:`libs` folder will contain native libraries after successful build,
+ the :file:`libs` folder will contain native libraries after a successful build,
+ and the :file:`jni` folder contains C/C++ application source code and NDK's build scripts :file:`Android.mk` and :file:`Application.mk`.
These scripts control the C++ build process (they are written in Makefile language).
Written in Makefile language, these scripts control the C++ build process.
Also the root folder should contain the following files:
...
...
@@ -78,9 +75,9 @@ Also the root folder should contain the following files:
* :file:`project.properties` is a text file containing information about target Android platform and other build details.
This file is generated by Eclipse or can be created with :command:`android` tool from Android SDK.
This file is generated by Eclipse or can be created with *Android* tool included in Android SDK.
.. note:: Both files (:file:`AndroidManifest.xml` and :file:`project.properties`) are required to compile the C++ part of the application (NDK build system uses information from these files). If any of these files does not exist, compile the Java part of the project before the C++ part.
.. note:: Both files (:file:`AndroidManifest.xml` and :file:`project.properties`) are required to compile the C++ part of the application, since NDK build system relies on them. If any of these files does not exist, compile the Java part of the project before the C++ part.
.. _NDK_build_cli:
...
...
@@ -90,13 +87,13 @@ Theory: Building application with C++ native part from command line
Here is the standard way to compile C++ part of an Android application:
#. Open console and go to the root folder of Android application
#. Open console and go to the root folder of an Android application
.. code-block:: bash
cd <root folder of the project>/
.. note:: Alternatively you can go to the :file:`jni` folder of Android project. But samples from OpenCV binary package are configured for building from the project root level (because of relative path to the OpenCV library).
.. note:: Alternatively you can go to the :file:`jni` folder of the Android project. But samples from OpenCV4Android SDK are configured for building from the project root level (because of relative path to the OpenCV library).
#. Run the following command
...
...
@@ -112,7 +109,7 @@ Here is the standard way to compile C++ part of an Android application:
#. After executing this command the C++ part of the source code is compiled.
After that the Java part of the application can be (re)compiled (using either *Eclipse* or :command:`ant` build tool).
After that the Java part of the application can be (re)compiled (using either *Eclipse* or *Ant* build tool).
.. note:: Some parameters can be set for the :command:`ndk-build`:
...
...
@@ -182,7 +179,7 @@ then paste the CDT 8.0 repository URL http://download.eclipse.org/tools/cdt/rele
Theory: The structure of :file:`Android.mk` and :file:`Application.mk` scripts
The script :file:`Android.mk` usually have the following structure:
The script :file:`Android.mk` usually has the following structure:
.. code-block:: make
...
...
@@ -197,9 +194,9 @@ The script :file:`Android.mk` usually have the following structure:
include $(BUILD_SHARED_LIBRARY)
This is the minimal file :file:`Android.mk`, which builds a C++ source code of an Android application. Note that the first two lines and the last line are mandatory for any :file:`Android.mk`.
This is the minimal file :file:`Android.mk`, which builds C++ source code of an Android application. Note that the first two lines and the last line are mandatory for any :file:`Android.mk`.
Usually the file :file:`Application.mk` is optional, but in case of project using OpenCV, when STL and exceptions are used in C++, it also should be written. Example of the file :file:`Application.mk`:
Usually the file :file:`Application.mk` is optional, but in case of project using OpenCV, when STL and exceptions are used in C++, it also should be created. Example of the file :file:`Application.mk`:
.. code-block:: make
...
...
@@ -207,14 +204,20 @@ Usually the file :file:`Application.mk` is optional, but in case of project usin
APP_CPPFLAGS := -frtti -fexceptions
APP_ABI := armeabi-v7a
Practice: Build samples from OpenCV binary package
Sometimes ``ndk-build`` fails with an `"undefined reference to std::basic_string<...>"` error message. Then one more additional code line in the :file:`Android.mk` can help:
OpenCV binary package includes 3 samples having JNI resources:
.. code-block:: make
APP_PLATFORM := android-9
Practice: Build samples from OpenCV4Android SDK
===============================================
OpenCV4Android SDK includes 3 samples having JNI resources:
* *Tutorial 3 (Advanced) - Add Native OpenCV*
This sample illustrates how you can use OpenCV in C++ but without OpenCV Java API.
This sample illustrates how you can use OpenCV in C++ without OpenCV Java API.
@@ -231,7 +234,7 @@ Practice: Create an Android application, which uses OpenCV
To build your own Android application, which uses OpenCV from native part, the following steps should be done:
#. The archive with OpenCV binary package should be downloaded and extracted to some folder (e.g. ``C:\Work\android-opencv\OpenCV-2.4.0``)
#. The archive with OpenCV4Android SDK should be downloaded and extracted to some folder (e.g. :file:`C:\\Work\\OpenCV4Android\\OpenCV-2.4.0`).
#. You can use an environment variable to specify the location of OpenCV package or just hardcode full or relative path in the :file:`jni/Android.mk` of your projects.
