adding OpenCV Manager

android/service/doc/AsyncServiceHelper.rst

@@ -0,0 +1,26 @@
+*******************************************
+Java Asynchronious OpenCV Helper (internal)
+*******************************************
+
+.. highlight:: java
+.. module:: org.opencv.android
+    :platform: Android
+    :synopsis: Implements Android dependent Java classes
+.. Class:: AsyncServiceHelper
+
+Helper class provides implementation of asynchronious OpenCV initialization with Android OpenCV Engine Service.
+
+.. note:: This is imternal class. Does not use it directly. Use OpenCVLoader.initAsync() instead!
+
+int initOpenCV()
+----------------
+
+.. method:: int initOpenCV(String Version, Context AppContext, LoaderCallbackInterface Callback)
+
+    Tries to init OpenCV library using OpenCV Engine Service. Callback method will be called, when initialisation finishes
+
+    :param Version: Version of OpenCV
+    :param AppContext: Application context for service connection
+    :param CallBack: Object that implements LoaderCallbackInterface. See Helper callback interface
+    :rtype: boolean
+    :return: Return true if initialization starts successfully

android/service/doc/BaseLoaderCallback.rst

@@ -0,0 +1,14 @@
+*********************************************
+Base Loader Callback Interface implementation
+*********************************************
+
+.. highlight:: java
+.. module:: org.opencv.android
+    :platform: Android
+    :synopsis: Implements OpenCV initialization callback interface.
+.. class:: BaseLoaderCallback
+
+    Basic implementation of LoaderCallbackInterface. Implementation logic is described by diagram.
+
+.. image:: img/AndroidAppUsageModel.dia.png
+

android/service/doc/IOpenCVEngine.rst

@@ -0,0 +1,54 @@
+***************************************
+Native OpenCV Manager service interface
+***************************************
+
+.. highlight:: cpp
+.. module:: IOpenCVEngine.h
+    :platform: Android
+    :synopsis: Defines OpenCV Manager interface for Android Binder component
+.. Class:: OpenCVEngine
+
+OpenCVEngine class provides Binder interface to OpenCV Manager Service
+
+int getEngineVersion()
+----------------------
+
+.. method:: int GetEngineVersion()
+
+    Gets OpenCV Manager version
+
+    :rtype: int
+    :return: Returns OpenCV Manager version
+
+android::String16 getLibPathByVersion()
+---------------------------------------
+
+.. method:: android::String16 GetLibPathByVersion(android::String16 version)
+
+    Gets path to native OpenCV libraries 
+
+    :param version: OpenCV Library version
+    :rtype: String;
+    :return: Returns path to OpenCV native libs or empty string if OpenCV was not found
+
+android::String16 getLibraryList()
+----------------------------------
+
+.. method:: android::String16 GetLibraryList(android::String16 version)
+
+    Gets list of OpenCV native libraries in loading order
+
+    :param version: OpenCV Library version
+    :rtype: String;
+    :return: Returns OpenCV libraries names separated by semicolon symbol in loading order
+
+boolean installVersion()
+------------------------
+
+.. method:: boolean InstallVersion(android::String16 version)
+
+    Trys to install defined version of OpenCV
+
+    :param version: OpenCV Library version
+    :rtype: String
+    :return: Returns true if installation successful or package has been already installed

android/service/doc/InstallCallbackInterface.rst

@@ -0,0 +1,35 @@
+**************************
+Install Callback Interface
+**************************
+.. highlight:: java
+.. module:: org.opencv.android
+    :platform: Android
+    :synopsis: Defines callback interface for package management.
+
+.. 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: Return package name, i.e. "OpenCV Manager Service" or "OpenCV library"
+
+void install()
+--------------
+
+.. method:: void install()
+
+    Installation of package is approved
+
+void cancel()
+-------------
+
+.. method:: void cancel()
+
+    Installation if package was canceled

android/service/doc/Intro.rst

@@ -0,0 +1,37 @@
+************
+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 of different versions 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 them self;
+#. Hardware specific optimizations for all supported platforms;
+#. Trusted OpenCV library source. All packages with OpenCV are published on Google Play service;
+#. Regular updates and bug fixes;
+
+Usage model for target user
+---------------------------
+
+.. image:: img/AndroidAppUsageModel.dia.png
+
+First OpenCV app\:
+
+#. User downloads app dependent from OpenCV from Google Play or installs it manually;
+#. User starts application. Application asks user to install OpenCV Manager;
+#. User installs OpenCV Manager from Google Play Service;
+#. User starts application. Application proposes to user to install OpenCV library for target device and runs Google Play;
+#. User runs app in the third time  and gets what he or she wants.
+
+Next OpenCV app\:
+
+#. User downloads app dependent from OpenCV from Google Play or installs it manually;
+#. User starts application.
+#. If selected version is not installed Manager asks user to install OpenCV library package and runs Google Play;
+#. User runs app in the second time and gets what he or she wants.
+
+OpenCV Manager structure
+------------------------
+
+.. image:: img/Structure.dia.png

android/service/doc/JavaHelper.rst

@@ -0,0 +1,54 @@
+******************
+Java OpenCV Loader
+******************
+
+.. highlight:: java
+.. module:: org.opencv.android
+    :platform: Android
+    :synopsis: Implements Android dependent Java classes.
+.. Class:: OpenCVLoader
+
+Helper class provides common initialization methods for OpenCV library
+
+boolean initDebug()
+-------------------
+
+.. method:: static boolean initDebug()
+    
+    Load and initialize OpenCV library from current application package. Roughly it is analog of system.loadLibrary("opencv_java")
+
+    :rtype: boolean
+    :return: Return true if initialization of OpenCV was successful
+
+.. note:: This way is deprecated for production code. It is designed for experimantal 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)
+
+    Load and initialize OpenCV library using OpenCV Manager service.
+
+    :param Version: OpenCV Library version
+    :param AppContext: Application context for connecting to service
+    :param Callback: Object, that implements LoaderCallbackInterface for handling Connection status. See BaseLoaderCallback.
+    :rtype: boolean
+    :return: Return true if initialization of OpenCV starts successfully
+
+OpenCV version constants
+-------------------------
+
+.. data:: OPENCV_VERSION_2_4_0
+
+    OpenCV Library version 2.4.0
+
+.. data:: OPENCV_VERSION_2_4_2
+
+    OpenCV Library version 2.4.2
+
+Other constatnts
+----------------
+
+.. data:: OPEN_CV_SERVICE_URL
+
+    Url for OpenCV Manager on Google Play (Android Market)

android/service/doc/LoaderCallbackInterface.rst

@@ -0,0 +1,56 @@
+*************************
+Loader Callback Interface
+*************************
+
+.. highlight:: java
+.. module:: org.opencv.android
+    :platform: Android
+    :synopsis: Defines OpenCV initialization callback interface.
+.. class:: LoaderCallbackInterface
+
+    Interface for 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
+
+void onPackageInstall()
+-----------------------
+
+.. method:: void onPackageInstall(InstallCallbackInterface Callback)
+
+    Callback method that is called in case when package installation is needed
+
+    @param callback Answer object with approve and cancel methods and package description
+
+Initialization status constants
+-------------------------------
+
+.. data:: SUCCESS
+
+    OpenCV initialization finished successfully
+
+.. data:: RESTART_REQUIRED
+
+    OpenCV library installation via Google Play service was initialized. Application restart is required
+
+.. data:: MARKET_ERROR
+
+    Google Play (Android Market) cannot be invoked
+
+.. data:: INSTALL_CANCELED
+
+    OpenCV library installation was canceled by user
+
+.. data:: INCOMPATIBLE_MANAGER_VERSION
+
+    Version of OpenCV Manager Service is incompatible with this app. Service update is needed
+
+.. data:: INIT_FAILED
+
+    OpenCV library initialization failed

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."

android/service/doc/NativeHelper.rst

@@ -0,0 +1,5 @@
+********************
+Native OpenCV Helper
+********************
+
+.. highlight:: cpp

android/service/doc/OpenCVEngineInterface.rst

@@ -0,0 +1,57 @@
+*********************************
+Java OpenCV OpenCVEngineInterface
+*********************************
+
+.. highlight:: java
+.. module:: org.opencv.engine
+    :platform: Android
+    :synopsis: Defines OpenCV Manager interface for Android.
+.. Class:: OpenCVEngineInterface
+
+OpenCVEngineInterface class provides Java interface to OpenCV Manager Service. Is synchronous with native OpenCVEngine class
+
+.. note:: Do not use this class directly. Use OpenCVLoader instead!
+
+int getEngineVersion()
+----------------------
+
+.. method:: int GetEngineVersion()
+
+    Get OpenCV Manager version
+
+    :rtype: int
+    :return: Return OpenCV Manager version
+
+String getLibPathByVersion()
+----------------------------
+
+.. method:: String GetLibPathByVersion(String version)
+
+    Find already installed OpenCV library 
+
+    :param version: OpenCV library version
+    :rtype: String
+    :return: Return path to OpenCV native libs or empty string if OpenCV was not found
+
+String getLibraryList()
+-----------------------
+
+.. method:: String GetLibraryList(String version)
+
+    Get list of OpenCV native libraries in loading order separated by ";" symbol
+
+    :param version: OpenCV library version
+    :rtype: String
+    :return: Return OpenCV libraries names separated by symbol ";" in loading order
+
+boolean installVersion()
+------------------------
+
+.. method:: boolean InstallVersion(String version)
+
+    Try to install defined version of OpenCV from Google Play (Android Market).
+
+    :param version: OpenCV library version
+    :rtype: String
+    :return: Return true if installation was successful or OpenCV package has been already installed
+ 

android/service/doc/StaticHelper.rst

@@ -0,0 +1,24 @@
+************************************
+Java Static OpenCV Helper (internal)
+************************************
+
+.. highlight:: java
+.. module:: org.opencv.android
+    :platform: Android
+    :synopsis: Implements Android dependent Java classes
+.. Class:: StaticHelper
+
+Helper class provides implementation of static OpenCV initialization. All OpenCV libraries must be included to application package.
+
+.. note:: This is internal class. Does not use it directly. Use OpenCVLoader.initDebug() instead!
+
+int initOpenCV()
+----------------
+
+.. method:: int initOpenCV()
+
+    Tries to init OpenCV library using libraries from application package. Method uses libopencv_info.so library for getting 
+    list of libraries in loading order. Method loads libopencv_java.so, if info library is not present.
+
+    :rtype: boolean
+    :return: Return true if initialization was successful

android/service/doc/UseCases.rst

@@ -0,0 +1,29 @@
+*******************************************
+Engine use Cases
+*******************************************
+
+First application start
+-----------------------
+
+There is no OpenCV Manager and OpenCV libraries.
+
+.. image:: img/NoService.dia.png
+
+Second application start
+------------------------
+
+There is OpenCV Manager service, but there is no OpenCV library.
+If OpenCV library installation approved\:
+
+.. image:: img/LibInstallAproved.dia.png
+
+If OpenCV library installation canceled\:
+
+.. image:: img/LibInstallCanceled.dia.png
+
+Regular application start
+-------------------------
+
+OpenCV Manager and OpenCV library has bee already installed.
+
+.. image:: img/LibInstalled.dia.png

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 + ".png"), filename))

android/service/doc/index.rst

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