OpenCV
4.0.0
Open Source Computer Vision
|
This guide was designed to help you in learning Android development basics and setting up your working environment quickly. It was written with Windows 7 in mind, though it would work with Linux (Ubuntu), Mac OS X and any other OS supported by Android SDK.
If you encounter any error after thoroughly following these steps, feel free to contact us via OpenCV4Android discussion group or OpenCV Q&A forum. We'll do our best to help you out.
Android is a Linux-based, open source mobile operating system developed by Open Handset Alliance led by Google. See the Android home site for general details.
Development for Android significantly differs from development for other platforms. So before starting programming for Android we recommend you make sure that you are familiar with the following key topis:
You need the following software to be installed in order to develop for Android in Java:
Sun JDK 6 (Sun JDK 7 is also possible)
Visit Java SE Downloads page and download an installer for your OS.
Here is a detailed JDK (Java Development Kit) installation guide for Ubuntu and Mac OS (only JDK sections are applicable for OpenCV)
Android SDK
Get the latest Android SDK from http://developer.android.com/sdk/index.html
Here is Google's install guide for the SDK.
Android SDK components
You need the following SDK components to be installed:
Android SDK Tools, revision 20 or newer.
Older revisions should also work, but they are not recommended.
SDK Platform Android 3.0 (API 11).
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 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.
See Adding Platforms and Packages for help with installing/updating SDK components.
Eclipse IDE
Check the Android SDK System Requirements 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 Eclipse 4.2 (Juno). They work well for OpenCV under both Windows and Linux.
If you have no Eclipse installed, you can get it from the official site.
ADT plugin for Eclipse
These instructions are copied from Android Developers site, 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:
Click OK
In the next window, you'll see a list of the tools to be downloaded. Click Next.
Read and accept the license agreements, then click Finish.
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. To install Android NDK just extract the archive to some folder on your computer. Here are installation instructions.
docs/
. The main article about using Android NDK build system is in the ANDROID-MK.html
file. Some additional information you can find in the APPLICATION-MK.html
, NDK-BUILD.html
files, and CPU-ARM-NEON.html
, CPLUSPLUS-SUPPORT.html
, PREBUILTS.html
.CDT plugin for Eclipse
If you selected for installation the NDK plugins component of Eclipse ADT plugin (see the picture above) your Eclipse IDE should already have CDT plugin (that means C/C++ Development Tooling). 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 CDT(C/C++ Development Tooling) Builder.
Usually source code of an Android application has the following structure:
root folder of the project/
jni/
libs/
res/
src/
AndroidManifest.xml
project.properties
... other files ...
Where:
src
folder contains Java code of the application,res
folder contains resources of the application (images, xml files describing UI layout, etc),libs
folder will contain native libraries after a successful build,jni
folder contains C/C++ application source code and NDK's build scripts Android.mk
and Application.mk
producing the native libraries,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 android tool from Android SDK.
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 android tool included in Android SDK.AndroidManifest.xml
and project.properties
files are required to compile the C++ part of the application, since Android 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.Android.mk
and Application.mk
scripts The script Android.mk
usually has the following structure:
This is the minimal 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 Android.mk
.
Usually the 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 Application.mk
:
Here is the standard way to compile C++ part of an Android application:
warning
We strongly recommend 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.
After that the Java part of the application can be (re)compiled (using either Eclipse or Ant build tool).
There are several possible ways to integrate compilation of native C++ code by Android NDK into Eclipse build process. We recommend the approach based on Eclipse CDT(C/C++ Development Tooling) Builder.
important
OpenCV for Android package since version 2.4.2 contains sample projects pre-configured CDT Builders. For your own projects follow the steps below.
Define the NDKROOT environment variable containing the path to Android NDK in your system (e.g. "X:\\Apps\\android-ndk-r8" or "/opt/android-ndk-r8").
On Windows an environment variable can be set via My Computer -> Properties -> Advanced -> Environment variables. 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 "export VAR_NAME=VAR_VALUE" line to the "~/.bashrc"
file and logging off and then on.
Open Project Properties -> C/C++ Build, uncheck Use default build command, replace "Build command" text from "make" to
"${NDKROOT}/ndk-build.cmd" on Windows,
"${NDKROOT}/ndk-build" on Linux and MacOS.
Go to Behaviour tab and change "Workbench build type" section like shown below:
Press OK and make sure the ndk-build is successfully invoked when building the project.
If you open your C++ source file in Eclipse editor, you'll see syntax error notifications. They are not real errors, but additional CDT configuring is required.
Open Project Properties -> C/C++ General -> Paths and Symbols and add the following Include paths for **C++**:
The last path should be changed to the correct absolute or relative path to OpenCV4Android SDK location.
This should clear the syntax error notifications in Eclipse C++ editor.
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 (Android Virtual Device) is not probably the most convenient way to test an OpenCV-dependent application, but sure the most uncomplicated one to configure.
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.
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. You need to make some actions for Windows and Linux operating systems to be able to work with Android devices. No extra actions are required for Mac OS. See detailed information on configuring hardware devices in subsections below.
You may also consult the official Android Developers site instructions for more information.
Select 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 appears in the list.
Try your luck installing Google USB drivers without any modifications: right-click on the unknown device, select Properties menu item –> Details tab –> Update Driver button.
Select Browse computer for driver software.
Specify the path to <Android SDK folder>/extras/google/usb_driver/
folder.
If you get the prompt to install unverified drivers and report about success - you've finished with USB driver installation.
Otherwise (getting the failure like shown below) follow the next steps.
Again right-click on the unknown device, select Properties –> Details –> Hardware Ids and copy the line like USB\VID_XXXX&PID_XXXX&MI_XX
.
Now open file <Android SDK folder>/extras/google/usb_driver/android_winusb.inf
. Select either Google.NTx86 or Google.NTamd64 section depending on your host system architecture.
There should be a record like existing ones for your device and you need to add one manually.
Save the android_winusb.inf
file and try to install the USB driver again.
This time installation should go successfully.
And an unknown device is now recognized as an Android phone.
Successful device USB connection can be verified in console via adb devices command.
By default Linux doesn't recognize Android devices, but it's easy to fix this issue. On Ubuntu Linux you have to create a new **/etc/udev/rules.d/51-android.rules** configuration file that contains information about your Android device. You may find some Vendor ID's here or execute lsusb command to view VendorID of plugged Android device. Here is an example of such file for LG device:
Then restart your adb server (even better to restart the system), plug in your Android device and execute adb devices command. You will see the list of attached devices:
No actions are required, just connect your device via USB and run adb devices to check connection.
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 OpenCV4Android SDK tutorial.