utility.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.
// Copyright (C) 2015, Itseez 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_UTILITY_H
#define OPENCV_CORE_UTILITY_H
 
#ifndef __cplusplus
#  error utility.hpp header must be compiled as C++
#endif
 
#if defined(check)
#  warning Detected Apple 'check' macro definition, it can cause build conflicts. Please, include this header before any Apple headers.
#endif
 
#include "opencv2/core.hpp"
#include <ostream>
 
#include <functional>
 
#if !defined(_M_CEE)
#include <mutex>  // std::mutex, std::lock_guard
#endif
 
namespace cv
{
 
 
#ifdef OPENCV_ENABLE_MEMORY_SANITIZER
template<typename _Tp, size_t fixed_size = 0> class AutoBuffer
#else
template<typename _Tp, size_t fixed_size = 1024/sizeof(_Tp)+8> class AutoBuffer
#endif
{
public:
    typedef _Tp value_type;
 
    AutoBuffer();
    explicit AutoBuffer(size_t _size);
 
    AutoBuffer(const AutoBuffer<_Tp, fixed_size>& buf);
    AutoBuffer<_Tp, fixed_size>& operator = (const AutoBuffer<_Tp, fixed_size>& buf);
 
    ~AutoBuffer();
 
    void allocate(size_t _size);
    void deallocate();
    void resize(size_t _size);
    size_t size() const;
    inline _Tp* data() { return ptr; }
    inline const _Tp* data() const { return ptr; }
 
#if !defined(OPENCV_DISABLE_DEPRECATED_COMPATIBILITY) // use to .data() calls instead
    operator _Tp* () { return ptr; }
    operator const _Tp* () const { return ptr; }
#else
    inline _Tp& operator[] (size_t i) { CV_DbgCheckLT(i, sz, "out of range"); return ptr[i]; }
    inline const _Tp& operator[] (size_t i) const { CV_DbgCheckLT(i, sz, "out of range"); return ptr[i]; }
#endif
 
protected:
    _Tp* ptr;
    size_t sz;
    _Tp buf[(fixed_size > 0) ? fixed_size : 1];
};
 
CV_EXPORTS bool setBreakOnError(bool flag);
 
extern "C" typedef int (*ErrorCallback)( int status, const char* func_name,
                                       const char* err_msg, const char* file_name,
                                       int line, void* userdata );
 
 
CV_EXPORTS ErrorCallback redirectError( ErrorCallback errCallback, void* userdata=0, void** prevUserdata=0);
 
CV_EXPORTS String tempfile( const char* suffix = 0);
CV_EXPORTS void glob(String pattern, std::vector<String>& result, bool recursive = false);
 
CV_EXPORTS_W void setNumThreads(int nthreads);
 
CV_EXPORTS_W int getNumThreads();
 
CV_EXPORTS_W int getThreadNum();
 
CV_EXPORTS_W const String& getBuildInformation();
 
CV_EXPORTS_W String getVersionString();
 
CV_EXPORTS_W int getVersionMajor();
 
CV_EXPORTS_W int getVersionMinor();
 
CV_EXPORTS_W int getVersionRevision();
 
CV_EXPORTS_W int64 getTickCount();
 
CV_EXPORTS_W double getTickFrequency();
 
class CV_EXPORTS_W TickMeter
{
public:
    CV_WRAP TickMeter()
    {
        reset();
    }
 
    CV_WRAP void start()
    {
        startTime = cv::getTickCount();
    }
 
    CV_WRAP void stop()
    {
        int64 time = cv::getTickCount();
        if (startTime == 0)
            return;
        ++counter;
        sumTime += (time - startTime);
        startTime = 0;
    }
 
    CV_WRAP int64 getTimeTicks() const
    {
        return sumTime;
    }
 
    CV_WRAP double getTimeMicro() const
    {
        return getTimeMilli()*1e3;
    }
 
    CV_WRAP double getTimeMilli() const
    {
        return getTimeSec()*1e3;
    }
 
    CV_WRAP double getTimeSec()   const
    {
        return (double)getTimeTicks() / getTickFrequency();
    }
 
    CV_WRAP int64 getCounter() const
    {
        return counter;
    }
 
    CV_WRAP double getFPS() const
    {
        const double sec = getTimeSec();
        if (sec < DBL_EPSILON)
            return 0.;
        return counter / sec;
    }
 
    CV_WRAP double getAvgTimeSec() const
    {
        if (counter <= 0)
            return 0.;
        return getTimeSec() / counter;
    }
 
    CV_WRAP double getAvgTimeMilli() const
    {
        return getAvgTimeSec() * 1e3;
    }
 
    CV_WRAP void reset()
    {
        startTime = 0;
        sumTime = 0;
        counter = 0;
    }
 
private:
    int64 counter;
    int64 sumTime;
    int64 startTime;
};
 
static inline
std::ostream& operator << (std::ostream& out, const TickMeter& tm)
{
    return out << tm.getTimeSec() << "sec";
}
 
CV_EXPORTS_W int64 getCPUTickCount();
 
CV_EXPORTS_W bool checkHardwareSupport(int feature);
 
CV_EXPORTS_W String getHardwareFeatureName(int feature);
 
CV_EXPORTS_W std::string getCPUFeaturesLine();
 
CV_EXPORTS_W int getNumberOfCPUs();
 
 
template<typename _Tp> static inline _Tp* alignPtr(_Tp* ptr, int n=(int)sizeof(_Tp))
{
    CV_DbgAssert((n & (n - 1)) == 0); // n is a power of 2
    return (_Tp*)(((size_t)ptr + n-1) & -n);
}
 
static inline size_t alignSize(size_t sz, int n)
{
    CV_DbgAssert((n & (n - 1)) == 0); // n is a power of 2
    return (sz + n-1) & -n;
}
 
static inline int divUp(int a, unsigned int b)
{
    CV_DbgAssert(a >= 0);
    return (a + b - 1) / b;
}
static inline size_t divUp(size_t a, unsigned int b)
{
    return (a + b - 1) / b;
}
 
static inline int roundUp(int a, unsigned int b)
{
    CV_DbgAssert(a >= 0);
    return a + b - 1 - (a + b -1) % b;
}
static inline size_t roundUp(size_t a, unsigned int b)
{
    return a + b - 1 - (a + b - 1) % b;
}
 
template<int N, typename T> static inline
bool isAligned(const T& data)
{
    CV_StaticAssert((N & (N - 1)) == 0, "");  // power of 2
    return (((size_t)data) & (N - 1)) == 0;
}
template<int N> static inline
bool isAligned(const void* p1)
{
    return isAligned<N>((size_t)p1);
}
template<int N> static inline
bool isAligned(const void* p1, const void* p2)
{
    return isAligned<N>(((size_t)p1)|((size_t)p2));
}
template<int N> static inline
bool isAligned(const void* p1, const void* p2, const void* p3)
{
    return isAligned<N>(((size_t)p1)|((size_t)p2)|((size_t)p3));
}
template<int N> static inline
bool isAligned(const void* p1, const void* p2, const void* p3, const void* p4)
{
    return isAligned<N>(((size_t)p1)|((size_t)p2)|((size_t)p3)|((size_t)p4));
}
 
CV_EXPORTS_W void setUseOptimized(bool onoff);
 
CV_EXPORTS_W bool useOptimized();
 
static inline size_t getElemSize(int type) { return (size_t)CV_ELEM_SIZE(type); }
 
 
class CV_EXPORTS ParallelLoopBody
{
public:
    virtual ~ParallelLoopBody();
    virtual void operator() (const Range& range) const = 0;
};
 
CV_EXPORTS void parallel_for_(const Range& range, const ParallelLoopBody& body, double nstripes=-1.);
 
class ParallelLoopBodyLambdaWrapper : public ParallelLoopBody
{
private:
    std::function<void(const Range&)> m_functor;
public:
    inline
    ParallelLoopBodyLambdaWrapper(std::function<void(const Range&)> functor)
        : m_functor(functor)
    {
        // nothing
    }
 
    virtual void operator() (const cv::Range& range) const CV_OVERRIDE
    {
        m_functor(range);
    }
};
 
static inline
void parallel_for_(const Range& range, std::function<void(const Range&)> functor, double nstripes=-1.)
{
    parallel_for_(range, ParallelLoopBodyLambdaWrapper(functor), nstripes);
}
 
 
template<typename _Tp, typename Functor> inline
void Mat::forEach_impl(const Functor& operation) {
    if (false) {
        operation(*reinterpret_cast<_Tp*>(0), reinterpret_cast<int*>(0));
        // If your compiler fails in this line.
        // Please check that your functor signature is
        //     (_Tp&, const int*)   <- multi-dimensional
        //  or (_Tp&, void*)        <- in case you don't need current idx.
    }
 
    CV_Assert(!empty());
    CV_Assert(this->total() / this->size[this->dims - 1] <= INT_MAX);
    const int LINES = static_cast<int>(this->total() / this->size[this->dims - 1]);
 
    class PixelOperationWrapper :public ParallelLoopBody
    {
    public:
        PixelOperationWrapper(Mat_<_Tp>* const frame, const Functor& _operation)
            : mat(frame), op(_operation) {}
        virtual ~PixelOperationWrapper(){}
        // ! Overloaded virtual operator
        // convert range call to row call.
        virtual void operator()(const Range &range) const CV_OVERRIDE
        {
            const int DIMS = mat->dims;
            const int COLS = mat->size[DIMS - 1];
            if (DIMS <= 2) {
                for (int row = range.start; row < range.end; ++row) {
                    this->rowCall2(row, COLS);
                }
            } else {
                std::vector<int> idx(DIMS); 
                idx[DIMS - 2] = range.start - 1;
 
                for (int line_num = range.start; line_num < range.end; ++line_num) {
                    idx[DIMS - 2]++;
                    for (int i = DIMS - 2; i >= 0; --i) {
                        if (idx[i] >= mat->size[i]) {
                            idx[i - 1] += idx[i] / mat->size[i];
                            idx[i] %= mat->size[i];
                            continue; // carry-over;
                        }
                        else {
                            break;
                        }
                    }
                    this->rowCall(&idx[0], COLS, DIMS);
                }
            }
        }
    private:
        Mat_<_Tp>* const mat;
        const Functor op;
        // ! Call operator for each elements in this row.
        inline void rowCall(int* const idx, const int COLS, const int DIMS) const {
            int &col = idx[DIMS - 1];
            col = 0;
            _Tp* pixel = &(mat->template at<_Tp>(idx));
 
            while (col < COLS) {
                op(*pixel, const_cast<const int*>(idx));
                pixel++; col++;
            }
            col = 0;
        }
        // ! Call operator for each elements in this row. 2d mat special version.
        inline void rowCall2(const int row, const int COLS) const {
            union Index{
                int body[2];
                operator const int*() const {
                    return reinterpret_cast<const int*>(this);
                }
                int& operator[](const int i) {
                    return body[i];
                }
            } idx = {{row, 0}};
            // Special union is needed to avoid
            // "error: array subscript is above array bounds [-Werror=array-bounds]"
            // when call the functor `op` such that access idx[3].
 
            _Tp* pixel = &(mat->template at<_Tp>(idx));
            const _Tp* const pixel_end = pixel + COLS;
            while(pixel < pixel_end) {
                op(*pixel++, static_cast<const int*>(idx));
                idx[1]++;
            }
        }
        PixelOperationWrapper& operator=(const PixelOperationWrapper &) {
            CV_Assert(false);
            // We can not remove this implementation because Visual Studio warning C4822.
            return *this;
        }
    };
 
    parallel_for_(cv::Range(0, LINES), PixelOperationWrapper(reinterpret_cast<Mat_<_Tp>*>(this), operation));
}
 
 
#if !defined(_M_CEE)
#ifndef OPENCV_DISABLE_THREAD_SUPPORT
typedef std::recursive_mutex Mutex;
typedef std::lock_guard<cv::Mutex> AutoLock;
#else // OPENCV_DISABLE_THREAD_SUPPORT
// Custom (failing) implementation of `std::recursive_mutex`.
struct Mutex {
    void lock(){
        CV_Error(cv::Error::StsNotImplemented,
                 "cv::Mutex is disabled by OPENCV_DISABLE_THREAD_SUPPORT=ON");
    }
    void unlock(){
        CV_Error(cv::Error::StsNotImplemented,
                 "cv::Mutex is disabled by OPENCV_DISABLE_THREAD_SUPPORT=ON");
    }
};
// Stub for cv::AutoLock when threads are disabled.
struct AutoLock {
    AutoLock(Mutex &) { }
};
#endif // OPENCV_DISABLE_THREAD_SUPPORT
#endif // !defined(_M_CEE)
 
 
class CV_EXPORTS CommandLineParser
{
public:
 
    CommandLineParser(int argc, const char* const argv[], const String& keys);
 
    CommandLineParser(const CommandLineParser& parser);
 
    CommandLineParser& operator = (const CommandLineParser& parser);
 
    ~CommandLineParser();
 
    String getPathToApplication() const;
 
    template <typename T>
    T get(const String& name, bool space_delete = true) const
    {
        T val = T();
        getByName(name, space_delete, ParamType<T>::type, (void*)&val);
        return val;
    }
 
    template <typename T>
    T get(int index, bool space_delete = true) const
    {
        T val = T();
        getByIndex(index, space_delete, ParamType<T>::type, (void*)&val);
        return val;
    }
 
    bool has(const String& name) const;
 
    bool check() const;
 
    void about(const String& message);
 
    void printMessage() const;
 
    void printErrors() const;
 
protected:
    void getByName(const String& name, bool space_delete, Param type, void* dst) const;
    void getByIndex(int index, bool space_delete, Param type, void* dst) const;
 
    struct Impl;
    Impl* impl;
};
 
 
 
 
template<typename _Tp, size_t fixed_size> inline
AutoBuffer<_Tp, fixed_size>::AutoBuffer()
{
    ptr = buf;
    sz = fixed_size;
}
 
template<typename _Tp, size_t fixed_size> inline
AutoBuffer<_Tp, fixed_size>::AutoBuffer(size_t _size)
{
    ptr = buf;
    sz = fixed_size;
    allocate(_size);
}
 
template<typename _Tp, size_t fixed_size> inline
AutoBuffer<_Tp, fixed_size>::AutoBuffer(const AutoBuffer<_Tp, fixed_size>& abuf )
{
    ptr = buf;
    sz = fixed_size;
    allocate(abuf.size());
    for( size_t i = 0; i < sz; i++ )
        ptr[i] = abuf.ptr[i];
}
 
template<typename _Tp, size_t fixed_size> inline AutoBuffer<_Tp, fixed_size>&
AutoBuffer<_Tp, fixed_size>::operator = (const AutoBuffer<_Tp, fixed_size>& abuf)
{
    if( this != &abuf )
    {
        deallocate();
        allocate(abuf.size());
        for( size_t i = 0; i < sz; i++ )
            ptr[i] = abuf.ptr[i];
    }
    return *this;
}
 
template<typename _Tp, size_t fixed_size> inline
AutoBuffer<_Tp, fixed_size>::~AutoBuffer()
{ deallocate(); }
 
template<typename _Tp, size_t fixed_size> inline void
AutoBuffer<_Tp, fixed_size>::allocate(size_t _size)
{
    if(_size <= sz)
    {
        sz = _size;
        return;
    }
    deallocate();
    sz = _size;
    if(_size > fixed_size)
    {
        ptr = new _Tp[_size];
    }
}
 
template<typename _Tp, size_t fixed_size> inline void
AutoBuffer<_Tp, fixed_size>::deallocate()
{
    if( ptr != buf )
    {
        delete[] ptr;
        ptr = buf;
        sz = fixed_size;
    }
}
 
template<typename _Tp, size_t fixed_size> inline void
AutoBuffer<_Tp, fixed_size>::resize(size_t _size)
{
    if(_size <= sz)
    {
        sz = _size;
        return;
    }
    size_t i, prevsize = sz, minsize = MIN(prevsize, _size);
    _Tp* prevptr = ptr;
 
    ptr = _size > fixed_size ? new _Tp[_size] : buf;
    sz = _size;
 
    if( ptr != prevptr )
        for( i = 0; i < minsize; i++ )
            ptr[i] = prevptr[i];
    for( i = prevsize; i < _size; i++ )
        ptr[i] = _Tp();
 
    if( prevptr != buf )
        delete[] prevptr;
}
 
template<typename _Tp, size_t fixed_size> inline size_t
AutoBuffer<_Tp, fixed_size>::size() const
{ return sz; }
 
 
 
// Basic Node class for tree building
template<class OBJECT>
class CV_EXPORTS Node
{
public:
    Node()
    {
        m_pParent  = 0;
    }
    Node(OBJECT& payload) : m_payload(payload)
    {
        m_pParent  = 0;
    }
    ~Node()
    {
        removeChilds();
        if (m_pParent)
        {
            int idx = m_pParent->findChild(this);
            if (idx >= 0)
                m_pParent->m_childs.erase(m_pParent->m_childs.begin() + idx);
        }
    }
 
    Node<OBJECT>* findChild(OBJECT& payload) const
    {
        for(size_t i = 0; i < this->m_childs.size(); i++)
        {
            if(this->m_childs[i]->m_payload == payload)
                return this->m_childs[i];
        }
        return NULL;
    }
 
    int findChild(Node<OBJECT> *pNode) const
    {
        for (size_t i = 0; i < this->m_childs.size(); i++)
        {
            if(this->m_childs[i] == pNode)
                return (int)i;
        }
        return -1;
    }
 
    void addChild(Node<OBJECT> *pNode)
    {
        if(!pNode)
            return;
 
        CV_Assert(pNode->m_pParent == 0);
        pNode->m_pParent = this;
        this->m_childs.push_back(pNode);
    }
 
    void removeChilds()
    {
        for(size_t i = 0; i < m_childs.size(); i++)
        {
            m_childs[i]->m_pParent = 0; // avoid excessive parent vector trimming
            delete m_childs[i];
        }
        m_childs.clear();
    }
 
    int getDepth()
    {
        int   count   = 0;
        Node *pParent = m_pParent;
        while(pParent) count++, pParent = pParent->m_pParent;
        return count;
    }
 
public:
    OBJECT                     m_payload;
    Node<OBJECT>*              m_pParent;
    std::vector<Node<OBJECT>*> m_childs;
};
 
 
namespace samples {
 
// This section describes utility functions for OpenCV samples.
//
// @note Implementation of these utilities is not thread-safe.
//
 
CV_EXPORTS_W cv::String findFile(const cv::String& relative_path, bool required = true, bool silentMode = false);
 
CV_EXPORTS_W cv::String findFileOrKeep(const cv::String& relative_path, bool silentMode = false);
 
inline cv::String findFileOrKeep(const cv::String& relative_path, bool silentMode)
{
    cv::String res = findFile(relative_path, false, silentMode);
    if (res.empty())
        return relative_path;
    return res;
}
 
CV_EXPORTS_W void addSamplesDataSearchPath(const cv::String& path);
 
CV_EXPORTS_W void addSamplesDataSearchSubDirectory(const cv::String& subdir);
 
} // namespace samples
 
namespace utils {
 
CV_EXPORTS int getThreadID();
 
} // namespace
 
} //namespace cv
 
#ifdef CV_COLLECT_IMPL_DATA
#include "opencv2/core/utils/instrumentation.hpp"
#else
#define CV_IMPL_ADD(impl)
#endif
 
#endif //OPENCV_CORE_UTILITY_H