From e9e46d3086025542ee69e84f37310e7a71cd2cdb Mon Sep 17 00:00:00 2001 From: Vsevolod Glumov Date: Thu, 20 Dec 2012 18:05:56 +0400 Subject: [PATCH] Updated Android introductory tutorials, based on frequent Q&A questions/issues. --- .../android_binary_package/O4A_SDK.rst | 56 ++++++++++++++++--- .../android_dev_intro.rst | 25 +++++++-- 2 files changed, 66 insertions(+), 15 deletions(-) diff --git a/doc/tutorials/introduction/android_binary_package/O4A_SDK.rst b/doc/tutorials/introduction/android_binary_package/O4A_SDK.rst index b426c5c1ec..66b7842c9c 100644 --- a/doc/tutorials/introduction/android_binary_package/O4A_SDK.rst +++ b/doc/tutorials/introduction/android_binary_package/O4A_SDK.rst @@ -159,7 +159,7 @@ Get the OpenCV4Android SDK unzip ~/Downloads/OpenCV-2.4.3-android-sdk.zip -.. |opencv_android_bin_pack| replace:: OpenCV-2.4.3-android-sdk.zip +.. |opencv_android_bin_pack| replace:: OpenCV-2.4.3.1-android-sdk.zip .. _opencv_android_bin_pack_url: http://sourceforge.net/projects/opencvlibrary/files/opencv-android/2.4.3/OpenCV-2.4.3-android-sdk.zip/download .. |opencv_android_bin_pack_url| replace:: |opencv_android_bin_pack| .. |seven_zip| replace:: 7-Zip @@ -186,6 +186,8 @@ Import OpenCV library and samples to the Eclipse Each sample included into the |opencv_android_bin_pack| is a regular Android project that already references OpenCV library.Follow the steps below to import OpenCV and samples into the workspace: + .. note:: OpenCV samples are indeed **dependent** on OpenCV library and wouldn't work without it. + * Right click on the :guilabel:`Package Explorer` window and choose :guilabel:`Import...` option from the context menu: @@ -213,7 +215,7 @@ Import OpenCV library and samples to the Eclipse and you have to wait some time while it is building OpenCV samples. Just give a minute to Eclipse to complete initialization. - .. note :: After the initial import, on a non-Windows (Linux and Mac OS) operating system Eclipse + .. warning :: After the initial import, on a non-Windows (Linux and Mac OS) operating system Eclipse will still show build errors for applications with native C++ code. To resolve the issues, please do the following: @@ -235,14 +237,14 @@ Import OpenCV library and samples to the 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`, ``Tutorial 4`` and ``Tutorial 5`` 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. -Other samples use OpenCV Native Camera which may not work with emulator. +.. warning:: Please consider that ``Tutorial 1`` samples use Java Camera API, which is accessible + with an AVD. Other samples use OpenCV Native Camera which **may not work** with + an emulator. .. note:: Recent *Android SDK tools, revision 19+* can run ARM v7a OS images but they available not for all Android versions. @@ -282,6 +284,41 @@ Well, running samples from Eclipse is very simple: If you have no access to the *Market*, which is often the case with emulators - you will need to install the packages from OpenCV4Android SDK folder manually. See :ref:`manager_selection` for details. + .. code-block:: sh + :linenos: + + /platform-tools/adb install /apk/OpenCV_2.4.3_Manager_armv7a-neon.apk + /platform-tools/adb install /apk/OpenCV_2.4.3_binary_pack_armv7a.apk + + .. note:: ``armeabi``, ``armv7a-neon``, ``arm7a-neon-android8``, ``mips`` and ``x86`` stand for + platform targets: + + * ``armeabi`` is for ARM v5 and ARM v6 architectures, + + * ``armv7a-neon`` is for NEON-optimized ARM v7, + + * ``arm7a-neon-android8`` is for NEON-optimized ARM v7 with Android API 8, + + * ``mips`` is for MIPS architecture, + + * ``x86`` is for Intel x86 CPUs. + + If using hardware device for testing/debugging, run the following command to learn + its CPU architecture: + + .. code-block:: sh + + adb shell getprop ro.product.cpu.abi + + If you're using an AVD emulator, go :menuselection:`Window > AVD Manager` to see the + list of availible devices. Click :menuselection:`Edit` in the context menu of the + selected device. In the window, which then pop-ups, find the CPU field. + + You may also see section :ref:`manager_selection` for details. + + + When done, you will be able to run OpenCV samples on your device/emulator seamlessly. + * Here is ``Tutorial 2 - Use OpenCV Camera`` sample, running on top of stock camera-preview of the emulator. .. image:: images/emulator_canny.png @@ -289,6 +326,7 @@ Well, running samples from Eclipse is very simple: :alt: Tutorial 1 Basic - 1. Add OpenCV - running Canny :align: center + What's next =========== diff --git a/doc/tutorials/introduction/android_binary_package/android_dev_intro.rst b/doc/tutorials/introduction/android_binary_package/android_dev_intro.rst index 8855c5bd90..db02fca857 100644 --- a/doc/tutorials/introduction/android_binary_package/android_dev_intro.rst +++ b/doc/tutorials/introduction/android_binary_package/android_dev_intro.rst @@ -78,7 +78,7 @@ Development in Java You need the following software to be installed in order to develop for Android in Java: -#. **Sun JDK 6** +#. **Sun JDK 7** Visit `Java SE Downloads page `_ and download an installer for your OS. @@ -93,7 +93,7 @@ You need the following software to be installed in order to develop for Android .. code-block:: bash - sudo update-java-alternatives --set java-6-sun + sudo update-java-alternatives --set java-7-sun .. TODO: Add a note on Sun/Oracle Java installation on Ubuntu 12. @@ -348,6 +348,11 @@ Building application native part from command line Here is the standard way to compile C++ part of an Android application: +.. warning:: We strongly reccomend using ``cmd.exe`` (standard windows console) instead of Cygwin on + Windows. Use the latter if only you're absolutely sure about, what you're doing. Cygwin + is not really supported and we are unlikely to help you in case you encounter some + problems with it. So, use it only if you're capable of handling the consequences yourself. + #. Open console and go to the root folder of an Android application .. code-block:: bash @@ -361,7 +366,7 @@ Here is the standard way to compile C++ part of an Android application: /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. + rather than the similar ``bash`` script in ``Cygwin`` shell. .. image:: images/ndk_build.png :alt: NDK build @@ -401,7 +406,15 @@ Eclipse build process. We recommend the approach based on Eclipse (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. + :guilabel:`My Computer -> Properties -> Advanced -> Environment variables` or in Eclipse itself + :guilabel:`Window -> Preferences -> C/C++ -> Build -> Env`. Restart Eclipse after setting the + variables. + + .. note:: If you're using Eclipse 3 and lower, keep in mind, that it doesn't change variables on + restart as Eclipse 4 does. You may need to clean :file:`org.eclipse.cdt.core.prefs`, + which is located in the following path inside Eclipse workspace: + ``\.metadata\.plugins\org.eclipse.core.runtime\.settings\``. + On Windows 7 it's also possible to use `setx `_ command in a console session. **On Linux** and **MacOS** an environment variable can be set via appending a @@ -666,8 +679,8 @@ execute :command:`adb devices` command. You will see the list of attached device :alt: List of attached devices :align: center -MacOS host computer -^^^^^^^^^^^^^^^^^^^ +Mac OS host computer +^^^^^^^^^^^^^^^^^^^^ No actions are required, just connect your device via USB and run ``adb devices`` to check connection. What's next