/*! \file core.hpp
\brief The Core Functionality
*/
/*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-2011, 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_CORE_HPP__
#define __OPENCV_CORE_HPP__

#include "opencv2/core/types_c.h"
#include "opencv2/core/version.hpp"

#ifdef __cplusplus

#ifndef SKIP_INCLUDES
#include <limits.h>
#include <algorithm>
#include <cmath>
#include <cstddef>
#include <complex>
#include <map>
#include <new>
#include <string>
#include <vector>
#endif // SKIP_INCLUDES

/*! \namespace cv
Namespace where all the C++ OpenCV functionality resides
*/
namespace cv {

#undef abs
#undef min
#undef max
#undef Complex

using std::vector;
using std::string;
using std::ptrdiff_t;

template<typename _Tp> class CV_EXPORTS Size_;
template<typename _Tp> class CV_EXPORTS Point_;
template<typename _Tp> class CV_EXPORTS Rect_;
template<typename _Tp, int cn> class CV_EXPORTS Vec;
template<typename _Tp, int m, int n> class CV_EXPORTS Matx;

typedef std::string String;
typedef std::basic_string<wchar_t> WString;

class Mat;
class SparseMat;
typedef Mat MatND;

class CV_EXPORTS MatExpr;
class CV_EXPORTS MatOp_Base;
class CV_EXPORTS MatArg;
class CV_EXPORTS MatConstIterator;

template<typename _Tp> class CV_EXPORTS Mat_;
template<typename _Tp> class CV_EXPORTS MatIterator_;
template<typename _Tp> class CV_EXPORTS MatConstIterator_;
template<typename _Tp> class CV_EXPORTS MatCommaInitializer_;

CV_EXPORTS string fromUtf16(const WString& str);
CV_EXPORTS WString toUtf16(const string& str);

CV_EXPORTS string format( const char* fmt, ... );
CV_EXPORTS string tempfile( const char* suffix CV_DEFAULT(0));

// matrix decomposition types
enum { DECOMP_LU=0, DECOMP_SVD=1, DECOMP_EIG=2, DECOMP_CHOLESKY=3, DECOMP_QR=4, DECOMP_NORMAL=16 };
enum { NORM_INF=1, NORM_L1=2, NORM_L2=4, NORM_TYPE_MASK=7, NORM_RELATIVE=8, NORM_MINMAX=32};
enum { CMP_EQ=0, CMP_GT=1, CMP_GE=2, CMP_LT=3, CMP_LE=4, CMP_NE=5 };
enum { GEMM_1_T=1, GEMM_2_T=2, GEMM_3_T=4 };
enum { DFT_INVERSE=1, DFT_SCALE=2, DFT_ROWS=4, DFT_COMPLEX_OUTPUT=16, DFT_REAL_OUTPUT=32,
DCT_INVERSE = DFT_INVERSE, DCT_ROWS=DFT_ROWS };


/*!
The standard OpenCV exception class.
Instances of the class are thrown by various functions and methods in the case of critical errors.
*/
class CV_EXPORTS Exception : public std::exception
{
public:
/*!
Default constructor
*/
Exception();
/*!
Full constructor. Normally the constuctor is not called explicitly.
Instead, the macros CV_Error(), CV_Error_() and CV_Assert() are used.
*/
Exception(int _code, const string& _err, const string& _func, const string& _file, int _line);
virtual ~Exception() throw();

/*!
\return the error description and the context as a text string.
*/
virtual const char *what() const throw();
void formatMessage();

string msg; ///< the formatted error message

int code; ///< error code @see CVStatus
string err; ///< error description
string func; ///< function name. Available only when the compiler supports __func__ macro
string file; ///< source file name where the error has occured
int line; ///< line number in the source file where the error has occured
};


//! Signals an error and raises the exception.

/*!
By default the function prints information about the error to stderr,
then it either stops if setBreakOnError() had been called before or raises the exception.
It is possible to alternate error processing by using redirectError().

\param exc the exception raisen.
*/
CV_EXPORTS void error( const Exception& exc );

//! Sets/resets the break-on-error mode.

/*!
When the break-on-error mode is set, the default error handler
issues a hardware exception, which can make debugging more convenient.

\return the previous state
*/
CV_EXPORTS bool setBreakOnError(bool flag);

typedef int (CV_CDECL *ErrorCallback)( int status, const char* func_name,
const char* err_msg, const char* file_name,
int line, void* userdata );

//! Sets the new error handler and the optional user data.

/*!
The function sets the new error handler, called from cv::error().

\param errCallback the new error handler. If NULL, the default error handler is used.
\param userdata the optional user data pointer, passed to the callback.
\param prevUserdata the optional output parameter where the previous user data pointer is stored

\return the previous error handler
*/
CV_EXPORTS ErrorCallback redirectError( ErrorCallback errCallback,
void* userdata=0, void** prevUserdata=0);

#ifdef __GNUC__
#define CV_Error( code, msg ) cv::error( cv::Exception(code, msg, __func__, __FILE__, __LINE__) )
#define CV_Error_( code, args ) cv::error( cv::Exception(code, cv::format args, __func__, __FILE__, __LINE__) )
#define CV_Assert( expr ) if((expr)) ; else cv::error( cv::Exception(CV_StsAssert, #expr, __func__, __FILE__, __LINE__) )
#else
#define CV_Error( code, msg ) cv::error( cv::Exception(code, msg, "", __FILE__, __LINE__) )
#define CV_Error_( code, args ) cv::error( cv::Exception(code, cv::format args, "", __FILE__, __LINE__) )
#define CV_Assert( expr ) if((expr)) ; else cv::error( cv::Exception(CV_StsAssert, #expr, "", __FILE__, __LINE__) )
#endif

#ifdef _DEBUG
#define CV_DbgAssert(expr) CV_Assert(expr)
#else
#define CV_DbgAssert(expr)
#endif

CV_EXPORTS void setNumThreads(int nthreads);
CV_EXPORTS int getNumThreads();
CV_EXPORTS int getThreadNum();

//! Returns the number of ticks.

/*!
The function returns the number of ticks since the certain event (e.g. when the machine was turned on).
It can be used to initialize cv::RNG or to measure a function execution time by reading the tick count
before and after the function call. The granularity of ticks depends on the hardware and OS used. Use
cv::getTickFrequency() to convert ticks to seconds.
*/
CV_EXPORTS_W int64 getTickCount();

/*!
Returns the number of ticks per seconds.

The function returns the number of ticks (as returned by cv::getTickCount()) per second.
The following code computes the execution time in milliseconds:

\code
double exec_time = (double)getTickCount();
// do something ...
exec_time = ((double)getTickCount() - exec_time)*1000./getTickFrequency();
\endcode
*/
CV_EXPORTS_W double getTickFrequency();

/*!
Returns the number of CPU ticks.

On platforms where the feature is available, the function returns the number of CPU ticks
since the certain event (normally, the system power-on moment). Using this function
one can accurately measure the execution time of very small code fragments,
for which cv::getTickCount() granularity is not enough.
*/
CV_EXPORTS_W int64 getCPUTickCount();

/*!
Returns SSE etc. support status

The function returns true if certain hardware features are available.
Currently, the following features are recognized:
- CV_CPU_MMX - MMX
- CV_CPU_SSE - SSE
- CV_CPU_SSE2 - SSE 2
- CV_CPU_SSE3 - SSE 3
- CV_CPU_SSSE3 - SSSE 3
- CV_CPU_SSE4_1 - SSE 4.1
- CV_CPU_SSE4_2 - SSE 4.2
- CV_CPU_POPCNT - POPCOUNT
- CV_CPU_AVX - AVX

\note {Note that the function output is not static. Once you called cv::useOptimized(false),
most of the hardware acceleration is disabled and thus the function will returns false,
until you call cv::useOptimized(true)}
*/
CV_EXPORTS_W bool checkHardwareSupport(int feature);

//! returns the number of CPUs (including hyper-threading)
CV_EXPORTS_W int getNumberOfCPUs();

/*!
Allocates memory buffer

This is specialized OpenCV memory allocation function that returns properly aligned memory buffers.
The usage is identical to malloc(). The allocated buffers must be freed with cv::fastFree().
If there is not enough memory, the function calls cv::error(), which raises an exception.

\param bufSize buffer size in bytes
\return the allocated memory buffer.
*/
CV_EXPORTS void* fastMalloc(size_t bufSize);

/*!
Frees the memory allocated with cv::fastMalloc

This is the corresponding deallocation function for cv::fastMalloc().
When ptr==NULL, the function has no effect.
*/
CV_EXPORTS void fastFree(void* ptr);

template<typename _Tp> static inline _Tp* allocate(size_t n)
{
return new _Tp[n];
}

template<typename _Tp> static inline void deallocate(_Tp* ptr, size_t)
{
delete[] ptr;
}

/*!
Aligns pointer by the certain number of bytes

This small inline function aligns the pointer by the certian number of bytes by shifting
it forward by 0 or a positive offset.
*/
template<typename _Tp> static inline _Tp* alignPtr(_Tp* ptr, int n=(int)sizeof(_Tp))
{
return (_Tp*)(((size_t)ptr + n-1) & -n);
}

/*!
Aligns buffer size by the certain number of bytes

This small inline function aligns a buffer size by the certian number of bytes by enlarging it.
*/
static inline size_t alignSize(size_t sz, int n)
{
return (sz + n-1) & -n;
}

/*!
Turns on/off available optimization

The function turns on or off the optimized code in OpenCV. Some optimization can not be enabled
or disabled, but, for example, most of SSE code in OpenCV can be temporarily turned on or off this way.

\note{Since optimization may imply using special data structures, it may be unsafe
to call this function anywhere in the code. Instead, call it somewhere at the top level.}
*/
CV_EXPORTS_W void setUseOptimized(bool onoff);

/*!
Returns the current optimization status

The function returns the current optimization status, which is controlled by cv::setUseOptimized().
*/
CV_EXPORTS_W bool useOptimized();

/*!
The STL-compilant memory Allocator based on cv::fastMalloc() and cv::fastFree()
*/
template<typename _Tp> class CV_EXPORTS Allocator
{
public:
typedef _Tp value_type;
typedef value_type* pointer;
typedef const value_type* const_pointer;
typedef value_type& reference;
typedef const value_type& const_reference;
typedef size_t size_type;
typedef ptrdiff_t difference_type;
template<typename U> class rebind { typedef Allocator<U> other; };

explicit Allocator() {}
~Allocator() {}
explicit Allocator(Allocator const&) {}
template<typename U>
explicit Allocator(Allocator<U> const&) {}

// address
pointer address(reference r) { return &r; }
const_pointer address(const_reference r) { return &r; }

pointer allocate(size_type count, const void* =0)
{ return reinterpret_cast<pointer>(fastMalloc(count * sizeof (_Tp))); }

void deallocate(pointer p, size_type) {fastFree(p); }

size_type max_size() const
{ return max(static_cast<_Tp>(-1)/sizeof(_Tp), 1); }

void construct(pointer p, const _Tp& v) { new(static_cast<void*>(p)) _Tp(v); }
void destroy(pointer p) { p->~_Tp(); }
};

/////////////////////// Vec (used as element of multi-channel images /////////////////////

/*!
A helper class for cv::DataType

The class is specialized for each fundamental numerical data type supported by OpenCV.
It provides DataDepth<T>::value constant.
*/
template<typename _Tp> class CV_EXPORTS DataDepth {};

template<> class DataDepth<bool> { public: enum { value = CV_8U, fmt=(int)'u' }; };
template<> class DataDepth<uchar> { public: enum { value = CV_8U, fmt=(int)'u' }; };
template<> class DataDepth<schar> { public: enum { value = CV_8S, fmt=(int)'c' }; };
template<> class DataDepth<char> { public: enum { value = CV_8S, fmt=(int)'c' }; };
template<> class DataDepth<ushort> { public: enum { value = CV_16U, fmt=(int)'w' }; };
template<> class DataDepth<short> { public: enum { value = CV_16S, fmt=(int)'s' }; };
template<> class DataDepth<int> { public: enum { value = CV_32S, fmt=(int)'i' }; };
// this is temporary solution to support 32-bit unsigned integers
template<> class DataDepth<unsigned> { public: enum { value = CV_32S, fmt=(int)'i' }; };
template<> class DataDepth<float> { public: enum { value = CV_32F, fmt=(int)'f' }; };
template<> class DataDepth<double> { public: enum { value = CV_64F, fmt=(int)'d' }; };
template<typename _Tp> class DataDepth<_Tp*> { public: enum { value = CV_USRTYPE1, fmt=(int)'r' }; };


////////////////////////////// Small Matrix ///////////////////////////

/*!
A short numerical vector.

This template class represents short numerical vectors (of 1, 2, 3, 4 ... elements)
on which you can perform basic arithmetical operations, access individual elements using [] operator etc.
The vectors are allocated on stack, as opposite to std::valarray, std::vector, cv::Mat etc.,
which elements are dynamically allocated in the heap.

The template takes 2 parameters:
-# _Tp element type
-# cn the number of elements

In addition to the universal notation like Vec<float, 3>, you can use shorter aliases
for the most popular specialized variants of Vec, e.g. Vec3f ~ Vec<float, 3>.
*/

struct CV_EXPORTS Matx_AddOp {};
struct CV_EXPORTS Matx_SubOp {};
struct CV_EXPORTS Matx_ScaleOp {};
struct CV_EXPORTS Matx_MulOp {};
struct CV_EXPORTS Matx_MatMulOp {};
struct CV_EXPORTS Matx_TOp {};

template<typename _Tp, int m, int n> class CV_EXPORTS Matx
{
public:
typedef _Tp value_type;
typedef Matx<_Tp, MIN(m, n), 1> diag_type;
typedef Matx<_Tp, m, n> mat_type;
enum { depth = DataDepth<_Tp>::value, rows = m, cols = n, channels = rows*cols,
type = CV_MAKETYPE(depth, channels) };

//! default constructor
Matx();

Matx(_Tp v0); //!< 1x1 matrix
Matx(_Tp v0, _Tp v1); //!< 1x2 or 2x1 matrix
Matx(_Tp v0, _Tp v1, _Tp v2); //!< 1x3 or 3x1 matrix
Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3); //!< 1x4, 2x2 or 4x1 matrix
Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4); //!< 1x5 or 5x1 matrix
Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5); //!< 1x6, 2x3, 3x2 or 6x1 matrix
Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6); //!< 1x7 or 7x1 matrix
Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6, _Tp v7); //!< 1x8, 2x4, 4x2 or 8x1 matrix
Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6, _Tp v7, _Tp v8); //!< 1x9, 3x3 or 9x1 matrix
Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3, _Tp v4, _Tp v5, _Tp v6, _Tp v7, _Tp v8, _Tp v9); //!< 1x10, 2x5 or 5x2 or 10x1 matrix
Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3,
_Tp v4, _Tp v5, _Tp v6, _Tp v7,
_Tp v8, _Tp v9, _Tp v10, _Tp v11); //!< 1x12, 2x6, 3x4, 4x3, 6x2 or 12x1 matrix
Matx(_Tp v0, _Tp v1, _Tp v2, _Tp v3,
_Tp v4, _Tp v5, _Tp v6, _Tp v7,
_Tp v8, _Tp v9, _Tp v10, _Tp v11,
_Tp v12, _Tp v13, _Tp v14, _Tp v15); //!< 1x16, 4x4 or 16x1 matrix
explicit Matx(const _Tp* vals); //!< initialize from a plain array

static Matx all(_Tp alpha);
static Matx zeros();
static Matx ones();
static Matx eye();
static Matx diag(const diag_type& d);
static Matx randu(_Tp a, _Tp b);
static Matx randn(_Tp a, _Tp b);

//! dot product computed with the default precision
_Tp dot(const Matx<_Tp, m, n>& v) const;

//! dot product computed in double-precision arithmetics
double ddot(const Matx<_Tp, m, n>& v) const;

//! convertion to another data type
template<typename T2> operator Matx<T2, m, n>() const;

//! change the matrix shape
template<int m1, int n1> Matx<_Tp, m1, n1> reshape() const;

//! extract part of the matrix
template<int m1, int n1> Matx<_Tp, m1, n1> get_minor(int i, int j) const;

//! extract the matrix row
Matx<_Tp, 1, n> row(int i) const;

//! extract the matrix column
Matx<_Tp, m, 1> col(int i) const;

//! extract the matrix diagonal
Matx<_Tp, MIN(m,n), 1> diag() const;

//! transpose the matrix
Matx<_Tp, n, m> t() const;

//! invert matrix the matrix
Matx<_Tp, n, m> inv(int method=DECOMP_LU) const;

//! solve linear system
template<int l> Matx<_Tp, n, l> solve(const Matx<_Tp, m, l>& rhs, int flags=DECOMP_LU) const;
Matx<_Tp, n, 1> solve(const Matx<_Tp, m, 1>& rhs, int method) const;

//! multiply two matrices element-wise
Matx<_Tp, m, n> mul(const Matx<_Tp, m, n>& a) const;

//! element access
const _Tp& operator ()(int i, int j) const;
_Tp& operator ()(int i, int j);

//! 1D element access
const _Tp& operator ()(int i) const;
_Tp& operator ()(int i);

Matx(const Matx<_Tp, m, n>& a, const Matx<_Tp, m, n>& b, Matx_AddOp);
Matx(const Matx<_Tp, m, n>& a, const Matx<_Tp, m, n>& b, Matx_SubOp);
template<typename _T2> Matx(const Matx<_Tp, m, n>& a, _T2 alpha, Matx_ScaleOp);
Matx(const Matx<_Tp, m, n>& a, const Matx<_Tp, m, n>& b, Matx_MulOp);
template<int l> Matx(const Matx<_Tp, m, l>& a, const Matx<_Tp, l, n>& b, Matx_MatMulOp);
Matx(const Matx<_Tp, n, m>& a, Matx_TOp);

_Tp val[m*n]; //< matrix elements
};


typedef Matx<float, 1, 2> Matx12f;
typedef Matx<double, 1, 2> Matx12d;
typedef Matx<float, 1, 3> Matx13f;
typedef Matx<double, 1, 3> Matx13d;
typedef Matx<float, 1, 4> Matx14f;
typedef Matx<double, 1, 4> Matx14d;
typedef Matx<float, 1, 6> Matx16f;
typedef Matx<double, 1, 6> Matx16d;

typedef Matx<float, 2, 1> Matx21f;
typedef Matx<double, 2, 1> Matx21d;
typedef Matx<float, 3, 1> Matx31f;
typedef Matx<double, 3, 1> Matx31d;
typedef Matx<float, 4, 1> Matx41f;
typedef Matx<double, 4, 1> Matx41d;
typedef Matx<float, 6, 1> Matx61f;
typedef Matx<double, 6, 1> Matx61d;

typedef Matx<float, 2, 2> Matx22f;
typedef Matx<double, 2, 2> Matx22d;
typedef Matx<float, 2, 3> Matx23f;
typedef Matx<double, 2, 3> Matx23d;
typedef Matx<float, 3, 2> Matx32f;
typedef Matx<double, 3, 2> Matx32d;

typedef Matx<float, 3, 3> Matx33f;
typedef Matx<double, 3, 3> Matx33d;

typedef Matx<float, 3, 4> Matx34f;
typedef Matx<double, 3, 4> Matx34d;
typedef Matx<float, 4, 3> Matx43f;
typedef Matx<double, 4, 3> Matx43d;

typedef Matx<float, 4, 4> Matx44f;
typedef Matx<double, 4, 4> Matx44d;
typedef Matx<float, 6, 6> Matx66f;
typedef Matx<double, 6, 6> Matx66d;