Merge pull request #1108 from nailbiter:optimLP

.gitignore

@@ -6,3 +6,4 @@ OpenCV4Tegra/
 .sw[a-z]
 .*.swp
 tags
+build/

modules/optim/CMakeLists.txt

+set(the_description "Generic optimization")
+ocv_define_module(optim opencv_core)

modules/optim/doc/linear_programming.rst

+Linear Programming
+==================
+
+.. highlight:: cpp
+
+optim::solveLP
+--------------------
+Solve given (non-integer) linear programming problem using the Simplex Algorithm (Simplex Method).
+What we mean here by "linear programming problem" (or LP problem, for short) can be
+formulated as:
+
+.. math::
+    \mbox{Maximize } c\cdot x\\
+    \mbox{Subject to:}\\
+    Ax\leq b\\
+    x\geq 0
+
+Where :math:`c` is fixed *1*-by-*n* row-vector, :math:`A` is fixed *m*-by-*n* matrix, :math:`b` is fixed *m*-by-*1* column vector and
+:math:`x` is an arbitrary *n*-by-*1* column vector, which satisfies the constraints.
+
+Simplex algorithm is one of many algorithms that are designed to handle this sort of problems efficiently. Although it is not optimal in theoretical
+sense (there exist algorithms that can solve any problem written as above in polynomial type, while simplex method degenerates to exponential time
+for some special cases), it is well-studied, easy to implement and is shown to work well for real-life purposes.
+
+The particular implementation is taken almost verbatim from **Introduction to Algorithms, third edition**
+by T. H. Cormen, C. E. Leiserson, R. L. Rivest and Clifford Stein. In particular, the Bland's rule
+(`http://en.wikipedia.org/wiki/Bland%27s\_rule <http://en.wikipedia.org/wiki/Bland%27s_rule>`_) is used to prevent cycling.
+
+.. ocv:function:: int optim::solveLP(const Mat& Func, const Mat& Constr, Mat& z)
+
+    :param Func: This row-vector corresponds to :math:`c` in the LP problem formulation (see above). It should contain 32- or 64-bit floating point numbers. As a convenience, column-vector may be also submitted, in the latter case it is understood to correspond to :math:`c^T`.
+
+    :param Constr: *m*-by-*n\+1* matrix, whose rightmost column corresponds to :math:`b` in formulation above and the remaining to :math:`A`. It should containt 32- or 64-bit floating point numbers.
+
+    :param z: The solution will be returned here as a column-vector - it corresponds to :math:`c` in the formulation above. It will contain 64-bit floating point numbers.
+
+    :return: One of the return codes:
+
+::
+
+    //!the return codes for solveLP() function
+    enum
+    {
+        SOLVELP_UNBOUNDED    = -2, //problem is unbounded (target function can achieve arbitrary high values)
+        SOLVELP_UNFEASIBLE    = -1, //problem is unfeasible (there are no points that satisfy all the constraints imposed)
+        SOLVELP_SINGLE    = 0, //there is only one maximum for target function
+        SOLVELP_MULTI    = 1 //there are multiple maxima for target function - the arbitrary one is returned
+    };

modules/optim/doc/optim.rst

+**************************************
+optim. Generic numerical optimization
+**************************************
+
+.. highlight:: cpp
+
+.. toctree::
+    :maxdepth: 2
+
+    linear_programming

modules/optim/include/opencv2/optim.hpp

+/*M///////////////////////////////////////////////////////////////////////////////////////
+//
+//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
+//
+//  By downloading, copying, installing or using the software you agree to this license.
+//  If you do not agree to this license, do not download, install,
+//  copy or use the software.
+//
+//
+//                           License Agreement
+//                For Open Source Computer Vision Library
+//
+// Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
+// Copyright (C) 2008-2012, Willow Garage Inc., all rights reserved.
+// Third party copyrights are property of their respective owners.
+//
+// Redistribution and use in source and binary forms, with or without modification,
+// are permitted provided that the following conditions are met:
+//
+//   * Redistribution's of source code must retain the above copyright notice,
+//     this list of conditions and the following disclaimer.
+//
+//   * Redistribution's in binary form must reproduce the above copyright notice,
+//     this list of conditions and the following disclaimer in the documentation
+//     and/or other materials provided with the distribution.
+//
+//   * The name of the copyright holders may not be used to endorse or promote products
+//     derived from this software without specific prior written permission.
+//
+// This software is provided by the copyright holders and contributors "as is" and
+// any express or implied warranties, including, but not limited to, the implied
+// warranties of merchantability and fitness for a particular purpose are disclaimed.
+// In no event shall the Intel Corporation or contributors be liable for any direct,
+// indirect, incidental, special, exemplary, or consequential damages
+// (including, but not limited to, procurement of substitute goods or services;
+// loss of use, data, or profits; or business interruption) however caused
+// and on any theory of liability, whether in contract, strict liability,
+// or tort (including negligence or otherwise) arising in any way out of
+// the use of this software, even if advised of the possibility of such damage.
+//
+//M*/
+
+#ifndef __OPENCV_OPTIM_HPP__
+#define __OPENCV_OPTIM_HPP__
+
+#include "opencv2/core.hpp"
+
+namespace cv{namespace optim
+{
+//!the return codes for solveLP() function
+enum
+{
+    SOLVELP_UNBOUNDED    = -2, //problem is unbounded (target function can achieve arbitrary high values)
+    SOLVELP_UNFEASIBLE    = -1, //problem is unfeasible (there are no points that satisfy all the constraints imposed)
+    SOLVELP_SINGLE    = 0, //there is only one maximum for target function
+    SOLVELP_MULTI    = 1 //there are multiple maxima for target function - the arbitrary one is returned
+};
+
+CV_EXPORTS_W int solveLP(const Mat& Func, const Mat& Constr, Mat& z);
+}}// cv
+
+#endif

modules/optim/include/opencv2/optim/optim.hpp

+/*M///////////////////////////////////////////////////////////////////////////////////////
+//
+//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
+//
+//  By downloading, copying, installing or using the software you agree to this license.
+//  If you do not agree to this license, do not download, install,
+//  copy or use the software.
+//
+//
+//                          License Agreement
+//                For Open Source Computer Vision Library
+//
+// Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
+// Copyright (C) 2009, Willow Garage Inc., all rights reserved.
+// Copyright (C) 2013, OpenCV Foundation, all rights reserved.
+// Third party copyrights are property of their respective owners.
+//
+// Redistribution and use in source and binary forms, with or without modification,
+// are permitted provided that the following conditions are met:
+//
+//   * Redistribution's of source code must retain the above copyright notice,
+//     this list of conditions and the following disclaimer.
+//
+//   * Redistribution's in binary form must reproduce the above copyright notice,
+//     this list of conditions and the following disclaimer in the documentation
+//     and/or other materials provided with the distribution.
+//
+//   * The name of the copyright holders may not be used to endorse or promote products
+//     derived from this software without specific prior written permission.
+//
+// This software is provided by the copyright holders and contributors "as is" and
+// any express or implied warranties, including, but not limited to, the implied
+// warranties of merchantability and fitness for a particular purpose are disclaimed.
+// In no event shall the Intel Corporation or contributors be liable for any direct,
+// indirect, incidental, special, exemplary, or consequential damages
+// (including, but not limited to, procurement of substitute goods or services;
+// loss of use, data, or profits; or business interruption) however caused
+// and on any theory of liability, whether in contract, strict liability,
+// or tort (including negligence or otherwise) arising in any way out of
+// the use of this software, even if advised of the possibility of such damage.
+//
+//M*/
+
+#ifdef __OPENCV_BUILD
+#error this is a compatibility header which should not be used inside the OpenCV library
+#endif
+
+#include "opencv2/optim.hpp"

modules/optim/src/precomp.cpp

+/*M///////////////////////////////////////////////////////////////////////////////////////
+//
+//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
+//
+//  By downloading, copying, installing or using the software you agree to this license.
+//  If you do not agree to this license, do not download, install,
+//  copy or use the software.
+//
+//
+//                        Intel License Agreement
+//                For Open Source Computer Vision Library
+//
+// Copyright (C) 2000, Intel Corporation, all rights reserved.
+// Third party copyrights are property of their respective owners.
+//
+// Redistribution and use in source and binary forms, with or without modification,
+// are permitted provided that the following conditions are met:
+//
+//   * Redistribution's of source code must retain the above copyright notice,
+//     this list of conditions and the following disclaimer.
+//
+//   * Redistribution's in binary form must reproduce the above copyright notice,
+//     this list of conditions and the following disclaimer in the documentation
+//     and/or other materials provided with the distribution.
+//
+//   * The name of Intel Corporation may not be used to endorse or promote products
+//     derived from this software without specific prior written permission.
+//
+// This software is provided by the copyright holders and contributors "as is" and
+// any express or implied warranties, including, but not limited to, the implied
+// warranties of merchantability and fitness for a particular purpose are disclaimed.
+// In no event shall the Intel Corporation or contributors be liable for any direct,
+// indirect, incidental, special, exemplary, or consequential damages
+// (including, but not limited to, procurement of substitute goods or services;
+// loss of use, data, or profits; or business interruption) however caused
+// and on any theory of liability, whether in contract, strict liability,
+// or tort (including negligence or otherwise) arising in any way out of
+// the use of this software, even if advised of the possibility of such damage.
+//
+//M*/
+
+#include "precomp.hpp"
+
+/* End of file. */

modules/optim/src/precomp.hpp

+/*M///////////////////////////////////////////////////////////////////////////////////////
+//
+//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
+//
+//  By downloading, copying, installing or using the software you agree to this license.
+//  If you do not agree to this license, do not download, install,
+//  copy or use the software.
+//
+//
+//                          License Agreement
+//                For Open Source Computer Vision Library
+//
+// Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
+// Copyright (C) 2009, Willow Garage Inc., all rights reserved.
+// Third party copyrights are property of their respective owners.
+//
+// Redistribution and use in source and binary forms, with or without modification,
+// are permitted provided that the following conditions are met:
+//
+//   * Redistribution's of source code must retain the above copyright notice,
+//     this list of conditions and the following disclaimer.
+//
+//   * Redistribution's in binary form must reproduce the above copyright notice,
+//     this list of conditions and the following disclaimer in the documentation
+//     and/or other materials provided with the distribution.
+//
+//   * The name of the copyright holders may not be used to endorse or promote products
+//     derived from this software without specific prior written permission.
+//
+// This software is provided by the copyright holders and contributors "as is" and
+// any express or implied warranties, including, but not limited to, the implied
+// warranties of merchantability and fitness for a particular purpose are disclaimed.
+// In no event shall the Intel Corporation or contributors be liable for any direct,
+// indirect, incidental, special, exemplary, or consequential damages
+// (including, but not limited to, procurement of substitute goods or services;
+// loss of use, data, or profits; or business interruption) however caused
+// and on any theory of liability, whether in contract, strict liability,
+// or tort (including negligence or otherwise) arising in any way out of
+// the use of this software, even if advised of the possibility of such damage.
+//
+//M*/
+
+#ifndef __OPENCV_PRECOMP_H__
+#define __OPENCV_PRECOMP_H__
+
+#include "opencv2/optim.hpp"
+
+#endif

modules/optim/test/test_lpsolver.cpp

+#include "test_precomp.hpp"
+#include <iostream>
+
+TEST(Optim_LpSolver, regression_basic){
+    cv::Mat A,B,z,etalon_z;
+
+#if 1
+    //cormen's example #1
+    A=(cv::Mat_<double>(3,1)<<3,1,2);
+    B=(cv::Mat_<double>(3,4)<<1,1,3,30,2,2,5,24,4,1,2,36);
+    std::cout<<"here A goes\n"<<A<<"\n";
+    cv::optim::solveLP(A,B,z);
+    std::cout<<"here z goes\n"<<z<<"\n";
+    etalon_z=(cv::Mat_<double>(3,1)<<8,4,0);
+    ASSERT_EQ(cv::countNonZero(z!=etalon_z),0);
+#endif
+
+#if 1
+    //cormen's example #2
+    A=(cv::Mat_<double>(1,2)<<18,12.5);
+    B=(cv::Mat_<double>(3,3)<<1,1,20,1,0,20,0,1,16);
+    std::cout<<"here A goes\n"<<A<<"\n";
+    cv::optim::solveLP(A,B,z);
+    std::cout<<"here z goes\n"<<z<<"\n";
+    etalon_z=(cv::Mat_<double>(2,1)<<20,0);
+    ASSERT_EQ(cv::countNonZero(z!=etalon_z),0);
+#endif
+
+#if 1
+    //cormen's example #3
+    A=(cv::Mat_<double>(1,2)<<5,-3);
+    B=(cv::Mat_<double>(2,3)<<1,-1,1,2,1,2);
+    std::cout<<"here A goes\n"<<A<<"\n";
+    cv::optim::solveLP(A,B,z);
+    std::cout<<"here z goes\n"<<z<<"\n";
+    etalon_z=(cv::Mat_<double>(2,1)<<1,0);
+    ASSERT_EQ(cv::countNonZero(z!=etalon_z),0);
+#endif
+}
+
+TEST(Optim_LpSolver, regression_init_unfeasible){
+    cv::Mat A,B,z,etalon_z;
+
+#if 1
+    //cormen's example #4 - unfeasible
+    A=(cv::Mat_<double>(1,3)<<-1,-1,-1);
+    B=(cv::Mat_<double>(2,4)<<-2,-7.5,-3,-10000,-20,-5,-10,-30000);
+    std::cout<<"here A goes\n"<<A<<"\n";
+    cv::optim::solveLP(A,B,z);
+    std::cout<<"here z goes\n"<<z<<"\n";
+    etalon_z=(cv::Mat_<double>(3,1)<<1250,1000,0);
+    ASSERT_EQ(cv::countNonZero(z!=etalon_z),0);
+#endif
+}
+
+TEST(Optim_LpSolver, regression_absolutely_unfeasible){
+    cv::Mat A,B,z,etalon_z;
+
+#if 1
+    //trivial absolutely unfeasible example
+    A=(cv::Mat_<double>(1,1)<<1);
+    B=(cv::Mat_<double>(2,2)<<1,-1);
+    std::cout<<"here A goes\n"<<A<<"\n";
+    int res=cv::optim::solveLP(A,B,z);
+    ASSERT_EQ(res,-1);
+#endif
+}
+
+TEST(Optim_LpSolver, regression_multiple_solutions){
+    cv::Mat A,B,z,etalon_z;
+
+#if 1
+    //trivial example with multiple solutions
+    A=(cv::Mat_<double>(2,1)<<1,1);
+    B=(cv::Mat_<double>(1,3)<<1,1,1);
+    std::cout<<"here A goes\n"<<A<<"\n";
+    int res=cv::optim::solveLP(A,B,z);
+    printf("res=%d\n",res);
+    printf("scalar %g\n",z.dot(A));
+    std::cout<<"here z goes\n"<<z<<"\n";
+    ASSERT_EQ(res,1);
+    ASSERT_EQ(z.dot(A),1);
+#endif
+}
+
+TEST(Optim_LpSolver, regression_cycling){
+    cv::Mat A,B,z,etalon_z;
+
+#if 1
+    //example with cycling from http://people.orie.cornell.edu/miketodd/or630/SimplexCyclingExample.pdf
+    A=(cv::Mat_<double>(4,1)<<10,-57,-9,-24);
+    B=(cv::Mat_<double>(3,5)<<0.5,-5.5,-2.5,9,0,0.5,-1.5,-0.5,1,0,1,0,0,0,1);
+    std::cout<<"here A goes\n"<<A<<"\n";
+    int res=cv::optim::solveLP(A,B,z);
+    printf("res=%d\n",res);
+    printf("scalar %g\n",z.dot(A));
+    std::cout<<"here z goes\n"<<z<<"\n";
+    ASSERT_EQ(z.dot(A),1);
+    //ASSERT_EQ(res,1);
+#endif
+}

modules/optim/test/test_main.cpp

+#include "test_precomp.hpp"
+
+CV_TEST_MAIN("cv")

modules/optim/test/test_precomp.cpp

+#include "test_precomp.hpp"

modules/optim/test/test_precomp.hpp

+#ifdef __GNUC__
+#  pragma GCC diagnostic ignored "-Wmissing-declarations"
+#  if defined __clang__ || defined __APPLE__
+#    pragma GCC diagnostic ignored "-Wmissing-prototypes"
+#    pragma GCC diagnostic ignored "-Wextra"
+#  endif
+#endif
+
+#ifndef __OPENCV_TEST_PRECOMP_HPP__
+#define __OPENCV_TEST_PRECOMP_HPP__
+
+#include "opencv2/ts.hpp"
+#include "opencv2/optim.hpp"
+
+#endif