android -> plarforms/android

platforms/android/service/doc/BaseLoaderCallback.rst

@@ -0,0 +1,63 @@
+*********************************************
+Base Loader Callback Interface Implementation
+*********************************************
+
+.. highlight:: java
+.. class:: BaseLoaderCallback
+
+    Basic implementation of ``LoaderCallbackInterface``. Logic of this implementation is
+    well-described by the following scheme:
+
+.. image:: img/AndroidAppUsageModel.png
+
+Using in Java Activity
+----------------------
+
+There is a very base code snippet implementing the async initialization with ``BaseLoaderCallback``.
+See the "15-puzzle" OpenCV sample for details.
+
+.. code-block:: java
+    :linenos:
+
+    public class MyActivity extends Activity implements HelperCallbackInterface
+    {
+    private BaseLoaderCallback mOpenCVCallBack = new BaseLoaderCallback(this) {
+       @Override
+       public void onManagerConnected(int status) {
+         switch (status) {
+           case LoaderCallbackInterface.SUCCESS:
+           {
+              Log.i(TAG, "OpenCV loaded successfully");
+              // Create and set View
+              mView = new puzzle15View(mAppContext);
+              setContentView(mView);
+           } break;
+           default:
+           {
+              super.onManagerConnected(status);
+           } break;
+         }
+       }
+    };
+
+    /** Call on every application resume **/
+    @Override
+    protected void onResume()
+    {
+        Log.i(TAG, "Called onResume");
+        super.onResume();
+
+        Log.i(TAG, "Trying to load OpenCV library");
+        if (!OpenCVLoader.initAsync(OpenCVLoader.OPENCV_VERSION_2_4_4, this, mOpenCVCallBack))
+        {
+            Log.e(TAG, "Cannot connect to OpenCV Manager");
+        }
+    }
+
+Using in Service
+----------------
+
+Default ``BaseLoaderCallback`` implementation treats 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.

platforms/android/service/doc/InstallCallbackInterface.rst

@@ -0,0 +1,38 @@
+**************************
+Install Callback Interface
+**************************
+.. highlight:: java
+.. class:: InstallCallbackInterface
+
+    Callback interface for package installation or update.
+
+String getPackageName()
+-----------------------
+
+.. method:: String getPackageName()
+
+    Get name of a package to be installed.
+
+    :rtype: string;
+    :return: returns package name, i.e. "OpenCV Manager Service" or "OpenCV library".
+
+void install()
+--------------
+
+.. method:: void install()
+
+    Installation of package has been approved.
+
+void cancel()
+-------------
+
+.. method:: void cancel()
+
+    Installation of package has been cancelled.
+
+void wait_install()
+-------------------
+
+.. method:: void wait_install()
+
+    Wait for package installation.

platforms/android/service/doc/Intro.rst

@@ -0,0 +1,44 @@
+
+.. _Android_OpenCV_Manager_Intro:
+
+************
+Introduction
+************
+
+.. highlight:: java
+
+OpenCV Manager is an Android service targeted to manage OpenCV library binaries on end users devices.
+It allows sharing the OpenCV dynamic libraries between applications on the same device. The Manager
+provides the following benefits\:
+
+#. Less memory usage. All apps use the same binaries from service and do not keep native libs inside themselves;
+#. Hardware specific optimizations for all supported platforms;
+#. Trusted OpenCV library source. All packages with OpenCV are published on Google Play market;
+#. Regular updates and bug fixes;
+
+Usage model for end user
+------------------------
+
+.. image:: img/AndroidAppUsageModel.png
+
+First OpenCV app\:
+
+#. Any OpenCV-dependent app is installed from Google Play marketplace or manually;
+#. At the first launch, it suggests installation of OpenCV Manager;
+#. Then OpenCV Manager is downloaded and installed, using the Google Play application.
+#. When Manager has been started, the application suggests installation of OpenCV library for the
+   target device architecture if it is necessary;
+#. After the installation is finished, the app may be launched.
+
+Subsequent launches of OpenCV apps\:
+
+#. Any OpenCV-dependent app is installed from Google Play market or manually;
+#. At the first launch, the app starts as usually;
+#. If the selected OpenCV version is not installed, OpenCV Manager suggests installing OpenCV
+   library for the target device through Google Play marketplace;
+#. After the installation is finished, the app may be launched.
+
+Architecture of OpenCV Manager
+------------------------------
+
+.. image:: img/Structure.png

platforms/android/service/doc/JavaHelper.rst

@@ -0,0 +1,57 @@
+******************
+Java OpenCV Loader
+******************
+
+.. highlight:: java
+.. Class:: OpenCVLoader
+
+Helper class provides common initialization methods for OpenCV library.
+
+boolean initDebug()
+-------------------
+
+.. method:: static boolean initDebug()
+
+    Loads and initializes OpenCV library from within current application package. Roughly it is
+    analog of ``system.loadLibrary("opencv_java")``.
+
+    :rtype: boolean;
+    :return: returns true if initialization of OpenCV was successful.
+
+.. note:: This method is deprecated for production code. It is designed for experimental and local
+          development purposes only. If you want to publish your app use approach with async
+          initialization.
+
+boolean initAsync()
+-------------------
+
+.. method:: static boolean initAsync(String Version, Context AppContext, LoaderCallbackInterface Callback)
+
+    Loads and initializes OpenCV library using OpenCV Manager.
+
+    :param Version: OpenCV Library version.
+    :param AppContext: application context for connecting to the service.
+    :param Callback: object, that implements ``LoaderCallbackInterface`` for handling connection
+                     status (see ``BaseLoaderCallback``).
+
+    :rtype: boolean;
+    :return: returns true if initialization of OpenCV starts successfully.
+
+OpenCV version constants
+-------------------------
+
+.. data:: OPENCV_VERSION_2_4_2
+
+    OpenCV Library version 2.4.2
+
+.. data:: OPENCV_VERSION_2_4_3
+
+    OpenCV Library version 2.4.3
+
+.. data:: OPENCV_VERSION_2_4_4
+
+    OpenCV Library version 2.4.4
+
+.. data:: OPENCV_VERSION_2_4_5
+
+    OpenCV Library version 2.4.5

platforms/android/service/doc/LoaderCallbackInterface.rst

@@ -0,0 +1,49 @@
+*************************
+Loader Callback Interface
+*************************
+
+.. highlight:: java
+.. class:: LoaderCallbackInterface
+
+    Interface for a callback object in case of asynchronous initialization of OpenCV.
+
+void onManagerConnected()
+-------------------------
+
+.. method:: void onManagerConnected(int status)
+
+    Callback method that is called after OpenCV library initialization.
+
+    :param status: status of initialization (see "Initialization Status Constants" section below).
+
+void onPackageInstall()
+-----------------------
+
+.. method:: void onPackageInstall(InstallCallbackInterface Callback)
+
+    Callback method that is called in case when package installation is needed.
+
+    :param callback: answer object with ``install`` and ``cancel`` methods and package description.
+
+Initialization status constants
+-------------------------------
+
+.. data:: SUCCESS
+
+    OpenCV initialization finished successfully
+
+.. data:: MARKET_ERROR
+
+    Google Play (Android Market) application cannot be invoked
+
+.. data:: INSTALL_CANCELED
+
+    OpenCV library installation was cancelled by user
+
+.. data:: INCOMPATIBLE_MANAGER_VERSION
+
+    Version of OpenCV Manager is incompatible with this app. Manager update is needed.
+
+.. data:: INIT_FAILED
+
+    OpenCV library initialization failed

platforms/android/service/doc/Makefile

@@ -0,0 +1,89 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html      to make standalone HTML files"
+	@echo "  dirhtml   to make HTML files named index.html in directories"
+	@echo "  pickle    to make pickle files"
+	@echo "  json      to make JSON files"
+	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  qthelp    to make HTML files and a qthelp project"
+	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  changes   to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck to check all external links for integrity"
+	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/OpenCVEngine.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/OpenCVEngine.qhc"
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
+	      "run these through (pdf)latex."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

platforms/android/service/doc/UseCases.rst

@@ -0,0 +1,32 @@
+Manager Workflow
+****************
+
+.. _manager_selection:
+
+.. include:: ../readme.txt
+
+First application start
+-----------------------
+
+There is no OpenCV Manager or OpenCV libraries:
+
+.. image:: img/NoService.png
+
+Additional library package installation
+---------------------------------------
+
+There is an OpenCV Manager service, but it does not contain appropriate OpenCV library.
+If OpenCV library installation has been approved\:
+
+.. image:: img/LibInstallAproved.png
+
+If OpenCV library installation has been cancelled\:
+
+.. image:: img/LibInstallCanceled.png
+
+Regular application start
+-------------------------
+
+OpenCV Manager and OpenCV library has been already installed.
+
+.. image:: img/LibInstalled.png

platforms/android/service/doc/build_uml.py

@@ -0,0 +1,23 @@
+#!/usr/bin/python
+
+import os
+
+TARGET_PATH = "img"
+
+pipe = os.popen("which dia")
+DiaPath = pipe.readline()
+DiaPath = DiaPath.strip("\n");
+pipe.close()
+
+if ("" == DiaPath):
+    print("Error: Dia tool was not found")
+    exit(-1)
+
+print("Dia tool: \"%s\"" % DiaPath)
+
+if (not os.path.exists(TARGET_PATH)):
+    os.mkdir("img")
+
+for filename in os.listdir("."):
+    if ("dia" == filename[-3:]):
+        os.system("%s --export %s %s" % (DiaPath, os.path.join(TARGET_PATH, filename[0:len(filename)-4] + ".png"), filename))

platforms/android/service/doc/index.rst

@@ -0,0 +1,18 @@
+
+.. _Android_OpenCV_Manager:
+
+***********************
+Android OpenCV Manager
+***********************
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   Intro
+   UseCases
+   JavaHelper
+   BaseLoaderCallback
+   LoaderCallbackInterface
+   InstallCallbackInterface