Joe Verbout / Mbed 2 deprecated main

opencv on mbed

Dependencies:   mbed

opencv2/core/utility.hpp@0:ea44dc9ed014, 2016-03-31 (annotated)

Committer:
joeverbout
Date:
Thu Mar 31 21:16:38 2016 +0000
Revision:
0:ea44dc9ed014
OpenCV on mbed attempt

Who changed what in which revision?

UserRevisionLine numberNew contents of line
joeverbout 0:ea44dc9ed014 1 /*M///////////////////////////////////////////////////////////////////////////////////////
joeverbout 0:ea44dc9ed014 2 //
joeverbout 0:ea44dc9ed014 3 // IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
joeverbout 0:ea44dc9ed014 4 //
joeverbout 0:ea44dc9ed014 5 // By downloading, copying, installing or using the software you agree to this license.
joeverbout 0:ea44dc9ed014 6 // If you do not agree to this license, do not download, install,
joeverbout 0:ea44dc9ed014 7 // copy or use the software.
joeverbout 0:ea44dc9ed014 8 //
joeverbout 0:ea44dc9ed014 9 //
joeverbout 0:ea44dc9ed014 10 // License Agreement
joeverbout 0:ea44dc9ed014 11 // For Open Source Computer Vision Library
joeverbout 0:ea44dc9ed014 12 //
joeverbout 0:ea44dc9ed014 13 // Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
joeverbout 0:ea44dc9ed014 14 // Copyright (C) 2009, Willow Garage Inc., all rights reserved.
joeverbout 0:ea44dc9ed014 15 // Copyright (C) 2013, OpenCV Foundation, all rights reserved.
joeverbout 0:ea44dc9ed014 16 // Copyright (C) 2015, Itseez Inc., all rights reserved.
joeverbout 0:ea44dc9ed014 17 // Third party copyrights are property of their respective owners.
joeverbout 0:ea44dc9ed014 18 //
joeverbout 0:ea44dc9ed014 19 // Redistribution and use in source and binary forms, with or without modification,
joeverbout 0:ea44dc9ed014 20 // are permitted provided that the following conditions are met:
joeverbout 0:ea44dc9ed014 21 //
joeverbout 0:ea44dc9ed014 22 // * Redistribution's of source code must retain the above copyright notice,
joeverbout 0:ea44dc9ed014 23 // this list of conditions and the following disclaimer.
joeverbout 0:ea44dc9ed014 24 //
joeverbout 0:ea44dc9ed014 25 // * Redistribution's in binary form must reproduce the above copyright notice,
joeverbout 0:ea44dc9ed014 26 // this list of conditions and the following disclaimer in the documentation
joeverbout 0:ea44dc9ed014 27 // and/or other materials provided with the distribution.
joeverbout 0:ea44dc9ed014 28 //
joeverbout 0:ea44dc9ed014 29 // * The name of the copyright holders may not be used to endorse or promote products
joeverbout 0:ea44dc9ed014 30 // derived from this software without specific prior written permission.
joeverbout 0:ea44dc9ed014 31 //
joeverbout 0:ea44dc9ed014 32 // This software is provided by the copyright holders and contributors "as is" and
joeverbout 0:ea44dc9ed014 33 // any express or implied warranties, including, but not limited to, the implied
joeverbout 0:ea44dc9ed014 34 // warranties of merchantability and fitness for a particular purpose are disclaimed.
joeverbout 0:ea44dc9ed014 35 // In no event shall the Intel Corporation or contributors be liable for any direct,
joeverbout 0:ea44dc9ed014 36 // indirect, incidental, special, exemplary, or consequential damages
joeverbout 0:ea44dc9ed014 37 // (including, but not limited to, procurement of substitute goods or services;
joeverbout 0:ea44dc9ed014 38 // loss of use, data, or profits; or business interruption) however caused
joeverbout 0:ea44dc9ed014 39 // and on any theory of liability, whether in contract, strict liability,
joeverbout 0:ea44dc9ed014 40 // or tort (including negligence or otherwise) arising in any way out of
joeverbout 0:ea44dc9ed014 41 // the use of this software, even if advised of the possibility of such damage.
joeverbout 0:ea44dc9ed014 42 //
joeverbout 0:ea44dc9ed014 43 //M*/
joeverbout 0:ea44dc9ed014 44
joeverbout 0:ea44dc9ed014 45 #ifndef __OPENCV_CORE_UTILITY_H__
joeverbout 0:ea44dc9ed014 46 #define __OPENCV_CORE_UTILITY_H__
joeverbout 0:ea44dc9ed014 47
joeverbout 0:ea44dc9ed014 48 #ifndef __cplusplus
joeverbout 0:ea44dc9ed014 49 # error utility.hpp header must be compiled as C++
joeverbout 0:ea44dc9ed014 50 #endif
joeverbout 0:ea44dc9ed014 51
joeverbout 0:ea44dc9ed014 52 #include "opencv2/core.hpp"
joeverbout 0:ea44dc9ed014 53
joeverbout 0:ea44dc9ed014 54 namespace cv
joeverbout 0:ea44dc9ed014 55 {
joeverbout 0:ea44dc9ed014 56
joeverbout 0:ea44dc9ed014 57 #ifdef CV_COLLECT_IMPL_DATA
joeverbout 0:ea44dc9ed014 58 CV_EXPORTS void setImpl(int flags); // set implementation flags and reset storage arrays
joeverbout 0:ea44dc9ed014 59 CV_EXPORTS void addImpl(int flag, const char* func = 0); // add implementation and function name to storage arrays
joeverbout 0:ea44dc9ed014 60 // Get stored implementation flags and fucntions names arrays
joeverbout 0:ea44dc9ed014 61 // Each implementation entry correspond to function name entry, so you can find which implementation was executed in which fucntion
joeverbout 0:ea44dc9ed014 62 CV_EXPORTS int getImpl(std::vector<int> &impl, std::vector<String> &funName);
joeverbout 0:ea44dc9ed014 63
joeverbout 0:ea44dc9ed014 64 CV_EXPORTS bool useCollection(); // return implementation collection state
joeverbout 0:ea44dc9ed014 65 CV_EXPORTS void setUseCollection(bool flag); // set implementation collection state
joeverbout 0:ea44dc9ed014 66
joeverbout 0:ea44dc9ed014 67 #define CV_IMPL_PLAIN 0x01 // native CPU OpenCV implementation
joeverbout 0:ea44dc9ed014 68 #define CV_IMPL_OCL 0x02 // OpenCL implementation
joeverbout 0:ea44dc9ed014 69 #define CV_IMPL_IPP 0x04 // IPP implementation
joeverbout 0:ea44dc9ed014 70 #define CV_IMPL_MT 0x10 // multithreaded implementation
joeverbout 0:ea44dc9ed014 71
joeverbout 0:ea44dc9ed014 72 #define CV_IMPL_ADD(impl) \
joeverbout 0:ea44dc9ed014 73 if(cv::useCollection()) \
joeverbout 0:ea44dc9ed014 74 { \
joeverbout 0:ea44dc9ed014 75 cv::addImpl(impl, CV_Func); \
joeverbout 0:ea44dc9ed014 76 }
joeverbout 0:ea44dc9ed014 77 #else
joeverbout 0:ea44dc9ed014 78 #define CV_IMPL_ADD(impl)
joeverbout 0:ea44dc9ed014 79 #endif
joeverbout 0:ea44dc9ed014 80
joeverbout 0:ea44dc9ed014 81 //! @addtogroup core_utils
joeverbout 0:ea44dc9ed014 82 //! @{
joeverbout 0:ea44dc9ed014 83
joeverbout 0:ea44dc9ed014 84 /** @brief Automatically Allocated Buffer Class
joeverbout 0:ea44dc9ed014 85
joeverbout 0:ea44dc9ed014 86 The class is used for temporary buffers in functions and methods.
joeverbout 0:ea44dc9ed014 87 If a temporary buffer is usually small (a few K's of memory),
joeverbout 0:ea44dc9ed014 88 but its size depends on the parameters, it makes sense to create a small
joeverbout 0:ea44dc9ed014 89 fixed-size array on stack and use it if it's large enough. If the required buffer size
joeverbout 0:ea44dc9ed014 90 is larger than the fixed size, another buffer of sufficient size is allocated dynamically
joeverbout 0:ea44dc9ed014 91 and released after the processing. Therefore, in typical cases, when the buffer size is small,
joeverbout 0:ea44dc9ed014 92 there is no overhead associated with malloc()/free().
joeverbout 0:ea44dc9ed014 93 At the same time, there is no limit on the size of processed data.
joeverbout 0:ea44dc9ed014 94
joeverbout 0:ea44dc9ed014 95 This is what AutoBuffer does. The template takes 2 parameters - type of the buffer elements and
joeverbout 0:ea44dc9ed014 96 the number of stack-allocated elements. Here is how the class is used:
joeverbout 0:ea44dc9ed014 97
joeverbout 0:ea44dc9ed014 98 \code
joeverbout 0:ea44dc9ed014 99 void my_func(const cv::Mat& m)
joeverbout 0:ea44dc9ed014 100 {
joeverbout 0:ea44dc9ed014 101 cv::AutoBuffer<float> buf; // create automatic buffer containing 1000 floats
joeverbout 0:ea44dc9ed014 102
joeverbout 0:ea44dc9ed014 103 buf.allocate(m.rows); // if m.rows <= 1000, the pre-allocated buffer is used,
joeverbout 0:ea44dc9ed014 104 // otherwise the buffer of "m.rows" floats will be allocated
joeverbout 0:ea44dc9ed014 105 // dynamically and deallocated in cv::AutoBuffer destructor
joeverbout 0:ea44dc9ed014 106 ...
joeverbout 0:ea44dc9ed014 107 }
joeverbout 0:ea44dc9ed014 108 \endcode
joeverbout 0:ea44dc9ed014 109 */
joeverbout 0:ea44dc9ed014 110 template<typename _Tp, size_t fixed_size = 1024/sizeof(_Tp)+8> class AutoBuffer
joeverbout 0:ea44dc9ed014 111 {
joeverbout 0:ea44dc9ed014 112 public:
joeverbout 0:ea44dc9ed014 113 typedef _Tp value_type;
joeverbout 0:ea44dc9ed014 114
joeverbout 0:ea44dc9ed014 115 //! the default constructor
joeverbout 0:ea44dc9ed014 116 AutoBuffer();
joeverbout 0:ea44dc9ed014 117 //! constructor taking the real buffer size
joeverbout 0:ea44dc9ed014 118 AutoBuffer(size_t _size);
joeverbout 0:ea44dc9ed014 119
joeverbout 0:ea44dc9ed014 120 //! the copy constructor
joeverbout 0:ea44dc9ed014 121 AutoBuffer(const AutoBuffer<_Tp, fixed_size>& buf);
joeverbout 0:ea44dc9ed014 122 //! the assignment operator
joeverbout 0:ea44dc9ed014 123 AutoBuffer<_Tp, fixed_size>& operator = (const AutoBuffer<_Tp, fixed_size>& buf);
joeverbout 0:ea44dc9ed014 124
joeverbout 0:ea44dc9ed014 125 //! destructor. calls deallocate()
joeverbout 0:ea44dc9ed014 126 ~AutoBuffer();
joeverbout 0:ea44dc9ed014 127
joeverbout 0:ea44dc9ed014 128 //! allocates the new buffer of size _size. if the _size is small enough, stack-allocated buffer is used
joeverbout 0:ea44dc9ed014 129 void allocate(size_t _size);
joeverbout 0:ea44dc9ed014 130 //! deallocates the buffer if it was dynamically allocated
joeverbout 0:ea44dc9ed014 131 void deallocate();
joeverbout 0:ea44dc9ed014 132 //! resizes the buffer and preserves the content
joeverbout 0:ea44dc9ed014 133 void resize(size_t _size);
joeverbout 0:ea44dc9ed014 134 //! returns the current buffer size
joeverbout 0:ea44dc9ed014 135 size_t size() const;
joeverbout 0:ea44dc9ed014 136 //! returns pointer to the real buffer, stack-allocated or head-allocated
joeverbout 0:ea44dc9ed014 137 operator _Tp* ();
joeverbout 0:ea44dc9ed014 138 //! returns read-only pointer to the real buffer, stack-allocated or head-allocated
joeverbout 0:ea44dc9ed014 139 operator const _Tp* () const;
joeverbout 0:ea44dc9ed014 140
joeverbout 0:ea44dc9ed014 141 protected:
joeverbout 0:ea44dc9ed014 142 //! pointer to the real buffer, can point to buf if the buffer is small enough
joeverbout 0:ea44dc9ed014 143 _Tp* ptr;
joeverbout 0:ea44dc9ed014 144 //! size of the real buffer
joeverbout 0:ea44dc9ed014 145 size_t sz;
joeverbout 0:ea44dc9ed014 146 //! pre-allocated buffer. At least 1 element to confirm C++ standard reqirements
joeverbout 0:ea44dc9ed014 147 _Tp buf[(fixed_size > 0) ? fixed_size : 1];
joeverbout 0:ea44dc9ed014 148 };
joeverbout 0:ea44dc9ed014 149
joeverbout 0:ea44dc9ed014 150 /** @brief Sets/resets the break-on-error mode.
joeverbout 0:ea44dc9ed014 151
joeverbout 0:ea44dc9ed014 152 When the break-on-error mode is set, the default error handler issues a hardware exception, which
joeverbout 0:ea44dc9ed014 153 can make debugging more convenient.
joeverbout 0:ea44dc9ed014 154
joeverbout 0:ea44dc9ed014 155 \return the previous state
joeverbout 0:ea44dc9ed014 156 */
joeverbout 0:ea44dc9ed014 157 CV_EXPORTS bool setBreakOnError(bool flag);
joeverbout 0:ea44dc9ed014 158
joeverbout 0:ea44dc9ed014 159 extern "C" typedef int (*ErrorCallback)( int status, const char* func_name,
joeverbout 0:ea44dc9ed014 160 const char* err_msg, const char* file_name,
joeverbout 0:ea44dc9ed014 161 int line, void* userdata );
joeverbout 0:ea44dc9ed014 162
joeverbout 0:ea44dc9ed014 163
joeverbout 0:ea44dc9ed014 164 /** @brief Sets the new error handler and the optional user data.
joeverbout 0:ea44dc9ed014 165
joeverbout 0:ea44dc9ed014 166 The function sets the new error handler, called from cv::error().
joeverbout 0:ea44dc9ed014 167
joeverbout 0:ea44dc9ed014 168 \param errCallback the new error handler. If NULL, the default error handler is used.
joeverbout 0:ea44dc9ed014 169 \param userdata the optional user data pointer, passed to the callback.
joeverbout 0:ea44dc9ed014 170 \param prevUserdata the optional output parameter where the previous user data pointer is stored
joeverbout 0:ea44dc9ed014 171
joeverbout 0:ea44dc9ed014 172 \return the previous error handler
joeverbout 0:ea44dc9ed014 173 */
joeverbout 0:ea44dc9ed014 174 CV_EXPORTS ErrorCallback redirectError( ErrorCallback errCallback, void* userdata=0, void** prevUserdata=0);
joeverbout 0:ea44dc9ed014 175
joeverbout 0:ea44dc9ed014 176 /** @brief Returns a text string formatted using the printf-like expression.
joeverbout 0:ea44dc9ed014 177
joeverbout 0:ea44dc9ed014 178 The function acts like sprintf but forms and returns an STL string. It can be used to form an error
joeverbout 0:ea44dc9ed014 179 message in the Exception constructor.
joeverbout 0:ea44dc9ed014 180 @param fmt printf-compatible formatting specifiers.
joeverbout 0:ea44dc9ed014 181 */
joeverbout 0:ea44dc9ed014 182 CV_EXPORTS String format( const char* fmt, ... );
joeverbout 0:ea44dc9ed014 183 CV_EXPORTS String tempfile( const char* suffix = 0);
joeverbout 0:ea44dc9ed014 184 CV_EXPORTS void glob(String pattern, std::vector<String>& result, bool recursive = false);
joeverbout 0:ea44dc9ed014 185
joeverbout 0:ea44dc9ed014 186 /** @brief OpenCV will try to set the number of threads for the next parallel region.
joeverbout 0:ea44dc9ed014 187
joeverbout 0:ea44dc9ed014 188 If threads == 0, OpenCV will disable threading optimizations and run all it's functions
joeverbout 0:ea44dc9ed014 189 sequentially. Passing threads \< 0 will reset threads number to system default. This function must
joeverbout 0:ea44dc9ed014 190 be called outside of parallel region.
joeverbout 0:ea44dc9ed014 191
joeverbout 0:ea44dc9ed014 192 OpenCV will try to run it's functions with specified threads number, but some behaviour differs from
joeverbout 0:ea44dc9ed014 193 framework:
joeverbout 0:ea44dc9ed014 194 - `TBB` – User-defined parallel constructions will run with the same threads number, if
joeverbout 0:ea44dc9ed014 195 another does not specified. If late on user creates own scheduler, OpenCV will be use it.
joeverbout 0:ea44dc9ed014 196 - `OpenMP` – No special defined behaviour.
joeverbout 0:ea44dc9ed014 197 - `Concurrency` – If threads == 1, OpenCV will disable threading optimizations and run it's
joeverbout 0:ea44dc9ed014 198 functions sequentially.
joeverbout 0:ea44dc9ed014 199 - `GCD` – Supports only values \<= 0.
joeverbout 0:ea44dc9ed014 200 - `C=` – No special defined behaviour.
joeverbout 0:ea44dc9ed014 201 @param nthreads Number of threads used by OpenCV.
joeverbout 0:ea44dc9ed014 202 @sa getNumThreads, getThreadNum
joeverbout 0:ea44dc9ed014 203 */
joeverbout 0:ea44dc9ed014 204 CV_EXPORTS_W void setNumThreads(int nthreads);
joeverbout 0:ea44dc9ed014 205
joeverbout 0:ea44dc9ed014 206 /** @brief Returns the number of threads used by OpenCV for parallel regions.
joeverbout 0:ea44dc9ed014 207
joeverbout 0:ea44dc9ed014 208 Always returns 1 if OpenCV is built without threading support.
joeverbout 0:ea44dc9ed014 209
joeverbout 0:ea44dc9ed014 210 The exact meaning of return value depends on the threading framework used by OpenCV library:
joeverbout 0:ea44dc9ed014 211 - `TBB` – The number of threads, that OpenCV will try to use for parallel regions. If there is
joeverbout 0:ea44dc9ed014 212 any tbb::thread_scheduler_init in user code conflicting with OpenCV, then function returns
joeverbout 0:ea44dc9ed014 213 default number of threads used by TBB library.
joeverbout 0:ea44dc9ed014 214 - `OpenMP` – An upper bound on the number of threads that could be used to form a new team.
joeverbout 0:ea44dc9ed014 215 - `Concurrency` – The number of threads, that OpenCV will try to use for parallel regions.
joeverbout 0:ea44dc9ed014 216 - `GCD` – Unsupported; returns the GCD thread pool limit (512) for compatibility.
joeverbout 0:ea44dc9ed014 217 - `C=` – The number of threads, that OpenCV will try to use for parallel regions, if before
joeverbout 0:ea44dc9ed014 218 called setNumThreads with threads \> 0, otherwise returns the number of logical CPUs,
joeverbout 0:ea44dc9ed014 219 available for the process.
joeverbout 0:ea44dc9ed014 220 @sa setNumThreads, getThreadNum
joeverbout 0:ea44dc9ed014 221 */
joeverbout 0:ea44dc9ed014 222 CV_EXPORTS_W int getNumThreads();
joeverbout 0:ea44dc9ed014 223
joeverbout 0:ea44dc9ed014 224 /** @brief Returns the index of the currently executed thread within the current parallel region. Always
joeverbout 0:ea44dc9ed014 225 returns 0 if called outside of parallel region.
joeverbout 0:ea44dc9ed014 226
joeverbout 0:ea44dc9ed014 227 The exact meaning of return value depends on the threading framework used by OpenCV library:
joeverbout 0:ea44dc9ed014 228 - `TBB` – Unsupported with current 4.1 TBB release. May be will be supported in future.
joeverbout 0:ea44dc9ed014 229 - `OpenMP` – The thread number, within the current team, of the calling thread.
joeverbout 0:ea44dc9ed014 230 - `Concurrency` – An ID for the virtual processor that the current context is executing on (0
joeverbout 0:ea44dc9ed014 231 for master thread and unique number for others, but not necessary 1,2,3,...).
joeverbout 0:ea44dc9ed014 232 - `GCD` – System calling thread's ID. Never returns 0 inside parallel region.
joeverbout 0:ea44dc9ed014 233 - `C=` – The index of the current parallel task.
joeverbout 0:ea44dc9ed014 234 @sa setNumThreads, getNumThreads
joeverbout 0:ea44dc9ed014 235 */
joeverbout 0:ea44dc9ed014 236 CV_EXPORTS_W int getThreadNum();
joeverbout 0:ea44dc9ed014 237
joeverbout 0:ea44dc9ed014 238 /** @brief Returns full configuration time cmake output.
joeverbout 0:ea44dc9ed014 239
joeverbout 0:ea44dc9ed014 240 Returned value is raw cmake output including version control system revision, compiler version,
joeverbout 0:ea44dc9ed014 241 compiler flags, enabled modules and third party libraries, etc. Output format depends on target
joeverbout 0:ea44dc9ed014 242 architecture.
joeverbout 0:ea44dc9ed014 243 */
joeverbout 0:ea44dc9ed014 244 CV_EXPORTS_W const String& getBuildInformation();
joeverbout 0:ea44dc9ed014 245
joeverbout 0:ea44dc9ed014 246 /** @brief Returns the number of ticks.
joeverbout 0:ea44dc9ed014 247
joeverbout 0:ea44dc9ed014 248 The function returns the number of ticks after the certain event (for example, when the machine was
joeverbout 0:ea44dc9ed014 249 turned on). It can be used to initialize RNG or to measure a function execution time by reading the
joeverbout 0:ea44dc9ed014 250 tick count before and after the function call. See also the tick frequency.
joeverbout 0:ea44dc9ed014 251 */
joeverbout 0:ea44dc9ed014 252 CV_EXPORTS_W int64 getTickCount();
joeverbout 0:ea44dc9ed014 253
joeverbout 0:ea44dc9ed014 254 /** @brief Returns the number of ticks per second.
joeverbout 0:ea44dc9ed014 255
joeverbout 0:ea44dc9ed014 256 The function returns the number of ticks per second. That is, the following code computes the
joeverbout 0:ea44dc9ed014 257 execution time in seconds:
joeverbout 0:ea44dc9ed014 258 @code
joeverbout 0:ea44dc9ed014 259 double t = (double)getTickCount();
joeverbout 0:ea44dc9ed014 260 // do something ...
joeverbout 0:ea44dc9ed014 261 t = ((double)getTickCount() - t)/getTickFrequency();
joeverbout 0:ea44dc9ed014 262 @endcode
joeverbout 0:ea44dc9ed014 263 */
joeverbout 0:ea44dc9ed014 264 CV_EXPORTS_W double getTickFrequency();
joeverbout 0:ea44dc9ed014 265
joeverbout 0:ea44dc9ed014 266 /** @brief Returns the number of CPU ticks.
joeverbout 0:ea44dc9ed014 267
joeverbout 0:ea44dc9ed014 268 The function returns the current number of CPU ticks on some architectures (such as x86, x64,
joeverbout 0:ea44dc9ed014 269 PowerPC). On other platforms the function is equivalent to getTickCount. It can also be used for
joeverbout 0:ea44dc9ed014 270 very accurate time measurements, as well as for RNG initialization. Note that in case of multi-CPU
joeverbout 0:ea44dc9ed014 271 systems a thread, from which getCPUTickCount is called, can be suspended and resumed at another CPU
joeverbout 0:ea44dc9ed014 272 with its own counter. So, theoretically (and practically) the subsequent calls to the function do
joeverbout 0:ea44dc9ed014 273 not necessary return the monotonously increasing values. Also, since a modern CPU varies the CPU
joeverbout 0:ea44dc9ed014 274 frequency depending on the load, the number of CPU clocks spent in some code cannot be directly
joeverbout 0:ea44dc9ed014 275 converted to time units. Therefore, getTickCount is generally a preferable solution for measuring
joeverbout 0:ea44dc9ed014 276 execution time.
joeverbout 0:ea44dc9ed014 277 */
joeverbout 0:ea44dc9ed014 278 CV_EXPORTS_W int64 getCPUTickCount();
joeverbout 0:ea44dc9ed014 279
joeverbout 0:ea44dc9ed014 280 /** @brief Returns true if the specified feature is supported by the host hardware.
joeverbout 0:ea44dc9ed014 281
joeverbout 0:ea44dc9ed014 282 The function returns true if the host hardware supports the specified feature. When user calls
joeverbout 0:ea44dc9ed014 283 setUseOptimized(false), the subsequent calls to checkHardwareSupport() will return false until
joeverbout 0:ea44dc9ed014 284 setUseOptimized(true) is called. This way user can dynamically switch on and off the optimized code
joeverbout 0:ea44dc9ed014 285 in OpenCV.
joeverbout 0:ea44dc9ed014 286 @param feature The feature of interest, one of cv::CpuFeatures
joeverbout 0:ea44dc9ed014 287 */
joeverbout 0:ea44dc9ed014 288 CV_EXPORTS_W bool checkHardwareSupport(int feature);
joeverbout 0:ea44dc9ed014 289
joeverbout 0:ea44dc9ed014 290 /** @brief Returns the number of logical CPUs available for the process.
joeverbout 0:ea44dc9ed014 291 */
joeverbout 0:ea44dc9ed014 292 CV_EXPORTS_W int getNumberOfCPUs();
joeverbout 0:ea44dc9ed014 293
joeverbout 0:ea44dc9ed014 294
joeverbout 0:ea44dc9ed014 295 /** @brief Aligns a pointer to the specified number of bytes.
joeverbout 0:ea44dc9ed014 296
joeverbout 0:ea44dc9ed014 297 The function returns the aligned pointer of the same type as the input pointer:
joeverbout 0:ea44dc9ed014 298 \f[\texttt{(_Tp*)(((size_t)ptr + n-1) & -n)}\f]
joeverbout 0:ea44dc9ed014 299 @param ptr Aligned pointer.
joeverbout 0:ea44dc9ed014 300 @param n Alignment size that must be a power of two.
joeverbout 0:ea44dc9ed014 301 */
joeverbout 0:ea44dc9ed014 302 template<typename _Tp> static inline _Tp* alignPtr(_Tp* ptr, int n=(int)sizeof(_Tp))
joeverbout 0:ea44dc9ed014 303 {
joeverbout 0:ea44dc9ed014 304 return (_Tp*)(((size_t)ptr + n-1) & -n);
joeverbout 0:ea44dc9ed014 305 }
joeverbout 0:ea44dc9ed014 306
joeverbout 0:ea44dc9ed014 307 /** @brief Aligns a buffer size to the specified number of bytes.
joeverbout 0:ea44dc9ed014 308
joeverbout 0:ea44dc9ed014 309 The function returns the minimum number that is greater or equal to sz and is divisible by n :
joeverbout 0:ea44dc9ed014 310 \f[\texttt{(sz + n-1) & -n}\f]
joeverbout 0:ea44dc9ed014 311 @param sz Buffer size to align.
joeverbout 0:ea44dc9ed014 312 @param n Alignment size that must be a power of two.
joeverbout 0:ea44dc9ed014 313 */
joeverbout 0:ea44dc9ed014 314 static inline size_t alignSize(size_t sz, int n)
joeverbout 0:ea44dc9ed014 315 {
joeverbout 0:ea44dc9ed014 316 CV_DbgAssert((n & (n - 1)) == 0); // n is a power of 2
joeverbout 0:ea44dc9ed014 317 return (sz + n-1) & -n;
joeverbout 0:ea44dc9ed014 318 }
joeverbout 0:ea44dc9ed014 319
joeverbout 0:ea44dc9ed014 320 /** @brief Enables or disables the optimized code.
joeverbout 0:ea44dc9ed014 321
joeverbout 0:ea44dc9ed014 322 The function can be used to dynamically turn on and off optimized code (code that uses SSE2, AVX,
joeverbout 0:ea44dc9ed014 323 and other instructions on the platforms that support it). It sets a global flag that is further
joeverbout 0:ea44dc9ed014 324 checked by OpenCV functions. Since the flag is not checked in the inner OpenCV loops, it is only
joeverbout 0:ea44dc9ed014 325 safe to call the function on the very top level in your application where you can be sure that no
joeverbout 0:ea44dc9ed014 326 other OpenCV function is currently executed.
joeverbout 0:ea44dc9ed014 327
joeverbout 0:ea44dc9ed014 328 By default, the optimized code is enabled unless you disable it in CMake. The current status can be
joeverbout 0:ea44dc9ed014 329 retrieved using useOptimized.
joeverbout 0:ea44dc9ed014 330 @param onoff The boolean flag specifying whether the optimized code should be used (onoff=true)
joeverbout 0:ea44dc9ed014 331 or not (onoff=false).
joeverbout 0:ea44dc9ed014 332 */
joeverbout 0:ea44dc9ed014 333 CV_EXPORTS_W void setUseOptimized(bool onoff);
joeverbout 0:ea44dc9ed014 334
joeverbout 0:ea44dc9ed014 335 /** @brief Returns the status of optimized code usage.
joeverbout 0:ea44dc9ed014 336
joeverbout 0:ea44dc9ed014 337 The function returns true if the optimized code is enabled. Otherwise, it returns false.
joeverbout 0:ea44dc9ed014 338 */
joeverbout 0:ea44dc9ed014 339 CV_EXPORTS_W bool useOptimized();
joeverbout 0:ea44dc9ed014 340
joeverbout 0:ea44dc9ed014 341 static inline size_t getElemSize(int type) { return CV_ELEM_SIZE(type); }
joeverbout 0:ea44dc9ed014 342
joeverbout 0:ea44dc9ed014 343 /////////////////////////////// Parallel Primitives //////////////////////////////////
joeverbout 0:ea44dc9ed014 344
joeverbout 0:ea44dc9ed014 345 /** @brief Base class for parallel data processors
joeverbout 0:ea44dc9ed014 346 */
joeverbout 0:ea44dc9ed014 347 class CV_EXPORTS ParallelLoopBody
joeverbout 0:ea44dc9ed014 348 {
joeverbout 0:ea44dc9ed014 349 public:
joeverbout 0:ea44dc9ed014 350 virtual ~ParallelLoopBody();
joeverbout 0:ea44dc9ed014 351 virtual void operator() (const Range& range) const = 0;
joeverbout 0:ea44dc9ed014 352 };
joeverbout 0:ea44dc9ed014 353
joeverbout 0:ea44dc9ed014 354 /** @brief Parallel data processor
joeverbout 0:ea44dc9ed014 355 */
joeverbout 0:ea44dc9ed014 356 CV_EXPORTS void parallel_for_(const Range& range, const ParallelLoopBody& body, double nstripes=-1.);
joeverbout 0:ea44dc9ed014 357
joeverbout 0:ea44dc9ed014 358 /////////////////////////////// forEach method of cv::Mat ////////////////////////////
joeverbout 0:ea44dc9ed014 359 template<typename _Tp, typename Functor> inline
joeverbout 0:ea44dc9ed014 360 void Mat::forEach_impl(const Functor& operation) {
joeverbout 0:ea44dc9ed014 361 if (false) {
joeverbout 0:ea44dc9ed014 362 operation(*reinterpret_cast<_Tp*>(0), reinterpret_cast<int*>(NULL));
joeverbout 0:ea44dc9ed014 363 // If your compiler fail in this line.
joeverbout 0:ea44dc9ed014 364 // Please check that your functor signature is
joeverbout 0:ea44dc9ed014 365 // (_Tp&, const int*) <- multidimential
joeverbout 0:ea44dc9ed014 366 // or (_Tp&, void*) <- in case of you don't need current idx.
joeverbout 0:ea44dc9ed014 367 }
joeverbout 0:ea44dc9ed014 368
joeverbout 0:ea44dc9ed014 369 CV_Assert(this->total() / this->size[this->dims - 1] <= INT_MAX);
joeverbout 0:ea44dc9ed014 370 const int LINES = static_cast<int>(this->total() / this->size[this->dims - 1]);
joeverbout 0:ea44dc9ed014 371
joeverbout 0:ea44dc9ed014 372 class PixelOperationWrapper :public ParallelLoopBody
joeverbout 0:ea44dc9ed014 373 {
joeverbout 0:ea44dc9ed014 374 public:
joeverbout 0:ea44dc9ed014 375 PixelOperationWrapper(Mat_<_Tp>* const frame, const Functor& _operation)
joeverbout 0:ea44dc9ed014 376 : mat(frame), op(_operation) {};
joeverbout 0:ea44dc9ed014 377 virtual ~PixelOperationWrapper(){};
joeverbout 0:ea44dc9ed014 378 // ! Overloaded virtual operator
joeverbout 0:ea44dc9ed014 379 // convert range call to row call.
joeverbout 0:ea44dc9ed014 380 virtual void operator()(const Range &range) const {
joeverbout 0:ea44dc9ed014 381 const int DIMS = mat->dims;
joeverbout 0:ea44dc9ed014 382 const int COLS = mat->size[DIMS - 1];
joeverbout 0:ea44dc9ed014 383 if (DIMS <= 2) {
joeverbout 0:ea44dc9ed014 384 for (int row = range.start; row < range.end; ++row) {
joeverbout 0:ea44dc9ed014 385 this->rowCall2(row, COLS);
joeverbout 0:ea44dc9ed014 386 }
joeverbout 0:ea44dc9ed014 387 } else {
joeverbout 0:ea44dc9ed014 388 std::vector<int> idx(COLS); /// idx is modified in this->rowCall
joeverbout 0:ea44dc9ed014 389 idx[DIMS - 2] = range.start - 1;
joeverbout 0:ea44dc9ed014 390
joeverbout 0:ea44dc9ed014 391 for (int line_num = range.start; line_num < range.end; ++line_num) {
joeverbout 0:ea44dc9ed014 392 idx[DIMS - 2]++;
joeverbout 0:ea44dc9ed014 393 for (int i = DIMS - 2; i >= 0; --i) {
joeverbout 0:ea44dc9ed014 394 if (idx[i] >= mat->size[i]) {
joeverbout 0:ea44dc9ed014 395 idx[i - 1] += idx[i] / mat->size[i];
joeverbout 0:ea44dc9ed014 396 idx[i] %= mat->size[i];
joeverbout 0:ea44dc9ed014 397 continue; // carry-over;
joeverbout 0:ea44dc9ed014 398 }
joeverbout 0:ea44dc9ed014 399 else {
joeverbout 0:ea44dc9ed014 400 break;
joeverbout 0:ea44dc9ed014 401 }
joeverbout 0:ea44dc9ed014 402 }
joeverbout 0:ea44dc9ed014 403 this->rowCall(&idx[0], COLS, DIMS);
joeverbout 0:ea44dc9ed014 404 }
joeverbout 0:ea44dc9ed014 405 }
joeverbout 0:ea44dc9ed014 406 };
joeverbout 0:ea44dc9ed014 407 private:
joeverbout 0:ea44dc9ed014 408 Mat_<_Tp>* const mat;
joeverbout 0:ea44dc9ed014 409 const Functor op;
joeverbout 0:ea44dc9ed014 410 // ! Call operator for each elements in this row.
joeverbout 0:ea44dc9ed014 411 inline void rowCall(int* const idx, const int COLS, const int DIMS) const {
joeverbout 0:ea44dc9ed014 412 int &col = idx[DIMS - 1];
joeverbout 0:ea44dc9ed014 413 col = 0;
joeverbout 0:ea44dc9ed014 414 _Tp* pixel = &(mat->template at<_Tp>(idx));
joeverbout 0:ea44dc9ed014 415
joeverbout 0:ea44dc9ed014 416 while (col < COLS) {
joeverbout 0:ea44dc9ed014 417 op(*pixel, const_cast<const int*>(idx));
joeverbout 0:ea44dc9ed014 418 pixel++; col++;
joeverbout 0:ea44dc9ed014 419 }
joeverbout 0:ea44dc9ed014 420 col = 0;
joeverbout 0:ea44dc9ed014 421 }
joeverbout 0:ea44dc9ed014 422 // ! Call operator for each elements in this row. 2d mat special version.
joeverbout 0:ea44dc9ed014 423 inline void rowCall2(const int row, const int COLS) const {
joeverbout 0:ea44dc9ed014 424 union Index{
joeverbout 0:ea44dc9ed014 425 int body[2];
joeverbout 0:ea44dc9ed014 426 operator const int*() const {
joeverbout 0:ea44dc9ed014 427 return reinterpret_cast<const int*>(this);
joeverbout 0:ea44dc9ed014 428 }
joeverbout 0:ea44dc9ed014 429 int& operator[](const int i) {
joeverbout 0:ea44dc9ed014 430 return body[i];
joeverbout 0:ea44dc9ed014 431 }
joeverbout 0:ea44dc9ed014 432 } idx = {{row, 0}};
joeverbout 0:ea44dc9ed014 433 // Special union is needed to avoid
joeverbout 0:ea44dc9ed014 434 // "error: array subscript is above array bounds [-Werror=array-bounds]"
joeverbout 0:ea44dc9ed014 435 // when call the functor `op` such that access idx[3].
joeverbout 0:ea44dc9ed014 436
joeverbout 0:ea44dc9ed014 437 _Tp* pixel = &(mat->template at<_Tp>(idx));
joeverbout 0:ea44dc9ed014 438 const _Tp* const pixel_end = pixel + COLS;
joeverbout 0:ea44dc9ed014 439 while(pixel < pixel_end) {
joeverbout 0:ea44dc9ed014 440 op(*pixel++, static_cast<const int*>(idx));
joeverbout 0:ea44dc9ed014 441 idx[1]++;
joeverbout 0:ea44dc9ed014 442 }
joeverbout 0:ea44dc9ed014 443 };
joeverbout 0:ea44dc9ed014 444 PixelOperationWrapper& operator=(const PixelOperationWrapper &) {
joeverbout 0:ea44dc9ed014 445 CV_Assert(false);
joeverbout 0:ea44dc9ed014 446 // We can not remove this implementation because Visual Studio warning C4822.
joeverbout 0:ea44dc9ed014 447 return *this;
joeverbout 0:ea44dc9ed014 448 };
joeverbout 0:ea44dc9ed014 449 };
joeverbout 0:ea44dc9ed014 450
joeverbout 0:ea44dc9ed014 451 parallel_for_(cv::Range(0, LINES), PixelOperationWrapper(reinterpret_cast<Mat_<_Tp>*>(this), operation));
joeverbout 0:ea44dc9ed014 452 }
joeverbout 0:ea44dc9ed014 453
joeverbout 0:ea44dc9ed014 454 /////////////////////////// Synchronization Primitives ///////////////////////////////
joeverbout 0:ea44dc9ed014 455
joeverbout 0:ea44dc9ed014 456 class CV_EXPORTS Mutex
joeverbout 0:ea44dc9ed014 457 {
joeverbout 0:ea44dc9ed014 458 public:
joeverbout 0:ea44dc9ed014 459 Mutex();
joeverbout 0:ea44dc9ed014 460 ~Mutex();
joeverbout 0:ea44dc9ed014 461 Mutex(const Mutex& m);
joeverbout 0:ea44dc9ed014 462 Mutex& operator = (const Mutex& m);
joeverbout 0:ea44dc9ed014 463
joeverbout 0:ea44dc9ed014 464 void lock();
joeverbout 0:ea44dc9ed014 465 bool trylock();
joeverbout 0:ea44dc9ed014 466 void unlock();
joeverbout 0:ea44dc9ed014 467
joeverbout 0:ea44dc9ed014 468 struct Impl;
joeverbout 0:ea44dc9ed014 469 protected:
joeverbout 0:ea44dc9ed014 470 Impl* impl;
joeverbout 0:ea44dc9ed014 471 };
joeverbout 0:ea44dc9ed014 472
joeverbout 0:ea44dc9ed014 473 class CV_EXPORTS AutoLock
joeverbout 0:ea44dc9ed014 474 {
joeverbout 0:ea44dc9ed014 475 public:
joeverbout 0:ea44dc9ed014 476 AutoLock(Mutex& m) : mutex(&m) { mutex->lock(); }
joeverbout 0:ea44dc9ed014 477 ~AutoLock() { mutex->unlock(); }
joeverbout 0:ea44dc9ed014 478 protected:
joeverbout 0:ea44dc9ed014 479 Mutex* mutex;
joeverbout 0:ea44dc9ed014 480 private:
joeverbout 0:ea44dc9ed014 481 AutoLock(const AutoLock&);
joeverbout 0:ea44dc9ed014 482 AutoLock& operator = (const AutoLock&);
joeverbout 0:ea44dc9ed014 483 };
joeverbout 0:ea44dc9ed014 484
joeverbout 0:ea44dc9ed014 485 // TLS interface
joeverbout 0:ea44dc9ed014 486 class CV_EXPORTS TLSDataContainer
joeverbout 0:ea44dc9ed014 487 {
joeverbout 0:ea44dc9ed014 488 protected:
joeverbout 0:ea44dc9ed014 489 TLSDataContainer();
joeverbout 0:ea44dc9ed014 490 virtual ~TLSDataContainer();
joeverbout 0:ea44dc9ed014 491
joeverbout 0:ea44dc9ed014 492 void gatherData(std::vector<void*> &data) const;
joeverbout 0:ea44dc9ed014 493 #if OPENCV_ABI_COMPATIBILITY > 300
joeverbout 0:ea44dc9ed014 494 void* getData() const;
joeverbout 0:ea44dc9ed014 495 void release();
joeverbout 0:ea44dc9ed014 496
joeverbout 0:ea44dc9ed014 497 private:
joeverbout 0:ea44dc9ed014 498 #else
joeverbout 0:ea44dc9ed014 499 void release();
joeverbout 0:ea44dc9ed014 500
joeverbout 0:ea44dc9ed014 501 public:
joeverbout 0:ea44dc9ed014 502 void* getData() const;
joeverbout 0:ea44dc9ed014 503 #endif
joeverbout 0:ea44dc9ed014 504 virtual void* createDataInstance() const = 0;
joeverbout 0:ea44dc9ed014 505 virtual void deleteDataInstance(void* pData) const = 0;
joeverbout 0:ea44dc9ed014 506
joeverbout 0:ea44dc9ed014 507 int key_;
joeverbout 0:ea44dc9ed014 508 };
joeverbout 0:ea44dc9ed014 509
joeverbout 0:ea44dc9ed014 510 // Main TLS data class
joeverbout 0:ea44dc9ed014 511 template <typename T>
joeverbout 0:ea44dc9ed014 512 class TLSData : protected TLSDataContainer
joeverbout 0:ea44dc9ed014 513 {
joeverbout 0:ea44dc9ed014 514 public:
joeverbout 0:ea44dc9ed014 515 inline TLSData() {}
joeverbout 0:ea44dc9ed014 516 inline ~TLSData() { release(); } // Release key and delete associated data
joeverbout 0:ea44dc9ed014 517 inline T* get() const { return (T*)getData(); } // Get data assosiated with key
joeverbout 0:ea44dc9ed014 518
joeverbout 0:ea44dc9ed014 519 // Get data from all threads
joeverbout 0:ea44dc9ed014 520 inline void gather(std::vector<T*> &data) const
joeverbout 0:ea44dc9ed014 521 {
joeverbout 0:ea44dc9ed014 522 std::vector<void*> &dataVoid = reinterpret_cast<std::vector<void*>&>(data);
joeverbout 0:ea44dc9ed014 523 gatherData(dataVoid);
joeverbout 0:ea44dc9ed014 524 }
joeverbout 0:ea44dc9ed014 525
joeverbout 0:ea44dc9ed014 526 private:
joeverbout 0:ea44dc9ed014 527 virtual void* createDataInstance() const {return new T;} // Wrapper to allocate data by template
joeverbout 0:ea44dc9ed014 528 virtual void deleteDataInstance(void* pData) const {delete (T*)pData;} // Wrapper to release data by template
joeverbout 0:ea44dc9ed014 529
joeverbout 0:ea44dc9ed014 530 // Disable TLS copy operations
joeverbout 0:ea44dc9ed014 531 TLSData(TLSData &) {};
joeverbout 0:ea44dc9ed014 532 TLSData& operator =(const TLSData &) {return *this;};
joeverbout 0:ea44dc9ed014 533 };
joeverbout 0:ea44dc9ed014 534
joeverbout 0:ea44dc9ed014 535 /** @brief Designed for command line parsing
joeverbout 0:ea44dc9ed014 536
joeverbout 0:ea44dc9ed014 537 The sample below demonstrates how to use CommandLineParser:
joeverbout 0:ea44dc9ed014 538 @code
joeverbout 0:ea44dc9ed014 539 CommandLineParser parser(argc, argv, keys);
joeverbout 0:ea44dc9ed014 540 parser.about("Application name v1.0.0");
joeverbout 0:ea44dc9ed014 541
joeverbout 0:ea44dc9ed014 542 if (parser.has("help"))
joeverbout 0:ea44dc9ed014 543 {
joeverbout 0:ea44dc9ed014 544 parser.printMessage();
joeverbout 0:ea44dc9ed014 545 return 0;
joeverbout 0:ea44dc9ed014 546 }
joeverbout 0:ea44dc9ed014 547
joeverbout 0:ea44dc9ed014 548 int N = parser.get<int>("N");
joeverbout 0:ea44dc9ed014 549 double fps = parser.get<double>("fps");
joeverbout 0:ea44dc9ed014 550 String path = parser.get<String>("path");
joeverbout 0:ea44dc9ed014 551
joeverbout 0:ea44dc9ed014 552 use_time_stamp = parser.has("timestamp");
joeverbout 0:ea44dc9ed014 553
joeverbout 0:ea44dc9ed014 554 String img1 = parser.get<String>(0);
joeverbout 0:ea44dc9ed014 555 String img2 = parser.get<String>(1);
joeverbout 0:ea44dc9ed014 556
joeverbout 0:ea44dc9ed014 557 int repeat = parser.get<int>(2);
joeverbout 0:ea44dc9ed014 558
joeverbout 0:ea44dc9ed014 559 if (!parser.check())
joeverbout 0:ea44dc9ed014 560 {
joeverbout 0:ea44dc9ed014 561 parser.printErrors();
joeverbout 0:ea44dc9ed014 562 return 0;
joeverbout 0:ea44dc9ed014 563 }
joeverbout 0:ea44dc9ed014 564 @endcode
joeverbout 0:ea44dc9ed014 565
joeverbout 0:ea44dc9ed014 566 ### Keys syntax
joeverbout 0:ea44dc9ed014 567
joeverbout 0:ea44dc9ed014 568 The keys parameter is a string containing several blocks, each one is enclosed in curley braces and
joeverbout 0:ea44dc9ed014 569 describes one argument. Each argument contains three parts separated by the `|` symbol:
joeverbout 0:ea44dc9ed014 570
joeverbout 0:ea44dc9ed014 571 -# argument names is a space-separated list of option synonyms (to mark argument as positional, prefix it with the `@` symbol)
joeverbout 0:ea44dc9ed014 572 -# default value will be used if the argument was not provided (can be empty)
joeverbout 0:ea44dc9ed014 573 -# help message (can be empty)
joeverbout 0:ea44dc9ed014 574
joeverbout 0:ea44dc9ed014 575 For example:
joeverbout 0:ea44dc9ed014 576
joeverbout 0:ea44dc9ed014 577 @code{.cpp}
joeverbout 0:ea44dc9ed014 578 const String keys =
joeverbout 0:ea44dc9ed014 579 "{help h usage ? | | print this message }"
joeverbout 0:ea44dc9ed014 580 "{@image1 | | image1 for compare }"
joeverbout 0:ea44dc9ed014 581 "{@image2 |<none>| image2 for compare }"
joeverbout 0:ea44dc9ed014 582 "{@repeat |1 | number }"
joeverbout 0:ea44dc9ed014 583 "{path |. | path to file }"
joeverbout 0:ea44dc9ed014 584 "{fps | -1.0 | fps for output video }"
joeverbout 0:ea44dc9ed014 585 "{N count |100 | count of objects }"
joeverbout 0:ea44dc9ed014 586 "{ts timestamp | | use time stamp }"
joeverbout 0:ea44dc9ed014 587 ;
joeverbout 0:ea44dc9ed014 588 }
joeverbout 0:ea44dc9ed014 589 @endcode
joeverbout 0:ea44dc9ed014 590
joeverbout 0:ea44dc9ed014 591 Note that there are no default values for `help` and `timestamp` so we can check their presence using the `has()` method.
joeverbout 0:ea44dc9ed014 592 Arguments with default values are considered to be always present. Use the `get()` method in these cases to check their
joeverbout 0:ea44dc9ed014 593 actual value instead.
joeverbout 0:ea44dc9ed014 594
joeverbout 0:ea44dc9ed014 595 String keys like `get<String>("@image1")` return the empty string `""` by default - even with an empty default value.
joeverbout 0:ea44dc9ed014 596 Use the special `<none>` default value to enforce that the returned string must not be empty. (like in `get<String>("@image2")`)
joeverbout 0:ea44dc9ed014 597
joeverbout 0:ea44dc9ed014 598 ### Usage
joeverbout 0:ea44dc9ed014 599
joeverbout 0:ea44dc9ed014 600 For the described keys:
joeverbout 0:ea44dc9ed014 601
joeverbout 0:ea44dc9ed014 602 @code{.sh}
joeverbout 0:ea44dc9ed014 603 # Good call (3 positional parameters: image1, image2 and repeat; N is 200, ts is true)
joeverbout 0:ea44dc9ed014 604 $ ./app -N=200 1.png 2.jpg 19 -ts
joeverbout 0:ea44dc9ed014 605
joeverbout 0:ea44dc9ed014 606 # Bad call
joeverbout 0:ea44dc9ed014 607 $ ./app -fps=aaa
joeverbout 0:ea44dc9ed014 608 ERRORS:
joeverbout 0:ea44dc9ed014 609 Parameter 'fps': can not convert: [aaa] to [double]
joeverbout 0:ea44dc9ed014 610 @endcode
joeverbout 0:ea44dc9ed014 611 */
joeverbout 0:ea44dc9ed014 612 class CV_EXPORTS CommandLineParser
joeverbout 0:ea44dc9ed014 613 {
joeverbout 0:ea44dc9ed014 614 public:
joeverbout 0:ea44dc9ed014 615
joeverbout 0:ea44dc9ed014 616 /** @brief Constructor
joeverbout 0:ea44dc9ed014 617
joeverbout 0:ea44dc9ed014 618 Initializes command line parser object
joeverbout 0:ea44dc9ed014 619
joeverbout 0:ea44dc9ed014 620 @param argc number of command line arguments (from main())
joeverbout 0:ea44dc9ed014 621 @param argv array of command line arguments (from main())
joeverbout 0:ea44dc9ed014 622 @param keys string describing acceptable command line parameters (see class description for syntax)
joeverbout 0:ea44dc9ed014 623 */
joeverbout 0:ea44dc9ed014 624 CommandLineParser(int argc, const char* const argv[], const String& keys);
joeverbout 0:ea44dc9ed014 625
joeverbout 0:ea44dc9ed014 626 /** @brief Copy constructor */
joeverbout 0:ea44dc9ed014 627 CommandLineParser(const CommandLineParser& parser);
joeverbout 0:ea44dc9ed014 628
joeverbout 0:ea44dc9ed014 629 /** @brief Assignment operator */
joeverbout 0:ea44dc9ed014 630 CommandLineParser& operator = (const CommandLineParser& parser);
joeverbout 0:ea44dc9ed014 631
joeverbout 0:ea44dc9ed014 632 /** @brief Destructor */
joeverbout 0:ea44dc9ed014 633 ~CommandLineParser();
joeverbout 0:ea44dc9ed014 634
joeverbout 0:ea44dc9ed014 635 /** @brief Returns application path
joeverbout 0:ea44dc9ed014 636
joeverbout 0:ea44dc9ed014 637 This method returns the path to the executable from the command line (`argv[0]`).
joeverbout 0:ea44dc9ed014 638
joeverbout 0:ea44dc9ed014 639 For example, if the application has been started with such command:
joeverbout 0:ea44dc9ed014 640 @code{.sh}
joeverbout 0:ea44dc9ed014 641 $ ./bin/my-executable
joeverbout 0:ea44dc9ed014 642 @endcode
joeverbout 0:ea44dc9ed014 643 this method will return `./bin`.
joeverbout 0:ea44dc9ed014 644 */
joeverbout 0:ea44dc9ed014 645 String getPathToApplication() const;
joeverbout 0:ea44dc9ed014 646
joeverbout 0:ea44dc9ed014 647 /** @brief Access arguments by name
joeverbout 0:ea44dc9ed014 648
joeverbout 0:ea44dc9ed014 649 Returns argument converted to selected type. If the argument is not known or can not be
joeverbout 0:ea44dc9ed014 650 converted to selected type, the error flag is set (can be checked with @ref check).
joeverbout 0:ea44dc9ed014 651
joeverbout 0:ea44dc9ed014 652 For example, define:
joeverbout 0:ea44dc9ed014 653 @code{.cpp}
joeverbout 0:ea44dc9ed014 654 String keys = "{N count||}";
joeverbout 0:ea44dc9ed014 655 @endcode
joeverbout 0:ea44dc9ed014 656
joeverbout 0:ea44dc9ed014 657 Call:
joeverbout 0:ea44dc9ed014 658 @code{.sh}
joeverbout 0:ea44dc9ed014 659 $ ./my-app -N=20
joeverbout 0:ea44dc9ed014 660 # or
joeverbout 0:ea44dc9ed014 661 $ ./my-app --count=20
joeverbout 0:ea44dc9ed014 662 @endcode
joeverbout 0:ea44dc9ed014 663
joeverbout 0:ea44dc9ed014 664 Access:
joeverbout 0:ea44dc9ed014 665 @code{.cpp}
joeverbout 0:ea44dc9ed014 666 int N = parser.get<int>("N");
joeverbout 0:ea44dc9ed014 667 @endcode
joeverbout 0:ea44dc9ed014 668
joeverbout 0:ea44dc9ed014 669 @param name name of the argument
joeverbout 0:ea44dc9ed014 670 @param space_delete remove spaces from the left and right of the string
joeverbout 0:ea44dc9ed014 671 @tparam T the argument will be converted to this type if possible
joeverbout 0:ea44dc9ed014 672
joeverbout 0:ea44dc9ed014 673 @note You can access positional arguments by their `@`-prefixed name:
joeverbout 0:ea44dc9ed014 674 @code{.cpp}
joeverbout 0:ea44dc9ed014 675 parser.get<String>("@image");
joeverbout 0:ea44dc9ed014 676 @endcode
joeverbout 0:ea44dc9ed014 677 */
joeverbout 0:ea44dc9ed014 678 template <typename T>
joeverbout 0:ea44dc9ed014 679 T get(const String& name, bool space_delete = true) const
joeverbout 0:ea44dc9ed014 680 {
joeverbout 0:ea44dc9ed014 681 T val = T();
joeverbout 0:ea44dc9ed014 682 getByName(name, space_delete, ParamType<T>::type, (void*)&val);
joeverbout 0:ea44dc9ed014 683 return val;
joeverbout 0:ea44dc9ed014 684 }
joeverbout 0:ea44dc9ed014 685
joeverbout 0:ea44dc9ed014 686 /** @brief Access positional arguments by index
joeverbout 0:ea44dc9ed014 687
joeverbout 0:ea44dc9ed014 688 Returns argument converted to selected type. Indexes are counted from zero.
joeverbout 0:ea44dc9ed014 689
joeverbout 0:ea44dc9ed014 690 For example, define:
joeverbout 0:ea44dc9ed014 691 @code{.cpp}
joeverbout 0:ea44dc9ed014 692 String keys = "{@arg1||}{@arg2||}"
joeverbout 0:ea44dc9ed014 693 @endcode
joeverbout 0:ea44dc9ed014 694
joeverbout 0:ea44dc9ed014 695 Call:
joeverbout 0:ea44dc9ed014 696 @code{.sh}
joeverbout 0:ea44dc9ed014 697 ./my-app abc qwe
joeverbout 0:ea44dc9ed014 698 @endcode
joeverbout 0:ea44dc9ed014 699
joeverbout 0:ea44dc9ed014 700 Access arguments:
joeverbout 0:ea44dc9ed014 701 @code{.cpp}
joeverbout 0:ea44dc9ed014 702 String val_1 = parser.get<String>(0); // returns "abc", arg1
joeverbout 0:ea44dc9ed014 703 String val_2 = parser.get<String>(1); // returns "qwe", arg2
joeverbout 0:ea44dc9ed014 704 @endcode
joeverbout 0:ea44dc9ed014 705
joeverbout 0:ea44dc9ed014 706 @param index index of the argument
joeverbout 0:ea44dc9ed014 707 @param space_delete remove spaces from the left and right of the string
joeverbout 0:ea44dc9ed014 708 @tparam T the argument will be converted to this type if possible
joeverbout 0:ea44dc9ed014 709 */
joeverbout 0:ea44dc9ed014 710 template <typename T>
joeverbout 0:ea44dc9ed014 711 T get(int index, bool space_delete = true) const
joeverbout 0:ea44dc9ed014 712 {
joeverbout 0:ea44dc9ed014 713 T val = T();
joeverbout 0:ea44dc9ed014 714 getByIndex(index, space_delete, ParamType<T>::type, (void*)&val);
joeverbout 0:ea44dc9ed014 715 return val;
joeverbout 0:ea44dc9ed014 716 }
joeverbout 0:ea44dc9ed014 717
joeverbout 0:ea44dc9ed014 718 /** @brief Check if field was provided in the command line
joeverbout 0:ea44dc9ed014 719
joeverbout 0:ea44dc9ed014 720 @param name argument name to check
joeverbout 0:ea44dc9ed014 721 */
joeverbout 0:ea44dc9ed014 722 bool has(const String& name) const;
joeverbout 0:ea44dc9ed014 723
joeverbout 0:ea44dc9ed014 724 /** @brief Check for parsing errors
joeverbout 0:ea44dc9ed014 725
joeverbout 0:ea44dc9ed014 726 Returns true if error occured while accessing the parameters (bad conversion, missing arguments,
joeverbout 0:ea44dc9ed014 727 etc.). Call @ref printErrors to print error messages list.
joeverbout 0:ea44dc9ed014 728 */
joeverbout 0:ea44dc9ed014 729 bool check() const;
joeverbout 0:ea44dc9ed014 730
joeverbout 0:ea44dc9ed014 731 /** @brief Set the about message
joeverbout 0:ea44dc9ed014 732
joeverbout 0:ea44dc9ed014 733 The about message will be shown when @ref printMessage is called, right before arguments table.
joeverbout 0:ea44dc9ed014 734 */
joeverbout 0:ea44dc9ed014 735 void about(const String& message);
joeverbout 0:ea44dc9ed014 736
joeverbout 0:ea44dc9ed014 737 /** @brief Print help message
joeverbout 0:ea44dc9ed014 738
joeverbout 0:ea44dc9ed014 739 This method will print standard help message containing the about message and arguments description.
joeverbout 0:ea44dc9ed014 740
joeverbout 0:ea44dc9ed014 741 @sa about
joeverbout 0:ea44dc9ed014 742 */
joeverbout 0:ea44dc9ed014 743 void printMessage() const;
joeverbout 0:ea44dc9ed014 744
joeverbout 0:ea44dc9ed014 745 /** @brief Print list of errors occured
joeverbout 0:ea44dc9ed014 746
joeverbout 0:ea44dc9ed014 747 @sa check
joeverbout 0:ea44dc9ed014 748 */
joeverbout 0:ea44dc9ed014 749 void printErrors() const;
joeverbout 0:ea44dc9ed014 750
joeverbout 0:ea44dc9ed014 751 protected:
joeverbout 0:ea44dc9ed014 752 void getByName(const String& name, bool space_delete, int type, void* dst) const;
joeverbout 0:ea44dc9ed014 753 void getByIndex(int index, bool space_delete, int type, void* dst) const;
joeverbout 0:ea44dc9ed014 754
joeverbout 0:ea44dc9ed014 755 struct Impl;
joeverbout 0:ea44dc9ed014 756 Impl* impl;
joeverbout 0:ea44dc9ed014 757 };
joeverbout 0:ea44dc9ed014 758
joeverbout 0:ea44dc9ed014 759 //! @} core_utils
joeverbout 0:ea44dc9ed014 760
joeverbout 0:ea44dc9ed014 761 //! @cond IGNORED
joeverbout 0:ea44dc9ed014 762
joeverbout 0:ea44dc9ed014 763 /////////////////////////////// AutoBuffer implementation ////////////////////////////////////////
joeverbout 0:ea44dc9ed014 764
joeverbout 0:ea44dc9ed014 765 template<typename _Tp, size_t fixed_size> inline
joeverbout 0:ea44dc9ed014 766 AutoBuffer<_Tp, fixed_size>::AutoBuffer()
joeverbout 0:ea44dc9ed014 767 {
joeverbout 0:ea44dc9ed014 768 ptr = buf;
joeverbout 0:ea44dc9ed014 769 sz = fixed_size;
joeverbout 0:ea44dc9ed014 770 }
joeverbout 0:ea44dc9ed014 771
joeverbout 0:ea44dc9ed014 772 template<typename _Tp, size_t fixed_size> inline
joeverbout 0:ea44dc9ed014 773 AutoBuffer<_Tp, fixed_size>::AutoBuffer(size_t _size)
joeverbout 0:ea44dc9ed014 774 {
joeverbout 0:ea44dc9ed014 775 ptr = buf;
joeverbout 0:ea44dc9ed014 776 sz = fixed_size;
joeverbout 0:ea44dc9ed014 777 allocate(_size);
joeverbout 0:ea44dc9ed014 778 }
joeverbout 0:ea44dc9ed014 779
joeverbout 0:ea44dc9ed014 780 template<typename _Tp, size_t fixed_size> inline
joeverbout 0:ea44dc9ed014 781 AutoBuffer<_Tp, fixed_size>::AutoBuffer(const AutoBuffer<_Tp, fixed_size>& abuf )
joeverbout 0:ea44dc9ed014 782 {
joeverbout 0:ea44dc9ed014 783 ptr = buf;
joeverbout 0:ea44dc9ed014 784 sz = fixed_size;
joeverbout 0:ea44dc9ed014 785 allocate(abuf.size());
joeverbout 0:ea44dc9ed014 786 for( size_t i = 0; i < sz; i++ )
joeverbout 0:ea44dc9ed014 787 ptr[i] = abuf.ptr[i];
joeverbout 0:ea44dc9ed014 788 }
joeverbout 0:ea44dc9ed014 789
joeverbout 0:ea44dc9ed014 790 template<typename _Tp, size_t fixed_size> inline AutoBuffer<_Tp, fixed_size>&
joeverbout 0:ea44dc9ed014 791 AutoBuffer<_Tp, fixed_size>::operator = (const AutoBuffer<_Tp, fixed_size>& abuf)
joeverbout 0:ea44dc9ed014 792 {
joeverbout 0:ea44dc9ed014 793 if( this != &abuf )
joeverbout 0:ea44dc9ed014 794 {
joeverbout 0:ea44dc9ed014 795 deallocate();
joeverbout 0:ea44dc9ed014 796 allocate(abuf.size());
joeverbout 0:ea44dc9ed014 797 for( size_t i = 0; i < sz; i++ )
joeverbout 0:ea44dc9ed014 798 ptr[i] = abuf.ptr[i];
joeverbout 0:ea44dc9ed014 799 }
joeverbout 0:ea44dc9ed014 800 return *this;
joeverbout 0:ea44dc9ed014 801 }
joeverbout 0:ea44dc9ed014 802
joeverbout 0:ea44dc9ed014 803 template<typename _Tp, size_t fixed_size> inline
joeverbout 0:ea44dc9ed014 804 AutoBuffer<_Tp, fixed_size>::~AutoBuffer()
joeverbout 0:ea44dc9ed014 805 { deallocate(); }
joeverbout 0:ea44dc9ed014 806
joeverbout 0:ea44dc9ed014 807 template<typename _Tp, size_t fixed_size> inline void
joeverbout 0:ea44dc9ed014 808 AutoBuffer<_Tp, fixed_size>::allocate(size_t _size)
joeverbout 0:ea44dc9ed014 809 {
joeverbout 0:ea44dc9ed014 810 if(_size <= sz)
joeverbout 0:ea44dc9ed014 811 {
joeverbout 0:ea44dc9ed014 812 sz = _size;
joeverbout 0:ea44dc9ed014 813 return;
joeverbout 0:ea44dc9ed014 814 }
joeverbout 0:ea44dc9ed014 815 deallocate();
joeverbout 0:ea44dc9ed014 816 if(_size > fixed_size)
joeverbout 0:ea44dc9ed014 817 {
joeverbout 0:ea44dc9ed014 818 ptr = new _Tp[_size];
joeverbout 0:ea44dc9ed014 819 sz = _size;
joeverbout 0:ea44dc9ed014 820 }
joeverbout 0:ea44dc9ed014 821 }
joeverbout 0:ea44dc9ed014 822
joeverbout 0:ea44dc9ed014 823 template<typename _Tp, size_t fixed_size> inline void
joeverbout 0:ea44dc9ed014 824 AutoBuffer<_Tp, fixed_size>::deallocate()
joeverbout 0:ea44dc9ed014 825 {
joeverbout 0:ea44dc9ed014 826 if( ptr != buf )
joeverbout 0:ea44dc9ed014 827 {
joeverbout 0:ea44dc9ed014 828 delete[] ptr;
joeverbout 0:ea44dc9ed014 829 ptr = buf;
joeverbout 0:ea44dc9ed014 830 sz = fixed_size;
joeverbout 0:ea44dc9ed014 831 }
joeverbout 0:ea44dc9ed014 832 }
joeverbout 0:ea44dc9ed014 833
joeverbout 0:ea44dc9ed014 834 template<typename _Tp, size_t fixed_size> inline void
joeverbout 0:ea44dc9ed014 835 AutoBuffer<_Tp, fixed_size>::resize(size_t _size)
joeverbout 0:ea44dc9ed014 836 {
joeverbout 0:ea44dc9ed014 837 if(_size <= sz)
joeverbout 0:ea44dc9ed014 838 {
joeverbout 0:ea44dc9ed014 839 sz = _size;
joeverbout 0:ea44dc9ed014 840 return;
joeverbout 0:ea44dc9ed014 841 }
joeverbout 0:ea44dc9ed014 842 size_t i, prevsize = sz, minsize = MIN(prevsize, _size);
joeverbout 0:ea44dc9ed014 843 _Tp* prevptr = ptr;
joeverbout 0:ea44dc9ed014 844
joeverbout 0:ea44dc9ed014 845 ptr = _size > fixed_size ? new _Tp[_size] : buf;
joeverbout 0:ea44dc9ed014 846 sz = _size;
joeverbout 0:ea44dc9ed014 847
joeverbout 0:ea44dc9ed014 848 if( ptr != prevptr )
joeverbout 0:ea44dc9ed014 849 for( i = 0; i < minsize; i++ )
joeverbout 0:ea44dc9ed014 850 ptr[i] = prevptr[i];
joeverbout 0:ea44dc9ed014 851 for( i = prevsize; i < _size; i++ )
joeverbout 0:ea44dc9ed014 852 ptr[i] = _Tp();
joeverbout 0:ea44dc9ed014 853
joeverbout 0:ea44dc9ed014 854 if( prevptr != buf )
joeverbout 0:ea44dc9ed014 855 delete[] prevptr;
joeverbout 0:ea44dc9ed014 856 }
joeverbout 0:ea44dc9ed014 857
joeverbout 0:ea44dc9ed014 858 template<typename _Tp, size_t fixed_size> inline size_t
joeverbout 0:ea44dc9ed014 859 AutoBuffer<_Tp, fixed_size>::size() const
joeverbout 0:ea44dc9ed014 860 { return sz; }
joeverbout 0:ea44dc9ed014 861
joeverbout 0:ea44dc9ed014 862 template<typename _Tp, size_t fixed_size> inline
joeverbout 0:ea44dc9ed014 863 AutoBuffer<_Tp, fixed_size>::operator _Tp* ()
joeverbout 0:ea44dc9ed014 864 { return ptr; }
joeverbout 0:ea44dc9ed014 865
joeverbout 0:ea44dc9ed014 866 template<typename _Tp, size_t fixed_size> inline
joeverbout 0:ea44dc9ed014 867 AutoBuffer<_Tp, fixed_size>::operator const _Tp* () const
joeverbout 0:ea44dc9ed014 868 { return ptr; }
joeverbout 0:ea44dc9ed014 869
joeverbout 0:ea44dc9ed014 870 #ifndef OPENCV_NOSTL
joeverbout 0:ea44dc9ed014 871 template<> inline std::string CommandLineParser::get<std::string>(int index, bool space_delete) const
joeverbout 0:ea44dc9ed014 872 {
joeverbout 0:ea44dc9ed014 873 return get<String>(index, space_delete);
joeverbout 0:ea44dc9ed014 874 }
joeverbout 0:ea44dc9ed014 875 template<> inline std::string CommandLineParser::get<std::string>(const String& name, bool space_delete) const
joeverbout 0:ea44dc9ed014 876 {
joeverbout 0:ea44dc9ed014 877 return get<String>(name, space_delete);
joeverbout 0:ea44dc9ed014 878 }
joeverbout 0:ea44dc9ed014 879 #endif // OPENCV_NOSTL
joeverbout 0:ea44dc9ed014 880
joeverbout 0:ea44dc9ed014 881 //! @endcond
joeverbout 0:ea44dc9ed014 882
joeverbout 0:ea44dc9ed014 883 } //namespace cv
joeverbout 0:ea44dc9ed014 884
joeverbout 0:ea44dc9ed014 885 #ifndef DISABLE_OPENCV_24_COMPATIBILITY
joeverbout 0:ea44dc9ed014 886 #include "opencv2/core/core_c.h"
joeverbout 0:ea44dc9ed014 887 #endif
joeverbout 0:ea44dc9ed014 888
joeverbout 0:ea44dc9ed014 889 #endif //__OPENCV_CORE_UTILITY_H__
joeverbout 0:ea44dc9ed014 890