improving android tutorial v2

doc/tutorials/introduction/android_binary_package/O4A_SDK.rst

@@ -7,7 +7,7 @@ OpenCV4Android SDK
 
 This tutorial was designed to help you with installation and configuration of OpenCV4Android SDK.
 
-This guide was written with Windows 7 in mind, though it should work with any other OS supported by 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 tutorial assumes you have the following installed and configured:
 
@@ -27,15 +27,66 @@ If you encounter any error after thoroughly following these steps, feel free to
 
 General info
 ============
-**TODO:** rewrite this section.
 
-OpenCV4Android SDK uses Android OpenCV Manager for library initialization. OpenCV Manager provides the following benefits:
+OpenCV4Android SDK package contains the stuff that enables development Android applications with use of OpenCV library.
+
+The package content look like the following:
+
+::
+
+    OpenCV-2.4.2-android-sdk
+    |_ apk
+    |   |_ OpenCV_2.4.2_binary_pack_XXX.apk 
+    |   |_ OpenCV_2.4.2_Manager.apk 
+    |
+    |_ doc
+    |_ samples
+    |_ sdk
+    |    |_ etc 
+    |    |_ java 
+    |    |_ native 
+    |          |_ 3rdparty 
+    |          |_ jni 
+    |          |_ libs 
+    |               |_ armeabi 
+    |               |_ armeabi-v7a 
+    |               |_ x86 
+    |
+    |_ license.txt
+    |_ README.android
+
+* :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/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).
+   
+  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).
+  
+  **Note**: installation from internet is the preferable way since we 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.
+
+* :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/.
+  Generally it's more up-to-date, but can refer not-yet-released functionality.
+
+Starting version 2.4.2 `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;
 
-* Regular updates and bug fixes;
+* Automatic updates and bug fixes;
 
 * Trusted OpenCV library source. All packages with OpenCV are published on Google Play;
 
@@ -44,27 +95,14 @@ OpenCV4Android SDK uses Android OpenCV Manager for library initialization. OpenC
 
 For additional information on OpenCV Manager see the:
  
-* |OpenCV4Android_Tutorial|_ 
+* |OpenCV4Android_Slides|_ 
   
 * |OpenCV4Android_Reference|_ 
 
      ..
 
-
+.. |OpenCV4Android_Slides| replace:: Slides
-This package is quite close to the current OpenCV4Android distribution. If you're beginner with OpenCV, tutorial from above will help you to start.
+.. _OpenCV4Android_Slides: https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p
-
-* Library Project for Java development with Eclipse. 
-
-* C++ headers and libraries for native application development.
-
-* Java samples, javadoc documentation.
-
-* prebuilt binaries for ARM-v7a platform.
-
-     ..
-
-.. |OpenCV4Android_Tutorial| replace:: Tutorial
-.. _OpenCV4Android_Tutorial: http://docs.opencv.org/doc/tutorials/introduction/android_binary_package/android_binary_package.html#android-binary-package
 .. |OpenCV4Android_Reference| replace:: Reference Manual
 .. _OpenCV4Android_Reference: http://docs.opencv.org/android/refman.html
 
@@ -255,4 +293,4 @@ Well, running samples from Eclipse is very simple:
 What's next
 ===========
 
-Now, when you have your instance of OpenCV4Adroid SDK set up and configured, you may want to proceed to using OpenCV in your own application. You can learn how to do that in a separate *Development with OpenCV* tutorial.
+Now, when you have your instance of OpenCV4Adroid SDK set up and configured, you may want to proceed to using OpenCV in your own application. You can learn how to do that in a separate :ref:`dev_with_OCV_on_Android` tutorial.

doc/tutorials/introduction/android_binary_package/android_dev_intro.rst

@@ -13,15 +13,15 @@ If you encounter any error after thoroughly following these steps, feel free to
 
 Preface
 =======
-Android is a linux-based, open source mobile operating system developed by Open Handset Alliance and backed by Google. See the `official 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 `official site <http://www.android.com/about/>`_ for general details.
 
-Though being relatively easy to enter, Android development would require fair understanding of programming and its common concepts. Even basic familiarity with Java or C++ is advantageous.
+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:
 
-For the quick start with Android development, you should get yourself accustomed with some fundamental Android aspects:
+#. `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.
-#. Activity and its lifecycle. Information on this essential Android class is available on the `official site for Android developers <http://developer.android.com/training/basics/activity-lifecycle/starting.html>`_ (see first two sections) or on the corresponding page of the `reference <http://developer.android.com/training/basics/activity-lifecycle/starting.html>`_.
+#. `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>`_ essentials.
+#. OpenCV development will certainly require some knowlege of the `Android Camera <http://developer.android.com/guide/topics/media/camera.html>`_ specifics.
-#. Some basic understanding of `Java Native Interface <http://en.wikipedia.org/wiki/Java_Native_Interface>`_ will help you to apprehend the concept of using native code in Java.
 
 Quick environment setup for Android development
 ===============================================
@@ -284,58 +284,91 @@ AVD (*Android Virtual Device*) is not probably the most convenient way to test a
 
 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 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 <http://developer.android.com/tools/device.html>`_ for more information.
+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 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 <http://developer.android.com/tools/device.html>`_ for more information.
 
 Windows host computer
 ^^^^^^^^^^^^^^^^^^^^^
 
-#. Enable USB debugging on the Android device (settings menu).
+#. 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 permittions.
 #. 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 appearing in the list.
     .. image:: images/usb_device_connect_01.png
      :alt: Unknown device
      :align: center
-#. Right-click on the unknoen device, select :guilabel:`Properties` then select the :guilabel:`Details` tab. Select :guilabel:`Hardware Ids` and copy the line like ``USB\VID_XXXX&PID_XXXX&MI_XX``.
+#. 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
+     :align: center
+#. Select :guilabel:`Browse computer for driver software`.
+    .. image:: images/usb_device_connect_06.png
+     :alt: Browse for driver
+     :align: center
+#. Specify the path to :file:`<Android SDK folder>/extras/google/usb_driver/` folder.
+    .. image:: images/usb_device_connect_07.png
+     :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.
+    .. image:: images/usb_device_connect_08.png
+     :alt: Install prompt
+     :align: center
+
+    ` `
+
+    .. image:: images/usb_device_connect_09.png
+     :alt: Installed OK
+     :align: center
+#. Otherwise (getting the failure like shown below) follow the next steps.
+    .. image:: images/usb_device_connect_12.png
+     :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``.
     .. 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.
     .. image:: images/usb_device_connect_03.png
-     :alt: Device properties details
+     :alt: "android_winusb.inf"
      :align: center
 #. There should be a record like existing ones for your device and you need to add one manually.
     .. image:: images/usb_device_connect_04.png
-     :alt: Device properties details
+     :alt: "android_winusb.inf"
      :align: center
-#. TBD.
+#. Save the :file:`android_winusb.inf` file and try to install the USB driver again.
     .. image:: images/usb_device_connect_05.png
-     :alt: Device properties details
+     :alt: Device properties
      :align: center
-#. TBD.
+
+    ` `
+
     .. image:: images/usb_device_connect_06.png
-     :alt: Device properties details
+     :alt: Browse for driver
      :align: center
-#. TBD.
+
+    ` `
+
     .. image:: images/usb_device_connect_07.png
-     :alt: Device properties details
+     :alt: Browse for driver
      :align: center
-#. TBD.
+#. This time installation should go successfully.
     .. image:: images/usb_device_connect_08.png
-     :alt: Device properties details
+     :alt: Install prompt
      :align: center
-#. TBD.
+
+    ` `
+
     .. image:: images/usb_device_connect_09.png
-     :alt: Device properties details
+     :alt: Installed OK
      :align: center
-#. TBD.
+#. And "unknown" device becomes "known" one.
     .. image:: images/usb_device_connect_10.png
-     :alt: Device properties details
+     :alt: "Known" device
      :align: center
-#. TBD.
+#. Successful device USB connection can be verified in console via ``adb devices`` command.
     .. image:: images/usb_device_connect_11.png
-     :alt: Device properties details
+     :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.