`Q&Aforum<http://answers.opencv.org>`_.We'll do our best to help you out.
Ifyouencounteranyerrorafterthoroughlyfollowingthesesteps,feelfreetocontactusvia`OpenCV4Android<https://groups.google.com/group/android-opencv/>`_discussiongrouporOpenCV`Q&Aforum<http://answers.opencv.org>`_.We'll do our best to help you out.
Using OpenCV library within your Android project
Using OpenCV Library Within Your Android Project
================================================
In this section we will explain how to make some existing project to use OpenCV.
Starting with 2.4.2 release for Android, *OpenCV Manager* is used to provide apps with the best available version of OpenCV.
You can get more information here: :ref:`Android_OpenCV_Manager` and in these `slides <https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p>`_.
In this section we will explain how to make some existing project to use OpenCV.
Starting with 2.4.2 release for Android, *OpenCV Manager* is used to provide apps with the best
available version of OpenCV.
You can get more information here: :ref:`Android_OpenCV_Manager` and in these
Using async initialization is a **recommended** way for application development. It uses the OpenCV Manager to access OpenCV libraries externally installed in the target system.
Using async initialization is a **recommended** way for application development. It uses the OpenCV
Manager to access OpenCV libraries externally installed in the target system.
#. Add OpenCV library project to your workspace. Use menu
:guilabel:`File -> Import -> Existing project in your workspace`.
#. Add OpenCV library project to your workspace. Use menu :guilabel:`File -> Import -> Existing project in your workspace`,
press :guilabel:`Browse` button and locate OpenCV4Android SDK (:file:`OpenCV-2.4.3-android-sdk/sdk`).
Press :guilabel:`Browse` button and locate OpenCV4Android SDK
(:file:`OpenCV-2.4.3-android-sdk/sdk`).
.. image:: images/eclipse_opencv_dependency0.png
:alt: Add dependency from OpenCV library
:align: center
#. In application project add a reference to the OpenCV Java SDK in :guilabel:`Project -> Properties -> Android -> Library -> Add` select ``OpenCV Library - 2.4.3``.
#. In application project add a reference to the OpenCV Java SDK in
In most cases OpenCV Manager may be installed automatically from Google Play. For such case, when Google Play is not available, i.e. emulator, developer board, etc, you can
install it manually using adb tool. See :ref:`manager_selection` for details.
In most cases OpenCV Manager may be installed automatically from Google Play. For the case, when
Google Play is not available, i.e. emulator, developer board, etc, you can install it manually
using adb tool. See :ref:`manager_selection` for details.
There is a very base code snippet implementing the async initialization. It shows basic principles. See the "15-puzzle" OpenCV sample for details.
There is a very base code snippet implementing the async initialization. It shows basic principles.
See the "15-puzzle" OpenCV sample for details.
.. code-block:: java
:linenos:
...
...
@@ -97,35 +113,48 @@ There is a very base code snippet implementing the async initialization. It show
}
}
It this case application works with OpenCV Manager in asynchronous fashion. ``OnManagerConnected`` callback will be called in UI thread, when initialization finishes.
Please note, that it is not allowed to use OpenCV calls or load OpenCV-dependent native libs before invoking this callback.
Load your own native libraries that depend on OpenCV after the successful OpenCV initialization.
Default BaseLoaderCallback implementation treat application context as Activity and calls Activity.finish() method to exit in case of initialization failure.
To override this behavior you need to override finish() method of BaseLoaderCallback class and implement your own finalization method.
It this case application works with OpenCV Manager in asynchronous fashion. ``OnManagerConnected``
callback will be called in UI thread, when initialization finishes. Please note, that it is not
allowed to use OpenCV calls or load OpenCV-dependent native libs before invoking this callback.
Load your own native libraries that depend on OpenCV after the successful OpenCV initialization.
Default ``BaseLoaderCallback`` implementation treat application context as Activity and calls
``Activity.finish()`` method to exit in case of initialization failure. To override this behavior
you need to override ``finish()`` method of ``BaseLoaderCallback`` class and implement your own
finalization method.
Application development with static initialization
Application Development with Static Initialization
According to this approach all OpenCV binaries are included into your application package. It is designed mostly for development purposes.
This approach is deprecated for the production code, release package is recommended to communicate with OpenCV Manager via the async initialization described above.
According to this approach all OpenCV binaries are included into your application package. It is
designed mostly for development purposes. This approach is deprecated for the production code,
release package is recommended to communicate with OpenCV Manager via the async initialization
described above.
#. Add the OpenCV library project to your workspace the same way as for the async initialization above.
Use menu :guilabel:`File -> Import -> Existing project in your workspace`, push :guilabel:`Browse` button and select OpenCV SDK path (:file:`OpenCV-2.4.3-android-sdk/sdk`).
#. Add the OpenCV library project to your workspace the same way as for the async initialization
above. Use menu :guilabel:`File -> Import -> Existing project in your workspace`,
press :guilabel:`Browse` button and select OpenCV SDK path
(:file:`OpenCV-2.4.3-android-sdk/sdk`).
.. image:: images/eclipse_opencv_dependency0.png
:alt: Add dependency from OpenCV library
:align: center
#. In the application project add a reference to the OpenCV4Android SDK in :guilabel:`Project -> Properties -> Android -> Library -> Add` select ``OpenCV Library - 2.4.3``;
#. In the application project add a reference to the OpenCV4Android SDK in
#. If your application project **doesn'thaveaJNIpart**,justcopythecorrespondingOpenCVnativelibsfrom:file:`<OpenCV-2.4.3-android-sdk>/sdk/native/libs/<target_arch>`toyourprojectdirectorytofolder:file:`libs/<target_arch>`.
#. If your application project **doesn'thaveaJNIpart**,justcopythecorrespondingOpenCV
#.SeveralvariablescanbeusedtocustomizeOpenCVstuff,butyou**don't need** to use them when your application uses the `async initialization` via the `OpenCV Manager` API.
#.SeveralvariablescanbeusedtocustomizeOpenCVstuff,butyou**don't need** to use them when
your application uses the `async initialization` via the `OpenCV Manager` API.
Note: these variables should be set **before** the ``"include .../OpenCV.mk"`` line:
.. note:: These variables should be set **before** the ``"include .../OpenCV.mk"`` line:
.. code-block:: make
.. code-block:: make
OPENCV_INSTALL_MODULES:=on
OPENCV_INSTALL_MODULES:=on
Copies necessary OpenCV dynamic libs to the project ``libs`` folder in order to include them into the APK.
Copies necessary OpenCV dynamic libs to the project ``libs`` folder in order to include them
into the APK.
.. code-block:: make
...
...
@@ -219,7 +257,8 @@ To build your own Android application, which uses OpenCV from native part, the f
OPENCV_LIB_TYPE:=STATIC
Perform static link with OpenCV. By default dynamic link is used and the project JNI lib depends on ``libopencv_java.so``.
Perform static linking with OpenCV. By default dynamic link is used and the project JNI lib
depends on ``libopencv_java.so``.
#. The file :file:`Application.mk` should exist and should contain lines:
...
...
@@ -228,50 +267,56 @@ To build your own Android application, which uses OpenCV from native part, the f
APP_STL := gnustl_static
APP_CPPFLAGS := -frtti -fexceptions
Also the line like this one:
Also, the line like this one:
.. code-block:: make
APP_ABI := armeabi-v7a
should specify the application target platforms.
Should specify the application target platforms.
In some cases a linkage error (like ``"In function 'cv::toUtf16(std::basic_string<...>...undefinedreferenceto'mbstowcs'"``) happens
when building an application JNI library depending on OpenCV.
The following line in the :file:`Application.mk` usually fixes it:
In some cases a linkage error (like ``"In function 'cv::toUtf16(std::basic_string<...>...
undefinedreferenceto'mbstowcs'"``) happens when building an application JNI library,
depending on OpenCV. The following line in the :file:`Application.mk` usually fixes it:
.. code-block:: make
APP_PLATFORM := android-9
#. Either use :ref:`manual <NDK_build_cli>` ``ndk-build`` invocation or :ref:`setup Eclipse CDT Builder <CDT_Builder>` to build native JNI lib before Java part [re]build and APK creation.
#. Either use :ref:`manual <NDK_build_cli>` ``ndk-build`` invocation or
:ref:`setup Eclipse CDT Builder <CDT_Builder>` to build native JNI lib before (re)building the Java
part and creating an APK.
Hello OpenCV Sample
===================
Here are basic steps to guide you trough the process of creating a simple OpenCV-centric application.
It will be capable of accessing camera output, processing it and displaying the result.
Here are basic steps to guide you trough the process of creating a simple OpenCV-centric
application. It will be capable of accessing camera output, processing it and displaying the
result.
#. Open Eclipse IDE, create a new clean workspace, create a new Android project (*File -> New -> Android Project*).
#. Open Eclipse IDE, create a new clean workspace, create a new Android project
:menuselection:`File --> New --> Android Project`.
#. Set name, target, package and minSDKVersion accordingly.
#. Set name, target, package and ``minSDKVersion`` accordingly.
#. Create a new class (*File -> New -> Class*). Name it for example: *HelloOpenCVView*.
#. Create a new class :menuselection:`File -> New -> Class`. Name it for example:
*HelloOpenCVView*.
.. image:: images/dev_OCV_new_class.png
:alt: Add a new class.
:align: center
* It should extend *SurfaceView* class.
* It also should implement *SurfaceHolder.Callback*, *Runnable*.
* It should extend ``SurfaceView`` class.
* It also should implement ``SurfaceHolder.Callback``, ``Runnable``.
#. Edit *HelloOpenCVView* class.
#. Edit ``HelloOpenCVView`` class.
* Add an *import* line for *android.content.context*.
* Add an ``import`` line for ``android.content.context``.
* Modify autogenerated stubs: *HelloOpenCVView*, *surfaceCreated*, *surfaceDestroyed* and *surfaceChanged*.
* Modify autogenerated stubs: ``HelloOpenCVView``, ``surfaceCreated``, ``surfaceDestroyed`` and
``surfaceChanged``.
.. code-block:: java
:linenos:
...
...
@@ -299,11 +344,9 @@ It will be capable of accessing camera output, processing it and displaying the
cameraSetup(width, height);
}
//...
* Add *cameraOpen*, *cameraRelease* and *cameraSetup* voids as shown below.
* Add ``cameraOpen``, ``cameraRelease`` and ``cameraSetup`` voids as shown below.
* Also, don't forget to add the public void *run()* as follows:
* Also, don't forget to add the public void ``run()`` as follows:
.. code-block:: java
:linenos:
...
...
@@ -324,40 +367,42 @@ It will be capable of accessing camera output, processing it and displaying the
// TODO setup camera
}
#. Create a new *Activity* (*New -> Other -> Android -> Android Activity*) and name it, for example: *HelloOpenCVActivity*. For this activity define *onCreate*, *onResume* and *onPause* voids.
#. Create a new ``Activity`` :menuselection:`New -> Other -> Android -> Android Activity` and name
it, for example: *HelloOpenCVActivity*. For this activity define ``onCreate``, ``onResume`` and
``onPause`` voids.
.. code-block:: java
:linenos:
public void onCreate (Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
mView = new HelloOpenCVView(this);
setContentView (mView);
}
public void onCreate (Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
mView = new HelloOpenCVView(this);
setContentView (mView);
}
protected void onPause() {
super.onPause();
mView.cameraRelease();
}
protected void onPause() {
super.onPause();
mView.cameraRelease();
}
protected void onResume() {
super.onResume();
if( !mView.cameraOpen() ) {
// MessageBox and exit app
AlertDialog ad = new AlertDialog.Builder(this).create();
ad.setCancelable(false); // This blocks the "BACK" button
ad.setMessage("Fatalerror:can't open camera!");
ad.setButton("OK", new DialogInterface.OnClickListener() {
public void onClick(DialogInterface dialog, int which) {
dialog.dismiss();
finish();
}
});
ad.show();
}
}
protected void onResume() {
super.onResume();
if( !mView.cameraOpen() ) {
// MessageBox and exit app
AlertDialog ad = new AlertDialog.Builder(this).create();
ad.setCancelable(false); // This blocks the "BACK" button
ad.setMessage("Fatalerror:can't open camera!");
ad.setButton("OK", new DialogInterface.OnClickListener() {
public void onClick(DialogInterface dialog, int which) {
dialog.dismiss();
finish();
}
});
ad.show();
}
}
#. Add the following permissions to the AndroidManifest.xml file:
#. Add the following permissions to the :file:`AndroidManifest.xml` file:
.. code-block:: xml
:linenos:
...
...
@@ -374,12 +419,12 @@ It will be capable of accessing camera output, processing it and displaying the
:alt: Reference OpenCV library.
:align: center
#. We now need some code to handle the camera. Update the *HelloOpenCVView* class as follows:
#. We now need some code to handle the camera. Update the ``HelloOpenCVView`` class as follows:
.. code-block:: java
:linenos:
private VideoCapture mCamera;
private VideoCapture mCamera;
public boolean cameraOpen() {
synchronized (this) {
...
...
@@ -426,7 +471,7 @@ It will be capable of accessing camera output, processing it and displaying the
}
}
#. The last step would be to update the *run()* void in *HelloOpenCVView* class as follows:
#. The last step would be to update the ``run()`` void in ``HelloOpenCVView`` class as follows:
