doc/tutorials/introduction/android_binary_package/O4A_SDK.markdown

   1 OpenCV4Android SDK {#tutorial_O4A_SDK}
   2 ==================
   3
   4 This tutorial was designed to help you with installation and configuration of OpenCV4Android SDK.
   5
   6 This guide was written with MS Windows 7 in mind, though it should work with GNU Linux and Apple Mac
   7 OS as well.
   8
   9 This tutorial assumes you have the following software installed and configured:
  10
  11 -   JDK
  12 -   Android SDK and NDK
  13 -   Eclipse IDE
  14 -   ADT and CDT plugins for Eclipse
  15
  16 If you need help with anything of the above, you may refer to our @ref tutorial_android_dev_intro guide.
  17
  18 If you encounter any error after thoroughly following these steps, feel free to contact us via
  19 [OpenCV4Android](https://groups.google.com/group/android-opencv/) discussion group or OpenCV [Q&A
  20 forum](http://answers.opencv.org). We'll do our best to help you out.
  21
  22 Tegra Android Development Pack users
  23 ------------------------------------
  24
  25 You may have used [Tegra Android Development
  26 Pack](http://developer.nvidia.com/tegra-android-development-pack) (**TADP**) released by **NVIDIA**
  27 for Android development environment setup.
  28
  29 Beside Android development tools the TADP 2.0 includes OpenCV4Android SDK, so it can be already
  30 installed in your system and you can skip to @ref tutorial_O4A_SDK_samples "samples" section of this tutorial.
  31
  32 More details regarding TADP can be found in the @ref tutorial_android_dev_intro guide.
  33
  34 General info
  35 ------------
  36
  37 OpenCV4Android SDK package enables development of Android applications with use of OpenCV library.
  38
  39 The structure of package contents looks as follows:
  40
  41     OpenCV-2.4.9-android-sdk
  42     |_ apk
  43     |   |_ OpenCV_2.4.9_binary_pack_armv7a.apk
  44     |   |_ OpenCV_2.4.9_Manager_2.18_XXX.apk
  45     |
  46     |_ doc
  47     |_ samples
  48     |_ sdk
  49     |    |_ etc
  50     |    |_ java
  51     |    |_ native
  52     |          |_ 3rdparty
  53     |          |_ jni
  54     |          |_ libs
  55     |               |_ armeabi
  56     |               |_ armeabi-v7a
  57     |               |_ x86
  58     |
  59     |_ LICENSE
  60     |_ README.android
  61
  62 -   `sdk` folder contains OpenCV API and libraries for Android:
  63 -   `sdk/java` folder contains an Android library Eclipse project providing OpenCV Java API that can
  64     be imported into developer's workspace;
  65 -   `sdk/native` folder contains OpenCV C++ headers (for JNI code) and native Android libraries
  66     (\*.so and \*.a) for ARM-v5, ARM-v7a and x86 architectures;
  67 -   `sdk/etc` folder contains Haar and LBP cascades distributed with OpenCV.
  68 -   `apk` folder contains Android packages that should be installed on the target Android device to
  69     enable OpenCV library access via OpenCV Manager API (see details below).
  70
  71     On production devices that have access to Google Play Market (and Internet) these packages will
  72     be installed from Market on the first start of an application using OpenCV Manager API. But
  73     devkits without Market or Internet connection require this packages to be installed manually.
  74     Install the Manager.apk and optional binary_pack.apk if it needed. See `Manager Selection`
  75     for details.
  76
  77     @note Installation from Internet is the preferable way since OpenCV team may publish updated
  78     versions of this packages on the Market.
  79
  80 -   `samples` folder contains sample applications projects
  81     and their prebuilt packages (APK). Import them into Eclipse workspace (like described below) and
  82     browse the code to learn possible ways of OpenCV use on Android.
  83
  84 -   `doc` folder contains various OpenCV documentation in PDF format. It's also available online at
  85     <http://docs.opencv.org>.
  86     @note The most recent docs (nightly build) are at <http://docs.opencv.org/3.4>. Generally, it's more
  87     up-to-date, but can refer to not-yet-released functionality.
  88     @todo I'm not sure that this is the best place to talk about OpenCV Manager
  89
  90 Starting from version 2.4.3 OpenCV4Android SDK uses OpenCV Manager API for library initialization.
  91 OpenCV Manager is an Android service based solution providing the following benefits for OpenCV
  92 applications developers:
  93
  94 -   Compact apk-size, since all applications use the same binaries from Manager and do not store
  95     native libs within themselves;
  96 -   Hardware specific optimizations are automatically enabled on all supported platforms;
  97 -   Automatic updates and bug fixes;
  98 -   Trusted OpenCV library source. All packages with OpenCV are published on Google Play;
  99
 100
 101 Manual OpenCV4Android SDK setup
 102 -------------------------------
 103
 104 ### Get the OpenCV4Android SDK
 105
 106 -#  Go to the [OpenCV download page on
 107     SourceForge](http://sourceforge.net/projects/opencvlibrary/files/) and download
 108     the latest available version. This tutorial is based on this package: [OpenCV-2.4.9-android-sdk.zip](http://sourceforge.net/projects/opencvlibrary/files/opencv-android/2.4.9/OpenCV-2.4.9-android-sdk.zip/download).
 109 -#  Create a new folder for Android with OpenCV development. For this tutorial we have unpacked
 110     OpenCV SDK to the `C:\Work\OpenCV4Android\` directory.
 111
 112     @note Better to use a path without spaces in it. Otherwise you may have problems with ndk-build.
 113
 114 -#  Unpack the SDK archive into the chosen directory.
 115
 116     You can unpack it using any popular archiver (e.g with 7-Zip):
 117
 118     ![](images/android_package_7zip.png)
 119
 120     On Unix you can use the following command:
 121     @code{.bash}
 122     unzip ~/Downloads/OpenCV-2.4.9-android-sdk.zip
 123     @endcode
 124
 125 ### Import OpenCV library and samples to the Eclipse
 126
 127 -#  Start Eclipse and choose your workspace location.
 128
 129     We recommend to start working with OpenCV for Android from a new clean workspace. A new Eclipse
 130     workspace can for example be created in the folder where you have unpacked OpenCV4Android SDK
 131     package:
 132
 133     ![](images/eclipse_1_choose_workspace.png)
 134
 135 -#  Import OpenCV library and samples into workspace.
 136
 137     OpenCV library is packed as a ready-for-use [Android Library
 138     Project](http://developer.android.com/guide/developing/projects/index.html#LibraryProjects). You
 139     can simply reference it in your projects.
 140
 141     Each sample included into the `OpenCV-2.4.9-android-sdk.zip` is a regular Android project that
 142     already references OpenCV library. Follow the steps below to import OpenCV and samples into the
 143     workspace:
 144
 145     -   Right click on the Package Explorer window and choose Import... option from the context
 146         menu:
 147
 148         ![](images/eclipse_5_import_command.png)
 149
 150     -   In the main panel select General --\> Existing Projects into Workspace and press Next
 151         button:
 152
 153         ![](images/eclipse_6_import_existing_projects.png)
 154
 155     -   In the Select root directory field locate your OpenCV package folder. Eclipse should
 156         automatically locate OpenCV library and samples:
 157
 158         ![](images/eclipse_7_select_projects.png)
 159
 160     -   Click Finish button to complete the import operation.
 161
 162     @note OpenCV samples are indeed **dependent** on OpenCV library project so don't forget to import it to your workspace as well.
 163
 164     After clicking Finish button Eclipse will load all selected projects into workspace, and you
 165     have to wait some time while it is building OpenCV samples. Just give a minute to Eclipse to
 166     complete initialization.
 167
 168     ![](images/eclipse_cdt_cfg4.png)
 169
 170     Once Eclipse completes build you will have the clean workspace without any build errors:
 171
 172     ![](images/eclipse_10_crystal_clean.png)
 173
 174 @anchor tutorial_O4A_SDK_samples
 175 ### Running OpenCV Samples
 176
 177 At this point you should be able to build and run the samples. Keep in mind, that face-detection and
 178 Tutorial 2 - Mixed Processing include some native code and require Android NDK and NDK/CDT plugin
 179 for Eclipse to build working applications. If you haven't installed these tools, see the
 180 corresponding section of @ref tutorial_android_dev_intro.
 181
 182 **warning**
 183
 184 Please consider that some samples use Android Java Camera API, which is accessible with an AVD.
 185
 186 @note Recent *Android SDK tools, revision 19+* can run ARM v7a OS images but they available not for
 187 all Android versions.
 188
 189 Well, running samples from Eclipse is very simple:
 190
 191 -   Connect your device with adb tool from Android SDK or create an emulator with camera support.
 192     -   See [Managing Virtual Devices](http://developer.android.com/guide/developing/devices/index.html) document for help
 193         with Android Emulator.
 194     -   See [Using Hardware Devices](http://developer.android.com/guide/developing/device.html) for
 195         help with real devices (not emulators).
 196
 197 -   Select project you want to start in Package Explorer and just press Ctrl + F11 or select option
 198     Run --\> Run from the main menu, or click Run button on the toolbar.
 199
 200     @note Android Emulator can take several minutes to start. So, please, be patient. \* On the first
 201     run Eclipse will ask you about the running mode for your application:
 202
 203     ![](images/eclipse_11_run_as.png)
 204
 205 -   Select the Android Application option and click OK button. Eclipse will install and run the
 206     sample.
 207
 208     Chances are that on the first launch you will not have the [OpenCV
 209     Manager](https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p)
 210     package installed. In this case you will see the following message:
 211
 212     ![](images/android_emulator_opencv_manager_fail.png)
 213
 214     To get rid of the message you will need to install OpenCV Manager and the appropriate
 215     OpenCV binary pack. Simply tap Yes if you have *Google Play Market* installed on your
 216     device/emulator. It will redirect you to the corresponding page on *Google Play Market*.
 217
 218     If you have no access to the *Market*, which is often the case with emulators - you will need to
 219     install the packages from OpenCV4Android SDK folder manually. See `Manager Selection` for
 220     details.
 221     @code{.sh}
 222     <Android SDK path>/platform-tools/adb install <OpenCV4Android SDK path>/apk/OpenCV_2.4.9_Manager_2.18_armv7a-neon.apk
 223     @endcode
 224
 225     @note armeabi, armv7a-neon, arm7a-neon-android8, mips and x86 stand for platform targets:
 226         -   armeabi is for ARM v5 and ARM v6 architectures with Android API 8+,
 227         -   armv7a-neon is for NEON-optimized ARM v7 with Android API 9+,
 228         -   arm7a-neon-android8 is for NEON-optimized ARM v7 with Android API 8,
 229         -   mips is for MIPS architecture with Android API 9+,
 230         -   x86 is for Intel x86 CPUs with Android API 9+.
 231
 232     @note
 233     If using hardware device for testing/debugging, run the following command to learn its CPU
 234     architecture:
 235     @code{.sh}
 236     adb shell getprop ro.product.cpu.abi
 237     @endcode
 238     If you're using an AVD emulator, go Window \> AVD Manager to see the list of available devices.
 239     Click Edit in the context menu of the selected device. In the window, which then pop-ups, find
 240     the CPU field.
 241
 242     @note
 243     You may also see section `Manager Selection` for details.
 244
 245     When done, you will be able to run OpenCV samples on your device/emulator seamlessly.
 246
 247 -   Here is Sample - image-manipulations sample, running on top of stock camera-preview of the
 248     emulator.
 249
 250     ![](images/emulator_canny.png)
 251
 252 What's next
 253 -----------
 254
 255 Now, when you have your instance of OpenCV4Adroid SDK set up and configured, you may want to proceed
 256 to using OpenCV in your own application. You can learn how to do that in a separate @ref tutorial_dev_with_OCV_on_Android tutorial.