• Android2.3.0

The Android build is based on android-cmake project originally developed by Ethan Rublee.
You can find the latest version of his project at http://code.google.com/p/android-cmake/

Prerequisites

• OpenCV source package http://sourceforge.net/projects/opencvlibrary/files/opencv-unix/2.3/OpenCV-2.3.0rc.tar.bz2

• cmake tool http://www.cmake.org/

• Android NDK (revision r5 or newer) http://developer.android.com/sdk/ndk/index.html

• OpenCV trunk https://code.ros.org/svn/opencv/trunk/opencv

Additional requirements for Java wrapper and Android samples

• SWIG http://www.swig.org/

• JDK 5 or JDK 6 http://www.oracle.com/technetwork/java/javase/downloads/index.html

• Android SDK http://developer.android.com/sdk/index.html

• ant http://ant.apache.org

Windows additional prerequisites

OpenCV cross compilation under cygwin is not supported for this release.

However you can cross-compile OpenCV on Windows using native port of make.
These two are tested to work for OpenCV:

• http://gnuwin32.sourceforge.net/packages/make.htm

• http://code.google.com/p/mingw-and-ndk/ (see "make-3.7z" under Downloads section)

OpenCV build

By default OpenCV and the most of Android samples are configured for modern ARM-v7a architecture.
If you want to compile OpenCV for emulator or older device, or want to build with NEON support please read the Android targets section for instructions.

Linux (Ubuntu) and Mac OS (10.6.7)

Export full path to your copy of NDK

export ANDROID_NDK=~/android-ndk-r5c

Alternatively to build with standalone toolchain extracted from NDK you can export toolchain location

export ANDROID_NDK_TOOLCHAIN_ROOT=~/android-toolchain

There is a scripts folder in the android folder for running cmake with the proper cache variables set. It is recommended that you use this to setup a cmake build directory.

cd opencv/android
sh ./scripts/cmake_android.sh

You should now see a build directory, that is ready to be made

cd build
make -j8

That will build most of the OpenCV modules, except for those that don't make sense on android - gpu, etc..

Troubleshooting

If you get an error saying install_name_tool not found, then:

1. search for the file install_name_tool on your file system (usually it is in /usr/bin/);

2. open the file /opt/local/share/cmake-2.8/Modules/CMakeFindBinUtils.cmake;

3. after the line 'FIND_PROGRAM(CMAKE_INSTALL_NAME_TOOL NAMES install_name_tool HINTS ${_CMAKE_TOOLCHAIN_LOCATION})' add the line

     set( CMAKE_INSTALL_NAME_TOOL <path to install_name_tool>)

   e.g. something like

     set( CMAKE_INSTALL_NAME_TOOL /usr/bin/install_name_tool)

Next remove your build folder and restart from the ./scripts/cmake_android.sh script.

Windows (native)

Define the following environment variables:

• ANDROID_NDK - full path to the Android NDK. This path should not contain spaces, and tailing slash.
• CMAKE_EXE - full path to cmake executable (including executable name).
• MAKE_EXE - full path to native port of make (including executable name). This path should not contain spaces.

Instead of modifying your environment you can create file opencv\android\scripts\wincfg.cmd and put all settings to this file. OpenCV provides template for this file named opencv\android\scripts\wincmd.cfg.tmpl. Please note that settings from wincfg.cmd takes precedence over global environment variables.

Then open Windows console (cmd.exe) and go to opencv\android folder. Run script cmake_android.cmd from scripts folder:

cd opencv\android\
scripts\cmake_android.cmd

When script finishes you will have OpenCV compiled.

Troubleshooting

First, make sure that paths to OpenCV, Android NDK and make.exe do not contain spaces and other suspicious symbols.

If make fails with message similar to

*** target pattern contains no `%'.  Stop.

Then you probably use cygwin tools instead of their native ports. Remove cygwin from your PATH, delete build directory and rebuild.

Building console "Hello World" with OpenCV

This application is not usual Android application. This is a unix console which may be used as a template for development. Console application is much more convenient for development, debugging and performance optimization stages. Then, if you are finished with your CV algorithm, you can switch to normal Android development with Java + NDK (see the android-opencv and OpenCV_SAMPLE sections below).

Prerequisities

First of all you need an Android device with root privileges. The goal is to have ability to run console applications on Android device using adb shell. Even chmod is not available by default (for example on Nexus One). You have the following options:

• Use emulator

• Enable root access to your device. Use google to find instructions for your device.

• Use developer device, for example NVidia Tegra devkits have root access by default.

If the device allows you to do chmod and run executables, then follow the instructions below.

Second, you need OpenCV compiled for your device. By default this sample is configured for emulator. Read Android targets to know how to build OpenCV for emulator.

Also you need some free space on sdcard to run the HelloAndroid application - it will write small image to /mnt/sdcard. Please note, that even with emulator you need a sdcard. You can create it with AVD Manager from Android SDK.

Linux (Ubuntu) and Mac OS (10.6.7)

Export full path to your copy of NDK

export ANDROID_NDK=~/android-ndk-r5c

or path to standalone toolchain

export ANDROID_NDK_TOOLCHAIN_ROOT=~/android-toolchain

Run the following commands to build project

cd opencv/android/apps/HelloAndroid
sh ./cmake_android.sh
cd ./build_armeabi
make
cd ..

Connect to your device with adb tool from Android SDK and run the application

sh ./run.sh

If you can see HelloAndroid.png in your current directory and Hello Android! message in console - you've arrived.

If you want to build this sample for ARM-v7a device (with or without NEON support) you need to edit cmake_android.sh and run.sh scripts. Change BUILD_DIR and OUT_DIR paths and ARM_TARGET cmake parameter.

Windows

Set the same environment variables as needed for OpenCV build (variables set in \opencv\android\scripts\wincfg.cmd work as well).
If you are using wincfg.cmd file then ensure that ARM_TARGET and BUILD_DIR are set to correct values. Use the following values for emulator:

SET BUILD_DIR=build_armeabi
SET ARM_TARGET=armeabi

When all variables are set run the commands

cd opencv\android\apps\HelloAndroid
cmake_android.cmd

Connect to your device with adb tool from Android SDK and run the application

run.cmd

If you can see HelloAndroid.png in your current directory and Hello Android! message in console - you've arrived.

Troubleshooting

If you see error message similar to

ld: cannot find -lopencv_contrib

or (on Windows)

ld.exe: cannot find -lopencv_contrib230

It means that cmake failed to find OpenCV compiled for Android. Check that all paths are set to correct values, remove build directory and try to rebuild the application.

Building the android-opencv project

The android-opencv project is a shared OpenCV library for Android. It contains some java bindings and a java/jni camera client. It is required to build the most of Android samples.

Prerequisities

You need OpenCV compiled for Android.

Linux (Ubuntu) and Mac OS (10.6.7)

cd android/android-opencv
sh ./cmake_android.sh
cd build
make -j4

If the cmake or make errors out, be sure to read the errors. Use cmake, or cmake-gui to set the path to the build directory for OpenCV (the one for Andorid, might be in android/build).

make sure your PATH has android-sdk-linux_x86/tools and android-sdk-linux_x86/platform-tools (android-sdk-darwin_x86/tools and android-sdk-darwin_x86/platform-tools on Mac)

To compile android part run the commands

cd android/android-opencv
sh project_create.sh
ant compile

Windows

In addition to variables set for OpenCV build set the following environment variables (or put them to opencv\android\scripts\wincfg.cmd)

• ANDROID_SDK - full path to Android SDK.
• SWIG_DIR - full path to SWIG.
• ANT_DIR - full path to Apache Ant.
• JAVA_HOME - full path to JDK. Both x86 and x64 work for OpenCV. But note that Android SDK installer requires 32 bit JRE. At the same time if you download zip with SDK, you can work with 64 bit JRE/JDK without 32 bit version installed.

All paths should be specified without tailing slash.

Next go to android-opencv folder and run build script:

cd android-opencv
cmake_andoid.cmd

Troubleshooting

If android helper tool complains (when you run project_create.sh script on linux/Mac or cmake_andoid.cmd on Windows) then you have not installed API level 7 package to your Android SDK. You can either install it or update project settings to use one of API levels you have.

Put your target API level to default.properties file and rerun the script. android-opnecv supports target-7 or higher.

To get full list of installed API targets you can use the command

android list targets

Building a sample OpenCV_SAMPLE

cd android/apps/OpenCV_SAMPLE
mkdir build
cd build
cmake -DOpenCVDIR=../../../build -DCMAKE_TOOLCHAIN_FILE=../../../android.toolchain.cmake ..
make

You may need to point the cmake cache to the android build of opencv, and the android-opencv/build directory. It's looking for the paths containing OpenCVConfig.cmake

Now you are ready to build the android project and run it on your device. You should have the android sdk setup on your machine, in your path, and also have ant for command line compilation of android apps.

Plug in your device and do the following

cd android/apps/OpenCV_SAMPLE
sh project_create.sh
ant compile
ant install

If installing to your device or emulator fails with "[INSTALL_FAILED_INVALID_APK]" be sure to check the device/emulator log with:

adb logcat

If you see errors related to an ABI mismatch, such as "Native ABI mismatch from package file", you may need to edit the CMake include file pointed to in ANDTOOLCHAIN, "android.toolchain.cmake".

If you are questioning if the libraries all made it into the apk, open up the apk in an archive manager and peak in the libs directory. You should see libOpenCV_SAMPLE.so and libandroid-opencv.so in there.

Native camera support in OpenCV

Native interface of Android camera is platform-dependent. So OpenCV isolates platform-dependent part of code into separate shared library.
OpenCV provides two prebuilt libraries for native camera:

libnative_camera_r2.2.2.so
libnative_camera_r2.3.3.so

These libraries are tested to work for Android 2.2.2, 2.3.3, 2.3.4, 3.0.1.
You should include these libraries into your .apk to get camera working. OpenCV will automatically load one of these libraries compatible with your Android OS version.

Please note, that prebuilt libraries are compiled for ARM-v7a hardware.

Also, please remember, that emulator from Android SDK has no camera.

Use native camera in your cmake project

Include highgui.hpp header to you source

#include "opencv2/highgui/highgui.hpp"

Create new VideoCapture object and start grabbing frames

cv::VideoCapture capture(CV_CAP_ANDROID + 0);
//cv::VideoCapture capture(CV_CAP_ANDROID + 1);//front camera for Android 2.3.3 or newer

if( !capture.isOpened() )
    return;

capture.set(CV_CAP_PROP_FRAME_WIDTH, 640);
capture.set(CV_CAP_PROP_FRAME_HEIGHT, 480);

for(int i=0; i < 100; ++i)
{
    cv::Mat frame;

    capture >> frame;
    if( !frame.empty() )
        yourfunction::processFrame(frame);
}

Finally, add following lines to your cmake

if (COMMAND COPY_NATIVE_CAMERA_LIBS)
  COPY_NATIVE_CAMERA_LIBS(${PROJECT_NAME})
endif()

Where PROJECT_NAME variable contains name of module that uses native camera.

Warning: Native camera from OpenCV 2.3.0 does not work inside console applications and test projects.

Advanced: build your camera wrapper

If prebuilt libraries don't work for you for whatever reason then you can build your own camera wrapper lib.

To build your lib you have to download sources for your version of Android and build entire OS first.
See http://source.android.com/source/downloading.html and google for instructions.

When you finish with Android OS run cmake for OpenCV (scripts/cmake_android.sh will run it for you). You should see following line in its output

--     AndroidNativeCamera:        use prebuilt libraries

Next, you need to set cmake cache variable ANDROID_SOURCE_TREE to the path to Android OS source tree and rerun cmake. (You can set this variable with cmake-gui application, or editing build/CMakeCache.txt file with text editor, or passing it as cmake argument).

If path is set correctly then you should see line similar to following in cmake output

--     AndroidNativeCamera:        build for Android 2.3.4

Run make command to compile the sources.

Most probably you will need to make changes in file opencv/modules/androidcamera/camera_wrapper/camera_wrapper.cpp to fix compiler errors.
If you do some changes please post your patch to https://code.ros.org/trac/opencv to help with OpenCV development.

Advanced build options

Using OpenCV in your own cmake projects

Use the cmake find script for OpenCV

find_package(OpenCV REQUIRED)

Export path to OpenCV source tree

export OPENCV_ROOT=~/opencv

Then when you run cmake, use:

cmake -DOpenCV_Dir=$OPENCV_ROOT/android/build -DCMAKE_TOOLCHAIN_FILE=$OPENCV_ROOT/android/android.toolchain.cmake ..

And direct your cmake cache for OpenCV_Dir to the path where you built OpenCV for android. something like : opencv/android/build

To avoid setting the cmake cache for OpenCV_Dir, you can just "install" OpenCV to your Android toolchain/NDK. Run the following from the opencv/android/build path:

make install/strip

Android hardware targets

You may wish to build OpenCV and samples for multiple hardware targets.

Just change the cmake cache ARM_TARGET to either: "armeabi" "armeab-v7a" "armeab-v7a with NEON"

You may install each of these to the toolchain/NDK, and they should be linked against properly via way of the android-cmake toolchain.

Android API levels

You may wish to build OpenCV and samples for different level of Android native API.

Just change the cmake cache ANDROID_API_LEVEL to appropriative value.

The following levels are currently supported: