generic-library/opencv
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Removed Sphinx documentation files

Browse Source
This commit is contained in:
Maksim Shabunin
2014-12-24 18:37:57 +03:00
parent 61991a3330
commit d01bedbc61
338 changed files with 0 additions and 73040 deletions
Download Patch File Download Diff File Expand all files Collapse all files

341
doc/tutorials/introduction/android_binary_package/O4A_SDK.rst
View File

@@ -1,341 +0,0 @@
.. _O4A_SDK:
OpenCV4Android SDK
******************
This tutorial was designed to help you with installation and configuration of OpenCV4Android SDK.
This guide was written with MS Windows 7 in mind, though it should work with GNU Linux and Apple
Mac OS as well.
This tutorial assumes you have the following software installed and configured:
* JDK
* Android SDK and NDK
* Eclipse IDE
* ADT and CDT plugins for Eclipse
..
If you need help with anything of the above, you may refer to our :ref:`android_dev_intro` guide.
If you encounter any error after thoroughly following these steps, feel free to contact us via
`OpenCV4Android <https://groups.google.com/group/android-opencv/>`_ discussion group or
OpenCV `Q&A forum <http://answers.opencv.org>`_. We'll do our best to help you out.
Tegra Android Development Pack users
====================================
You may have used `Tegra Android Development Pack <http://developer.nvidia.com/tegra-android-development-pack>`_
(**TADP**) released by **NVIDIA** for Android development environment setup.
Beside Android development tools the TADP 2.0 includes OpenCV4Android SDK, so it can be already
installed in your system and you can skip to :ref:`Running_OpenCV_Samples` section of this tutorial.
More details regarding TADP can be found in the :ref:`android_dev_intro` guide.
General info
============
OpenCV4Android SDK package enables development of Android applications with use of OpenCV library.
The structure of package contents looks as follows:
::
OpenCV-2.4.9-android-sdk
|_ apk
| |_ OpenCV_2.4.9_binary_pack_armv7a.apk
| |_ OpenCV_2.4.9_Manager_2.18_XXX.apk
|
|_ doc
|_ samples
|_ sdk
| |_ etc
| |_ java
| |_ native
| |_ 3rdparty
| |_ jni
| |_ libs
| |_ armeabi
| |_ armeabi-v7a
| |_ x86
|
|_ LICENSE
|_ README.android
* :file:`sdk` folder contains OpenCV API and libraries for Android:
* :file:`sdk/java` folder contains an Android library Eclipse project providing OpenCV Java API that
can be imported into developer's workspace;
* :file:`sdk/native` folder contains OpenCV C++ headers (for JNI code) and native Android libraries
(\*\.so and \*\.a) for ARM-v5, ARM-v7a and x86 architectures;
* :file:`sdk/etc` folder contains Haar and LBP cascades distributed with OpenCV.
* :file:`apk` folder contains Android packages that should be installed on the target Android device
to enable OpenCV library access via OpenCV Manager API (see details below).
On production devices that have access to Google Play Market (and Internet) these packages will be
installed from Market on the first start of an application using OpenCV Manager API.
But devkits without Market or Internet connection require this packages to be installed manually.
Install the `Manager.apk` and optional `binary_pack.apk` if it needed.
See :ref:`manager_selection` for details.
.. note:: Installation from Internet is the preferable way since OpenCV team may publish updated
versions of this packages on the Market.
* :file:`samples` folder contains sample applications projects and their prebuilt packages (APK).
Import them into Eclipse workspace (like described below) and browse the code to learn possible
ways of OpenCV use on Android.
* :file:`doc` folder contains various OpenCV documentation in PDF format.
It's also available online at http://docs.opencv.org.
.. note:: The most recent docs (nightly build) are at http://docs.opencv.org/2.4.
Generally, it's more up-to-date, but can refer to not-yet-released functionality.
.. TODO: I'm not sure that this is the best place to talk about OpenCV Manager
Starting from version 2.4.3 `OpenCV4Android SDK` uses `OpenCV Manager` API for library
initialization. `OpenCV Manager` is an Android service based solution providing the following
benefits for OpenCV applications developers:
* Compact apk-size, since all applications use the same binaries from Manager and do not store
native libs within themselves;
* Hardware specific optimizations are automatically enabled on all supported platforms;
* Automatic updates and bug fixes;
* Trusted OpenCV library source. All packages with OpenCV are published on Google Play;
..
For additional information on OpenCV Manager see the:
* |OpenCV4Android_Slides|_
* |OpenCV4Android_Reference|_
..
.. |OpenCV4Android_Slides| replace:: Slides
.. _OpenCV4Android_Slides: https://docs.google.com/a/itseez.com/presentation/d/1EO_1kijgBg_BsjNp2ymk-aarg-0K279_1VZRcPplSuk/present#slide=id.p
.. |OpenCV4Android_Reference| replace:: Reference Manual
.. _OpenCV4Android_Reference: http://docs.opencv.org/android/refman.html
Manual OpenCV4Android SDK setup
===============================
Get the OpenCV4Android SDK
--------------------------
#. Go to the `OpenCV download page on SourceForge <http://sourceforge.net/projects/opencvlibrary/files/opencv-android/>`_
and download the latest available version. Currently it's |opencv_android_bin_pack_url|_.
#. Create a new folder for Android with OpenCV development. For this tutorial we have unpacked
OpenCV SDK to the :file:`C:\\Work\\OpenCV4Android\\` directory.
.. note:: Better to use a path without spaces in it. Otherwise you may have problems with :command:`ndk-build`.
#. Unpack the SDK archive into the chosen directory.
You can unpack it using any popular archiver (e.g with |seven_zip|_):
.. image:: images/android_package_7zip.png
:alt: Exploring OpenCV package with 7-Zip
:align: center
On Unix you can use the following command:
.. code-block:: bash
unzip ~/Downloads/OpenCV-2.4.9-android-sdk.zip
.. |opencv_android_bin_pack| replace:: :file:`OpenCV-2.4.9-android-sdk.zip`
.. _opencv_android_bin_pack_url: http://sourceforge.net/projects/opencvlibrary/files/opencv-android/2.4.9/OpenCV-2.4.9-android-sdk.zip/download
.. |opencv_android_bin_pack_url| replace:: |opencv_android_bin_pack|
.. |seven_zip| replace:: 7-Zip
.. _seven_zip: http://www.7-zip.org/
Import OpenCV library and samples to the Eclipse
------------------------------------------------
#. Start Eclipse and choose your workspace location.
We recommend to start working with OpenCV for Android from a new clean workspace. A new Eclipse
workspace can for example be created in the folder where you have unpacked OpenCV4Android SDK package:
.. image:: images/eclipse_1_choose_workspace.png
:alt: Choosing C:\Work\android-opencv\ as workspace location
:align: center
#. Import OpenCV library and samples into workspace.
OpenCV library is packed as a ready-for-use `Android Library Project
<http://developer.android.com/guide/developing/projects/index.html#LibraryProjects>`_.
You can simply reference it in your projects.
Each sample included into the |opencv_android_bin_pack| is a regular Android project that already
references OpenCV library. Follow the steps below to import OpenCV and samples into the workspace:
.. note:: OpenCV samples are indeed **dependent** on OpenCV library project so don't forget to import it to your workspace as well.
* Right click on the :guilabel:`Package Explorer` window and choose :guilabel:`Import...` option
from the context menu:
.. image:: images/eclipse_5_import_command.png
:alt: Select Import... from context menu
:align: center
* In the main panel select :menuselection:`General --> Existing Projects into Workspace` and
press :guilabel:`Next` button:
.. image:: images/eclipse_6_import_existing_projects.png
:alt: General > Existing Projects into Workspace
:align: center
* In the :guilabel:`Select root directory` field locate your OpenCV package folder. Eclipse
should automatically locate OpenCV library and samples:
.. image:: images/eclipse_7_select_projects.png
:alt: Locate OpenCV library and samples
:align: center
* Click :guilabel:`Finish` button to complete the import operation.
After clicking :guilabel:`Finish` button Eclipse will load all selected projects into workspace,
and you have to wait some time while it is building OpenCV samples. Just give a minute to
Eclipse to complete initialization.
.. warning :: After the initial import, on a non-Windows (Linux and Mac OS) operating system Eclipse
will still show build errors for applications with native C++ code. To resolve the
issues, please do the following:
Open :guilabel:`Project Properties -> C/C++ Build`, and replace "Build command" text
to ``"${NDKROOT}/ndk-build"`` (remove .cmd at the end).
.. note :: In some cases the build errors don't disappear, then try the following actions:
* right click on ``OpenCV Library`` project -> :guilabel:`Android Tools -> Fix Project Properties`,
then menu :guilabel:`Project -> Clean... -> Clean all`
* right click on the project with errors -> :guilabel:`Properties -> Android`, make sure the
``Target`` is selected and is ``Android 3.0`` or higher
* check the build errors in the :guilabel:`Problems` view window and try to resolve them by yourselves
.. image:: images/eclipse_cdt_cfg4.png
:alt: Configure CDT
:align: center
Once Eclipse completes build you will have the clean workspace without any build errors:
.. image:: images/eclipse_10_crystal_clean.png
:alt: OpenCV package imported into Eclipse
:align: center
.. _Running_OpenCV_Samples:
Running OpenCV Samples
----------------------
At this point you should be able to build and run the samples. Keep in mind, that
``face-detection`` and ``Tutorial 2 - Mixed Processing`` include some native code and
require Android NDK and NDK/CDT plugin for Eclipse to build working applications. If you haven't
installed these tools, see the corresponding section of :ref:`Android_Dev_Intro`.
.. warning:: Please consider that some samples use Android Java Camera API, which is accessible
with an AVD. But most of samples use OpenCV Native Camera which **may not work** with
an emulator.
.. note:: Recent *Android SDK tools, revision 19+* can run ARM v7a OS images but they available not
for all Android versions.
Well, running samples from Eclipse is very simple:
* Connect your device with :command:`adb` tool from Android SDK or create an emulator with camera support.
* See `Managing Virtual Devices
<http://developer.android.com/guide/developing/devices/index.html>`_ document for help with Android Emulator.
* See `Using Hardware Devices
<http://developer.android.com/guide/developing/device.html>`_ for help with real devices (not emulators).
* Select project you want to start in :guilabel:`Package Explorer` and just press :kbd:`Ctrl + F11`
or select option :menuselection:`Run --> Run` from the main menu, or click :guilabel:`Run` button on the toolbar.
.. note:: Android Emulator can take several minutes to start. So, please, be patient.
* On the first run Eclipse will ask you about the running mode for your application:
.. image:: images/eclipse_11_run_as.png
:alt: Run sample as Android Application
:align: center
* Select the :guilabel:`Android Application` option and click :guilabel:`OK` button. Eclipse will install and run the sample.
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.
In this case you will see the following message:
.. image:: images/android_emulator_opencv_manager_fail.png
:alt: You will see this message if you have no OpenCV Manager installed
:align: center
To get rid of the message you will need to install `OpenCV Manager` and the appropriate `OpenCV binary pack`.
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*.
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.
.. code-block:: sh
:linenos:
<Android SDK path>/platform-tools/adb install <OpenCV4Android SDK path>/apk/OpenCV_2.4.9_Manager_2.18_armv7a-neon.apk
.. note:: ``armeabi``, ``armv7a-neon``, ``arm7a-neon-android8``, ``mips`` and ``x86`` stand for
platform targets:
* ``armeabi`` is for ARM v5 and ARM v6 architectures with Android API 8+,
* ``armv7a-neon`` is for NEON-optimized ARM v7 with Android API 9+,
* ``arm7a-neon-android8`` is for NEON-optimized ARM v7 with Android API 8,
* ``mips`` is for MIPS architecture with Android API 9+,
* ``x86`` is for Intel x86 CPUs with Android API 9+.
If using hardware device for testing/debugging, run the following command to learn
its CPU architecture:
.. code-block:: sh
adb shell getprop ro.product.cpu.abi
If you're using an AVD emulator, go :menuselection:`Window > AVD Manager` to see the
list of availible devices. Click :menuselection:`Edit` in the context menu of the
selected device. In the window, which then pop-ups, find the CPU field.
You may also see section :ref:`manager_selection` for details.
When done, you will be able to run OpenCV samples on your device/emulator seamlessly.
* Here is ``Sample - image-manipulations`` sample, running on top of stock camera-preview of the emulator.
.. image:: images/emulator_canny.png
:alt: 'Sample - image-manipulations' running Canny
:align: center
What's next
===========
Now, when you have your instance of OpenCV4Adroid SDK set up and configured,
you may want to proceed to using OpenCV in your own application.
You can learn how to do that in a separate :ref:`dev_with_OCV_on_Android` tutorial.

655
doc/tutorials/introduction/android_binary_package/android_dev_intro.rst
View File

@@ -1,655 +0,0 @@
.. _Android_Dev_Intro:
Introduction into Android Development
*************************************
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 <https://groups.google.com/group/android-opencv/>`_ discussion group or
OpenCV `Q&A forum <http://answers.opencv.org>`_. We'll do our best to help you out.
Preface
=======
Android is a Linux-based, open source mobile operating system developed by Open Handset Alliance
led by Google. See the `Android home site <http://www.android.com/about/>`_ 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:
#. `Java <http://en.wikipedia.org/wiki/Java_(programming_language)>`_ programming language that is
the primary development technology for Android OS. Also, you can find
`Oracle docs on Java <http://docs.oracle.com/javase/>`_ useful.
#. `Java Native Interface (JNI) <http://en.wikipedia.org/wiki/Java_Native_Interface>`_ that is a
technology of running native code in Java virtual machine. Also, you can find
`Oracle docs on JNI <http://docs.oracle.com/javase/7/docs/technotes/guides/jni/>`_ useful.
#. `Android Activity <http://developer.android.com/training/basics/activity-lifecycle/starting.html>`_
and its lifecycle, that is an essential Android API class.
#. OpenCV development will certainly require some knowlege of the
`Android Camera <http://developer.android.com/guide/topics/media/camera.html>`_ specifics.
Quick environment setup for Android development
===============================================
If you are making a clean environment install, then you can try `Tegra Android Development Pack <https://developer.nvidia.com/tegra-android-development-pack>`_
(**TADP**) released by **NVIDIA**.
.. note:: Starting the *version 2.0* the TADP package includes *OpenCV for Tegra* SDK that is a regular *OpenCV4Android SDK* extended with Tegra-specific stuff.
When unpacked, TADP will cover all of the environment setup automatically and you can skip the rest of the guide.
If you are a beginner in Android development then we also recommend you to start with TADP.
.. note:: *NVIDIA*\ 's Tegra Android Development Pack includes some special features for
|Nvidia_Tegra_Platform|_ but its use is not limited to *Tegra* devices only.
* You need at least *1.6 Gb* free disk space for the install.
* TADP will download Android SDK platforms and Android NDK from Google's server, so Internet
connection is required for the installation.
* TADP may ask you to flash your development kit at the end of installation process. Just skip
this step if you have no |Tegra_Development_Kit|_\ .
* (``UNIX``) TADP will ask you for *root* in the middle of installation, so you need to be a
member of *sudo* group.
..
.. |Nvidia_Tegra_Platform| replace:: *NVIDIA*\ ’s Tegra platform
.. _Nvidia_Tegra_Platform: http://www.nvidia.com/object/tegra-3-processor.html
.. |Tegra_Development_Kit| replace:: Tegra Development Kit
.. _Tegra_Development_Kit: http://developer.nvidia.com/mobile/tegra-hardware-sales-inquiries
.. _Android_Environment_Setup_Lite:
Manual environment setup for Android development
================================================
Development in Java
-------------------
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 <http://www.oracle.com/technetwork/java/javase/downloads/>`_
and download an installer for your OS.
Here is a detailed :abbr:`JDK (Java Development Kit)`
`installation guide <http://source.android.com/source/initializing.html#installing-the-jdk>`_
for Ubuntu and Mac OS (only JDK sections are applicable for OpenCV)
.. note:: OpenJDK is not suitable for Android development, since Android SDK supports only Sun JDK.
If you use Ubuntu, after installation of Sun JDK you should run the following command to set
Sun java environment:
.. code-block:: bash
sudo update-java-alternatives --set java-6-sun
.. TODO: Add a note on Sun/Oracle Java installation on Ubuntu 12.
#. **Android SDK**
Get the latest ``Android SDK`` from http://developer.android.com/sdk/index.html
Here is Google's `install guide <http://developer.android.com/sdk/installing.html>`_ for the SDK.
.. note:: You can choose downloading **ADT Bundle package** that in addition to Android SDK Tools includes
Eclipse + ADT + NDK/CDT plugins, Android Platform-tools, the latest Android platform and the latest
Android system image for the emulator - this is the best choice for those who is setting up Android
development environment the first time!
.. note:: If you are running x64 version of Ubuntu Linux, then you need ia32 shared libraries
for use on amd64 and ia64 systems to be installed. You can install them with the
following command:
.. code-block:: bash
sudo apt-get install ia32-libs
For Red Hat based systems the following command might be helpful:
.. code-block:: bash
sudo yum install libXtst.i386
#. **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.
.. image:: images/android_sdk_and_avd_manager.png
:alt: Android SDK Manager
:align: center
See `Adding Platforms and Packages <http://developer.android.com/sdk/installing/adding-packages.html>`_
for help with installing/updating SDK components.
#. **Eclipse IDE**
Check the `Android SDK System Requirements <http://developer.android.com/sdk/requirements.html>`_
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 <http://www.eclipse.org/downloads/>`_.
#. **ADT plugin for Eclipse**
These instructions are copied from
`Android Developers site <http://developer.android.com/sdk/installing/installing-adt.html>`_,
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:
#. Start Eclipse, then select :menuselection:`Help --> Install New Software...`
#. Click :guilabel:`Add` (in the top-right corner).
#. In the :guilabel:`Add Repository` dialog that appears, enter "ADT Plugin" for the Name and the
following URL for the Location:
https://dl-ssl.google.com/android/eclipse/
#. Click :guilabel:`OK`
.. note:: If you have trouble acquiring the plugin, try using "http" in the Location URL,
instead of "https" (https is preferred for security reasons).
#. In the :guilabel:`Available Software` dialog, select the checkbox next to
:guilabel:`Developer Tools` and click :guilabel:`Next`.
#. In the next window, you'll see a list of the tools to be downloaded. Click :guilabel:`Next`.
.. note:: If you also plan to develop native C++ code with Android NDK don't forget to
enable `NDK Plugins` installations as well.
.. image:: images/eclipse_inst_adt.png
:alt: ADT installation
:align: center
#. Read and accept the license agreements, then click :guilabel:`Finish`.
.. note:: If you get a security warning saying that the authenticity or validity of the software
can't be established, click :guilabel:`OK`.
#. When the installation completes, restart Eclipse.
Native development in C++
-------------------------
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 <http://developer.android.com/tools/sdk/ndk/index.html>`_.
To install Android NDK just extract the archive to some folder on your computer. Here are
`installation instructions <http://developer.android.com/tools/sdk/ndk/index.html#Installing>`_.
.. note:: Before start you can read official Android NDK documentation which is in the Android
NDK archive, in the folder :file:`docs/`.
The main article about using Android NDK build system is in the :file:`ANDROID-MK.html` file.
Some additional information you can find in
the :file:`APPLICATION-MK.html`, :file:`NDK-BUILD.html` files,
and :file:`CPU-ARM-NEON.html`, :file:`CPLUSPLUS-SUPPORT.html`, :file:`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
:abbr:`CDT(C/C++ Development Tooling)` Builder.
Android application structure
=============================
Usually source code of an Android application has the following structure:
+ :file:`root folder of the project/`
- :file:`jni/`
- :file:`libs/`
- :file:`res/`
- :file:`src/`
- :file:`AndroidManifest.xml`
- :file:`project.properties`
- :file:`... other files ...`
Where:
* the :file:`src` folder contains Java code of the application,
* the :file:`res` folder contains resources of the application (images, xml files describing UI
layout, etc),
* the :file:`libs` folder will contain native libraries after a successful build,
* and the :file:`jni` folder contains C/C++ application source code and NDK's build scripts
:file:`Android.mk` and :file:`Application.mk` producing the native libraries,
* :file:`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 :command:`android` tool from Android SDK.
* :file:`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
:command:`android` tool included in Android SDK.
.. note:: Both :file:`AndroidManifest.xml` and :file:`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.
:file:`Android.mk` and :file:`Application.mk` scripts
==================================================================
The script :file:`Android.mk` usually has the following structure:
.. code-block:: make
:linenos:
LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := <module_name>
LOCAL_SRC_FILES := <list of .c and .cpp project files>
<some variable name> := <some variable value>
...
<some variable name> := <some variable value>
include $(BUILD_SHARED_LIBRARY)
This is the minimal file :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 :file:`Android.mk`.
Usually the file :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 :file:`Application.mk`:
.. code-block:: make
:linenos:
APP_STL := gnustl_static
APP_CPPFLAGS := -frtti -fexceptions
APP_ABI := all
.. note:: We recommend setting ``APP_ABI := all`` for all targets. If you want to specify the
target explicitly, use ``armeabi`` for ARMv5/ARMv6, ``armeabi-v7a`` for ARMv7, ``x86``
for Intel Atom or ``mips`` for MIPS.
.. _NDK_build_cli:
Building application native part from command line
==================================================
Here is the standard way to compile C++ part of an Android application:
.. warning:: We strongly reccomend 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.
#. Open console and go to the root folder of an Android application
.. code-block:: bash
cd <root folder of the project>/
#. Run the following command
.. code-block:: bash
<path_where_NDK_is_placed>/ndk-build
.. note:: On Windows we recommend to use ``ndk-build.cmd`` in standard Windows console (``cmd.exe``)
rather than the similar ``bash`` script in ``Cygwin`` shell.
.. image:: images/ndk_build.png
:alt: NDK build
:align: center
#. After executing this command the C++ part of the source code is compiled.
After that the Java part of the application can be (re)compiled (using either *Eclipse* or *Ant* build tool).
.. note:: Some parameters can be set for the :command:`ndk-build`:
**Example 1**: Verbose compilation
.. code-block:: bash
<path_where_NDK_is_placed>/ndk-build V=1
**Example 2**: Rebuild all
.. code-block:: bash
<path_where_NDK_is_placed>/ndk-build -B
.. _CDT_Builder:
Building application native part from *Eclipse* (CDT Builder)
=============================================================
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
:abbr:`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
:guilabel:`My Computer -> Properties -> Advanced -> Environment variables`.
On Windows 7 it's also possible to use `setx <http://ss64.com/nt/setx.html>`_ 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 :file:`"~/.bashrc"` file and logging off and then on.
.. note:: It's also possible to define the ``NDKROOT`` environment variable within Eclipse IDE,
but it should be done for every new workspace you create. If you prefer this option better than setting system
environment variable, open Eclipse menu :guilabel:`Window -> Preferences -> C/C++ -> Build -> Environment`,
press the :guilabel:`Add...` button and set variable name to ``NDKROOT`` and value to local Android NDK path.
#. After that you need to **restart Eclipse** to apply the changes.
#. Open Eclipse and load the Android app project to configure.
#. Add C/C++ Nature to the project via Eclipse menu :guilabel:`New -> Other -> C/C++ -> Convert to a C/C++ Project`.
.. image:: images/eclipse_cdt_cfg1.png
:alt: Configure CDT
:align: center
And:
.. image:: images/eclipse_cdt_cfg2.png
:alt: Configure CDT
:align: center
#. Select the project(s) to convert. Specify "Project type" = ``Makefile project``,
"Toolchains" = ``Other Toolchain``.
.. image:: images/eclipse_cdt_cfg3.png
:alt: Configure CDT
:align: center
#. Open :guilabel:`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.
.. image:: images/eclipse_cdt_cfg4.png
:alt: Configure CDT
:align: center
#. Go to :guilabel:`Behaviour` tab and change "Workbench build type" section like shown below:
.. image:: images/eclipse_cdt_cfg5.png
:alt: Configure CDT
:align: center
#. Press :guilabel:`OK` and make sure the ``ndk-build`` is successfully invoked when building the project.
.. image:: images/eclipse_cdt_cfg6.png
:alt: Configure CDT
:align: center
#. 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.
.. image:: images/eclipse_cdt_cfg7.png
:alt: Configure CDT
:align: center
#. Open :guilabel:`Project Properties -> C/C++ General -> Paths and Symbols` and add the following
**Include** paths for **C++**:
::
# for NDK r8 and prior:
${NDKROOT}/platforms/android-9/arch-arm/usr/include
${NDKROOT}/sources/cxx-stl/gnu-libstdc++/include
${NDKROOT}/sources/cxx-stl/gnu-libstdc++/libs/armeabi-v7a/include
${ProjDirPath}/../../sdk/native/jni/include
::
# for NDK r8b and later:
${NDKROOT}/platforms/android-9/arch-arm/usr/include
${NDKROOT}/sources/cxx-stl/gnu-libstdc++/4.6/include
${NDKROOT}/sources/cxx-stl/gnu-libstdc++/4.6/libs/armeabi-v7a/include
${ProjDirPath}/../../sdk/native/jni/include
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.
.. image:: images/eclipse_cdt_cfg8.png
:alt: Configure CDT
:align: center
Debugging and Testing
=====================
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
---
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.
#. Assuming you already have *Android SDK* and *Eclipse IDE* installed, in Eclipse go
:guilabel:`Window -> AVD Manager`.
.. TODO: how to start AVD Manager without Eclipse...
#. Press the :guilabel:`New` button in :guilabel:`AVD Manager` window.
#. :guilabel:`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.
.. image:: images/AVD_create.png
:alt: Configure builders
:align: center
#. When you click the :guilabel:`Create AVD` button, your new AVD will be availible in :guilabel:`AVD Manager`.
#. Press :guilabel:`Start` to launch the device. Be aware that any AVD (a.k.a. Emulator) is usually
much slower than a hardware Android device, so it may take up to several minutes to start.
#. Go :guilabel:`Run -> Run/Debug` in Eclipse IDE to run your application in regular or debugging
mode. :guilabel:`Device Chooser` will let you choose among the running devices or to start a new one.
Hardware Device
---------------
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 <http://developer.android.com/tools/device.html>`_
for more information.
Windows host computer
^^^^^^^^^^^^^^^^^^^^^
#. Enable USB debugging on the Android device (via :guilabel:`Settings` menu).
#. Attach the Android device to your PC with a USB cable.
#. Go to :guilabel:`Start Menu` and **right-click** on :guilabel:`Computer`.
Select :guilabel:`Manage` in the context menu. You may be asked for Administrative permissions.
#. Select :guilabel:`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.
.. image:: images/usb_device_connect_01.png
:alt: Unknown device
:align: center
#. Try your luck installing `Google USB drivers` without any modifications: **right-click** on the
unknown device, select :guilabel:`Properties` menu item --> :guilabel:`Details` tab -->
:guilabel:`Update Driver` button.
.. image:: images/usb_device_connect_05.png
:alt: Device properties
:align: center
#. Select :guilabel:`Browse computer for driver software`.
.. image:: images/usb_device_connect_06.png
:alt: Browse for driver
:align: center
#. Specify the path to :file:`<Android SDK folder>/extras/google/usb_driver/` folder.
.. image:: images/usb_device_connect_07.png
:alt: Browse for driver
:align: center
#. If you get the prompt to install unverified drivers and report about success - you've finished
with USB driver installation.
.. image:: images/usb_device_connect_08.png
:alt: Install prompt
:align: center
` `
.. FIXME: All such places should be replaced with something else! This is a bad separator.
.. image:: images/usb_device_connect_09.png
:alt: Installed OK
:align: center
#. Otherwise (getting the failure like shown below) follow the next steps.
.. image:: images/usb_device_connect_12.png
:alt: No driver
:align: center
#. Again **right-click** on the unknown device, select :guilabel:`Properties --> Details --> Hardware Ids`
and copy the line like ``USB\VID_XXXX&PID_XXXX&MI_XX``.
.. image:: images/usb_device_connect_02.png
:alt: Device properties details
:align: center
#. Now open file :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.
.. image:: images/usb_device_connect_03.png
:alt: "android_winusb.inf"
:align: center
#. There should be a record like existing ones for your device and you need to add one manually.
.. image:: images/usb_device_connect_04.png
:alt: "android_winusb.inf"
:align: center
#. Save the :file:`android_winusb.inf` file and try to install the USB driver again.
.. image:: images/usb_device_connect_05.png
:alt: Device properties
:align: center
` `
.. image:: images/usb_device_connect_06.png
:alt: Browse for driver
:align: center
` `
.. image:: images/usb_device_connect_07.png
:alt: Browse for driver
:align: center
#. This time installation should go successfully.
.. image:: images/usb_device_connect_08.png
:alt: Install prompt
:align: center
` `
.. image:: images/usb_device_connect_09.png
:alt: Installed OK
:align: center
#. And an unknown device is now recognized as an Android phone.
.. image:: images/usb_device_connect_10.png
:alt: "Known" device
:align: center
#. Successful device USB connection can be verified in console via ``adb devices`` command.
.. image:: images/usb_device_connect_11.png
:alt: "adb devices"
:align: center
#. Now, in Eclipse go :guilabel:`Run -> Run/Debug` to run your application in regular or debugging
mode. :guilabel:`Device Chooser` will let you choose among the devices.
Linux host computer
^^^^^^^^^^^^^^^^^^^
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 <http://developer.android.com/tools/device.html#VendorIds>`_ or execute :command:`lsusb`
command to view VendorID of plugged Android device. Here is an example of such file for LG device:
.. code-block:: guess
SUBSYSTEM=="usb", ATTR{idVendor}=="1004", MODE="0666", GROUP="plugdev"
Then restart your adb server (even better to restart the system), plug in your Android device and
execute :command:`adb devices` command. You will see the list of attached devices:
.. image:: images/usb_device_connect_ubuntu.png
:alt: List of attached devices
:align: center
Mac OS host computer
^^^^^^^^^^^^^^^^^^^^
No actions are required, just connect your device via USB and run ``adb devices`` to check connection.
What's next
===========
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 :ref:`O4A_SDK` tutorial.

460
doc/tutorials/introduction/android_binary_package/dev_with_OCV_on_Android.rst
View File

@@ -1,460 +0,0 @@
.. _dev_with_OCV_on_Android:
Android Development with OpenCV
*******************************
This tutorial has been created to help you use OpenCV library within your Android project.
This guide was written with Windows 7 in mind, though it should work with any other OS supported by
OpenCV4Android SDK.
This tutorial assumes you have the following installed and configured:
* JDK
* Android SDK and NDK
* Eclipse IDE
* ADT and CDT plugins for Eclipse
..
If you need help with anything of the above, you may refer to our :ref:`android_dev_intro` guide.
This tutorial also assumes you have OpenCV4Android SDK already installed on your development
machine and OpenCV Manager on your testing device correspondingly. If you need help with any of
these, you may consult our :ref:`O4A_SDK` tutorial.
If you encounter any error after thoroughly following these steps, feel free to contact us via
`OpenCV4Android <https://groups.google.com/group/android-opencv/>`_ discussion group or OpenCV
`Q&A forum <http://answers.opencv.org>`_ . We'll do our best to help you out.
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>`_.
Java
----
Application Development with Async Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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`.
Press :guilabel:`Browse` button and locate OpenCV4Android SDK
(:file:`OpenCV-2.4.9-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.9``.
.. image:: images/eclipse_opencv_dependency1.png
:alt: Add dependency from OpenCV library
:align: center
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.
.. code-block:: java
:linenos:
public class Sample1Java extends Activity implements CvCameraViewListener {
private BaseLoaderCallback mLoaderCallback = new BaseLoaderCallback(this) {
@Override
public void onManagerConnected(int status) {
switch (status) {
case LoaderCallbackInterface.SUCCESS:
{
Log.i(TAG, "OpenCV loaded successfully");
mOpenCvCameraView.enableView();
} break;
default:
{
super.onManagerConnected(status);
} break;
}
}
};
@Override
public void onResume()
{
super.onResume();
OpenCVLoader.initAsync(OpenCVLoader.OPENCV_VERSION_2_4_6, this, mLoaderCallback);
}
...
}
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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`,
press :guilabel:`Browse` button and select OpenCV SDK path
(:file:`OpenCV-2.4.9-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.9``;
.. image:: images/eclipse_opencv_dependency1.png
:alt: Add dependency from OpenCV library
:align: center
#. If your application project **doesn't have a JNI part**, just copy the corresponding OpenCV
native libs from :file:`<OpenCV-2.4.9-android-sdk>/sdk/native/libs/<target_arch>` to your
project directory to folder :file:`libs/<target_arch>`.
In case of the application project **with a JNI part**, instead of manual libraries copying you
need to modify your ``Android.mk`` file:
add the following two code lines after the ``"include $(CLEAR_VARS)"`` and before
``"include path_to_OpenCV-2.4.9-android-sdk/sdk/native/jni/OpenCV.mk"``
.. code-block:: make
:linenos:
OPENCV_CAMERA_MODULES:=on
OPENCV_INSTALL_MODULES:=on
The result should look like the following:
.. code-block:: make
:linenos:
include $(CLEAR_VARS)
# OpenCV
OPENCV_CAMERA_MODULES:=on
OPENCV_INSTALL_MODULES:=on
include ../../sdk/native/jni/OpenCV.mk
After that the OpenCV libraries will be copied to your application :file:`libs` folder during
the JNI build.v
Eclipse will automatically include all the libraries from the :file:`libs` folder to the
application package (APK).
#. The last step of enabling OpenCV in your application is Java initialization code before calling
OpenCV API. It can be done, for example, in the static section of the ``Activity`` class:
.. code-block:: java
:linenos:
static {
if (!OpenCVLoader.initDebug()) {
// Handle initialization error
}
}
If you application includes other OpenCV-dependent native libraries you should load them
**after** OpenCV initialization:
.. code-block:: java
:linenos:
static {
if (!OpenCVLoader.initDebug()) {
// Handle initialization error
} else {
System.loadLibrary("my_jni_lib1");
System.loadLibrary("my_jni_lib2");
}
}
Native/C++
----------
To build your own Android application, using OpenCV as native part, the following steps should be
taken:
#. You can use an environment variable to specify the location of OpenCV package or just hardcode
absolute or relative path in the :file:`jni/Android.mk` of your projects.
#. The file :file:`jni/Android.mk` should be written for the current application using the common
rules for this file.
For detailed information see the Android NDK documentation from the Android NDK archive, in the
file :file:`<path_where_NDK_is_placed>/docs/ANDROID-MK.html`.
#. The following line:
.. code-block:: make
include C:\Work\OpenCV4Android\OpenCV-2.4.9-android-sdk\sdk\native\jni\OpenCV.mk
Should be inserted into the :file:`jni/Android.mk` file **after** this line:
.. code-block:: make
include $(CLEAR_VARS)
#. Several variables can be used to customize OpenCV stuff, but you **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:
.. code-block:: make
OPENCV_INSTALL_MODULES:=on
Copies necessary OpenCV dynamic libs to the project ``libs`` folder in order to include them
into the APK.
.. code-block:: make
OPENCV_CAMERA_MODULES:=off
Skip native OpenCV camera related libs copying to the project ``libs`` folder.
.. code-block:: make
OPENCV_LIB_TYPE:=STATIC
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:
.. code-block:: make
APP_STL := gnustl_static
APP_CPPFLAGS := -frtti -fexceptions
Also, the line like this one:
.. code-block:: make
APP_ABI := armeabi-v7a
Should specify the application target platforms.
In some cases a linkage error (like ``"In function 'cv::toUtf16(std::basic_string<...>...
undefined reference to '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 (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.
#. 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. The minimal SDK version for build
with OpenCV4Android SDK is 11. Minimal device API Level (for application manifest) is 8.
#. Allow Eclipse to create default activity. Lets name the activity ``HelloOpenCvActivity``.
#. Choose Blank Activity with full screen layout. Lets name the layout ``HelloOpenCvLayout``.
#. Import OpenCV library project to your workspace.
#. Reference OpenCV library within your project properties.
.. image:: images/dev_OCV_reference.png
:alt: Reference OpenCV library.
:align: center
#. Edit your layout file as xml file and pass the following layout there:
.. code-block:: xml
:linenos:
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
xmlns:opencv="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent"
android:layout_height="match_parent" >
<org.opencv.android.JavaCameraView
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:visibility="gone"
android:id="@+id/HelloOpenCvView"
opencv:show_fps="true"
opencv:camera_id="any" />
</LinearLayout>
#. Add the following permissions to the :file:`AndroidManifest.xml` file:
.. code-block:: xml
:linenos:
</application>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-feature android:name="android.hardware.camera" android:required="false"/>
<uses-feature android:name="android.hardware.camera.autofocus" android:required="false"/>
<uses-feature android:name="android.hardware.camera.front" android:required="false"/>
<uses-feature android:name="android.hardware.camera.front.autofocus" android:required="false"/>
#. Set application theme in AndroidManifest.xml to hide title and system buttons.
.. code-block:: xml
:linenos:
<application
android:icon="@drawable/icon"
android:label="@string/app_name"
android:theme="@android:style/Theme.NoTitleBar.Fullscreen" >
#. Add OpenCV library initialization to your activity. Fix errors by adding requited imports.
.. code-block:: java
:linenos:
private BaseLoaderCallback mLoaderCallback = new BaseLoaderCallback(this) {
@Override
public void onManagerConnected(int status) {
switch (status) {
case LoaderCallbackInterface.SUCCESS:
{
Log.i(TAG, "OpenCV loaded successfully");
mOpenCvCameraView.enableView();
} break;
default:
{
super.onManagerConnected(status);
} break;
}
}
};
@Override
public void onResume()
{
super.onResume();
OpenCVLoader.initAsync(OpenCVLoader.OPENCV_VERSION_2_4_6, this, mLoaderCallback);
}
#. Defines that your activity implements ``CvCameraViewListener2`` interface and fix activity related
errors by defining missed methods. For this activity define ``onCreate``, ``onDestroy`` and
``onPause`` and implement them according code snippet bellow. Fix errors by adding requited
imports.
.. code-block:: java
:linenos:
private CameraBridgeViewBase mOpenCvCameraView;
@Override
public void onCreate(Bundle savedInstanceState) {
Log.i(TAG, "called onCreate");
super.onCreate(savedInstanceState);
getWindow().addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON);
setContentView(R.layout.HelloOpenCvLayout);
mOpenCvCameraView = (CameraBridgeViewBase) findViewById(R.id.HelloOpenCvView);
mOpenCvCameraView.setVisibility(SurfaceView.VISIBLE);
mOpenCvCameraView.setCvCameraViewListener(this);
}
@Override
public void onPause()
{
super.onPause();
if (mOpenCvCameraView != null)
mOpenCvCameraView.disableView();
}
public void onDestroy() {
super.onDestroy();
if (mOpenCvCameraView != null)
mOpenCvCameraView.disableView();
}
public void onCameraViewStarted(int width, int height) {
}
public void onCameraViewStopped() {
}
public Mat onCameraFrame(CvCameraViewFrame inputFrame) {
return inputFrame.rgba();
}
#. Run your application on device or emulator.
Lets discuss some most important steps. Every Android application with UI must implement Activity
and View. By the first steps we create blank activity and default view layout. The simplest
OpenCV-centric application must implement OpenCV initialization, create its own view to show
preview from camera and implements ``CvCameraViewListener2`` interface to get frames from camera and
process it.
First of all we create our application view using xml layout. Our layout consists of the only
one full screen component of class ``org.opencv.android.JavaCameraView``. This class is
implemented inside OpenCV library. It is inherited from ``CameraBridgeViewBase``, that extends
``SurfaceView`` and uses standard Android camera API. Alternatively you can use
``org.opencv.android.NativeCameraView`` class, that implements the same interface, but uses
``VideoCapture`` class as camera access back-end. ``opencv:show_fps="true"`` and
``opencv:camera_id="any"`` options enable FPS message and allow to use any camera on device.
Application tries to use back camera first.
After creating layout we need to implement ``Activity`` class. OpenCV initialization process has
been already discussed above. In this sample we use asynchronous initialization. Implementation of
``CvCameraViewListener`` interface allows you to add processing steps after frame grabbing from
camera and before its rendering on screen. The most important function is ``onCameraFrame``. It is
callback function and it is called on retrieving frame from camera. The callback input is object
of ``CvCameraViewFrame`` class that represents frame from camera.
.. note::
Do not save or use ``CvCameraViewFrame`` object out of ``onCameraFrame`` callback. This object
does not have its own state and its behavior out of callback is unpredictable!
It has ``rgba()`` and ``gray()`` methods that allows to get frame as RGBA and one channel gray scale
``Mat`` respectively. It expects that ``onCameraFrame`` function returns RGBA frame that will be
drawn on the screen.