tutorial updated
@ -60,7 +60,7 @@ You need the following tools to be installed:
|
||||
|
||||
#. **Android SDK**
|
||||
|
||||
Get the latest Android SDK from http://developer.android.com/sdk/index.html
|
||||
Get the latest ``Android SDK`` from http://developer.android.com/sdk/index.html
|
||||
|
||||
Here is Google's `install guide <http://developer.android.com/sdk/installing.html>`_ for SDK.
|
||||
|
||||
@ -284,9 +284,9 @@ 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 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 does not work with emulator.
|
||||
Also I want to note that only ``Tutorial 0 - Android Camera`` and ``Tutorial 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 14* can run ARM v7 OS images but *Google* provides such image for Android 4.x only.
|
||||
.. note:: Latest *Android SDK tools, revision 19* can run ARM v7a OS images but *Google* provides such image for Android 4.x only.
|
||||
|
||||
Well, running samples from Eclipse is very simple:
|
||||
|
||||
@ -310,7 +310,7 @@ Well, running samples from Eclipse is very simple:
|
||||
|
||||
* Select the :guilabel:`Android Application` option and click :guilabel:`OK` button. Eclipse will install and run the sample.
|
||||
|
||||
Here is ``Tutorial 1 Basic - 1. Add OpenCV`` sample detecting edges using Canny algorithm from OpenCV:
|
||||
Here is ``Tutorial 1 - Add OpenCV`` sample detecting edges using Canny algorithm from OpenCV:
|
||||
|
||||
.. image:: images/emulator_canny.png
|
||||
:height: 600px
|
||||
|
@ -17,17 +17,18 @@ This tutorial describes a fast way how to create and build Android applications
|
||||
Please note that before starting this tutorial you should fulfill 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 *android-opencv* discussion group https://groups.google.com/group/android-opencv/ and we will try to help you.
|
||||
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 <https://groups.google.com/group/android-opencv/>`_ discussion group and we will try to help you.
|
||||
|
||||
|
||||
Prerequisites: Setup NDK
|
||||
========================
|
||||
|
||||
To compile C++ code for Android platform you need Android **N**\ ative **D**\ evelopment **K**\ it (*NDK*).
|
||||
To compile C++ code for Android platform you need ``Android Native Development Kit`` (*NDK*).
|
||||
|
||||
You can get the latest version of NDK from the page http://developer.android.com/sdk/ndk/index.html .
|
||||
You can get the latest version of NDK from the `download 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 <http://developer.android.com/sdk/ndk/index.html#installing>`_ on the NDK home page.)
|
||||
|
||||
.. note:: Before start you can read official Android NDK documentation which is in the Android NDK archive, in the folder :file:`docs/`.
|
||||
|
||||
@ -53,7 +54,7 @@ Usually code of an Android application has the following structure:
|
||||
|
||||
- :file:`AndroidManifest.xml`
|
||||
|
||||
- :file:`default.properties`
|
||||
- :file:`project.properties`
|
||||
|
||||
- :file:`... other files ...`
|
||||
|
||||
@ -77,11 +78,13 @@ Also the root folder should contain the following files
|
||||
|
||||
It can be created using Eclipse wizard or :command:`android` tool from Android SDK
|
||||
|
||||
* :file:`default.properties` is a text file containing information about target Android platform and other build details.
|
||||
* :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
|
||||
|
||||
.. 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.
|
||||
.. 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.
|
||||
|
||||
.. _NDK_build_cli:
|
||||
|
||||
|
||||
Theory: How to build Android application having C++ native part (from command line)
|
||||
@ -103,11 +106,11 @@ Here is the standard way to compile C++ part of an Android application:
|
||||
|
||||
<path_where_NDK_is_placed>/ndk-build
|
||||
|
||||
.. 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:
|
||||
.. note:: On Windows we recomend use of ``ndk-build.cmd`` in standard Windows console (``cmd.exe``) rather than the similar ``bash`` script in ``Cygwin`` shell.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export NDK_USE_CYGPATH=1
|
||||
.. image:: images/ndk_build.png
|
||||
:alt: NDK build
|
||||
:align: center
|
||||
|
||||
#. After executing this command the C++ part of the source code is compiled.
|
||||
|
||||
@ -134,95 +137,66 @@ After that the Java part of the application can be (re)compiled (using either *E
|
||||
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/
|
||||
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:: 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.
|
||||
.. important:: Make sure your Eclipse IDE has the :abbr:`CDT(C/C++ Development Tooling)` plugin installed. (Menu ``Help`` -> ``About Eclipse SDK`` -> ``Installation Details``)
|
||||
|
||||
Below is an adapted version of this guide:
|
||||
.. image:: images/eclipse_inst_details.png
|
||||
:alt: Configure builders
|
||||
:align: center
|
||||
|
||||
#. Navigate to :guilabel:`Package Explorer` window and expand your project having JNI resources.
|
||||
To install the `CDT plugin <http://eclipse.org/cdt/>`_ use menu ``Help`` -> ``Install New Software...``,
|
||||
then paste the CDT 8.0 repository URL http://download.eclipse.org/tools/cdt/releases/indigo as shown on the picture below and click :guilabel:`Add...`, name it *CDT* and click :guilabel:`OK`.
|
||||
|
||||
.. image:: images/eclipse_inst_cdt.png
|
||||
:alt: Configure builders
|
||||
:align: center
|
||||
|
||||
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.)
|
||||
``CDT Main Features`` should be enough:
|
||||
|
||||
.. image:: images/eclipse_inst_cdt_2.png
|
||||
:alt: Configure builders
|
||||
:align: center
|
||||
.. important:: This instructions should be applied for each Android project in *Eclipse* workspace having native (JNI) part to build.
|
||||
|
||||
#. Right click on your project in :guilabel:`Package Explorer` window and select :guilabel:`Properties`.
|
||||
#. Right click on your project in :guilabel:`Package Explorer` window and select :guilabel:`New` -> :guilabel:`Other`:
|
||||
|
||||
#. In the :guilabel:`Properties` dialog select :guilabel:`Builders` menu and press the :guilabel:`New...` button:
|
||||
|
||||
.. image:: images/eclipse_builders.png
|
||||
:alt: Configure builders
|
||||
.. image:: images/eclipse_cdt_cfg1.png
|
||||
:alt: Configure CDT
|
||||
:align: center
|
||||
|
||||
#. In the resulting dialog select the :guilabel:`Program` type and press :guilabel:`OK` button:
|
||||
#. Select :guilabel:`C/C++` -> :guilabel:`Convert to C/C++ project`:
|
||||
|
||||
.. image:: images/eclipse_builder_types.png
|
||||
:alt: Choose builder type
|
||||
.. image:: images/eclipse_cdt_cfg2.png
|
||||
:alt: Configure CDT
|
||||
:align: center
|
||||
|
||||
#. In the :guilabel:`Main` tab fill the following fields:
|
||||
#. Select :guilabel:`"C++"`, :guilabel:`"Makefile Project"`, :guilabel:`"Other Toolchain"`:
|
||||
|
||||
* :guilabel:`Name` - any name for your builder. ("Tutorial 2.1 Builder" in my case.)
|
||||
.. image:: images/eclipse_cdt_cfg3.png
|
||||
:alt: Configure CDT
|
||||
:align: center
|
||||
|
||||
.. note:: This name has to be unique for each project in your workspace.
|
||||
#. Right click on your project in :guilabel:`Package Explorer` window and select :guilabel:`Properties`, then :guilabel:`C/C++ Build` in the left pane.
|
||||
Unckeck :guilabel:`Use default build command` and put ndk-build invocation in the :guilabel:`Build command` edit box and click :guilabel:`Apply` :
|
||||
|
||||
* :guilabel:`Location` - full path to :command:`ndk-build` tool.
|
||||
.. image:: images/eclipse_cdt_cfg4.png
|
||||
:alt: Configure CDT
|
||||
:align: center
|
||||
|
||||
+ *UNIX*
|
||||
#. Select :guilabel:`Builders` in the left pane, select :guilabel:`"CDT Builder"`, press :guilabel:`Edit` button on the righ and set check-boxes as on the picture below for automatic rebuild of JNI part:
|
||||
|
||||
Just put full path to :command:`ndk-build` into this filed. Also you can add some options to the :guilabel:`Arguments:guilabel:` fied, for example ``-B`` option.
|
||||
.. image:: images/eclipse_cdt_cfg5.png
|
||||
:alt: Configure CDT
|
||||
:align: center
|
||||
|
||||
+ *Cygwin*
|
||||
|
||||
- Instead of path to the :command:`ndk-build` tool you need to put full path to *cygwin*\ 's :program:`bash.exe` location. E.g: :file:`C:\\cygwin\\bin\\bash.exe`.
|
||||
#. Use menu :guilabel:`Project` -> :guilabel:`Clean...` to make sure that NDK build is invoked on the project build:
|
||||
|
||||
- Put full path to :command:`ndk-build` into the :guilabel:`Arguments` field E.g. :file:`C:\\Android\\android-ndk-r6\\ndk-build`.
|
||||
|
||||
- Go to the :guilabel:`Environment` tab and define an environment variable:
|
||||
|
||||
* :envvar:`PATH` - full path to the *cygwin* tools. E.g. :file:`C:\\cygwin\\bin`
|
||||
|
||||
.. image:: images/eclipse_windows_environment.png
|
||||
:alt: Define environment variables
|
||||
:align: center
|
||||
|
||||
* :guilabel:`Working Directory` - put path to your project into this field. Instead of hardcoding full path you can click :guilabel:`Browse Workspace...` button and select your project.
|
||||
|
||||
.. image:: images/eclipse_edit_configuration_main.png
|
||||
:alt: Define environment variables
|
||||
:align: center
|
||||
|
||||
#. Go to the :guilabel:`Refresh` tab and select both :guilabel:`Refresh resources upon completion` and :guilabel:`Recursively include sub-folders`.
|
||||
|
||||
Next set the :guilabel:`Specific resources` option and click :guilabel:`Specify resources...` button:
|
||||
|
||||
.. image:: images/eclipse_edit_configuration_refresh.png
|
||||
:alt: Define environment variables
|
||||
:align: center
|
||||
|
||||
#. Select :file:`libs` folder under your project and click :guilabel:`Finish`:
|
||||
|
||||
.. image:: images/eclipse_edit_configuration_specify_resources.png
|
||||
:alt: Select resources folder to refresh automatically
|
||||
:align: center
|
||||
|
||||
#. Go to the last tab :guilabel:`Build options`. Make sure that all checkboxes are set as shown on the next screen:
|
||||
|
||||
.. image:: images/eclipse_edit_configuration_build_options.png
|
||||
:alt: Configure build options
|
||||
:align: center
|
||||
|
||||
#. Next, click the :guilabel:`Specify resources...` button.
|
||||
|
||||
#. Select :file:`jni` folder of your project and click the :guilabel:`Finish` button:
|
||||
|
||||
.. image:: images/eclipse_edit_configuration_build_resources.png
|
||||
:alt: Select resources to build
|
||||
:align: center
|
||||
|
||||
#. Finally press :guilabel:`OK` in the builder configuration and project properties dialogs. If you have automatic build turned on then console showing build log should appear:
|
||||
|
||||
.. image:: images/eclipse_NDK_build_success.png
|
||||
:alt: Select resources to build
|
||||
:align: center
|
||||
.. image:: images/eclipse_ndk_build.png
|
||||
:alt: Select resources folder to refresh automatically
|
||||
:align: center
|
||||
|
||||
Theory: The structure of :file:`Android.mk` and :file:`Application.mk` scripts
|
||||
==============================================================================
|
||||
@ -255,65 +229,30 @@ Usually the file :file:`Application.mk` is optional, but in case of project usin
|
||||
Practice: Build samples from OpenCV binary package
|
||||
==================================================
|
||||
|
||||
OpenCV binary package includes two samples having JNI resources:
|
||||
OpenCV binary package includes 3 samples having JNI resources:
|
||||
|
||||
* *Tutorial 2 Advanced - 1. Add Native OpenCV*
|
||||
* *Tutorial 3 (Advanced) - Add Native OpenCV*
|
||||
|
||||
This sample illustrate how you can use OpenCV in C++ but without OpenCV Java API.
|
||||
This sample illustrates how you can use OpenCV in C++ but without OpenCV Java API.
|
||||
|
||||
* *Tutorial 2 Advanced - 2. Mix Java+Native OpenCV*
|
||||
* *Tutorial 4 (Advanced) - Mix Java+Native OpenCV*
|
||||
|
||||
This sample shows how you can mix OpenCV Java API and native C++ code.
|
||||
|
||||
To build these samples you need to:
|
||||
|
||||
#. Fulfill all the steps, described in the tutorial :ref:`Android_Binary_Package`.
|
||||
|
||||
#. Setup one builder for *"Tutorial 2 Advanced - 1. Add Native OpenCV"* project (as described in :ref:`Android_NDK_integration_with_Eclipse`)
|
||||
|
||||
#. Setup second builder for *"Tutorial 2 Advanced - 2. Mix Java+Native OpenCV"* project (repeat the steps from :ref:`Android_NDK_integration_with_Eclipse`)
|
||||
|
||||
#. Clean these projects (in the main Eclipse menu: :menuselection:`Project --> Clean...`)
|
||||
|
||||
#. Run Eclipse build command (if option :guilabel:`Build Automatically` is not set)
|
||||
* *Sample - face-detection*
|
||||
|
||||
This sample illustrates usage of both simple OpenCV face detector via Java API and advanced detection based face tracker via JNI and C++.
|
||||
|
||||
Before OpenCV 2.4.2 for Android these projects are not configured to use CDT for building their native part , so you can do it yourself.
|
||||
|
||||
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 (as example, into the home folder)
|
||||
#. The archive with OpenCV binary package should be downloaded and extracted to some folder (e.g. ``C:\Work\android-opencv\OpenCV-2.4.0``)
|
||||
|
||||
#. We recommend to use an environment variable to specify the location of OpenCV package. Full or relative path hardcoded in :file:`jni/Android.mk` will also work.
|
||||
|
||||
So, the environment variable :envvar:`OPENCV_PACKAGE_DIR` should be defined.
|
||||
The value of the variable should points to the folder, where the OpenCV package has been extracted.
|
||||
|
||||
|
||||
As an example, on *UNIX* you can add add the following line into the hidden file :file:`.bashrc` placed in your home folder:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export OPENCV_PACKAGE_DIR = <path to the extracted OpenCV package>
|
||||
|
||||
Then relogin (or better reboot your computer).
|
||||
|
||||
.. attention:: without rebooting (or logout) this change might not work.
|
||||
|
||||
If you are a *Windows* user, then navigate to:
|
||||
|
||||
* *Windows 7 / Windows Vista*
|
||||
|
||||
:menuselection:`My Computer (Right Click on Icon) --> Properties (Link) --> Advanced System Settings (Link) --> Advanced (Tab) --> Environment Variables (Button) --> System variables (Section)`
|
||||
|
||||
* *Windows XP*
|
||||
|
||||
:menuselection:`My Computer (Right Click on Icon) --> Properties (Link) --> Advanced (Tab) --> Environment Variables (Button) --> System variables (Section)`
|
||||
|
||||
Create new variable :envvar:`OPENCV_PACKAGE_DIR` and similarly to *UNIX* relogin or reboot.
|
||||
|
||||
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 :guilabel:`Environment` tab of the builder configuration window (we have already added some variables to this tab on *Windows* but skipped it for other platforms).
|
||||
#. 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.
|
||||
|
||||
#. The file :file:`jni/Android.mk` should be written for the current application using the common rules for the file.
|
||||
|
||||
@ -324,7 +263,7 @@ To build your own Android application, which uses OpenCV from native part, the f
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
include $(OPENCV_PACKAGE_DIR)/share/OpenCV/OpenCV.mk
|
||||
include C:\Work\android-opencv\OpenCV-2.4.0\share\OpenCV\OpenCV.mk
|
||||
|
||||
should be inserted into the :file:`jni/Android.mk` file right after the line
|
||||
|
||||
@ -332,11 +271,25 @@ To build your own Android application, which uses OpenCV from native part, the f
|
||||
|
||||
include $(CLEAR_VARS)
|
||||
|
||||
.. note:: If your application utilize both native (C++) OpenCV and its Java API you need to put the following line before including :file:`OpenCV.mk` to avoid conflict between C++ and Java builders:
|
||||
Several variables can be used to customize OpenCV stuff, they should be set **before** the ``"include ...\OpenCV.mk"`` line:
|
||||
|
||||
.. code-block:: make
|
||||
.. code-block:: make
|
||||
|
||||
OPENCV_CAMERA_MODULES:=off
|
||||
OPENCV_INSTALL_MODULES:=on
|
||||
|
||||
Copies necessary OpenCV dynamic libs to the project ``libs`` folder in order to include them into the APK.
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
OPENCV_CAMERA_MODULES:=off
|
||||
|
||||
Skip native OpenCV camera related libs copying to the project ``libs`` folder.
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
OPENCV_LIB_TYPE:=STATIC
|
||||
|
||||
Perform static link with OpenCV. By default dynamic link is used and the project JNI lib depends on ``libopencv_java.so``.
|
||||
|
||||
#. The file :file:`Application.mk` should exist and should contain lines
|
||||
|
||||
@ -353,25 +306,4 @@ To build your own Android application, which uses OpenCV from native part, the f
|
||||
|
||||
is recommended for the applications targeting modern ARMs
|
||||
|
||||
#. To build the C++ code the Android NDK script :command:`ndk-build` should be run in the root directory of application.
|
||||
Then the C++ source code using OpenCV will be built by Android NDK build system.
|
||||
After that the Java part of the application can be rebuild and the application can be installed on an Android device.
|
||||
|
||||
Note that this step requires calling the :command:`ndk-build` script from the console. Instead of this step you can use integration of Android NDK into Eclipse
|
||||
as stated above in the section :ref:`Android_NDK_integration_with_Eclipse` .
|
||||
|
||||
|
||||
Additional C++ support in Eclipse
|
||||
==================================
|
||||
|
||||
Note that you can install additional C++ plugins in Eclipse:
|
||||
|
||||
#. Open :guilabel:`Help / Install New Software`. This shows the :guilabel:`Install` dialog.
|
||||
|
||||
#. In the :guilabel:`Work with` drop-down list choose :guilabel:`Helios - http://download.eclipse.org/releases/helios` (or :guilabel:`Indigo - http://download.eclipse.org/releases/indigo` depending on your Eclipse version) and wait while the list of available software is loaded.
|
||||
|
||||
#. From the list of available software select :menuselection:`Programming Languages --> C/C++ Development Tools`.
|
||||
|
||||
#. Click :guilabel:`Next`, click :guilabel:`Next` again, accept the agreement, and click the :guilabel:`Finish` button.
|
||||
|
||||
#. When installation is finished, click :guilabel:`Reload`
|
||||
#. Either use :ref:`manual <NDK_build_cli>` ``ndk-build`` invocation or :ref:`setup Eclipse CDT Builder <Android_NDK_integration_with_Eclipse>` to build native JNI lib before Java part [re]build and APK creation.
|
||||
|
After Width: | Height: | Size: 34 KiB |
After Width: | Height: | Size: 26 KiB |
After Width: | Height: | Size: 33 KiB |
After Width: | Height: | Size: 42 KiB |
After Width: | Height: | Size: 43 KiB |
After Width: | Height: | Size: 40 KiB |
After Width: | Height: | Size: 17 KiB |
After Width: | Height: | Size: 37 KiB |
After Width: | Height: | Size: 72 KiB |
After Width: | Height: | Size: 14 KiB |