Added the tutorial "Using OpenCV Android binary package to compile applications,…

Added the tutorial "Using OpenCV Android binary package to compile applications, which use OpenCV from native level".

doc/tutorials/definitions/tocDefinitions.rst

 .. |Author_AnaH| unicode:: Ana U+0020 Huam U+00E1 n
 .. |Author_BernatG| unicode:: Bern U+00E1 t U+0020 G U+00E1 bor
 .. |Author_AndreyK| unicode:: Andrey U+0020 Kamaev
+.. |Author_LeonidBLB| unicode:: Leonid U+0020 Beynenson
 .. |Author_VictorE| unicode:: Victor U+0020 Eruhimov 
 .. |Author_FernandoI| unicode:: Fernando U+0020 Iglesias U+0020 Garc U+00ED a 
 

doc/tutorials/introduction/android_binary_package/android_binary_package.rst

+
 .. _Android_Binary_Package:
 
+
 Using Android binary package with Eclipse
 *****************************************
 
@@ -16,9 +18,17 @@ You need the following tools to be installed:
 
    Visit http://www.oracle.com/technetwork/java/javase/downloads/index.html and download installer for your OS.
 
-   Here is a detailed JDK installation guide for Ubuntu and Mac OS: http://source.android.com/source/initializing.html (only JDK sections are applicable for OpenCV)
+   Here is a detailed JDK installation guide for Ubuntu and Mac OS: http://source.android.com/source/initializing.html#installing-the-jdk (only JDK sections are applicable for OpenCV)
 
    .. note:: OpenJDK is not usable for Android development because 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:
+
+        .. code-block:: bash
+
+           sudo update-java-alternatives --set java-6-sun
+
+        
+
 
 #. **Android SDK**
 
@@ -222,7 +232,7 @@ 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). 
+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`). 
 
 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.
 
@@ -254,3 +264,19 @@ Well, running samples from Eclipse is very simple:
      :height: 600px 
      :alt: Tutorial 1 Basic - 1. Add OpenCV - running Canny
      :align: center
+
+
+
+How to use OpenCV library project in your application
+=====================================================
+
+If you already have an Android application, you can add a reference to OpenCV and import all its functionality. 
+
+#. First of all you need to have both projects (your app and OpenCV) in a single workspace. 
+   So, open workspace with your application and import the OpenCV project into your workspace as stated above. 
+
+#. Add a reference to OpenCV project.
+
+   Do the right mouse click on your app in Package Explorer, go to **Properties > Android > Library > Add**
+   and choose the OpenCV library project. 
+

doc/tutorials/introduction/android_binary_package/android_binary_package_using_with_NDK.rst

+
+
+.. _Android_Binary_Package_with_NDK:
+
+
+Using OpenCV Android binary package to compile applications, which use OpenCV from native level
+************************************************************************************************
+
+This tutorial describes a simple way to build Android application which uses OpenCV from the native (C++) level. 
+
+This is impotant when you have some 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 (e.g. if the speed is critical for this part of the code).
+
+In this case the only way is to use JNI. 
+It means, that into the Java code of your Android application should be added a Java class with native methods,
+which will be wrappers for your C++ functionality.
+
+This tutorial describes a way how to use OpenCV binary package to compile Android applications, which contains C++ native code using OpenCV.
+
+Note that before using this tutorial you should fulfill all the operations,
+described in the tutorial :ref:`Android_Binary_Package` .
+
+The tutorial was tested using Ubuntu 10.04 operating systems (Windows 7 SP1 coming soon). 
+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.
+
+
+Setup NDK
+==============================================
+
+To compile C++ code for using in Android applications you need Android NDK.
+
+You can get the latest version of Android NDK as an archive 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.
+
+
+Android NDK Documentation
+==============================================
+
+Before start you can read official Android NDK documentation which is in the Android NDK archive, in the folder **docs/**.
+
+The main article about using Android NDK build system you can read in the file **ANDROID-MK.html**. 
+
+Also some additional useful information you can read in the files
+**APPLICATION-MK.html**, **NDK-BUILD.html**, and in the files **CPU-ARM-NEON.html**, **CPLUSPLUS-SUPPORT.html**,  **PREBUILTS.html**. 
+
+Android application source code structure
+==========================================
+
+Usually source code of an Android application has the following structure:
+
++ root folder of the project/
+
+  - jni/
+
+  - res/
+
+  - src/
+
+  - AndroidManifest.xml
+
+  - default.properties
+
+  - ... other files ... 
+
+where
+
++ the folder **src** contains the Java code of the application,
+
++ the folder **res** contains resources of the application (images, xml files describing the application layout, etc),
+
++ and the folder **jni** contains C/C++ application source code and simple scripts **Android.mk** and **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** 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, etc) 
+  --- it can be created using Eclipse wizard, android tool from SDK, or manually 
+
+* the text file **default.properties** contains information about Android target platform and some other details. 
+
+  The file is generated by Eclipse or console ant application. 
+
+
+**Attention**: Both files (AndroidManifest.xml and default.properties) are required to compile the C++ part of the application source code (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. 
+
+
+How to build Android application which have C++ native part (from console)
+===========================================================================
+
+Here is the standard way to compile C++ part of an Android application: 
+
+#. Open console and go to the folder jni of the application project. 
+#. Run the following command
+
+        .. code-block:: bash
+
+                <path_where_NDK_is_placed>/ndk-build
+
+        After executing this command the C++ part of the source code is compiled.
+
+After that the Java part of the application can be recompiled (using either Eclipse, or ant build tool, or scripts calling ant commands, etc), and then the built application can be installed on a device. 
+
+Note that some parameters can be set for the script ndk-build.
+
+**Example 1**: Verbose compilation
+
+.. code-block:: bash
+
+        <path_where_NDK_is_placed>/ndk-build V=1
+
+**Example 2**: Rebuild all
+
+.. code-block:: bash
+
+        <path_where_NDK_is_placed>/ndk-build -B
+
+The tutorials 3 and 4 in OpenCV package may be compiled by this way.
+
+
+.. _Android_NDK_integration_with_Eclipse:
+
+
+How to build Android application which have C++ native part (from Eclipse)
+=============================================================================
+
+There is a simple way to integrate compilation of C++ code by Android NDK into Eclipse compilation process.
+
+To use it follow instructions 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.
+
+Note that in the instructions the folder "lib" is shown on pictures, whereas the name of the folder  is "libs" indeed (if the folder "libs" is absent in your project, compile the Java part of your project or just create it).
+
+Also note that if you have followed this instructions for new project in the workspace, sometimes you will have to change the name of the builder (as example, you can give it name "NDK Builder1" instead of "NDK builder", etc)
+
+The tutorials 3 and 4 in OpenCV package may be compiled by this way.
+
+
+The structure of Android.mk and Application.mk scripts
+======================================================
+
+The script Android.mk usually have the following structure: 
+
+.. code-block:: make
+
+        LOCAL_PATH := $(call my-dir)
+        include $(CLEAR_VARS)
+        LOCAL_MODULE    := <module_name>
+        LOCAL_SRC_FILES := <list of .c and .cpp project files>
+        <some variable name> := <some variable value>
+        ...
+        <some variable name> := <some variable value>
+        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 Android.mk.
+
+Usually the file Application.mk is optional, but sometimes, when STL or exceptions are used in C++, it also should be written. Example of the file Application.mk:
+
+.. code-block:: make
+
+        APP_STL := gnustl_static
+        APP_CPPFLAGS := -frtti -fexceptions
+        APP_ABI := armeabi-v7a
+
+How to build an Android application, which uses OpenCV
+======================================================
+
+To build your own Android application, which uses OpenCV from native part, the following steps should be done:
+
+1. The archive with OpenCV binary package should be downloaded and extracted to some folder (as example, into the home folder)
+
+2. The environment variable 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, you can add add the following line into the hidden file .bashrc placed in your home folder: 
+   
+   .. code-block:: bash
+
+        export OPENCV_PACKAGE_DIR = <path to the extracted OpenCV package>
+        
+   Then reboot your computer. 
+   
+   **Attention**: without rebooting (or logout) this change won't work.
+
+3.  The 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
+    <path_where_NDK_is_placed>/docs/ANDROID-MK.html 
+
+4. The line 
+
+   .. code-block:: make
+
+           include $(OPENCV_PACKAGE_DIR)/share/OpenCV/OpenCV.mk
+
+   should be inserted into the jni/Android.mk file right after the line
+
+   .. code-block:: make
+
+        include $(CLEAR_VARS)
+
+   (check the path to the included file)
+
+5. Also the line 
+
+   .. code-block:: make
+
+        LOCAL_ARM_NEON := true
+
+   is recommended to be added to the jni/Android.mk file, if the application should be run on Android devices with ARM NEON support. 
+
+6. The file Application.mk should exist and should contain lines
+
+   .. code-block:: make
+
+        APP_STL := gnustl_static 
+        APP_CPPFLAGS := -frtti -fexceptions
+
+   Also the line
+
+   .. code-block:: make
+
+                 APP_ABI := armeabi-v7a 
+
+   is recommended to run the application on modern ARMs 
+   
+7. To build the C++ code the Android NDK script **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 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 Help / Install New Software. This shows the “Install” dialog.
+
+#. In the “Work with” dropdown list choose "Helios - http://download.eclipse.org/releases/helios" and wait while the list of 
+   available software is loaded.
+
+#. From the list of available software select “Programming Languages” / “C/C++ Development Tools 7.0.1”.
+
+#. Click "Next", click "Next" again, accept the agreement, and click the button "Finish"
+
+#. When installation is finished, click "Reload"

doc/tutorials/introduction/table_of_content_introduction/table_of_content_introduction.rst

@@ -121,6 +121,24 @@ Here you can read tutorials about how to set up your computer to work with the O
                            :height: 90pt
                            :width:  90pt
 
+  .. tabularcolumns:: m{100pt} m{300pt}
+  .. cssclass:: toctableopencv
+    
+  ================ ======================================================
+  |AndroidNDKPack| **Title:** :ref:`Android_Binary_Package_with_NDK`
+
+                   *Compatibility:* > OpenCV 2.3.1
+
+                   *Author:* |Author_LeonidBLB|
+
+                   You will learn how to work with C++ OpenCV code for Android platform
+
+  ================ ======================================================
+
+     .. |AndroidNDKPack| image:: images/android_logo.png
+                           :height: 90pt
+                           :width:  90pt
+
 * **From where to start?**
 
   .. tabularcolumns:: m{100pt} m{300pt}
@@ -173,5 +191,6 @@ Here you can read tutorials about how to set up your computer to work with the O
    ../windows_install/windows_install
    ../windows_visual_studio_Opencv/windows_visual_studio_Opencv
    ../android_binary_package/android_binary_package
+   ../android_binary_package/android_binary_package_using_with_NDK
    ../display_image/display_image
    ../load_save_image/load_save_image