@@ -149,6 +149,8 @@ Open OpenCV library and samples in Eclipse
#. Configure your ADT plugin
.. important:: ADT plugin settings are workspace-dependent. So you have to repeat this step each time when you create a new workspace.
Once you have created a new workspace, you have to point the ADT plugin to the Android SDK directory. This setting is stored in workspace metadata, as result this step is required each time when you are creating new workspace for Android development. See `Configuring the ADT Plugin
<http://developer.android.com/sdk/eclipse-adt.html#configuring>`_ document for the original instructions from *Google*.
...
...
@@ -232,9 +234,9 @@ Open OpenCV library and samples in Eclipse
Running OpenCV Samples
======================
At this point you should be able to build and run all samples except two from Advanced tutorial (these samples require Android NDK to build working applications, see the document :ref:`Android_Binary_Package_with_NDK`).
At this point you should be able to build and run all samples except two from Advanced tutorial (these samples require Android NDK to build working applications, see the next tutorial :ref:`Android_Binary_Package_with_NDK` to learn how to compile them).
Also I want to note that only ``Tutorial 1 Basic - 0. Android Camera`` and ``Tutorial 1 Basic - 1. Add OpenCV`` samples are able to run on Emulator from Android SDK. Other samples are using OpenCV Native Camera which is supported only for ARM v7 CPUs.
Also I want to note that only ``Tutorial 1 Basic - 0. Android Camera`` and ``Tutorial 1 Basic - 1. Add OpenCV`` samples are able to run on Emulator from Android SDK. Other samples are using OpenCV Native Camera which does not work with emulator.
.. note:: Latest *Android SDK tools, revision 12* can run ARM v7 OS images but *Google* does not provide such images with SDK.
...
...
@@ -250,6 +252,8 @@ Well, running samples from Eclipse is very simple:
* Select project you want to start in *Package Explorer* and just press **Ctrl + F11** or select option **Run** > **Run** from main menu, or click **Run** button on the toolbar.
.. note:: Android Emulator can take several minutes to start. So, please, be patient.
* On the first run Eclipse will ask you how to run your application:
This tutorial describes a fast way how to create and build Android applications containing OpenCV code written in C++ with OpenCV binary package.
Using C++ OpenCV code with Android binary package
*************************************************
The Android way is writing all your code in Java. But somethimes it is not enough and you need to go to a native level and write part of your application in C/C++.
This is important when you already have some computer vision functionality which is written in C++ and uses OpenCV, and you want to use 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 mechanism.
It means, that you should add a class with native methods wrapping your C++ functionality into the Java part of your Android application.
This tutorial describes a fast way how 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.
Please note that before starting this tutorial you should fulfill all the steps, described in the tutorial :ref:`Android_Binary_Package`.
The tutorial was tested using Ubuntu 10.04 operating systems (Windows 7 SP1 coming soon).
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 *android-opencv* discussion group https://groups.google.com/group/android-opencv/ and we will try to help you.
Prerequisites: Setup NDK
========================
To compile C++ code for Android platform you need Android NDK.
To compile C++ code for Android platform you need Android **N**\ ative **D**\ evelopment **K**\ it (*NDK*).
You can get the latest version of NDK from the page http://developer.android.com/sdk/ndk/index.html .
To install Android NDK just extract the archive to some folder on your computer. Here is installation instructions on the NDK home page: http://developer.android.com/sdk/ndk/index.html#installing
To install Android NDK just extract the archive to some folder on your computer. (Here is installation instructions on the NDK home page: http://developer.android.com/sdk/ndk/index.html#installing)
.. note:: Before start you can read official Android NDK documentation which is in the Android NDK archive, in the folder :file:`docs/`.
...
...
@@ -58,29 +59,29 @@ Usually code of an Android application has the following structure:
where
+ the :file:`src` folder contains the Java code of the application,
+ 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,
+ and the :file:`jni` folder contains C/C++ application source code and NDK build scripts :file:`Android.mk` and :file:`Application.mk`.
+ 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).
Also the root folder should contain the following files
* the :file:`AndroidManifest.xml` file presents essential information about the application to the Android system
(name of the Application, name of the main application's Java package, components of the application, required permissions, etc)
* :file:`AndroidManifest.xml` file presents essential information about application to the Android system
(name of the Application, name of main application's package, components of the application, required permissions, etc)
It can be created using Eclipse wizard or :file:`android` tool from Android SDK
* the :file:`default.properties` is a text file containing information about target Android platform and other build details.
* :file:`default.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 :file:`android` tool from Android SDK
.. note:: Both files (AndroidManifest.xml and default.properties) are required to compile the C++ part of the application (the Android build system uses information from these files). If the files don't exist, compile the Java part of the project before the C++ part of the project.
.. note:: Both files (:file:`AndroidManifest.xml` and :file:`default.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.
Theory: How to build Android application having C++ native part (from command line)
...
...
@@ -98,19 +99,15 @@ Here is the standard way to compile C++ part of an Android application:
#. Run the following command
+ *UNIX*
.. code-block:: bash
<path_where_NDK_is_placed>/ndk-build
.. code-block:: bash
+ *Cygwin*
<path_where_NDK_is_placed>/ndk-build
.. code-block:: bash
.. note:: If you are working in *cygwin* shell and encounter an error saying that NDK does not find some *cygwin*\ 's path then you might need to define the following environment variable:
export NDK_USE_CYGPATH=1
<path_where_NDK_is_placed>/ndk-build
.. code-block:: bash
export NDK_USE_CYGPATH=1
#. After executing this command the C++ part of the source code is compiled.
...
...
@@ -139,13 +136,13 @@ Theory: How to build Android application having C++ native part (from *Eclipse*)
There are several possible ways to integrate compilation of C++ code by Android NDK into Eclipse compilation process. We recommend the approach taken from this site: http://mobilepearls.com/labs/ndk-builder-in-eclipse/
.. important:: This instructions should be applied for each Android project in *Eclipse* workspace, which contains native C++ code.
.. important:: This instructions should be applied for each Android project in *Eclipse* workspace. So if you have 3 projects having C++ part then you need to configure 3 builders.
Below is an adapted version of this guide:
#. Navigate to *Package Explorer* window and expand your project having JNI resources.
If you can not see :file:`libs` folder under this project then you need to create it manually.
If you can not see :file:`libs` folder under this project then you need to create it manually. (It will be required on step 7, but you need to create it before you open project properties.)
#. Right click on your project in *Package Explorer* window and select *Properties*.
...
...
@@ -179,22 +176,19 @@ Below is an adapted version of this guide:
- Put full path to :file:`ndk-build` into the *Arguments* field E.g. :file:`C:\\Android\\android-ndk-r6\\ndk-build`.
- Go to the *Environment* tab and define 2 environment variables:
- Go to the *Environment* tab and define an environment variable:
* **PATH** - full path to the *cygwin* tools. E.g. :file:`C:\\cygwin\\bin`
* **NDK_USE_CYGPATH** - set to 1
.. image:: images/eclipse_windows_environment.png
:alt: Define environment variables
:align: center
.. image:: images/eclipse_windows_environment.png
:alt: Define environment variables
:align: center
* *Working Directory* - put path to your project into this field. Instead of hardcoding full path you can click *Browse Workspace..." button and select your project.
#. Go to the *Refresh* tab and select both *"Refresh resources upon completion"* and *"Recursively include sub-folders"*.
...
...
@@ -248,7 +242,7 @@ The script :file:`Android.mk` usually have the following structure:
include $(BUILD_SHARED_LIBRARY)
This is the minimal 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 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`.
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`:
...
...
@@ -321,7 +315,7 @@ To build your own Android application, which uses OpenCV from native part, the f
If you are setting NDK builder as described above in :ref:`Android_NDK_integration_with_Eclipse`, then you can define this variable in builder settings. It can be done on third *Environment* tab of the builder configuration window (we have already added some variables to this tab on *Windows* but skipped it for other platforms).
# The file :file:`jni/Android.mk` should be written for the current application using the common rules for the file.
#. The file :file:`jni/Android.mk` should be written for the current application using the common rules for the file.
For detailed information see the Android NDK documentation from the Android NDK archive, in the file
