1 Utility and System Functions and Macros
2 =======================================
8 Aligns a pointer to the specified number of bytes.
10 .. ocv:function:: template<typename _Tp> _Tp* alignPtr(_Tp* ptr, int n=sizeof(_Tp))
12 :param ptr: Aligned pointer.
14 :param n: Alignment size that must be a power of two.
16 The function returns the aligned pointer of the same type as the input pointer:
20 \texttt{(\_Tp*)(((size\_t)ptr + n-1) \& -n)}
26 Aligns a buffer size to the specified number of bytes.
28 .. ocv:function:: size_t alignSize(size_t sz, int n)
30 :param sz: Buffer size to align.
32 :param n: Alignment size that must be a power of two.
34 The function returns the minimum number that is greater or equal to ``sz`` and is divisible by ``n`` :
38 \texttt{(sz + n-1) \& -n}
44 Allocates an array of elements.
46 .. ocv:function:: template<typename _Tp> _Tp* allocate(size_t n)
48 :param n: Number of elements to allocate.
50 The generic function ``allocate`` allocates a buffer for the specified number of elements. For each element, the default constructor is called.
56 Deallocates an array of elements.
58 .. ocv:function:: template<typename _Tp> void deallocate(_Tp* ptr, size_t n)
60 :param ptr: Pointer to the deallocated buffer.
62 :param n: Number of elements in the buffer.
64 The generic function ``deallocate`` deallocates the buffer allocated with
65 :ocv:func:`allocate` . The number of elements must match the number passed to
66 :ocv:func:`allocate` .
72 Calculates the angle of a 2D vector in degrees.
74 .. ocv:function:: float fastAtan2(float y, float x)
76 .. ocv:pyfunction:: cv2.fastAtan2(y, x) -> retval
78 .. ocv:cfunction:: float cvFastArctan(float y, float x)
79 .. ocv:pyoldfunction:: cv.FastArctan(y, x)-> float
81 :param x: x-coordinate of the vector.
83 :param y: y-coordinate of the vector.
85 The function ``fastAtan2`` calculates the full-range angle of an input 2D vector. The angle is measured in degrees and varies from 0 to 360 degrees. The accuracy is about 0.3 degrees.
90 Computes the cube root of an argument.
92 .. ocv:function:: float cubeRoot(float val)
94 .. ocv:pyfunction:: cv2.cubeRoot(val) -> retval
96 .. ocv:cfunction:: float cvCbrt( float value )
98 .. ocv:pyoldfunction:: cv.Cbrt(value)-> float
100 :param val: A function argument.
102 The function ``cubeRoot`` computes :math:`\sqrt[3]{\texttt{val}}`. Negative arguments are handled correctly. NaN and Inf are not handled. The accuracy approaches the maximum possible accuracy for single-precision data.
107 Rounds floating-point number to the nearest integer not smaller than the original.
109 .. ocv:cfunction:: int cvCeil(double value)
110 .. ocv:pyoldfunction:: cv.Ceil(value) -> int
112 :param value: floating-point number. If the value is outside of ``INT_MIN`` ... ``INT_MAX`` range, the result is not defined.
114 The function computes an integer ``i`` such that:
118 i-1 < \texttt{value} \le i
123 Rounds floating-point number to the nearest integer not larger than the original.
125 .. ocv:cfunction:: int cvFloor(double value)
126 .. ocv:pyoldfunction:: cv.Floor(value) -> int
128 :param value: floating-point number. If the value is outside of ``INT_MIN`` ... ``INT_MAX`` range, the result is not defined.
130 The function computes an integer ``i`` such that:
134 i \le \texttt{value} < i+1
139 Rounds floating-point number to the nearest integer
141 .. ocv:cfunction:: int cvRound(double value)
142 .. ocv:pyoldfunction:: cv.Round(value) -> int
144 :param value: floating-point number. If the value is outside of ``INT_MIN`` ... ``INT_MAX`` range, the result is not defined.
149 Determines if the argument is Infinity.
151 .. ocv:cfunction:: int cvIsInf(double value)
152 .. ocv:pyoldfunction:: cv.IsInf(value)-> int
154 :param value: The input floating-point value
156 The function returns 1 if the argument is a plus or minus infinity (as defined by IEEE754 standard) and 0 otherwise.
160 Determines if the argument is Not A Number.
162 .. ocv:cfunction:: int cvIsNaN(double value)
163 .. ocv:pyoldfunction:: cv.IsNaN(value)-> int
165 :param value: The input floating-point value
167 The function returns 1 if the argument is Not A Number (as defined by IEEE754 standard), 0 otherwise.
172 Checks a condition at runtime and throws exception if it fails
174 .. ocv:function:: CV_Assert(expr)
176 The macros ``CV_Assert`` (and ``CV_DbgAssert``) evaluate the specified expression. If it is 0, the macros raise an error (see :ocv:func:`error` ). The macro ``CV_Assert`` checks the condition in both Debug and Release configurations while ``CV_DbgAssert`` is only retained in the Debug configuration.
181 Signals an error and raises an exception.
183 .. ocv:function:: void error( const Exception& exc )
185 .. ocv:cfunction:: void cvError( int status, const char* func_name, const char* err_msg, const char* file_name, int line )
187 :param exc: Exception to throw.
189 :param status: Error code. Normally, it is a negative value. The list of pre-defined error codes can be found in ``cxerror.h`` .
191 :param err_msg: Text of the error message.
193 :param args: ``printf`` -like formatted error message in parentheses.
195 The function and the helper macros ``CV_Error`` and ``CV_Error_``: ::
197 #define CV_Error( code, msg ) error(...)
198 #define CV_Error_( code, args ) error(...)
200 call the error handler. Currently, the error handler prints the error code ( ``exc.code`` ), the context ( ``exc.file``,``exc.line`` ), and the error message ``exc.err`` to the standard error stream ``stderr`` . In the Debug configuration, it then provokes memory access violation, so that the execution stack and all the parameters can be analyzed by the debugger. In the Release configuration, the exception ``exc`` is thrown.
202 The macro ``CV_Error_`` can be used to construct an error message on-fly to include some dynamic information, for example: ::
204 // note the extra parentheses around the formatted text message
205 CV_Error_(CV_StsOutOfRange,
206 ("the matrix element (
207 i, j, mtx.at<float>(i,j)))
212 .. ocv:class:: Exception : public std::exception
214 Exception class passed to an error. ::
219 // various constructors and the copy operation
220 Exception() { code = 0; line = 0; }
221 Exception(int _code, const string& _err,
222 const string& _func, const string& _file, int _line);
223 Exception(const Exception& exc);
224 Exception& operator = (const Exception& exc);
228 // the error text message
230 // function name where the error happened
232 // the source file name where the error happened
234 // the source file line where the error happened
238 The class ``Exception`` encapsulates all or almost all necessary information about the error happened in the program. The exception is usually constructed and thrown implicitly via ``CV_Error`` and ``CV_Error_`` macros. See
245 Allocates an aligned memory buffer.
247 .. ocv:function:: void* fastMalloc( size_t bufSize )
249 .. ocv:cfunction:: void* cvAlloc( size_t size )
251 :param size: Allocated buffer size.
253 The function allocates the buffer of the specified size and returns it. When the buffer size is 16 bytes or more, the returned buffer is aligned to 16 bytes.
259 Deallocates a memory buffer.
261 .. ocv:function:: void fastFree(void* ptr)
262 .. ocv:cfunction:: void cvFree( void** pptr )
264 :param ptr: Pointer to the allocated buffer.
266 :param pptr: Double pointer to the allocated buffer
268 The function deallocates the buffer allocated with :ocv:func:`fastMalloc` . If NULL pointer is passed, the function does nothing. C version of the function clears the pointer ``*pptr`` to avoid problems with double memory deallocation.
273 Returns a text string formatted using the ``printf``\ -like expression.
275 .. ocv:function:: string format( const char* fmt, ... )
277 :param fmt: ``printf`` -compatible formatting specifiers.
279 The function acts like ``sprintf`` but forms and returns an STL string. It can be used to form an error message in the
280 :ocv:class:`Exception` constructor.
285 Returns full configuration time cmake output.
287 .. ocv:function:: const std::string& getBuildInformation()
289 Returned value is raw cmake output including version control system revision, compiler version, compiler flags, enabled modules and third party libraries, etc. Output format depends on target architecture.
294 Returns true if the specified feature is supported by the host hardware.
296 .. ocv:function:: bool checkHardwareSupport(int feature)
297 .. ocv:cfunction:: int cvCheckHardwareSupport(int feature)
298 .. ocv:pyfunction:: cv2.checkHardwareSupport(feature) -> retval
300 :param feature: The feature of interest, one of:
302 * ``CV_CPU_MMX`` - MMX
303 * ``CV_CPU_SSE`` - SSE
304 * ``CV_CPU_SSE2`` - SSE 2
305 * ``CV_CPU_SSE3`` - SSE 3
306 * ``CV_CPU_SSSE3`` - SSSE 3
307 * ``CV_CPU_SSE4_1`` - SSE 4.1
308 * ``CV_CPU_SSE4_2`` - SSE 4.2
309 * ``CV_CPU_POPCNT`` - POPCOUNT
310 * ``CV_CPU_AVX`` - AVX
312 The function returns true if the host hardware supports the specified feature. When user calls ``setUseOptimized(false)``, the subsequent calls to ``checkHardwareSupport()`` will return false until ``setUseOptimized(true)`` is called. This way user can dynamically switch on and off the optimized code in OpenCV.
318 Returns the number of logical CPUs available for the process.
320 .. ocv:function:: int getNumberOfCPUs()
326 Returns the number of threads used by OpenCV for parallel regions.
327 Always returns 1 if OpenCV is built without threading support.
329 .. ocv:function:: int getNumThreads()
331 The exact meaning of return value depends on the threading framework used by OpenCV library:
333 * **TBB** – The number of threads, that OpenCV will try to use for parallel regions.
334 If there is any ``tbb::thread_scheduler_init`` in user code conflicting with OpenCV, then
335 function returns default number of threads used by TBB library.
336 * **OpenMP** – An upper bound on the number of threads that could be used to form a new team.
337 * **Concurrency** – The number of threads, that OpenCV will try to use for parallel regions.
338 * **GCD** – Unsupported; returns the GCD thread pool limit (512) for compatibility.
339 * **C=** – The number of threads, that OpenCV will try to use for parallel regions,
340 if before called ``setNumThreads`` with ``threads > 0``,
341 otherwise returns the number of logical CPUs, available for the process.
344 :ocv:func:`setNumThreads`,
345 :ocv:func:`getThreadNum`
351 Returns the index of the currently executed thread within the current parallel region.
352 Always returns 0 if called outside of parallel region.
354 .. ocv:function:: int getThreadNum()
356 The exact meaning of return value depends on the threading framework used by OpenCV library:
358 * **TBB** – Unsupported with current 4.1 TBB release. May be will be supported in future.
359 * **OpenMP** – The thread number, within the current team, of the calling thread.
360 * **Concurrency** – An ID for the virtual processor that the current context is executing
361 on (0 for master thread and unique number for others, but not necessary 1,2,3,...).
362 * **GCD** – System calling thread's ID. Never returns 0 inside parallel region.
363 * **C=** – The index of the current parallel task.
366 :ocv:func:`setNumThreads`,
367 :ocv:func:`getNumThreads`
373 Returns the number of ticks.
375 .. ocv:function:: int64 getTickCount()
377 .. ocv:pyfunction:: cv2.getTickCount() -> retval
379 The function returns the number of ticks after the certain event (for example, when the machine was turned on).
380 It can be used to initialize
381 :ocv:func:`RNG` or to measure a function execution time by reading the tick count before and after the function call. See also the tick frequency.
387 Returns the number of ticks per second.
389 .. ocv:function:: double getTickFrequency()
391 .. ocv:pyfunction:: cv2.getTickFrequency() -> retval
393 The function returns the number of ticks per second.
394 That is, the following code computes the execution time in seconds: ::
396 double t = (double)getTickCount();
398 t = ((double)getTickCount() - t)/getTickFrequency();
404 Returns the number of CPU ticks.
406 .. ocv:function:: int64 getCPUTickCount()
408 .. ocv:pyfunction:: cv2.getCPUTickCount() -> retval
410 The function returns the current number of CPU ticks on some architectures (such as x86, x64, PowerPC). On other platforms the function is equivalent to ``getTickCount``. It can also be used for very accurate time measurements, as well as for RNG initialization. Note that in case of multi-CPU systems a thread, from which ``getCPUTickCount`` is called, can be suspended and resumed at another CPU with its own counter. So, theoretically (and practically) the subsequent calls to the function do not necessary return the monotonously increasing values. Also, since a modern CPU varies the CPU frequency depending on the load, the number of CPU clocks spent in some code cannot be directly converted to time units. Therefore, ``getTickCount`` is generally a preferable solution for measuring execution time.
415 Template function for accurate conversion from one primitive type to another.
417 .. ocv:function:: template<...> _Tp saturate_cast(_Tp2 v)
419 :param v: Function parameter.
421 The functions ``saturate_cast`` resemble the standard C++ cast operations, such as ``static_cast<T>()`` and others. They perform an efficient and accurate conversion from one primitive type to another (see the introduction chapter). ``saturate`` in the name means that when the input value ``v`` is out of the range of the target type, the result is not formed just by taking low bits of the input, but instead the value is clipped. For example: ::
423 uchar a = saturate_cast<uchar>(-100); // a = 0 (UCHAR_MIN)
424 short b = saturate_cast<short>(33333.33333); // b = 32767 (SHRT_MAX)
426 Such clipping is done when the target type is ``unsigned char`` , ``signed char`` , ``unsigned short`` or ``signed short`` . For 32-bit integers, no clipping is done.
428 When the parameter is a floating-point value and the target type is an integer (8-, 16- or 32-bit), the floating-point value is first rounded to the nearest integer and then clipped if needed (when the target type is 8- or 16-bit).
430 This operation is used in the simplest or most complex image processing functions in OpenCV.
435 :ocv:func:`subtract`,
436 :ocv:func:`multiply`,
438 :ocv:func:`Mat::convertTo`
442 OpenCV will try to set the number of threads for the next parallel region.
443 If ``threads == 0``, OpenCV will disable threading optimizations and run all it's
444 functions sequentially. Passing ``threads < 0`` will reset threads number to system default.
445 This function must be called outside of parallel region.
447 .. ocv:function:: void setNumThreads(int nthreads)
449 :param nthreads: Number of threads used by OpenCV.
451 OpenCV will try to run it's functions with specified threads number, but
452 some behaviour differs from framework:
454 * **TBB** – User-defined parallel constructions will run with the same threads number,
455 if another does not specified. If late on user creates own scheduler, OpenCV will be use it.
456 * **OpenMP** – No special defined behaviour.
457 * **Concurrency** – If ``threads == 1``, OpenCV will disable threading optimizations
458 and run it's functions sequentially.
459 * **GCD** – Supports only values <= 0.
460 * **C=** – No special defined behaviour.
463 :ocv:func:`getNumThreads`,
464 :ocv:func:`getThreadNum`
470 Enables or disables the optimized code.
472 .. ocv:function:: int cvUseOptimized( int on_off )
474 .. ocv:pyfunction:: cv2.setUseOptimized(onoff) -> None
476 .. ocv:cfunction:: int cvUseOptimized( int on_off )
478 :param on_off: The boolean flag specifying whether the optimized code should be used (``on_off=true``) or not (``on_off=false``).
480 The function can be used to dynamically turn on and off optimized code (code that uses SSE2, AVX, and other instructions on the platforms that support it). It sets a global flag that is further checked by OpenCV functions. Since the flag is not checked in the inner OpenCV loops, it is only safe to call the function on the very top level in your application where you can be sure that no other OpenCV function is currently executed.
482 By default, the optimized code is enabled unless you disable it in CMake. The current status can be retrieved using ``useOptimized``.
486 Returns the status of optimized code usage.
488 .. ocv:function:: bool useOptimized()
490 .. ocv:pyfunction:: cv2.useOptimized() -> retval
492 The function returns ``true`` if the optimized code is enabled. Otherwise, it returns ``false``.