mirror/opencv
1
0
Fork 0
mirror of https://github.com/opencv/opencv.git synced 2024-12-03 16:35:09 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

android tutorial v2, initial draft commit

Browse Source
This commit is contained in:
Andrey Pavlenko 2012-08-07 17:27:48 +04:00 committed by Andrey Kamaev
parent 639bbec44a
commit 9e171c9e26
12 changed files with 1127 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/tutorials/definitions/tocDefinitions.rst
View File

@ -2,6 +2,7 @@
.. |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_VsevolodG| unicode:: Vsevolod U+0020 Glumov
.. |Author_VictorE| unicode:: Victor U+0020 Eruhimov
.. |Author_ArtemM| unicode:: Artem U+0020 Myagkov
.. |Author_FernandoI| unicode:: Fernando U+0020 Iglesias U+0020 Garc U+00ED a

258
doc/tutorials/introduction/android_binary_package/O4A_SDK.rst Normal file
View File

@ -0,0 +1,258 @@
.. _O4A_SDK:
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 tutorial assumes you have the following installed and configured:
* JDK
* Android SDK and NDK
* Eclipse IDE
* ADT and CDT plugins for Eclipse
..
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.
General info
============
**TODO:** rewrite this section.
OpenCV4Android SDK uses Android OpenCV Manager for library initialization. OpenCV Manager provides the following benefits:
* 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;
* Trusted OpenCV library source. All packages with OpenCV are published on Google Play;
..
For additional information on OpenCV Manager see the:
* |OpenCV4Android_Tutorial|_
* |OpenCV4Android_Reference|_
..
This package is quite close to the current OpenCV4Android distribution. If you're beginner with OpenCV, tutorial from above will help you to start.
* 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
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 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|_
#. Create a new folder for development for Android with OpenCV development. For this tutorial I have unpacked OpenCV 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.
You can unpack it using any popular archiver (e.g with |seven_zip|_):
.. image:: images/android_package_7zip.png
:alt: Exploring OpenCV package with 7-Zip
:align: center
On Unix you can use the following command:
.. code-block:: bash
unzip ~/Downloads/OpenCV-2.4.2-android-sdk.zip
.. |opencv_android_bin_pack| replace:: OpenCV-2.4.2-android-sdk.zip
.. _opencv_android_bin_pack_url: http://sourceforge.net/projects/opencvlibrary/files/opencv-android/2.4.2/OpenCV-2.4.2-android-sdk.zip/download
.. |opencv_android_bin_pack_url| replace:: |opencv_android_bin_pack|
.. |seven_zip| replace:: 7-Zip
.. _seven_zip: http://www.7-zip.org/
Open OpenCV library and samples in Eclipse
------------------------------------------
#. 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:
.. image:: images/eclipse_1_choose_workspace.png
:alt: Choosing C:\Work\android-opencv\ as workspace location
:align: center
#. 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.
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:
* Right click on the :guilabel:`Package Explorer` window and choose :guilabel:`Import...` option from the context menu:
.. image:: images/eclipse_5_import_command.png
:alt: Select Import... from context menu
:align: center
* In the main panel select :menuselection:`General --> Existing Projects into Workspace` and press :guilabel:`Next` button:
.. image:: images/eclipse_6_import_existing_projects.png
:alt: General > Existing Projects into Workspace
:align: center
* In the :guilabel:`Select root directory` field locate your OpenCV package folder. Eclipse should automatically locate OpenCV library and samples:
.. image:: images/eclipse_7_select_projects.png
:alt: Locate OpenCV library and samples
:align: center
* Click :guilabel:`Finish` button to complete the import operation.
After clicking :guilabel:`Finish` button Eclipse will load all selected projects into workspace. Numerous errors will be indicated:
.. image:: images/eclipse_8_false_alarm.png
:alt: Confusing Eclipse screen with numerous errors
:align: center
However, **all these errors are only false-alarms**!
Just give a minute to Eclipse to complete initialization.
In some cases these errors disappear after :menuselection:`Project --> Clean... --> Clean all --> OK`
or after pressing :kbd:`F5` (for Refresh action) when selecting error-label-marked projects in :guilabel:`Package Explorer`.
Sometimes more advanced manipulations are required:
* The provided projects are configured for ``API 11`` target (and ``API 9`` for the library) that can be missing platform in your Android SDK.
After right click on any project select :guilabel:`Properties` and then :guilabel:`Android` on the left pane.
Click some target with `API Level` 11 or higher:
.. image:: images/eclipse_8a_target.png
:alt: Updating target
:align: center
Eclipse will rebuild your workspace and error icons will disappear one by one:
.. image:: images/eclipse_9_errors_dissapearing.png
:alt: After small help Eclipse removes error icons!
:align: center
Once Eclipse completes build you will have the clean workspace without any build errors:
.. image:: images/eclipse_10_crystal_clean.png
:alt: OpenCV package imported into Eclipse
:align: center
.. _Running_OpenCV_Samples:
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`` ones 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.
.. 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:
* Connect your device with :command:`adb` tool from Android SDK or create an emulator with camera support.
* See `Managing Virtual Devices
<http://developer.android.com/guide/developing/devices/index.html>`_ document for help with Android Emulator.
* See `Using Hardware Devices
<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.
.. note:: Android Emulator can take several minutes to start. So, please, be patient.
* On the first run Eclipse will ask you about the running mode for your application:
.. image:: images/eclipse_11_run_as.png
:alt: Run sample as Android Application
:align: center
* Select the :guilabel:`Android Application` option and click :guilabel:`OK` button. Eclipse will install and run the sample.
Chances are that on the first launch you will not have the `OpenCV Manager <https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p>`_ package installed.
In this case you will see the following message:
.. image:: images/android_emulator_opencv_manager_fail.png
:alt: You will see this message if you have no OpenCV Manager installed
:align: center
To get rid of the message you will need to install `OpenCV Manager` and the appropriate `OpenCV binary pack`.
Simply tap :menuselection:`Yes` if you have *Google Play Market* installed on your device/emulator. It will redirect you to the corresponding page on *Google Play Market*.
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. Open the console/terminal and type in the following two commands:
.. code-block:: sh
:linenos:
<Android SDK path>/platform-tools/adb install <OpenCV4Android SDK path>/apk/OpenCV_2.4.2_Manager.apk
<Android SDK path>/platform-tools/adb install <OpenCV4Android SDK path>/apk/OpenCV_2.4.2_binary_pack_armv7a.apk
If you're running Windows, that will probably look like this:
.. image:: images/install_opencv_manager_with_adb.png
:alt: Run these commands in the console to install OpenCV Manager
:align: center
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
:height: 600px
:alt: Tutorial 1 Basic - 1. Add OpenCV - running Canny
:align: center
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.

2
doc/tutorials/introduction/android_binary_package/android_binary_package_using_with_NDK.rst
View File

@ -4,7 +4,7 @@
Using OpenCV in C++ code with OpenCV4Android SDK
*********************************************
************************************************
The Android way is writing all your code in Java. But sometimes, it is not enough and you need to go to the native level and write some parts of your application in C/C++.
This is especially important when you already have some computer vision code which is written in C++ and uses OpenCV, and you want to reuse it in your Android application.

314
doc/tutorials/introduction/android_binary_package/android_dev_intro.rst Normal file
View File

@ -0,0 +1,314 @@
.. _Android_Dev_Intro:
Introduction into Android Development
*************************************
This guide was designed to help you in learning Android development basics and quickly seting up your working environment.
This guide was written with Windows 7 in mind, though it should work with 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.
Android application structure
=============================
Usually source code of an Android application has the following structure:
+ :file:`root folder of the project/`
- :file:`jni/`
- :file:`libs/`
- :file:`res/`
- :file:`src/`
- :file:`AndroidManifest.xml`
- :file:`project.properties`
- :file:`... other files ...`
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:`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.
* :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.
.. note:: Both files (:file:`AndroidManifest.xml` and :file:`project.properties`) are required to compile the C++ part of the application,
since 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
==================================================================
The script :file:`Android.mk` usually has 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 :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`:
.. code-block:: make
APP_STL := gnustl_static
APP_CPPFLAGS := -frtti -fexceptions
APP_ABI := armeabi-v7a
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/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.
* 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 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.
..
.. |Nvidia_Tegra_Platform| replace:: *NVIDIA*\ ’s Tegra platform
.. _Nvidia_Tegra_Platform: http://developer.nvidia.com/node/19071
.. |Tegra_Development_Kit| replace:: Tegra Development Kit
.. _Tegra_Development_Kit: http://developer.nvidia.com/tegra-ventana-development-kit
.. _Android_Environment_Setup_Lite:
Manual environment setup for Android Development
================================================
Development in Java
-------------------
You need the following software to be installed in order to develop for Android in Java:
#. **Sun JDK 6**
Visit `Java SE Downloads page <http://www.oracle.com/technetwork/java/javase/downloads/>`_ and download an installer for your OS.
Here is a detailed :abbr:`JDK (Java Development Kit)` `installation guide <http://source.android.com/source/initializing.html#installing-the-jdk>`_
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:
.. code-block:: bash
sudo update-java-alternatives --set java-6-sun
**TODO:** add a note on Sun/Oracle Java installation on Ubuntu 12.
#. **Android SDK**
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 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 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
sudo apt-get install ia32-libs
For Red Hat based systems the following command might be helpful:
.. code-block:: bash
sudo yum install libXtst.i386
#. **Android SDK components**
You need the following SDK components to be installed:
* *Android SDK Tools, revision14* or newer.
Older revisions should also work, but they are not recommended.
* *SDK Platform Android 3.0*, ``API 11`` and *Android 2.3.1*, ``API 9``.
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.
.. image:: images/android_sdk_and_avd_manager.png
:height: 500px
:alt: Android SDK Manager
:align: center
See `Adding SDK Components <http://developer.android.com/sdk/adding-components.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.
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/eclipse-adt.html#downloading>`_, 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:
#. 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:
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).
#. 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`.
#. 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`.
#. When the installation completes, restart Eclipse.
Native development in C++
-------------------------
You need the following software to be installed in order to develop for Android in C++:
#. **Android 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 `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 are `installation instructions <http://developer.android.com/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/`.
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`.
#. **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.
.. 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.
.. image:: images/eclipse_inst_details.png
:alt: Configure builders
: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`.
.. image:: images/eclipse_inst_cdt.png
:alt: Configure builders
:align: center
``CDT Main Features`` should be enough:
.. image:: images/eclipse_inst_cdt_2.png
:alt: Configure builders
:align: center
That's it. Compilation of C++ code is fully integrated into Eclipse building process now.
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.
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.
#. 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...
#. 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.
.. 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 (aka 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.
#. 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.
#. Right-click on your device to get to :guilabel:`Properties` and select the :guilabel:`Details` tab. Select :guilabel:`Device ID` and save both numbers (*e.g in a text file*).
.. image:: images/device_details.png
:alt: Details
:align: center
#. Now open file :file:`<Android SDK folder>/extras/google/usb_driver/android_winusb.inf`. You will see some default records there, perhaps looking similar to this:
.. code-block:: ini
;Google Nexus One
%SingleAdbInterface% = USB_Install, USB\VID_18D1&PID_0D02
%CompositeAdbInterface% = USB_Install, USB\VID_18D1&PID_0D02&MI_01
#. There should be a record like this for your device and since it hasn't appeared automatically you are free to add one manually. All you should do is to add another record similar to the above, but using the numbers you saved earlier. Second number goes to the first line and the first one goes to the second line. Notice, that the record should be inserted under *[Google.NTx86]* or *[Google.NTamd64]* tag, depending on what system you're currently running. For example, in my case it was Nvidia Tegra device and the record looked like this:
.. code-block:: ini
;NVIDIA Tegra
%SingleAdbInterface% = USB_Install, USB\VID_0955&PID_7100&MI_01
%CompositeAdbInterface% = USB_Install, USB\VID_0955&PID_7100&REV_9999&MI_01
#. Assuming you have your SDK installed to :file:`C:/android-sdk/`, you may try the following command in Windows console to acertain that your device was recognised and attached:
.. code-block:: ini
C:\android-sdk\platform-tools\adb devices
.. image:: images/cmd_adb_devices.png
:alt: Console
: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.
Consult the official `Android Developers site <http://developer.android.com/tools/device.html>`_ for more information on configuring hardware devices to work with other operating systems.
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.

471
doc/tutorials/introduction/android_binary_package/dev_with_OCV_on_Android.rst Normal file
View File

@ -0,0 +1,471 @@
.. _dev_with_OCV_on_Android:
Android development with OpenCV
*******************************
This tutorial is created to help you use OpenCV library within your Android project.
This guide was written with Windows 7 in mind, though it should work with any other OS supported by OpenCV4Android SDK.
This tutorial assumes you have the following installed and configured:
* JDK
* Android SDK and NDK
* Eclipse IDE
* ADT and CDT plugins for Eclipse
..
If you need help with anything of the above, you may refer to our :ref:`android_dev_intro` guide.
This tutorial also assumes you have OpenCV4Android SDK already installed on your development machine and OpenCV Manager on your testing device correspondingly. If you need help with any of these, you may consult our :ref:`O4A_SDK` tutorial.
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.
Using OpenCV library within your Android project
================================================
In this section we will explain how to make some existing project to use OpenCV.
Starting with 2.4.2 release for Android, *OpenCV Manager* is used to provide apps with the best available version of OpenCV.
You can get more information here: :ref:`Android_OpenCV_Manager` and in these `slides <https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p>`_.
Java
----
Application development with async initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Using async initialization is a **recommended** way for application development. It uses the OpenCV Manager to access OpenCV libraries externally installed in the target system.
#. Add OpenCV library project to your workspace. Use menu :guilabel:`File -> Import -> Existing project in your workspace`,
press :guilabel:`Browse` button and locate OpenCV4Android SDK (:file:`OpenCV-2.4.2-android-sdk/sdk`).
.. image:: images/eclipse_opencv_dependency0.png
:alt: Add dependency from OpenCV library
:align: center
#. In application project add a reference to the OpenCV Java SDK in :guilabel:`Project -> Properties -> Android -> Library -> Add` select ``OpenCV Library - 2.4.2``.
.. image:: images/eclipse_opencv_dependency1.png
:alt: Add dependency from OpenCV library
:align: center
To run OpenCV Manager-based application the first time you need to install packages with the `OpenCV Manager` and `OpenCV binary pack` for you platform.
You can do it using Google Play Market or manually with ``adb`` tool:
.. code-block:: sh
:linenos:
<Android SDK path>/platform-tools/adb install <OpenCV4Android SDK path>/apk/OpenCV_2.4.2_Manager.apk
<Android SDK path>/platform-tools/adb install <OpenCV4Android SDK path>/apk/OpenCV_2.4.2_binary_pack_armv7a.apk
There is a very base code snippet implementing the async initialization. It shows basic principles. See the "15-puzzle" OpenCV sample for details.
.. code-block:: java
:linenos:
public class MyActivity extends Activity implements HelperCallbackInterface
{
private BaseLoaderCallback mOpenCVCallBack = new BaseLoaderCallback(this) {
@Override
public void onManagerConnected(int status) {
switch (status) {
case LoaderCallbackInterface.SUCCESS:
{
Log.i(TAG, "OpenCV loaded successfully");
// Create and set View
mView = new puzzle15View(mAppContext);
setContentView(mView);
} break;
default:
{
super.onManagerConnected(status);
} break;
}
}
};
/** Called when the activity is first created. */
@Override
public void onCreate(Bundle savedInstanceState)
{
Log.i(TAG, "onCreate");
super.onCreate(savedInstanceState);
Log.i(TAG, "Trying to load OpenCV library");
if (!OpenCVLoader.initAsync(OpenCVLoader.OPENCV_VERSION_2_4_2, this, mOpenCVCallBack))
{
Log.e(TAG, "Cannot connect to OpenCV Manager");
}
}
// ...
}
It this case application works with OpenCV Manager in asynchronous fashion. ``OnManagerConnected`` callback will be called in UI thread, when initialization finishes.
Please note, that it is not allowed to use OpenCV calls or load OpenCV-dependent native libs before invoking this callback.
Load your own native libraries that depend on OpenCV after the successful OpenCV initialization.
Application development with static initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
According to this approach all OpenCV binaries are included into your application package. It is designed mostly for development purposes.
This approach is deprecated for the production code, release package is recommended to communicate with OpenCV Manager via the async initialization described above.
#. Add the OpenCV library project to your workspace the same way as for the async initialization above.
Use menu :guilabel:`File -> Import -> Existing project in your workspace`, push :guilabel:`Browse` button and select OpenCV SDK path (:file:`OpenCV-2.4.2-android-sdk/sdk`).
.. image:: images/eclipse_opencv_dependency0.png
:alt: Add dependency from OpenCV library
:align: center
#. In the application project add a reference to the OpenCV4Android SDK in :guilabel:`Project -> Properties -> Android -> Library -> Add` select ``OpenCV Library - 2.4.2``;
.. image:: images/eclipse_opencv_dependency1.png
:alt: Add dependency from OpenCV library
:align: center
#. If your application project **doesn't have a JNI part**, just copy the corresponding OpenCV native libs from :file:`<OpenCV-2.4.2-android-sdk>/sdk/native/libs/<target_arch>` to your project directory to folder :file:`libs/<target_arch>`.
In case of the application project **with a JNI part**, instead of manual libraries copying you need to modify your ``Android.mk`` file:
add the following two code lines after the ``"include $(CLEAR_VARS)"`` and before ``"include path_to_OpenCV-2.4.2-android-sdk/sdk/native/jni/OpenCV.mk"``
.. code-block:: make
:linenos:
OPENCV_CAMERA_MODULES:=on
OPENCV_INSTALL_MODULES:=on
The result should look like the following:
.. code-block:: make
:linenos:
include $(CLEAR_VARS)
# OpenCV
OPENCV_CAMERA_MODULES:=on
OPENCV_INSTALL_MODULES:=on
include ../../sdk/native/jni/OpenCV.mk
After that the OpenCV libraries will be copied to your application :file:`libs` folder during the JNI part build.
Eclipse will automatically include all the libraries from the :file:`libs` folder to the application package (APK).
#. The last step of enabling OpenCV in your application is Java initialization code before call to OpenCV API.
It can be done, for example, in the static section of the ``Activity`` class:
.. code-block:: java
:linenos:
static {
if (!OpenCVLoader.initDebug()) {
// Handle initialization error
}
}
If you application includes other OpenCV-dependent native libraries you should load them **after** OpenCV initialization:
.. code-block:: java
:linenos:
static {
if (!OpenCVLoader.initDebug()) {
// Handle initialization error
} else {
System.loadLibrary("my_jni_lib1");
System.loadLibrary("my_jni_lib2");
}
}
Native/C++
----------
To build your own Android application, which uses OpenCV from native part, the following steps should be done:
#. You can use an environment variable to specify the location of OpenCV package or just hardcode absolute 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 this file.
For detailed information see the Android NDK documentation from the Android NDK archive, in the file
:file:`<path_where_NDK_is_placed>/docs/ANDROID-MK.html`
#. The line
.. code-block:: make
include C:\Work\OpenCV4Android\OpenCV-2.4.2-android-sdk\sdk\native\jni\OpenCV.mk
should be inserted into the :file:`jni/Android.mk` file **after** the line
.. code-block:: make
include $(CLEAR_VARS)
#. Several variables can be used to customize OpenCV stuff, but you **don't need** to use them when your application uses the `async initialization` via the `OpenCV Manager` API.
Note: these variables should be set **before** the ``"include .../OpenCV.mk"`` line:
.. code-block:: make
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:
.. code-block:: make
APP_STL := gnustl_static
APP_CPPFLAGS := -frtti -fexceptions
Also the line like this one:
.. code-block:: make
APP_ABI := armeabi-v7a
should specify the application target platforms.
In some cases a linkage error (like ``"In function 'cv::toUtf16(std::basic_string<...>... undefined reference to 'mbstowcs'"``) happens
when building an application JNI library depending on OpenCV.
The following line in the :file:`Application.mk` usually fixes it:
.. code-block:: make
APP_PLATFORM := android-9
#. 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.
**TBD:** move this info from tutorial v1 to part 1 of tutorial v2.
Hello OpenCV Sample
===================
Here are basic steps to guide you trough the process of creating a simple OpenCV-centric application.
It will be capable of accessing camera output, processing it and displaying the result.
#. Open Eclipse IDE, create a new clean workspace, create a new Android project (*File -> New -> Android Project*).
#. Set name, target, package and minSDKVersion accordingly.
#. Create a new class (*File -> New -> Class*). Name it for example: *HelloOpenCVView*.
.. image:: images/dev_OCV_new_class.png
:alt: Add a new class.
:align: center
* It should extend *SurfaceView* class.
* It also should implement *SurfaceHolder.Callback*, *Runnable*.
#. Edit *HelloOpenCVView* class.
* Add an *import* line for *android.content.context*.
* Modify autogenerated stubs: *HelloOpenCVView*, *surfaceCreated*, *surfaceDestroyed* and *surfaceChanged*.
.. code-block:: java
package com.hello.opencv.test;
import android.content.Context;
public class HelloOpenCVView extends SurfaceView implements Callback, Runnable {
public HelloOpenCVView(Context context) {
super(context);
getHolder().addCallback(this);
}
public void surfaceCreated(SurfaceHolder holder) {
(new Thread(this)).start();
}
public void surfaceDestroyed(SurfaceHolder holder) {
cameraRelease();
}
public void surfaceChanged(SurfaceHolder holder, int format, int width,
int height) {
cameraSetup(width, height);
}
* Add *cameraOpen*, *cameraRelease* and *cameraSetup* voids as shown below.
* Also, don't forget to add the public void *run()* as follows:
.. code-block:: java
public void run() {
// TODO: loop { getFrame(), processFrame(), drawFrame() }
}
public boolean cameraOpen() {
return false; //TODO: open camera
}
private void cameraRelease() {
// TODO release camera
}
private void cameraSetup(int width, int height) {
// TODO setup camera
}
..
#. Create a new *Activity* (*New -> Other -> Android -> Android Activity*) and name it, for example: *HelloOpenCVActivity*. For this activity define *onCreate*, *onResume* and *onPause* voids.
.. code-block:: java
public void onCreate (Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
mView = new HelloOpenCVView(this);
setContentView (mView);
}
protected void onPause() {
super.onPause();
mView.cameraRelease();
}
protected void onResume() {
super.onResume();
if( !mView.cameraOpen() ) {
// MessageBox and exit app
AlertDialog ad = new AlertDialog.Builder(this).create();
ad.setCancelable(false); // This blocks the "BACK" button
ad.setMessage("Fatal error: can't open camera!");
ad.setButton("OK", new DialogInterface.OnClickListener() {
public void onClick(DialogInterface dialog, int which) {
dialog.dismiss();
finish();
}
});
ad.show();
}
}
#. Add the following permissions to the AndroidManifest.xml file:
.. code-block:: xml
</application>
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />
#. Reference OpenCV library within your project properties.
.. image:: images/dev_OCV_reference.png
:alt: Reference OpenCV library.
:align: center
#. We now need some code to handle the camera. Update the *HelloOpenCVView* class as follows:
.. code-block:: java
private VideoCapture mCamera;
public boolean cameraOpen() {
synchronized (this) {
cameraRelease();
mCamera = new VideoCapture(Highgui.CV_CAP_ANDROID);
if (!mCamera.isOpened()) {
mCamera.release();
mCamera = null;
Log.e("HelloOpenCVView", "Failed to open native camera");
return false;
}
}
return true;
}
public void cameraRelease() {
synchronized(this) {
if (mCamera != null) {
mCamera.release();
mCamera = null;
}
}
}
private void cameraSetup(int width, int height) {
synchronized (this) {
if (mCamera != null && mCamera.isOpened()) {
List<Size> sizes = mCamera.getSupportedPreviewSizes();
int mFrameWidth = width;
int mFrameHeight = height;
{ // selecting optimal camera preview size
double minDiff = Double.MAX_VALUE;
for (Size size : sizes) {
if (Math.abs(size.height - height) < minDiff) {
mFrameWidth = (int) size.width;
mFrameHeight = (int) size.height;
minDiff = Math.abs(size.height - height);
}
}
}
mCamera.set(Highgui.CV_CAP_PROP_FRAME_WIDTH, mFrameWidth);
mCamera.set(Highgui.CV_CAP_PROP_FRAME_HEIGHT, mFrameHeight);
}
}
}
#. The last step would be to update the *run()* void in *HelloOpenCVView* class as follows:
.. code-block:: java
public void run() {
while (true) {
Bitmap bmp = null;
synchronized (this) {
if (mCamera == null)
break;
if (!mCamera.grab())
break;
bmp = processFrame(mCamera);
}
if (bmp != null) {
Canvas canvas = getHolder().lockCanvas();
if (canvas != null) {
canvas.drawBitmap(bmp, (canvas.getWidth() - bmp.getWidth()) / 2,
(canvas.getHeight() - bmp.getHeight()) / 2, null);
getHolder().unlockCanvasAndPost(canvas);
}
bmp.recycle();
}
}
}
protected Bitmap processFrame(VideoCapture capture) {
Mat mRgba = new Mat();
capture.retrieve(mRgba, Highgui.CV_CAP_ANDROID_COLOR_FRAME_RGBA);
//process mRgba
Bitmap bmp = Bitmap.createBitmap(mRgba.cols(), mRgba.rows(), Bitmap.Config.ARGB_8888);
try {
Utils.matToBitmap(mRgba, bmp);
} catch(Exception e) {
Log.e("processFrame", "Utils.matToBitmap() throws an exception: " + e.getMessage());
bmp.recycle();
bmp = null;
}
return bmp;
}

BIN
doc/tutorials/introduction/android_binary_package/images/AVD_create.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

BIN
doc/tutorials/introduction/android_binary_package/images/AVD_empty.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
doc/tutorials/introduction/android_binary_package/images/cmd_adb_devices.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.6 KiB

BIN
doc/tutorials/introduction/android_binary_package/images/dev_OCV_new_class.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
doc/tutorials/introduction/android_binary_package/images/dev_OCV_reference.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 33 KiB

BIN
doc/tutorials/introduction/android_binary_package/images/device_details.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

113
doc/tutorials/introduction/table_of_content_introduction/table_of_content_introduction.rst
View File

@ -105,8 +105,8 @@ Here you can read tutorials about how to set up your computer to work with the O
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ ======================================================
================ =================================================
|AndroidBinPack| **Title:** :ref:`Android_Binary_Package`
*Compatibility:* > OpenCV 2.3.1
@ -115,17 +115,13 @@ Here you can read tutorials about how to set up your computer to work with the O
You will learn how to setup OpenCV for Android platform!
================ ======================================================
.. |AndroidBinPack| image:: images/android_logo.png
:height: 90pt
:width: 90pt
================ =================================================
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ ======================================================
|AndroidNDKPack| **Title:** :ref:`Android_Binary_Package_with_NDK`
================ =================================================
|AndroidBinPack| **Title:** :ref:`Android_Binary_Package_with_NDK`
*Compatibility:* > OpenCV 2.3.1
@ -133,34 +129,84 @@ Here you can read tutorials about how to set up your computer to work with the O
You will learn how to work with C++ OpenCV code for Android platform
================ ======================================================
================ =================================================
.. |AndroidBinPack| image:: images/android_logo.png
:height: 90pt
:width: 90pt
* **Android** tutorials v2 [in progress]
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ =================================================
|AndroidNDKPack| **Title:** :ref:`Android_Dev_Intro`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_VsevolodG|
Not a tutorial, but a guide introducing Android development basics and environment setup
================ =================================================
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ =================================================
|AndroidNDKPack| **Title:** :ref:`O4A_SDK`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_VsevolodG|
OpenCV4Android SDK: general info, installation, running samples
================ =================================================
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
================ =================================================
|AndroidNDKPack| **Title:** :ref:`dev_with_OCV_on_Android`
*Compatibility:* > OpenCV 2.4.2
*Author:* |Author_VsevolodG|
Development with OpenCV4Android SDK
================ =================================================
.. |AndroidNDKPack| image:: images/android_logo.png
:height: 90pt
:width: 90pt
* **iOS**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=========== ======================================================
|Install_2| **Title:** :ref:`iOS-Installation`
=========== ======================================================
|Install_2| **Title:** :ref:`iOS-Installation`
*Compatibility:* > OpenCV 2.3.1
*Compatibility:* > OpenCV 2.3.1
*Author:* |Author_ArtemM|
*Author:* |Author_ArtemM|
We will learn how to setup OpenCV for using it in iOS!
We will learn how to setup OpenCV for using it in iOS!
=========== ======================================================
=========== ======================================================
.. |Install_2| image:: images/ios4_logo.jpg
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
.. |Install_2| image:: images/ios4_logo.jpg
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
============= ======================================================
|Beginners_1| **Title:** :ref:`Display_Image`
@ -172,12 +218,12 @@ Here you can read tutorials about how to set up your computer to work with the O
============= ======================================================
.. |Beginners_1| image:: images/Display_Image_Tutorial_Result.jpg
:height: 90pt
:width: 90pt
.. |Beginners_1| image:: images/Display_Image_Tutorial_Result.jpg
:height: 90pt
:width: 90pt
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
.. cssclass:: toctableopencv
=============== ======================================================
|Beginners_2| **Title:** :ref:`Load_Save_Image`
@ -190,12 +236,15 @@ Here you can read tutorials about how to set up your computer to work with the O
=============== ======================================================
.. |Beginners_2| image:: images/Load_Save_Image_Result_1.jpg
:height: 90pt
:width: 90pt
.. |Beginners_2| image:: images/Load_Save_Image_Result_1.jpg
:height: 90pt
:width: 90pt
* **Want to contribute, and see your own work between the OpenCV tutorials?**
.. tabularcolumns:: m{100pt} m{300pt}
.. cssclass:: toctableopencv
=============== ======================================================
|HowToWriteT| **Title:** :ref:`howToWriteTutorial`
@ -226,6 +275,8 @@ Here you can read tutorials about how to set up your computer to work with the O
../windows_visual_studio_Opencv/windows_visual_studio_Opencv
../android_binary_package/android_binary_package
../android_binary_package/android_binary_package_using_with_NDK
../android_binary_package/android_dev_intro
../android_binary_package/dev_with_OCV_on_Android
../ios_install/ios_install
../display_image/display_image
../load_save_image/load_save_image