This tutorial was designed to help you with installation and configuration of OpenCV4Android SDK.
This guide was written with MS Windows 7 in mind, though it should work with GNU Linux and Apple MacOS as well.
This guide was written with MS Windows 7 in mind, though it should work with GNU Linux and Apple
Mac OS as well.
This tutorial assumes you have the following installed and configured:
This tutorial assumes you have the following software installed and configured:
* JDK
...
...
@@ -23,7 +24,20 @@ This tutorial assumes you have the following installed and configured:
If you need help with anything of the above, you may refer to our :ref:`android_dev_intro` guide.
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.
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.
Tegra Android Development Pack users
====================================
You may have used `Tegra Android Development Pack <http://developer.nvidia.com/tegra-android-development-pack>`_
(**TADP**) released by **NVIDIA** for Android development environment setup.
Beside Android development tools the TADP 2.0 includes OpenCV4Android SDK, so it can be already
installed in your system and you can skip to :ref:`Running_OpenCV_Samples` section of this tutorial.
More details regarding TADP can be found in the :ref:`android_dev_intro` guide.
General info
============
...
...
@@ -57,32 +71,44 @@ The structure of package contents looks as follows:
* :file:`sdk` folder contains OpenCV API and libraries for Android:
* :file:`sdk/java` folder contains an Android library Eclipse project providing OpenCV Java API that can be imported into developer's workspace;
* :file:`sdk/java` folder contains an Android library Eclipse project providing OpenCV Java API that
can be imported into developer's workspace;
* :file:`sdk/native` folder contains OpenCV C++ headers (for JNI code) and native Android libraries (\*\.so and \*\.a) for ARM-v5, ARM-v7a and x86 architectures;
* :file:`sdk/native` folder contains OpenCV C++ headers (for JNI code) and native Android libraries
(\*\.so and \*\.a) for ARM-v5, ARM-v7a and x86 architectures;
* :file:`sdk/etc` folder contains Haar and LBP cascades distributed with OpenCV.
* :file:`apk` folder contains Android packages that should be installed on the target Android device to enable OpenCV library access via OpenCV Manager API (see details below).
* :file:`apk` folder contains Android packages that should be installed on the target Android device
to enable OpenCV library access via OpenCV Manager API (see details below).
On production devices that have access to Google Play Market (and internet) these packages will be installed from Market on the first start of an application using OpenCV Manager API.
But dev kits without Market or internet require this packages to be installed manually.
(Install the `Manager.apk` and the corresponding `binary_pack.apk` depending on the device CPU, the Manager GUI provides this info).
On production devices that have access to Google Play Market (and Internet) these packages will be
installed from Market on the first start of an application using OpenCV Manager API.
But devkits without Market or Internet connection require this packages to be installed manually.
Install the `Manager.apk` and the corresponding `binary_pack.apk` depending on the device CPU,
the Manager GUI provides this info. Below you'll see exact commands on how to do this.
**Note**: installation from internet is the preferable way since we may publish updated versions of this packages on the Market.
.. note:: Installation from Internet is the preferable way since OpenCV team may publish updated
versions of this packages on the Market.
* :file:`samples` folder contains sample applications projects and their prebuilt packages (APK).
Import them into Eclipse workspace (like described below) and browse the code to learn possible ways of OpenCV use on Android.
Import them into Eclipse workspace (like described below) and browse the code to learn possible
ways of OpenCV use on Android.
* :file:`doc` folder contains various OpenCV documentation in PDF format.
It's also available online at http://docs.opencv.org.
**Note**: the most recent docs (nightly build) are at http://docs.opencv.org/trunk/.
.. note:: The most recent docs (nightly build) are at http://docs.opencv.org/trunk/.
Generally, it's more up-to-date, but can refer to not-yet-released functionality.
Starting version 2.4.3 `OpenCV4Android SDK` uses `OpenCV Manager` API for library initialization. `OpenCV Manager` is an Android service based solution providing the following benefits for OpenCV applications developers:
.. TODO: I'm not sure that this is the best place to talk about OpenCV Manager
* Compact apk-size, since all applications use the same binaries from Manager and do not store native libs within themselves;
Starting from version 2.4.3 `OpenCV4Android SDK` uses `OpenCV Manager` API for library
initialization. `OpenCV Manager` is an Android service based solution providing the following
benefits for OpenCV applications developers:
* Compact apk-size, since all applications use the same binaries from Manager and do not store
native libs within themselves;
* Hardware specific optimizations are automatically enabled on all supported platforms;
...
...
@@ -92,7 +118,6 @@ Starting version 2.4.3 `OpenCV4Android SDK` uses `OpenCV Manager` API for librar
..
For additional information on OpenCV Manager see the:
* |OpenCV4Android_Slides|_
...
...
@@ -106,29 +131,21 @@ For additional information on OpenCV Manager see the:
You may have used `Tegra Android Development Pack <http://developer.nvidia.com/tegra-android-development-pack>`_
(**TADP**) released by **NVIDIA** for Android development environment setup.
Beside Android development tools the TADP 2.0 includes OpenCV4Android SDK 2.4.2, so it can be already installed in your system and you can skip to running the ``face-detection`` sample.
More details regarding TADP can be found in the :ref:`android_dev_intro` guide.
Manual OpenCV4Android SDK setup
===============================
Get the OpenCV4Android SDK
--------------------------
#. Go to the `OpenCV dowload page on SourceForge <http://sourceforge.net/projects/opencvlibrary/files/opencv-android/>`_ and download the latest available version. Currently it's |opencv_android_bin_pack_url|_
#. Go to the `OpenCV download page on SourceForge <http://sourceforge.net/projects/opencvlibrary/files/opencv-android/>`_
and download the latest available version. Currently it's |opencv_android_bin_pack_url|_.
#. Create a new folder for Android with OpenCV development. For this tutorial I have unpacked OpenCV to the :file:`C:\\Work\\OpenCV4Android\\` directory.
#. Create a new folder for Android with OpenCV development. For this tutorial we have unpacked
OpenCV SDK to the :file:`C:\\Work\\OpenCV4Android\\` directory.
.. note:: Better to use a path without spaces in it. Otherwise you may have problems with :command:`ndk-build`.
#. Unpack the OpenCV package into the chosen directory.
#. Unpack the SDK archive into the chosen directory.
You can unpack it using any popular archiver (e.g with |seven_zip|_):
...
...
@@ -148,12 +165,13 @@ Get the OpenCV4Android SDK
.. |seven_zip| replace:: 7-Zip
.. _seven_zip: http://www.7-zip.org/
Open OpenCV library and samples in Eclipse
------------------------------------------
Import OpenCV library and samples to the Eclipse
------------------------------------------------
#. Start *Eclipse* and choose your workspace location.
#. Start Eclipse and choose your workspace location.
We recommend to start working with OpenCV for Android from a new clean workspace. A new Eclipse workspace can for example be created in the folder where you have unpacked OpenCV4Android SDK package:
We recommend to start working with OpenCV for Android from a new clean workspace. A new Eclipse
workspace can for example be created in the folder where you have unpacked OpenCV4Android SDK package:
.. image:: images/eclipse_1_choose_workspace.png
:alt: Choosing C:\Work\android-opencv\ as workspace location
...
...
@@ -162,24 +180,28 @@ Open OpenCV library and samples in Eclipse
#. Import OpenCV library and samples into workspace.
OpenCV library is packed as a ready-for-use `Android Library Project
<http://developer.android.com/guide/developing/projects/index.html#LibraryProjects>`_. You can simply reference it in your projects.
:alt: After small help Eclipse removes error icons!
.. image:: images/eclipse_cdt_cfg4.png
:alt: Configure CDT
:align: center
Once Eclipse completes build you will have the clean workspace without any build errors:
...
...
@@ -227,13 +235,17 @@ Open OpenCV library and samples in Eclipse
Running OpenCV Samples
----------------------
At this point you should be able to build and run the samples. Keep in mind, that ``face-detection``, ``Tutorial 3`` and ``Tutorial 4`` include some native code and require Android NDK and CDT plugin for Eclipse to build working applications.
If you haven't installed these tools see the corresponding section of :ref:`Android_Dev_Intro`.
At this point you should be able to build and run the samples. Keep in mind, that ``face-detection``,
``Tutorial 3`` and ``Tutorial 4`` include some native code and require Android NDK and CDT plugin
for Eclipse to build working applications. If you haven't installed these tools see the corresponding
section of :ref:`Android_Dev_Intro`.
Also, please consider that ``Tutorial 0`` and ``Tutorial 1`` samples use Java Camera API that definitelly accessible on emulator from the Android SDK.
Also, please consider that ``Tutorial 0`` and ``Tutorial 1`` samples use Java Camera API that
definitelly accessible on emulator from the Android SDK.
Other samples use OpenCV Native Camera which may not work with emulator.
.. note:: Recent *Android SDK tools, revision 19+* can run ARM v7a OS images but they available not for all Android versions.
.. note:: Recent *Android SDK tools, revision 19+* can run ARM v7a OS images but they available not
for all Android versions.
Well, running samples from Eclipse is very simple:
...
...
@@ -245,7 +257,8 @@ Well, running samples from Eclipse is very simple:
<http://developer.android.com/guide/developing/device.html>`_ for help with real devices (not emulators).
* Select project you want to start in :guilabel:`Package Explorer` and just press :kbd:`Ctrl + F11` or select option :menuselection:`Run --> Run` from the main menu, or click :guilabel:`Run` button on the toolbar.
* Select project you want to start in :guilabel:`Package Explorer` and just press :kbd:`Ctrl + F11`
or select option :menuselection:`Run --> Run` from the main menu, or click :guilabel:`Run` button on the toolbar.
.. note:: Android Emulator can take several minutes to start. So, please, be patient.
This guide was designed to help you in learning Android development basics and seting up your working environment quickly.
This guide was designed to help you in learning Android development basics and seting up your
working environment quickly. It was written with Windows 7 in mind, though it would work with Linux
(Ubuntu), Mac OS X and any other OS supported by Android SDK.
This guide was written with Windows 7 in mind, though it would work with Linux (Ubuntu), Mac OS X and any other OS supported by Android SDK.
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.
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.
Preface
=======
Android is a Linux-based, open source mobile operating system developed by Open Handset Alliance led by Google. See the `Android home site <http://www.android.com/about/>`_ for general details.
Android is a Linux-based, open source mobile operating system developed by Open Handset Alliance
led by Google. See the `Android home site <http://www.android.com/about/>`_ for general details.
Development for Android significantly differs from development for other platforms.
So before starting programming for Android we recommend you make sure that you are familiar with the following key topis:
So before starting programming for Android we recommend you make sure that you are familiar with the
following key topis:
#. `Java <http://en.wikipedia.org/wiki/Java_(programming_language)>`_ programming language that is
the primary development technology for Android OS. Also, you can find
`Oracle docs on Java <http://docs.oracle.com/javase/>`_ useful.
#. `Java Native Interface (JNI) <http://en.wikipedia.org/wiki/Java_Native_Interface>`_ that is a
technology of running native code in Java virtual machine. Also, you can find
`Oracle docs on JNI <http://docs.oracle.com/javase/7/docs/technotes/guides/jni/>`_ useful.
and its lifecycle, that is an essential Android API class.
#. OpenCV development will certainly require some knowlege of the
`Android Camera <http://developer.android.com/guide/topics/media/camera.html>`_ specifics.
#. `Java <http://en.wikipedia.org/wiki/Java_(programming_language)>`_ programming language that is the primary development technology for Android OS. Also, you can find `Oracle docs on Java <http://docs.oracle.com/javase/>`_ useful.
#. `Java Native Interface (JNI) <http://en.wikipedia.org/wiki/Java_Native_Interface>`_ that is a technology of running native code in Java virtual machine. Also, you can find `Oracle docs on JNI <http://docs.oracle.com/javase/7/docs/technotes/guides/jni/>`_ useful.
#. `Android Activity <http://developer.android.com/training/basics/activity-lifecycle/starting.html>`_ and its lifecycle, that is an essential Android API class.
#. OpenCV development will certainly require some knowlege of the `Android Camera <http://developer.android.com/guide/topics/media/camera.html>`_ specifics.
Quick environment setup for Android development
===============================================
If you are making a clean environment install, then you can try `Tegra Android Development Pack <http://developer.nvidia.com/mobile/tegra-android-development-pack>`_
If you are making a clean environment install, then you can try
`Tegra Android Development Pack <http://developer.nvidia.com/mobile/tegra-android-development-pack>`_
(**TADP**) released by **NVIDIA**.
When unpacked, TADP will cover all of the environment setup automatically and you can skip the rest of the guide.
If you are a beginner in Android development then we also recommend you to start with TADP.
.. note:: *NVIDIA*\ 's Tegra Android Development Pack includes some special features for |Nvidia_Tegra_Platform|_ but its use is not limited to *Tegra* devices only.
.. note:: *NVIDIA*\ 's Tegra Android Development Pack includes some special features for
|Nvidia_Tegra_Platform|_ but its use is not limited to *Tegra* devices only.
* You need at least *1.6 Gb* free disk space for the install.
* You need at least *1.6 Gb* free disk space for the install.
* TADP will download Android SDK platforms and Android NDK from Google's server, so Internet connection is required for the installation.
* TADP will download Android SDK platforms and Android NDK from Google's server, so Internet
connection is required for the installation.
* TADP may ask you to flash your development kit at the end of installation process. Just skip this step if you have no |Tegra_Development_Kit|_\ .
* TADP may ask you to flash your development kit at the end of installation process. Just skip
this step if you have no |Tegra_Development_Kit|_\ .
* (``UNIX``) TADP will ask you for *root* in the middle of installation, so you need to be a member of *sudo* group.
* (``UNIX``) TADP will ask you for *root* in the middle of installation, so you need to be a
for Ubuntu and Mac OS (only JDK sections are applicable for OpenCV)
.. note:: OpenJDK is not suitable for Android development, since Android SDK supports only Sun JDK.
If you use Ubuntu, after installation of Sun JDK you should run the following command to set Sun java environment:
If you use Ubuntu, after installation of Sun JDK you should run the following command to set
Sun java environment:
.. code-block:: bash
sudo update-java-alternatives --set java-6-sun
.. **TODO:** add a note on Sun/Oracle Java installation on Ubuntu 12.
.. TODO: Add a note on Sun/Oracle Java installation on Ubuntu 12.
#. **Android SDK**
...
...
@@ -83,9 +102,13 @@ You need the following software to be installed in order to develop for Android
Here is Google's `install guide <http://developer.android.com/sdk/installing.html>`_ for the SDK.
.. note:: If you choose SDK packed into a Windows installer, then you should have 32-bit JRE installed. It is not a prerequisite for Android development, but installer is a x86 application and requires 32-bit Java runtime.
.. note:: If you choose SDK packed into a Windows installer, then you should have 32-bit JRE
installed. It is not a prerequisite for Android development, but installer is a x86
application and requires 32-bit Java runtime.
.. note:: If you are running x64 version of Ubuntu Linux, then you need ia32 shared libraries for use on amd64 and ia64 systems to be installed. You can install them with the following command:
.. note:: If you are running x64 version of Ubuntu Linux, then you need ia32 shared libraries
for use on amd64 and ia64 systems to be installed. You can install them with the
following command:
.. code-block:: bash
...
...
@@ -101,51 +124,66 @@ You need the following software to be installed in order to develop for Android
You need the following SDK components to be installed:
* *Android SDK Tools, revision14* or newer.
* *Android SDK Tools, revision14* or newer.
Older revisions should also work, but they are not recommended.
The minimal platform supported by OpenCV Java API is **Android 2.2** (``API 8``). This is also the minimum API Level required for the provided samples to run.
The minimal platform supported by OpenCV Java API is **Android 2.2** (``API 8``). This is also
the minimum API Level required for the provided samples to run.
See the ``<uses-sdk android:minSdkVersion="8"/>`` tag in their **AndroidManifest.xml** files.
But for successful compilation of some samples the **target** platform should be set to Android 3.0 (API 11) or higher. It will not prevent them from running on Android 2.2.
But for successful compilation of some samples the **target** platform should be set to
Android 3.0 (API 11) or higher. It will not prevent them from running on Android 2.2.
.. image:: images/android_sdk_and_avd_manager.png
:height: 500px
:alt: Android SDK Manager
:align: center
See `Adding Platforms and Packages <http://developer.android.com/sdk/installing/adding-packages.html>`_ for help with installing/updating SDK components.
See `Adding Platforms and Packages <http://developer.android.com/sdk/installing/adding-packages.html>`_
for help with installing/updating SDK components.
#. **Eclipse IDE**
Check the `Android SDK System Requirements <http://developer.android.com/sdk/requirements.html>`_ document for a list of Eclipse versions that are compatible with the Android SDK.
For OpenCV 2.4.x we recommend **Eclipse 3.7 (Indigo)** or later versions. They work well for OpenCV under both Windows and Linux.
Check the `Android SDK System Requirements <http://developer.android.com/sdk/requirements.html>`_
document for a list of Eclipse versions that are compatible with the Android SDK.
For OpenCV 2.4.x we recommend **Eclipse 3.7 (Indigo)** or later versions. They work well for
OpenCV under both Windows and Linux.
If you have no Eclipse installed, you can get it from the `official site <http://www.eclipse.org/downloads/>`_.
#. **ADT plugin for Eclipse**
These instructions are copied from `Android Developers site <http://developer.android.com/sdk/installing/installing-adt.html>`_, check it out in case of any ADT-related problem.
These instructions are copied from
`Android Developers site <http://developer.android.com/sdk/installing/installing-adt.html>`_,
check it out in case of any ADT-related problem.
Assuming that you have Eclipse IDE installed, as described above, follow these steps to download and install the ADT plugin:
Assuming that you have Eclipse IDE installed, as described above, follow these steps to download
and install the ADT plugin:
#. Start Eclipse, then select :menuselection:`Help --> Install New Software...`
#. Click :guilabel:`Add` (in the top-right corner).
#. In the :guilabel:`Add Repository` dialog that appears, enter "ADT Plugin" for the Name and the following URL for the Location:
#. In the :guilabel:`Add Repository` dialog that appears, enter "ADT Plugin" for the Name and the
following URL for the Location:
https://dl-ssl.google.com/android/eclipse/
#. Click :guilabel:`OK`
.. note:: If you have trouble acquiring the plugin, try using "http" in the Location URL, instead of "https" (https is preferred for security reasons).
.. note:: If you have trouble acquiring the plugin, try using "http" in the Location URL,
instead of "https" (https is preferred for security reasons).
#. In the :guilabel:`Available Software` dialog, select the checkbox next to :guilabel:`Developer Tools` and click :guilabel:`Next`.
#. In the :guilabel:`Available Software` dialog, select the checkbox next to
:guilabel:`Developer Tools` and click :guilabel:`Next`.
#. In the next window, you'll see a list of the tools to be downloaded. Click :guilabel:`Next`.
.. TODO: Here we need user to check the presence of CDT plugin.
#. Read and accept the license agreements, then click :guilabel:`Finish`.
.. note:: If you get a security warning saying that the authenticity or validity of the software can't be established, click :guilabel:`OK`.
.. note:: If you get a security warning saying that the authenticity or validity of the software
can't be established, click :guilabel:`OK`.
#. When the installation completes, restart Eclipse.
...
...
@@ -158,27 +196,38 @@ You need the following software to be installed in order to develop for Android
To compile C++ code for Android platform you need ``Android Native Development Kit`` (*NDK*).
You can get the latest version of NDK from the `download page <http://developer.android.com/tools/sdk/ndk/index.html>`_. To install Android NDK just extract the archive to some folder on your computer. Here are `installation instructions <http://developer.android.com/tools/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/`.
.. note:: Before start you can read official Android NDK documentation which is in the Android
NDK archive, in the folder :file:`docs/`.
The main article about using Android NDK build system is in the :file:`ANDROID-MK.html` file.
Some additional information you can find in the :file:`APPLICATION-MK.html`, :file:`NDK-BUILD.html` files, and :file:`CPU-ARM-NEON.html`, :file:`CPLUSPLUS-SUPPORT.html`, :file:`PREBUILTS.html`.
Some additional information you can find in the :file:`APPLICATION-MK.html`,
:file:`NDK-BUILD.html` files, and :file:`CPU-ARM-NEON.html`, :file:`CPLUSPLUS-SUPPORT.html`,
:file:`PREBUILTS.html`.
#. **CDT plugin for Eclipse**
There are several possible ways to integrate compilation of C++ code by Android NDK into Eclipse compilation process.
We recommend the approach based on Eclipse :abbr:`CDT(C/C++ Development Tooling)` Builder.
There are several possible ways to integrate compilation of C++ code by Android NDK into Eclipse
compilation process. We recommend the approach based on Eclipse
:abbr:`CDT(C/C++ Development Tooling)` Builder.
.. important:: Make sure your Eclipse IDE has the :abbr:`CDT(C/C++ Development Tooling)` plugin installed. Menu :guilabel:`Help -> About Eclipse SDK` and push :guilabel:`Installation Details` button.
.. note:: If you're using the latest ADT plugin for Eclipse (version 20 and above), most likely
that you already have the CDT plugin. If it is so, just skip this section.
Make sure your Eclipse IDE has the :abbr:`CDT(C/C++ Development Tooling)` plugin
installed. Menu :guilabel:`Help -> About Eclipse SDK -> Installation Details`.
.. image:: images/eclipse_inst_details.png
:alt: Configure builders
:alt: Eclipse About
:align: center
To install the `CDT plugin <http://eclipse.org/cdt/>`_ use menu :guilabel:`Help -> Install New Software...`,
then paste the CDT 8.0 repository URL http://download.eclipse.org/tools/cdt/releases/indigo as shown in the picture below and click :guilabel:`Add...`, name it *CDT* and click :guilabel:`OK`.
To install the `CDT plugin <http://eclipse.org/cdt/>`_ use menu
:guilabel:`Help -> Install New Software...`, then paste the CDT 8.0 repository URL
http://download.eclipse.org/tools/cdt/releases/indigo as shown in the picture below and click
:guilabel:`Add...`, name it *CDT* and click :guilabel:`OK`.
.. image:: images/eclipse_inst_cdt.png
:alt: Configure builders
...
...
@@ -192,6 +241,7 @@ You need the following software to be installed in order to develop for Android
That's it. Compilation of C++ code is fully integrated into Eclipse building process now.
Android application structure
=============================
...
...
@@ -213,27 +263,32 @@ Usually source 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:`res` folder contains resources of the application (images, xml files describing UI
layout, etc),
* 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`
producing the native libraries,
* and the :file:`jni` folder contains C/C++ application source code and NDK's build scripts
:file:`Android.mk` and :file:`Application.mk` producing the native libraries,
* :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).
* :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 :command:`android` tool from Android SDK.
* :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 included in Android SDK.
* :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 included in Android SDK.
.. note:: Both :file:`AndroidManifest.xml` and :file:`project.properties` files are required to
compile the C++ part of the application, since Android 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.
.. note:: Both files (:file:`AndroidManifest.xml` and :file:`project.properties`) are required to compile the C++ part of the application,
since Android 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.
:file:`Android.mk` and :file:`Application.mk` scripts
@@ -254,9 +309,11 @@ The script :file:`Android.mk` usually has the following structure:
include $(BUILD_SHARED_LIBRARY)
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`.
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 created. 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
:linenos:
...
...
@@ -285,7 +342,8 @@ Here is the standard way to compile C++ part of an Android application:
<path_where_NDK_is_placed>/ndk-build
.. note:: On Windows we recommend to use ``ndk-build.cmd`` in standard Windows console (``cmd.exe``) rather than the similar ``bash`` script in ``Cygwin`` shell.
.. note:: On Windows we recommend to use ``ndk-build.cmd`` in standard Windows console (``cmd.exe``)
rather than the similar ``bash`` script in ``Cygwin`` shell.
.. image:: images/ndk_build.png
:alt: NDK build
...
...
@@ -314,22 +372,22 @@ After that the Java part of the application can be (re)compiled (using either *E
Building application native part from *Eclipse* (CDT Builder)
There are several possible ways to integrate compilation of native C++ code by Android NDK into Eclipse build process.
We recommend the approach based on Eclipse :abbr:`CDT(C/C++ Development Tooling)` Builder.
.. important:: Make sure your Eclipse IDE has the :abbr:`CDT(C/C++ Development Tooling)` plugin installed. Menu :guilabel:`Help -> About Eclipse SDK -> Installation Details`.
There are several possible ways to integrate compilation of native C++ code by Android NDK into
Eclipse build process. We recommend the approach based on Eclipse
:abbr:`CDT(C/C++ Development Tooling)` Builder.
.. image:: images/eclipse_inst_details.png
:alt: Eclipse About
:align: center
.. important:: OpenCV for Android package since version 2.4.2 contains sample projects
pre-configured CDT Builders. For your own projects follow the steps below.
.. important:: OpenCV for Android package since version 2.4.2 contains sample projects pre-configured CDT Builders. For your own projects follow the steps below.
#. Define the ``NDKROOT`` environment variable containing the path to Android NDK in your system
(e.g. ``"X:\\Apps\\android-ndk-r8"`` or ``"/opt/android-ndk-r8"``).
#. Define the ``NDKROOT`` environment variable containing the path to Android NDK in your system (e.g. ``"X:\\Apps\\android-ndk-r8"`` or ``"/opt/android-ndk-r8"``).
**On Windows** an environment variable can be set via :guilabel:`My Computer -> Properties -> Advanced -> Environment variables` and restarting Eclipse.
**On Windows** an environment variable can be set via
On Windows 7 it's also possible to use `setx <http://ss64.com/nt/setx.html>`_ command in a console session.
**On Linux** and **MacOS** an environment variable can be set via appending a ``"export VAR_NAME=VAR_VALUE"`` line to the :file:`"~/.bashrc"` file and logging off and then on.
**On Linux** and **MacOS** an environment variable can be set via appending a
``"export VAR_NAME=VAR_VALUE"`` line to the :file:`"~/.bashrc"` file and logging off and then on.
#. Open Eclipse and load the Android app project to configure.
...
...
@@ -345,13 +403,15 @@ We recommend the approach based on Eclipse :abbr:`CDT(C/C++ Development Tooling)
:alt: Configure CDT
:align: center
#. Select the project(s) to convert. Specify "Project type" = ``Makefile project``, "Toolchains" = ``Other Toolchain``.
#. Select the project(s) to convert. Specify "Project type" = ``Makefile project``,
"Toolchains" = ``Other Toolchain``.
.. image:: images/eclipse_cdt_cfg3.png
:alt: Configure CDT
:align: center
#. Open :guilabel:`Project Properties -> C/C++ Build`, unckeck ``Use default build command``, replace "Build command" text from ``"make"`` to
@@ -373,13 +433,15 @@ We recommend the approach based on Eclipse :abbr:`CDT(C/C++ Development Tooling)
:alt: Configure CDT
:align: center
#. If you open your C++ source file in Eclipse editor, you'll see syntax error notifications. They are not real errors, but additional CDT configuring is required.
#. If you open your C++ source file in Eclipse editor, you'll see syntax error notifications.
They are not real errors, but additional CDT configuring is required.
.. image:: images/eclipse_cdt_cfg7.png
:alt: Configure CDT
:align: center
#. Open :guilabel:`Project Properties -> C/C++ General -> Paths and Symbols` and add the following **Include** paths for **C++**:
#. Open :guilabel:`Project Properties -> C/C++ General -> Paths and Symbols` and add the following
**Include** paths for **C++**:
::
...
...
@@ -396,7 +458,8 @@ We recommend the approach based on Eclipse :abbr:`CDT(C/C++ Development Tooling)
:alt: Configure CDT
:align: center
.. note:: The latest Android NDK **r8b** uses different STL headers path. So if you use this NDK release add the following **Include** paths list instead:
.. note:: The latest Android NDK **r8b** uses different STL headers path. So if you use this NDK
release add the following **Include** paths list instead:
::
...
...
@@ -408,46 +471,62 @@ We recommend the approach based on Eclipse :abbr:`CDT(C/C++ Development Tooling)
Debugging and Testing
=====================
In this section we will give you some easy-to-follow instructions on how to set up an emulator or hardware device for testing and debugging an Android project.
In this section we will give you some easy-to-follow instructions on how to set up an emulator or
hardware device for testing and debugging an Android project.
AVD
---
AVD (*Android Virtual Device*) is not probably the most convenient way to test an OpenCV-dependent application, but sure the most uncomplicated one to configure.
AVD (*Android Virtual Device*) is not probably the most convenient way to test an OpenCV-dependent
application, but sure the most uncomplicated one to configure.
#. Assuming you already have *Android SDK* and *Eclipse IDE* installed, in Eclipse go :guilabel:`Window -> AVD Manager`.
#. Assuming you already have *Android SDK* and *Eclipse IDE* installed, in Eclipse go
:guilabel:`Window -> AVD Manager`.
.. **TBD:** how to start AVD Manager without Eclipse...
.. TODO: how to start AVD Manager without Eclipse...
#. Press the :guilabel:`New` button in :guilabel:`AVD Manager` window.
#. :guilabel:`Create new Android Virtual Device` window will let you select some properties for your new device, like target API level, size of SD-card and other.
#. :guilabel:`Create new Android Virtual Device` window will let you select some properties for your
new device, like target API level, size of SD-card and other.
.. image:: images/AVD_create.png
:alt: Configure builders
:align: center
#. When you click the :guilabel:`Create AVD` button, your new AVD will be availible in :guilabel:`AVD Manager`.
#. Press :guilabel:`Start` to launch the device. Be aware that any AVD (a.k.a. Emulator) is usually much slower than a hardware Android device, so it may take up to several minutes to start.
#. Go :guilabel:`Run -> Run/Debug` in Eclipse IDE to run your application in regular or debugging mode. :guilabel:`Device Chooser` will let you choose among the running devices or to start a new one.
#. Press :guilabel:`Start` to launch the device. Be aware that any AVD (a.k.a. Emulator) is usually
much slower than a hardware Android device, so it may take up to several minutes to start.
#. Go :guilabel:`Run -> Run/Debug` in Eclipse IDE to run your application in regular or debugging
mode. :guilabel:`Device Chooser` will let you choose among the running devices or to start a new one.
Hardware Device
---------------
If you have an Android device, you can use it to test and debug your applications. This way is more authentic, though a little bit harder to set up. You need to make some actions for Windows and Linux operating systems to be able to work with Android devices. No extra actions are required for Mac OS. See detailed information on configuring hardware devices in subsections below.
If you have an Android device, you can use it to test and debug your applications. This way is more
authentic, though a little bit harder to set up. You need to make some actions for Windows and Linux
operating systems to be able to work with Android devices. No extra actions are required for Mac OS.
See detailed information on configuring hardware devices in subsections below.
You may also consult the official `Android Developers site instructions <http://developer.android.com/tools/device.html>`_ for more information.
You may also consult the official
`Android Developers site instructions <http://developer.android.com/tools/device.html>`_
for more information.
Windows host computer
^^^^^^^^^^^^^^^^^^^^^
#. Enable USB debugging on the Android device (via :guilabel:`Settings` menu).
#. Attach the Android device to your PC with a USB cable.
#. Go to :guilabel:`Start Menu` and **right-click** on :guilabel:`Computer`. Select :guilabel:`Manage` in the context menu. You may be asked for Administrative permissions.
#. Select :guilabel:`Device Manager` in the left pane and find an unknown device in the list. You may try unplugging it and then plugging back in order to check whether it's your exact equipment appears in the list.
#. Go to :guilabel:`Start Menu` and **right-click** on :guilabel:`Computer`.
Select :guilabel:`Manage` in the context menu. You may be asked for Administrative permissions.
#. Select :guilabel:`Device Manager` in the left pane and find an unknown device in the list.
You may try unplugging it and then plugging back in order to check whether it's your exact
equipment appears in the list.
.. image:: images/usb_device_connect_01.png
:alt: Unknown device
:align: center
#. Try your luck installing `Google USB drivers` without any modifications: **right-click** on the unknown device, select :guilabel:`Properties` menu item --> :guilabel:`Details` tab --> :guilabel:`Update Driver` button.
#. Try your luck installing `Google USB drivers` without any modifications: **right-click** on the
unknown device, select :guilabel:`Properties` menu item --> :guilabel:`Details` tab -->
:guilabel:`Update Driver` button.
.. image:: images/usb_device_connect_05.png
:alt: Device properties
...
...
@@ -465,13 +544,15 @@ Windows host computer
:alt: Browse for driver
:align: center
#. If you get the prompt to install unverified drivers and report about success - you've finished with USB driver installation.
#. If you get the prompt to install unverified drivers and report about success - you've finished
with USB driver installation.
.. image:: images/usb_device_connect_08.png
:alt: Install prompt
:align: center
` `
.. FIXME: All such places should be replaced with something else! This is a bad separator.
.. image:: images/usb_device_connect_09.png
:alt: Installed OK
...
...
@@ -483,13 +564,15 @@ Windows host computer
:alt: No driver
:align: center
#. Again **right-click** on the unknown device, select :guilabel:`Properties --> Details --> Hardware Ids` and copy the line like ``USB\VID_XXXX&PID_XXXX&MI_XX``.
#. Again **right-click** on the unknown device, select :guilabel:`Properties --> Details --> Hardware Ids`
and copy the line like ``USB\VID_XXXX&PID_XXXX&MI_XX``.
.. image:: images/usb_device_connect_02.png
:alt: Device properties details
:align: center
#. Now open file :file:`<Android SDK folder>/extras/google/usb_driver/android_winusb.inf`. Select either ``Google.NTx86`` or ``Google.NTamd64`` section depending on your host system architecture.
#. Now open file :file:`<Android SDK folder>/extras/google/usb_driver/android_winusb.inf`. Select
either ``Google.NTx86`` or ``Google.NTamd64`` section depending on your host system architecture.
.. image:: images/usb_device_connect_03.png
:alt: "android_winusb.inf"
...
...
@@ -543,17 +626,23 @@ Windows host computer
:alt: "adb devices"
:align: center
#. Now, in Eclipse go :guilabel:`Run -> Run/Debug` to run your application in regular or debugging mode. :guilabel:`Device Chooser` will let you choose among the devices.
#. Now, in Eclipse go :guilabel:`Run -> Run/Debug` to run your application in regular or debugging
mode. :guilabel:`Device Chooser` will let you choose among the devices.
Linux host computer
^^^^^^^^^^^^^^^^^^^
By default Linux doesn't recognize Android devices, but it's easy to fix this issue. On Ubuntu Linux you have to create a new **/etc/udev/rules.d/51-android.rules** configuration file that contains information about your Android device. You may find some Vendor ID's `here <http://developer.android.com/tools/device.html#VendorIds>`_ or execute :command:`lsusb` command to view VendorID of plugged Android device. Here is an example of such file for LG device:
By default Linux doesn't recognize Android devices, but it's easy to fix this issue. On Ubuntu Linux
you have to create a new **/etc/udev/rules.d/51-android.rules** configuration file that contains
information about your Android device. You may find some Vendor ID's
`here <http://developer.android.com/tools/device.html#VendorIds>`_ or execute :command:`lsusb`
command to view VendorID of plugged Android device. Here is an example of such file for LG device:
Then restart your adb server (even better to restart the system), plug in your Android device and execute :command:`adb devices` command. You will see the list of attached devices:
Then restart your adb server (even better to restart the system), plug in your Android device and
execute :command:`adb devices` command. You will see the list of attached devices:
.. image:: images/usb_device_connect_ubuntu.png
:alt: List of attached devices
...
...
@@ -566,4 +655,5 @@ No actions are required, just connect your device via USB and run ``adb devices`
What's next
===========
Now, when you have your development environment set up and configured, you may want to proceed to installing OpenCV4Android SDK. You can learn how to do that in a separate :ref:`O4A_SDK` tutorial.
\ No newline at end of file
Now, when you have your development environment set up and configured, you may want to proceed to
installing OpenCV4Android SDK. You can learn how to do that in a separate :ref:`O4A_SDK` tutorial.
