Android for Opencv 2.2

Android is awesome, and so is OpenCV, so wouldn't it be awesomer if they could work together? Well they can, and its now officially supported in opencv trunk.

Opencv 2.2

Please verify that you are working against this version of opencv: 

https://code.ros.org/svn/opencv/branches/2.2/opencv

quick ubuntu opencv static libs build

cd opencv/android
mkdir build
cd build
cmake ..
make

quick Windows opencv static libs

quick Mac OS opencv static libs

Prerequisites

android ndk

This will not work with the official release of the android ndk. The official android ndk does not support c++ concepts fully like RTTI, exceptions, and most of the stl. Make sure you use the modified android ndk from crystax available at http://www.crystax.net/android/ndk-r4.php

The android ndk, now referred to as the ndk, is the gcc toolchain for android, and is what creates the shared libraries for android that are loadable by android apps through a the Java Native Interface(JNI)

Recommended install of the ndk is to unzip it to your home directory

For example this is what mine looks like: 

erublee@bde:~/android-ndk-r4-crystax$ ls
build  docs  GNUmakefile  ndk-build  ndk-gdb  README.TXT  samples  sources

Android SDK

Please read the very well documented android sdk getting started instructions - http://developer.android.com/sdk/index.html and at least build and install a hello world app on your Android phone.

Android SDK tips

I always add the android sdk tools directory to my path so i can run the adb from any where.

On ubuntu, add the following to your ~/.bashrc 

ANDROID_SDK=~/android-sdk-linux_86
export PATH=$ANDROID_SDK/tools:$ANDROID_SDK/platform-tools:$PATH

The platform-tools directory is needed in the latest android sdk for the adb tool.

Install ant so that you can build from command line.

Make sure your udev permissions are set for usb debug and that the phone itself is set to allow debugging http://developer.android.com/guide/developing/device.html#setting-up

Nexus one users on ubuntu lucid should have the following udev file: 

#/etc/udev/rules.d/51-android.rules
#unplug phone, save this file, then run:
#sudo service udev reload
#plug in your phone, and try running:
#adb devices
SUBSYSTEM=="usb", SYSFS{idVendor}=="18d1", MODE="0666"

see the following blog post on why http://alan.lamielle.net/2010/01/22/nexus-one-usb-in-ubuntu-9-10

How and What

The android port involves high jacking the existing cmake build files and replacing the define_opencv_module with android specific build commands.

In particular the cmake based build creates android ndk build files and calls the android ndk to build opencv.

OpenCV static libs

The main cmake build of opencv generates a static lib for each module and some of the 3rdparty libraries. These can then be linked against in your own android projects.

the cmake build will also generate an android-opencv.mk file in the build folder. Include this file in your Android.mk files to link against the static libs.

this would go in your Android.mk file. See the docs in the ndk for an explanation of LOCAL_LDLIBS and LOCAL_C_INCLUDES. 

#define OPENCV_INCLUDES and OPENCV_LIBS
include $(PATH_TO_OPENCV_ANDROID_BUILD)/android-opencv.mk

LOCAL_LDLIBS += $(OPENCV_LIBS)
    
LOCAL_C_INCLUDES +=  $(OPENCV_INCLUDES)

OpenCV shared library

There is an attempt at a library that is more generally useful for android that could also be linked against in your on projects. This project is under opencv/android/android-jni

This uses swig to expose some functions to java. Also it implements a live camera preview interface, so that you can have access to the Android camera for live vision apps.

Apps

A few sample apps that use the library are under opencv/android/apps

steps

Static libs

cd opencv/android
mkdir build
cd build
cmake ..
make

This may take some time.

android-jni

After the static libs are built, run make in the android-jni folder 

cd opencv/android/android-jni
make

The first time you run make, it will warn you to edit "local.env.mk". If you have the ndk in the default $(HOME)\<android-ndk-name> location, you can just run make again. Otherwise, edit the paths in the local.env.mk file. The second make creates the swig wrappers and compiles the shared library.

Now run the ant based java build. 

sh ./project_create.sh
ant compile

For Windows Users: The above may return an error such as "android: command not found". This is because the android command is a batch file on windows and will not execute within the cygwin bash shell. A quick fix is to create a batch file with the same functionality as project_create.sh and run that instead. Create project_create.bat in the android-jni directory, add the following line to it, and run it from a standard windows command prompt. 

android update project --name android-opencv --path .\

Also note that ant commands will work from either the windows command line or the cygwin bash shell (that's the beauty of ant :-) )

Now you're ready to use it in a sample. Sample's must link to android-jni in the default.properties as an android library. See the following for details on working with android library projects: http://developer.android.com/guide/developing/eclipse-adt.html#libraryProject

CVCamera

cd opencv/android/apps/CVCamera
sh build.sh
make

That builds the swig wrappers and shared library.

Build the android apk ( the thing that gets installed on the phone ) 

sh project_create.sh
ant debug

Now if everything worked, try to install it. Connect your device and run the following 

ant install

Run it, press menu to see options - right now it can draw fast, star, and surf feature points on the live preview image.

Calibration

cd opencv/android/apps/Calibration
sh project_create.sh
ant debug
ant install

To run the app, make sure that the sdcard is not mounted on your computer and point the phone at a calibration pattern and snap away. When you have taken enough chessboards to satisfy yourself press the save button to have the camera calibarted. The calibration will be saved to /sdcard/opencv/calibration.yml

Also see this app for how to make a slightly nicer camera ui than CVCamera.

Troubles

BUILD FAILED
<android-sdk-root>\tools\ant\lib_rules.xml:121: Refrence android.libraries.src not found

Add the following two lines to build.xml, just below </setup>: 

        <path id="android.libraries.src"><path refid="project.libraries.src" /></path>
        <path id="android.libraries.jars"><path refid="project.libraries.jars" /></path>

(see http://code.google.com/p/android/issues/detail?id=13024 for the latest details on this issue)

Programming your own apps

Try to look at the samples - like CVCamera, for how to do this. A tutorial may be forthcoming.

Contributing

If you have any apps that you've created or would like to contribute to the android opencv development, let us know.

OpenCVWiki: Android2.2 (last edited 2011-04-29 21:32:45 by ethanrublee)