8 This tutorial was designed to help you with installation and configuration of OpenCV4Android SDK.
10 This guide was written with MS Windows 7 in mind, though it should work with GNU Linux and Apple
13 This tutorial assumes you have the following software installed and configured:
21 * ADT and CDT plugins for Eclipse
25 If you need help with anything of the above, you may refer to our :ref:`android_dev_intro` guide.
27 If you encounter any error after thoroughly following these steps, feel free to contact us via
28 `OpenCV4Android <https://groups.google.com/group/android-opencv/>`_ discussion group or
29 OpenCV `Q&A forum <http://answers.opencv.org>`_. We'll do our best to help you out.
31 Tegra Android Development Pack users
32 ====================================
34 You may have used `Tegra Android Development Pack <http://developer.nvidia.com/tegra-android-development-pack>`_
35 (**TADP**) released by **NVIDIA** for Android development environment setup.
37 Beside Android development tools the TADP 2.0 includes OpenCV4Android SDK, so it can be already
38 installed in your system and you can skip to :ref:`Running_OpenCV_Samples` section of this tutorial.
40 More details regarding TADP can be found in the :ref:`android_dev_intro` guide.
45 OpenCV4Android SDK package enables development of Android applications with use of OpenCV library.
47 The structure of package contents looks as follows:
51 OpenCV-2.4.5-android-sdk
53 | |_ OpenCV_2.4.5_binary_pack_armv7a.apk
54 | |_ OpenCV_2.4.5_Manager_2.7_XXX.apk
72 * :file:`sdk` folder contains OpenCV API and libraries for Android:
74 * :file:`sdk/java` folder contains an Android library Eclipse project providing OpenCV Java API that
75 can be imported into developer's workspace;
77 * :file:`sdk/native` folder contains OpenCV C++ headers (for JNI code) and native Android libraries
78 (\*\.so and \*\.a) for ARM-v5, ARM-v7a and x86 architectures;
80 * :file:`sdk/etc` folder contains Haar and LBP cascades distributed with OpenCV.
82 * :file:`apk` folder contains Android packages that should be installed on the target Android device
83 to enable OpenCV library access via OpenCV Manager API (see details below).
85 On production devices that have access to Google Play Market (and Internet) these packages will be
86 installed from Market on the first start of an application using OpenCV Manager API.
87 But devkits without Market or Internet connection require this packages to be installed manually.
88 Install the `Manager.apk` and optional `binary_pack.apk` if it needed.
89 See :ref:`manager_selection` for details.
91 .. note:: Installation from Internet is the preferable way since OpenCV team may publish updated
92 versions of this packages on the Market.
94 * :file:`samples` folder contains sample applications projects and their prebuilt packages (APK).
95 Import them into Eclipse workspace (like described below) and browse the code to learn possible
96 ways of OpenCV use on Android.
98 * :file:`doc` folder contains various OpenCV documentation in PDF format.
99 It's also available online at http://docs.opencv.org.
101 .. note:: The most recent docs (nightly build) are at http://docs.opencv.org/trunk/.
102 Generally, it's more up-to-date, but can refer to not-yet-released functionality.
104 .. TODO: I'm not sure that this is the best place to talk about OpenCV Manager
106 Starting from version 2.4.3 `OpenCV4Android SDK` uses `OpenCV Manager` API for library
107 initialization. `OpenCV Manager` is an Android service based solution providing the following
108 benefits for OpenCV applications developers:
110 * Compact apk-size, since all applications use the same binaries from Manager and do not store
111 native libs within themselves;
113 * Hardware specific optimizations are automatically enabled on all supported platforms;
115 * Automatic updates and bug fixes;
117 * Trusted OpenCV library source. All packages with OpenCV are published on Google Play;
121 For additional information on OpenCV Manager see the:
123 * |OpenCV4Android_Slides|_
125 * |OpenCV4Android_Reference|_
129 .. |OpenCV4Android_Slides| replace:: Slides
130 .. _OpenCV4Android_Slides: https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p
131 .. |OpenCV4Android_Reference| replace:: Reference Manual
132 .. _OpenCV4Android_Reference: http://docs.opencv.org/android/refman.html
134 Manual OpenCV4Android SDK setup
135 ===============================
137 Get the OpenCV4Android SDK
138 --------------------------
140 #. Go to the `OpenCV download page on SourceForge <http://sourceforge.net/projects/opencvlibrary/files/opencv-android/>`_
141 and download the latest available version. Currently it's |opencv_android_bin_pack_url|_.
143 #. Create a new folder for Android with OpenCV development. For this tutorial we have unpacked
144 OpenCV SDK to the :file:`C:\\Work\\OpenCV4Android\\` directory.
146 .. note:: Better to use a path without spaces in it. Otherwise you may have problems with :command:`ndk-build`.
148 #. Unpack the SDK archive into the chosen directory.
150 You can unpack it using any popular archiver (e.g with |seven_zip|_):
152 .. image:: images/android_package_7zip.png
153 :alt: Exploring OpenCV package with 7-Zip
156 On Unix you can use the following command:
160 unzip ~/Downloads/OpenCV-2.4.5-android-sdk.zip
162 .. |opencv_android_bin_pack| replace:: :file:`OpenCV-2.4.5-android-sdk.zip`
163 .. _opencv_android_bin_pack_url: http://sourceforge.net/projects/opencvlibrary/files/opencv-android/2.4.5/OpenCV-2.4.5-android-sdk.zip/download
164 .. |opencv_android_bin_pack_url| replace:: |opencv_android_bin_pack|
165 .. |seven_zip| replace:: 7-Zip
166 .. _seven_zip: http://www.7-zip.org/
168 Import OpenCV library and samples to the Eclipse
169 ------------------------------------------------
171 #. Start Eclipse and choose your workspace location.
173 We recommend to start working with OpenCV for Android from a new clean workspace. A new Eclipse
174 workspace can for example be created in the folder where you have unpacked OpenCV4Android SDK package:
176 .. image:: images/eclipse_1_choose_workspace.png
177 :alt: Choosing C:\Work\android-opencv\ as workspace location
180 #. Import OpenCV library and samples into workspace.
182 OpenCV library is packed as a ready-for-use `Android Library Project
183 <http://developer.android.com/guide/developing/projects/index.html#LibraryProjects>`_.
184 You can simply reference it in your projects.
186 Each sample included into the |opencv_android_bin_pack| is a regular Android project that already
187 references OpenCV library. Follow the steps below to import OpenCV and samples into the workspace:
189 .. note:: OpenCV samples are indeed **dependent** on OpenCV library project so don't forget to import it to your workspace as well.
191 * Right click on the :guilabel:`Package Explorer` window and choose :guilabel:`Import...` option
192 from the context menu:
194 .. image:: images/eclipse_5_import_command.png
195 :alt: Select Import... from context menu
198 * In the main panel select :menuselection:`General --> Existing Projects into Workspace` and
199 press :guilabel:`Next` button:
201 .. image:: images/eclipse_6_import_existing_projects.png
202 :alt: General > Existing Projects into Workspace
205 * In the :guilabel:`Select root directory` field locate your OpenCV package folder. Eclipse
206 should automatically locate OpenCV library and samples:
208 .. image:: images/eclipse_7_select_projects.png
209 :alt: Locate OpenCV library and samples
212 * Click :guilabel:`Finish` button to complete the import operation.
214 After clicking :guilabel:`Finish` button Eclipse will load all selected projects into workspace,
215 and you have to wait some time while it is building OpenCV samples. Just give a minute to
216 Eclipse to complete initialization.
218 .. warning :: After the initial import, on a non-Windows (Linux and Mac OS) operating system Eclipse
219 will still show build errors for applications with native C++ code. To resolve the
220 issues, please do the following:
222 Open :guilabel:`Project Properties -> C/C++ Build`, and replace "Build command" text
223 to ``"${NDKROOT}/ndk-build"`` (remove .cmd at the end).
225 .. note :: In some cases the build errors don't disappear, then try the following actions:
227 * right click on ``OpenCV Library`` project -> :guilabel:`Android Tools -> Fix Project Properties`,
228 then menu :guilabel:`Project -> Clean... -> Clean all`
229 * right click on the project with errors -> :guilabel:`Properties -> Android`, make sure the
230 ``Target`` is selected and is ``Android 3.0`` or higher
231 * check the build errors in the :guilabel:`Problems` view window and try to resolve them by yourselves
233 .. image:: images/eclipse_cdt_cfg4.png
237 Once Eclipse completes build you will have the clean workspace without any build errors:
239 .. image:: images/eclipse_10_crystal_clean.png
240 :alt: OpenCV package imported into Eclipse
243 .. _Running_OpenCV_Samples:
245 Running OpenCV Samples
246 ----------------------
248 At this point you should be able to build and run the samples. Keep in mind, that
249 ``face-detection`` and ``Tutorial 2 - Mixed Processing`` include some native code and
250 require Android NDK and NDK/CDT plugin for Eclipse to build working applications. If you haven't
251 installed these tools, see the corresponding section of :ref:`Android_Dev_Intro`.
253 .. warning:: Please consider that some samples use Android Java Camera API, which is accessible
254 with an AVD. But most of samples use OpenCV Native Camera which **may not work** with
257 .. note:: Recent *Android SDK tools, revision 19+* can run ARM v7a OS images but they available not
258 for all Android versions.
260 Well, running samples from Eclipse is very simple:
262 * Connect your device with :command:`adb` tool from Android SDK or create an emulator with camera support.
264 * See `Managing Virtual Devices
265 <http://developer.android.com/guide/developing/devices/index.html>`_ document for help with Android Emulator.
266 * See `Using Hardware Devices
267 <http://developer.android.com/guide/developing/device.html>`_ for help with real devices (not emulators).
270 * Select project you want to start in :guilabel:`Package Explorer` and just press :kbd:`Ctrl + F11`
271 or select option :menuselection:`Run --> Run` from the main menu, or click :guilabel:`Run` button on the toolbar.
273 .. note:: Android Emulator can take several minutes to start. So, please, be patient.
275 * On the first run Eclipse will ask you about the running mode for your application:
277 .. image:: images/eclipse_11_run_as.png
278 :alt: Run sample as Android Application
281 * Select the :guilabel:`Android Application` option and click :guilabel:`OK` button. Eclipse will install and run the sample.
283 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.
284 In this case you will see the following message:
286 .. image:: images/android_emulator_opencv_manager_fail.png
287 :alt: You will see this message if you have no OpenCV Manager installed
290 To get rid of the message you will need to install `OpenCV Manager` and the appropriate `OpenCV binary pack`.
291 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*.
293 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.
298 <Android SDK path>/platform-tools/adb install <OpenCV4Android SDK path>/apk/OpenCV_2.4.5_Manager_2.7_armv7a-neon.apk
300 .. note:: ``armeabi``, ``armv7a-neon``, ``arm7a-neon-android8``, ``mips`` and ``x86`` stand for
303 * ``armeabi`` is for ARM v5 and ARM v6 architectures with Android API 8+,
305 * ``armv7a-neon`` is for NEON-optimized ARM v7 with Android API 9+,
307 * ``arm7a-neon-android8`` is for NEON-optimized ARM v7 with Android API 8,
309 * ``mips`` is for MIPS architecture with Android API 9+,
311 * ``x86`` is for Intel x86 CPUs with Android API 9+.
313 If using hardware device for testing/debugging, run the following command to learn
314 its CPU architecture:
318 adb shell getprop ro.product.cpu.abi
320 If you're using an AVD emulator, go :menuselection:`Window > AVD Manager` to see the
321 list of availible devices. Click :menuselection:`Edit` in the context menu of the
322 selected device. In the window, which then pop-ups, find the CPU field.
324 You may also see section :ref:`manager_selection` for details.
327 When done, you will be able to run OpenCV samples on your device/emulator seamlessly.
329 * Here is ``Sample - image-manipulations`` sample, running on top of stock camera-preview of the emulator.
331 .. image:: images/emulator_canny.png
332 :alt: 'Sample - image-manipulations' running Canny
339 Now, when you have your instance of OpenCV4Adroid SDK set up and configured,
340 you may want to proceed to using OpenCV in your own application.
341 You can learn how to do that in a separate :ref:`dev_with_OCV_on_Android` tutorial.