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/2.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 For additional information on OpenCV Manager see the: 101 102 - [Slides](https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p) 103 - [Reference Manual](http://docs.opencv.org/android/refman.html) 104 105 Manual OpenCV4Android SDK setup 106 ------------------------------- 107 108 ### Get the OpenCV4Android SDK 109 110 -# Go to the [OpenCV download page on 111 SourceForge](http://sourceforge.net/projects/opencvlibrary/files/opencv-android/) and download 112 the latest available version. Currently it's [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). 113 -# Create a new folder for Android with OpenCV development. For this tutorial we have unpacked 114 OpenCV SDK to the `C:\Work\OpenCV4Android\` directory. 115 116 @note Better to use a path without spaces in it. Otherwise you may have problems with ndk-build. 117 118 -# Unpack the SDK archive into the chosen directory. 119 120 You can unpack it using any popular archiver (e.g with 7-Zip): 121 122  123 124 On Unix you can use the following command: 125 @code{.bash} 126 unzip ~/Downloads/OpenCV-2.4.9-android-sdk.zip 127 @endcode 128 129 ### Import OpenCV library and samples to the Eclipse 130 131 -# Start Eclipse and choose your workspace location. 132 133 We recommend to start working with OpenCV for Android from a new clean workspace. A new Eclipse 134 workspace can for example be created in the folder where you have unpacked OpenCV4Android SDK 135 package: 136 137  138 139 -# Import OpenCV library and samples into workspace. 140 141 OpenCV library is packed as a ready-for-use [Android Library 142 Project](http://developer.android.com/guide/developing/projects/index.html#LibraryProjects). You 143 can simply reference it in your projects. 144 145 Each sample included into the `OpenCV-2.4.9-android-sdk.zip` is a regular Android project that 146 already references OpenCV library. Follow the steps below to import OpenCV and samples into the 147 workspace: 148 149 - Right click on the Package Explorer window and choose Import... option from the context 150 menu: 151 152  153 154 - In the main panel select General --\> Existing Projects into Workspace and press Next 155 button: 156 157  158 159 - In the Select root directory field locate your OpenCV package folder. Eclipse should 160 automatically locate OpenCV library and samples: 161 162  163 164 - Click Finish button to complete the import operation. 165 166 @note OpenCV samples are indeed **dependent** on OpenCV library project so don't forget to import it to your workspace as well. 167 168 After clicking Finish button Eclipse will load all selected projects into workspace, and you 169 have to wait some time while it is building OpenCV samples. Just give a minute to Eclipse to 170 complete initialization. 171 172  173 174 Once Eclipse completes build you will have the clean workspace without any build errors: 175 176  177 178 @anchor tutorial_O4A_SDK_samples 179 ### Running OpenCV Samples 180 181 At this point you should be able to build and run the samples. Keep in mind, that face-detection and 182 Tutorial 2 - Mixed Processing include some native code and require Android NDK and NDK/CDT plugin 183 for Eclipse to build working applications. If you haven't installed these tools, see the 184 corresponding section of @ref tutorial_android_dev_intro. 185 186 **warning** 187 188 Please consider that some samples use Android Java Camera API, which is accessible with an AVD. 189 190 @note Recent *Android SDK tools, revision 19+* can run ARM v7a OS images but they available not for 191 all Android versions. 192 193 Well, running samples from Eclipse is very simple: 194 195 - Connect your device with adb tool from Android SDK or create an emulator with camera support. 196 - See [Managing Virtual Devices](http://developer.android.com/guide/developing/devices/index.html) document for help 197 with Android Emulator. 198 - See [Using Hardware Devices](http://developer.android.com/guide/developing/device.html) for 199 help with real devices (not emulators). 200 201 - Select project you want to start in Package Explorer and just press Ctrl + F11 or select option 202 Run --\> Run from the main menu, or click Run button on the toolbar. 203 204 @note Android Emulator can take several minutes to start. So, please, be patient. \* On the first 205 run Eclipse will ask you about the running mode for your application: 206 207  208 209 - Select the Android Application option and click OK button. Eclipse will install and run the 210 sample. 211 212 Chances are that on the first launch you will not have the [OpenCV 213 Manager](https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p) 214 package installed. In this case you will see the following message: 215 216  217 218 To get rid of the message you will need to install OpenCV Manager and the appropriate 219 OpenCV binary pack. Simply tap Yes if you have *Google Play Market* installed on your 220 device/emulator. It will redirect you to the corresponding page on *Google Play Market*. 221 222 If you have no access to the *Market*, which is often the case with emulators - you will need to 223 install the packages from OpenCV4Android SDK folder manually. See `Manager Selection` for 224 details. 225 @code{.sh} 226 <Android SDK path>/platform-tools/adb install <OpenCV4Android SDK path>/apk/OpenCV_2.4.9_Manager_2.18_armv7a-neon.apk 227 @endcode 228 229 @note armeabi, armv7a-neon, arm7a-neon-android8, mips and x86 stand for platform targets: 230 - armeabi is for ARM v5 and ARM v6 architectures with Android API 8+, 231 - armv7a-neon is for NEON-optimized ARM v7 with Android API 9+, 232 - arm7a-neon-android8 is for NEON-optimized ARM v7 with Android API 8, 233 - mips is for MIPS architecture with Android API 9+, 234 - x86 is for Intel x86 CPUs with Android API 9+. 235 236 @note 237 If using hardware device for testing/debugging, run the following command to learn its CPU 238 architecture: 239 @code{.sh} 240 adb shell getprop ro.product.cpu.abi 241 @endcode 242 If you're using an AVD emulator, go Window \> AVD Manager to see the list of availible devices. 243 Click Edit in the context menu of the selected device. In the window, which then pop-ups, find 244 the CPU field. 245 246 @note 247 You may also see section `Manager Selection` for details. 248 249 When done, you will be able to run OpenCV samples on your device/emulator seamlessly. 250 251 - Here is Sample - image-manipulations sample, running on top of stock camera-preview of the 252 emulator. 253 254  255 256 What's next 257 ----------- 258 259 Now, when you have your instance of OpenCV4Adroid SDK set up and configured, you may want to proceed 260 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. 261
