Merge remote-tracking branch 'upstream/master' into rho
This commit is contained in:
Olexa Bilaniuk
@@ -1,8 +0,0 @@
|
||||
*************************************************
|
||||
calib3d. Camera Calibration and 3D Reconstruction
|
||||
*************************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
camera_calibration_and_3d_reconstruction
|
||||
File diff suppressed because it is too large
Load Diff
@@ -666,7 +666,7 @@ findStereoCorrespondenceBM( const Mat& left, const Mat& right,
|
||||
int thresh = minsad + (minsad * uniquenessRatio/100);
|
||||
for( d = 0; d < ndisp; d++ )
|
||||
{
|
||||
if( sad[d] <= thresh && (d < mind-1 || d > mind+1))
|
||||
if( (d < mind-1 || d > mind+1) && sad[d] <= thresh)
|
||||
break;
|
||||
}
|
||||
if( d < ndisp )
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,101 +0,0 @@
|
||||
Clustering
|
||||
==========
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
kmeans
|
||||
------
|
||||
Finds centers of clusters and groups input samples around the clusters.
|
||||
|
||||
.. ocv:function:: double kmeans( InputArray data, int K, InputOutputArray bestLabels, TermCriteria criteria, int attempts, int flags, OutputArray centers=noArray() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.kmeans(data, K, bestLabels, criteria, attempts, flags[, centers]) -> retval, bestLabels, centers
|
||||
|
||||
.. ocv:cfunction:: int cvKMeans2( const CvArr* samples, int cluster_count, CvArr* labels, CvTermCriteria termcrit, int attempts=1, CvRNG* rng=0, int flags=0, CvArr* _centers=0, double* compactness=0 )
|
||||
|
||||
:param samples: Floating-point matrix of input samples, one row per sample.
|
||||
|
||||
:param data: Data for clustering. An array of N-Dimensional points with float coordinates is needed. Examples of this array can be:
|
||||
|
||||
* ``Mat points(count, 2, CV_32F);``
|
||||
|
||||
* ``Mat points(count, 1, CV_32FC2);``
|
||||
|
||||
* ``Mat points(1, count, CV_32FC2);``
|
||||
|
||||
* ``std::vector<cv::Point2f> points(sampleCount);``
|
||||
|
||||
:param cluster_count: Number of clusters to split the set by.
|
||||
|
||||
:param K: Number of clusters to split the set by.
|
||||
|
||||
:param labels: Input/output integer array that stores the cluster indices for every sample.
|
||||
|
||||
:param criteria: The algorithm termination criteria, that is, the maximum number of iterations and/or the desired accuracy. The accuracy is specified as ``criteria.epsilon``. As soon as each of the cluster centers moves by less than ``criteria.epsilon`` on some iteration, the algorithm stops.
|
||||
|
||||
:param termcrit: The algorithm termination criteria, that is, the maximum number of iterations and/or the desired accuracy.
|
||||
|
||||
:param attempts: Flag to specify the number of times the algorithm is executed using different initial labellings. The algorithm returns the labels that yield the best compactness (see the last function parameter).
|
||||
|
||||
:param rng: CvRNG state initialized by RNG().
|
||||
|
||||
:param flags: Flag that can take the following values:
|
||||
|
||||
* **KMEANS_RANDOM_CENTERS** Select random initial centers in each attempt.
|
||||
|
||||
* **KMEANS_PP_CENTERS** Use ``kmeans++`` center initialization by Arthur and Vassilvitskii [Arthur2007].
|
||||
|
||||
* **KMEANS_USE_INITIAL_LABELS** During the first (and possibly the only) attempt, use the user-supplied labels instead of computing them from the initial centers. For the second and further attempts, use the random or semi-random centers. Use one of ``KMEANS_*_CENTERS`` flag to specify the exact method.
|
||||
|
||||
:param centers: Output matrix of the cluster centers, one row per each cluster center.
|
||||
|
||||
:param _centers: Output matrix of the cluster centers, one row per each cluster center.
|
||||
|
||||
:param compactness: The returned value that is described below.
|
||||
|
||||
The function ``kmeans`` implements a k-means algorithm that finds the
|
||||
centers of ``cluster_count`` clusters and groups the input samples
|
||||
around the clusters. As an output,
|
||||
:math:`\texttt{labels}_i` contains a 0-based cluster index for
|
||||
the sample stored in the
|
||||
:math:`i^{th}` row of the ``samples`` matrix.
|
||||
|
||||
The function returns the compactness measure that is computed as
|
||||
|
||||
.. math::
|
||||
|
||||
\sum _i \| \texttt{samples} _i - \texttt{centers} _{ \texttt{labels} _i} \| ^2
|
||||
|
||||
after every attempt. The best (minimum) value is chosen and the
|
||||
corresponding labels and the compactness value are returned by the function.
|
||||
Basically, you can use only the core of the function, set the number of
|
||||
attempts to 1, initialize labels each time using a custom algorithm, pass them with the
|
||||
( ``flags`` = ``KMEANS_USE_INITIAL_LABELS`` ) flag, and then choose the best (most-compact) clustering.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example on K-means clustering can be found at opencv_source_code/samples/cpp/kmeans.cpp
|
||||
|
||||
* (Python) An example on K-means clustering can be found at opencv_source_code/samples/python2/kmeans.py
|
||||
|
||||
partition
|
||||
-------------
|
||||
Splits an element set into equivalency classes.
|
||||
|
||||
.. ocv:function:: template<typename _Tp, class _EqPredicate> int partition( const vector<_Tp>& vec, vector<int>& labels, _EqPredicate predicate=_EqPredicate())
|
||||
|
||||
:param vec: Set of elements stored as a vector.
|
||||
|
||||
:param labels: Output vector of labels. It contains as many elements as ``vec``. Each label ``labels[i]`` is a 0-based cluster index of ``vec[i]`` .
|
||||
|
||||
:param predicate: Equivalence predicate (pointer to a boolean function of two arguments or an instance of the class that has the method ``bool operator()(const _Tp& a, const _Tp& b)`` ). The predicate returns ``true`` when the elements are certainly in the same class, and returns ``false`` if they may or may not be in the same class.
|
||||
|
||||
The generic function ``partition`` implements an
|
||||
:math:`O(N^2)` algorithm for
|
||||
splitting a set of
|
||||
:math:`N` elements into one or more equivalency classes, as described in
|
||||
http://en.wikipedia.org/wiki/Disjoint-set_data_structure
|
||||
. The function
|
||||
returns the number of equivalency classes.
|
||||
|
||||
.. [Arthur2007] Arthur and S. Vassilvitskii. k-means++: the advantages of careful seeding, Proceedings of the eighteenth annual ACM-SIAM symposium on Discrete algorithms, 2007
|
||||
@@ -1,100 +0,0 @@
|
||||
Command Line Parser
|
||||
===================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
CommandLineParser
|
||||
-----------------
|
||||
.. ocv:class:: CommandLineParser
|
||||
|
||||
The CommandLineParser class is designed for command line arguments parsing
|
||||
|
||||
|
||||
.. ocv:function:: CommandLineParser::CommandLineParser( int argc, const char* const argv[], const String& keys )
|
||||
|
||||
:param argc:
|
||||
:param argv:
|
||||
:param keys:
|
||||
|
||||
.. ocv:function:: template<typename T> T CommandLineParser::get<T>(const String& name, bool space_delete = true)
|
||||
|
||||
:param name:
|
||||
:param space_delete:
|
||||
|
||||
.. ocv:function:: template<typename T> T CommandLineParser::get<T>(int index, bool space_delete = true)
|
||||
|
||||
:param index:
|
||||
:param space_delete:
|
||||
|
||||
.. ocv:function:: bool CommandLineParser::has(const String& name)
|
||||
|
||||
:param name:
|
||||
|
||||
.. ocv:function:: bool CommandLineParser::check()
|
||||
|
||||
|
||||
.. ocv:function:: void CommandLineParser::about( const String& message )
|
||||
|
||||
:param message:
|
||||
|
||||
.. ocv:function:: void CommandLineParser::printMessage()
|
||||
|
||||
.. ocv:function:: void CommandLineParser::printErrors()
|
||||
|
||||
.. ocv:function:: String CommandLineParser::getPathToApplication()
|
||||
|
||||
|
||||
The sample below demonstrates how to use CommandLineParser:
|
||||
|
||||
::
|
||||
|
||||
CommandLineParser parser(argc, argv, keys);
|
||||
parser.about("Application name v1.0.0");
|
||||
|
||||
if (parser.has("help"))
|
||||
{
|
||||
parser.printMessage();
|
||||
return 0;
|
||||
}
|
||||
|
||||
int N = parser.get<int>("N");
|
||||
double fps = parser.get<double>("fps");
|
||||
String path = parser.get<String>("path");
|
||||
|
||||
use_time_stamp = parser.has("timestamp");
|
||||
|
||||
String img1 = parser.get<String>(0);
|
||||
String img2 = parser.get<String>(1);
|
||||
|
||||
int repeat = parser.get<int>(2);
|
||||
|
||||
if (!parser.check())
|
||||
{
|
||||
parser.printErrors();
|
||||
return 0;
|
||||
}
|
||||
|
||||
Syntax:
|
||||
|
||||
::
|
||||
|
||||
const String keys =
|
||||
"{help h usage ? | | print this message }"
|
||||
"{@image1 | | image1 for compare }"
|
||||
"{@image2 | | image2 for compare }"
|
||||
"{@repeat |1 | number }"
|
||||
"{path |. | path to file }"
|
||||
"{fps | -1.0 | fps for output video }"
|
||||
"{N count |100 | count of objects }"
|
||||
"{ts timestamp | | use time stamp }"
|
||||
;
|
||||
|
||||
Use:
|
||||
|
||||
::
|
||||
|
||||
# ./app -N=200 1.png 2.jpg 19 -ts
|
||||
|
||||
# ./app -fps=aaa
|
||||
ERRORS:
|
||||
Exception: can not convert: [aaa] to [double]
|
||||
@@ -1,19 +0,0 @@
|
||||
****************************
|
||||
core. The Core Functionality
|
||||
****************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
basic_structures
|
||||
command_line_parser
|
||||
old_basic_structures
|
||||
dynamic_structures
|
||||
operations_on_arrays
|
||||
xml_yaml_persistence
|
||||
old_xml_yaml_persistence
|
||||
clustering
|
||||
utility_and_system_functions_and_macros
|
||||
opengl_interop
|
||||
ipp_async_converters
|
||||
optim
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,235 +0,0 @@
|
||||
************
|
||||
Introduction
|
||||
************
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
OpenCV (Open Source Computer Vision Library: http://opencv.org) is an open-source BSD-licensed library that includes several hundreds of computer vision algorithms. The document describes the so-called OpenCV 2.x API, which is essentially a C++ API, as opposite to the C-based OpenCV 1.x API. The latter is described in opencv1x.pdf.
|
||||
|
||||
OpenCV has a modular structure, which means that the package includes several shared or static libraries. The following modules are available:
|
||||
|
||||
* **core** - a compact module defining basic data structures, including the dense multi-dimensional array ``Mat`` and basic functions used by all other modules.
|
||||
* **imgproc** - an image processing module that includes linear and non-linear image filtering, geometrical image transformations (resize, affine and perspective warping, generic table-based remapping), color space conversion, histograms, and so on.
|
||||
* **video** - a video analysis module that includes motion estimation, background subtraction, and object tracking algorithms.
|
||||
* **calib3d** - basic multiple-view geometry algorithms, single and stereo camera calibration, object pose estimation, stereo correspondence algorithms, and elements of 3D reconstruction.
|
||||
* **features2d** - salient feature detectors, descriptors, and descriptor matchers.
|
||||
* **objdetect** - detection of objects and instances of the predefined classes (for example, faces, eyes, mugs, people, cars, and so on).
|
||||
* **highgui** - an easy-to-use interface to simple UI capabilities.
|
||||
* **videoio** - an easy-to-use interface to video capturing and video codecs.
|
||||
* **gpu** - GPU-accelerated algorithms from different OpenCV modules.
|
||||
* ... some other helper modules, such as FLANN and Google test wrappers, Python bindings, and others.
|
||||
|
||||
The further chapters of the document describe functionality of each module. But first, make sure to get familiar with the common API concepts used thoroughly in the library.
|
||||
|
||||
API Concepts
|
||||
================
|
||||
|
||||
``cv`` Namespace
|
||||
------------------
|
||||
|
||||
All the OpenCV classes and functions are placed into the ``cv`` namespace. Therefore, to access this functionality from your code, use the ``cv::`` specifier or ``using namespace cv;`` directive:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "opencv2/core.hpp"
|
||||
...
|
||||
cv::Mat H = cv::findHomography(points1, points2, CV_RANSAC, 5);
|
||||
...
|
||||
|
||||
or ::
|
||||
|
||||
#include "opencv2/core.hpp"
|
||||
using namespace cv;
|
||||
...
|
||||
Mat H = findHomography(points1, points2, CV_RANSAC, 5 );
|
||||
...
|
||||
|
||||
Some of the current or future OpenCV external names may conflict with STL
|
||||
or other libraries. In this case, use explicit namespace specifiers to resolve the name conflicts: ::
|
||||
|
||||
Mat a(100, 100, CV_32F);
|
||||
randu(a, Scalar::all(1), Scalar::all(std::rand()));
|
||||
cv::log(a, a);
|
||||
a /= std::log(2.);
|
||||
|
||||
Automatic Memory Management
|
||||
---------------------------
|
||||
|
||||
OpenCV handles all the memory automatically.
|
||||
|
||||
First of all, ``std::vector``, ``Mat``, and other data structures used by the functions and methods have destructors that deallocate the underlying memory buffers when needed. This means that the destructors do not always deallocate the buffers as in case of ``Mat``. They take into account possible data sharing. A destructor decrements the reference counter associated with the matrix data buffer. The buffer is deallocated if and only if the reference counter reaches zero, that is, when no other structures refer to the same buffer. Similarly, when a ``Mat`` instance is copied, no actual data is really copied. Instead, the reference counter is incremented to memorize that there is another owner of the same data. There is also the ``Mat::clone`` method that creates a full copy of the matrix data. See the example below: ::
|
||||
|
||||
// create a big 8Mb matrix
|
||||
Mat A(1000, 1000, CV_64F);
|
||||
|
||||
// create another header for the same matrix;
|
||||
// this is an instant operation, regardless of the matrix size.
|
||||
Mat B = A;
|
||||
// create another header for the 3-rd row of A; no data is copied either
|
||||
Mat C = B.row(3);
|
||||
// now create a separate copy of the matrix
|
||||
Mat D = B.clone();
|
||||
// copy the 5-th row of B to C, that is, copy the 5-th row of A
|
||||
// to the 3-rd row of A.
|
||||
B.row(5).copyTo(C);
|
||||
// now let A and D share the data; after that the modified version
|
||||
// of A is still referenced by B and C.
|
||||
A = D;
|
||||
// now make B an empty matrix (which references no memory buffers),
|
||||
// but the modified version of A will still be referenced by C,
|
||||
// despite that C is just a single row of the original A
|
||||
B.release();
|
||||
|
||||
// finally, make a full copy of C. As a result, the big modified
|
||||
// matrix will be deallocated, since it is not referenced by anyone
|
||||
C = C.clone();
|
||||
|
||||
You see that the use of ``Mat`` and other basic structures is simple. But what about high-level classes or even user
|
||||
data types created without taking automatic memory management into account? For them, OpenCV offers the :ocv:class:`Ptr`
|
||||
template class that is similar to ``std::shared_ptr`` from C++11. So, instead of using plain pointers::
|
||||
|
||||
T* ptr = new T(...);
|
||||
|
||||
you can use::
|
||||
|
||||
Ptr<T> ptr(new T(...));
|
||||
|
||||
or::
|
||||
|
||||
Ptr<T> ptr = makePtr<T>(...);
|
||||
|
||||
``Ptr<T>`` encapsulates a pointer to a ``T`` instance and a reference counter associated with the pointer. See the
|
||||
:ocv:class:`Ptr` description for details.
|
||||
|
||||
.. _AutomaticAllocation:
|
||||
|
||||
Automatic Allocation of the Output Data
|
||||
---------------------------------------
|
||||
|
||||
OpenCV deallocates the memory automatically, as well as automatically allocates the memory for output function parameters most of the time. So, if a function has one or more input arrays (``cv::Mat`` instances) and some output arrays, the output arrays are automatically allocated or reallocated. The size and type of the output arrays are determined from the size and type of input arrays. If needed, the functions take extra parameters that help to figure out the output array properties.
|
||||
|
||||
Example: ::
|
||||
|
||||
#include "opencv2/imgproc.hpp"
|
||||
#include "opencv2/highgui.hpp"
|
||||
|
||||
using namespace cv;
|
||||
|
||||
int main(int, char**)
|
||||
{
|
||||
VideoCapture cap(0);
|
||||
if(!cap.isOpened()) return -1;
|
||||
|
||||
Mat frame, edges;
|
||||
namedWindow("edges",1);
|
||||
for(;;)
|
||||
{
|
||||
cap >> frame;
|
||||
cvtColor(frame, edges, COLOR_BGR2GRAY);
|
||||
GaussianBlur(edges, edges, Size(7,7), 1.5, 1.5);
|
||||
Canny(edges, edges, 0, 30, 3);
|
||||
imshow("edges", edges);
|
||||
if(waitKey(30) >= 0) break;
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
|
||||
The array ``frame`` is automatically allocated by the ``>>`` operator since the video frame resolution and the bit-depth is known to the video capturing module. The array ``edges`` is automatically allocated by the ``cvtColor`` function. It has the same size and the bit-depth as the input array. The number of channels is 1 because the color conversion code ``COLOR_BGR2GRAY`` is passed, which means a color to grayscale conversion. Note that ``frame`` and ``edges`` are allocated only once during the first execution of the loop body since all the next video frames have the same resolution. If you somehow change the video resolution, the arrays are automatically reallocated.
|
||||
|
||||
The key component of this technology is the ``Mat::create`` method. It takes the desired array size and type. If the array already has the specified size and type, the method does nothing. Otherwise, it releases the previously allocated data, if any (this part involves decrementing the reference counter and comparing it with zero), and then allocates a new buffer of the required size. Most functions call the ``Mat::create`` method for each output array, and so the automatic output data allocation is implemented.
|
||||
|
||||
Some notable exceptions from this scheme are ``cv::mixChannels``, ``cv::RNG::fill``, and a few other functions and methods. They are not able to allocate the output array, so you have to do this in advance.
|
||||
|
||||
Saturation Arithmetics
|
||||
----------------------
|
||||
|
||||
As a computer vision library, OpenCV deals a lot with image pixels that are often encoded in a compact, 8- or 16-bit per channel, form and thus have a limited value range. Furthermore, certain operations on images, like color space conversions, brightness/contrast adjustments, sharpening, complex interpolation (bi-cubic, Lanczos) can produce values out of the available range. If you just store the lowest 8 (16) bits of the result, this results in visual artifacts and may affect a further image analysis. To solve this problem, the so-called *saturation* arithmetics is used. For example, to store ``r``, the result of an operation, to an 8-bit image, you find the nearest value within the 0..255 range:
|
||||
|
||||
.. math::
|
||||
|
||||
I(x,y)= \min ( \max (\textrm{round}(r), 0), 255)
|
||||
|
||||
Similar rules are applied to 8-bit signed, 16-bit signed and unsigned types. This semantics is used everywhere in the library. In C++ code, it is done using the ``saturate_cast<>`` functions that resemble standard C++ cast operations. See below the implementation of the formula provided above::
|
||||
|
||||
I.at<uchar>(y, x) = saturate_cast<uchar>(r);
|
||||
|
||||
where ``cv::uchar`` is an OpenCV 8-bit unsigned integer type. In the optimized SIMD code, such SSE2 instructions as ``paddusb``, ``packuswb``, and so on are used. They help achieve exactly the same behavior as in C++ code.
|
||||
|
||||
.. note:: Saturation is not applied when the result is 32-bit integer.
|
||||
|
||||
Fixed Pixel Types. Limited Use of Templates
|
||||
-------------------------------------------
|
||||
|
||||
Templates is a great feature of C++ that enables implementation of very powerful, efficient and yet safe data structures and algorithms. However, the extensive use of templates may dramatically increase compilation time and code size. Besides, it is difficult to separate an interface and implementation when templates are used exclusively. This could be fine for basic algorithms but not good for computer vision libraries where a single algorithm may span thousands lines of code. Because of this and also to simplify development of bindings for other languages, like Python, Java, Matlab that do not have templates at all or have limited template capabilities, the current OpenCV implementation is based on polymorphism and runtime dispatching over templates. In those places where runtime dispatching would be too slow (like pixel access operators), impossible (generic ``Ptr<>`` implementation), or just very inconvenient (``saturate_cast<>()``) the current implementation introduces small template classes, methods, and functions. Anywhere else in the current OpenCV version the use of templates is limited.
|
||||
|
||||
Consequently, there is a limited fixed set of primitive data types the library can operate on. That is, array elements should have one of the following types:
|
||||
|
||||
* 8-bit unsigned integer (uchar)
|
||||
* 8-bit signed integer (schar)
|
||||
* 16-bit unsigned integer (ushort)
|
||||
* 16-bit signed integer (short)
|
||||
* 32-bit signed integer (int)
|
||||
* 32-bit floating-point number (float)
|
||||
* 64-bit floating-point number (double)
|
||||
* a tuple of several elements where all elements have the same type (one of the above). An array whose elements are such tuples, are called multi-channel arrays, as opposite to the single-channel arrays, whose elements are scalar values. The maximum possible number of channels is defined by the ``CV_CN_MAX`` constant, which is currently set to 512.
|
||||
|
||||
For these basic types, the following enumeration is applied::
|
||||
|
||||
enum { CV_8U=0, CV_8S=1, CV_16U=2, CV_16S=3, CV_32S=4, CV_32F=5, CV_64F=6 };
|
||||
|
||||
Multi-channel (``n``-channel) types can be specified using the following options:
|
||||
|
||||
* ``CV_8UC1`` ... ``CV_64FC4`` constants (for a number of channels from 1 to 4)
|
||||
* ``CV_8UC(n)`` ... ``CV_64FC(n)`` or ``CV_MAKETYPE(CV_8U, n)`` ... ``CV_MAKETYPE(CV_64F, n)`` macros when the number of channels is more than 4 or unknown at the compilation time.
|
||||
|
||||
.. note:: ``CV_32FC1 == CV_32F``, ``CV_32FC2 == CV_32FC(2) == CV_MAKETYPE(CV_32F, 2)``, and ``CV_MAKETYPE(depth, n) == ((x&7)<<3) + (n-1)``. This means that the constant type is formed from the ``depth``, taking the lowest 3 bits, and the number of channels minus 1, taking the next ``log2(CV_CN_MAX)`` bits.
|
||||
|
||||
Examples: ::
|
||||
|
||||
Mat mtx(3, 3, CV_32F); // make a 3x3 floating-point matrix
|
||||
Mat cmtx(10, 1, CV_64FC2); // make a 10x1 2-channel floating-point
|
||||
// matrix (10-element complex vector)
|
||||
Mat img(Size(1920, 1080), CV_8UC3); // make a 3-channel (color) image
|
||||
// of 1920 columns and 1080 rows.
|
||||
Mat grayscale(image.size(), CV_MAKETYPE(image.depth(), 1)); // make a 1-channel image of
|
||||
// the same size and same
|
||||
// channel type as img
|
||||
|
||||
Arrays with more complex elements cannot be constructed or processed using OpenCV. Furthermore, each function or method can handle only a subset of all possible array types. Usually, the more complex the algorithm is, the smaller the supported subset of formats is. See below typical examples of such limitations:
|
||||
|
||||
* The face detection algorithm only works with 8-bit grayscale or color images.
|
||||
* Linear algebra functions and most of the machine learning algorithms work with floating-point arrays only.
|
||||
* Basic functions, such as ``cv::add``, support all types.
|
||||
* Color space conversion functions support 8-bit unsigned, 16-bit unsigned, and 32-bit floating-point types.
|
||||
|
||||
The subset of supported types for each function has been defined from practical needs and could be extended in future based on user requests.
|
||||
|
||||
|
||||
InputArray and OutputArray
|
||||
--------------------------
|
||||
|
||||
Many OpenCV functions process dense 2-dimensional or multi-dimensional numerical arrays. Usually, such functions take cpp:class:`Mat` as parameters, but in some cases it's more convenient to use ``std::vector<>`` (for a point set, for example) or ``Matx<>`` (for 3x3 homography matrix and such). To avoid many duplicates in the API, special "proxy" classes have been introduced. The base "proxy" class is ``InputArray``. It is used for passing read-only arrays on a function input. The derived from ``InputArray`` class ``OutputArray`` is used to specify an output array for a function. Normally, you should not care of those intermediate types (and you should not declare variables of those types explicitly) - it will all just work automatically. You can assume that instead of ``InputArray``/``OutputArray`` you can always use ``Mat``, ``std::vector<>``, ``Matx<>``, ``Vec<>`` or ``Scalar``. When a function has an optional input or output array, and you do not have or do not want one, pass ``cv::noArray()``.
|
||||
|
||||
Error Handling
|
||||
--------------
|
||||
|
||||
OpenCV uses exceptions to signal critical errors. When the input data has a correct format and belongs to the specified value range, but the algorithm cannot succeed for some reason (for example, the optimization algorithm did not converge), it returns a special error code (typically, just a boolean variable).
|
||||
|
||||
The exceptions can be instances of the ``cv::Exception`` class or its derivatives. In its turn, ``cv::Exception`` is a derivative of ``std::exception``. So it can be gracefully handled in the code using other standard C++ library components.
|
||||
|
||||
The exception is typically thrown either using the ``CV_Error(errcode, description)`` macro, or its printf-like ``CV_Error_(errcode, printf-spec, (printf-args))`` variant, or using the ``CV_Assert(condition)`` macro that checks the condition and throws an exception when it is not satisfied. For performance-critical code, there is ``CV_DbgAssert(condition)`` that is only retained in the Debug configuration. Due to the automatic memory management, all the intermediate buffers are automatically deallocated in case of a sudden error. You only need to add a try statement to catch exceptions, if needed: ::
|
||||
|
||||
try
|
||||
{
|
||||
... // call OpenCV
|
||||
}
|
||||
catch( cv::Exception& e )
|
||||
{
|
||||
const char* err_msg = e.what();
|
||||
std::cout << "exception caught: " << err_msg << std::endl;
|
||||
}
|
||||
|
||||
Multi-threading and Re-enterability
|
||||
-----------------------------------
|
||||
|
||||
The current OpenCV implementation is fully re-enterable. That is, the same function, the same *constant* method of a class instance, or the same *non-constant* method of different class instances can be called from different threads. Also, the same ``cv::Mat`` can be used in different threads because the reference-counting operations use the architecture-specific atomic instructions.
|
||||
@@ -1,72 +0,0 @@
|
||||
Intel® IPP Asynchronous C/C++ Converters
|
||||
========================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
General Information
|
||||
-------------------
|
||||
|
||||
This section describes conversion between OpenCV and `Intel® IPP Asynchronous C/C++ <http://software.intel.com/en-us/intel-ipp-preview>`_ library.
|
||||
`Getting Started Guide <http://registrationcenter.intel.com/irc_nas/3727/ipp_async_get_started.htm>`_ help you to install the library, configure header and library build paths.
|
||||
|
||||
hpp::getHpp
|
||||
-----------
|
||||
Create ``hppiMatrix`` from ``Mat``.
|
||||
|
||||
.. ocv:function:: hppiMatrix* hpp::getHpp(const Mat& src, hppAccel accel)
|
||||
|
||||
:param src: input matrix.
|
||||
:param accel: accelerator instance. Supports type:
|
||||
|
||||
* **HPP_ACCEL_TYPE_CPU** - accelerated by optimized CPU instructions.
|
||||
|
||||
* **HPP_ACCEL_TYPE_GPU** - accelerated by GPU programmable units or fixed-function accelerators.
|
||||
|
||||
* **HPP_ACCEL_TYPE_ANY** - any acceleration or no acceleration available.
|
||||
|
||||
This function allocates and initializes the ``hppiMatrix`` that has the same size and type as input matrix, returns the ``hppiMatrix*``.
|
||||
|
||||
If you want to use zero-copy for GPU you should to have 4KB aligned matrix data. See details `hppiCreateSharedMatrix <http://software.intel.com/ru-ru/node/501697>`_.
|
||||
|
||||
Supports ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32S``, ``CV_32F``, ``CV_64F``.
|
||||
|
||||
.. note:: The ``hppiMatrix`` pointer to the image buffer in system memory refers to the ``src.data``. Control the lifetime of the matrix and don't change its data, if there is no special need.
|
||||
.. seealso:: :ref:`howToUseIPPAconversion`, :ocv:func:`hpp::getMat`
|
||||
|
||||
|
||||
hpp::getMat
|
||||
-----------
|
||||
Create ``Mat`` from ``hppiMatrix``.
|
||||
|
||||
.. ocv:function:: Mat hpp::getMat(hppiMatrix* src, hppAccel accel, int cn)
|
||||
|
||||
:param src: input hppiMatrix.
|
||||
|
||||
:param accel: accelerator instance (see :ocv:func:`hpp::getHpp` for the list of acceleration framework types).
|
||||
|
||||
:param cn: number of channels.
|
||||
|
||||
This function allocates and initializes the ``Mat`` that has the same size and type as input matrix.
|
||||
Supports ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32S``, ``CV_32F``, ``CV_64F``.
|
||||
|
||||
.. seealso:: :ref:`howToUseIPPAconversion`, :ocv:func:`hpp::copyHppToMat`, :ocv:func:`hpp::getHpp`.
|
||||
|
||||
|
||||
hpp::copyHppToMat
|
||||
-----------------
|
||||
Convert ``hppiMatrix`` to ``Mat``.
|
||||
|
||||
.. ocv:function:: void hpp::copyHppToMat(hppiMatrix* src, Mat& dst, hppAccel accel, int cn)
|
||||
|
||||
:param src: input hppiMatrix.
|
||||
|
||||
:param dst: output matrix.
|
||||
|
||||
:param accel: accelerator instance (see :ocv:func:`hpp::getHpp` for the list of acceleration framework types).
|
||||
|
||||
:param cn: number of channels.
|
||||
|
||||
This function allocates and initializes new matrix (if needed) that has the same size and type as input matrix.
|
||||
Supports ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32S``, ``CV_32F``, ``CV_64F``.
|
||||
|
||||
.. seealso:: :ref:`howToUseIPPAconversion`, :ocv:func:`hpp::getMat`, :ocv:func:`hpp::getHpp`.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,909 +0,0 @@
|
||||
XML/YAML Persistence (C API)
|
||||
==============================
|
||||
|
||||
The section describes the OpenCV 1.x API for reading and writing data structures to/from XML or YAML files. It is now recommended to use the new C++ interface for reading and writing data.
|
||||
|
||||
.. highlight:: c
|
||||
|
||||
CvFileStorage
|
||||
-------------
|
||||
|
||||
.. ocv:struct:: CvFileStorage
|
||||
|
||||
The structure ``CvFileStorage`` is a "black box" representation of the file storage associated with a file on disk. Several functions that are described below take ``CvFileStorage*`` as inputs and allow the user to save or to load hierarchical collections that consist of scalar values, standard CXCore objects (such as matrices, sequences, graphs), and user-defined objects.
|
||||
|
||||
OpenCV can read and write data in XML (http://www.w3c.org/XML) or YAML
|
||||
(http://www.yaml.org) formats. Below is an example of 3x3 floating-point identity matrix ``A``, stored in XML and YAML files using CXCore functions:
|
||||
|
||||
XML: ::
|
||||
|
||||
<?xml version="1.0">
|
||||
<opencv_storage>
|
||||
<A type_id="opencv-matrix">
|
||||
<rows>3</rows>
|
||||
<cols>3</cols>
|
||||
<dt>f</dt>
|
||||
<data>1. 0. 0. 0. 1. 0. 0. 0. 1.</data>
|
||||
</A>
|
||||
</opencv_storage>
|
||||
|
||||
YAML: ::
|
||||
|
||||
%YAML:1.0
|
||||
A: !!opencv-matrix
|
||||
rows: 3
|
||||
cols: 3
|
||||
dt: f
|
||||
data: [ 1., 0., 0., 0., 1., 0., 0., 0., 1.]
|
||||
|
||||
As it can be seen from the examples, XML uses nested tags to represent
|
||||
hierarchy, while YAML uses indentation for that purpose (similar
|
||||
to the Python programming language).
|
||||
|
||||
The same functions can read and write data in both formats;
|
||||
the particular format is determined by the extension of the opened file, ".xml" for XML files and ".yml" or ".yaml" for YAML.
|
||||
|
||||
CvFileNode
|
||||
----------
|
||||
|
||||
.. ocv:struct:: CvFileNode
|
||||
|
||||
File storage node. When XML/YAML file is read, it is first parsed and stored in the memory as a hierarchical collection of nodes. Each node can be a "leaf", that is, contain a single number or a string, or be a collection of other nodes. Collections are also referenced to as "structures" in the data writing functions. There can be named collections (mappings), where each element has a name and is accessed by a name, and ordered collections (sequences), where elements do not have names, but rather accessed by index.
|
||||
|
||||
.. ocv:member:: int tag
|
||||
|
||||
type of the file node:
|
||||
|
||||
* CV_NODE_NONE - empty node
|
||||
* CV_NODE_INT - an integer
|
||||
* CV_NODE_REAL - a floating-point number
|
||||
* CV_NODE_STR - text string
|
||||
* CV_NODE_SEQ - a sequence
|
||||
* CV_NODE_MAP - a mapping
|
||||
|
||||
type of the node can be retrieved using ``CV_NODE_TYPE(node->tag)`` macro.
|
||||
|
||||
.. ocv:member:: CvTypeInfo* info
|
||||
|
||||
optional pointer to the user type information. If you look at the matrix representation in XML and YAML, shown above, you may notice ``type_id="opencv-matrix"`` or ``!!opencv-matrix`` strings. They are used to specify that the certain element of a file is a representation of a data structure of certain type ("opencv-matrix" corresponds to :ocv:struct:`CvMat`). When a file is parsed, such type identifiers are passed to :ocv:cfunc:`FindType` to find type information and the pointer to it is stored in the file node. See :ocv:struct:`CvTypeInfo` for more details.
|
||||
|
||||
.. ocv:member:: union data
|
||||
|
||||
the node data, declared as: ::
|
||||
|
||||
union
|
||||
{
|
||||
double f; /* scalar floating-point number */
|
||||
int i; /* scalar integer number */
|
||||
CvString str; /* text string */
|
||||
CvSeq* seq; /* sequence (ordered collection of file nodes) */
|
||||
struct CvMap* map; /* map (collection of named file nodes) */
|
||||
} data;
|
||||
|
||||
..
|
||||
|
||||
Primitive nodes are read using :ocv:cfunc:`ReadInt`, :ocv:cfunc:`ReadReal` and :ocv:cfunc:`ReadString`. Sequences are read by iterating through ``node->data.seq`` (see "Dynamic Data Structures" section). Mappings are read using :ocv:cfunc:`GetFileNodeByName`. Nodes with the specified type (so that ``node->info != NULL``) can be read using :ocv:cfunc:`Read`.
|
||||
|
||||
CvAttrList
|
||||
----------
|
||||
|
||||
.. ocv:struct:: CvAttrList
|
||||
|
||||
List of attributes. ::
|
||||
|
||||
typedef struct CvAttrList
|
||||
{
|
||||
const char** attr; /* NULL-terminated array of (attribute_name,attribute_value) pairs */
|
||||
struct CvAttrList* next; /* pointer to next chunk of the attributes list */
|
||||
}
|
||||
CvAttrList;
|
||||
|
||||
/* initializes CvAttrList structure */
|
||||
inline CvAttrList cvAttrList( const char** attr=NULL, CvAttrList* next=NULL );
|
||||
|
||||
/* returns attribute value or 0 (NULL) if there is no such attribute */
|
||||
const char* cvAttrValue( const CvAttrList* attr, const char* attr_name );
|
||||
|
||||
..
|
||||
|
||||
In the current implementation, attributes are used to pass extra parameters when writing user objects (see
|
||||
:ocv:cfunc:`Write`). XML attributes inside tags are not supported, aside from the object type specification (``type_id`` attribute).
|
||||
|
||||
CvTypeInfo
|
||||
----------
|
||||
|
||||
.. ocv:struct:: CvTypeInfo
|
||||
|
||||
Type information. ::
|
||||
|
||||
typedef int (CV_CDECL *CvIsInstanceFunc)( const void* structPtr );
|
||||
typedef void (CV_CDECL *CvReleaseFunc)( void** structDblPtr );
|
||||
typedef void* (CV_CDECL *CvReadFunc)( CvFileStorage* storage, CvFileNode* node );
|
||||
typedef void (CV_CDECL *CvWriteFunc)( CvFileStorage* storage,
|
||||
const char* name,
|
||||
const void* structPtr,
|
||||
CvAttrList attributes );
|
||||
typedef void* (CV_CDECL *CvCloneFunc)( const void* structPtr );
|
||||
|
||||
typedef struct CvTypeInfo
|
||||
{
|
||||
int flags; /* not used */
|
||||
int header_size; /* sizeof(CvTypeInfo) */
|
||||
struct CvTypeInfo* prev; /* previous registered type in the list */
|
||||
struct CvTypeInfo* next; /* next registered type in the list */
|
||||
const char* type_name; /* type name, written to file storage */
|
||||
|
||||
/* methods */
|
||||
CvIsInstanceFunc is_instance; /* checks if the passed object belongs to the type */
|
||||
CvReleaseFunc release; /* releases object (memory etc.) */
|
||||
CvReadFunc read; /* reads object from file storage */
|
||||
CvWriteFunc write; /* writes object to file storage */
|
||||
CvCloneFunc clone; /* creates a copy of the object */
|
||||
}
|
||||
CvTypeInfo;
|
||||
|
||||
..
|
||||
|
||||
The structure contains information about one of the standard or user-defined types. Instances of the type may or may not contain a pointer to the corresponding :ocv:struct:`CvTypeInfo` structure. In any case, there is a way to find the type info structure for a given object using the :ocv:cfunc:`TypeOf` function. Alternatively, type info can be found by type name using :ocv:cfunc:`FindType`, which is used when an object is read from file storage. The user can register a new type with :ocv:cfunc:`RegisterType`
|
||||
that adds the type information structure into the beginning of the type list. Thus, it is possible to create specialized types from generic standard types and override the basic methods.
|
||||
|
||||
Clone
|
||||
-----
|
||||
Makes a clone of an object.
|
||||
|
||||
.. ocv:cfunction:: void* cvClone( const void* struct_ptr )
|
||||
|
||||
:param struct_ptr: The object to clone
|
||||
|
||||
The function finds the type of a given object and calls ``clone`` with the passed object. Of course, if you know the object type, for example, ``struct_ptr`` is ``CvMat*``, it is faster to call the specific function, like :ocv:cfunc:`CloneMat`.
|
||||
|
||||
EndWriteStruct
|
||||
--------------
|
||||
Finishes writing to a file node collection.
|
||||
|
||||
.. ocv:cfunction:: void cvEndWriteStruct(CvFileStorage* fs)
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
.. seealso:: :ocv:cfunc:`StartWriteStruct`.
|
||||
|
||||
FindType
|
||||
--------
|
||||
Finds a type by its name.
|
||||
|
||||
.. ocv:cfunction:: CvTypeInfo* cvFindType( const char* type_name )
|
||||
|
||||
:param type_name: Type name
|
||||
|
||||
The function finds a registered type by its name. It returns NULL if there is no type with the specified name.
|
||||
|
||||
FirstType
|
||||
---------
|
||||
Returns the beginning of a type list.
|
||||
|
||||
.. ocv:cfunction:: CvTypeInfo* cvFirstType(void)
|
||||
|
||||
The function returns the first type in the list of registered types. Navigation through the list can be done via the ``prev`` and ``next`` fields of the :ocv:struct:`CvTypeInfo` structure.
|
||||
|
||||
GetFileNode
|
||||
-----------
|
||||
Finds a node in a map or file storage.
|
||||
|
||||
.. ocv:cfunction:: CvFileNode* cvGetFileNode( CvFileStorage* fs, CvFileNode* map, const CvStringHashNode* key, int create_missing=0 )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param map: The parent map. If it is NULL, the function searches a top-level node. If both ``map`` and ``key`` are NULLs, the function returns the root file node - a map that contains top-level nodes.
|
||||
|
||||
:param key: Unique pointer to the node name, retrieved with :ocv:cfunc:`GetHashedKey`
|
||||
|
||||
:param create_missing: Flag that specifies whether an absent node should be added to the map
|
||||
|
||||
The function finds a file node. It is a faster version of :ocv:cfunc:`GetFileNodeByName`
|
||||
(see :ocv:cfunc:`GetHashedKey` discussion). Also, the function can insert a new node, if it is not in the map yet.
|
||||
|
||||
GetFileNodeByName
|
||||
-----------------
|
||||
Finds a node in a map or file storage.
|
||||
|
||||
.. ocv:cfunction:: CvFileNode* cvGetFileNodeByName( const CvFileStorage* fs, const CvFileNode* map, const char* name)
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param map: The parent map. If it is NULL, the function searches in all the top-level nodes (streams), starting with the first one.
|
||||
|
||||
:param name: The file node name
|
||||
|
||||
The function finds a file node by ``name``. The node is searched either in ``map`` or, if the pointer is NULL, among the top-level file storage nodes. Using this function for maps and :ocv:cfunc:`GetSeqElem`
|
||||
(or sequence reader) for sequences, it is possible to navigate through the file storage. To speed up multiple queries for a certain key (e.g., in the case of an array of structures) one may use a combination of :ocv:cfunc:`GetHashedKey` and :ocv:cfunc:`GetFileNode`.
|
||||
|
||||
GetFileNodeName
|
||||
---------------
|
||||
Returns the name of a file node.
|
||||
|
||||
.. ocv:cfunction:: const char* cvGetFileNodeName( const CvFileNode* node )
|
||||
|
||||
:param node: File node
|
||||
|
||||
The function returns the name of a file node or NULL, if the file node does not have a name or if ``node`` is ``NULL``.
|
||||
|
||||
GetHashedKey
|
||||
------------
|
||||
Returns a unique pointer for a given name.
|
||||
|
||||
.. ocv:cfunction:: CvStringHashNode* cvGetHashedKey( CvFileStorage* fs, const char* name, int len=-1, int create_missing=0 )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param name: Literal node name
|
||||
|
||||
:param len: Length of the name (if it is known apriori), or -1 if it needs to be calculated
|
||||
|
||||
:param create_missing: Flag that specifies, whether an absent key should be added into the hash table
|
||||
|
||||
The function returns a unique pointer for each particular file node name. This pointer can be then passed to the :ocv:cfunc:`GetFileNode` function that is faster than :ocv:cfunc:`GetFileNodeByName`
|
||||
because it compares text strings by comparing pointers rather than the strings' content.
|
||||
|
||||
Consider the following example where an array of points is encoded as a sequence of 2-entry maps: ::
|
||||
|
||||
points:
|
||||
- { x: 10, y: 10 }
|
||||
- { x: 20, y: 20 }
|
||||
- { x: 30, y: 30 }
|
||||
# ...
|
||||
|
||||
..
|
||||
|
||||
Then, it is possible to get hashed "x" and "y" pointers to speed up decoding of the points. ::
|
||||
|
||||
#include "cxcore.h"
|
||||
|
||||
int main( int argc, char** argv )
|
||||
{
|
||||
CvFileStorage* fs = cvOpenFileStorage( "points.yml", 0, CV_STORAGE_READ );
|
||||
CvStringHashNode* x_key = cvGetHashedNode( fs, "x", -1, 1 );
|
||||
CvStringHashNode* y_key = cvGetHashedNode( fs, "y", -1, 1 );
|
||||
CvFileNode* points = cvGetFileNodeByName( fs, 0, "points" );
|
||||
|
||||
if( CV_NODE_IS_SEQ(points->tag) )
|
||||
{
|
||||
CvSeq* seq = points->data.seq;
|
||||
int i, total = seq->total;
|
||||
CvSeqReader reader;
|
||||
cvStartReadSeq( seq, &reader, 0 );
|
||||
for( i = 0; i < total; i++ )
|
||||
{
|
||||
CvFileNode* pt = (CvFileNode*)reader.ptr;
|
||||
#if 1 /* faster variant */
|
||||
CvFileNode* xnode = cvGetFileNode( fs, pt, x_key, 0 );
|
||||
CvFileNode* ynode = cvGetFileNode( fs, pt, y_key, 0 );
|
||||
assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
|
||||
ynode && CV_NODE_IS_INT(ynode->tag));
|
||||
int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
|
||||
int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
|
||||
#elif 1 /* slower variant; does not use x_key & y_key */
|
||||
CvFileNode* xnode = cvGetFileNodeByName( fs, pt, "x" );
|
||||
CvFileNode* ynode = cvGetFileNodeByName( fs, pt, "y" );
|
||||
assert( xnode && CV_NODE_IS_INT(xnode->tag) &&
|
||||
ynode && CV_NODE_IS_INT(ynode->tag));
|
||||
int x = xnode->data.i; // or x = cvReadInt( xnode, 0 );
|
||||
int y = ynode->data.i; // or y = cvReadInt( ynode, 0 );
|
||||
#else /* the slowest yet the easiest to use variant */
|
||||
int x = cvReadIntByName( fs, pt, "x", 0 /* default value */ );
|
||||
int y = cvReadIntByName( fs, pt, "y", 0 /* default value */ );
|
||||
#endif
|
||||
CV_NEXT_SEQ_ELEM( seq->elem_size, reader );
|
||||
printf("
|
||||
}
|
||||
}
|
||||
cvReleaseFileStorage( &fs );
|
||||
return 0;
|
||||
}
|
||||
|
||||
..
|
||||
|
||||
Please note that whatever method of accessing a map you are using, it is
|
||||
still much slower than using plain sequences; for example, in the above
|
||||
example, it is more efficient to encode the points as pairs of integers
|
||||
in a single numeric sequence.
|
||||
|
||||
GetRootFileNode
|
||||
---------------
|
||||
Retrieves one of the top-level nodes of the file storage.
|
||||
|
||||
.. ocv:cfunction:: CvFileNode* cvGetRootFileNode( const CvFileStorage* fs, int stream_index=0 )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param stream_index: Zero-based index of the stream. See :ocv:cfunc:`StartNextStream` . In most cases, there is only one stream in the file; however, there can be several.
|
||||
|
||||
The function returns one of the top-level file nodes. The top-level nodes do not have a name, they correspond to the streams that are stored one after another in the file storage. If the index is out of range, the function returns a NULL pointer, so all the top-level nodes can be iterated by subsequent calls to the function with ``stream_index=0,1,...``, until the NULL pointer is returned. This function
|
||||
can be used as a base for recursive traversal of the file storage.
|
||||
|
||||
|
||||
Load
|
||||
----
|
||||
Loads an object from a file.
|
||||
|
||||
.. ocv:cfunction:: void* cvLoad( const char* filename, CvMemStorage* memstorage=NULL, const char* name=NULL, const char** real_name=NULL )
|
||||
|
||||
:param filename: File name
|
||||
|
||||
:param memstorage: Memory storage for dynamic structures, such as :ocv:struct:`CvSeq` or :ocv:struct:`CvGraph` . It is not used for matrices or images.
|
||||
|
||||
:param name: Optional object name. If it is NULL, the first top-level object in the storage will be loaded.
|
||||
|
||||
:param real_name: Optional output parameter that will contain the name of the loaded object (useful if ``name=NULL`` )
|
||||
|
||||
The function loads an object from a file. It basically reads the specified file, find the first top-level node and calls :ocv:cfunc:`Read` for that node. If the file node does not have type information or the type information can not be found by the type name, the function returns NULL. After the object is loaded, the file storage is closed and all the temporary buffers are deleted. Thus, to load a dynamic structure, such as a sequence, contour, or graph, one should pass a valid memory storage destination to the function.
|
||||
|
||||
OpenFileStorage
|
||||
---------------
|
||||
Opens file storage for reading or writing data.
|
||||
|
||||
.. ocv:cfunction:: CvFileStorage* cvOpenFileStorage( const char* filename, CvMemStorage* memstorage, int flags, const char* encoding=NULL )
|
||||
|
||||
:param filename: Name of the file associated with the storage
|
||||
|
||||
:param memstorage: Memory storage used for temporary data and for
|
||||
storing dynamic structures, such as :ocv:struct:`CvSeq` or :ocv:struct:`CvGraph` .
|
||||
If it is NULL, a temporary memory storage is created and used.
|
||||
|
||||
:param flags: Can be one of the following:
|
||||
|
||||
* **CV_STORAGE_READ** the storage is open for reading
|
||||
|
||||
* **CV_STORAGE_WRITE** the storage is open for writing
|
||||
|
||||
The function opens file storage for reading or writing data. In the latter case, a new file is created or an existing file is rewritten. The type of the read or written file is determined by the filename extension: ``.xml`` for ``XML`` and ``.yml`` or ``.yaml`` for ``YAML``. The function returns a pointer to the :ocv:struct:`CvFileStorage` structure. If the file cannot be opened then the function returns ``NULL``.
|
||||
|
||||
Read
|
||||
----
|
||||
Decodes an object and returns a pointer to it.
|
||||
|
||||
.. ocv:cfunction:: void* cvRead( CvFileStorage* fs, CvFileNode* node, CvAttrList* attributes=NULL )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param node: The root object node
|
||||
|
||||
:param attributes: Unused parameter
|
||||
|
||||
The function decodes a user object (creates an object in a native representation from the file storage subtree) and returns it. The object to be decoded must be an instance of a registered type that supports the ``read`` method (see :ocv:struct:`CvTypeInfo`). The type of the object is determined by the type name that is encoded in the file. If the object is a dynamic structure, it is created either in memory storage and passed to :ocv:cfunc:`OpenFileStorage` or, if a NULL pointer was passed, in temporary
|
||||
memory storage, which is released when :ocv:cfunc:`ReleaseFileStorage` is called. Otherwise, if the object is not a dynamic structure, it is created in a heap and should be released with a specialized function or by using the generic :ocv:cfunc:`Release`.
|
||||
|
||||
ReadByName
|
||||
----------
|
||||
Finds an object by name and decodes it.
|
||||
|
||||
.. ocv:cfunction:: void* cvReadByName( CvFileStorage* fs, const CvFileNode* map, const char* name, CvAttrList* attributes=NULL )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param map: The parent map. If it is NULL, the function searches a top-level node.
|
||||
|
||||
:param name: The node name
|
||||
|
||||
:param attributes: Unused parameter
|
||||
|
||||
The function is a simple superposition of :ocv:cfunc:`GetFileNodeByName` and :ocv:cfunc:`Read`.
|
||||
|
||||
ReadInt
|
||||
-------
|
||||
Retrieves an integer value from a file node.
|
||||
|
||||
.. ocv:cfunction:: int cvReadInt( const CvFileNode* node, int default_value=0 )
|
||||
|
||||
:param node: File node
|
||||
|
||||
:param default_value: The value that is returned if ``node`` is NULL
|
||||
|
||||
The function returns an integer that is represented by the file node. If the file node is NULL, the
|
||||
``default_value`` is returned (thus, it is convenient to call the function right after :ocv:cfunc:`GetFileNode` without checking for a NULL pointer). If the file node has type ``CV_NODE_INT``, then ``node->data.i`` is returned. If the file node has type ``CV_NODE_REAL``, then ``node->data.f``
|
||||
is converted to an integer and returned. Otherwise the error is reported.
|
||||
|
||||
ReadIntByName
|
||||
-------------
|
||||
Finds a file node and returns its value.
|
||||
|
||||
.. ocv:cfunction:: int cvReadIntByName( const CvFileStorage* fs, const CvFileNode* map, const char* name, int default_value=0 )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param map: The parent map. If it is NULL, the function searches a top-level node.
|
||||
|
||||
:param name: The node name
|
||||
|
||||
:param default_value: The value that is returned if the file node is not found
|
||||
|
||||
The function is a simple superposition of :ocv:cfunc:`GetFileNodeByName` and :ocv:cfunc:`ReadInt`.
|
||||
|
||||
ReadRawData
|
||||
-----------
|
||||
Reads multiple numbers.
|
||||
|
||||
.. ocv:cfunction:: void cvReadRawData( const CvFileStorage* fs, const CvFileNode* src, void* dst, const char* dt)
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param src: The file node (a sequence) to read numbers from
|
||||
|
||||
:param dst: Pointer to the destination array
|
||||
|
||||
:param dt: Specification of each array element. It has the same format as in :ocv:cfunc:`WriteRawData` .
|
||||
|
||||
The function reads elements from a file node that represents a sequence of scalars.
|
||||
|
||||
|
||||
ReadRawDataSlice
|
||||
----------------
|
||||
Initializes file node sequence reader.
|
||||
|
||||
.. ocv:cfunction:: void cvReadRawDataSlice( const CvFileStorage* fs, CvSeqReader* reader, int count, void* dst, const char* dt )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param reader: The sequence reader. Initialize it with :ocv:cfunc:`StartReadRawData` .
|
||||
|
||||
:param count: The number of elements to read
|
||||
|
||||
:param dst: Pointer to the destination array
|
||||
|
||||
:param dt: Specification of each array element. It has the same format as in :ocv:cfunc:`WriteRawData` .
|
||||
|
||||
The function reads one or more elements from the file node, representing a sequence, to a user-specified array. The total number of read sequence elements is a product of ``total``
|
||||
and the number of components in each array element. For example, if ``dt=2if``, the function will read ``total*3`` sequence elements. As with any sequence, some parts of the file node sequence can be skipped or read repeatedly by repositioning the reader using :ocv:cfunc:`SetSeqReaderPos`.
|
||||
|
||||
ReadReal
|
||||
--------
|
||||
Retrieves a floating-point value from a file node.
|
||||
|
||||
.. ocv:cfunction:: double cvReadReal( const CvFileNode* node, double default_value=0. )
|
||||
|
||||
:param node: File node
|
||||
|
||||
:param default_value: The value that is returned if ``node`` is NULL
|
||||
|
||||
The function returns a floating-point value
|
||||
that is represented by the file node. If the file node is NULL, the
|
||||
``default_value``
|
||||
is returned (thus, it is convenient to call
|
||||
the function right after
|
||||
:ocv:cfunc:`GetFileNode`
|
||||
without checking for a NULL
|
||||
pointer). If the file node has type
|
||||
``CV_NODE_REAL``
|
||||
,
|
||||
then
|
||||
``node->data.f``
|
||||
is returned. If the file node has type
|
||||
``CV_NODE_INT``
|
||||
, then
|
||||
``node-:math:`>`data.f``
|
||||
is converted to floating-point
|
||||
and returned. Otherwise the result is not determined.
|
||||
|
||||
|
||||
ReadRealByName
|
||||
--------------
|
||||
Finds a file node and returns its value.
|
||||
|
||||
.. ocv:cfunction:: double cvReadRealByName( const CvFileStorage* fs, const CvFileNode* map, const char* name, double default_value=0. )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param map: The parent map. If it is NULL, the function searches a top-level node.
|
||||
|
||||
:param name: The node name
|
||||
|
||||
:param default_value: The value that is returned if the file node is not found
|
||||
|
||||
The function is a simple superposition of
|
||||
:ocv:cfunc:`GetFileNodeByName`
|
||||
and
|
||||
:ocv:cfunc:`ReadReal`
|
||||
.
|
||||
|
||||
|
||||
ReadString
|
||||
----------
|
||||
Retrieves a text string from a file node.
|
||||
|
||||
.. ocv:cfunction:: const char* cvReadString( const CvFileNode* node, const char* default_value=NULL )
|
||||
|
||||
:param node: File node
|
||||
|
||||
:param default_value: The value that is returned if ``node`` is NULL
|
||||
|
||||
The function returns a text string that is represented
|
||||
by the file node. If the file node is NULL, the
|
||||
``default_value``
|
||||
is returned (thus, it is convenient to call the function right after
|
||||
:ocv:cfunc:`GetFileNode`
|
||||
without checking for a NULL pointer). If
|
||||
the file node has type
|
||||
``CV_NODE_STR``
|
||||
, then
|
||||
``node-:math:`>`data.str.ptr``
|
||||
is returned. Otherwise the result is not determined.
|
||||
|
||||
|
||||
ReadStringByName
|
||||
----------------
|
||||
Finds a file node by its name and returns its value.
|
||||
|
||||
.. ocv:cfunction:: const char* cvReadStringByName( const CvFileStorage* fs, const CvFileNode* map, const char* name, const char* default_value=NULL )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param map: The parent map. If it is NULL, the function searches a top-level node.
|
||||
|
||||
:param name: The node name
|
||||
|
||||
:param default_value: The value that is returned if the file node is not found
|
||||
|
||||
The function is a simple superposition of
|
||||
:ocv:cfunc:`GetFileNodeByName`
|
||||
and
|
||||
:ocv:cfunc:`ReadString`
|
||||
.
|
||||
|
||||
|
||||
RegisterType
|
||||
------------
|
||||
Registers a new type.
|
||||
|
||||
.. ocv:cfunction:: void cvRegisterType(const CvTypeInfo* info)
|
||||
|
||||
:param info: Type info structure
|
||||
|
||||
The function registers a new type, which is
|
||||
described by
|
||||
``info``
|
||||
. The function creates a copy of the structure,
|
||||
so the user should delete it after calling the function.
|
||||
|
||||
|
||||
Release
|
||||
-------
|
||||
Releases an object.
|
||||
|
||||
.. ocv:cfunction:: void cvRelease( void** struct_ptr )
|
||||
|
||||
:param struct_ptr: Double pointer to the object
|
||||
|
||||
The function finds the type of a given object and calls
|
||||
``release``
|
||||
with the double pointer.
|
||||
|
||||
|
||||
ReleaseFileStorage
|
||||
------------------
|
||||
Releases file storage.
|
||||
|
||||
.. ocv:cfunction:: void cvReleaseFileStorage(CvFileStorage** fs)
|
||||
|
||||
:param fs: Double pointer to the released file storage
|
||||
|
||||
The function closes the file associated with the storage and releases all the temporary structures. It must be called after all I/O operations with the storage are finished.
|
||||
|
||||
|
||||
Save
|
||||
----
|
||||
Saves an object to a file.
|
||||
|
||||
.. ocv:cfunction:: void cvSave( const char* filename, const void* struct_ptr, const char* name=NULL, const char* comment=NULL, CvAttrList attributes=cvAttrList() )
|
||||
|
||||
:param filename: File name
|
||||
|
||||
:param struct_ptr: Object to save
|
||||
|
||||
:param name: Optional object name. If it is NULL, the name will be formed from ``filename`` .
|
||||
|
||||
:param comment: Optional comment to put in the beginning of the file
|
||||
|
||||
:param attributes: Optional attributes passed to :ocv:cfunc:`Write`
|
||||
|
||||
The function saves an object to a file. It provides a simple interface to
|
||||
:ocv:cfunc:`Write`
|
||||
.
|
||||
|
||||
|
||||
StartNextStream
|
||||
---------------
|
||||
Starts the next stream.
|
||||
|
||||
.. ocv:cfunction:: void cvStartNextStream(CvFileStorage* fs)
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
The function finishes the currently written stream and starts the next stream. In the case of XML the file with multiple streams looks like this: ::
|
||||
|
||||
<opencv_storage>
|
||||
<!-- stream #1 data -->
|
||||
</opencv_storage>
|
||||
<opencv_storage>
|
||||
<!-- stream #2 data -->
|
||||
</opencv_storage>
|
||||
...
|
||||
|
||||
The YAML file will look like this: ::
|
||||
|
||||
%YAML:1.0
|
||||
# stream #1 data
|
||||
...
|
||||
---
|
||||
# stream #2 data
|
||||
|
||||
This is useful for concatenating files or for resuming the writing process.
|
||||
|
||||
|
||||
StartReadRawData
|
||||
----------------
|
||||
Initializes the file node sequence reader.
|
||||
|
||||
.. ocv:cfunction:: void cvStartReadRawData( const CvFileStorage* fs, const CvFileNode* src, CvSeqReader* reader)
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param src: The file node (a sequence) to read numbers from
|
||||
|
||||
:param reader: Pointer to the sequence reader
|
||||
|
||||
The function initializes the sequence reader to read data from a file node. The initialized reader can be then passed to :ocv:cfunc:`ReadRawDataSlice`.
|
||||
|
||||
|
||||
StartWriteStruct
|
||||
----------------
|
||||
Starts writing a new structure.
|
||||
|
||||
.. ocv:cfunction:: void cvStartWriteStruct( CvFileStorage* fs, const char* name, int struct_flags, const char* type_name=NULL, CvAttrList attributes=cvAttrList() )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param name: Name of the written structure. The structure can be accessed by this name when the storage is read.
|
||||
|
||||
:param struct_flags: A combination one of the following values:
|
||||
|
||||
* **CV_NODE_SEQ** the written structure is a sequence (see discussion of :ocv:struct:`CvFileStorage` ), that is, its elements do not have a name.
|
||||
|
||||
* **CV_NODE_MAP** the written structure is a map (see discussion of :ocv:struct:`CvFileStorage` ), that is, all its elements have names.
|
||||
|
||||
One and only one of the two above flags must be specified
|
||||
|
||||
* **CV_NODE_FLOW** the optional flag that makes sense only for YAML streams. It means that the structure is written as a flow (not as a block), which is more compact. It is recommended to use this flag for structures or arrays whose elements are all scalars.
|
||||
|
||||
:param type_name: Optional parameter - the object type name. In
|
||||
case of XML it is written as a ``type_id`` attribute of the
|
||||
structure opening tag. In the case of YAML it is written after a colon
|
||||
following the structure name (see the example in :ocv:struct:`CvFileStorage`
|
||||
description). Mainly it is used with user objects. When the storage
|
||||
is read, the encoded type name is used to determine the object type
|
||||
(see :ocv:struct:`CvTypeInfo` and :ocv:cfunc:`FindType` ).
|
||||
|
||||
:param attributes: This parameter is not used in the current implementation
|
||||
|
||||
The function starts writing a compound structure (collection) that can be a sequence or a map. After all the structure fields, which can be scalars or structures, are written, :ocv:cfunc:`EndWriteStruct` should be called. The function can be used to group some objects or to implement the ``write`` function for a some user object (see :ocv:struct:`CvTypeInfo`).
|
||||
|
||||
|
||||
TypeOf
|
||||
------
|
||||
Returns the type of an object.
|
||||
|
||||
.. ocv:cfunction:: CvTypeInfo* cvTypeOf( const void* struct_ptr )
|
||||
|
||||
:param struct_ptr: The object pointer
|
||||
|
||||
The function finds the type of a given object. It iterates through the list of registered types and calls the ``is_instance`` function/method for every type info structure with that object until one of them returns non-zero or until the whole list has been traversed. In the latter case, the function returns NULL.
|
||||
|
||||
|
||||
UnregisterType
|
||||
--------------
|
||||
Unregisters the type.
|
||||
|
||||
.. ocv:cfunction:: void cvUnregisterType( const char* type_name )
|
||||
|
||||
:param type_name: Name of an unregistered type
|
||||
|
||||
The function unregisters a type with a specified name. If the name is unknown, it is possible to locate the type info by an instance of the type using :ocv:cfunc:`TypeOf` or by iterating the type list, starting from :ocv:cfunc:`FirstType`, and then calling ``cvUnregisterType(info->typeName)``.
|
||||
|
||||
|
||||
Write
|
||||
-----
|
||||
Writes an object to file storage.
|
||||
|
||||
.. ocv:cfunction:: void cvWrite( CvFileStorage* fs, const char* name, const void* ptr, CvAttrList attributes=cvAttrList() )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param name: Name of the written object. Should be NULL if and only if the parent structure is a sequence.
|
||||
|
||||
:param ptr: Pointer to the object
|
||||
|
||||
:param attributes: The attributes of the object. They are specific for each particular type (see the discussion below).
|
||||
|
||||
The function writes an object to file storage. First, the appropriate type info is found using :ocv:cfunc:`TypeOf`. Then, the ``write`` method associated with the type info is called.
|
||||
|
||||
Attributes are used to customize the writing procedure. The standard types support the following attributes (all the ``dt`` attributes have the same format as in :ocv:cfunc:`WriteRawData`):
|
||||
|
||||
#.
|
||||
CvSeq
|
||||
|
||||
* **header_dt** description of user fields of the sequence header that follow CvSeq, or CvChain (if the sequence is a Freeman chain) or CvContour (if the sequence is a contour or point sequence)
|
||||
|
||||
* **dt** description of the sequence elements.
|
||||
|
||||
* **recursive** if the attribute is present and is not equal to "0" or "false", the whole tree of sequences (contours) is stored.
|
||||
|
||||
#.
|
||||
CvGraph
|
||||
|
||||
* **header_dt** description of user fields of the graph header that follows CvGraph;
|
||||
|
||||
* **vertex_dt** description of user fields of graph vertices
|
||||
|
||||
* **edge_dt** description of user fields of graph edges (note that the edge weight is always written, so there is no need to specify it explicitly)
|
||||
|
||||
Below is the code that creates the YAML file shown in the
|
||||
``CvFileStorage``
|
||||
description:
|
||||
|
||||
::
|
||||
|
||||
#include "cxcore.h"
|
||||
|
||||
int main( int argc, char** argv )
|
||||
{
|
||||
CvMat* mat = cvCreateMat( 3, 3, CV_32F );
|
||||
CvFileStorage* fs = cvOpenFileStorage( "example.yml", 0, CV_STORAGE_WRITE );
|
||||
|
||||
cvSetIdentity( mat );
|
||||
cvWrite( fs, "A", mat, cvAttrList(0,0) );
|
||||
|
||||
cvReleaseFileStorage( &fs );
|
||||
cvReleaseMat( &mat );
|
||||
return 0;
|
||||
}
|
||||
|
||||
..
|
||||
|
||||
|
||||
WriteComment
|
||||
------------
|
||||
Writes a comment.
|
||||
|
||||
.. ocv:cfunction:: void cvWriteComment( CvFileStorage* fs, const char* comment, int eol_comment )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param comment: The written comment, single-line or multi-line
|
||||
|
||||
:param eol_comment: If non-zero, the function tries to put the comment at the end of current line. If the flag is zero, if the comment is multi-line, or if it does not fit at the end of the current line, the comment starts a new line.
|
||||
|
||||
The function writes a comment into file storage. The comments are skipped when the storage is read.
|
||||
|
||||
WriteFileNode
|
||||
-------------
|
||||
Writes a file node to another file storage.
|
||||
|
||||
.. ocv:cfunction:: void cvWriteFileNode( CvFileStorage* fs, const char* new_node_name, const CvFileNode* node, int embed )
|
||||
|
||||
:param fs: Destination file storage
|
||||
|
||||
:param new_node_name: New name of the file node in the destination file storage. To keep the existing name, use :ocv:cfunc:`cvGetFileNodeName`
|
||||
|
||||
:param node: The written node
|
||||
|
||||
:param embed: If the written node is a collection and this parameter is not zero, no extra level of hierarchy is created. Instead, all the elements of ``node`` are written into the currently written structure. Of course, map elements can only be embedded into another map, and sequence elements can only be embedded into another sequence.
|
||||
|
||||
The function writes a copy of a file node to file storage. Possible applications of the function are merging several file storages into one and conversion between XML and YAML formats.
|
||||
|
||||
WriteInt
|
||||
--------
|
||||
Writes an integer value.
|
||||
|
||||
.. ocv:cfunction:: void cvWriteInt( CvFileStorage* fs, const char* name, int value)
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param name: Name of the written value. Should be NULL if and only if the parent structure is a sequence.
|
||||
|
||||
:param value: The written value
|
||||
|
||||
The function writes a single integer value (with or without a name) to the file storage.
|
||||
|
||||
|
||||
WriteRawData
|
||||
------------
|
||||
Writes multiple numbers.
|
||||
|
||||
.. ocv:cfunction:: void cvWriteRawData( CvFileStorage* fs, const void* src, int len, const char* dt )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param src: Pointer to the written array
|
||||
|
||||
:param len: Number of the array elements to write
|
||||
|
||||
:param dt: Specification of each array element that has the following format ``([count]{'u'|'c'|'w'|'s'|'i'|'f'|'d'})...``
|
||||
where the characters correspond to fundamental C types:
|
||||
|
||||
* **u** 8-bit unsigned number
|
||||
|
||||
* **c** 8-bit signed number
|
||||
|
||||
* **w** 16-bit unsigned number
|
||||
|
||||
* **s** 16-bit signed number
|
||||
|
||||
* **i** 32-bit signed number
|
||||
|
||||
* **f** single precision floating-point number
|
||||
|
||||
* **d** double precision floating-point number
|
||||
|
||||
* **r** pointer, 32 lower bits of which are written as a signed integer. The type can be used to store structures with links between the elements. ``count`` is the optional counter of values of a given type. For
|
||||
example, ``2if`` means that each array element is a structure
|
||||
of 2 integers, followed by a single-precision floating-point number. The
|
||||
equivalent notations of the above specification are ' ``iif`` ',
|
||||
' ``2i1f`` ' and so forth. Other examples: ``u`` means that the
|
||||
array consists of bytes, and ``2d`` means the array consists of pairs
|
||||
of doubles.
|
||||
|
||||
The function writes an array, whose elements consist
|
||||
of single or multiple numbers. The function call can be replaced with
|
||||
a loop containing a few
|
||||
:ocv:cfunc:`WriteInt`
|
||||
and
|
||||
:ocv:cfunc:`WriteReal`
|
||||
calls, but
|
||||
a single call is more efficient. Note that because none of the elements
|
||||
have a name, they should be written to a sequence rather than a map.
|
||||
|
||||
|
||||
WriteReal
|
||||
---------
|
||||
Writes a floating-point value.
|
||||
|
||||
.. ocv:cfunction:: void cvWriteReal( CvFileStorage* fs, const char* name, double value )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param name: Name of the written value. Should be NULL if and only if the parent structure is a sequence.
|
||||
|
||||
:param value: The written value
|
||||
|
||||
The function writes a single floating-point value (with or without a name) to file storage. Special values are encoded as follows: NaN (Not A Number) as .NaN, infinity as +.Inf or -.Inf.
|
||||
|
||||
The following example shows how to use the low-level writing functions to store custom structures, such as termination criteria, without registering a new type. ::
|
||||
|
||||
void write_termcriteria( CvFileStorage* fs, const char* struct_name,
|
||||
CvTermCriteria* termcrit )
|
||||
{
|
||||
cvStartWriteStruct( fs, struct_name, CV_NODE_MAP, NULL, cvAttrList(0,0));
|
||||
cvWriteComment( fs, "termination criteria", 1 ); // just a description
|
||||
if( termcrit->type & CV_TERMCRIT_ITER )
|
||||
cvWriteInteger( fs, "max_iterations", termcrit->max_iter );
|
||||
if( termcrit->type & CV_TERMCRIT_EPS )
|
||||
cvWriteReal( fs, "accuracy", termcrit->epsilon );
|
||||
cvEndWriteStruct( fs );
|
||||
}
|
||||
|
||||
..
|
||||
|
||||
|
||||
WriteString
|
||||
-----------
|
||||
Writes a text string.
|
||||
|
||||
.. ocv:cfunction:: void cvWriteString( CvFileStorage* fs, const char* name, const char* str, int quote=0 )
|
||||
|
||||
:param fs: File storage
|
||||
|
||||
:param name: Name of the written string . Should be NULL if and only if the parent structure is a sequence.
|
||||
|
||||
:param str: The written text string
|
||||
|
||||
:param quote: If non-zero, the written string is put in quotes, regardless of whether they are required. Otherwise, if the flag is zero, quotes are used only when they are required (e.g. when the string starts with a digit or contains spaces).
|
||||
|
||||
The function writes a text string to file storage.
|
||||
@@ -1,543 +0,0 @@
|
||||
OpenGL interoperability
|
||||
=======================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
General Information
|
||||
-------------------
|
||||
This section describes OpenGL interoperability.
|
||||
|
||||
To enable OpenGL support, configure OpenCV using ``CMake`` with ``WITH_OPENGL=ON`` .
|
||||
Currently OpenGL is supported only with WIN32, GTK and Qt backends on Windows and Linux (MacOS and Android are not supported).
|
||||
For GTK backend ``gtkglext-1.0`` library is required.
|
||||
|
||||
To use OpenGL functionality you should first create OpenGL context (window or frame buffer).
|
||||
You can do this with :ocv:func:`namedWindow` function or with other OpenGL toolkit (GLUT, for example).
|
||||
|
||||
|
||||
|
||||
ogl::Buffer
|
||||
-----------
|
||||
Smart pointer for OpenGL buffer object with reference counting.
|
||||
|
||||
.. ocv:class:: ogl::Buffer
|
||||
|
||||
Buffer Objects are OpenGL objects that store an array of unformatted memory allocated by the OpenGL context.
|
||||
These can be used to store vertex data, pixel data retrieved from images or the framebuffer, and a variety of other things.
|
||||
|
||||
``ogl::Buffer`` has interface similar with :ocv:class:`Mat` interface and represents 2D array memory.
|
||||
|
||||
``ogl::Buffer`` supports memory transfers between host and device and also can be mapped to CUDA memory.
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::Target
|
||||
-------------------
|
||||
The target defines how you intend to use the buffer object.
|
||||
|
||||
.. ocv:enum:: ogl::Buffer::Target
|
||||
|
||||
.. ocv:emember:: ARRAY_BUFFER
|
||||
|
||||
The buffer will be used as a source for vertex data.
|
||||
|
||||
.. ocv:emember:: ELEMENT_ARRAY_BUFFER
|
||||
|
||||
The buffer will be used for indices (in ``glDrawElements`` or :ocv:func:`ogl::render`, for example).
|
||||
|
||||
.. ocv:emember:: PIXEL_PACK_BUFFER
|
||||
|
||||
The buffer will be used for reading from OpenGL textures.
|
||||
|
||||
.. ocv:emember:: PIXEL_UNPACK_BUFFER
|
||||
|
||||
The buffer will be used for writing to OpenGL textures.
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::Buffer
|
||||
-------------------
|
||||
The constructors.
|
||||
|
||||
.. ocv:function:: ogl::Buffer::Buffer()
|
||||
|
||||
.. ocv:function:: ogl::Buffer::Buffer(int arows, int acols, int atype, unsigned int abufId, bool autoRelease = false)
|
||||
|
||||
.. ocv:function:: ogl::Buffer::Buffer(Size asize, int atype, unsigned int abufId, bool autoRelease = false)
|
||||
|
||||
.. ocv:function:: ogl::Buffer::Buffer(int arows, int acols, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
|
||||
|
||||
.. ocv:function:: ogl::Buffer::Buffer(Size asize, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
|
||||
|
||||
.. ocv:function:: ogl::Buffer::Buffer(InputArray arr, Target target = ARRAY_BUFFER, bool autoRelease = false)
|
||||
|
||||
:param arows: Number of rows in a 2D array.
|
||||
|
||||
:param acols: Number of columns in a 2D array.
|
||||
|
||||
:param asize: 2D array size.
|
||||
|
||||
:param atype: Array type ( ``CV_8UC1, ..., CV_64FC4`` ). See :ocv:class:`Mat` for details.
|
||||
|
||||
:param abufId: Buffer object name.
|
||||
|
||||
:param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` or ``std::vector`` ).
|
||||
|
||||
:param target: Buffer usage. See :ocv:enum:`ogl::Buffer::Target` .
|
||||
|
||||
:param autoRelease: Auto release mode (if true, release will be called in object's destructor).
|
||||
|
||||
Creates empty ``ogl::Buffer`` object, creates ``ogl::Buffer`` object from existed buffer ( ``abufId`` parameter),
|
||||
allocates memory for ``ogl::Buffer`` object or copies from host/device memory.
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::create
|
||||
-------------------
|
||||
Allocates memory for ``ogl::Buffer`` object.
|
||||
|
||||
.. ocv:function:: void ogl::Buffer::create(int arows, int acols, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
|
||||
|
||||
.. ocv:function:: void ogl::Buffer::create(Size asize, int atype, Target target = ARRAY_BUFFER, bool autoRelease = false)
|
||||
|
||||
:param arows: Number of rows in a 2D array.
|
||||
|
||||
:param acols: Number of columns in a 2D array.
|
||||
|
||||
:param asize: 2D array size.
|
||||
|
||||
:param atype: Array type ( ``CV_8UC1, ..., CV_64FC4`` ). See :ocv:class:`Mat` for details.
|
||||
|
||||
:param target: Buffer usage. See :ocv:enum:`ogl::Buffer::Target` .
|
||||
|
||||
:param autoRelease: Auto release mode (if true, release will be called in object's destructor).
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::release
|
||||
--------------------
|
||||
Decrements the reference counter and destroys the buffer object if needed.
|
||||
|
||||
.. ocv:function:: void ogl::Buffer::release()
|
||||
|
||||
The function will call `setAutoRelease(true)` .
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::setAutoRelease
|
||||
---------------------------
|
||||
Sets auto release mode.
|
||||
|
||||
.. ocv:function:: void ogl::Buffer::setAutoRelease(bool flag)
|
||||
|
||||
:param flag: Auto release mode (if true, release will be called in object's destructor).
|
||||
|
||||
The lifetime of the OpenGL object is tied to the lifetime of the context.
|
||||
If OpenGL context was bound to a window it could be released at any time (user can close a window).
|
||||
If object's destructor is called after destruction of the context it will cause an error.
|
||||
Thus ``ogl::Buffer`` doesn't destroy OpenGL object in destructor by default (all OpenGL resources will be released with OpenGL context).
|
||||
This function can force ``ogl::Buffer`` destructor to destroy OpenGL object.
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::copyFrom
|
||||
---------------------
|
||||
Copies from host/device memory to OpenGL buffer.
|
||||
|
||||
.. ocv:function:: void ogl::Buffer::copyFrom(InputArray arr, Target target = ARRAY_BUFFER, bool autoRelease = false)
|
||||
|
||||
:param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` or ``std::vector`` ).
|
||||
|
||||
:param target: Buffer usage. See :ocv:enum:`ogl::Buffer::Target` .
|
||||
|
||||
:param autoRelease: Auto release mode (if true, release will be called in object's destructor).
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::copyTo
|
||||
-------------------
|
||||
Copies from OpenGL buffer to host/device memory or another OpenGL buffer object.
|
||||
|
||||
.. ocv:function:: void ogl::Buffer::copyTo(OutputArray arr) const
|
||||
|
||||
:param arr: Destination array (host or device memory, can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` , ``std::vector`` or ``ogl::Buffer`` ).
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::clone
|
||||
------------------
|
||||
Creates a full copy of the buffer object and the underlying data.
|
||||
|
||||
.. ocv:function:: Buffer ogl::Buffer::clone(Target target = ARRAY_BUFFER, bool autoRelease = false) const
|
||||
|
||||
:param target: Buffer usage for destination buffer.
|
||||
|
||||
:param autoRelease: Auto release mode for destination buffer.
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::bind
|
||||
-----------------
|
||||
Binds OpenGL buffer to the specified buffer binding point.
|
||||
|
||||
.. ocv:function:: void ogl::Buffer::bind(Target target) const
|
||||
|
||||
:param target: Binding point. See :ocv:enum:`ogl::Buffer::Target` .
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::unbind
|
||||
-------------------
|
||||
Unbind any buffers from the specified binding point.
|
||||
|
||||
.. ocv:function:: static void ogl::Buffer::unbind(Target target)
|
||||
|
||||
:param target: Binding point. See :ocv:enum:`ogl::Buffer::Target` .
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::mapHost
|
||||
--------------------
|
||||
Maps OpenGL buffer to host memory.
|
||||
|
||||
.. ocv:function:: Mat ogl::Buffer::mapHost(Access access)
|
||||
|
||||
:param access: Access policy, indicating whether it will be possible to read from, write to, or both read from and write to the buffer object's mapped data store. The symbolic constant must be ``ogl::Buffer::READ_ONLY`` , ``ogl::Buffer::WRITE_ONLY`` or ``ogl::Buffer::READ_WRITE`` .
|
||||
|
||||
``mapHost`` maps to the client's address space the entire data store of the buffer object.
|
||||
The data can then be directly read and/or written relative to the returned pointer, depending on the specified ``access`` policy.
|
||||
|
||||
A mapped data store must be unmapped with :ocv:func:`ogl::Buffer::unmapHost` before its buffer object is used.
|
||||
|
||||
This operation can lead to memory transfers between host and device.
|
||||
|
||||
Only one buffer object can be mapped at a time.
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::unmapHost
|
||||
----------------------
|
||||
Unmaps OpenGL buffer.
|
||||
|
||||
.. ocv:function:: void ogl::Buffer::unmapHost()
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::mapDevice
|
||||
----------------------
|
||||
Maps OpenGL buffer to CUDA device memory.
|
||||
|
||||
.. ocv:function:: cuda::GpuMat ogl::Buffer::mapDevice()
|
||||
|
||||
This operatation doesn't copy data.
|
||||
Several buffer objects can be mapped to CUDA memory at a time.
|
||||
|
||||
A mapped data store must be unmapped with :ocv:func:`ogl::Buffer::unmapDevice` before its buffer object is used.
|
||||
|
||||
|
||||
|
||||
ogl::Buffer::unmapDevice
|
||||
------------------------
|
||||
Unmaps OpenGL buffer.
|
||||
|
||||
.. ocv:function:: void ogl::Buffer::unmapDevice()
|
||||
|
||||
|
||||
|
||||
ogl::Texture2D
|
||||
--------------
|
||||
Smart pointer for OpenGL 2D texture memory with reference counting.
|
||||
|
||||
.. ocv:class:: ogl::Texture2D
|
||||
|
||||
|
||||
|
||||
ogl::Texture2D::Format
|
||||
----------------------
|
||||
An Image Format describes the way that the images in Textures store their data.
|
||||
|
||||
.. ocv:enum:: ogl::Texture2D::Format
|
||||
|
||||
.. ocv:emember:: NONE
|
||||
.. ocv:emember:: DEPTH_COMPONENT
|
||||
.. ocv:emember:: RGB
|
||||
.. ocv:emember:: RGBA
|
||||
|
||||
|
||||
|
||||
ogl::Texture2D::Texture2D
|
||||
-------------------------
|
||||
The constructors.
|
||||
|
||||
.. ocv:function:: ogl::Texture2D::Texture2D()
|
||||
|
||||
.. ocv:function:: ogl::Texture2D::Texture2D(int arows, int acols, Format aformat, unsigned int atexId, bool autoRelease = false)
|
||||
|
||||
.. ocv:function:: ogl::Texture2D::Texture2D(Size asize, Format aformat, unsigned int atexId, bool autoRelease = false)
|
||||
|
||||
.. ocv:function:: ogl::Texture2D::Texture2D(int arows, int acols, Format aformat, bool autoRelease = false)
|
||||
|
||||
.. ocv:function:: ogl::Texture2D::Texture2D(Size asize, Format aformat, bool autoRelease = false)
|
||||
|
||||
.. ocv:function:: ogl::Texture2D::Texture2D(InputArray arr, bool autoRelease = false)
|
||||
|
||||
:param arows: Number of rows.
|
||||
|
||||
:param acols: Number of columns.
|
||||
|
||||
:param asize: 2D array size.
|
||||
|
||||
:param aformat: Image format. See :ocv:enum:`ogl::Texture2D::Format` .
|
||||
|
||||
:param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` or :ocv:class:`ogl::Buffer` ).
|
||||
|
||||
:param autoRelease: Auto release mode (if true, release will be called in object's destructor).
|
||||
|
||||
Creates empty ``ogl::Texture2D`` object, allocates memory for ``ogl::Texture2D`` object or copies from host/device memory.
|
||||
|
||||
|
||||
|
||||
ogl::Texture2D::create
|
||||
----------------------
|
||||
Allocates memory for ``ogl::Texture2D`` object.
|
||||
|
||||
.. ocv:function:: void ogl::Texture2D::create(int arows, int acols, Format aformat, bool autoRelease = false)
|
||||
|
||||
.. ocv:function:: void ogl::Texture2D::create(Size asize, Format aformat, bool autoRelease = false)
|
||||
|
||||
:param arows: Number of rows.
|
||||
|
||||
:param acols: Number of columns.
|
||||
|
||||
:param asize: 2D array size.
|
||||
|
||||
:param aformat: Image format. See :ocv:enum:`ogl::Texture2D::Format` .
|
||||
|
||||
:param autoRelease: Auto release mode (if true, release will be called in object's destructor).
|
||||
|
||||
|
||||
|
||||
ogl::Texture2D::release
|
||||
-----------------------
|
||||
Decrements the reference counter and destroys the texture object if needed.
|
||||
|
||||
.. ocv:function:: void ogl::Texture2D::release()
|
||||
|
||||
The function will call `setAutoRelease(true)` .
|
||||
|
||||
|
||||
|
||||
ogl::Texture2D::setAutoRelease
|
||||
------------------------------
|
||||
Sets auto release mode.
|
||||
|
||||
.. ocv:function:: void ogl::Texture2D::setAutoRelease(bool flag)
|
||||
|
||||
:param flag: Auto release mode (if true, release will be called in object's destructor).
|
||||
|
||||
The lifetime of the OpenGL object is tied to the lifetime of the context.
|
||||
If OpenGL context was bound to a window it could be released at any time (user can close a window).
|
||||
If object's destructor is called after destruction of the context it will cause an error.
|
||||
Thus ``ogl::Texture2D`` doesn't destroy OpenGL object in destructor by default (all OpenGL resources will be released with OpenGL context).
|
||||
This function can force ``ogl::Texture2D`` destructor to destroy OpenGL object.
|
||||
|
||||
|
||||
|
||||
ogl::Texture2D::copyFrom
|
||||
------------------------
|
||||
Copies from host/device memory to OpenGL texture.
|
||||
|
||||
.. ocv:function:: void ogl::Texture2D::copyFrom(InputArray arr, bool autoRelease = false)
|
||||
|
||||
:param arr: Input array (host or device memory, it can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` or :ocv:class:`ogl::Buffer` ).
|
||||
|
||||
:param autoRelease: Auto release mode (if true, release will be called in object's destructor).
|
||||
|
||||
|
||||
|
||||
ogl::Texture2D::copyTo
|
||||
----------------------
|
||||
Copies from OpenGL texture to host/device memory or another OpenGL texture object.
|
||||
|
||||
.. ocv:function:: void ogl::Texture2D::copyTo(OutputArray arr, int ddepth = CV_32F, bool autoRelease = false) const
|
||||
|
||||
:param arr: Destination array (host or device memory, can be :ocv:class:`Mat` , :ocv:class:`cuda::GpuMat` , :ocv:class:`ogl::Buffer` or ``ogl::Texture2D`` ).
|
||||
|
||||
:param ddepth: Destination depth.
|
||||
|
||||
:param autoRelease: Auto release mode for destination buffer (if ``arr`` is OpenGL buffer or texture).
|
||||
|
||||
|
||||
|
||||
ogl::Texture2D::bind
|
||||
--------------------
|
||||
Binds texture to current active texture unit for ``GL_TEXTURE_2D`` target.
|
||||
|
||||
.. ocv:function:: void ogl::Texture2D::bind() const
|
||||
|
||||
|
||||
|
||||
ogl::Arrays
|
||||
-----------
|
||||
Wrapper for OpenGL Client-Side Vertex arrays.
|
||||
|
||||
.. ocv:class:: ogl::Arrays
|
||||
|
||||
``ogl::Arrays`` stores vertex data in :ocv:class:`ogl::Buffer` objects.
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::setVertexArray
|
||||
---------------------------
|
||||
Sets an array of vertex coordinates.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::setVertexArray(InputArray vertex)
|
||||
|
||||
:param vertex: array with vertex coordinates, can be both host and device memory.
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::resetVertexArray
|
||||
-----------------------------
|
||||
Resets vertex coordinates.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::resetVertexArray()
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::setColorArray
|
||||
--------------------------
|
||||
Sets an array of vertex colors.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::setColorArray(InputArray color)
|
||||
|
||||
:param color: array with vertex colors, can be both host and device memory.
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::resetColorArray
|
||||
----------------------------
|
||||
Resets vertex colors.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::resetColorArray()
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::setNormalArray
|
||||
---------------------------
|
||||
Sets an array of vertex normals.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::setNormalArray(InputArray normal)
|
||||
|
||||
:param normal: array with vertex normals, can be both host and device memory.
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::resetNormalArray
|
||||
-----------------------------
|
||||
Resets vertex normals.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::resetNormalArray()
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::setTexCoordArray
|
||||
-----------------------------
|
||||
Sets an array of vertex texture coordinates.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::setTexCoordArray(InputArray texCoord)
|
||||
|
||||
:param texCoord: array with vertex texture coordinates, can be both host and device memory.
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::resetTexCoordArray
|
||||
-------------------------------
|
||||
Resets vertex texture coordinates.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::resetTexCoordArray()
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::release
|
||||
--------------------
|
||||
Releases all inner buffers.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::release()
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::setAutoRelease
|
||||
---------------------------
|
||||
Sets auto release mode all inner buffers.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::setAutoRelease(bool flag)
|
||||
|
||||
:param flag: Auto release mode.
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::bind
|
||||
-----------------
|
||||
Binds all vertex arrays.
|
||||
|
||||
.. ocv:function:: void ogl::Arrays::bind() const
|
||||
|
||||
|
||||
|
||||
ogl::Arrays::size
|
||||
-----------------
|
||||
Returns the vertex count.
|
||||
|
||||
.. ocv:function:: int ogl::Arrays::size() const
|
||||
|
||||
|
||||
|
||||
ogl::render
|
||||
-----------
|
||||
Render OpenGL texture or primitives.
|
||||
|
||||
.. ocv:function:: void ogl::render(const Texture2D& tex, Rect_<double> wndRect = Rect_<double>(0.0, 0.0, 1.0, 1.0), Rect_<double> texRect = Rect_<double>(0.0, 0.0, 1.0, 1.0))
|
||||
|
||||
.. ocv:function:: void ogl::render(const Arrays& arr, int mode = POINTS, Scalar color = Scalar::all(255))
|
||||
|
||||
.. ocv:function:: void ogl::render(const Arrays& arr, InputArray indices, int mode = POINTS, Scalar color = Scalar::all(255))
|
||||
|
||||
:param tex: Texture to draw.
|
||||
|
||||
:param wndRect: Region of window, where to draw a texture (normalized coordinates).
|
||||
|
||||
:param texRect: Region of texture to draw (normalized coordinates).
|
||||
|
||||
:param arr: Array of privitives vertices.
|
||||
|
||||
:param indices: Array of vertices indices (host or device memory).
|
||||
|
||||
:param mode: Render mode. Available options:
|
||||
|
||||
* **POINTS**
|
||||
* **LINES**
|
||||
* **LINE_LOOP**
|
||||
* **LINE_STRIP**
|
||||
* **TRIANGLES**
|
||||
* **TRIANGLE_STRIP**
|
||||
* **TRIANGLE_FAN**
|
||||
* **QUADS**
|
||||
* **QUAD_STRIP**
|
||||
* **POLYGON**
|
||||
|
||||
:param color: Color for all vertices. Will be used if ``arr`` doesn't contain color array.
|
||||
|
||||
|
||||
|
||||
cuda::setGlDevice
|
||||
-----------------
|
||||
Sets a CUDA device and initializes it for the current thread with OpenGL interoperability.
|
||||
|
||||
.. ocv:function:: void cuda::setGlDevice( int device = 0 )
|
||||
|
||||
:param device: System index of a CUDA device starting with 0.
|
||||
|
||||
This function should be explicitly called after OpenGL context creation and before any CUDA calls.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,341 +0,0 @@
|
||||
Optimization Algorithms
|
||||
=======================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
The algorithms in this section minimize or maximize function value within specified constraints or without any constraints.
|
||||
|
||||
solveLP
|
||||
--------------------
|
||||
Solve given (non-integer) linear programming problem using the Simplex Algorithm (Simplex Method).
|
||||
What we mean here by "linear programming problem" (or LP problem, for short) can be
|
||||
formulated as:
|
||||
|
||||
.. math::
|
||||
\mbox{Maximize } c\cdot x\\
|
||||
\mbox{Subject to:}\\
|
||||
Ax\leq b\\
|
||||
x\geq 0
|
||||
|
||||
Where :math:`c` is fixed *1*-by-*n* row-vector, :math:`A` is fixed *m*-by-*n* matrix, :math:`b` is fixed *m*-by-*1* column vector and
|
||||
:math:`x` is an arbitrary *n*-by-*1* column vector, which satisfies the constraints.
|
||||
|
||||
Simplex algorithm is one of many algorithms that are designed to handle this sort of problems efficiently. Although it is not optimal in theoretical
|
||||
sense (there exist algorithms that can solve any problem written as above in polynomial type, while simplex method degenerates to exponential time
|
||||
for some special cases), it is well-studied, easy to implement and is shown to work well for real-life purposes.
|
||||
|
||||
The particular implementation is taken almost verbatim from **Introduction to Algorithms, third edition**
|
||||
by T. H. Cormen, C. E. Leiserson, R. L. Rivest and Clifford Stein. In particular, the Bland's rule
|
||||
(`http://en.wikipedia.org/wiki/Bland%27s\_rule <http://en.wikipedia.org/wiki/Bland%27s_rule>`_) is used to prevent cycling.
|
||||
|
||||
.. ocv:function:: int solveLP(const Mat& Func, const Mat& Constr, Mat& z)
|
||||
|
||||
:param Func: This row-vector corresponds to :math:`c` in the LP problem formulation (see above). It should contain 32- or 64-bit floating point numbers. As a convenience, column-vector may be also submitted, in the latter case it is understood to correspond to :math:`c^T`.
|
||||
|
||||
:param Constr: *m*-by-*n\+1* matrix, whose rightmost column corresponds to :math:`b` in formulation above and the remaining to :math:`A`. It should containt 32- or 64-bit floating point numbers.
|
||||
|
||||
:param z: The solution will be returned here as a column-vector - it corresponds to :math:`c` in the formulation above. It will contain 64-bit floating point numbers.
|
||||
|
||||
:return: One of the return codes:
|
||||
|
||||
::
|
||||
|
||||
//!the return codes for solveLP() function
|
||||
enum
|
||||
{
|
||||
SOLVELP_UNBOUNDED = -2, //problem is unbounded (target function can achieve arbitrary high values)
|
||||
SOLVELP_UNFEASIBLE = -1, //problem is unfeasible (there are no points that satisfy all the constraints imposed)
|
||||
SOLVELP_SINGLE = 0, //there is only one maximum for target function
|
||||
SOLVELP_MULTI = 1 //there are multiple maxima for target function - the arbitrary one is returned
|
||||
};
|
||||
|
||||
DownhillSolver
|
||||
---------------------------------
|
||||
|
||||
.. ocv:class:: DownhillSolver
|
||||
|
||||
This class is used to perform the non-linear non-constrained *minimization* of a function, defined on an *n*-dimensional Euclidean space,
|
||||
using the **Nelder-Mead method**, also known as **downhill simplex method**. The basic idea about the method can be obtained from
|
||||
(`http://en.wikipedia.org/wiki/Nelder-Mead\_method <http://en.wikipedia.org/wiki/Nelder-Mead_method>`_). It should be noted, that
|
||||
this method, although deterministic, is rather a heuristic and therefore may converge to a local minima, not necessary a global one.
|
||||
It is iterative optimization technique, which at each step uses an information about the values of a function evaluated only at
|
||||
*n+1* points, arranged as a *simplex* in *n*-dimensional space (hence the second name of the method). At each step new point is
|
||||
chosen to evaluate function at, obtained value is compared with previous ones and based on this information simplex changes it's shape
|
||||
, slowly moving to the local minimum. Thus this method is using *only* function values to make decision, on contrary to, say, Nonlinear
|
||||
Conjugate Gradient method (which is also implemented in ``optim``).
|
||||
|
||||
Algorithm stops when the number of function evaluations done exceeds ``termcrit.maxCount``, when the function values at the
|
||||
vertices of simplex are within ``termcrit.epsilon`` range or simplex becomes so small that it
|
||||
can enclosed in a box with ``termcrit.epsilon`` sides, whatever comes first, for some defined by user
|
||||
positive integer ``termcrit.maxCount`` and positive non-integer ``termcrit.epsilon``.
|
||||
|
||||
::
|
||||
|
||||
class CV_EXPORTS Solver : public Algorithm
|
||||
{
|
||||
public:
|
||||
class CV_EXPORTS Function
|
||||
{
|
||||
public:
|
||||
virtual ~Function() {}
|
||||
virtual double calc(const double* x) const = 0;
|
||||
virtual void getGradient(const double* /*x*/,double* /*grad*/) {}
|
||||
};
|
||||
|
||||
virtual Ptr<Function> getFunction() const = 0;
|
||||
virtual void setFunction(const Ptr<Function>& f) = 0;
|
||||
|
||||
virtual TermCriteria getTermCriteria() const = 0;
|
||||
virtual void setTermCriteria(const TermCriteria& termcrit) = 0;
|
||||
|
||||
// x contain the initial point before the call and the minima position (if algorithm converged) after. x is assumed to be (something that
|
||||
// after getMat() will return) row-vector or column-vector. *It's size and should
|
||||
// be consisted with previous dimensionality data given, if any (otherwise, it determines dimensionality)*
|
||||
virtual double minimize(InputOutputArray x) = 0;
|
||||
};
|
||||
|
||||
class CV_EXPORTS DownhillSolver : public Solver
|
||||
{
|
||||
public:
|
||||
//! returns row-vector, even if the column-vector was given
|
||||
virtual void getInitStep(OutputArray step) const=0;
|
||||
//!This should be called at least once before the first call to minimize() and step is assumed to be (something that
|
||||
//! after getMat() will return) row-vector or column-vector. *It's dimensionality determines the dimensionality of a problem.*
|
||||
virtual void setInitStep(InputArray step)=0;
|
||||
};
|
||||
|
||||
It should be noted, that ``DownhillSolver`` is a derivative of the abstract interface ``Solver``, which in
|
||||
turn is derived from the ``Algorithm`` interface and is used to encapsulate the functionality, common to all non-linear optimization
|
||||
algorithms in the ``optim`` module.
|
||||
|
||||
DownhillSolver::getFunction
|
||||
--------------------------------------------
|
||||
|
||||
Getter for the optimized function. The optimized function is represented by ``Solver::Function`` interface, which requires
|
||||
derivatives to implement the sole method ``calc(double*)`` to evaluate the function.
|
||||
|
||||
.. ocv:function:: Ptr<Solver::Function> DownhillSolver::getFunction()
|
||||
|
||||
:return: Smart-pointer to an object that implements ``Solver::Function`` interface - it represents the function that is being optimized. It can be empty, if no function was given so far.
|
||||
|
||||
DownhillSolver::setFunction
|
||||
-----------------------------------------------
|
||||
|
||||
Setter for the optimized function. *It should be called at least once before the call to* ``DownhillSolver::minimize()``, as
|
||||
default value is not usable.
|
||||
|
||||
.. ocv:function:: void DownhillSolver::setFunction(const Ptr<Solver::Function>& f)
|
||||
|
||||
:param f: The new function to optimize.
|
||||
|
||||
DownhillSolver::getTermCriteria
|
||||
----------------------------------------------------
|
||||
|
||||
Getter for the previously set terminal criteria for this algorithm.
|
||||
|
||||
.. ocv:function:: TermCriteria DownhillSolver::getTermCriteria()
|
||||
|
||||
:return: Deep copy of the terminal criteria used at the moment.
|
||||
|
||||
DownhillSolver::setTermCriteria
|
||||
------------------------------------------
|
||||
|
||||
Set terminal criteria for downhill simplex method. Two things should be noted. First, this method *is not necessary* to be called
|
||||
before the first call to ``DownhillSolver::minimize()``, as the default value is sensible. Second, the method will raise an error
|
||||
if ``termcrit.type!=(TermCriteria::MAX_ITER+TermCriteria::EPS)``, ``termcrit.epsilon<=0`` or ``termcrit.maxCount<=0``. That is,
|
||||
both ``epsilon`` and ``maxCount`` should be set to positive values (non-integer and integer respectively) and they represent
|
||||
tolerance and maximal number of function evaluations that is allowed.
|
||||
|
||||
Algorithm stops when the number of function evaluations done exceeds ``termcrit.maxCount``, when the function values at the
|
||||
vertices of simplex are within ``termcrit.epsilon`` range or simplex becomes so small that it
|
||||
can enclosed in a box with ``termcrit.epsilon`` sides, whatever comes first.
|
||||
|
||||
.. ocv:function:: void DownhillSolver::setTermCriteria(const TermCriteria& termcrit)
|
||||
|
||||
:param termcrit: Terminal criteria to be used, represented as ``TermCriteria`` structure (defined elsewhere in openCV). Mind you, that it should meet ``(termcrit.type==(TermCriteria::MAX_ITER+TermCriteria::EPS) && termcrit.epsilon>0 && termcrit.maxCount>0)``, otherwise the error will be raised.
|
||||
|
||||
DownhillSolver::getInitStep
|
||||
-----------------------------------
|
||||
|
||||
Returns the initial step that will be used in downhill simplex algorithm. See the description
|
||||
of corresponding setter (follows next) for the meaning of this parameter.
|
||||
|
||||
.. ocv:function:: void getInitStep(OutputArray step)
|
||||
|
||||
:param step: Initial step that will be used in algorithm. Note, that although corresponding setter accepts column-vectors as well as row-vectors, this method will return a row-vector.
|
||||
|
||||
DownhillSolver::setInitStep
|
||||
----------------------------------
|
||||
|
||||
Sets the initial step that will be used in downhill simplex algorithm. Step, together with initial point (givin in ``DownhillSolver::minimize``)
|
||||
are two *n*-dimensional vectors that are used to determine the shape of initial simplex. Roughly said, initial point determines the position
|
||||
of a simplex (it will become simplex's centroid), while step determines the spread (size in each dimension) of a simplex. To be more precise,
|
||||
if :math:`s,x_0\in\mathbb{R}^n` are the initial step and initial point respectively, the vertices of a simplex will be: :math:`v_0:=x_0-\frac{1}{2}
|
||||
s` and :math:`v_i:=x_0+s_i` for :math:`i=1,2,\dots,n` where :math:`s_i` denotes projections of the initial step of *n*-th coordinate (the result
|
||||
of projection is treated to be vector given by :math:`s_i:=e_i\cdot\left<e_i\cdot s\right>`, where :math:`e_i` form canonical basis)
|
||||
|
||||
.. ocv:function:: void setInitStep(InputArray step)
|
||||
|
||||
:param step: Initial step that will be used in algorithm. Roughly said, it determines the spread (size in each dimension) of an initial simplex.
|
||||
|
||||
DownhillSolver::minimize
|
||||
-----------------------------------
|
||||
|
||||
The main method of the ``DownhillSolver``. It actually runs the algorithm and performs the minimization. The sole input parameter determines the
|
||||
centroid of the starting simplex (roughly, it tells where to start), all the others (terminal criteria, initial step, function to be minimized)
|
||||
are supposed to be set via the setters before the call to this method or the default values (not always sensible) will be used.
|
||||
|
||||
.. ocv:function:: double DownhillSolver::minimize(InputOutputArray x)
|
||||
|
||||
:param x: The initial point, that will become a centroid of an initial simplex. After the algorithm will terminate, it will be setted to the point where the algorithm stops, the point of possible minimum.
|
||||
|
||||
:return: The value of a function at the point found.
|
||||
|
||||
createDownhillSolver
|
||||
------------------------------------
|
||||
|
||||
This function returns the reference to the ready-to-use ``DownhillSolver`` object. All the parameters are optional, so this procedure can be called
|
||||
even without parameters at all. In this case, the default values will be used. As default value for terminal criteria are the only sensible ones,
|
||||
``DownhillSolver::setFunction()`` and ``DownhillSolver::setInitStep()`` should be called upon the obtained object, if the respective parameters
|
||||
were not given to ``createDownhillSolver()``. Otherwise, the two ways (give parameters to ``createDownhillSolver()`` or miss them out and call the
|
||||
``DownhillSolver::setFunction()`` and ``DownhillSolver::setInitStep()``) are absolutely equivalent (and will drop the same errors in the same way,
|
||||
should invalid input be detected).
|
||||
|
||||
.. ocv:function:: Ptr<DownhillSolver> createDownhillSolver(const Ptr<Solver::Function>& f,InputArray initStep, TermCriteria termcrit)
|
||||
|
||||
:param f: Pointer to the function that will be minimized, similarly to the one you submit via ``DownhillSolver::setFunction``.
|
||||
:param step: Initial step, that will be used to construct the initial simplex, similarly to the one you submit via ``DownhillSolver::setInitStep``.
|
||||
:param termcrit: Terminal criteria to the algorithm, similarly to the one you submit via ``DownhillSolver::setTermCriteria``.
|
||||
|
||||
|
||||
ConjGradSolver
|
||||
---------------------------------
|
||||
|
||||
.. ocv:class:: ConjGradSolver
|
||||
|
||||
This class is used to perform the non-linear non-constrained *minimization* of a function with *known gradient*
|
||||
, defined on an *n*-dimensional Euclidean space,
|
||||
using the **Nonlinear Conjugate Gradient method**. The implementation was done based on the beautifully clear explanatory article `An Introduction to the Conjugate Gradient Method Without the Agonizing Pain <http://www.cs.cmu.edu/~quake-papers/painless-conjugate-gradient.pdf>`_
|
||||
by Jonathan Richard Shewchuk. The method can be seen as an adaptation of a standard Conjugate Gradient method (see, for example
|
||||
`http://en.wikipedia.org/wiki/Conjugate_gradient_method <http://en.wikipedia.org/wiki/Conjugate_gradient_method>`_) for numerically solving the
|
||||
systems of linear equations.
|
||||
|
||||
It should be noted, that
|
||||
this method, although deterministic, is rather a heuristic method and therefore may converge to a local minima, not necessary a global one. What
|
||||
is even more disastrous, most of its behaviour is ruled by gradient, therefore it essentially cannot distinguish between local minima and maxima.
|
||||
Therefore, if it starts sufficiently near to the local maximum, it may converge to it. Another obvious restriction is that it should be possible
|
||||
to compute the gradient of a function at any point, thus it is preferable to have analytic expression for gradient and computational burden
|
||||
should be born by the user.
|
||||
|
||||
The latter responsibility is accompilished via the ``getGradient(const double* x,double* grad)`` method of a
|
||||
``Solver::Function`` interface (which represents function that is being optimized). This method takes point a point in *n*-dimensional space
|
||||
(first argument represents the array of coordinates of that point) and comput its gradient (it should be stored in the second argument as an array).
|
||||
|
||||
::
|
||||
|
||||
class CV_EXPORTS Solver : public Algorithm
|
||||
{
|
||||
public:
|
||||
class CV_EXPORTS Function
|
||||
{
|
||||
public:
|
||||
virtual ~Function() {}
|
||||
virtual double calc(const double* x) const = 0;
|
||||
virtual void getGradient(const double* /*x*/,double* /*grad*/) {}
|
||||
};
|
||||
|
||||
virtual Ptr<Function> getFunction() const = 0;
|
||||
virtual void setFunction(const Ptr<Function>& f) = 0;
|
||||
|
||||
virtual TermCriteria getTermCriteria() const = 0;
|
||||
virtual void setTermCriteria(const TermCriteria& termcrit) = 0;
|
||||
|
||||
// x contain the initial point before the call and the minima position (if algorithm converged) after. x is assumed to be (something that
|
||||
// after getMat() will return) row-vector or column-vector. *It's size and should
|
||||
// be consisted with previous dimensionality data given, if any (otherwise, it determines dimensionality)*
|
||||
virtual double minimize(InputOutputArray x) = 0;
|
||||
};
|
||||
|
||||
class CV_EXPORTS ConjGradSolver : public Solver{
|
||||
};
|
||||
|
||||
Note, that class ``ConjGradSolver`` thus does not add any new methods to the basic ``Solver`` interface.
|
||||
|
||||
ConjGradSolver::getFunction
|
||||
--------------------------------------------
|
||||
|
||||
Getter for the optimized function. The optimized function is represented by ``Solver::Function`` interface, which requires
|
||||
derivatives to implement the method ``calc(double*)`` to evaluate the function. It should be emphasized once more, that since Nonlinear
|
||||
Conjugate Gradient method requires gradient to be computable in addition to the function values,
|
||||
``getGradient(const double* x,double* grad)`` method of a ``Solver::Function`` interface should be also implemented meaningfully.
|
||||
|
||||
.. ocv:function:: Ptr<Solver::Function> ConjGradSolver::getFunction()
|
||||
|
||||
:return: Smart-pointer to an object that implements ``Solver::Function`` interface - it represents the function that is being optimized. It can be empty, if no function was given so far.
|
||||
|
||||
ConjGradSolver::setFunction
|
||||
-----------------------------------------------
|
||||
|
||||
Setter for the optimized function. *It should be called at least once before the call to* ``ConjGradSolver::minimize()``, as
|
||||
default value is not usable.
|
||||
|
||||
.. ocv:function:: void ConjGradSolver::setFunction(const Ptr<Solver::Function>& f)
|
||||
|
||||
:param f: The new function to optimize.
|
||||
|
||||
ConjGradSolver::getTermCriteria
|
||||
----------------------------------------------------
|
||||
|
||||
Getter for the previously set terminal criteria for this algorithm.
|
||||
|
||||
.. ocv:function:: TermCriteria ConjGradSolver::getTermCriteria()
|
||||
|
||||
:return: Deep copy of the terminal criteria used at the moment.
|
||||
|
||||
ConjGradSolver::setTermCriteria
|
||||
------------------------------------------
|
||||
|
||||
Set terminal criteria for downhill simplex method. Two things should be noted. First, this method *is not necessary* to be called
|
||||
before the first call to ``ConjGradSolver::minimize()``, as the default value is sensible. Second, the method will raise an error
|
||||
if ``termcrit.type!=(TermCriteria::MAX_ITER+TermCriteria::EPS)`` and ``termcrit.type!=TermCriteria::MAX_ITER``. This means that termination criteria
|
||||
has to restrict maximum number of iterations to be done and may optionally allow algorithm to stop earlier if certain tolerance
|
||||
is achieved (what we mean by "tolerance is achieved" will be clarified below). If ``termcrit`` restricts both tolerance and maximum iteration
|
||||
number, both ``termcrit.epsilon`` and ``termcrit.maxCount`` should be positive. In case, if ``termcrit.type==TermCriteria::MAX_ITER``,
|
||||
only member ``termcrit.maxCount`` is required to be positive and in this case algorithm will just work for required number of iterations.
|
||||
|
||||
In current implementation, "tolerance is achieved" means that we have arrived at the point where the :math:`L_2`-norm of the gradient is less
|
||||
than the tolerance value.
|
||||
|
||||
.. ocv:function:: void ConjGradSolver::setTermCriteria(const TermCriteria& termcrit)
|
||||
|
||||
:param termcrit: Terminal criteria to be used, represented as ``TermCriteria`` structure (defined elsewhere in openCV). Mind you, that it should meet ``termcrit.type==(TermCriteria::MAX_ITER+TermCriteria::EPS) && termcrit.epsilon>0 && termcrit.maxCount>0`` or ``termcrit.type==TermCriteria::MAX_ITER) && termcrit.maxCount>0``, otherwise the error will be raised.
|
||||
|
||||
ConjGradSolver::minimize
|
||||
-----------------------------------
|
||||
|
||||
The main method of the ``ConjGradSolver``. It actually runs the algorithm and performs the minimization. The sole input parameter determines the
|
||||
centroid of the starting simplex (roughly, it tells where to start), all the others (terminal criteria and function to be minimized)
|
||||
are supposed to be set via the setters before the call to this method or the default values (not always sensible) will be used. Sometimes it may
|
||||
throw an error, if these default values cannot be used (say, you forgot to set the function to minimize and default value, that is, empty function,
|
||||
cannot be used).
|
||||
|
||||
.. ocv:function:: double ConjGradSolver::minimize(InputOutputArray x)
|
||||
|
||||
:param x: The initial point. It is hard to overemphasize how important the choise of initial point is when you are using the heuristic algorithm like this one. Badly chosen initial point can make algorithm converge to (local) maximum instead of minimum, do not converge at all, converge to local minimum instead of global one.
|
||||
|
||||
:return: The value of a function at the point found.
|
||||
|
||||
createConjGradSolver
|
||||
------------------------------------
|
||||
|
||||
This function returns the reference to the ready-to-use ``ConjGradSolver`` object. All the parameters are optional, so this procedure can be called
|
||||
even without parameters at all. In this case, the default values will be used. As default value for terminal criteria are the only sensible ones,
|
||||
``ConjGradSolver::setFunction()`` should be called upon the obtained object, if the function
|
||||
was not given to ``createConjGradSolver()``. Otherwise, the two ways (submit it to ``createConjGradSolver()`` or miss it out and call the
|
||||
``ConjGradSolver::setFunction()``) are absolutely equivalent (and will drop the same errors in the same way,
|
||||
should invalid input be detected).
|
||||
|
||||
.. ocv:function:: Ptr<ConjGradSolver> createConjGradSolver(const Ptr<Solver::Function>& f, TermCriteria termcrit)
|
||||
|
||||
:param f: Pointer to the function that will be minimized, similarly to the one you submit via ``ConjGradSolver::setFunction``.
|
||||
:param termcrit: Terminal criteria to the algorithm, similarly to the one you submit via ``ConjGradSolver::setTermCriteria``.
|
||||
@@ -1,493 +0,0 @@
|
||||
Utility and System Functions and Macros
|
||||
=======================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
alignPtr
|
||||
------------
|
||||
Aligns a pointer to the specified number of bytes.
|
||||
|
||||
.. ocv:function:: template<typename _Tp> _Tp* alignPtr(_Tp* ptr, int n=sizeof(_Tp))
|
||||
|
||||
:param ptr: Aligned pointer.
|
||||
|
||||
:param n: Alignment size that must be a power of two.
|
||||
|
||||
The function returns the aligned pointer of the same type as the input pointer:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{(\_Tp*)(((size\_t)ptr + n-1) \& -n)}
|
||||
|
||||
|
||||
|
||||
alignSize
|
||||
-------------
|
||||
Aligns a buffer size to the specified number of bytes.
|
||||
|
||||
.. ocv:function:: size_t alignSize(size_t sz, int n)
|
||||
|
||||
:param sz: Buffer size to align.
|
||||
|
||||
:param n: Alignment size that must be a power of two.
|
||||
|
||||
The function returns the minimum number that is greater or equal to ``sz`` and is divisible by ``n`` :
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{(sz + n-1) \& -n}
|
||||
|
||||
|
||||
|
||||
allocate
|
||||
------------
|
||||
Allocates an array of elements.
|
||||
|
||||
.. ocv:function:: template<typename _Tp> _Tp* allocate(size_t n)
|
||||
|
||||
:param n: Number of elements to allocate.
|
||||
|
||||
The generic function ``allocate`` allocates a buffer for the specified number of elements. For each element, the default constructor is called.
|
||||
|
||||
|
||||
|
||||
deallocate
|
||||
--------------
|
||||
Deallocates an array of elements.
|
||||
|
||||
.. ocv:function:: template<typename _Tp> void deallocate(_Tp* ptr, size_t n)
|
||||
|
||||
:param ptr: Pointer to the deallocated buffer.
|
||||
|
||||
:param n: Number of elements in the buffer.
|
||||
|
||||
The generic function ``deallocate`` deallocates the buffer allocated with
|
||||
:ocv:func:`allocate` . The number of elements must match the number passed to
|
||||
:ocv:func:`allocate` .
|
||||
|
||||
|
||||
|
||||
fastAtan2
|
||||
---------
|
||||
Calculates the angle of a 2D vector in degrees.
|
||||
|
||||
.. ocv:function:: float fastAtan2(float y, float x)
|
||||
|
||||
.. ocv:pyfunction:: cv2.fastAtan2(y, x) -> retval
|
||||
|
||||
.. ocv:cfunction:: float cvFastArctan(float y, float x)
|
||||
|
||||
:param x: x-coordinate of the vector.
|
||||
|
||||
:param y: y-coordinate of the vector.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
cubeRoot
|
||||
--------
|
||||
Computes the cube root of an argument.
|
||||
|
||||
.. ocv:function:: float cubeRoot(float val)
|
||||
|
||||
.. ocv:pyfunction:: cv2.cubeRoot(val) -> retval
|
||||
|
||||
.. ocv:cfunction:: float cvCbrt( float value )
|
||||
|
||||
:param val: A function argument.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Ceil
|
||||
-----
|
||||
Rounds floating-point number to the nearest integer not smaller than the original.
|
||||
|
||||
.. ocv:cfunction:: int cvCeil(double value)
|
||||
|
||||
:param value: floating-point number. If the value is outside of ``INT_MIN`` ... ``INT_MAX`` range, the result is not defined.
|
||||
|
||||
The function computes an integer ``i`` such that:
|
||||
|
||||
.. math::
|
||||
|
||||
i-1 < \texttt{value} \le i
|
||||
|
||||
|
||||
Floor
|
||||
-----
|
||||
Rounds floating-point number to the nearest integer not larger than the original.
|
||||
|
||||
.. ocv:cfunction:: int cvFloor(double value)
|
||||
|
||||
:param value: floating-point number. If the value is outside of ``INT_MIN`` ... ``INT_MAX`` range, the result is not defined.
|
||||
|
||||
The function computes an integer ``i`` such that:
|
||||
|
||||
.. math::
|
||||
|
||||
i \le \texttt{value} < i+1
|
||||
|
||||
|
||||
Round
|
||||
-----
|
||||
Rounds floating-point number to the nearest integer
|
||||
|
||||
.. ocv:cfunction:: int cvRound(double value)
|
||||
|
||||
:param value: floating-point number. If the value is outside of ``INT_MIN`` ... ``INT_MAX`` range, the result is not defined.
|
||||
|
||||
|
||||
IsInf
|
||||
-----
|
||||
Determines if the argument is Infinity.
|
||||
|
||||
.. ocv:cfunction:: int cvIsInf(double value)
|
||||
|
||||
:param value: The input floating-point value
|
||||
|
||||
The function returns 1 if the argument is a plus or minus infinity (as defined by IEEE754 standard) and 0 otherwise.
|
||||
|
||||
IsNaN
|
||||
-----
|
||||
Determines if the argument is Not A Number.
|
||||
|
||||
.. ocv:cfunction:: int cvIsNaN(double value)
|
||||
|
||||
:param value: The input floating-point value
|
||||
|
||||
The function returns 1 if the argument is Not A Number (as defined by IEEE754 standard), 0 otherwise.
|
||||
|
||||
|
||||
CV_Assert
|
||||
---------
|
||||
Checks a condition at runtime and throws exception if it fails
|
||||
|
||||
.. ocv:function:: CV_Assert(expr)
|
||||
|
||||
:param expr: Expression for check.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
error
|
||||
-----
|
||||
Signals an error and raises an exception.
|
||||
|
||||
.. ocv:function:: void error( const Exception& exc )
|
||||
|
||||
.. ocv:cfunction:: void cvError( int status, const char* func_name, const char* err_msg, const char* file_name, int line )
|
||||
|
||||
:param exc: Exception to throw.
|
||||
|
||||
:param status: Error code. Normally, it is a negative value. The list of pre-defined error codes can be found in ``cxerror.h`` .
|
||||
|
||||
:param func_name: The function name where error occurs.
|
||||
|
||||
:param err_msg: Text of the error message.
|
||||
|
||||
:param file_name: The file name where error occurs.
|
||||
|
||||
:param line: The line number where error occurs.
|
||||
|
||||
:param args: ``printf`` -like formatted error message in parentheses.
|
||||
|
||||
The function and the helper macros ``CV_Error`` and ``CV_Error_``: ::
|
||||
|
||||
#define CV_Error( code, msg ) error(...)
|
||||
#define CV_Error_( code, args ) error(...)
|
||||
|
||||
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.
|
||||
|
||||
The macro ``CV_Error_`` can be used to construct an error message on-fly to include some dynamic information, for example: ::
|
||||
|
||||
// note the extra parentheses around the formatted text message
|
||||
CV_Error_(CV_StsOutOfRange,
|
||||
("the matrix element (
|
||||
i, j, mtx.at<float>(i,j)))
|
||||
|
||||
|
||||
Exception
|
||||
---------
|
||||
.. ocv:class:: Exception : public std::exception
|
||||
|
||||
Exception class passed to an error. ::
|
||||
|
||||
class Exception
|
||||
{
|
||||
public:
|
||||
// various constructors and the copy operation
|
||||
Exception() { code = 0; line = 0; }
|
||||
Exception(int _code, const String& _err,
|
||||
const String& _func, const String& _file, int _line);
|
||||
Exception(const Exception& exc);
|
||||
Exception& operator = (const Exception& exc);
|
||||
|
||||
// the error code
|
||||
int code;
|
||||
// the error text message
|
||||
String err;
|
||||
// function name where the error happened
|
||||
String func;
|
||||
// the source file name where the error happened
|
||||
String file;
|
||||
// the source file line where the error happened
|
||||
int line;
|
||||
};
|
||||
|
||||
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
|
||||
:ocv:func:`error` .
|
||||
|
||||
|
||||
|
||||
fastMalloc
|
||||
--------------
|
||||
Allocates an aligned memory buffer.
|
||||
|
||||
.. ocv:function:: void* fastMalloc( size_t bufSize )
|
||||
|
||||
.. ocv:cfunction:: void* cvAlloc( size_t size )
|
||||
|
||||
:param size: Allocated buffer size.
|
||||
:param bufSize: Allocated buffer size.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
fastFree
|
||||
--------
|
||||
Deallocates a memory buffer.
|
||||
|
||||
.. ocv:function:: void fastFree(void* ptr)
|
||||
.. ocv:cfunction:: void cvFree( void** pptr )
|
||||
|
||||
:param ptr: Pointer to the allocated buffer.
|
||||
|
||||
:param pptr: Double pointer to the allocated buffer
|
||||
|
||||
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.
|
||||
|
||||
|
||||
format
|
||||
------
|
||||
Returns a text string formatted using the ``printf``\ -like expression.
|
||||
|
||||
.. ocv:function:: String format( const char* fmt, ... )
|
||||
|
||||
:param fmt: ``printf`` -compatible formatting specifiers.
|
||||
|
||||
The function acts like ``sprintf`` but forms and returns an STL string. It can be used to form an error message in the
|
||||
:ocv:class:`Exception` constructor.
|
||||
|
||||
|
||||
getBuildInformation
|
||||
-------------------
|
||||
Returns full configuration time cmake output.
|
||||
|
||||
.. ocv:function:: const String& getBuildInformation()
|
||||
|
||||
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.
|
||||
|
||||
|
||||
checkHardwareSupport
|
||||
--------------------
|
||||
Returns true if the specified feature is supported by the host hardware.
|
||||
|
||||
.. ocv:function:: bool checkHardwareSupport(int feature)
|
||||
.. ocv:cfunction:: int cvCheckHardwareSupport(int feature)
|
||||
.. ocv:pyfunction:: cv2.checkHardwareSupport(feature) -> retval
|
||||
|
||||
:param feature: The feature of interest, one of:
|
||||
|
||||
* ``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
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
getNumberOfCPUs
|
||||
-----------------
|
||||
Returns the number of logical CPUs available for the process.
|
||||
|
||||
.. ocv:function:: int getNumberOfCPUs()
|
||||
|
||||
|
||||
|
||||
getNumThreads
|
||||
-----------------
|
||||
Returns the number of threads used by OpenCV for parallel regions.
|
||||
Always returns 1 if OpenCV is built without threading support.
|
||||
|
||||
.. ocv:function:: int getNumThreads()
|
||||
|
||||
The exact meaning of return value depends on the threading framework used by OpenCV library:
|
||||
|
||||
* **TBB** – The number of threads, that OpenCV will try to use for parallel regions.
|
||||
If there is any ``tbb::thread_scheduler_init`` in user code conflicting with OpenCV, then
|
||||
function returns default number of threads used by TBB library.
|
||||
* **OpenMP** – An upper bound on the number of threads that could be used to form a new team.
|
||||
* **Concurrency** – The number of threads, that OpenCV will try to use for parallel regions.
|
||||
* **GCD** – Unsupported; returns the GCD thread pool limit (512) for compatibility.
|
||||
* **C=** – The number of threads, that OpenCV will try to use for parallel regions,
|
||||
if before called ``setNumThreads`` with ``threads > 0``,
|
||||
otherwise returns the number of logical CPUs, available for the process.
|
||||
|
||||
.. seealso::
|
||||
:ocv:func:`setNumThreads`,
|
||||
:ocv:func:`getThreadNum`
|
||||
|
||||
|
||||
|
||||
getThreadNum
|
||||
----------------
|
||||
Returns the index of the currently executed thread within the current parallel region.
|
||||
Always returns 0 if called outside of parallel region.
|
||||
|
||||
.. ocv:function:: int getThreadNum()
|
||||
|
||||
The exact meaning of return value depends on the threading framework used by OpenCV library:
|
||||
|
||||
* **TBB** – Unsupported with current 4.1 TBB release. May be will be supported in future.
|
||||
* **OpenMP** – The thread number, within the current team, of the calling thread.
|
||||
* **Concurrency** – An ID for the virtual processor that the current context is executing
|
||||
on (0 for master thread and unique number for others, but not necessary 1,2,3,...).
|
||||
* **GCD** – System calling thread's ID. Never returns 0 inside parallel region.
|
||||
* **C=** – The index of the current parallel task.
|
||||
|
||||
.. seealso::
|
||||
:ocv:func:`setNumThreads`,
|
||||
:ocv:func:`getNumThreads`
|
||||
|
||||
|
||||
|
||||
getTickCount
|
||||
------------
|
||||
Returns the number of ticks.
|
||||
|
||||
.. ocv:function:: int64 getTickCount()
|
||||
|
||||
.. ocv:pyfunction:: cv2.getTickCount() -> retval
|
||||
|
||||
The function returns the number of ticks after the certain event (for example, when the machine was turned on).
|
||||
It can be used to initialize
|
||||
: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.
|
||||
|
||||
|
||||
|
||||
getTickFrequency
|
||||
----------------
|
||||
Returns the number of ticks per second.
|
||||
|
||||
.. ocv:function:: double getTickFrequency()
|
||||
|
||||
.. ocv:pyfunction:: cv2.getTickFrequency() -> retval
|
||||
|
||||
The function returns the number of ticks per second.
|
||||
That is, the following code computes the execution time in seconds: ::
|
||||
|
||||
double t = (double)getTickCount();
|
||||
// do something ...
|
||||
t = ((double)getTickCount() - t)/getTickFrequency();
|
||||
|
||||
|
||||
|
||||
getCPUTickCount
|
||||
---------------
|
||||
Returns the number of CPU ticks.
|
||||
|
||||
.. ocv:function:: int64 getCPUTickCount()
|
||||
|
||||
.. ocv:pyfunction:: cv2.getCPUTickCount() -> retval
|
||||
|
||||
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.
|
||||
|
||||
|
||||
saturate_cast
|
||||
-------------
|
||||
Template function for accurate conversion from one primitive type to another.
|
||||
|
||||
.. ocv:function:: template<...> _Tp saturate_cast(_Tp2 v)
|
||||
|
||||
:param v: Function parameter.
|
||||
|
||||
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: ::
|
||||
|
||||
uchar a = saturate_cast<uchar>(-100); // a = 0 (UCHAR_MIN)
|
||||
short b = saturate_cast<short>(33333.33333); // b = 32767 (SHRT_MAX)
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
This operation is used in the simplest or most complex image processing functions in OpenCV.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`add`,
|
||||
:ocv:func:`subtract`,
|
||||
:ocv:func:`multiply`,
|
||||
:ocv:func:`divide`,
|
||||
:ocv:func:`Mat::convertTo`
|
||||
|
||||
setNumThreads
|
||||
-----------------
|
||||
OpenCV will try to set the number of threads for the next parallel region.
|
||||
If ``threads == 0``, OpenCV will disable threading optimizations and run all it's
|
||||
functions sequentially. Passing ``threads < 0`` will reset threads number to system default.
|
||||
This function must be called outside of parallel region.
|
||||
|
||||
.. ocv:function:: void setNumThreads(int nthreads)
|
||||
|
||||
:param nthreads: Number of threads used by OpenCV.
|
||||
|
||||
OpenCV will try to run it's functions with specified threads number, but
|
||||
some behaviour differs from framework:
|
||||
|
||||
* **TBB** – User-defined parallel constructions will run with the same threads number,
|
||||
if another does not specified. If late on user creates own scheduler, OpenCV will be use it.
|
||||
* **OpenMP** – No special defined behaviour.
|
||||
* **Concurrency** – If ``threads == 1``, OpenCV will disable threading optimizations
|
||||
and run it's functions sequentially.
|
||||
* **GCD** – Supports only values <= 0.
|
||||
* **C=** – No special defined behaviour.
|
||||
|
||||
.. seealso::
|
||||
:ocv:func:`getNumThreads`,
|
||||
:ocv:func:`getThreadNum`
|
||||
|
||||
|
||||
|
||||
setUseOptimized
|
||||
---------------
|
||||
Enables or disables the optimized code.
|
||||
|
||||
.. ocv:function:: int cvUseOptimized( int on_off )
|
||||
|
||||
.. ocv:pyfunction:: cv2.setUseOptimized(onoff) -> None
|
||||
|
||||
.. ocv:cfunction:: int cvUseOptimized( int on_off )
|
||||
|
||||
:param on_off: The boolean flag specifying whether the optimized code should be used (``on_off=true``) or not (``on_off=false``).
|
||||
|
||||
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.
|
||||
|
||||
By default, the optimized code is enabled unless you disable it in CMake. The current status can be retrieved using ``useOptimized``.
|
||||
|
||||
useOptimized
|
||||
------------
|
||||
Returns the status of optimized code usage.
|
||||
|
||||
.. ocv:function:: bool useOptimized()
|
||||
|
||||
.. ocv:pyfunction:: cv2.useOptimized() -> retval
|
||||
|
||||
The function returns ``true`` if the optimized code is enabled. Otherwise, it returns ``false``.
|
||||
@@ -1,718 +0,0 @@
|
||||
XML/YAML Persistence
|
||||
====================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
XML/YAML file storages. Writing to a file storage.
|
||||
--------------------------------------------------
|
||||
|
||||
You can store and then restore various OpenCV data structures to/from XML (http://www.w3c.org/XML) or YAML
|
||||
(http://www.yaml.org) formats. Also, it is possible store and load arbitrarily complex data structures, which include OpenCV data structures, as well as primitive data types (integer and floating-point numbers and text strings) as their elements.
|
||||
|
||||
Use the following procedure to write something to XML or YAML:
|
||||
#. Create new :ocv:class:`FileStorage` and open it for writing. It can be done with a single call to :ocv:func:`FileStorage::FileStorage` constructor that takes a filename, or you can use the default constructor and then call :ocv:func:`FileStorage::open`. Format of the file (XML or YAML) is determined from the filename extension (".xml" and ".yml"/".yaml", respectively)
|
||||
#. Write all the data you want using the streaming operator ``<<``, just like in the case of STL streams.
|
||||
#. Close the file using :ocv:func:`FileStorage::release`. ``FileStorage`` destructor also closes the file.
|
||||
|
||||
Here is an example: ::
|
||||
|
||||
#include "opencv2/opencv.hpp"
|
||||
#include <time.h>
|
||||
|
||||
using namespace cv;
|
||||
|
||||
int main(int, char** argv)
|
||||
{
|
||||
FileStorage fs("test.yml", FileStorage::WRITE);
|
||||
|
||||
fs << "frameCount" << 5;
|
||||
time_t rawtime; time(&rawtime);
|
||||
fs << "calibrationDate" << asctime(localtime(&rawtime));
|
||||
Mat cameraMatrix = (Mat_<double>(3,3) << 1000, 0, 320, 0, 1000, 240, 0, 0, 1);
|
||||
Mat distCoeffs = (Mat_<double>(5,1) << 0.1, 0.01, -0.001, 0, 0);
|
||||
fs << "cameraMatrix" << cameraMatrix << "distCoeffs" << distCoeffs;
|
||||
fs << "features" << "[";
|
||||
for( int i = 0; i < 3; i++ )
|
||||
{
|
||||
int x = rand() % 640;
|
||||
int y = rand() % 480;
|
||||
uchar lbp = rand() % 256;
|
||||
|
||||
fs << "{:" << "x" << x << "y" << y << "lbp" << "[:";
|
||||
for( int j = 0; j < 8; j++ )
|
||||
fs << ((lbp >> j) & 1);
|
||||
fs << "]" << "}";
|
||||
}
|
||||
fs << "]";
|
||||
fs.release();
|
||||
return 0;
|
||||
}
|
||||
|
||||
The sample above stores to XML and integer, text string (calibration date), 2 matrices, and a custom structure "feature", which includes feature coordinates and LBP (local binary pattern) value. Here is output of the sample:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
%YAML:1.0
|
||||
frameCount: 5
|
||||
calibrationDate: "Fri Jun 17 14:09:29 2011\n"
|
||||
cameraMatrix: !!opencv-matrix
|
||||
rows: 3
|
||||
cols: 3
|
||||
dt: d
|
||||
data: [ 1000., 0., 320., 0., 1000., 240., 0., 0., 1. ]
|
||||
distCoeffs: !!opencv-matrix
|
||||
rows: 5
|
||||
cols: 1
|
||||
dt: d
|
||||
data: [ 1.0000000000000001e-01, 1.0000000000000000e-02,
|
||||
-1.0000000000000000e-03, 0., 0. ]
|
||||
features:
|
||||
- { x:167, y:49, lbp:[ 1, 0, 0, 1, 1, 0, 1, 1 ] }
|
||||
- { x:298, y:130, lbp:[ 0, 0, 0, 1, 0, 0, 1, 1 ] }
|
||||
- { x:344, y:158, lbp:[ 1, 1, 0, 0, 0, 0, 1, 0 ] }
|
||||
|
||||
As an exercise, you can replace ".yml" with ".xml" in the sample above and see, how the corresponding XML file will look like.
|
||||
|
||||
Several things can be noted by looking at the sample code and the output:
|
||||
*
|
||||
The produced YAML (and XML) consists of heterogeneous collections that can be nested. There are 2 types of collections: named collections (mappings) and unnamed collections (sequences). In mappings each element has a name and is accessed by name. This is similar to structures and ``std::map`` in C/C++ and dictionaries in Python. In sequences elements do not have names, they are accessed by indices. This is similar to arrays and ``std::vector`` in C/C++ and lists, tuples in Python. "Heterogeneous" means that elements of each single collection can have different types.
|
||||
|
||||
Top-level collection in YAML/XML is a mapping. Each matrix is stored as a mapping, and the matrix elements are stored as a sequence. Then, there is a sequence of features, where each feature is represented a mapping, and lbp value in a nested sequence.
|
||||
|
||||
*
|
||||
When you write to a mapping (a structure), you write element name followed by its value. When you write to a sequence, you simply write the elements one by one. OpenCV data structures (such as cv::Mat) are written in absolutely the same way as simple C data structures - using **``<<``** operator.
|
||||
|
||||
*
|
||||
To write a mapping, you first write the special string **"{"** to the storage, then write the elements as pairs (``fs << <element_name> << <element_value>``) and then write the closing **"}"**.
|
||||
|
||||
*
|
||||
To write a sequence, you first write the special string **"["**, then write the elements, then write the closing **"]"**.
|
||||
|
||||
*
|
||||
In YAML (but not XML), mappings and sequences can be written in a compact Python-like inline form. In the sample above matrix elements, as well as each feature, including its lbp value, is stored in such inline form. To store a mapping/sequence in a compact form, put ":" after the opening character, e.g. use **"{:"** instead of **"{"** and **"[:"** instead of **"["**. When the data is written to XML, those extra ":" are ignored.
|
||||
|
||||
.. note::
|
||||
|
||||
* A complete example using the FileStorage interface can be found at opencv_source_code/samples/cpp/filestorage.cpp
|
||||
|
||||
|
||||
Reading data from a file storage.
|
||||
---------------------------------
|
||||
|
||||
To read the previously written XML or YAML file, do the following:
|
||||
|
||||
#.
|
||||
Open the file storage using :ocv:func:`FileStorage::FileStorage` constructor or :ocv:func:`FileStorage::open` method. In the current implementation the whole file is parsed and the whole representation of file storage is built in memory as a hierarchy of file nodes (see :ocv:class:`FileNode`)
|
||||
|
||||
#.
|
||||
Read the data you are interested in. Use :ocv:func:`FileStorage::operator []`, :ocv:func:`FileNode::operator []` and/or :ocv:class:`FileNodeIterator`.
|
||||
|
||||
#.
|
||||
Close the storage using :ocv:func:`FileStorage::release`.
|
||||
|
||||
Here is how to read the file created by the code sample above: ::
|
||||
|
||||
FileStorage fs2("test.yml", FileStorage::READ);
|
||||
|
||||
// first method: use (type) operator on FileNode.
|
||||
int frameCount = (int)fs2["frameCount"];
|
||||
|
||||
String date;
|
||||
// second method: use FileNode::operator >>
|
||||
fs2["calibrationDate"] >> date;
|
||||
|
||||
Mat cameraMatrix2, distCoeffs2;
|
||||
fs2["cameraMatrix"] >> cameraMatrix2;
|
||||
fs2["distCoeffs"] >> distCoeffs2;
|
||||
|
||||
cout << "frameCount: " << frameCount << endl
|
||||
<< "calibration date: " << date << endl
|
||||
<< "camera matrix: " << cameraMatrix2 << endl
|
||||
<< "distortion coeffs: " << distCoeffs2 << endl;
|
||||
|
||||
FileNode features = fs2["features"];
|
||||
FileNodeIterator it = features.begin(), it_end = features.end();
|
||||
int idx = 0;
|
||||
std::vector<uchar> lbpval;
|
||||
|
||||
// iterate through a sequence using FileNodeIterator
|
||||
for( ; it != it_end; ++it, idx++ )
|
||||
{
|
||||
cout << "feature #" << idx << ": ";
|
||||
cout << "x=" << (int)(*it)["x"] << ", y=" << (int)(*it)["y"] << ", lbp: (";
|
||||
// you can also easily read numerical arrays using FileNode >> std::vector operator.
|
||||
(*it)["lbp"] >> lbpval;
|
||||
for( int i = 0; i < (int)lbpval.size(); i++ )
|
||||
cout << " " << (int)lbpval[i];
|
||||
cout << ")" << endl;
|
||||
}
|
||||
fs.release();
|
||||
|
||||
FileStorage
|
||||
-----------
|
||||
.. ocv:class:: FileStorage
|
||||
|
||||
XML/YAML file storage class that encapsulates all the information necessary for writing or reading data to/from a file.
|
||||
|
||||
FileStorage::FileStorage
|
||||
------------------------
|
||||
The constructors.
|
||||
|
||||
.. ocv:function:: FileStorage::FileStorage()
|
||||
|
||||
.. ocv:function:: FileStorage::FileStorage(const String& source, int flags, const String& encoding=String())
|
||||
|
||||
:param source: Name of the file to open or the text string to read the data from. Extension of the file (``.xml`` or ``.yml``/``.yaml``) determines its format (XML or YAML respectively). Also you can append ``.gz`` to work with compressed files, for example ``myHugeMatrix.xml.gz``. If both ``FileStorage::WRITE`` and ``FileStorage::MEMORY`` flags are specified, ``source`` is used just to specify the output file format (e.g. ``mydata.xml``, ``.yml`` etc.).
|
||||
|
||||
:param flags: Mode of operation. Possible values are:
|
||||
|
||||
* **FileStorage::READ** Open the file for reading.
|
||||
|
||||
* **FileStorage::WRITE** Open the file for writing.
|
||||
|
||||
* **FileStorage::APPEND** Open the file for appending.
|
||||
|
||||
* **FileStorage::MEMORY** Read data from ``source`` or write data to the internal buffer (which is returned by ``FileStorage::release``)
|
||||
|
||||
:param encoding: Encoding of the file. Note that UTF-16 XML encoding is not supported currently and you should use 8-bit encoding instead of it.
|
||||
|
||||
The full constructor opens the file. Alternatively you can use the default constructor and then call :ocv:func:`FileStorage::open`.
|
||||
|
||||
|
||||
FileStorage::open
|
||||
-----------------
|
||||
Opens a file.
|
||||
|
||||
.. ocv:function:: bool FileStorage::open(const String& filename, int flags, const String& encoding=String())
|
||||
|
||||
:param filename: Name of the file to open or the text string to read the data from.
|
||||
Extension of the file (``.xml`` or ``.yml``/``.yaml``) determines its format (XML or YAML respectively).
|
||||
Also you can append ``.gz`` to work with compressed files, for example ``myHugeMatrix.xml.gz``.
|
||||
If both ``FileStorage::WRITE`` and ``FileStorage::MEMORY`` flags are specified, ``source``
|
||||
is used just to specify the output file format (e.g. ``mydata.xml``, ``.yml`` etc.).
|
||||
|
||||
:param flags: Mode of operation. See FileStorage constructor for more details.
|
||||
|
||||
:param encoding: Encoding of the file. Note that UTF-16 XML encoding is not supported currently and you should use 8-bit encoding instead of it.
|
||||
|
||||
|
||||
See description of parameters in :ocv:func:`FileStorage::FileStorage`. The method calls :ocv:func:`FileStorage::release` before opening the file.
|
||||
|
||||
|
||||
FileStorage::isOpened
|
||||
---------------------
|
||||
Checks whether the file is opened.
|
||||
|
||||
.. ocv:function:: bool FileStorage::isOpened() const
|
||||
|
||||
:returns: ``true`` if the object is associated with the current file and ``false`` otherwise.
|
||||
|
||||
It is a good practice to call this method after you tried to open a file.
|
||||
|
||||
|
||||
FileStorage::release
|
||||
--------------------
|
||||
Closes the file and releases all the memory buffers.
|
||||
|
||||
.. ocv:function:: void FileStorage::release()
|
||||
|
||||
Call this method after all I/O operations with the storage are finished.
|
||||
|
||||
|
||||
FileStorage::releaseAndGetString
|
||||
--------------------------------
|
||||
Closes the file and releases all the memory buffers.
|
||||
|
||||
.. ocv:function:: String FileStorage::releaseAndGetString()
|
||||
|
||||
Call this method after all I/O operations with the storage are finished. If the storage was opened for writing data and ``FileStorage::WRITE`` was specified
|
||||
|
||||
|
||||
FileStorage::getFirstTopLevelNode
|
||||
---------------------------------
|
||||
Returns the first element of the top-level mapping.
|
||||
|
||||
.. ocv:function:: FileNode FileStorage::getFirstTopLevelNode() const
|
||||
|
||||
:returns: The first element of the top-level mapping.
|
||||
|
||||
|
||||
FileStorage::root
|
||||
-----------------
|
||||
Returns the top-level mapping
|
||||
|
||||
.. ocv:function:: FileNode FileStorage::root(int streamidx=0) const
|
||||
|
||||
:param streamidx: Zero-based index of the stream. In most cases there is only one stream in the file. However, YAML supports multiple streams and so there can be several.
|
||||
|
||||
:returns: The top-level mapping.
|
||||
|
||||
|
||||
FileStorage::operator[]
|
||||
-----------------------
|
||||
Returns the specified element of the top-level mapping.
|
||||
|
||||
.. ocv:function:: FileNode FileStorage::operator[](const String& nodename) const
|
||||
|
||||
.. ocv:function:: FileNode FileStorage::operator[](const char* nodename) const
|
||||
|
||||
:param nodename: Name of the file node.
|
||||
|
||||
:returns: Node with the given name.
|
||||
|
||||
|
||||
FileStorage::operator*
|
||||
----------------------
|
||||
Returns the obsolete C FileStorage structure.
|
||||
|
||||
.. ocv:function:: CvFileStorage* FileStorage::operator *()
|
||||
|
||||
.. ocv:function:: const CvFileStorage* FileStorage::operator *() const
|
||||
|
||||
:returns: Pointer to the underlying C FileStorage structure
|
||||
|
||||
|
||||
FileStorage::writeRaw
|
||||
---------------------
|
||||
Writes multiple numbers.
|
||||
|
||||
.. ocv:function:: void FileStorage::writeRaw( const String& fmt, const uchar* vec, size_t len )
|
||||
|
||||
:param fmt: Specification of each array element that has the following format ``([count]{'u'|'c'|'w'|'s'|'i'|'f'|'d'})...`` where the characters correspond to fundamental C++ types:
|
||||
|
||||
* **u** 8-bit unsigned number
|
||||
|
||||
* **c** 8-bit signed number
|
||||
|
||||
* **w** 16-bit unsigned number
|
||||
|
||||
* **s** 16-bit signed number
|
||||
|
||||
* **i** 32-bit signed number
|
||||
|
||||
* **f** single precision floating-point number
|
||||
|
||||
* **d** double precision floating-point number
|
||||
|
||||
* **r** pointer, 32 lower bits of which are written as a signed integer. The type can be used to store structures with links between the elements.
|
||||
|
||||
``count`` is the optional counter of values of a given type. For example, ``2if`` means that each array element is a structure of 2 integers, followed by a single-precision floating-point number. The equivalent notations of the above specification are ' ``iif`` ', ' ``2i1f`` ' and so forth. Other examples: ``u`` means that the array consists of bytes, and ``2d`` means the array consists of pairs of doubles.
|
||||
|
||||
:param vec: Pointer to the written array.
|
||||
|
||||
:param len: Number of the ``uchar`` elements to write.
|
||||
|
||||
Writes one or more numbers of the specified format to the currently written structure. Usually it is more convenient to use :ocv:func:`operator <<` instead of this method.
|
||||
|
||||
FileStorage::writeObj
|
||||
---------------------
|
||||
Writes the registered C structure (CvMat, CvMatND, CvSeq).
|
||||
|
||||
.. ocv:function:: void FileStorage::writeObj( const String& name, const void* obj )
|
||||
|
||||
:param name: Name of the written object.
|
||||
|
||||
:param obj: Pointer to the object.
|
||||
|
||||
See :ocv:cfunc:`Write` for details.
|
||||
|
||||
|
||||
FileStorage::getDefaultObjectName
|
||||
---------------------------------
|
||||
Returns the normalized object name for the specified name of a file.
|
||||
|
||||
.. ocv:function:: static String FileStorage::getDefaultObjectName(const String& filename)
|
||||
|
||||
:param filename: Name of a file
|
||||
|
||||
:returns: The normalized object name.
|
||||
|
||||
|
||||
operator <<
|
||||
-----------
|
||||
Writes data to a file storage.
|
||||
|
||||
.. ocv:function:: template<typename _Tp> FileStorage& operator << (FileStorage& fs, const _Tp& value)
|
||||
|
||||
.. ocv:function:: template<typename _Tp> FileStorage& operator << ( FileStorage& fs, const vector<_Tp>& vec )
|
||||
|
||||
:param fs: Opened file storage to write data.
|
||||
|
||||
:param value: Value to be written to the file storage.
|
||||
|
||||
:param vec: Vector of values to be written to the file storage.
|
||||
|
||||
It is the main function to write data to a file storage. See an example of its usage at the beginning of the section.
|
||||
|
||||
|
||||
operator >>
|
||||
-----------
|
||||
Reads data from a file storage.
|
||||
|
||||
.. ocv:function:: template<typename _Tp> void operator >> (const FileNode& n, _Tp& value)
|
||||
|
||||
.. ocv:function:: template<typename _Tp> void operator >> (const FileNode& n, vector<_Tp>& vec)
|
||||
|
||||
.. ocv:function:: template<typename _Tp> FileNodeIterator& operator >> (FileNodeIterator& it, _Tp& value)
|
||||
|
||||
.. ocv:function:: template<typename _Tp> FileNodeIterator& operator >> (FileNodeIterator& it, vector<_Tp>& vec)
|
||||
|
||||
:param n: Node from which data will be read.
|
||||
|
||||
:param it: Iterator from which data will be read.
|
||||
|
||||
:param value: Value to be read from the file storage.
|
||||
|
||||
:param vec: Vector of values to be read from the file storage.
|
||||
|
||||
It is the main function to read data from a file storage. See an example of its usage at the beginning of the section.
|
||||
|
||||
|
||||
FileNode
|
||||
--------
|
||||
.. ocv:class:: FileNode
|
||||
|
||||
File Storage Node class. The node is used to store each and every element of the file storage opened for reading. When XML/YAML file is read, it is first parsed and stored in the memory as a hierarchical collection of nodes. Each node can be a “leaf” that is contain a single number or a string, or be a collection of other nodes. There can be named collections (mappings) where each element has a name and it is accessed by a name, and ordered collections (sequences) where elements do not have names but rather accessed by index. Type of the file node can be determined using :ocv:func:`FileNode::type` method.
|
||||
|
||||
Note that file nodes are only used for navigating file storages opened for reading. When a file storage is opened for writing, no data is stored in memory after it is written.
|
||||
|
||||
|
||||
FileNode::FileNode
|
||||
------------------
|
||||
The constructors.
|
||||
|
||||
.. ocv:function:: FileNode::FileNode()
|
||||
|
||||
.. ocv:function:: FileNode::FileNode(const CvFileStorage* fs, const CvFileNode* node)
|
||||
|
||||
.. ocv:function:: FileNode::FileNode(const FileNode& node)
|
||||
|
||||
:param fs: Pointer to the obsolete file storage structure.
|
||||
|
||||
:param node: File node to be used as initialization for the created file node.
|
||||
|
||||
These constructors are used to create a default file node, construct it from obsolete structures or from the another file node.
|
||||
|
||||
|
||||
FileNode::operator[]
|
||||
--------------------
|
||||
Returns element of a mapping node or a sequence node.
|
||||
|
||||
.. ocv:function:: FileNode FileNode::operator[](const String& nodename) const
|
||||
|
||||
.. ocv:function:: FileNode FileNode::operator[](const char* nodename) const
|
||||
|
||||
.. ocv:function:: FileNode FileNode::operator[](int i) const
|
||||
|
||||
:param nodename: Name of an element in the mapping node.
|
||||
|
||||
:param i: Index of an element in the sequence node.
|
||||
|
||||
:returns: Returns the element with the given identifier.
|
||||
|
||||
|
||||
FileNode::type
|
||||
--------------
|
||||
Returns type of the node.
|
||||
|
||||
.. ocv:function:: int FileNode::type() const
|
||||
|
||||
:returns: Type of the node. Possible values are:
|
||||
|
||||
* **FileNode::NONE** Empty node.
|
||||
|
||||
* **FileNode::INT** Integer.
|
||||
|
||||
* **FileNode::REAL** Floating-point number.
|
||||
|
||||
* **FileNode::FLOAT** Synonym or ``REAL``.
|
||||
|
||||
* **FileNode::STR** Text string in UTF-8 encoding.
|
||||
|
||||
* **FileNode::STRING** Synonym for ``STR``.
|
||||
|
||||
* **FileNode::REF** Integer of type ``size_t``. Typically used for storing complex dynamic structures where some elements reference the others.
|
||||
|
||||
* **FileNode::SEQ** Sequence.
|
||||
|
||||
* **FileNode::MAP** Mapping.
|
||||
|
||||
* **FileNode::FLOW** Compact representation of a sequence or mapping. Used only by the YAML writer.
|
||||
|
||||
* **FileNode::USER** Registered object (e.g. a matrix).
|
||||
|
||||
* **FileNode::EMPTY** Empty structure (sequence or mapping).
|
||||
|
||||
* **FileNode::NAMED** The node has a name (i.e. it is an element of a mapping).
|
||||
|
||||
|
||||
FileNode::empty
|
||||
---------------
|
||||
Checks whether the node is empty.
|
||||
|
||||
.. ocv:function:: bool FileNode::empty() const
|
||||
|
||||
:returns: ``true`` if the node is empty.
|
||||
|
||||
|
||||
FileNode::isNone
|
||||
----------------
|
||||
Checks whether the node is a "none" object
|
||||
|
||||
.. ocv:function:: bool FileNode::isNone() const
|
||||
|
||||
:returns: ``true`` if the node is a "none" object.
|
||||
|
||||
|
||||
FileNode::isSeq
|
||||
---------------
|
||||
Checks whether the node is a sequence.
|
||||
|
||||
.. ocv:function:: bool FileNode::isSeq() const
|
||||
|
||||
:returns: ``true`` if the node is a sequence.
|
||||
|
||||
|
||||
FileNode::isMap
|
||||
---------------
|
||||
Checks whether the node is a mapping.
|
||||
|
||||
.. ocv:function:: bool FileNode::isMap() const
|
||||
|
||||
:returns: ``true`` if the node is a mapping.
|
||||
|
||||
|
||||
FileNode::isInt
|
||||
---------------
|
||||
Checks whether the node is an integer.
|
||||
|
||||
.. ocv:function:: bool FileNode::isInt() const
|
||||
|
||||
:returns: ``true`` if the node is an integer.
|
||||
|
||||
|
||||
FileNode::isReal
|
||||
----------------
|
||||
Checks whether the node is a floating-point number.
|
||||
|
||||
.. ocv:function:: bool FileNode::isReal() const
|
||||
|
||||
:returns: ``true`` if the node is a floating-point number.
|
||||
|
||||
|
||||
FileNode::isString
|
||||
------------------
|
||||
Checks whether the node is a text string.
|
||||
|
||||
.. ocv:function:: bool FileNode::isString() const
|
||||
|
||||
:returns: ``true`` if the node is a text string.
|
||||
|
||||
|
||||
FileNode::isNamed
|
||||
-----------------
|
||||
Checks whether the node has a name.
|
||||
|
||||
.. ocv:function:: bool FileNode::isNamed() const
|
||||
|
||||
:returns: ``true`` if the node has a name.
|
||||
|
||||
|
||||
FileNode::name
|
||||
--------------
|
||||
Returns the node name.
|
||||
|
||||
.. ocv:function:: String FileNode::name() const
|
||||
|
||||
:returns: The node name or an empty string if the node is nameless.
|
||||
|
||||
|
||||
FileNode::size
|
||||
--------------
|
||||
Returns the number of elements in the node.
|
||||
|
||||
.. ocv:function:: size_t FileNode::size() const
|
||||
|
||||
:returns: The number of elements in the node, if it is a sequence or mapping, or 1 otherwise.
|
||||
|
||||
|
||||
FileNode::operator int
|
||||
----------------------
|
||||
Returns the node content as an integer.
|
||||
|
||||
.. ocv:function:: FileNode::operator int() const
|
||||
|
||||
:returns: The node content as an integer. If the node stores a floating-point number, it is rounded.
|
||||
|
||||
|
||||
FileNode::operator float
|
||||
------------------------
|
||||
Returns the node content as float.
|
||||
|
||||
.. ocv:function:: FileNode::operator float() const
|
||||
|
||||
:returns: The node content as float.
|
||||
|
||||
|
||||
FileNode::operator double
|
||||
-------------------------
|
||||
Returns the node content as double.
|
||||
|
||||
.. ocv:function:: FileNode::operator double() const
|
||||
|
||||
:returns: The node content as double.
|
||||
|
||||
|
||||
FileNode::operator String
|
||||
------------------------------
|
||||
Returns the node content as text string.
|
||||
|
||||
.. ocv:function:: FileNode::operator String() const
|
||||
|
||||
:returns: The node content as a text string.
|
||||
|
||||
|
||||
FileNode::operator*
|
||||
-------------------
|
||||
Returns pointer to the underlying obsolete file node structure.
|
||||
|
||||
.. ocv:function:: CvFileNode* FileNode::operator *()
|
||||
|
||||
:returns: Pointer to the underlying obsolete file node structure.
|
||||
|
||||
|
||||
FileNode::begin
|
||||
---------------
|
||||
Returns the iterator pointing to the first node element.
|
||||
|
||||
.. ocv:function:: FileNodeIterator FileNode::begin() const
|
||||
|
||||
:returns: Iterator pointing to the first node element.
|
||||
|
||||
|
||||
FileNode::end
|
||||
-------------
|
||||
Returns the iterator pointing to the element following the last node element.
|
||||
|
||||
.. ocv:function:: FileNodeIterator FileNode::end() const
|
||||
|
||||
:returns: Iterator pointing to the element following the last node element.
|
||||
|
||||
|
||||
FileNode::readRaw
|
||||
-----------------
|
||||
Reads node elements to the buffer with the specified format.
|
||||
|
||||
.. ocv:function:: void FileNode::readRaw( const String& fmt, uchar* vec, size_t len ) const
|
||||
|
||||
:param fmt: Specification of each array element. It has the same format as in :ocv:func:`FileStorage::writeRaw`.
|
||||
|
||||
:param vec: Pointer to the destination array.
|
||||
|
||||
:param len: Number of elements to read. If it is greater than number of remaining elements then all of them will be read.
|
||||
|
||||
Usually it is more convenient to use :ocv:func:`operator >>` instead of this method.
|
||||
|
||||
FileNode::readObj
|
||||
-----------------
|
||||
Reads the registered object.
|
||||
|
||||
.. ocv:function:: void* FileNode::readObj() const
|
||||
|
||||
:returns: Pointer to the read object.
|
||||
|
||||
See :ocv:cfunc:`Read` for details.
|
||||
|
||||
FileNodeIterator
|
||||
----------------
|
||||
.. ocv:class:: FileNodeIterator
|
||||
|
||||
The class ``FileNodeIterator`` is used to iterate through sequences and mappings. A standard STL notation, with ``node.begin()``, ``node.end()`` denoting the beginning and the end of a sequence, stored in ``node``. See the data reading sample in the beginning of the section.
|
||||
|
||||
|
||||
FileNodeIterator::FileNodeIterator
|
||||
----------------------------------
|
||||
The constructors.
|
||||
|
||||
.. ocv:function:: FileNodeIterator::FileNodeIterator()
|
||||
|
||||
.. ocv:function:: FileNodeIterator::FileNodeIterator(const CvFileStorage* fs, const CvFileNode* node, size_t ofs=0)
|
||||
|
||||
.. ocv:function:: FileNodeIterator::FileNodeIterator(const FileNodeIterator& it)
|
||||
|
||||
:param fs: File storage for the iterator.
|
||||
|
||||
:param node: File node for the iterator.
|
||||
|
||||
:param ofs: Index of the element in the node. The created iterator will point to this element.
|
||||
|
||||
:param it: Iterator to be used as initialization for the created iterator.
|
||||
|
||||
These constructors are used to create a default iterator, set it to specific element in a file node or construct it from another iterator.
|
||||
|
||||
|
||||
FileNodeIterator::operator*
|
||||
---------------------------
|
||||
Returns the currently observed element.
|
||||
|
||||
.. ocv:function:: FileNode FileNodeIterator::operator *() const
|
||||
|
||||
:returns: Currently observed element.
|
||||
|
||||
|
||||
FileNodeIterator::operator->
|
||||
----------------------------
|
||||
Accesses methods of the currently observed element.
|
||||
|
||||
.. ocv:function:: FileNode FileNodeIterator::operator ->() const
|
||||
|
||||
|
||||
FileNodeIterator::operator ++
|
||||
-----------------------------
|
||||
Moves iterator to the next node.
|
||||
|
||||
.. ocv:function:: FileNodeIterator& FileNodeIterator::operator ++ ()
|
||||
|
||||
.. ocv:function:: FileNodeIterator FileNodeIterator::operator ++ (int)
|
||||
|
||||
|
||||
FileNodeIterator::operator --
|
||||
-----------------------------
|
||||
Moves iterator to the previous node.
|
||||
|
||||
.. ocv:function:: FileNodeIterator& FileNodeIterator::operator -- ()
|
||||
|
||||
.. ocv:function:: FileNodeIterator FileNodeIterator::operator -- (int)
|
||||
|
||||
|
||||
FileNodeIterator::operator +=
|
||||
-----------------------------
|
||||
Moves iterator forward by the specified offset.
|
||||
|
||||
.. ocv:function:: FileNodeIterator& FileNodeIterator::operator +=( int ofs )
|
||||
|
||||
:param ofs: Offset (possibly negative) to move the iterator.
|
||||
|
||||
|
||||
FileNodeIterator::operator -=
|
||||
-----------------------------
|
||||
Moves iterator backward by the specified offset (possibly negative).
|
||||
|
||||
.. ocv:function:: FileNodeIterator& FileNodeIterator::operator -=( int ofs )
|
||||
|
||||
:param ofs: Offset (possibly negative) to move the iterator.
|
||||
|
||||
|
||||
FileNodeIterator::readRaw
|
||||
-------------------------
|
||||
Reads node elements to the buffer with the specified format.
|
||||
|
||||
.. ocv:function:: FileNodeIterator& FileNodeIterator::readRaw( const String& fmt, uchar* vec, size_t maxCount=(size_t)INT_MAX )
|
||||
|
||||
:param fmt: Specification of each array element. It has the same format as in :ocv:func:`FileStorage::writeRaw`.
|
||||
|
||||
:param vec: Pointer to the destination array.
|
||||
|
||||
:param maxCount: Number of elements to read. If it is greater than number of remaining elements then all of them will be read.
|
||||
|
||||
Usually it is more convenient to use :ocv:func:`operator >>` instead of this method.
|
||||
@@ -637,9 +637,7 @@ sub-matrices.
|
||||
Partial yet very common cases of this *user-allocated data* case are conversions from CvMat and
|
||||
IplImage to Mat. For this purpose, there is function cv::cvarrToMat taking pointers to CvMat or
|
||||
IplImage and the optional flag indicating whether to copy the data or not.
|
||||
@dontinclude samples/cpp/image.cpp
|
||||
@skip Ptr<IplImage> iplimg
|
||||
@until is converted, while the data is shared
|
||||
@snippet samples/cpp/image.cpp iplimage
|
||||
|
||||
- Use MATLAB-style array initializers, zeros(), ones(), eye(), for example:
|
||||
@code
|
||||
|
||||
@@ -1005,13 +1005,13 @@ MatIterator_<_Tp> Mat::end()
|
||||
template<typename _Tp, typename Functor> inline
|
||||
void Mat::forEach(const Functor& operation) {
|
||||
this->forEach_impl<_Tp>(operation);
|
||||
};
|
||||
}
|
||||
|
||||
template<typename _Tp, typename Functor> inline
|
||||
void Mat::forEach(const Functor& operation) const {
|
||||
// call as not const
|
||||
(const_cast<Mat*>(this))->forEach<const _Tp>(operation);
|
||||
};
|
||||
}
|
||||
|
||||
template<typename _Tp> inline
|
||||
Mat::operator std::vector<_Tp>() const
|
||||
|
||||
@@ -465,7 +465,7 @@ void Mat::forEach_impl(const Functor& operation) {
|
||||
};
|
||||
|
||||
parallel_for_(cv::Range(0, LINES), PixelOperationWrapper(reinterpret_cast<Mat_<_Tp>*>(this), operation));
|
||||
};
|
||||
}
|
||||
|
||||
/////////////////////////// Synchronization Primitives ///////////////////////////////
|
||||
|
||||
|
||||
@@ -3012,7 +3012,52 @@ static double dotProd_8s(const schar* src1, const schar* src2, int len)
|
||||
int i = 0;
|
||||
double r = 0.0;
|
||||
|
||||
#if CV_NEON
|
||||
#if CV_SSE2
|
||||
if( USE_SSE2 )
|
||||
{
|
||||
int j, len0 = len & -4, blockSize0 = (1 << 13), blockSize;
|
||||
__m128i z = _mm_setzero_si128();
|
||||
CV_DECL_ALIGNED(16) int buf[4];
|
||||
|
||||
while( i < len0 )
|
||||
{
|
||||
blockSize = std::min(len0 - i, blockSize0);
|
||||
__m128i s = z;
|
||||
j = 0;
|
||||
for( ; j <= blockSize - 16; j += 16 )
|
||||
{
|
||||
__m128i b0 = _mm_loadu_si128((const __m128i*)(src1 + j));
|
||||
__m128i b1 = _mm_loadu_si128((const __m128i*)(src2 + j));
|
||||
__m128i s0, s1, s2, s3;
|
||||
s0 = _mm_srai_epi16(_mm_unpacklo_epi8(b0, b0), 8);
|
||||
s2 = _mm_srai_epi16(_mm_unpackhi_epi8(b0, b0), 8);
|
||||
s1 = _mm_srai_epi16(_mm_unpacklo_epi8(b1, b1), 8);
|
||||
s3 = _mm_srai_epi16(_mm_unpackhi_epi8(b1, b1), 8);
|
||||
s0 = _mm_madd_epi16(s0, s1);
|
||||
s2 = _mm_madd_epi16(s2, s3);
|
||||
s = _mm_add_epi32(s, s0);
|
||||
s = _mm_add_epi32(s, s2);
|
||||
}
|
||||
|
||||
for( ; j < blockSize; j += 4 )
|
||||
{
|
||||
__m128i s0 = _mm_cvtsi32_si128(*(const int*)(src1 + j));
|
||||
__m128i s1 = _mm_cvtsi32_si128(*(const int*)(src2 + j));
|
||||
s0 = _mm_srai_epi16(_mm_unpacklo_epi8(s0, s0), 8);
|
||||
s1 = _mm_srai_epi16(_mm_unpacklo_epi8(s1, s1), 8);
|
||||
s0 = _mm_madd_epi16(s0, s1);
|
||||
s = _mm_add_epi32(s, s0);
|
||||
}
|
||||
|
||||
_mm_store_si128((__m128i*)buf, s);
|
||||
r += buf[0] + buf[1] + buf[2] + buf[3];
|
||||
|
||||
src1 += blockSize;
|
||||
src2 += blockSize;
|
||||
i += blockSize;
|
||||
}
|
||||
}
|
||||
#elif CV_NEON
|
||||
int len0 = len & -8, blockSize0 = (1 << 14), blockSize;
|
||||
int32x4_t v_zero = vdupq_n_s32(0);
|
||||
CV_DECL_ALIGNED(16) int buf[4];
|
||||
|
||||
@@ -771,25 +771,29 @@ UMat& UMat::setTo(InputArray _value, InputArray _mask)
|
||||
{
|
||||
bool haveMask = !_mask.empty();
|
||||
#ifdef HAVE_OPENCL
|
||||
int tp = type(), cn = CV_MAT_CN(tp);
|
||||
int tp = type(), cn = CV_MAT_CN(tp), d = CV_MAT_DEPTH(tp);
|
||||
|
||||
if( dims <= 2 && cn <= 4 && CV_MAT_DEPTH(tp) < CV_64F && ocl::useOpenCL() )
|
||||
{
|
||||
Mat value = _value.getMat();
|
||||
CV_Assert( checkScalar(value, type(), _value.kind(), _InputArray::UMAT) );
|
||||
double buf[4] = { 0, 0, 0, 0 };
|
||||
convertAndUnrollScalar(value, tp, (uchar *)buf, 1);
|
||||
int kercn = haveMask || cn == 3 ? cn : std::max(cn, ocl::predictOptimalVectorWidth(*this)),
|
||||
kertp = CV_MAKE_TYPE(d, kercn);
|
||||
|
||||
int scalarcn = cn == 3 ? 4 : cn, rowsPerWI = ocl::Device::getDefault().isIntel() ? 4 : 1;
|
||||
double buf[16] = { 0, 0, 0, 0, 0, 0, 0, 0,
|
||||
0, 0, 0, 0, 0, 0, 0, 0 };
|
||||
convertAndUnrollScalar(value, tp, (uchar *)buf, kercn / cn);
|
||||
|
||||
int scalarcn = kercn == 3 ? 4 : kercn, rowsPerWI = ocl::Device::getDefault().isIntel() ? 4 : 1;
|
||||
String opts = format("-D dstT=%s -D rowsPerWI=%d -D dstST=%s -D dstT1=%s -D cn=%d",
|
||||
ocl::memopTypeToStr(tp), rowsPerWI,
|
||||
ocl::memopTypeToStr(CV_MAKETYPE(tp, scalarcn)),
|
||||
ocl::memopTypeToStr(CV_MAT_DEPTH(tp)), cn);
|
||||
ocl::memopTypeToStr(kertp), rowsPerWI,
|
||||
ocl::memopTypeToStr(CV_MAKETYPE(d, scalarcn)),
|
||||
ocl::memopTypeToStr(d), kercn);
|
||||
|
||||
ocl::Kernel setK(haveMask ? "setMask" : "set", ocl::core::copyset_oclsrc, opts);
|
||||
if( !setK.empty() )
|
||||
{
|
||||
ocl::KernelArg scalararg(0, 0, 0, 0, buf, CV_ELEM_SIZE1(tp) * scalarcn);
|
||||
ocl::KernelArg scalararg(0, 0, 0, 0, buf, CV_ELEM_SIZE(d) * scalarcn);
|
||||
UMat mask;
|
||||
|
||||
if( haveMask )
|
||||
@@ -802,11 +806,11 @@ UMat& UMat::setTo(InputArray _value, InputArray _mask)
|
||||
}
|
||||
else
|
||||
{
|
||||
ocl::KernelArg dstarg = ocl::KernelArg::WriteOnly(*this);
|
||||
ocl::KernelArg dstarg = ocl::KernelArg::WriteOnly(*this, cn, kercn);
|
||||
setK.args(dstarg, scalararg);
|
||||
}
|
||||
|
||||
size_t globalsize[] = { cols, (rows + rowsPerWI - 1) / rowsPerWI };
|
||||
size_t globalsize[] = { cols * cn / kercn, (rows + rowsPerWI - 1) / rowsPerWI };
|
||||
if( setK.run(2, globalsize, NULL, false) )
|
||||
{
|
||||
CV_IMPL_ADD(CV_IMPL_OCL);
|
||||
|
||||
@@ -1,36 +0,0 @@
|
||||
Camera Calibration and 3D Reconstruction
|
||||
========================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::solvePnPRansac
|
||||
--------------------
|
||||
Finds the object pose from 3D-2D point correspondences.
|
||||
|
||||
.. ocv:function:: void cuda::solvePnPRansac(const Mat& object, const Mat& image, const Mat& camera_mat, const Mat& dist_coef, Mat& rvec, Mat& tvec, bool use_extrinsic_guess=false, int num_iters=100, float max_dist=8.0, int min_inlier_count=100, vector<int>* inliers=NULL)
|
||||
|
||||
:param object: Single-row matrix of object points.
|
||||
|
||||
:param image: Single-row matrix of image points.
|
||||
|
||||
:param camera_mat: 3x3 matrix of intrinsic camera parameters.
|
||||
|
||||
:param dist_coef: Distortion coefficients. See :ocv:func:`undistortPoints` for details.
|
||||
|
||||
:param rvec: Output 3D rotation vector.
|
||||
|
||||
:param tvec: Output 3D translation vector.
|
||||
|
||||
:param use_extrinsic_guess: Flag to indicate that the function must use ``rvec`` and ``tvec`` as an initial transformation guess. It is not supported for now.
|
||||
|
||||
:param num_iters: Maximum number of RANSAC iterations.
|
||||
|
||||
:param max_dist: Euclidean distance threshold to detect whether point is inlier or not.
|
||||
|
||||
:param min_inlier_count: Flag to indicate that the function must stop if greater or equal number of inliers is achieved. It is not supported for now.
|
||||
|
||||
:param inliers: Output vector of inlier indices.
|
||||
|
||||
.. seealso:: :ocv:func:`solvePnPRansac`
|
||||
@@ -1,12 +0,0 @@
|
||||
**************************************
|
||||
cuda. CUDA-accelerated Computer Vision
|
||||
**************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
introduction
|
||||
initalization_and_information
|
||||
data_structures
|
||||
object_detection
|
||||
calib3d
|
||||
@@ -1,311 +0,0 @@
|
||||
Data Structures
|
||||
===============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::PtrStepSz
|
||||
---------------
|
||||
.. ocv:class:: cuda::PtrStepSz
|
||||
|
||||
Lightweight class encapsulating pitched memory on a GPU and passed to nvcc-compiled code (CUDA kernels). Typically, it is used internally by OpenCV and by users who write device code. You can call its members from both host and device code. ::
|
||||
|
||||
template <typename T> struct PtrStepSz : public PtrStep<T>
|
||||
{
|
||||
__CV_GPU_HOST_DEVICE__ PtrStepSz() : cols(0), rows(0) {}
|
||||
__CV_GPU_HOST_DEVICE__ PtrStepSz(int rows_, int cols_, T* data_, size_t step_)
|
||||
: PtrStep<T>(data_, step_), cols(cols_), rows(rows_) {}
|
||||
|
||||
template <typename U>
|
||||
explicit PtrStepSz(const PtrStepSz<U>& d) : PtrStep<T>((T*)d.data, d.step), cols(d.cols), rows(d.rows){}
|
||||
|
||||
int cols;
|
||||
int rows;
|
||||
};
|
||||
|
||||
typedef PtrStepSz<unsigned char> PtrStepSzb;
|
||||
typedef PtrStepSz<float> PtrStepSzf;
|
||||
typedef PtrStepSz<int> PtrStepSzi;
|
||||
|
||||
|
||||
|
||||
cuda::PtrStep
|
||||
-------------
|
||||
.. ocv:class:: cuda::PtrStep
|
||||
|
||||
Structure similar to :ocv:class:`cuda::PtrStepSz` but containing only a pointer and row step. Width and height fields are excluded due to performance reasons. The structure is intended for internal use or for users who write device code. ::
|
||||
|
||||
template <typename T> struct PtrStep : public DevPtr<T>
|
||||
{
|
||||
__CV_GPU_HOST_DEVICE__ PtrStep() : step(0) {}
|
||||
__CV_GPU_HOST_DEVICE__ PtrStep(T* data_, size_t step_) : DevPtr<T>(data_), step(step_) {}
|
||||
|
||||
//! stride between two consecutive rows in bytes. Step is stored always and everywhere in bytes!!!
|
||||
size_t step;
|
||||
|
||||
__CV_GPU_HOST_DEVICE__ T* ptr(int y = 0) { return ( T*)( ( char*)DevPtr<T>::data + y * step); }
|
||||
__CV_GPU_HOST_DEVICE__ const T* ptr(int y = 0) const { return (const T*)( (const char*)DevPtr<T>::data + y * step); }
|
||||
|
||||
__CV_GPU_HOST_DEVICE__ T& operator ()(int y, int x) { return ptr(y)[x]; }
|
||||
__CV_GPU_HOST_DEVICE__ const T& operator ()(int y, int x) const { return ptr(y)[x]; }
|
||||
};
|
||||
|
||||
typedef PtrStep<unsigned char> PtrStepb;
|
||||
typedef PtrStep<float> PtrStepf;
|
||||
typedef PtrStep<int> PtrStepi;
|
||||
|
||||
|
||||
|
||||
cuda::GpuMat
|
||||
------------
|
||||
.. ocv:class:: cuda::GpuMat
|
||||
|
||||
Base storage class for GPU memory with reference counting. Its interface matches the :ocv:class:`Mat` interface with the following limitations:
|
||||
|
||||
* no arbitrary dimensions support (only 2D)
|
||||
* no functions that return references to their data (because references on GPU are not valid for CPU)
|
||||
* no expression templates technique support
|
||||
|
||||
Beware that the latter limitation may lead to overloaded matrix operators that cause memory allocations. The ``GpuMat`` class is convertible to :ocv:class:`cuda::PtrStepSz` and :ocv:class:`cuda::PtrStep` so it can be passed directly to the kernel.
|
||||
|
||||
.. note:: In contrast with :ocv:class:`Mat`, in most cases ``GpuMat::isContinuous() == false`` . This means that rows are aligned to a size depending on the hardware. Single-row ``GpuMat`` is always a continuous matrix.
|
||||
|
||||
::
|
||||
|
||||
class CV_EXPORTS GpuMat
|
||||
{
|
||||
public:
|
||||
//! default constructor
|
||||
GpuMat();
|
||||
|
||||
//! constructs GpuMat of the specified size and type
|
||||
GpuMat(int rows, int cols, int type);
|
||||
GpuMat(Size size, int type);
|
||||
|
||||
.....
|
||||
|
||||
//! builds GpuMat from host memory (Blocking call)
|
||||
explicit GpuMat(InputArray arr);
|
||||
|
||||
//! returns lightweight PtrStepSz structure for passing
|
||||
//to nvcc-compiled code. Contains size, data ptr and step.
|
||||
template <class T> operator PtrStepSz<T>() const;
|
||||
template <class T> operator PtrStep<T>() const;
|
||||
|
||||
//! pefroms upload data to GpuMat (Blocking call)
|
||||
void upload(InputArray arr);
|
||||
|
||||
//! pefroms upload data to GpuMat (Non-Blocking call)
|
||||
void upload(InputArray arr, Stream& stream);
|
||||
|
||||
//! pefroms download data from device to host memory (Blocking call)
|
||||
void download(OutputArray dst) const;
|
||||
|
||||
//! pefroms download data from device to host memory (Non-Blocking call)
|
||||
void download(OutputArray dst, Stream& stream) const;
|
||||
};
|
||||
|
||||
|
||||
.. note:: You are not recommended to leave static or global ``GpuMat`` variables allocated, that is, to rely on its destructor. The destruction order of such variables and CUDA context is undefined. GPU memory release function returns error if the CUDA context has been destroyed before.
|
||||
|
||||
.. seealso:: :ocv:class:`Mat`
|
||||
|
||||
|
||||
|
||||
cuda::createContinuous
|
||||
----------------------
|
||||
Creates a continuous matrix.
|
||||
|
||||
.. ocv:function:: void cuda::createContinuous(int rows, int cols, int type, OutputArray arr)
|
||||
|
||||
:param rows: Row count.
|
||||
|
||||
:param cols: Column count.
|
||||
|
||||
:param type: Type of the matrix.
|
||||
|
||||
:param arr: Destination matrix. This parameter changes only if it has a proper type and area ( :math:`\texttt{rows} \times \texttt{cols}` ).
|
||||
|
||||
Matrix is called continuous if its elements are stored continuously, that is, without gaps at the end of each row.
|
||||
|
||||
|
||||
|
||||
cuda::ensureSizeIsEnough
|
||||
------------------------
|
||||
Ensures that the size of a matrix is big enough and the matrix has a proper type.
|
||||
|
||||
.. ocv:function:: void cuda::ensureSizeIsEnough(int rows, int cols, int type, OutputArray arr)
|
||||
|
||||
:param rows: Minimum desired number of rows.
|
||||
|
||||
:param cols: Minimum desired number of columns.
|
||||
|
||||
:param type: Desired matrix type.
|
||||
|
||||
:param arr: Destination matrix.
|
||||
|
||||
The function does not reallocate memory if the matrix has proper attributes already.
|
||||
|
||||
|
||||
|
||||
cuda::CudaMem
|
||||
-------------
|
||||
.. ocv:class:: cuda::CudaMem
|
||||
|
||||
Class with reference counting wrapping special memory type allocation functions from CUDA. Its interface is also :ocv:func:`Mat`-like but with additional memory type parameters.
|
||||
|
||||
* **PAGE_LOCKED** sets a page locked memory type used commonly for fast and asynchronous uploading/downloading data from/to GPU.
|
||||
* **SHARED** specifies a zero copy memory allocation that enables mapping the host memory to GPU address space, if supported.
|
||||
* **WRITE_COMBINED** sets the write combined buffer that is not cached by CPU. Such buffers are used to supply GPU with data when GPU only reads it. The advantage is a better CPU cache utilization.
|
||||
|
||||
.. note:: Allocation size of such memory types is usually limited. For more details, see *CUDA 2.2 Pinned Memory APIs* document or *CUDA C Programming Guide*.
|
||||
|
||||
::
|
||||
|
||||
class CV_EXPORTS CudaMem
|
||||
{
|
||||
public:
|
||||
enum AllocType { PAGE_LOCKED = 1, SHARED = 2, WRITE_COMBINED = 4 };
|
||||
|
||||
explicit CudaMem(AllocType alloc_type = PAGE_LOCKED);
|
||||
|
||||
CudaMem(int rows, int cols, int type, AllocType alloc_type = PAGE_LOCKED);
|
||||
CudaMem(Size size, int type, AllocType alloc_type = PAGE_LOCKED);
|
||||
|
||||
//! creates from host memory with coping data
|
||||
explicit CudaMem(InputArray arr, AllocType alloc_type = PAGE_LOCKED);
|
||||
|
||||
......
|
||||
|
||||
//! returns matrix header with disabled reference counting for CudaMem data.
|
||||
Mat createMatHeader() const;
|
||||
|
||||
//! maps host memory into device address space and returns GpuMat header for it. Throws exception if not supported by hardware.
|
||||
GpuMat createGpuMatHeader() const;
|
||||
|
||||
......
|
||||
|
||||
AllocType alloc_type;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::CudaMem::createMatHeader
|
||||
------------------------------
|
||||
Creates a header without reference counting to :ocv:class:`cuda::CudaMem` data.
|
||||
|
||||
.. ocv:function:: Mat cuda::CudaMem::createMatHeader() const
|
||||
|
||||
|
||||
|
||||
cuda::CudaMem::createGpuMatHeader
|
||||
---------------------------------
|
||||
Maps CPU memory to GPU address space and creates the :ocv:class:`cuda::GpuMat` header without reference counting for it.
|
||||
|
||||
.. ocv:function:: GpuMat cuda::CudaMem::createGpuMatHeader() const
|
||||
|
||||
This can be done only if memory was allocated with the ``SHARED`` flag and if it is supported by the hardware. Laptops often share video and CPU memory, so address spaces can be mapped, which eliminates an extra copy.
|
||||
|
||||
|
||||
|
||||
cuda::registerPageLocked
|
||||
------------------------
|
||||
Page-locks the memory of matrix and maps it for the device(s).
|
||||
|
||||
.. ocv:function:: void cuda::registerPageLocked(Mat& m)
|
||||
|
||||
:param m: Input matrix.
|
||||
|
||||
|
||||
|
||||
cuda::unregisterPageLocked
|
||||
--------------------------
|
||||
Unmaps the memory of matrix and makes it pageable again.
|
||||
|
||||
.. ocv:function:: void cuda::unregisterPageLocked(Mat& m)
|
||||
|
||||
:param m: Input matrix.
|
||||
|
||||
|
||||
|
||||
cuda::Stream
|
||||
------------
|
||||
.. ocv:class:: cuda::Stream
|
||||
|
||||
This class encapsulates a queue of asynchronous calls.
|
||||
|
||||
.. note:: Currently, you may face problems if an operation is enqueued twice with different data. Some functions use the constant GPU memory, and next call may update the memory before the previous one has been finished. But calling different operations asynchronously is safe because each operation has its own constant buffer. Memory copy/upload/download/set operations to the buffers you hold are also safe.
|
||||
|
||||
::
|
||||
|
||||
class CV_EXPORTS Stream
|
||||
{
|
||||
public:
|
||||
Stream();
|
||||
|
||||
//! queries an asynchronous stream for completion status
|
||||
bool queryIfComplete() const;
|
||||
|
||||
//! waits for stream tasks to complete
|
||||
void waitForCompletion();
|
||||
|
||||
//! makes a compute stream wait on an event
|
||||
void waitEvent(const Event& event);
|
||||
|
||||
//! adds a callback to be called on the host after all currently enqueued items in the stream have completed
|
||||
void enqueueHostCallback(StreamCallback callback, void* userData);
|
||||
|
||||
//! return Stream object for default CUDA stream
|
||||
static Stream& Null();
|
||||
|
||||
//! returns true if stream object is not default (!= 0)
|
||||
operator bool_type() const;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::Stream::queryIfComplete
|
||||
-----------------------------
|
||||
Returns ``true`` if the current stream queue is finished. Otherwise, it returns false.
|
||||
|
||||
.. ocv:function:: bool cuda::Stream::queryIfComplete()
|
||||
|
||||
|
||||
|
||||
cuda::Stream::waitForCompletion
|
||||
-------------------------------
|
||||
Blocks the current CPU thread until all operations in the stream are complete.
|
||||
|
||||
.. ocv:function:: void cuda::Stream::waitForCompletion()
|
||||
|
||||
|
||||
|
||||
cuda::Stream::waitEvent
|
||||
-----------------------
|
||||
Makes a compute stream wait on an event.
|
||||
|
||||
.. ocv:function:: void cuda::Stream::waitEvent(const Event& event)
|
||||
|
||||
|
||||
|
||||
cuda::Stream::enqueueHostCallback
|
||||
---------------------------------
|
||||
Adds a callback to be called on the host after all currently enqueued items in the stream have completed.
|
||||
|
||||
.. ocv:function:: void cuda::Stream::enqueueHostCallback(StreamCallback callback, void* userData)
|
||||
|
||||
.. note:: Callbacks must not make any CUDA API calls. Callbacks must not perform any synchronization that may depend on outstanding device work or other callbacks that are not mandated to run earlier. Callbacks without a mandated order (in independent streams) execute in undefined order and may be serialized.
|
||||
|
||||
|
||||
|
||||
cuda::StreamAccessor
|
||||
--------------------
|
||||
.. ocv:struct:: cuda::StreamAccessor
|
||||
|
||||
Class that enables getting ``cudaStream_t`` from :ocv:class:`cuda::Stream` and is declared in ``stream_accessor.hpp`` because it is the only public header that depends on the CUDA Runtime API. Including it brings a dependency to your code. ::
|
||||
|
||||
struct StreamAccessor
|
||||
{
|
||||
CV_EXPORTS static cudaStream_t getStream(const Stream& stream);
|
||||
};
|
||||
@@ -1,375 +0,0 @@
|
||||
Initalization and Information
|
||||
=============================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::getCudaEnabledDeviceCount
|
||||
-------------------------------
|
||||
Returns the number of installed CUDA-enabled devices.
|
||||
|
||||
.. ocv:function:: int cuda::getCudaEnabledDeviceCount()
|
||||
|
||||
Use this function before any other CUDA functions calls. If OpenCV is compiled without CUDA support, this function returns 0.
|
||||
|
||||
|
||||
|
||||
cuda::setDevice
|
||||
---------------
|
||||
Sets a device and initializes it for the current thread.
|
||||
|
||||
.. ocv:function:: void cuda::setDevice(int device)
|
||||
|
||||
:param device: System index of a CUDA device starting with 0.
|
||||
|
||||
If the call of this function is omitted, a default device is initialized at the fist CUDA usage.
|
||||
|
||||
|
||||
|
||||
cuda::getDevice
|
||||
---------------
|
||||
Returns the current device index set by :ocv:func:`cuda::setDevice` or initialized by default.
|
||||
|
||||
.. ocv:function:: int cuda::getDevice()
|
||||
|
||||
|
||||
|
||||
cuda::resetDevice
|
||||
-----------------
|
||||
Explicitly destroys and cleans up all resources associated with the current device in the current process.
|
||||
|
||||
.. ocv:function:: void cuda::resetDevice()
|
||||
|
||||
Any subsequent API call to this device will reinitialize the device.
|
||||
|
||||
|
||||
|
||||
cuda::FeatureSet
|
||||
----------------
|
||||
Enumeration providing CUDA computing features.
|
||||
|
||||
.. ocv:enum:: cuda::FeatureSet
|
||||
|
||||
.. ocv:emember:: FEATURE_SET_COMPUTE_10
|
||||
.. ocv:emember:: FEATURE_SET_COMPUTE_11
|
||||
.. ocv:emember:: FEATURE_SET_COMPUTE_12
|
||||
.. ocv:emember:: FEATURE_SET_COMPUTE_13
|
||||
.. ocv:emember:: FEATURE_SET_COMPUTE_20
|
||||
.. ocv:emember:: FEATURE_SET_COMPUTE_21
|
||||
.. ocv:emember:: GLOBAL_ATOMICS
|
||||
.. ocv:emember:: SHARED_ATOMICS
|
||||
.. ocv:emember:: NATIVE_DOUBLE
|
||||
|
||||
|
||||
|
||||
cuda::TargetArchs
|
||||
-----------------
|
||||
.. ocv:class:: cuda::TargetArchs
|
||||
|
||||
Class providing a set of static methods to check what NVIDIA* card architecture the CUDA module was built for.
|
||||
|
||||
The following method checks whether the module was built with the support of the given feature:
|
||||
|
||||
.. ocv:function:: static bool cuda::TargetArchs::builtWith( FeatureSet feature_set )
|
||||
|
||||
:param feature_set: Features to be checked. See :ocv:enum:`cuda::FeatureSet`.
|
||||
|
||||
There is a set of methods to check whether the module contains intermediate (PTX) or binary CUDA code for the given architecture(s):
|
||||
|
||||
.. ocv:function:: static bool cuda::TargetArchs::has(int major, int minor)
|
||||
|
||||
.. ocv:function:: static bool cuda::TargetArchs::hasPtx(int major, int minor)
|
||||
|
||||
.. ocv:function:: static bool cuda::TargetArchs::hasBin(int major, int minor)
|
||||
|
||||
.. ocv:function:: static bool cuda::TargetArchs::hasEqualOrLessPtx(int major, int minor)
|
||||
|
||||
.. ocv:function:: static bool cuda::TargetArchs::hasEqualOrGreater(int major, int minor)
|
||||
|
||||
.. ocv:function:: static bool cuda::TargetArchs::hasEqualOrGreaterPtx(int major, int minor)
|
||||
|
||||
.. ocv:function:: static bool cuda::TargetArchs::hasEqualOrGreaterBin(int major, int minor)
|
||||
|
||||
:param major: Major compute capability version.
|
||||
|
||||
:param minor: Minor compute capability version.
|
||||
|
||||
According to the CUDA C Programming Guide Version 3.2: "PTX code produced for some specific compute capability can always be compiled to binary code of greater or equal compute capability".
|
||||
|
||||
|
||||
|
||||
cuda::DeviceInfo
|
||||
----------------
|
||||
.. ocv:class:: cuda::DeviceInfo
|
||||
|
||||
Class providing functionality for querying the specified GPU properties. ::
|
||||
|
||||
class CV_EXPORTS DeviceInfo
|
||||
{
|
||||
public:
|
||||
//! creates DeviceInfo object for the current GPU
|
||||
DeviceInfo();
|
||||
|
||||
//! creates DeviceInfo object for the given GPU
|
||||
DeviceInfo(int device_id);
|
||||
|
||||
//! ASCII string identifying device
|
||||
const char* name() const;
|
||||
|
||||
//! global memory available on device in bytes
|
||||
size_t totalGlobalMem() const;
|
||||
|
||||
//! shared memory available per block in bytes
|
||||
size_t sharedMemPerBlock() const;
|
||||
|
||||
//! 32-bit registers available per block
|
||||
int regsPerBlock() const;
|
||||
|
||||
//! warp size in threads
|
||||
int warpSize() const;
|
||||
|
||||
//! maximum pitch in bytes allowed by memory copies
|
||||
size_t memPitch() const;
|
||||
|
||||
//! maximum number of threads per block
|
||||
int maxThreadsPerBlock() const;
|
||||
|
||||
//! maximum size of each dimension of a block
|
||||
Vec3i maxThreadsDim() const;
|
||||
|
||||
//! maximum size of each dimension of a grid
|
||||
Vec3i maxGridSize() const;
|
||||
|
||||
//! clock frequency in kilohertz
|
||||
int clockRate() const;
|
||||
|
||||
//! constant memory available on device in bytes
|
||||
size_t totalConstMem() const;
|
||||
|
||||
//! major compute capability
|
||||
int majorVersion() const;
|
||||
|
||||
//! minor compute capability
|
||||
int minorVersion() const;
|
||||
|
||||
//! alignment requirement for textures
|
||||
size_t textureAlignment() const;
|
||||
|
||||
//! pitch alignment requirement for texture references bound to pitched memory
|
||||
size_t texturePitchAlignment() const;
|
||||
|
||||
//! number of multiprocessors on device
|
||||
int multiProcessorCount() const;
|
||||
|
||||
//! specified whether there is a run time limit on kernels
|
||||
bool kernelExecTimeoutEnabled() const;
|
||||
|
||||
//! device is integrated as opposed to discrete
|
||||
bool integrated() const;
|
||||
|
||||
//! device can map host memory with cudaHostAlloc/cudaHostGetDevicePointer
|
||||
bool canMapHostMemory() const;
|
||||
|
||||
enum ComputeMode
|
||||
{
|
||||
ComputeModeDefault, /**< default compute mode (Multiple threads can use ::cudaSetDevice() with this device) */
|
||||
ComputeModeExclusive, /**< compute-exclusive-thread mode (Only one thread in one process will be able to use ::cudaSetDevice() with this device) */
|
||||
ComputeModeProhibited, /**< compute-prohibited mode (No threads can use ::cudaSetDevice() with this device) */
|
||||
ComputeModeExclusiveProcess /**< compute-exclusive-process mode (Many threads in one process will be able to use ::cudaSetDevice() with this device) */
|
||||
};
|
||||
|
||||
//! compute mode
|
||||
ComputeMode computeMode() const;
|
||||
|
||||
//! maximum 1D texture size
|
||||
int maxTexture1D() const;
|
||||
|
||||
//! maximum 1D mipmapped texture size
|
||||
int maxTexture1DMipmap() const;
|
||||
|
||||
//! maximum size for 1D textures bound to linear memory
|
||||
int maxTexture1DLinear() const;
|
||||
|
||||
//! maximum 2D texture dimensions
|
||||
Vec2i maxTexture2D() const;
|
||||
|
||||
//! maximum 2D mipmapped texture dimensions
|
||||
Vec2i maxTexture2DMipmap() const;
|
||||
|
||||
//! maximum dimensions (width, height, pitch) for 2D textures bound to pitched memory
|
||||
Vec3i maxTexture2DLinear() const;
|
||||
|
||||
//! maximum 2D texture dimensions if texture gather operations have to be performed
|
||||
Vec2i maxTexture2DGather() const;
|
||||
|
||||
//! maximum 3D texture dimensions
|
||||
Vec3i maxTexture3D() const;
|
||||
|
||||
//! maximum Cubemap texture dimensions
|
||||
int maxTextureCubemap() const;
|
||||
|
||||
//! maximum 1D layered texture dimensions
|
||||
Vec2i maxTexture1DLayered() const;
|
||||
|
||||
//! maximum 2D layered texture dimensions
|
||||
Vec3i maxTexture2DLayered() const;
|
||||
|
||||
//! maximum Cubemap layered texture dimensions
|
||||
Vec2i maxTextureCubemapLayered() const;
|
||||
|
||||
//! maximum 1D surface size
|
||||
int maxSurface1D() const;
|
||||
|
||||
//! maximum 2D surface dimensions
|
||||
Vec2i maxSurface2D() const;
|
||||
|
||||
//! maximum 3D surface dimensions
|
||||
Vec3i maxSurface3D() const;
|
||||
|
||||
//! maximum 1D layered surface dimensions
|
||||
Vec2i maxSurface1DLayered() const;
|
||||
|
||||
//! maximum 2D layered surface dimensions
|
||||
Vec3i maxSurface2DLayered() const;
|
||||
|
||||
//! maximum Cubemap surface dimensions
|
||||
int maxSurfaceCubemap() const;
|
||||
|
||||
//! maximum Cubemap layered surface dimensions
|
||||
Vec2i maxSurfaceCubemapLayered() const;
|
||||
|
||||
//! alignment requirements for surfaces
|
||||
size_t surfaceAlignment() const;
|
||||
|
||||
//! device can possibly execute multiple kernels concurrently
|
||||
bool concurrentKernels() const;
|
||||
|
||||
//! device has ECC support enabled
|
||||
bool ECCEnabled() const;
|
||||
|
||||
//! PCI bus ID of the device
|
||||
int pciBusID() const;
|
||||
|
||||
//! PCI device ID of the device
|
||||
int pciDeviceID() const;
|
||||
|
||||
//! PCI domain ID of the device
|
||||
int pciDomainID() const;
|
||||
|
||||
//! true if device is a Tesla device using TCC driver, false otherwise
|
||||
bool tccDriver() const;
|
||||
|
||||
//! number of asynchronous engines
|
||||
int asyncEngineCount() const;
|
||||
|
||||
//! device shares a unified address space with the host
|
||||
bool unifiedAddressing() const;
|
||||
|
||||
//! peak memory clock frequency in kilohertz
|
||||
int memoryClockRate() const;
|
||||
|
||||
//! global memory bus width in bits
|
||||
int memoryBusWidth() const;
|
||||
|
||||
//! size of L2 cache in bytes
|
||||
int l2CacheSize() const;
|
||||
|
||||
//! maximum resident threads per multiprocessor
|
||||
int maxThreadsPerMultiProcessor() const;
|
||||
|
||||
//! gets free and total device memory
|
||||
void queryMemory(size_t& totalMemory, size_t& freeMemory) const;
|
||||
size_t freeMemory() const;
|
||||
size_t totalMemory() const;
|
||||
|
||||
//! checks whether device supports the given feature
|
||||
bool supports(FeatureSet feature_set) const;
|
||||
|
||||
//! checks whether the CUDA module can be run on the given device
|
||||
bool isCompatible() const;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::DeviceInfo::DeviceInfo
|
||||
----------------------------
|
||||
The constructors.
|
||||
|
||||
.. ocv:function:: cuda::DeviceInfo::DeviceInfo()
|
||||
|
||||
.. ocv:function:: cuda::DeviceInfo::DeviceInfo(int device_id)
|
||||
|
||||
:param device_id: System index of the CUDA device starting with 0.
|
||||
|
||||
Constructs the ``DeviceInfo`` object for the specified device. If ``device_id`` parameter is missed, it constructs an object for the current device.
|
||||
|
||||
|
||||
|
||||
cuda::DeviceInfo::name
|
||||
----------------------
|
||||
Returns the device name.
|
||||
|
||||
.. ocv:function:: const char* cuda::DeviceInfo::name() const
|
||||
|
||||
|
||||
|
||||
cuda::DeviceInfo::majorVersion
|
||||
------------------------------
|
||||
Returns the major compute capability version.
|
||||
|
||||
.. ocv:function:: int cuda::DeviceInfo::majorVersion()
|
||||
|
||||
|
||||
|
||||
cuda::DeviceInfo::minorVersion
|
||||
------------------------------
|
||||
Returns the minor compute capability version.
|
||||
|
||||
.. ocv:function:: int cuda::DeviceInfo::minorVersion()
|
||||
|
||||
|
||||
|
||||
cuda::DeviceInfo::freeMemory
|
||||
----------------------------
|
||||
Returns the amount of free memory in bytes.
|
||||
|
||||
.. ocv:function:: size_t cuda::DeviceInfo::freeMemory()
|
||||
|
||||
|
||||
|
||||
cuda::DeviceInfo::totalMemory
|
||||
-----------------------------
|
||||
Returns the amount of total memory in bytes.
|
||||
|
||||
.. ocv:function:: size_t cuda::DeviceInfo::totalMemory()
|
||||
|
||||
|
||||
|
||||
cuda::DeviceInfo::supports
|
||||
--------------------------
|
||||
Provides information on CUDA feature support.
|
||||
|
||||
.. ocv:function:: bool cuda::DeviceInfo::supports(FeatureSet feature_set) const
|
||||
|
||||
:param feature_set: Features to be checked. See :ocv:enum:`cuda::FeatureSet`.
|
||||
|
||||
This function returns ``true`` if the device has the specified CUDA feature. Otherwise, it returns ``false`` .
|
||||
|
||||
|
||||
|
||||
cuda::DeviceInfo::isCompatible
|
||||
------------------------------
|
||||
Checks the CUDA module and device compatibility.
|
||||
|
||||
.. ocv:function:: bool cuda::DeviceInfo::isCompatible()
|
||||
|
||||
This function returns ``true`` if the CUDA module can be run on the specified device. Otherwise, it returns ``false`` .
|
||||
|
||||
|
||||
|
||||
cuda::DeviceInfo::deviceID
|
||||
--------------------------
|
||||
Returns system index of the CUDA device starting with 0.
|
||||
|
||||
.. ocv:function:: int cuda::DeviceInfo::deviceID()
|
||||
@@ -1,61 +0,0 @@
|
||||
CUDA Module Introduction
|
||||
========================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
General Information
|
||||
-------------------
|
||||
|
||||
The OpenCV CUDA module is a set of classes and functions to utilize CUDA computational capabilities. It is implemented using NVIDIA* CUDA* Runtime API and supports only NVIDIA GPUs. The OpenCV CUDA module includes utility functions, low-level vision primitives, and high-level algorithms. The utility functions and low-level primitives provide a powerful infrastructure for developing fast vision algorithms taking advantage of CUDA whereas the high-level functionality includes some state-of-the-art algorithms (such as stereo correspondence, face and people detectors, and others) ready to be used by the application developers.
|
||||
|
||||
The CUDA module is designed as a host-level API. This means that if you have pre-compiled OpenCV CUDA binaries, you are not required to have the CUDA Toolkit installed or write any extra code to make use of the CUDA.
|
||||
|
||||
The OpenCV CUDA module is designed for ease of use and does not require any knowledge of CUDA. Though, such a knowledge will certainly be useful to handle non-trivial cases or achieve the highest performance. It is helpful to understand the cost of various operations, what the GPU does, what the preferred data formats are, and so on. The CUDA module is an effective instrument for quick implementation of CUDA-accelerated computer vision algorithms. However, if your algorithm involves many simple operations, then, for the best possible performance, you may still need to write your own kernels to avoid extra write and read operations on the intermediate results.
|
||||
|
||||
To enable CUDA support, configure OpenCV using ``CMake`` with ``WITH_CUDA=ON`` . When the flag is set and if CUDA is installed, the full-featured OpenCV CUDA module is built. Otherwise, the module is still built but at runtime all functions from the module throw
|
||||
:ocv:class:`Exception` with ``CV_GpuNotSupported`` error code, except for
|
||||
:ocv:func:`cuda::getCudaEnabledDeviceCount()`. The latter function returns zero GPU count in this case. Building OpenCV without CUDA support does not perform device code compilation, so it does not require the CUDA Toolkit installed. Therefore, using the
|
||||
:ocv:func:`cuda::getCudaEnabledDeviceCount()` function, you can implement a high-level algorithm that will detect GPU presence at runtime and choose an appropriate implementation (CPU or GPU) accordingly.
|
||||
|
||||
Compilation for Different NVIDIA* Platforms
|
||||
-------------------------------------------
|
||||
|
||||
NVIDIA* compiler enables generating binary code (cubin and fatbin) and intermediate code (PTX). Binary code often implies a specific GPU architecture and generation, so the compatibility with other GPUs is not guaranteed. PTX is targeted for a virtual platform that is defined entirely by the set of capabilities or features. Depending on the selected virtual platform, some of the instructions are emulated or disabled, even if the real hardware supports all the features.
|
||||
|
||||
At the first call, the PTX code is compiled to binary code for the particular GPU using a JIT compiler. When the target GPU has a compute capability (CC) lower than the PTX code, JIT fails.
|
||||
By default, the OpenCV CUDA module includes:
|
||||
|
||||
*
|
||||
Binaries for compute capabilities 1.3 and 2.0 (controlled by ``CUDA_ARCH_BIN`` in ``CMake``)
|
||||
|
||||
*
|
||||
PTX code for compute capabilities 1.1 and 1.3 (controlled by ``CUDA_ARCH_PTX`` in ``CMake``)
|
||||
|
||||
This means that for devices with CC 1.3 and 2.0 binary images are ready to run. For all newer platforms, the PTX code for 1.3 is JIT'ed to a binary image. For devices with CC 1.1 and 1.2, the PTX for 1.1 is JIT'ed. For devices with CC 1.0, no code is available and the functions throw
|
||||
:ocv:class:`Exception`. For platforms where JIT compilation is performed first, the run is slow.
|
||||
|
||||
On a GPU with CC 1.0, you can still compile the CUDA module and most of the functions will run flawlessly. To achieve this, add "1.0" to the list of binaries, for example, ``CUDA_ARCH_BIN="1.0 1.3 2.0"`` . The functions that cannot be run on CC 1.0 GPUs throw an exception.
|
||||
|
||||
You can always determine at runtime whether the OpenCV GPU-built binaries (or PTX code) are compatible with your GPU. The function
|
||||
:ocv:func:`cuda::DeviceInfo::isCompatible` returns the compatibility status (true/false).
|
||||
|
||||
Utilizing Multiple GPUs
|
||||
-----------------------
|
||||
|
||||
In the current version, each of the OpenCV CUDA algorithms can use only a single GPU. So, to utilize multiple GPUs, you have to manually distribute the work between GPUs.
|
||||
Switching active devie can be done using :ocv:func:`cuda::setDevice()` function. For more details please read Cuda C Programming Guide.
|
||||
|
||||
While developing algorithms for multiple GPUs, note a data passing overhead. For primitive functions and small images, it can be significant, which may eliminate all the advantages of having multiple GPUs. But for high-level algorithms, consider using multi-GPU acceleration. For example, the Stereo Block Matching algorithm has been successfully parallelized using the following algorithm:
|
||||
|
||||
|
||||
1. Split each image of the stereo pair into two horizontal overlapping stripes.
|
||||
|
||||
|
||||
2. Process each pair of stripes (from the left and right images) on a separate Fermi* GPU.
|
||||
|
||||
|
||||
3. Merge the results into a single disparity map.
|
||||
|
||||
With this algorithm, a dual GPU gave a 180% performance increase comparing to the single Fermi GPU. For a source code example, see https://github.com/Itseez/opencv/tree/master/samples/gpu/.
|
||||
@@ -1,331 +0,0 @@
|
||||
Object Detection
|
||||
================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor
|
||||
-------------------
|
||||
.. ocv:struct:: cuda::HOGDescriptor
|
||||
|
||||
The class implements Histogram of Oriented Gradients ([Dalal2005]_) object detector. ::
|
||||
|
||||
struct CV_EXPORTS HOGDescriptor
|
||||
{
|
||||
enum { DEFAULT_WIN_SIGMA = -1 };
|
||||
enum { DEFAULT_NLEVELS = 64 };
|
||||
enum { DESCR_FORMAT_ROW_BY_ROW, DESCR_FORMAT_COL_BY_COL };
|
||||
|
||||
HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16),
|
||||
Size block_stride=Size(8, 8), Size cell_size=Size(8, 8),
|
||||
int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA,
|
||||
double threshold_L2hys=0.2, bool gamma_correction=true,
|
||||
int nlevels=DEFAULT_NLEVELS);
|
||||
|
||||
size_t getDescriptorSize() const;
|
||||
size_t getBlockHistogramSize() const;
|
||||
|
||||
void setSVMDetector(const vector<float>& detector);
|
||||
|
||||
static vector<float> getDefaultPeopleDetector();
|
||||
static vector<float> getPeopleDetector48x96();
|
||||
static vector<float> getPeopleDetector64x128();
|
||||
|
||||
void detect(const GpuMat& img, vector<Point>& found_locations,
|
||||
double hit_threshold=0, Size win_stride=Size(),
|
||||
Size padding=Size());
|
||||
|
||||
void detectMultiScale(const GpuMat& img, vector<Rect>& found_locations,
|
||||
double hit_threshold=0, Size win_stride=Size(),
|
||||
Size padding=Size(), double scale0=1.05,
|
||||
int group_threshold=2);
|
||||
|
||||
void getDescriptors(const GpuMat& img, Size win_stride,
|
||||
GpuMat& descriptors,
|
||||
int descr_format=DESCR_FORMAT_COL_BY_COL);
|
||||
|
||||
Size win_size;
|
||||
Size block_size;
|
||||
Size block_stride;
|
||||
Size cell_size;
|
||||
int nbins;
|
||||
double win_sigma;
|
||||
double threshold_L2hys;
|
||||
bool gamma_correction;
|
||||
int nlevels;
|
||||
|
||||
private:
|
||||
// Hidden
|
||||
}
|
||||
|
||||
|
||||
Interfaces of all methods are kept similar to the ``CPU HOG`` descriptor and detector analogues as much as possible.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example applying the HOG descriptor for people detection can be found at opencv_source_code/samples/cpp/peopledetect.cpp
|
||||
* A CUDA example applying the HOG descriptor for people detection can be found at opencv_source_code/samples/gpu/hog.cpp
|
||||
|
||||
* (Python) An example applying the HOG descriptor for people detection can be found at opencv_source_code/samples/python2/peopledetect.py
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor::HOGDescriptor
|
||||
----------------------------------
|
||||
Creates the ``HOG`` descriptor and detector.
|
||||
|
||||
.. ocv:function:: cuda::HOGDescriptor::HOGDescriptor(Size win_size=Size(64, 128), Size block_size=Size(16, 16), Size block_stride=Size(8, 8), Size cell_size=Size(8, 8), int nbins=9, double win_sigma=DEFAULT_WIN_SIGMA, double threshold_L2hys=0.2, bool gamma_correction=true, int nlevels=DEFAULT_NLEVELS)
|
||||
|
||||
:param win_size: Detection window size. Align to block size and block stride.
|
||||
|
||||
:param block_size: Block size in pixels. Align to cell size. Only (16,16) is supported for now.
|
||||
|
||||
:param block_stride: Block stride. It must be a multiple of cell size.
|
||||
|
||||
:param cell_size: Cell size. Only (8, 8) is supported for now.
|
||||
|
||||
:param nbins: Number of bins. Only 9 bins per cell are supported for now.
|
||||
|
||||
:param win_sigma: Gaussian smoothing window parameter.
|
||||
|
||||
:param threshold_L2hys: L2-Hys normalization method shrinkage.
|
||||
|
||||
:param gamma_correction: Flag to specify whether the gamma correction preprocessing is required or not.
|
||||
|
||||
:param nlevels: Maximum number of detection window increases.
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor::getDescriptorSize
|
||||
--------------------------------------
|
||||
Returns the number of coefficients required for the classification.
|
||||
|
||||
.. ocv:function:: size_t cuda::HOGDescriptor::getDescriptorSize() const
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor::getBlockHistogramSize
|
||||
------------------------------------------
|
||||
Returns the block histogram size.
|
||||
|
||||
.. ocv:function:: size_t cuda::HOGDescriptor::getBlockHistogramSize() const
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor::setSVMDetector
|
||||
-----------------------------------
|
||||
Sets coefficients for the linear SVM classifier.
|
||||
|
||||
.. ocv:function:: void cuda::HOGDescriptor::setSVMDetector(const vector<float>& detector)
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor::getDefaultPeopleDetector
|
||||
---------------------------------------------
|
||||
Returns coefficients of the classifier trained for people detection (for default window size).
|
||||
|
||||
.. ocv:function:: static vector<float> cuda::HOGDescriptor::getDefaultPeopleDetector()
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor::getPeopleDetector48x96
|
||||
-------------------------------------------
|
||||
Returns coefficients of the classifier trained for people detection (for 48x96 windows).
|
||||
|
||||
.. ocv:function:: static vector<float> cuda::HOGDescriptor::getPeopleDetector48x96()
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor::getPeopleDetector64x128
|
||||
--------------------------------------------
|
||||
Returns coefficients of the classifier trained for people detection (for 64x128 windows).
|
||||
|
||||
.. ocv:function:: static vector<float> cuda::HOGDescriptor::getPeopleDetector64x128()
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor::detect
|
||||
---------------------------
|
||||
Performs object detection without a multi-scale window.
|
||||
|
||||
.. ocv:function:: void cuda::HOGDescriptor::detect(const GpuMat& img, vector<Point>& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size())
|
||||
|
||||
:param img: Source image. ``CV_8UC1`` and ``CV_8UC4`` types are supported for now.
|
||||
|
||||
:param found_locations: Left-top corner points of detected objects boundaries.
|
||||
|
||||
:param hit_threshold: Threshold for the distance between features and SVM classifying plane. Usually it is 0 and should be specfied in the detector coefficients (as the last free coefficient). But if the free coefficient is omitted (which is allowed), you can specify it manually here.
|
||||
|
||||
:param win_stride: Window stride. It must be a multiple of block stride.
|
||||
|
||||
:param padding: Mock parameter to keep the CPU interface compatibility. It must be (0,0).
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor::detectMultiScale
|
||||
-------------------------------------
|
||||
Performs object detection with a multi-scale window.
|
||||
|
||||
.. ocv:function:: void cuda::HOGDescriptor::detectMultiScale(const GpuMat& img, vector<Rect>& found_locations, double hit_threshold=0, Size win_stride=Size(), Size padding=Size(), double scale0=1.05, int group_threshold=2)
|
||||
|
||||
:param img: Source image. See :ocv:func:`cuda::HOGDescriptor::detect` for type limitations.
|
||||
|
||||
:param found_locations: Detected objects boundaries.
|
||||
|
||||
:param hit_threshold: Threshold for the distance between features and SVM classifying plane. See :ocv:func:`cuda::HOGDescriptor::detect` for details.
|
||||
|
||||
:param win_stride: Window stride. It must be a multiple of block stride.
|
||||
|
||||
:param padding: Mock parameter to keep the CPU interface compatibility. It must be (0,0).
|
||||
|
||||
:param scale0: Coefficient of the detection window increase.
|
||||
|
||||
:param group_threshold: Coefficient to regulate the similarity threshold. When detected, some objects can be covered by many rectangles. 0 means not to perform grouping. See :ocv:func:`groupRectangles` .
|
||||
|
||||
|
||||
|
||||
cuda::HOGDescriptor::getDescriptors
|
||||
-----------------------------------
|
||||
Returns block descriptors computed for the whole image.
|
||||
|
||||
.. ocv:function:: void cuda::HOGDescriptor::getDescriptors(const GpuMat& img, Size win_stride, GpuMat& descriptors, int descr_format=DESCR_FORMAT_COL_BY_COL)
|
||||
|
||||
:param img: Source image. See :ocv:func:`cuda::HOGDescriptor::detect` for type limitations.
|
||||
|
||||
:param win_stride: Window stride. It must be a multiple of block stride.
|
||||
|
||||
:param descriptors: 2D array of descriptors.
|
||||
|
||||
:param descr_format: Descriptor storage format:
|
||||
|
||||
* **DESCR_FORMAT_ROW_BY_ROW** - Row-major order.
|
||||
|
||||
* **DESCR_FORMAT_COL_BY_COL** - Column-major order.
|
||||
|
||||
The function is mainly used to learn the classifier.
|
||||
|
||||
|
||||
|
||||
cuda::CascadeClassifier_CUDA
|
||||
----------------------------
|
||||
.. ocv:class:: cuda::CascadeClassifier_CUDA
|
||||
|
||||
Cascade classifier class used for object detection. Supports HAAR and LBP cascades. ::
|
||||
|
||||
class CV_EXPORTS CascadeClassifier_CUDA
|
||||
{
|
||||
public:
|
||||
CascadeClassifier_CUDA();
|
||||
CascadeClassifier_CUDA(const String& filename);
|
||||
~CascadeClassifier_CUDA();
|
||||
|
||||
bool empty() const;
|
||||
bool load(const String& filename);
|
||||
void release();
|
||||
|
||||
/* Returns number of detected objects */
|
||||
int detectMultiScale( const GpuMat& image, GpuMat& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size());
|
||||
int detectMultiScale( const GpuMat& image, GpuMat& objectsBuf, Size maxObjectSize, Size minSize = Size(), double scaleFactor = 1.1, int minNeighbors = 4);
|
||||
|
||||
/* Finds only the largest object. Special mode if training is required.*/
|
||||
bool findLargestObject;
|
||||
|
||||
/* Draws rectangles in input image */
|
||||
bool visualizeInPlace;
|
||||
|
||||
Size getClassifierSize() const;
|
||||
};
|
||||
|
||||
.. note::
|
||||
|
||||
* A cascade classifier example can be found at opencv_source_code/samples/gpu/cascadeclassifier.cpp
|
||||
* A Nvidea API specific cascade classifier example can be found at opencv_source_code/samples/gpu/cascadeclassifier_nvidia_api.cpp
|
||||
|
||||
|
||||
|
||||
cuda::CascadeClassifier_CUDA::CascadeClassifier_CUDA
|
||||
----------------------------------------------------
|
||||
Loads the classifier from a file. Cascade type is detected automatically by constructor parameter.
|
||||
|
||||
.. ocv:function:: cuda::CascadeClassifier_CUDA::CascadeClassifier_CUDA(const String& filename)
|
||||
|
||||
:param filename: Name of the file from which the classifier is loaded. Only the old ``haar`` classifier (trained by the ``haar`` training application) and NVIDIA's ``nvbin`` are supported for HAAR and only new type of OpenCV XML cascade supported for LBP.
|
||||
|
||||
|
||||
|
||||
cuda::CascadeClassifier_CUDA::empty
|
||||
-----------------------------------
|
||||
Checks whether the classifier is loaded or not.
|
||||
|
||||
.. ocv:function:: bool cuda::CascadeClassifier_CUDA::empty() const
|
||||
|
||||
|
||||
|
||||
cuda::CascadeClassifier_CUDA::load
|
||||
----------------------------------
|
||||
Loads the classifier from a file. The previous content is destroyed.
|
||||
|
||||
.. ocv:function:: bool cuda::CascadeClassifier_CUDA::load(const String& filename)
|
||||
|
||||
:param filename: Name of the file from which the classifier is loaded. Only the old ``haar`` classifier (trained by the ``haar`` training application) and NVIDIA's ``nvbin`` are supported for HAAR and only new type of OpenCV XML cascade supported for LBP.
|
||||
|
||||
|
||||
|
||||
cuda::CascadeClassifier_CUDA::release
|
||||
-------------------------------------
|
||||
Destroys the loaded classifier.
|
||||
|
||||
.. ocv:function:: void cuda::CascadeClassifier_CUDA::release()
|
||||
|
||||
|
||||
|
||||
cuda::CascadeClassifier_CUDA::detectMultiScale
|
||||
----------------------------------------------
|
||||
Detects objects of different sizes in the input image.
|
||||
|
||||
.. ocv:function:: int cuda::CascadeClassifier_CUDA::detectMultiScale(const GpuMat& image, GpuMat& objectsBuf, double scaleFactor=1.2, int minNeighbors=4, Size minSize=Size())
|
||||
|
||||
.. ocv:function:: int cuda::CascadeClassifier_CUDA::detectMultiScale(const GpuMat& image, GpuMat& objectsBuf, Size maxObjectSize, Size minSize = Size(), double scaleFactor = 1.1, int minNeighbors = 4)
|
||||
|
||||
:param image: Matrix of type ``CV_8U`` containing an image where objects should be detected.
|
||||
|
||||
:param objectsBuf: Buffer to store detected objects (rectangles). If it is empty, it is allocated with the default size. If not empty, the function searches not more than N objects, where ``N = sizeof(objectsBufer's data)/sizeof(cv::Rect)``.
|
||||
|
||||
:param maxObjectSize: Maximum possible object size. Objects larger than that are ignored. Used for second signature and supported only for LBP cascades.
|
||||
|
||||
:param scaleFactor: Parameter specifying how much the image size is reduced at each image scale.
|
||||
|
||||
:param minNeighbors: Parameter specifying how many neighbors each candidate rectangle should have to retain it.
|
||||
|
||||
:param minSize: Minimum possible object size. Objects smaller than that are ignored.
|
||||
|
||||
The detected objects are returned as a list of rectangles.
|
||||
|
||||
The function returns the number of detected objects, so you can retrieve them as in the following example: ::
|
||||
|
||||
cuda::CascadeClassifier_CUDA cascade_gpu(...);
|
||||
|
||||
Mat image_cpu = imread(...)
|
||||
GpuMat image_gpu(image_cpu);
|
||||
|
||||
GpuMat objbuf;
|
||||
int detections_number = cascade_gpu.detectMultiScale( image_gpu,
|
||||
objbuf, 1.2, minNeighbors);
|
||||
|
||||
Mat obj_host;
|
||||
// download only detected number of rectangles
|
||||
objbuf.colRange(0, detections_number).download(obj_host);
|
||||
|
||||
Rect* faces = obj_host.ptr<Rect>();
|
||||
for(int i = 0; i < detections_num; ++i)
|
||||
cv::rectangle(image_cpu, faces[i], Scalar(255));
|
||||
|
||||
imshow("Faces", image_cpu);
|
||||
|
||||
|
||||
.. seealso:: :ocv:func:`CascadeClassifier::detectMultiScale`
|
||||
|
||||
|
||||
|
||||
.. [Dalal2005] Navneet Dalal and Bill Triggs. *Histogram of oriented gradients for human detection*. 2005.
|
||||
@@ -1,168 +0,0 @@
|
||||
Arithm Operations on Matrices
|
||||
=============================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::gemm
|
||||
----------
|
||||
Performs generalized matrix multiplication.
|
||||
|
||||
.. ocv:function:: void cuda::gemm(InputArray src1, InputArray src2, double alpha, InputArray src3, double beta, OutputArray dst, int flags = 0, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First multiplied input matrix that should have ``CV_32FC1`` , ``CV_64FC1`` , ``CV_32FC2`` , or ``CV_64FC2`` type.
|
||||
|
||||
:param src2: Second multiplied input matrix of the same type as ``src1`` .
|
||||
|
||||
:param alpha: Weight of the matrix product.
|
||||
|
||||
:param src3: Third optional delta matrix added to the matrix product. It should have the same type as ``src1`` and ``src2`` .
|
||||
|
||||
:param beta: Weight of ``src3`` .
|
||||
|
||||
:param dst: Destination matrix. It has the proper size and the same type as input matrices.
|
||||
|
||||
:param flags: Operation flags:
|
||||
|
||||
* **GEMM_1_T** transpose ``src1``
|
||||
* **GEMM_2_T** transpose ``src2``
|
||||
* **GEMM_3_T** transpose ``src3``
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
The function performs generalized matrix multiplication similar to the ``gemm`` functions in BLAS level 3. For example, ``gemm(src1, src2, alpha, src3, beta, dst, GEMM_1_T + GEMM_3_T)`` corresponds to
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} = \texttt{alpha} \cdot \texttt{src1} ^T \cdot \texttt{src2} + \texttt{beta} \cdot \texttt{src3} ^T
|
||||
|
||||
.. note:: Transposition operation doesn't support ``CV_64FC2`` input type.
|
||||
|
||||
.. seealso:: :ocv:func:`gemm`
|
||||
|
||||
|
||||
|
||||
cuda::mulSpectrums
|
||||
------------------
|
||||
Performs a per-element multiplication of two Fourier spectrums.
|
||||
|
||||
.. ocv:function:: void cuda::mulSpectrums(InputArray src1, InputArray src2, OutputArray dst, int flags, bool conjB=false, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First spectrum.
|
||||
|
||||
:param src2: Second spectrum with the same size and type as ``a`` .
|
||||
|
||||
:param dst: Destination spectrum.
|
||||
|
||||
:param flags: Mock parameter used for CPU/CUDA interfaces similarity, simply add a `0` value.
|
||||
|
||||
:param conjB: Optional flag to specify if the second spectrum needs to be conjugated before the multiplication.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
Only full (not packed) ``CV_32FC2`` complex spectrums in the interleaved format are supported for now.
|
||||
|
||||
.. seealso:: :ocv:func:`mulSpectrums`
|
||||
|
||||
|
||||
|
||||
cuda::mulAndScaleSpectrums
|
||||
--------------------------
|
||||
Performs a per-element multiplication of two Fourier spectrums and scales the result.
|
||||
|
||||
.. ocv:function:: void cuda::mulAndScaleSpectrums(InputArray src1, InputArray src2, OutputArray dst, int flags, float scale, bool conjB=false, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First spectrum.
|
||||
|
||||
:param src2: Second spectrum with the same size and type as ``a`` .
|
||||
|
||||
:param dst: Destination spectrum.
|
||||
|
||||
:param flags: Mock parameter used for CPU/CUDA interfaces similarity.
|
||||
|
||||
:param scale: Scale constant.
|
||||
|
||||
:param conjB: Optional flag to specify if the second spectrum needs to be conjugated before the multiplication.
|
||||
|
||||
Only full (not packed) ``CV_32FC2`` complex spectrums in the interleaved format are supported for now.
|
||||
|
||||
.. seealso:: :ocv:func:`mulSpectrums`
|
||||
|
||||
|
||||
|
||||
cuda::dft
|
||||
---------
|
||||
Performs a forward or inverse discrete Fourier transform (1D or 2D) of the floating point matrix.
|
||||
|
||||
.. ocv:function:: void cuda::dft(InputArray src, OutputArray dst, Size dft_size, int flags=0, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix (real or complex).
|
||||
|
||||
:param dst: Destination matrix (real or complex).
|
||||
|
||||
:param dft_size: Size of a discrete Fourier transform.
|
||||
|
||||
:param flags: Optional flags:
|
||||
|
||||
* **DFT_ROWS** transforms each individual row of the source matrix.
|
||||
|
||||
* **DFT_SCALE** scales the result: divide it by the number of elements in the transform (obtained from ``dft_size`` ).
|
||||
|
||||
* **DFT_INVERSE** inverts DFT. Use for complex-complex cases (real-complex and complex-real cases are always forward and inverse, respectively).
|
||||
|
||||
* **DFT_REAL_OUTPUT** specifies the output as real. The source matrix is the result of real-complex transform, so the destination matrix must be real.
|
||||
|
||||
Use to handle real matrices ( ``CV32FC1`` ) and complex matrices in the interleaved format ( ``CV32FC2`` ).
|
||||
|
||||
The source matrix should be continuous, otherwise reallocation and data copying is performed. The function chooses an operation mode depending on the flags, size, and channel count of the source matrix:
|
||||
|
||||
* If the source matrix is complex and the output is not specified as real, the destination matrix is complex and has the ``dft_size`` size and ``CV_32FC2`` type. The destination matrix contains a full result of the DFT (forward or inverse).
|
||||
|
||||
* If the source matrix is complex and the output is specified as real, the function assumes that its input is the result of the forward transform (see the next item). The destination matrix has the ``dft_size`` size and ``CV_32FC1`` type. It contains the result of the inverse DFT.
|
||||
|
||||
* If the source matrix is real (its type is ``CV_32FC1`` ), forward DFT is performed. The result of the DFT is packed into complex ( ``CV_32FC2`` ) matrix. So, the width of the destination matrix is ``dft_size.width / 2 + 1`` . But if the source is a single column, the height is reduced instead of the width.
|
||||
|
||||
.. seealso:: :ocv:func:`dft`
|
||||
|
||||
|
||||
|
||||
cuda::Convolution
|
||||
-----------------
|
||||
.. ocv:class:: cuda::Convolution : public Algorithm
|
||||
|
||||
Base class for convolution (or cross-correlation) operator. ::
|
||||
|
||||
class CV_EXPORTS Convolution : public Algorithm
|
||||
{
|
||||
public:
|
||||
virtual void convolve(InputArray image, InputArray templ, OutputArray result, bool ccorr = false, Stream& stream = Stream::Null()) = 0;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::Convolution::convolve
|
||||
---------------------------
|
||||
Computes a convolution (or cross-correlation) of two images.
|
||||
|
||||
.. ocv:function:: void cuda::Convolution::convolve(InputArray image, InputArray templ, OutputArray result, bool ccorr = false, Stream& stream = Stream::Null())
|
||||
|
||||
:param image: Source image. Only ``CV_32FC1`` images are supported for now.
|
||||
|
||||
:param templ: Template image. The size is not greater than the ``image`` size. The type is the same as ``image`` .
|
||||
|
||||
:param result: Result image. If ``image`` is *W x H* and ``templ`` is *w x h*, then ``result`` must be *W-w+1 x H-h+1*.
|
||||
|
||||
:param ccorr: Flags to evaluate cross-correlation instead of convolution.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::createConvolution
|
||||
-----------------------
|
||||
Creates implementation for :ocv:class:`cuda::Convolution` .
|
||||
|
||||
.. ocv:function:: Ptr<Convolution> createConvolution(Size user_block_size = Size())
|
||||
|
||||
:param user_block_size: Block size. If you leave default value `Size(0,0)` then automatic estimation of block size will be used (which is optimized for speed). By varying `user_block_size` you can reduce memory requirements at the cost of speed.
|
||||
@@ -1,150 +0,0 @@
|
||||
Core Operations on Matrices
|
||||
===========================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::merge
|
||||
-----------
|
||||
Makes a multi-channel matrix out of several single-channel matrices.
|
||||
|
||||
.. ocv:function:: void cuda::merge(const GpuMat* src, size_t n, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::merge(const std::vector<GpuMat>& src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Array/vector of source matrices.
|
||||
|
||||
:param n: Number of source matrices.
|
||||
|
||||
:param dst: Destination matrix.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`merge`
|
||||
|
||||
|
||||
|
||||
cuda::split
|
||||
-----------
|
||||
Copies each plane of a multi-channel matrix into an array.
|
||||
|
||||
.. ocv:function:: void cuda::split(InputArray src, GpuMat* dst, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::split(InputArray src, vector<GpuMat>& dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix.
|
||||
|
||||
:param dst: Destination array/vector of single-channel matrices.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`split`
|
||||
|
||||
|
||||
|
||||
cuda::transpose
|
||||
---------------
|
||||
Transposes a matrix.
|
||||
|
||||
.. ocv:function:: void cuda::transpose(InputArray src1, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: Source matrix. 1-, 4-, 8-byte element sizes are supported for now.
|
||||
|
||||
:param dst: Destination matrix.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`transpose`
|
||||
|
||||
|
||||
|
||||
cuda::flip
|
||||
----------
|
||||
Flips a 2D matrix around vertical, horizontal, or both axes.
|
||||
|
||||
.. ocv:function:: void cuda::flip(InputArray src, OutputArray dst, int flipCode, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix. Supports 1, 3 and 4 channels images with ``CV_8U``, ``CV_16U``, ``CV_32S`` or ``CV_32F`` depth.
|
||||
|
||||
:param dst: Destination matrix.
|
||||
|
||||
:param flipCode: Flip mode for the source:
|
||||
|
||||
* ``0`` Flips around x-axis.
|
||||
|
||||
* ``> 0`` Flips around y-axis.
|
||||
|
||||
* ``< 0`` Flips around both axes.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`flip`
|
||||
|
||||
|
||||
|
||||
cuda::LookUpTable
|
||||
-----------------
|
||||
.. ocv:class:: cuda::LookUpTable : public Algorithm
|
||||
|
||||
Base class for transform using lookup table. ::
|
||||
|
||||
class CV_EXPORTS LookUpTable : public Algorithm
|
||||
{
|
||||
public:
|
||||
virtual void transform(InputArray src, OutputArray dst, Stream& stream = Stream::Null()) = 0;
|
||||
};
|
||||
|
||||
.. seealso:: :ocv:func:`LUT`
|
||||
|
||||
|
||||
|
||||
cuda::LookUpTable::transform
|
||||
----------------------------
|
||||
Transforms the source matrix into the destination matrix using the given look-up table: ``dst(I) = lut(src(I))`` .
|
||||
|
||||
.. ocv:function:: void cuda::LookUpTable::transform(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix. ``CV_8UC1`` and ``CV_8UC3`` matrices are supported for now.
|
||||
|
||||
:param dst: Destination matrix.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::createLookUpTable
|
||||
-----------------------
|
||||
Creates implementation for :ocv:class:`cuda::LookUpTable` .
|
||||
|
||||
.. ocv:function:: Ptr<LookUpTable> createLookUpTable(InputArray lut)
|
||||
|
||||
:param lut: Look-up table of 256 elements. It is a continuous ``CV_8U`` matrix.
|
||||
|
||||
|
||||
|
||||
cuda::copyMakeBorder
|
||||
--------------------
|
||||
Forms a border around an image.
|
||||
|
||||
.. ocv:function:: void cuda::copyMakeBorder(InputArray src, OutputArray dst, int top, int bottom, int left, int right, int borderType, Scalar value = Scalar(), Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. ``CV_8UC1`` , ``CV_8UC4`` , ``CV_32SC1`` , and ``CV_32FC1`` types are supported.
|
||||
|
||||
:param dst: Destination image with the same type as ``src``. The size is ``Size(src.cols+left+right, src.rows+top+bottom)`` .
|
||||
|
||||
:param top:
|
||||
|
||||
:param bottom:
|
||||
|
||||
:param left:
|
||||
|
||||
:param right: Number of pixels in each direction from the source image rectangle to extrapolate. For example: ``top=1, bottom=1, left=1, right=1`` mean that 1 pixel-wide border needs to be built.
|
||||
|
||||
:param borderType: Border type. See :ocv:func:`borderInterpolate` for details. ``BORDER_REFLECT101`` , ``BORDER_REPLICATE`` , ``BORDER_CONSTANT`` , ``BORDER_REFLECT`` and ``BORDER_WRAP`` are supported for now.
|
||||
|
||||
:param value: Border value.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`copyMakeBorder`
|
||||
@@ -1,11 +0,0 @@
|
||||
***************************************************
|
||||
cudaarithm. CUDA-accelerated Operations on Matrices
|
||||
***************************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
core
|
||||
element_operations
|
||||
reductions
|
||||
arithm
|
||||
@@ -1,543 +0,0 @@
|
||||
Per-element Operations
|
||||
======================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::add
|
||||
---------
|
||||
Computes a matrix-matrix or matrix-scalar sum.
|
||||
|
||||
.. ocv:function:: void cuda::add(InputArray src1, InputArray src2, OutputArray dst, InputArray mask = noArray(), int dtype = -1, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar. Matrix should have the same size and type as ``src1`` .
|
||||
|
||||
:param dst: Destination matrix that has the same size and number of channels as the input array(s). The depth is defined by ``dtype`` or ``src1`` depth.
|
||||
|
||||
:param mask: Optional operation mask, 8-bit single channel array, that specifies elements of the destination array to be changed.
|
||||
|
||||
:param dtype: Optional depth of the output array.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`add`
|
||||
|
||||
|
||||
|
||||
cuda::subtract
|
||||
--------------
|
||||
Computes a matrix-matrix or matrix-scalar difference.
|
||||
|
||||
.. ocv:function:: void cuda::subtract(InputArray src1, InputArray src2, OutputArray dst, InputArray mask = noArray(), int dtype = -1, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar. Matrix should have the same size and type as ``src1`` .
|
||||
|
||||
:param dst: Destination matrix that has the same size and number of channels as the input array(s). The depth is defined by ``dtype`` or ``src1`` depth.
|
||||
|
||||
:param mask: Optional operation mask, 8-bit single channel array, that specifies elements of the destination array to be changed.
|
||||
|
||||
:param dtype: Optional depth of the output array.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`subtract`
|
||||
|
||||
|
||||
|
||||
cuda::multiply
|
||||
--------------
|
||||
Computes a matrix-matrix or matrix-scalar per-element product.
|
||||
|
||||
.. ocv:function:: void cuda::multiply(InputArray src1, InputArray src2, OutputArray dst, double scale = 1, int dtype = -1, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar.
|
||||
|
||||
:param dst: Destination matrix that has the same size and number of channels as the input array(s). The depth is defined by ``dtype`` or ``src1`` depth.
|
||||
|
||||
:param scale: Optional scale factor.
|
||||
|
||||
:param dtype: Optional depth of the output array.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`multiply`
|
||||
|
||||
|
||||
|
||||
cuda::divide
|
||||
------------
|
||||
Computes a matrix-matrix or matrix-scalar division.
|
||||
|
||||
.. ocv:function:: void cuda::divide(InputArray src1, InputArray src2, OutputArray dst, double scale = 1, int dtype = -1, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::divide(double src1, InputArray src2, OutputArray dst, int dtype = -1, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or a scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar.
|
||||
|
||||
:param dst: Destination matrix that has the same size and number of channels as the input array(s). The depth is defined by ``dtype`` or ``src1`` depth.
|
||||
|
||||
:param scale: Optional scale factor.
|
||||
|
||||
:param dtype: Optional depth of the output array.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
This function, in contrast to :ocv:func:`divide`, uses a round-down rounding mode.
|
||||
|
||||
.. seealso:: :ocv:func:`divide`
|
||||
|
||||
|
||||
|
||||
cuda::absdiff
|
||||
-------------
|
||||
Computes per-element absolute difference of two matrices (or of a matrix and scalar).
|
||||
|
||||
.. ocv:function:: void cuda::absdiff(InputArray src1, InputArray src2, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar.
|
||||
|
||||
:param dst: Destination matrix that has the same size and type as the input array(s).
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`absdiff`
|
||||
|
||||
|
||||
|
||||
cuda::abs
|
||||
---------
|
||||
Computes an absolute value of each matrix element.
|
||||
|
||||
.. ocv:function:: void cuda::abs(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix.
|
||||
|
||||
:param dst: Destination matrix with the same size and type as ``src`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`abs`
|
||||
|
||||
|
||||
|
||||
cuda::sqr
|
||||
---------
|
||||
Computes a square value of each matrix element.
|
||||
|
||||
.. ocv:function:: void cuda::sqr(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix.
|
||||
|
||||
:param dst: Destination matrix with the same size and type as ``src`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::sqrt
|
||||
----------
|
||||
Computes a square root of each matrix element.
|
||||
|
||||
.. ocv:function:: void cuda::sqrt(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix.
|
||||
|
||||
:param dst: Destination matrix with the same size and type as ``src`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`sqrt`
|
||||
|
||||
|
||||
|
||||
cuda::exp
|
||||
---------
|
||||
Computes an exponent of each matrix element.
|
||||
|
||||
.. ocv:function:: void cuda::exp(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix.
|
||||
|
||||
:param dst: Destination matrix with the same size and type as ``src`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`exp`
|
||||
|
||||
|
||||
|
||||
cuda::log
|
||||
---------
|
||||
Computes a natural logarithm of absolute value of each matrix element.
|
||||
|
||||
.. ocv:function:: void cuda::log(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix.
|
||||
|
||||
:param dst: Destination matrix with the same size and type as ``src`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`log`
|
||||
|
||||
|
||||
|
||||
cuda::pow
|
||||
---------
|
||||
Raises every matrix element to a power.
|
||||
|
||||
.. ocv:function:: void cuda::pow(InputArray src, double power, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix.
|
||||
|
||||
:param power: Exponent of power.
|
||||
|
||||
:param dst: Destination matrix with the same size and type as ``src`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
The function ``pow`` raises every element of the input matrix to ``power`` :
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (I) = \fork{\texttt{src}(I)^power}{if \texttt{power} is integer}{|\texttt{src}(I)|^power}{otherwise}
|
||||
|
||||
.. seealso:: :ocv:func:`pow`
|
||||
|
||||
|
||||
|
||||
cuda::compare
|
||||
-------------
|
||||
Compares elements of two matrices (or of a matrix and scalar).
|
||||
|
||||
.. ocv:function:: void cuda::compare(InputArray src1, InputArray src2, OutputArray dst, int cmpop, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar.
|
||||
|
||||
:param dst: Destination matrix that has the same size and type as the input array(s).
|
||||
|
||||
:param cmpop: Flag specifying the relation between the elements to be checked:
|
||||
|
||||
* **CMP_EQ:** ``a(.) == b(.)``
|
||||
* **CMP_GT:** ``a(.) < b(.)``
|
||||
* **CMP_GE:** ``a(.) <= b(.)``
|
||||
* **CMP_LT:** ``a(.) < b(.)``
|
||||
* **CMP_LE:** ``a(.) <= b(.)``
|
||||
* **CMP_NE:** ``a(.) != b(.)``
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`compare`
|
||||
|
||||
|
||||
|
||||
cuda::bitwise_not
|
||||
-----------------
|
||||
Performs a per-element bitwise inversion.
|
||||
|
||||
.. ocv:function:: void cuda::bitwise_not(InputArray src, OutputArray dst, InputArray mask = noArray(), Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix.
|
||||
|
||||
:param dst: Destination matrix with the same size and type as ``src`` .
|
||||
|
||||
:param mask: Optional operation mask. 8-bit single channel image.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::bitwise_or
|
||||
----------------
|
||||
Performs a per-element bitwise disjunction of two matrices (or of matrix and scalar).
|
||||
|
||||
.. ocv:function:: void cuda::bitwise_or(InputArray src1, InputArray src2, OutputArray dst, InputArray mask = noArray(), Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar.
|
||||
|
||||
:param dst: Destination matrix that has the same size and type as the input array(s).
|
||||
|
||||
:param mask: Optional operation mask. 8-bit single channel image.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::bitwise_and
|
||||
-----------------
|
||||
Performs a per-element bitwise conjunction of two matrices (or of matrix and scalar).
|
||||
|
||||
.. ocv:function:: void cuda::bitwise_and(InputArray src1, InputArray src2, OutputArray dst, InputArray mask = noArray(), Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar.
|
||||
|
||||
:param dst: Destination matrix that has the same size and type as the input array(s).
|
||||
|
||||
:param mask: Optional operation mask. 8-bit single channel image.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::bitwise_xor
|
||||
-----------------
|
||||
Performs a per-element bitwise ``exclusive or`` operation of two matrices (or of matrix and scalar).
|
||||
|
||||
.. ocv:function:: void cuda::bitwise_xor(InputArray src1, InputArray src2, OutputArray dst, InputArray mask = noArray(), Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar.
|
||||
|
||||
:param dst: Destination matrix that has the same size and type as the input array(s).
|
||||
|
||||
:param mask: Optional operation mask. 8-bit single channel image.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::rshift
|
||||
------------
|
||||
Performs pixel by pixel right shift of an image by a constant value.
|
||||
|
||||
.. ocv:function:: void cuda::rshift(InputArray src, Scalar_<int> val, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix. Supports 1, 3 and 4 channels images with integers elements.
|
||||
|
||||
:param val: Constant values, one per channel.
|
||||
|
||||
:param dst: Destination matrix with the same size and type as ``src`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::lshift
|
||||
------------
|
||||
Performs pixel by pixel right left of an image by a constant value.
|
||||
|
||||
.. ocv:function:: void cuda::lshift(InputArray src, Scalar_<int> val, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source matrix. Supports 1, 3 and 4 channels images with ``CV_8U`` , ``CV_16U`` or ``CV_32S`` depth.
|
||||
|
||||
:param val: Constant values, one per channel.
|
||||
|
||||
:param dst: Destination matrix with the same size and type as ``src`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::min
|
||||
---------
|
||||
Computes the per-element minimum of two matrices (or a matrix and a scalar).
|
||||
|
||||
.. ocv:function:: void cuda::min(InputArray src1, InputArray src2, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar.
|
||||
|
||||
:param dst: Destination matrix that has the same size and type as the input array(s).
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`min`
|
||||
|
||||
|
||||
|
||||
cuda::max
|
||||
---------
|
||||
Computes the per-element maximum of two matrices (or a matrix and a scalar).
|
||||
|
||||
.. ocv:function:: void cuda::max(InputArray src1, InputArray src2, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source matrix or scalar.
|
||||
|
||||
:param src2: Second source matrix or scalar.
|
||||
|
||||
:param dst: Destination matrix that has the same size and type as the input array(s).
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`max`
|
||||
|
||||
|
||||
|
||||
cuda::addWeighted
|
||||
-----------------
|
||||
Computes the weighted sum of two arrays.
|
||||
|
||||
.. ocv:function:: void cuda::addWeighted(InputArray src1, double alpha, InputArray src2, double beta, double gamma, OutputArray dst, int dtype = -1, Stream& stream = Stream::Null())
|
||||
|
||||
:param src1: First source array.
|
||||
|
||||
:param alpha: Weight for the first array elements.
|
||||
|
||||
:param src2: Second source array of the same size and channel number as ``src1`` .
|
||||
|
||||
:param beta: Weight for the second array elements.
|
||||
|
||||
:param dst: Destination array that has the same size and number of channels as the input arrays.
|
||||
|
||||
:param gamma: Scalar added to each sum.
|
||||
|
||||
:param dtype: Optional depth of the destination array. When both input arrays have the same depth, ``dtype`` can be set to ``-1``, which will be equivalent to ``src1.depth()``.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
The function ``addWeighted`` calculates the weighted sum of two arrays as follows:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (I)= \texttt{saturate} ( \texttt{src1} (I)* \texttt{alpha} + \texttt{src2} (I)* \texttt{beta} + \texttt{gamma} )
|
||||
|
||||
where ``I`` is a multi-dimensional index of array elements. In case of multi-channel arrays, each channel is processed independently.
|
||||
|
||||
.. seealso:: :ocv:func:`addWeighted`
|
||||
|
||||
|
||||
|
||||
cuda::threshold
|
||||
---------------
|
||||
Applies a fixed-level threshold to each array element.
|
||||
|
||||
.. ocv:function:: double cuda::threshold(InputArray src, OutputArray dst, double thresh, double maxval, int type, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source array (single-channel).
|
||||
|
||||
:param dst: Destination array with the same size and type as ``src`` .
|
||||
|
||||
:param thresh: Threshold value.
|
||||
|
||||
:param maxval: Maximum value to use with ``THRESH_BINARY`` and ``THRESH_BINARY_INV`` threshold types.
|
||||
|
||||
:param type: Threshold type. For details, see :ocv:func:`threshold` . The ``THRESH_OTSU`` and ``THRESH_TRIANGLE`` threshold types are not supported.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`threshold`
|
||||
|
||||
|
||||
|
||||
cuda::magnitude
|
||||
---------------
|
||||
Computes magnitudes of complex matrix elements.
|
||||
|
||||
.. ocv:function:: void cuda::magnitude(InputArray xy, OutputArray magnitude, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::magnitude(InputArray x, InputArray y, OutputArray magnitude, Stream& stream = Stream::Null())
|
||||
|
||||
:param xy: Source complex matrix in the interleaved format ( ``CV_32FC2`` ).
|
||||
|
||||
:param x: Source matrix containing real components ( ``CV_32FC1`` ).
|
||||
|
||||
:param y: Source matrix containing imaginary components ( ``CV_32FC1`` ).
|
||||
|
||||
:param magnitude: Destination matrix of float magnitudes ( ``CV_32FC1`` ).
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`magnitude`
|
||||
|
||||
|
||||
|
||||
cuda::magnitudeSqr
|
||||
------------------
|
||||
Computes squared magnitudes of complex matrix elements.
|
||||
|
||||
.. ocv:function:: void cuda::magnitudeSqr(InputArray xy, OutputArray magnitude, Stream& stream=Stream::Null() )
|
||||
|
||||
.. ocv:function:: void cuda::magnitudeSqr(InputArray x, InputArray y, OutputArray magnitude, Stream& stream = Stream::Null())
|
||||
|
||||
:param xy: Source complex matrix in the interleaved format ( ``CV_32FC2`` ).
|
||||
|
||||
:param x: Source matrix containing real components ( ``CV_32FC1`` ).
|
||||
|
||||
:param y: Source matrix containing imaginary components ( ``CV_32FC1`` ).
|
||||
|
||||
:param magnitude: Destination matrix of float magnitude squares ( ``CV_32FC1`` ).
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::phase
|
||||
-----------
|
||||
Computes polar angles of complex matrix elements.
|
||||
|
||||
.. ocv:function:: void cuda::phase(InputArray x, InputArray y, OutputArray angle, bool angleInDegrees = false, Stream& stream = Stream::Null())
|
||||
|
||||
:param x: Source matrix containing real components ( ``CV_32FC1`` ).
|
||||
|
||||
:param y: Source matrix containing imaginary components ( ``CV_32FC1`` ).
|
||||
|
||||
:param angle: Destination matrix of angles ( ``CV_32FC1`` ).
|
||||
|
||||
:param angleInDegrees: Flag for angles that must be evaluated in degrees.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`phase`
|
||||
|
||||
|
||||
|
||||
cuda::cartToPolar
|
||||
-----------------
|
||||
Converts Cartesian coordinates into polar.
|
||||
|
||||
.. ocv:function:: void cuda::cartToPolar(InputArray x, InputArray y, OutputArray magnitude, OutputArray angle, bool angleInDegrees = false, Stream& stream = Stream::Null())
|
||||
|
||||
:param x: Source matrix containing real components ( ``CV_32FC1`` ).
|
||||
|
||||
:param y: Source matrix containing imaginary components ( ``CV_32FC1`` ).
|
||||
|
||||
:param magnitude: Destination matrix of float magnitudes ( ``CV_32FC1`` ).
|
||||
|
||||
:param angle: Destination matrix of angles ( ``CV_32FC1`` ).
|
||||
|
||||
:param angleInDegrees: Flag for angles that must be evaluated in degrees.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`cartToPolar`
|
||||
|
||||
|
||||
|
||||
cuda::polarToCart
|
||||
-----------------
|
||||
Converts polar coordinates into Cartesian.
|
||||
|
||||
.. ocv:function:: void cuda::polarToCart(InputArray magnitude, InputArray angle, OutputArray x, OutputArray y, bool angleInDegrees = false, Stream& stream = Stream::Null())
|
||||
|
||||
:param magnitude: Source matrix containing magnitudes ( ``CV_32FC1`` ).
|
||||
|
||||
:param angle: Source matrix containing angles ( ``CV_32FC1`` ).
|
||||
|
||||
:param x: Destination matrix of real components ( ``CV_32FC1`` ).
|
||||
|
||||
:param y: Destination matrix of imaginary components ( ``CV_32FC1`` ).
|
||||
|
||||
:param angleInDegrees: Flag that indicates angles in degrees.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`polarToCart`
|
||||
@@ -1,295 +0,0 @@
|
||||
Matrix Reductions
|
||||
=================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::norm
|
||||
----------
|
||||
Returns the norm of a matrix (or difference of two matrices).
|
||||
|
||||
.. ocv:function:: double cuda::norm(InputArray src1, int normType)
|
||||
|
||||
.. ocv:function:: double cuda::norm(InputArray src1, int normType, GpuMat& buf)
|
||||
|
||||
.. ocv:function:: double cuda::norm(InputArray src1, int normType, InputArray mask, GpuMat& buf)
|
||||
|
||||
.. ocv:function:: double cuda::norm(InputArray src1, InputArray src2, int normType=NORM_L2)
|
||||
|
||||
:param src1: Source matrix. Any matrices except 64F are supported.
|
||||
|
||||
:param src2: Second source matrix (if any) with the same size and type as ``src1``.
|
||||
|
||||
:param normType: Norm type. ``NORM_L1`` , ``NORM_L2`` , and ``NORM_INF`` are supported for now.
|
||||
|
||||
:param mask: optional operation mask; it must have the same size as ``src1`` and ``CV_8UC1`` type.
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
.. seealso:: :ocv:func:`norm`
|
||||
|
||||
|
||||
|
||||
cuda::sum
|
||||
---------
|
||||
Returns the sum of matrix elements.
|
||||
|
||||
.. ocv:function:: Scalar cuda::sum(InputArray src)
|
||||
|
||||
.. ocv:function:: Scalar cuda::sum(InputArray src, GpuMat& buf)
|
||||
|
||||
.. ocv:function:: Scalar cuda::sum(InputArray src, InputArray mask, GpuMat& buf)
|
||||
|
||||
:param src: Source image of any depth except for ``CV_64F`` .
|
||||
|
||||
:param mask: optional operation mask; it must have the same size as ``src1`` and ``CV_8UC1`` type.
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
.. seealso:: :ocv:func:`sum`
|
||||
|
||||
|
||||
|
||||
cuda::absSum
|
||||
------------
|
||||
Returns the sum of absolute values for matrix elements.
|
||||
|
||||
.. ocv:function:: Scalar cuda::absSum(InputArray src)
|
||||
|
||||
.. ocv:function:: Scalar cuda::absSum(InputArray src, GpuMat& buf)
|
||||
|
||||
.. ocv:function:: Scalar cuda::absSum(InputArray src, InputArray mask, GpuMat& buf)
|
||||
|
||||
:param src: Source image of any depth except for ``CV_64F`` .
|
||||
|
||||
:param mask: optional operation mask; it must have the same size as ``src1`` and ``CV_8UC1`` type.
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
|
||||
|
||||
cuda::sqrSum
|
||||
------------
|
||||
Returns the squared sum of matrix elements.
|
||||
|
||||
.. ocv:function:: Scalar cuda::sqrSum(InputArray src)
|
||||
|
||||
.. ocv:function:: Scalar cuda::sqrSum(InputArray src, GpuMat& buf)
|
||||
|
||||
.. ocv:function:: Scalar cuda::sqrSum(InputArray src, InputArray mask, GpuMat& buf)
|
||||
|
||||
:param src: Source image of any depth except for ``CV_64F`` .
|
||||
|
||||
:param mask: optional operation mask; it must have the same size as ``src1`` and ``CV_8UC1`` type.
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
|
||||
|
||||
cuda::minMax
|
||||
------------
|
||||
Finds global minimum and maximum matrix elements and returns their values.
|
||||
|
||||
.. ocv:function:: void cuda::minMax(InputArray src, double* minVal, double* maxVal=0, InputArray mask=noArray())
|
||||
|
||||
.. ocv:function:: void cuda::minMax(InputArray src, double* minVal, double* maxVal, InputArray mask, GpuMat& buf)
|
||||
|
||||
:param src: Single-channel source image.
|
||||
|
||||
:param minVal: Pointer to the returned minimum value. Use ``NULL`` if not required.
|
||||
|
||||
:param maxVal: Pointer to the returned maximum value. Use ``NULL`` if not required.
|
||||
|
||||
:param mask: Optional mask to select a sub-matrix.
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
The function does not work with ``CV_64F`` images on GPUs with the compute capability < 1.3.
|
||||
|
||||
.. seealso:: :ocv:func:`minMaxLoc`
|
||||
|
||||
|
||||
|
||||
cuda::minMaxLoc
|
||||
---------------
|
||||
Finds global minimum and maximum matrix elements and returns their values with locations.
|
||||
|
||||
.. ocv:function:: void cuda::minMaxLoc(InputArray src, double* minVal, double* maxVal=0, Point* minLoc=0, Point* maxLoc=0, InputArray mask=noArray())
|
||||
|
||||
.. ocv:function:: void cuda::minMaxLoc(InputArray src, double* minVal, double* maxVal, Point* minLoc, Point* maxLoc, InputArray mask, GpuMat& valbuf, GpuMat& locbuf)
|
||||
|
||||
:param src: Single-channel source image.
|
||||
|
||||
:param minVal: Pointer to the returned minimum value. Use ``NULL`` if not required.
|
||||
|
||||
:param maxVal: Pointer to the returned maximum value. Use ``NULL`` if not required.
|
||||
|
||||
:param minLoc: Pointer to the returned minimum location. Use ``NULL`` if not required.
|
||||
|
||||
:param maxLoc: Pointer to the returned maximum location. Use ``NULL`` if not required.
|
||||
|
||||
:param mask: Optional mask to select a sub-matrix.
|
||||
|
||||
:param valbuf: Optional values buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
:param locbuf: Optional locations buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
The function does not work with ``CV_64F`` images on GPU with the compute capability < 1.3.
|
||||
|
||||
.. seealso:: :ocv:func:`minMaxLoc`
|
||||
|
||||
|
||||
|
||||
cuda::countNonZero
|
||||
------------------
|
||||
Counts non-zero matrix elements.
|
||||
|
||||
.. ocv:function:: int cuda::countNonZero(InputArray src)
|
||||
|
||||
.. ocv:function:: int cuda::countNonZero(InputArray src, GpuMat& buf)
|
||||
|
||||
:param src: Single-channel source image.
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
The function does not work with ``CV_64F`` images on GPUs with the compute capability < 1.3.
|
||||
|
||||
.. seealso:: :ocv:func:`countNonZero`
|
||||
|
||||
|
||||
|
||||
cuda::reduce
|
||||
------------
|
||||
Reduces a matrix to a vector.
|
||||
|
||||
.. ocv:function:: void cuda::reduce(InputArray mtx, OutputArray vec, int dim, int reduceOp, int dtype = -1, Stream& stream = Stream::Null())
|
||||
|
||||
:param mtx: Source 2D matrix.
|
||||
|
||||
:param vec: Destination vector. Its size and type is defined by ``dim`` and ``dtype`` parameters.
|
||||
|
||||
:param dim: Dimension index along which the matrix is reduced. 0 means that the matrix is reduced to a single row. 1 means that the matrix is reduced to a single column.
|
||||
|
||||
:param reduceOp: Reduction operation that could be one of the following:
|
||||
|
||||
* **CV_REDUCE_SUM** The output is the sum of all rows/columns of the matrix.
|
||||
|
||||
* **CV_REDUCE_AVG** The output is the mean vector of all rows/columns of the matrix.
|
||||
|
||||
* **CV_REDUCE_MAX** The output is the maximum (column/row-wise) of all rows/columns of the matrix.
|
||||
|
||||
* **CV_REDUCE_MIN** The output is the minimum (column/row-wise) of all rows/columns of the matrix.
|
||||
|
||||
:param dtype: When it is negative, the destination vector will have the same type as the source matrix. Otherwise, its type will be ``CV_MAKE_TYPE(CV_MAT_DEPTH(dtype), mtx.channels())`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
The function ``reduce`` reduces the matrix to a vector by treating the matrix rows/columns as a set of 1D vectors and performing the specified operation on the vectors until a single row/column is obtained. For example, the function can be used to compute horizontal and vertical projections of a raster image. In case of ``CV_REDUCE_SUM`` and ``CV_REDUCE_AVG`` , the output may have a larger element bit-depth to preserve accuracy. And multi-channel arrays are also supported in these two reduction modes.
|
||||
|
||||
.. seealso:: :ocv:func:`reduce`
|
||||
|
||||
|
||||
|
||||
cuda::meanStdDev
|
||||
----------------
|
||||
Computes a mean value and a standard deviation of matrix elements.
|
||||
|
||||
.. ocv:function:: void cuda::meanStdDev(InputArray mtx, Scalar& mean, Scalar& stddev)
|
||||
.. ocv:function:: void cuda::meanStdDev(InputArray mtx, Scalar& mean, Scalar& stddev, GpuMat& buf)
|
||||
|
||||
:param mtx: Source matrix. ``CV_8UC1`` matrices are supported for now.
|
||||
|
||||
:param mean: Mean value.
|
||||
|
||||
:param stddev: Standard deviation value.
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
.. seealso:: :ocv:func:`meanStdDev`
|
||||
|
||||
|
||||
|
||||
cuda::rectStdDev
|
||||
----------------
|
||||
Computes a standard deviation of integral images.
|
||||
|
||||
.. ocv:function:: void cuda::rectStdDev(InputArray src, InputArray sqr, OutputArray dst, Rect rect, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. Only the ``CV_32SC1`` type is supported.
|
||||
|
||||
:param sqr: Squared source image. Only the ``CV_32FC1`` type is supported.
|
||||
|
||||
:param dst: Destination image with the same type and size as ``src`` .
|
||||
|
||||
:param rect: Rectangular window.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::normalize
|
||||
---------------
|
||||
Normalizes the norm or value range of an array.
|
||||
|
||||
.. ocv:function:: void cuda::normalize(InputArray src, OutputArray dst, double alpha = 1, double beta = 0, int norm_type = NORM_L2, int dtype = -1, InputArray mask = noArray())
|
||||
|
||||
.. ocv:function:: void cuda::normalize(InputArray src, OutputArray dst, double alpha, double beta, int norm_type, int dtype, InputArray mask, GpuMat& norm_buf, GpuMat& cvt_buf)
|
||||
|
||||
:param src: Input array.
|
||||
|
||||
:param dst: Output array of the same size as ``src`` .
|
||||
|
||||
:param alpha: Norm value to normalize to or the lower range boundary in case of the range normalization.
|
||||
|
||||
:param beta: Upper range boundary in case of the range normalization; it is not used for the norm normalization.
|
||||
|
||||
:param normType: Normalization type ( ``NORM_MINMAX`` , ``NORM_L2`` , ``NORM_L1`` or ``NORM_INF`` ).
|
||||
|
||||
:param dtype: When negative, the output array has the same type as ``src``; otherwise, it has the same number of channels as ``src`` and the depth ``=CV_MAT_DEPTH(dtype)``.
|
||||
|
||||
:param mask: Optional operation mask.
|
||||
|
||||
:param norm_buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
:param cvt_buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
.. seealso:: :ocv:func:`normalize`
|
||||
|
||||
|
||||
|
||||
cuda::integral
|
||||
--------------
|
||||
Computes an integral image.
|
||||
|
||||
.. ocv:function:: void cuda::integral(InputArray src, OutputArray sum, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::integral(InputArray src, OutputArray sum, GpuMat& buffer, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. Only ``CV_8UC1`` images are supported for now.
|
||||
|
||||
:param sum: Integral image containing 32-bit unsigned integer values packed into ``CV_32SC1`` .
|
||||
|
||||
:param buffer: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`integral`
|
||||
|
||||
|
||||
|
||||
cuda::sqrIntegral
|
||||
-----------------
|
||||
Computes a squared integral image.
|
||||
|
||||
.. ocv:function:: void cuda::sqrIntegral(InputArray src, OutputArray sqsum, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::sqrIntegral(InputArray src, OutputArray sqsum, GpuMat& buf, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. Only ``CV_8UC1`` images are supported for now.
|
||||
|
||||
:param sqsum: Squared integral image containing 64-bit unsigned integer values packed into ``CV_64FC1`` .
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations. It is resized automatically.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
@@ -1,128 +0,0 @@
|
||||
Background Segmentation
|
||||
=======================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::BackgroundSubtractorMOG
|
||||
-----------------------------
|
||||
Gaussian Mixture-based Background/Foreground Segmentation Algorithm.
|
||||
|
||||
.. ocv:class:: cuda::BackgroundSubtractorMOG : public cv::BackgroundSubtractorMOG
|
||||
|
||||
The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [MOG2001]_.
|
||||
|
||||
.. seealso:: :ocv:class:`BackgroundSubtractorMOG`
|
||||
|
||||
.. note::
|
||||
|
||||
* An example on gaussian mixture based background/foreground segmantation can be found at opencv_source_code/samples/gpu/bgfg_segm.cpp
|
||||
|
||||
|
||||
|
||||
cuda::createBackgroundSubtractorMOG
|
||||
-----------------------------------
|
||||
Creates mixture-of-gaussian background subtractor
|
||||
|
||||
.. ocv:function:: Ptr<cuda::BackgroundSubtractorMOG> cuda::createBackgroundSubtractorMOG(int history=200, int nmixtures=5, double backgroundRatio=0.7, double noiseSigma=0)
|
||||
|
||||
:param history: Length of the history.
|
||||
|
||||
:param nmixtures: Number of Gaussian mixtures.
|
||||
|
||||
:param backgroundRatio: Background ratio.
|
||||
|
||||
:param noiseSigma: Noise strength (standard deviation of the brightness or each color channel). 0 means some automatic value.
|
||||
|
||||
|
||||
|
||||
cuda::BackgroundSubtractorMOG2
|
||||
------------------------------
|
||||
Gaussian Mixture-based Background/Foreground Segmentation Algorithm.
|
||||
|
||||
.. ocv:class:: cuda::BackgroundSubtractorMOG2 : public cv::BackgroundSubtractorMOG2
|
||||
|
||||
The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [MOG2004]_.
|
||||
|
||||
.. seealso:: :ocv:class:`BackgroundSubtractorMOG2`
|
||||
|
||||
|
||||
|
||||
cuda::createBackgroundSubtractorMOG2
|
||||
------------------------------------
|
||||
Creates MOG2 Background Subtractor
|
||||
|
||||
.. ocv:function:: Ptr<cuda::BackgroundSubtractorMOG2> cuda::createBackgroundSubtractorMOG2( int history=500, double varThreshold=16, bool detectShadows=true )
|
||||
|
||||
:param history: Length of the history.
|
||||
|
||||
:param varThreshold: Threshold on the squared Mahalanobis distance between the pixel and the model to decide whether a pixel is well described by the background model. This parameter does not affect the background update.
|
||||
|
||||
:param detectShadows: If true, the algorithm will detect shadows and mark them. It decreases the speed a bit, so if you do not need this feature, set the parameter to false.
|
||||
|
||||
|
||||
|
||||
cuda::BackgroundSubtractorGMG
|
||||
-----------------------------
|
||||
Background/Foreground Segmentation Algorithm.
|
||||
|
||||
.. ocv:class:: cuda::BackgroundSubtractorGMG : public cv::BackgroundSubtractorGMG
|
||||
|
||||
The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [GMG2012]_.
|
||||
|
||||
|
||||
|
||||
cuda::createBackgroundSubtractorGMG
|
||||
-----------------------------------
|
||||
Creates GMG Background Subtractor
|
||||
|
||||
.. ocv:function:: Ptr<cuda::BackgroundSubtractorGMG> cuda::createBackgroundSubtractorGMG(int initializationFrames = 120, double decisionThreshold = 0.8)
|
||||
|
||||
:param initializationFrames: Number of frames of video to use to initialize histograms.
|
||||
|
||||
:param decisionThreshold: Value above which pixel is determined to be FG.
|
||||
|
||||
|
||||
|
||||
cuda::BackgroundSubtractorFGD
|
||||
-----------------------------
|
||||
|
||||
.. ocv:class:: cuda::BackgroundSubtractorFGD : public cv::BackgroundSubtractor
|
||||
|
||||
The class discriminates between foreground and background pixels by building and maintaining a model of the background. Any pixel which does not fit this model is then deemed to be foreground. The class implements algorithm described in [FGD2003]_. ::
|
||||
|
||||
class CV_EXPORTS BackgroundSubtractorFGD : public cv::BackgroundSubtractor
|
||||
{
|
||||
public:
|
||||
virtual void getForegroundRegions(OutputArrayOfArrays foreground_regions) = 0;
|
||||
};
|
||||
|
||||
.. seealso:: :ocv:class:`BackgroundSubtractor`
|
||||
|
||||
|
||||
|
||||
cuda::BackgroundSubtractorFGD::getForegroundRegions
|
||||
---------------------------------------------------
|
||||
Returns the output foreground regions calculated by :ocv:func:`findContours`.
|
||||
|
||||
.. ocv:function:: void cuda::BackgroundSubtractorFGD::getForegroundRegions(OutputArrayOfArrays foreground_regions)
|
||||
|
||||
:params foreground_regions: Output array (CPU memory).
|
||||
|
||||
|
||||
|
||||
cuda::createBackgroundSubtractorFGD
|
||||
-----------------------------------
|
||||
Creates FGD Background Subtractor
|
||||
|
||||
.. ocv:function:: Ptr<cuda::BackgroundSubtractorGMG> cuda::createBackgroundSubtractorFGD(const FGDParams& params = FGDParams())
|
||||
|
||||
:param params: Algorithm's parameters. See [FGD2003]_ for explanation.
|
||||
|
||||
|
||||
|
||||
.. [FGD2003] Liyuan Li, Weimin Huang, Irene Y.H. Gu, and Qi Tian. *Foreground Object Detection from Videos Containing Complex Background*. ACM MM2003 9p, 2003.
|
||||
.. [MOG2001] P. KadewTraKuPong and R. Bowden. *An improved adaptive background mixture model for real-time tracking with shadow detection*. Proc. 2nd European Workshop on Advanced Video-Based Surveillance Systems, 2001
|
||||
.. [MOG2004] Z. Zivkovic. *Improved adaptive Gausian mixture model for background subtraction*. International Conference Pattern Recognition, UK, August, 2004
|
||||
.. [GMG2012] A. Godbehere, A. Matsukawa and K. Goldberg. *Visual Tracking of Human Visitors under Variable-Lighting Conditions for a Responsive Audio Art Installation*. American Control Conference, Montreal, June 2012
|
||||
@@ -1,8 +0,0 @@
|
||||
****************************************************
|
||||
cudabgsegm. CUDA-accelerated Background Segmentation
|
||||
****************************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
background_segmentation
|
||||
@@ -1,9 +0,0 @@
|
||||
***************************************************
|
||||
cudacodec. CUDA-accelerated Video Encoding/Decoding
|
||||
***************************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
videodec
|
||||
videoenc
|
||||
@@ -1,156 +0,0 @@
|
||||
Video Decoding
|
||||
==============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cudacodec::VideoReader
|
||||
----------------------
|
||||
Video reader interface.
|
||||
|
||||
.. ocv:class:: cudacodec::VideoReader
|
||||
|
||||
.. note::
|
||||
|
||||
* An example on how to use the videoReader class can be found at opencv_source_code/samples/gpu/video_reader.cpp
|
||||
|
||||
|
||||
cudacodec::VideoReader::nextFrame
|
||||
---------------------------------
|
||||
Grabs, decodes and returns the next video frame.
|
||||
|
||||
.. ocv:function:: bool cudacodec::VideoReader::nextFrame(OutputArray frame)
|
||||
|
||||
If no frames has been grabbed (there are no more frames in video file), the methods return ``false`` . The method throws :ocv:class:`Exception` if error occurs.
|
||||
|
||||
|
||||
|
||||
cudacodec::VideoReader::format
|
||||
------------------------------
|
||||
Returns information about video file format.
|
||||
|
||||
.. ocv:function:: FormatInfo cudacodec::VideoReader::format() const
|
||||
|
||||
|
||||
|
||||
cudacodec::Codec
|
||||
----------------
|
||||
Video codecs supported by :ocv:class:`cudacodec::VideoReader` .
|
||||
|
||||
.. ocv:enum:: cudacodec::Codec
|
||||
|
||||
.. ocv:emember:: MPEG1 = 0
|
||||
.. ocv:emember:: MPEG2
|
||||
.. ocv:emember:: MPEG4
|
||||
.. ocv:emember:: VC1
|
||||
.. ocv:emember:: H264
|
||||
.. ocv:emember:: JPEG
|
||||
.. ocv:emember:: H264_SVC
|
||||
.. ocv:emember:: H264_MVC
|
||||
|
||||
.. ocv:emember:: Uncompressed_YUV420 = (('I'<<24)|('Y'<<16)|('U'<<8)|('V'))
|
||||
|
||||
Y,U,V (4:2:0)
|
||||
|
||||
.. ocv:emember:: Uncompressed_YV12 = (('Y'<<24)|('V'<<16)|('1'<<8)|('2'))
|
||||
|
||||
Y,V,U (4:2:0)
|
||||
|
||||
.. ocv:emember:: Uncompressed_NV12 = (('N'<<24)|('V'<<16)|('1'<<8)|('2'))
|
||||
|
||||
Y,UV (4:2:0)
|
||||
|
||||
.. ocv:emember:: Uncompressed_YUYV = (('Y'<<24)|('U'<<16)|('Y'<<8)|('V'))
|
||||
|
||||
YUYV/YUY2 (4:2:2)
|
||||
|
||||
.. ocv:emember:: Uncompressed_UYVY = (('U'<<24)|('Y'<<16)|('V'<<8)|('Y'))
|
||||
|
||||
UYVY (4:2:2)
|
||||
|
||||
|
||||
|
||||
cudacodec::ChromaFormat
|
||||
-----------------------
|
||||
Chroma formats supported by :ocv:class:`cudacodec::VideoReader` .
|
||||
|
||||
.. ocv:enum:: cudacodec::ChromaFormat
|
||||
|
||||
.. ocv:emember:: Monochrome = 0
|
||||
.. ocv:emember:: YUV420
|
||||
.. ocv:emember:: YUV422
|
||||
.. ocv:emember:: YUV444
|
||||
|
||||
|
||||
|
||||
cudacodec::FormatInfo
|
||||
---------------------
|
||||
.. ocv:struct:: cudacodec::FormatInfo
|
||||
|
||||
Struct providing information about video file format. ::
|
||||
|
||||
struct FormatInfo
|
||||
{
|
||||
Codec codec;
|
||||
ChromaFormat chromaFormat;
|
||||
int width;
|
||||
int height;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cudacodec::createVideoReader
|
||||
----------------------------
|
||||
Creates video reader.
|
||||
|
||||
.. ocv:function:: Ptr<VideoReader> cudacodec::createVideoReader(const String& filename)
|
||||
.. ocv:function:: Ptr<VideoReader> cudacodec::createVideoReader(const Ptr<RawVideoSource>& source)
|
||||
|
||||
:param filename: Name of the input video file.
|
||||
|
||||
:param source: RAW video source implemented by user.
|
||||
|
||||
FFMPEG is used to read videos. User can implement own demultiplexing with :ocv:class:`cudacodec::RawVideoSource` .
|
||||
|
||||
|
||||
|
||||
cudacodec::RawVideoSource
|
||||
-------------------------
|
||||
.. ocv:class:: cudacodec::RawVideoSource
|
||||
|
||||
Interface for video demultiplexing. ::
|
||||
|
||||
class RawVideoSource
|
||||
{
|
||||
public:
|
||||
virtual ~RawVideoSource() {}
|
||||
|
||||
virtual bool getNextPacket(unsigned char** data, int* size, bool* endOfFile) = 0;
|
||||
|
||||
virtual FormatInfo format() const = 0;
|
||||
};
|
||||
|
||||
User can implement own demultiplexing by implementing this interface.
|
||||
|
||||
|
||||
|
||||
cudacodec::RawVideoSource::getNextPacket
|
||||
----------------------------------------
|
||||
Returns next packet with RAW video frame.
|
||||
|
||||
.. ocv:function:: bool cudacodec::VideoSource::getNextPacket(unsigned char** data, int* size, bool* endOfFile) = 0
|
||||
|
||||
:param data: Pointer to frame data.
|
||||
|
||||
:param size: Size in bytes of current frame.
|
||||
|
||||
:param endOfStream: Indicates that it is end of stream.
|
||||
|
||||
|
||||
|
||||
cudacodec::RawVideoSource::format
|
||||
---------------------------------
|
||||
Returns information about video file format.
|
||||
|
||||
.. ocv:function:: virtual FormatInfo cudacodec::RawVideoSource::format() const = 0
|
||||
@@ -1,192 +0,0 @@
|
||||
Video Encoding
|
||||
==============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cudacodec::VideoWriter
|
||||
----------------------
|
||||
Video writer interface.
|
||||
|
||||
.. ocv:class:: cudacodec::VideoWriter
|
||||
|
||||
The implementation uses H264 video codec.
|
||||
|
||||
.. note:: Currently only Windows platform is supported.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example on how to use the videoWriter class can be found at opencv_source_code/samples/gpu/video_writer.cpp
|
||||
|
||||
|
||||
cudacodec::VideoWriter::write
|
||||
-----------------------------
|
||||
Writes the next video frame.
|
||||
|
||||
.. ocv:function:: void cudacodec::VideoWriter::write(InputArray frame, bool lastFrame = false) = 0
|
||||
|
||||
:param frame: The written frame.
|
||||
|
||||
:param lastFrame: Indicates that it is end of stream. The parameter can be ignored.
|
||||
|
||||
The method write the specified image to video file. The image must have the same size and the same surface format as has been specified when opening the video writer.
|
||||
|
||||
|
||||
|
||||
cudacodec::createVideoWriter
|
||||
----------------------------
|
||||
Creates video writer.
|
||||
|
||||
.. ocv:function:: Ptr<cudacodec::VideoWriter> cudacodec::createVideoWriter(const String& fileName, Size frameSize, double fps, SurfaceFormat format = SF_BGR)
|
||||
.. ocv:function:: Ptr<cudacodec::VideoWriter> cudacodec::createVideoWriter(const String& fileName, Size frameSize, double fps, const EncoderParams& params, SurfaceFormat format = SF_BGR)
|
||||
.. ocv:function:: Ptr<cudacodec::VideoWriter> cudacodec::createVideoWriter(const Ptr<EncoderCallBack>& encoderCallback, Size frameSize, double fps, SurfaceFormat format = SF_BGR)
|
||||
.. ocv:function:: Ptr<cudacodec::VideoWriter> cudacodec::createVideoWriter(const Ptr<EncoderCallBack>& encoderCallback, Size frameSize, double fps, const EncoderParams& params, SurfaceFormat format = SF_BGR)
|
||||
|
||||
:param fileName: Name of the output video file. Only AVI file format is supported.
|
||||
|
||||
:param frameSize: Size of the input video frames.
|
||||
|
||||
:param fps: Framerate of the created video stream.
|
||||
|
||||
:param params: Encoder parameters. See :ocv:struct:`cudacodec::EncoderParams` .
|
||||
|
||||
:param format: Surface format of input frames ( ``SF_UYVY`` , ``SF_YUY2`` , ``SF_YV12`` , ``SF_NV12`` , ``SF_IYUV`` , ``SF_BGR`` or ``SF_GRAY``). BGR or gray frames will be converted to YV12 format before encoding, frames with other formats will be used as is.
|
||||
|
||||
:param encoderCallback: Callbacks for video encoder. See :ocv:class:`cudacodec::EncoderCallBack` . Use it if you want to work with raw video stream.
|
||||
|
||||
The constructors initialize video writer. FFMPEG is used to write videos. User can implement own multiplexing with :ocv:class:`cudacodec::EncoderCallBack` .
|
||||
|
||||
|
||||
|
||||
cudacodec::EncoderParams
|
||||
------------------------
|
||||
.. ocv:struct:: cudacodec::EncoderParams
|
||||
|
||||
Different parameters for CUDA video encoder. ::
|
||||
|
||||
struct EncoderParams
|
||||
{
|
||||
int P_Interval; // NVVE_P_INTERVAL,
|
||||
int IDR_Period; // NVVE_IDR_PERIOD,
|
||||
int DynamicGOP; // NVVE_DYNAMIC_GOP,
|
||||
int RCType; // NVVE_RC_TYPE,
|
||||
int AvgBitrate; // NVVE_AVG_BITRATE,
|
||||
int PeakBitrate; // NVVE_PEAK_BITRATE,
|
||||
int QP_Level_Intra; // NVVE_QP_LEVEL_INTRA,
|
||||
int QP_Level_InterP; // NVVE_QP_LEVEL_INTER_P,
|
||||
int QP_Level_InterB; // NVVE_QP_LEVEL_INTER_B,
|
||||
int DeblockMode; // NVVE_DEBLOCK_MODE,
|
||||
int ProfileLevel; // NVVE_PROFILE_LEVEL,
|
||||
int ForceIntra; // NVVE_FORCE_INTRA,
|
||||
int ForceIDR; // NVVE_FORCE_IDR,
|
||||
int ClearStat; // NVVE_CLEAR_STAT,
|
||||
int DIMode; // NVVE_SET_DEINTERLACE,
|
||||
int Presets; // NVVE_PRESETS,
|
||||
int DisableCabac; // NVVE_DISABLE_CABAC,
|
||||
int NaluFramingType; // NVVE_CONFIGURE_NALU_FRAMING_TYPE
|
||||
int DisableSPSPPS; // NVVE_DISABLE_SPS_PPS
|
||||
|
||||
EncoderParams();
|
||||
explicit EncoderParams(const String& configFile);
|
||||
|
||||
void load(const String& configFile);
|
||||
void save(const String& configFile) const;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cudacodec::EncoderParams::EncoderParams
|
||||
---------------------------------------
|
||||
Constructors.
|
||||
|
||||
.. ocv:function:: cudacodec::EncoderParams::EncoderParams()
|
||||
.. ocv:function:: cudacodec::EncoderParams::EncoderParams(const String& configFile)
|
||||
|
||||
:param configFile: Config file name.
|
||||
|
||||
Creates default parameters or reads parameters from config file.
|
||||
|
||||
|
||||
|
||||
cudacodec::EncoderParams::load
|
||||
------------------------------
|
||||
Reads parameters from config file.
|
||||
|
||||
.. ocv:function:: void cudacodec::EncoderParams::load(const String& configFile)
|
||||
|
||||
:param configFile: Config file name.
|
||||
|
||||
|
||||
|
||||
cudacodec::EncoderParams::save
|
||||
------------------------------
|
||||
Saves parameters to config file.
|
||||
|
||||
.. ocv:function:: void cudacodec::EncoderParams::save(const String& configFile) const
|
||||
|
||||
:param configFile: Config file name.
|
||||
|
||||
|
||||
|
||||
cudacodec::EncoderCallBack
|
||||
--------------------------
|
||||
.. ocv:class:: cudacodec::EncoderCallBack
|
||||
|
||||
Callbacks for CUDA video encoder. ::
|
||||
|
||||
class EncoderCallBack
|
||||
{
|
||||
public:
|
||||
enum PicType
|
||||
{
|
||||
IFRAME = 1,
|
||||
PFRAME = 2,
|
||||
BFRAME = 3
|
||||
};
|
||||
|
||||
virtual ~EncoderCallBack() {}
|
||||
|
||||
virtual unsigned char* acquireBitStream(int* bufferSize) = 0;
|
||||
virtual void releaseBitStream(unsigned char* data, int size) = 0;
|
||||
virtual void onBeginFrame(int frameNumber, PicType picType) = 0;
|
||||
virtual void onEndFrame(int frameNumber, PicType picType) = 0;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cudacodec::EncoderCallBack::acquireBitStream
|
||||
--------------------------------------------
|
||||
Callback function to signal the start of bitstream that is to be encoded.
|
||||
|
||||
.. ocv:function:: virtual uchar* cudacodec::EncoderCallBack::acquireBitStream(int* bufferSize) = 0
|
||||
|
||||
Callback must allocate buffer for CUDA encoder and return pointer to it and it's size.
|
||||
|
||||
|
||||
|
||||
cudacodec::EncoderCallBack::releaseBitStream
|
||||
--------------------------------------------
|
||||
Callback function to signal that the encoded bitstream is ready to be written to file.
|
||||
|
||||
.. ocv:function:: virtual void cudacodec::EncoderCallBack::releaseBitStream(unsigned char* data, int size) = 0
|
||||
|
||||
|
||||
|
||||
cudacodec::EncoderCallBack::onBeginFrame
|
||||
----------------------------------------
|
||||
Callback function to signal that the encoding operation on the frame has started.
|
||||
|
||||
.. ocv:function:: virtual void cudacodec::EncoderCallBack::onBeginFrame(int frameNumber, PicType picType) = 0
|
||||
|
||||
:param picType: Specify frame type (I-Frame, P-Frame or B-Frame).
|
||||
|
||||
|
||||
|
||||
cudacodec::EncoderCallBack::onEndFrame
|
||||
--------------------------------------
|
||||
Callback function signals that the encoding operation on the frame has finished.
|
||||
|
||||
.. ocv:function:: virtual void cudacodec::EncoderCallBack::onEndFrame(int frameNumber, PicType picType) = 0
|
||||
|
||||
:param picType: Specify frame type (I-Frame, P-Frame or B-Frame).
|
||||
@@ -1,8 +0,0 @@
|
||||
******************************************************************
|
||||
cudafeatures2d. CUDA-accelerated Feature Detection and Description
|
||||
******************************************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
feature_detection_and_description
|
||||
@@ -1,539 +0,0 @@
|
||||
Feature Detection and Description
|
||||
=================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::FAST_CUDA
|
||||
---------------
|
||||
.. ocv:class:: cuda::FAST_CUDA
|
||||
|
||||
Class used for corner detection using the FAST algorithm. ::
|
||||
|
||||
class FAST_CUDA
|
||||
{
|
||||
public:
|
||||
enum
|
||||
{
|
||||
LOCATION_ROW = 0,
|
||||
RESPONSE_ROW,
|
||||
ROWS_COUNT
|
||||
};
|
||||
|
||||
// all features have same size
|
||||
static const int FEATURE_SIZE = 7;
|
||||
|
||||
explicit FAST_CUDA(int threshold, bool nonmaxSuppression = true,
|
||||
double keypointsRatio = 0.05);
|
||||
|
||||
void operator ()(const GpuMat& image, const GpuMat& mask, GpuMat& keypoints);
|
||||
void operator ()(const GpuMat& image, const GpuMat& mask,
|
||||
std::vector<KeyPoint>& keypoints);
|
||||
|
||||
void downloadKeypoints(const GpuMat& d_keypoints,
|
||||
std::vector<KeyPoint>& keypoints);
|
||||
|
||||
void convertKeypoints(const Mat& h_keypoints,
|
||||
std::vector<KeyPoint>& keypoints);
|
||||
|
||||
void release();
|
||||
|
||||
bool nonmaxSuppression;
|
||||
|
||||
int threshold;
|
||||
|
||||
double keypointsRatio;
|
||||
|
||||
int calcKeyPointsLocation(const GpuMat& image, const GpuMat& mask);
|
||||
|
||||
int getKeyPoints(GpuMat& keypoints);
|
||||
};
|
||||
|
||||
|
||||
The class ``FAST_CUDA`` implements FAST corner detection algorithm.
|
||||
|
||||
.. seealso:: :ocv:func:`FAST`
|
||||
|
||||
|
||||
|
||||
cuda::FAST_CUDA::FAST_CUDA
|
||||
--------------------------
|
||||
Constructor.
|
||||
|
||||
.. ocv:function:: cuda::FAST_CUDA::FAST_CUDA(int threshold, bool nonmaxSuppression = true, double keypointsRatio = 0.05)
|
||||
|
||||
:param threshold: Threshold on difference between intensity of the central pixel and pixels on a circle around this pixel.
|
||||
|
||||
:param nonmaxSuppression: If it is true, non-maximum suppression is applied to detected corners (keypoints).
|
||||
|
||||
:param keypointsRatio: Inner buffer size for keypoints store is determined as (keypointsRatio * image_width * image_height).
|
||||
|
||||
|
||||
|
||||
cuda::FAST_CUDA::operator ()
|
||||
----------------------------
|
||||
Finds the keypoints using FAST detector.
|
||||
|
||||
.. ocv:function:: void cuda::FAST_CUDA::operator ()(const GpuMat& image, const GpuMat& mask, GpuMat& keypoints)
|
||||
.. ocv:function:: void cuda::FAST_CUDA::operator ()(const GpuMat& image, const GpuMat& mask, std::vector<KeyPoint>& keypoints)
|
||||
|
||||
:param image: Image where keypoints (corners) are detected. Only 8-bit grayscale images are supported.
|
||||
|
||||
:param mask: Optional input mask that marks the regions where we should detect features.
|
||||
|
||||
:param keypoints: The output vector of keypoints. Can be stored both in CPU and GPU memory. For GPU memory:
|
||||
|
||||
* keypoints.ptr<Vec2s>(LOCATION_ROW)[i] will contain location of i'th point
|
||||
* keypoints.ptr<float>(RESPONSE_ROW)[i] will contain response of i'th point (if non-maximum suppression is applied)
|
||||
|
||||
|
||||
|
||||
cuda::FAST_CUDA::downloadKeypoints
|
||||
----------------------------------
|
||||
Download keypoints from GPU to CPU memory.
|
||||
|
||||
.. ocv:function:: void cuda::FAST_CUDA::downloadKeypoints(const GpuMat& d_keypoints, std::vector<KeyPoint>& keypoints)
|
||||
|
||||
|
||||
|
||||
cuda::FAST_CUDA::convertKeypoints
|
||||
---------------------------------
|
||||
Converts keypoints from CUDA representation to vector of ``KeyPoint``.
|
||||
|
||||
.. ocv:function:: void cuda::FAST_CUDA::convertKeypoints(const Mat& h_keypoints, std::vector<KeyPoint>& keypoints)
|
||||
|
||||
|
||||
|
||||
cuda::FAST_CUDA::release
|
||||
------------------------
|
||||
Releases inner buffer memory.
|
||||
|
||||
.. ocv:function:: void cuda::FAST_CUDA::release()
|
||||
|
||||
|
||||
|
||||
cuda::FAST_CUDA::calcKeyPointsLocation
|
||||
--------------------------------------
|
||||
Find keypoints and compute it's response if ``nonmaxSuppression`` is true.
|
||||
|
||||
.. ocv:function:: int cuda::FAST_CUDA::calcKeyPointsLocation(const GpuMat& image, const GpuMat& mask)
|
||||
|
||||
:param image: Image where keypoints (corners) are detected. Only 8-bit grayscale images are supported.
|
||||
|
||||
:param mask: Optional input mask that marks the regions where we should detect features.
|
||||
|
||||
The function returns count of detected keypoints.
|
||||
|
||||
|
||||
|
||||
cuda::FAST_CUDA::getKeyPoints
|
||||
-----------------------------
|
||||
Gets final array of keypoints.
|
||||
|
||||
.. ocv:function:: int cuda::FAST_CUDA::getKeyPoints(GpuMat& keypoints)
|
||||
|
||||
:param keypoints: The output vector of keypoints.
|
||||
|
||||
The function performs non-max suppression if needed and returns final count of keypoints.
|
||||
|
||||
|
||||
|
||||
cuda::ORB_CUDA
|
||||
--------------
|
||||
.. ocv:class:: cuda::ORB_CUDA
|
||||
|
||||
Class for extracting ORB features and descriptors from an image. ::
|
||||
|
||||
class ORB_CUDA
|
||||
{
|
||||
public:
|
||||
enum
|
||||
{
|
||||
X_ROW = 0,
|
||||
Y_ROW,
|
||||
RESPONSE_ROW,
|
||||
ANGLE_ROW,
|
||||
OCTAVE_ROW,
|
||||
SIZE_ROW,
|
||||
ROWS_COUNT
|
||||
};
|
||||
|
||||
enum
|
||||
{
|
||||
DEFAULT_FAST_THRESHOLD = 20
|
||||
};
|
||||
|
||||
explicit ORB_CUDA(int nFeatures = 500, float scaleFactor = 1.2f,
|
||||
int nLevels = 8, int edgeThreshold = 31,
|
||||
int firstLevel = 0, int WTA_K = 2,
|
||||
int scoreType = 0, int patchSize = 31);
|
||||
|
||||
void operator()(const GpuMat& image, const GpuMat& mask,
|
||||
std::vector<KeyPoint>& keypoints);
|
||||
void operator()(const GpuMat& image, const GpuMat& mask, GpuMat& keypoints);
|
||||
|
||||
void operator()(const GpuMat& image, const GpuMat& mask,
|
||||
std::vector<KeyPoint>& keypoints, GpuMat& descriptors);
|
||||
void operator()(const GpuMat& image, const GpuMat& mask,
|
||||
GpuMat& keypoints, GpuMat& descriptors);
|
||||
|
||||
void downloadKeyPoints(GpuMat& d_keypoints, std::vector<KeyPoint>& keypoints);
|
||||
|
||||
void convertKeyPoints(Mat& d_keypoints, std::vector<KeyPoint>& keypoints);
|
||||
|
||||
int descriptorSize() const;
|
||||
|
||||
void setParams(size_t n_features, const ORB::CommonParams& detector_params);
|
||||
void setFastParams(int threshold, bool nonmaxSuppression = true);
|
||||
|
||||
void release();
|
||||
|
||||
bool blurForDescriptor;
|
||||
};
|
||||
|
||||
The class implements ORB feature detection and description algorithm.
|
||||
|
||||
|
||||
|
||||
cuda::ORB_CUDA::ORB_CUDA
|
||||
------------------------
|
||||
Constructor.
|
||||
|
||||
.. ocv:function:: cuda::ORB_CUDA::ORB_CUDA(int nFeatures = 500, float scaleFactor = 1.2f, int nLevels = 8, int edgeThreshold = 31, int firstLevel = 0, int WTA_K = 2, int scoreType = 0, int patchSize = 31)
|
||||
|
||||
:param nFeatures: The number of desired features.
|
||||
|
||||
:param scaleFactor: Coefficient by which we divide the dimensions from one scale pyramid level to the next.
|
||||
|
||||
:param nLevels: The number of levels in the scale pyramid.
|
||||
|
||||
:param edgeThreshold: How far from the boundary the points should be.
|
||||
|
||||
:param firstLevel: The level at which the image is given. If 1, that means we will also look at the image `scaleFactor` times bigger.
|
||||
|
||||
|
||||
|
||||
cuda::ORB_CUDA::operator()
|
||||
--------------------------
|
||||
Detects keypoints and computes descriptors for them.
|
||||
|
||||
.. ocv:function:: void cuda::ORB_CUDA::operator()(const GpuMat& image, const GpuMat& mask, std::vector<KeyPoint>& keypoints)
|
||||
|
||||
.. ocv:function:: void cuda::ORB_CUDA::operator()(const GpuMat& image, const GpuMat& mask, GpuMat& keypoints)
|
||||
|
||||
.. ocv:function:: void cuda::ORB_CUDA::operator()(const GpuMat& image, const GpuMat& mask, std::vector<KeyPoint>& keypoints, GpuMat& descriptors)
|
||||
|
||||
.. ocv:function:: void cuda::ORB_CUDA::operator()(const GpuMat& image, const GpuMat& mask, GpuMat& keypoints, GpuMat& descriptors)
|
||||
|
||||
:param image: Input 8-bit grayscale image.
|
||||
|
||||
:param mask: Optional input mask that marks the regions where we should detect features.
|
||||
|
||||
:param keypoints: The input/output vector of keypoints. Can be stored both in CPU and GPU memory. For GPU memory:
|
||||
|
||||
* ``keypoints.ptr<float>(X_ROW)[i]`` contains x coordinate of the i'th feature.
|
||||
* ``keypoints.ptr<float>(Y_ROW)[i]`` contains y coordinate of the i'th feature.
|
||||
* ``keypoints.ptr<float>(RESPONSE_ROW)[i]`` contains the response of the i'th feature.
|
||||
* ``keypoints.ptr<float>(ANGLE_ROW)[i]`` contains orientation of the i'th feature.
|
||||
* ``keypoints.ptr<float>(OCTAVE_ROW)[i]`` contains the octave of the i'th feature.
|
||||
* ``keypoints.ptr<float>(SIZE_ROW)[i]`` contains the size of the i'th feature.
|
||||
|
||||
:param descriptors: Computed descriptors. if ``blurForDescriptor`` is true, image will be blurred before descriptors calculation.
|
||||
|
||||
|
||||
|
||||
cuda::ORB_CUDA::downloadKeyPoints
|
||||
---------------------------------
|
||||
Download keypoints from GPU to CPU memory.
|
||||
|
||||
.. ocv:function:: static void cuda::ORB_CUDA::downloadKeyPoints( const GpuMat& d_keypoints, std::vector<KeyPoint>& keypoints )
|
||||
|
||||
|
||||
|
||||
cuda::ORB_CUDA::convertKeyPoints
|
||||
--------------------------------
|
||||
Converts keypoints from CUDA representation to vector of ``KeyPoint``.
|
||||
|
||||
.. ocv:function:: static void cuda::ORB_CUDA::convertKeyPoints( const Mat& d_keypoints, std::vector<KeyPoint>& keypoints )
|
||||
|
||||
|
||||
|
||||
cuda::ORB_CUDA::release
|
||||
-----------------------
|
||||
Releases inner buffer memory.
|
||||
|
||||
.. ocv:function:: void cuda::ORB_CUDA::release()
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA
|
||||
--------------------
|
||||
.. ocv:class:: cuda::BFMatcher_CUDA
|
||||
|
||||
Brute-force descriptor matcher. For each descriptor in the first set, this matcher finds the closest descriptor in the second set by trying each one. This descriptor matcher supports masking permissible matches between descriptor sets. ::
|
||||
|
||||
class BFMatcher_CUDA
|
||||
{
|
||||
public:
|
||||
explicit BFMatcher_CUDA(int norm = cv::NORM_L2);
|
||||
|
||||
// Add descriptors to train descriptor collection.
|
||||
void add(const std::vector<GpuMat>& descCollection);
|
||||
|
||||
// Get train descriptors collection.
|
||||
const std::vector<GpuMat>& getTrainDescriptors() const;
|
||||
|
||||
// Clear train descriptors collection.
|
||||
void clear();
|
||||
|
||||
// Return true if there are no train descriptors in collection.
|
||||
bool empty() const;
|
||||
|
||||
// Return true if the matcher supports mask in match methods.
|
||||
bool isMaskSupported() const;
|
||||
|
||||
void matchSingle(const GpuMat& query, const GpuMat& train,
|
||||
GpuMat& trainIdx, GpuMat& distance,
|
||||
const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null());
|
||||
|
||||
static void matchDownload(const GpuMat& trainIdx,
|
||||
const GpuMat& distance, std::vector<DMatch>& matches);
|
||||
static void matchConvert(const Mat& trainIdx,
|
||||
const Mat& distance, std::vector<DMatch>& matches);
|
||||
|
||||
void match(const GpuMat& query, const GpuMat& train,
|
||||
std::vector<DMatch>& matches, const GpuMat& mask = GpuMat());
|
||||
|
||||
void makeGpuCollection(GpuMat& trainCollection, GpuMat& maskCollection,
|
||||
const vector<GpuMat>& masks = std::vector<GpuMat>());
|
||||
|
||||
void matchCollection(const GpuMat& query, const GpuMat& trainCollection,
|
||||
GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance,
|
||||
const GpuMat& maskCollection, Stream& stream = Stream::Null());
|
||||
|
||||
static void matchDownload(const GpuMat& trainIdx, GpuMat& imgIdx,
|
||||
const GpuMat& distance, std::vector<DMatch>& matches);
|
||||
static void matchConvert(const Mat& trainIdx, const Mat& imgIdx,
|
||||
const Mat& distance, std::vector<DMatch>& matches);
|
||||
|
||||
void match(const GpuMat& query, std::vector<DMatch>& matches,
|
||||
const std::vector<GpuMat>& masks = std::vector<GpuMat>());
|
||||
|
||||
void knnMatchSingle(const GpuMat& query, const GpuMat& train,
|
||||
GpuMat& trainIdx, GpuMat& distance, GpuMat& allDist, int k,
|
||||
const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null());
|
||||
|
||||
static void knnMatchDownload(const GpuMat& trainIdx, const GpuMat& distance,
|
||||
std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
|
||||
static void knnMatchConvert(const Mat& trainIdx, const Mat& distance,
|
||||
std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
|
||||
|
||||
void knnMatch(const GpuMat& query, const GpuMat& train,
|
||||
std::vector< std::vector<DMatch> >& matches, int k,
|
||||
const GpuMat& mask = GpuMat(), bool compactResult = false);
|
||||
|
||||
void knnMatch2Collection(const GpuMat& query, const GpuMat& trainCollection,
|
||||
GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance,
|
||||
const GpuMat& maskCollection = GpuMat(), Stream& stream = Stream::Null());
|
||||
|
||||
static void knnMatch2Download(const GpuMat& trainIdx, const GpuMat& imgIdx, const GpuMat& distance,
|
||||
std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
|
||||
static void knnMatch2Convert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance,
|
||||
std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
|
||||
|
||||
void knnMatch(const GpuMat& query, std::vector< std::vector<DMatch> >& matches, int k,
|
||||
const std::vector<GpuMat>& masks = std::vector<GpuMat>(),
|
||||
bool compactResult = false);
|
||||
|
||||
void radiusMatchSingle(const GpuMat& query, const GpuMat& train,
|
||||
GpuMat& trainIdx, GpuMat& distance, GpuMat& nMatches, float maxDistance,
|
||||
const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null());
|
||||
|
||||
static void radiusMatchDownload(const GpuMat& trainIdx, const GpuMat& distance, const GpuMat& nMatches,
|
||||
std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
|
||||
static void radiusMatchConvert(const Mat& trainIdx, const Mat& distance, const Mat& nMatches,
|
||||
std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
|
||||
|
||||
void radiusMatch(const GpuMat& query, const GpuMat& train,
|
||||
std::vector< std::vector<DMatch> >& matches, float maxDistance,
|
||||
const GpuMat& mask = GpuMat(), bool compactResult = false);
|
||||
|
||||
void radiusMatchCollection(const GpuMat& query, GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance, GpuMat& nMatches, float maxDistance,
|
||||
const std::vector<GpuMat>& masks = std::vector<GpuMat>(), Stream& stream = Stream::Null());
|
||||
|
||||
static void radiusMatchDownload(const GpuMat& trainIdx, const GpuMat& imgIdx, const GpuMat& distance, const GpuMat& nMatches,
|
||||
std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
|
||||
static void radiusMatchConvert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, const Mat& nMatches,
|
||||
std::vector< std::vector<DMatch> >& matches, bool compactResult = false);
|
||||
|
||||
void radiusMatch(const GpuMat& query, std::vector< std::vector<DMatch> >& matches, float maxDistance,
|
||||
const std::vector<GpuMat>& masks = std::vector<GpuMat>(), bool compactResult = false);
|
||||
|
||||
private:
|
||||
std::vector<GpuMat> trainDescCollection;
|
||||
};
|
||||
|
||||
|
||||
The class ``BFMatcher_CUDA`` has an interface similar to the class :ocv:class:`DescriptorMatcher`. It has two groups of ``match`` methods: for matching descriptors of one image with another image or with an image set. Also, all functions have an alternative to save results either to the GPU memory or to the CPU memory.
|
||||
|
||||
.. seealso:: :ocv:class:`DescriptorMatcher`, :ocv:class:`BFMatcher`
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA::match
|
||||
---------------------------
|
||||
Finds the best match for each descriptor from a query set with train descriptors.
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::match(const GpuMat& query, const GpuMat& train, std::vector<DMatch>& matches, const GpuMat& mask = GpuMat())
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::matchSingle(const GpuMat& query, const GpuMat& train, GpuMat& trainIdx, GpuMat& distance, const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::match(const GpuMat& query, std::vector<DMatch>& matches, const std::vector<GpuMat>& masks = std::vector<GpuMat>())
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::matchCollection( const GpuMat& query, const GpuMat& trainCollection, GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance, const GpuMat& masks=GpuMat(), Stream& stream=Stream::Null() )
|
||||
|
||||
.. seealso:: :ocv:func:`DescriptorMatcher::match`
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA::makeGpuCollection
|
||||
---------------------------------------
|
||||
Performs a GPU collection of train descriptors and masks in a suitable format for the :ocv:func:`cuda::BFMatcher_CUDA::matchCollection` function.
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::makeGpuCollection(GpuMat& trainCollection, GpuMat& maskCollection, const vector<GpuMat>& masks = std::vector<GpuMat>())
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA::matchDownload
|
||||
-----------------------------------
|
||||
Downloads matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::matchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::matchCollection` to vector with :ocv:class:`DMatch`.
|
||||
|
||||
.. ocv:function:: static void cuda::BFMatcher_CUDA::matchDownload(const GpuMat& trainIdx, const GpuMat& distance, std::vector<DMatch>&matches)
|
||||
|
||||
.. ocv:function:: static void cuda::BFMatcher_CUDA::matchDownload( const GpuMat& trainIdx, const GpuMat& imgIdx, const GpuMat& distance, std::vector<DMatch>& matches )
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA::matchConvert
|
||||
----------------------------------
|
||||
Converts matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::matchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::matchCollection` to vector with :ocv:class:`DMatch`.
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::matchConvert(const Mat& trainIdx, const Mat& distance, std::vector<DMatch>&matches)
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::matchConvert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, std::vector<DMatch>&matches)
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA::knnMatch
|
||||
------------------------------
|
||||
Finds the ``k`` best matches for each descriptor from a query set with train descriptors.
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatch(const GpuMat& query, const GpuMat& train, std::vector< std::vector<DMatch> >&matches, int k, const GpuMat& mask = GpuMat(), bool compactResult = false)
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatchSingle(const GpuMat& query, const GpuMat& train, GpuMat& trainIdx, GpuMat& distance, GpuMat& allDist, int k, const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatch(const GpuMat& query, std::vector< std::vector<DMatch> >&matches, int k, const std::vector<GpuMat>&masks = std::vector<GpuMat>(), bool compactResult = false )
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatch2Collection(const GpuMat& query, const GpuMat& trainCollection, GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance, const GpuMat& maskCollection = GpuMat(), Stream& stream = Stream::Null())
|
||||
|
||||
:param query: Query set of descriptors.
|
||||
|
||||
:param train: Training set of descriptors. It is not be added to train descriptors collection stored in the class object.
|
||||
|
||||
:param k: Number of the best matches per each query descriptor (or less if it is not possible).
|
||||
|
||||
:param mask: Mask specifying permissible matches between the input query and train matrices of descriptors.
|
||||
|
||||
:param compactResult: If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
The function returns detected ``k`` (or less if not possible) matches in the increasing order by distance.
|
||||
|
||||
The third variant of the method stores the results in GPU memory.
|
||||
|
||||
.. seealso:: :ocv:func:`DescriptorMatcher::knnMatch`
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA::knnMatchDownload
|
||||
--------------------------------------
|
||||
Downloads matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::knnMatchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::knnMatch2Collection` to vector with :ocv:class:`DMatch`.
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatchDownload(const GpuMat& trainIdx, const GpuMat& distance, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatch2Download(const GpuMat& trainIdx, const GpuMat& imgIdx, const GpuMat& distance, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
|
||||
|
||||
If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA::knnMatchConvert
|
||||
-------------------------------------
|
||||
Converts matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::knnMatchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::knnMatch2Collection` to CPU vector with :ocv:class:`DMatch`.
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatchConvert(const Mat& trainIdx, const Mat& distance, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::knnMatch2Convert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
|
||||
|
||||
If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA::radiusMatch
|
||||
---------------------------------
|
||||
For each query descriptor, finds the best matches with a distance less than a given threshold.
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatch(const GpuMat& query, const GpuMat& train, std::vector< std::vector<DMatch> >&matches, float maxDistance, const GpuMat& mask = GpuMat(), bool compactResult = false)
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchSingle(const GpuMat& query, const GpuMat& train, GpuMat& trainIdx, GpuMat& distance, GpuMat& nMatches, float maxDistance, const GpuMat& mask = GpuMat(), Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatch(const GpuMat& query, std::vector< std::vector<DMatch> >&matches, float maxDistance, const std::vector<GpuMat>& masks = std::vector<GpuMat>(), bool compactResult = false)
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchCollection(const GpuMat& query, GpuMat& trainIdx, GpuMat& imgIdx, GpuMat& distance, GpuMat& nMatches, float maxDistance, const std::vector<GpuMat>& masks = std::vector<GpuMat>(), Stream& stream = Stream::Null())
|
||||
|
||||
:param query: Query set of descriptors.
|
||||
|
||||
:param train: Training set of descriptors. It is not added to train descriptors collection stored in the class object.
|
||||
|
||||
:param maxDistance: Distance threshold.
|
||||
|
||||
:param mask: Mask specifying permissible matches between the input query and train matrices of descriptors.
|
||||
|
||||
:param compactResult: If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
The function returns detected matches in the increasing order by distance.
|
||||
|
||||
The methods work only on devices with the compute capability :math:`>=` 1.1.
|
||||
|
||||
The third variant of the method stores the results in GPU memory and does not store the points by the distance.
|
||||
|
||||
.. seealso:: :ocv:func:`DescriptorMatcher::radiusMatch`
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA::radiusMatchDownload
|
||||
-----------------------------------------
|
||||
Downloads matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::radiusMatchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::radiusMatchCollection` to vector with :ocv:class:`DMatch`.
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchDownload(const GpuMat& trainIdx, const GpuMat& distance, const GpuMat& nMatches, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchDownload(const GpuMat& trainIdx, const GpuMat& imgIdx, const GpuMat& distance, const GpuMat& nMatches, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
|
||||
|
||||
If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
|
||||
|
||||
|
||||
|
||||
|
||||
cuda::BFMatcher_CUDA::radiusMatchConvert
|
||||
----------------------------------------
|
||||
Converts matrices obtained via :ocv:func:`cuda::BFMatcher_CUDA::radiusMatchSingle` or :ocv:func:`cuda::BFMatcher_CUDA::radiusMatchCollection` to vector with :ocv:class:`DMatch`.
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchConvert(const Mat& trainIdx, const Mat& distance, const Mat& nMatches, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
|
||||
|
||||
.. ocv:function:: void cuda::BFMatcher_CUDA::radiusMatchConvert(const Mat& trainIdx, const Mat& imgIdx, const Mat& distance, const Mat& nMatches, std::vector< std::vector<DMatch> >& matches, bool compactResult = false)
|
||||
|
||||
If ``compactResult`` is ``true`` , the ``matches`` vector does not contain matches for fully masked-out query descriptors.
|
||||
@@ -1,8 +0,0 @@
|
||||
*********************************************
|
||||
cudafilters. CUDA-accelerated Image Filtering
|
||||
*********************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
filtering
|
||||
@@ -1,338 +0,0 @@
|
||||
Image Filtering
|
||||
===============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
Functions and classes described in this section are used to perform various linear or non-linear filtering operations on 2D images.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example containing all basic morphology operators like erode and dilate can be found at opencv_source_code/samples/gpu/morphology.cpp
|
||||
|
||||
|
||||
|
||||
cuda::Filter
|
||||
------------
|
||||
.. ocv:class:: cuda::Filter
|
||||
|
||||
Common interface for all CUDA filters ::
|
||||
|
||||
class CV_EXPORTS Filter : public Algorithm
|
||||
{
|
||||
public:
|
||||
virtual void apply(InputArray src, OutputArray dst, Stream& stream = Stream::Null()) = 0;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::Filter::apply
|
||||
-------------------
|
||||
Applies the specified filter to the image.
|
||||
|
||||
.. ocv:function:: void cuda::Filter::apply(InputArray src, OutputArray dst, Stream& stream = Stream::Null()) = 0
|
||||
|
||||
:param src: Input image.
|
||||
|
||||
:param dst: Output image.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::createBoxFilter
|
||||
---------------------
|
||||
Creates a normalized 2D box filter.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createBoxFilter(int srcType, int dstType, Size ksize, Point anchor = Point(-1,-1), int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
|
||||
|
||||
:param srcType: Input image type. Only ``CV_8UC1`` and ``CV_8UC4`` are supported for now.
|
||||
|
||||
:param dstType: Output image type. Only the same type as ``src`` is supported for now.
|
||||
|
||||
:param ksize: Kernel size.
|
||||
|
||||
:param anchor: Anchor point. The default value ``Point(-1, -1)`` means that the anchor is at the kernel center.
|
||||
|
||||
:param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
|
||||
|
||||
:param borderVal: Default border value.
|
||||
|
||||
.. seealso:: :ocv:func:`boxFilter`
|
||||
|
||||
|
||||
|
||||
cuda::createLinearFilter
|
||||
------------------------
|
||||
Creates a non-separable linear 2D filter.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createLinearFilter(int srcType, int dstType, InputArray kernel, Point anchor = Point(-1,-1), int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
|
||||
|
||||
:param srcType: Input image type. Supports ``CV_8U`` , ``CV_16U`` and ``CV_32F`` one and four channel image.
|
||||
|
||||
:param dstType: Output image type. Only the same type as ``src`` is supported for now.
|
||||
|
||||
:param kernel: 2D array of filter coefficients.
|
||||
|
||||
:param anchor: Anchor point. The default value Point(-1, -1) means that the anchor is at the kernel center.
|
||||
|
||||
:param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
|
||||
|
||||
:param borderVal: Default border value.
|
||||
|
||||
.. seealso:: :ocv:func:`filter2D`
|
||||
|
||||
|
||||
|
||||
cuda::createLaplacianFilter
|
||||
---------------------------
|
||||
Creates a Laplacian operator.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createLaplacianFilter(int srcType, int dstType, int ksize = 1, double scale = 1, int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
|
||||
|
||||
:param srcType: Input image type. Supports ``CV_8U`` , ``CV_16U`` and ``CV_32F`` one and four channel image.
|
||||
|
||||
:param dstType: Output image type. Only the same type as ``src`` is supported for now.
|
||||
|
||||
:param ksize: Aperture size used to compute the second-derivative filters (see :ocv:func:`getDerivKernels`). It must be positive and odd. Only ``ksize`` = 1 and ``ksize`` = 3 are supported.
|
||||
|
||||
:param scale: Optional scale factor for the computed Laplacian values. By default, no scaling is applied (see :ocv:func:`getDerivKernels` ).
|
||||
|
||||
:param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
|
||||
|
||||
:param borderVal: Default border value.
|
||||
|
||||
.. seealso:: :ocv:func:`Laplacian`
|
||||
|
||||
|
||||
|
||||
cuda::createSeparableLinearFilter
|
||||
---------------------------------
|
||||
Creates a separable linear filter.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createSeparableLinearFilter(int srcType, int dstType, InputArray rowKernel, InputArray columnKernel, Point anchor = Point(-1,-1), int rowBorderMode = BORDER_DEFAULT, int columnBorderMode = -1)
|
||||
|
||||
:param srcType: Source array type.
|
||||
|
||||
:param dstType: Destination array type.
|
||||
|
||||
:param rowKernel: Horizontal filter coefficients. Support kernels with ``size <= 32`` .
|
||||
|
||||
:param columnKernel: Vertical filter coefficients. Support kernels with ``size <= 32`` .
|
||||
|
||||
:param anchor: Anchor position within the kernel. Negative values mean that anchor is positioned at the aperture center.
|
||||
|
||||
:param rowBorderMode: Pixel extrapolation method in the vertical direction For details, see :ocv:func:`borderInterpolate`.
|
||||
|
||||
:param columnBorderMode: Pixel extrapolation method in the horizontal direction.
|
||||
|
||||
.. seealso:: :ocv:func:`sepFilter2D`
|
||||
|
||||
|
||||
|
||||
cuda::createDerivFilter
|
||||
-----------------------
|
||||
Creates a generalized Deriv operator.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createDerivFilter(int srcType, int dstType, int dx, int dy, int ksize, bool normalize = false, double scale = 1, int rowBorderMode = BORDER_DEFAULT, int columnBorderMode = -1)
|
||||
|
||||
:param srcType: Source image type.
|
||||
|
||||
:param dstType: Destination array type.
|
||||
|
||||
:param dx: Derivative order in respect of x.
|
||||
|
||||
:param dy: Derivative order in respect of y.
|
||||
|
||||
:param ksize: Aperture size. See :ocv:func:`getDerivKernels` for details.
|
||||
|
||||
:param normalize: Flag indicating whether to normalize (scale down) the filter coefficients or not. See :ocv:func:`getDerivKernels` for details.
|
||||
|
||||
:param scale: Optional scale factor for the computed derivative values. By default, no scaling is applied. For details, see :ocv:func:`getDerivKernels` .
|
||||
|
||||
:param rowBorderMode: Pixel extrapolation method in the vertical direction. For details, see :ocv:func:`borderInterpolate`.
|
||||
|
||||
:param columnBorderMode: Pixel extrapolation method in the horizontal direction.
|
||||
|
||||
|
||||
|
||||
cuda::createSobelFilter
|
||||
-----------------------
|
||||
Creates a Sobel operator.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createSobelFilter(int srcType, int dstType, int dx, int dy, int ksize = 3, double scale = 1, int rowBorderMode = BORDER_DEFAULT, int columnBorderMode = -1)
|
||||
|
||||
:param srcType: Source image type.
|
||||
|
||||
:param dstType: Destination array type.
|
||||
|
||||
:param dx: Derivative order in respect of x.
|
||||
|
||||
:param dy: Derivative order in respect of y.
|
||||
|
||||
:param ksize: Size of the extended Sobel kernel. Possible values are 1, 3, 5 or 7.
|
||||
|
||||
:param scale: Optional scale factor for the computed derivative values. By default, no scaling is applied. For details, see :ocv:func:`getDerivKernels` .
|
||||
|
||||
:param rowBorderMode: Pixel extrapolation method in the vertical direction. For details, see :ocv:func:`borderInterpolate`.
|
||||
|
||||
:param columnBorderMode: Pixel extrapolation method in the horizontal direction.
|
||||
|
||||
.. seealso:: :ocv:func:`Sobel`
|
||||
|
||||
|
||||
|
||||
cuda::createScharrFilter
|
||||
------------------------
|
||||
Creates a vertical or horizontal Scharr operator.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createScharrFilter(int srcType, int dstType, int dx, int dy, double scale = 1, int rowBorderMode = BORDER_DEFAULT, int columnBorderMode = -1)
|
||||
|
||||
:param srcType: Source image type.
|
||||
|
||||
:param dstType: Destination array type.
|
||||
|
||||
:param dx: Order of the derivative x.
|
||||
|
||||
:param dy: Order of the derivative y.
|
||||
|
||||
:param scale: Optional scale factor for the computed derivative values. By default, no scaling is applied. See :ocv:func:`getDerivKernels` for details.
|
||||
|
||||
:param rowBorderMode: Pixel extrapolation method in the vertical direction. For details, see :ocv:func:`borderInterpolate`.
|
||||
|
||||
:param columnBorderMode: Pixel extrapolation method in the horizontal direction.
|
||||
|
||||
.. seealso:: :ocv:func:`Scharr`
|
||||
|
||||
|
||||
|
||||
cuda::createGaussianFilter
|
||||
--------------------------
|
||||
Creates a Gaussian filter.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createGaussianFilter(int srcType, int dstType, Size ksize, double sigma1, double sigma2 = 0, int rowBorderMode = BORDER_DEFAULT, int columnBorderMode = -1)
|
||||
|
||||
:param srcType: Source image type.
|
||||
|
||||
:param dstType: Destination array type.
|
||||
|
||||
:param ksize: Aperture size. See :ocv:func:`getGaussianKernel` for details.
|
||||
|
||||
:param sigma1: Gaussian sigma in the horizontal direction. See :ocv:func:`getGaussianKernel` for details.
|
||||
|
||||
:param sigma2: Gaussian sigma in the vertical direction. If 0, then :math:`\texttt{sigma2}\leftarrow\texttt{sigma1}` .
|
||||
|
||||
:param rowBorderMode: Pixel extrapolation method in the vertical direction. For details, see :ocv:func:`borderInterpolate`.
|
||||
|
||||
:param columnBorderMode: Pixel extrapolation method in the horizontal direction.
|
||||
|
||||
.. seealso:: :ocv:func:`GaussianBlur`
|
||||
|
||||
|
||||
|
||||
cuda::createMorphologyFilter
|
||||
----------------------------
|
||||
Creates a 2D morphological filter.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createMorphologyFilter(int op, int srcType, InputArray kernel, Point anchor = Point(-1, -1), int iterations = 1)
|
||||
|
||||
:param op: Type of morphological operation. The following types are possible:
|
||||
|
||||
* **MORPH_ERODE** erode
|
||||
|
||||
* **MORPH_DILATE** dilate
|
||||
|
||||
* **MORPH_OPEN** opening
|
||||
|
||||
* **MORPH_CLOSE** closing
|
||||
|
||||
* **MORPH_GRADIENT** morphological gradient
|
||||
|
||||
* **MORPH_TOPHAT** "top hat"
|
||||
|
||||
* **MORPH_BLACKHAT** "black hat"
|
||||
|
||||
:param srcType: Input/output image type. Only ``CV_8UC1`` and ``CV_8UC4`` are supported.
|
||||
|
||||
:param kernel: 2D 8-bit structuring element for the morphological operation.
|
||||
|
||||
:param anchor: Anchor position within the structuring element. Negative values mean that the anchor is at the center.
|
||||
|
||||
:param iterations: Number of times erosion and dilation to be applied.
|
||||
|
||||
.. seealso:: :ocv:func:`morphologyEx`
|
||||
|
||||
|
||||
|
||||
cuda::createBoxMaxFilter
|
||||
------------------------
|
||||
Creates the maximum filter.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createBoxMaxFilter(int srcType, Size ksize, Point anchor = Point(-1, -1), int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
|
||||
|
||||
:param srcType: Input/output image type. Only ``CV_8UC1`` and ``CV_8UC4`` are supported.
|
||||
|
||||
:param ksize: Kernel size.
|
||||
|
||||
:param anchor: Anchor point. The default value (-1) means that the anchor is at the kernel center.
|
||||
|
||||
:param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
|
||||
|
||||
:param borderVal: Default border value.
|
||||
|
||||
|
||||
|
||||
cuda::createBoxMinFilter
|
||||
------------------------
|
||||
Creates the minimum filter.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createBoxMinFilter(int srcType, Size ksize, Point anchor = Point(-1, -1), int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
|
||||
|
||||
:param srcType: Input/output image type. Only ``CV_8UC1`` and ``CV_8UC4`` are supported.
|
||||
|
||||
:param ksize: Kernel size.
|
||||
|
||||
:param anchor: Anchor point. The default value (-1) means that the anchor is at the kernel center.
|
||||
|
||||
:param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
|
||||
|
||||
:param borderVal: Default border value.
|
||||
|
||||
|
||||
|
||||
cuda::createRowSumFilter
|
||||
------------------------
|
||||
Creates a horizontal 1D box filter.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createRowSumFilter(int srcType, int dstType, int ksize, int anchor = -1, int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
|
||||
|
||||
:param srcType: Input image type. Only ``CV_8UC1`` type is supported for now.
|
||||
|
||||
:param sumType: Output image type. Only ``CV_32FC1`` type is supported for now.
|
||||
|
||||
:param ksize: Kernel size.
|
||||
|
||||
:param anchor: Anchor point. The default value (-1) means that the anchor is at the kernel center.
|
||||
|
||||
:param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
|
||||
|
||||
:param borderVal: Default border value.
|
||||
|
||||
|
||||
|
||||
cuda::createColumnSumFilter
|
||||
---------------------------
|
||||
Creates a vertical 1D box filter.
|
||||
|
||||
.. ocv:function:: Ptr<Filter> cuda::createColumnSumFilter(int srcType, int dstType, int ksize, int anchor = -1, int borderMode = BORDER_DEFAULT, Scalar borderVal = Scalar::all(0))
|
||||
|
||||
:param srcType: Input image type. Only ``CV_8UC1`` type is supported for now.
|
||||
|
||||
:param sumType: Output image type. Only ``CV_32FC1`` type is supported for now.
|
||||
|
||||
:param ksize: Kernel size.
|
||||
|
||||
:param anchor: Anchor point. The default value (-1) means that the anchor is at the kernel center.
|
||||
|
||||
:param borderMode: Pixel extrapolation method. For details, see :ocv:func:`borderInterpolate` .
|
||||
|
||||
:param borderVal: Default border value.
|
||||
@@ -1,131 +0,0 @@
|
||||
Color space processing
|
||||
======================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::cvtColor
|
||||
--------------
|
||||
Converts an image from one color space to another.
|
||||
|
||||
.. ocv:function:: void cuda::cvtColor(InputArray src, OutputArray dst, int code, int dcn = 0, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image with ``CV_8U`` , ``CV_16U`` , or ``CV_32F`` depth and 1, 3, or 4 channels.
|
||||
|
||||
:param dst: Destination image.
|
||||
|
||||
:param code: Color space conversion code. For details, see :ocv:func:`cvtColor` .
|
||||
|
||||
:param dcn: Number of channels in the destination image. If the parameter is 0, the number of the channels is derived automatically from ``src`` and the ``code`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
3-channel color spaces (like ``HSV``, ``XYZ``, and so on) can be stored in a 4-channel image for better performance.
|
||||
|
||||
.. seealso:: :ocv:func:`cvtColor`
|
||||
|
||||
|
||||
|
||||
cuda::demosaicing
|
||||
-----------------
|
||||
Converts an image from Bayer pattern to RGB or grayscale.
|
||||
|
||||
.. ocv:function:: void cuda::demosaicing(InputArray src, OutputArray dst, int code, int dcn = -1, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image (8-bit or 16-bit single channel).
|
||||
|
||||
:param dst: Destination image.
|
||||
|
||||
:param code: Color space conversion code (see the description below).
|
||||
|
||||
:param dcn: Number of channels in the destination image. If the parameter is 0, the number of the channels is derived automatically from ``src`` and the ``code`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
The function can do the following transformations:
|
||||
|
||||
* Demosaicing using bilinear interpolation
|
||||
|
||||
* ``COLOR_BayerBG2GRAY`` , ``COLOR_BayerGB2GRAY`` , ``COLOR_BayerRG2GRAY`` , ``COLOR_BayerGR2GRAY``
|
||||
|
||||
* ``COLOR_BayerBG2BGR`` , ``COLOR_BayerGB2BGR`` , ``COLOR_BayerRG2BGR`` , ``COLOR_BayerGR2BGR``
|
||||
|
||||
* Demosaicing using Malvar-He-Cutler algorithm ([MHT2011]_)
|
||||
|
||||
* ``COLOR_BayerBG2GRAY_MHT`` , ``COLOR_BayerGB2GRAY_MHT`` , ``COLOR_BayerRG2GRAY_MHT`` , ``COLOR_BayerGR2GRAY_MHT``
|
||||
|
||||
* ``COLOR_BayerBG2BGR_MHT`` , ``COLOR_BayerGB2BGR_MHT`` , ``COLOR_BayerRG2BGR_MHT`` , ``COLOR_BayerGR2BGR_MHT``
|
||||
|
||||
.. seealso:: :ocv:func:`cvtColor`
|
||||
|
||||
|
||||
|
||||
cuda::swapChannels
|
||||
------------------
|
||||
Exchanges the color channels of an image in-place.
|
||||
|
||||
.. ocv:function:: void cuda::swapChannels(InputOutputArray image, const int dstOrder[4], Stream& stream = Stream::Null())
|
||||
|
||||
:param image: Source image. Supports only ``CV_8UC4`` type.
|
||||
|
||||
:param dstOrder: Integer array describing how channel values are permutated. The n-th entry of the array contains the number of the channel that is stored in the n-th channel of the output image. E.g. Given an RGBA image, aDstOrder = [3,2,1,0] converts this to ABGR channel order.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
The methods support arbitrary permutations of the original channels, including replication.
|
||||
|
||||
|
||||
|
||||
cuda::gammaCorrection
|
||||
---------------------
|
||||
Routines for correcting image color gamma.
|
||||
|
||||
.. ocv:function:: void cuda::gammaCorrection(InputArray src, OutputArray dst, bool forward = true, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image (3- or 4-channel 8 bit).
|
||||
|
||||
:param dst: Destination image.
|
||||
|
||||
:param forward: ``true`` for forward gamma correction or ``false`` for inverse gamma correction.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::alphaComp
|
||||
---------------
|
||||
Composites two images using alpha opacity values contained in each image.
|
||||
|
||||
.. ocv:function:: void cuda::alphaComp(InputArray img1, InputArray img2, OutputArray dst, int alpha_op, Stream& stream = Stream::Null())
|
||||
|
||||
:param img1: First image. Supports ``CV_8UC4`` , ``CV_16UC4`` , ``CV_32SC4`` and ``CV_32FC4`` types.
|
||||
|
||||
:param img2: Second image. Must have the same size and the same type as ``img1`` .
|
||||
|
||||
:param dst: Destination image.
|
||||
|
||||
:param alpha_op: Flag specifying the alpha-blending operation:
|
||||
|
||||
* **ALPHA_OVER**
|
||||
* **ALPHA_IN**
|
||||
* **ALPHA_OUT**
|
||||
* **ALPHA_ATOP**
|
||||
* **ALPHA_XOR**
|
||||
* **ALPHA_PLUS**
|
||||
* **ALPHA_OVER_PREMUL**
|
||||
* **ALPHA_IN_PREMUL**
|
||||
* **ALPHA_OUT_PREMUL**
|
||||
* **ALPHA_ATOP_PREMUL**
|
||||
* **ALPHA_XOR_PREMUL**
|
||||
* **ALPHA_PLUS_PREMUL**
|
||||
* **ALPHA_PREMUL**
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example demonstrating the use of alphaComp can be found at opencv_source_code/samples/gpu/alpha_comp.cpp
|
||||
|
||||
|
||||
.. [MHT2011] Pascal Getreuer, Malvar-He-Cutler Linear Image Demosaicking, Image Processing On Line, 2011
|
||||
@@ -1,12 +0,0 @@
|
||||
**********************************************
|
||||
cudaimgproc. CUDA-accelerated Image Processing
|
||||
**********************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
color
|
||||
histogram
|
||||
hough
|
||||
feature_detection
|
||||
imgproc
|
||||
@@ -1,122 +0,0 @@
|
||||
Feature Detection
|
||||
=================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::CornernessCriteria
|
||||
------------------------
|
||||
.. ocv:class:: cuda::CornernessCriteria : public Algorithm
|
||||
|
||||
Base class for Cornerness Criteria computation. ::
|
||||
|
||||
class CV_EXPORTS CornernessCriteria : public Algorithm
|
||||
{
|
||||
public:
|
||||
virtual void compute(InputArray src, OutputArray dst, Stream& stream = Stream::Null()) = 0;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::CornernessCriteria::compute
|
||||
---------------------------------
|
||||
Computes the cornerness criteria at each image pixel.
|
||||
|
||||
.. ocv:function:: void cuda::CornernessCriteria::compute(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image.
|
||||
|
||||
:param dst: Destination image containing cornerness values. It will have the same size as ``src`` and ``CV_32FC1`` type.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::createHarrisCorner
|
||||
------------------------
|
||||
Creates implementation for Harris cornerness criteria.
|
||||
|
||||
.. ocv:function:: Ptr<CornernessCriteria> cuda::createHarrisCorner(int srcType, int blockSize, int ksize, double k, int borderType = BORDER_REFLECT101)
|
||||
|
||||
:param srcType: Input source type. Only ``CV_8UC1`` and ``CV_32FC1`` are supported for now.
|
||||
|
||||
:param blockSize: Neighborhood size.
|
||||
|
||||
:param ksize: Aperture parameter for the Sobel operator.
|
||||
|
||||
:param k: Harris detector free parameter.
|
||||
|
||||
:param borderType: Pixel extrapolation method. Only ``BORDER_REFLECT101`` and ``BORDER_REPLICATE`` are supported for now.
|
||||
|
||||
.. seealso:: :ocv:func:`cornerHarris`
|
||||
|
||||
|
||||
|
||||
cuda::createMinEigenValCorner
|
||||
-----------------------------
|
||||
Creates implementation for the minimum eigen value of a 2x2 derivative covariation matrix (the cornerness criteria).
|
||||
|
||||
.. ocv:function:: Ptr<CornernessCriteria> cuda::createMinEigenValCorner(int srcType, int blockSize, int ksize, int borderType = BORDER_REFLECT101)
|
||||
|
||||
:param srcType: Input source type. Only ``CV_8UC1`` and ``CV_32FC1`` are supported for now.
|
||||
|
||||
:param blockSize: Neighborhood size.
|
||||
|
||||
:param ksize: Aperture parameter for the Sobel operator.
|
||||
|
||||
:param borderType: Pixel extrapolation method. Only ``BORDER_REFLECT101`` and ``BORDER_REPLICATE`` are supported for now.
|
||||
|
||||
.. seealso:: :ocv:func:`cornerMinEigenVal`
|
||||
|
||||
|
||||
|
||||
cuda::CornersDetector
|
||||
---------------------
|
||||
.. ocv:class:: cuda::CornersDetector : public Algorithm
|
||||
|
||||
Base class for Corners Detector. ::
|
||||
|
||||
class CV_EXPORTS CornersDetector : public Algorithm
|
||||
{
|
||||
public:
|
||||
virtual void detect(InputArray image, OutputArray corners, InputArray mask = noArray()) = 0;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::CornersDetector::detect
|
||||
-----------------------------
|
||||
Determines strong corners on an image.
|
||||
|
||||
.. ocv:function:: void cuda::CornersDetector::detect(InputArray image, OutputArray corners, InputArray mask = noArray())
|
||||
|
||||
:param image: Input 8-bit or floating-point 32-bit, single-channel image.
|
||||
|
||||
:param corners: Output vector of detected corners (1-row matrix with CV_32FC2 type with corners positions).
|
||||
|
||||
:param mask: Optional region of interest. If the image is not empty (it needs to have the type ``CV_8UC1`` and the same size as ``image`` ), it specifies the region in which the corners are detected.
|
||||
|
||||
|
||||
|
||||
cuda::createGoodFeaturesToTrackDetector
|
||||
---------------------------------------
|
||||
Creates implementation for :ocv:class:`cuda::CornersDetector` .
|
||||
|
||||
.. ocv:function:: Ptr<CornersDetector> cuda::createGoodFeaturesToTrackDetector(int srcType, int maxCorners = 1000, double qualityLevel = 0.01, double minDistance = 0.0, int blockSize = 3, bool useHarrisDetector = false, double harrisK = 0.04)
|
||||
|
||||
:param srcType: Input source type. Only ``CV_8UC1`` and ``CV_32FC1`` are supported for now.
|
||||
|
||||
:param maxCorners: Maximum number of corners to return. If there are more corners than are found, the strongest of them is returned.
|
||||
|
||||
:param qualityLevel: Parameter characterizing the minimal accepted quality of image corners. The parameter value is multiplied by the best corner quality measure, which is the minimal eigenvalue (see :ocv:func:`cornerMinEigenVal` ) or the Harris function response (see :ocv:func:`cornerHarris` ). The corners with the quality measure less than the product are rejected. For example, if the best corner has the quality measure = 1500, and the ``qualityLevel=0.01`` , then all the corners with the quality measure less than 15 are rejected.
|
||||
|
||||
:param minDistance: Minimum possible Euclidean distance between the returned corners.
|
||||
|
||||
:param blockSize: Size of an average block for computing a derivative covariation matrix over each pixel neighborhood. See :ocv:func:`cornerEigenValsAndVecs` .
|
||||
|
||||
:param useHarrisDetector: Parameter indicating whether to use a Harris detector (see :ocv:func:`cornerHarris`) or :ocv:func:`cornerMinEigenVal`.
|
||||
|
||||
:param harrisK: Free parameter of the Harris detector.
|
||||
|
||||
.. seealso:: :ocv:func:`goodFeaturesToTrack`
|
||||
@@ -1,150 +0,0 @@
|
||||
Histogram Calculation
|
||||
=====================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::calcHist
|
||||
--------------
|
||||
Calculates histogram for one channel 8-bit image.
|
||||
|
||||
.. ocv:function:: void cuda::calcHist(InputArray src, OutputArray hist, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image with ``CV_8UC1`` type.
|
||||
|
||||
:param hist: Destination histogram with one row, 256 columns, and the ``CV_32SC1`` type.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::equalizeHist
|
||||
------------------
|
||||
Equalizes the histogram of a grayscale image.
|
||||
|
||||
.. ocv:function:: void cuda::equalizeHist(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::equalizeHist(InputArray src, OutputArray dst, InputOutputArray buf, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image with ``CV_8UC1`` type.
|
||||
|
||||
:param dst: Destination image.
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations (for many calls with the same sizes).
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`equalizeHist`
|
||||
|
||||
|
||||
|
||||
cuda::CLAHE
|
||||
-----------
|
||||
.. ocv:class:: cuda::CLAHE : public cv::CLAHE
|
||||
|
||||
Base class for Contrast Limited Adaptive Histogram Equalization. ::
|
||||
|
||||
class CV_EXPORTS CLAHE : public cv::CLAHE
|
||||
{
|
||||
public:
|
||||
using cv::CLAHE::apply;
|
||||
virtual void apply(InputArray src, OutputArray dst, Stream& stream) = 0;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::CLAHE::apply
|
||||
------------------
|
||||
Equalizes the histogram of a grayscale image using Contrast Limited Adaptive Histogram Equalization.
|
||||
|
||||
.. ocv:function:: void cuda::CLAHE::apply(InputArray src, OutputArray dst)
|
||||
|
||||
.. ocv:function:: void cuda::CLAHE::apply(InputArray src, OutputArray dst, Stream& stream)
|
||||
|
||||
:param src: Source image with ``CV_8UC1`` type.
|
||||
|
||||
:param dst: Destination image.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::createCLAHE
|
||||
-----------------
|
||||
Creates implementation for :ocv:class:`cuda::CLAHE` .
|
||||
|
||||
.. ocv:function:: Ptr<cuda::CLAHE> createCLAHE(double clipLimit = 40.0, Size tileGridSize = Size(8, 8))
|
||||
|
||||
:param clipLimit: Threshold for contrast limiting.
|
||||
|
||||
:param tileGridSize: Size of grid for histogram equalization. Input image will be divided into equally sized rectangular tiles. ``tileGridSize`` defines the number of tiles in row and column.
|
||||
|
||||
|
||||
|
||||
|
||||
cuda::evenLevels
|
||||
----------------
|
||||
Computes levels with even distribution.
|
||||
|
||||
.. ocv:function:: void cuda::evenLevels(OutputArray levels, int nLevels, int lowerLevel, int upperLevel)
|
||||
|
||||
:param levels: Destination array. ``levels`` has 1 row, ``nLevels`` columns, and the ``CV_32SC1`` type.
|
||||
|
||||
:param nLevels: Number of computed levels. ``nLevels`` must be at least 2.
|
||||
|
||||
:param lowerLevel: Lower boundary value of the lowest level.
|
||||
|
||||
:param upperLevel: Upper boundary value of the greatest level.
|
||||
|
||||
|
||||
|
||||
cuda::histEven
|
||||
--------------
|
||||
Calculates a histogram with evenly distributed bins.
|
||||
|
||||
.. ocv:function:: void cuda::histEven(InputArray src, OutputArray hist, int histSize, int lowerLevel, int upperLevel, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::histEven(InputArray src, OutputArray hist, InputOutputArray buf, int histSize, int lowerLevel, int upperLevel, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::histEven(InputArray src, GpuMat hist[4], int histSize[4], int lowerLevel[4], int upperLevel[4], Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::histEven(InputArray src, GpuMat hist[4], InputOutputArray buf, int histSize[4], int lowerLevel[4], int upperLevel[4], Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. ``CV_8U``, ``CV_16U``, or ``CV_16S`` depth and 1 or 4 channels are supported. For a four-channel image, all channels are processed separately.
|
||||
|
||||
:param hist: Destination histogram with one row, ``histSize`` columns, and the ``CV_32S`` type.
|
||||
|
||||
:param histSize: Size of the histogram.
|
||||
|
||||
:param lowerLevel: Lower boundary of lowest-level bin.
|
||||
|
||||
:param upperLevel: Upper boundary of highest-level bin.
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations (for many calls with the same sizes).
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::histRange
|
||||
---------------
|
||||
Calculates a histogram with bins determined by the ``levels`` array.
|
||||
|
||||
.. ocv:function:: void cuda::histRange(InputArray src, OutputArray hist, InputArray levels, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::histRange(InputArray src, OutputArray hist, InputArray levels, InputOutputArray buf, Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::histRange(InputArray src, GpuMat hist[4], const GpuMat levels[4], Stream& stream = Stream::Null())
|
||||
|
||||
.. ocv:function:: void cuda::histRange(InputArray src, GpuMat hist[4], const GpuMat levels[4], InputOutputArray buf, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. ``CV_8U`` , ``CV_16U`` , or ``CV_16S`` depth and 1 or 4 channels are supported. For a four-channel image, all channels are processed separately.
|
||||
|
||||
:param hist: Destination histogram with one row, ``(levels.cols-1)`` columns, and the ``CV_32SC1`` type.
|
||||
|
||||
:param levels: Number of levels in the histogram.
|
||||
|
||||
:param buf: Optional buffer to avoid extra memory allocations (for many calls with the same sizes).
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
@@ -1,236 +0,0 @@
|
||||
Hough Transform
|
||||
===============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::HoughLinesDetector
|
||||
------------------------
|
||||
.. ocv:class:: cuda::HoughLinesDetector : public Algorithm
|
||||
|
||||
Base class for lines detector algorithm. ::
|
||||
|
||||
class CV_EXPORTS HoughLinesDetector : public Algorithm
|
||||
{
|
||||
public:
|
||||
virtual void detect(InputArray src, OutputArray lines) = 0;
|
||||
virtual void downloadResults(InputArray d_lines, OutputArray h_lines, OutputArray h_votes = noArray()) = 0;
|
||||
|
||||
virtual void setRho(float rho) = 0;
|
||||
virtual float getRho() const = 0;
|
||||
|
||||
virtual void setTheta(float theta) = 0;
|
||||
virtual float getTheta() const = 0;
|
||||
|
||||
virtual void setThreshold(int threshold) = 0;
|
||||
virtual int getThreshold() const = 0;
|
||||
|
||||
virtual void setDoSort(bool doSort) = 0;
|
||||
virtual bool getDoSort() const = 0;
|
||||
|
||||
virtual void setMaxLines(int maxLines) = 0;
|
||||
virtual int getMaxLines() const = 0;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::HoughLinesDetector::detect
|
||||
--------------------------------
|
||||
Finds lines in a binary image using the classical Hough transform.
|
||||
|
||||
.. ocv:function:: void cuda::HoughLinesDetector::detect(InputArray src, OutputArray lines)
|
||||
|
||||
:param src: 8-bit, single-channel binary source image.
|
||||
|
||||
:param lines: Output vector of lines. Each line is represented by a two-element vector :math:`(\rho, \theta)` . :math:`\rho` is the distance from the coordinate origin :math:`(0,0)` (top-left corner of the image). :math:`\theta` is the line rotation angle in radians ( :math:`0 \sim \textrm{vertical line}, \pi/2 \sim \textrm{horizontal line}` ).
|
||||
|
||||
.. seealso:: :ocv:func:`HoughLines`
|
||||
|
||||
|
||||
|
||||
cuda::HoughLinesDetector::downloadResults
|
||||
-----------------------------------------
|
||||
Downloads results from :ocv:func:`cuda::HoughLinesDetector::detect` to host memory.
|
||||
|
||||
.. ocv:function:: void cuda::HoughLinesDetector::downloadResults(InputArray d_lines, OutputArray h_lines, OutputArray h_votes = noArray())
|
||||
|
||||
:param d_lines: Result of :ocv:func:`cuda::HoughLinesDetector::detect` .
|
||||
|
||||
:param h_lines: Output host array.
|
||||
|
||||
:param h_votes: Optional output array for line's votes.
|
||||
|
||||
|
||||
|
||||
cuda::createHoughLinesDetector
|
||||
------------------------------
|
||||
Creates implementation for :ocv:class:`cuda::HoughLinesDetector` .
|
||||
|
||||
.. ocv:function:: Ptr<HoughLinesDetector> cuda::createHoughLinesDetector(float rho, float theta, int threshold, bool doSort = false, int maxLines = 4096)
|
||||
|
||||
:param rho: Distance resolution of the accumulator in pixels.
|
||||
|
||||
:param theta: Angle resolution of the accumulator in radians.
|
||||
|
||||
:param threshold: Accumulator threshold parameter. Only those lines are returned that get enough votes ( :math:`>\texttt{threshold}` ).
|
||||
|
||||
:param doSort: Performs lines sort by votes.
|
||||
|
||||
:param maxLines: Maximum number of output lines.
|
||||
|
||||
|
||||
|
||||
cuda::HoughSegmentDetector
|
||||
--------------------------
|
||||
.. ocv:class:: cuda::HoughSegmentDetector : public Algorithm
|
||||
|
||||
Base class for line segments detector algorithm. ::
|
||||
|
||||
class CV_EXPORTS HoughSegmentDetector : public Algorithm
|
||||
{
|
||||
public:
|
||||
virtual void detect(InputArray src, OutputArray lines) = 0;
|
||||
|
||||
virtual void setRho(float rho) = 0;
|
||||
virtual float getRho() const = 0;
|
||||
|
||||
virtual void setTheta(float theta) = 0;
|
||||
virtual float getTheta() const = 0;
|
||||
|
||||
virtual void setMinLineLength(int minLineLength) = 0;
|
||||
virtual int getMinLineLength() const = 0;
|
||||
|
||||
virtual void setMaxLineGap(int maxLineGap) = 0;
|
||||
virtual int getMaxLineGap() const = 0;
|
||||
|
||||
virtual void setMaxLines(int maxLines) = 0;
|
||||
virtual int getMaxLines() const = 0;
|
||||
};
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the Hough segment detector can be found at opencv_source_code/samples/gpu/houghlines.cpp
|
||||
|
||||
|
||||
cuda::HoughSegmentDetector::detect
|
||||
----------------------------------
|
||||
Finds line segments in a binary image using the probabilistic Hough transform.
|
||||
|
||||
.. ocv:function:: void cuda::HoughSegmentDetector::detect(InputArray src, OutputArray lines)
|
||||
|
||||
:param src: 8-bit, single-channel binary source image.
|
||||
|
||||
:param lines: Output vector of lines. Each line is represented by a 4-element vector :math:`(x_1, y_1, x_2, y_2)` , where :math:`(x_1,y_1)` and :math:`(x_2, y_2)` are the ending points of each detected line segment.
|
||||
|
||||
.. seealso:: :ocv:func:`HoughLinesP`
|
||||
|
||||
|
||||
|
||||
cuda::createHoughSegmentDetector
|
||||
--------------------------------
|
||||
Creates implementation for :ocv:class:`cuda::HoughSegmentDetector` .
|
||||
|
||||
.. ocv:function:: Ptr<HoughSegmentDetector> cuda::createHoughSegmentDetector(float rho, float theta, int minLineLength, int maxLineGap, int maxLines = 4096)
|
||||
|
||||
:param rho: Distance resolution of the accumulator in pixels.
|
||||
|
||||
:param theta: Angle resolution of the accumulator in radians.
|
||||
|
||||
:param minLineLength: Minimum line length. Line segments shorter than that are rejected.
|
||||
|
||||
:param maxLineGap: Maximum allowed gap between points on the same line to link them.
|
||||
|
||||
:param maxLines: Maximum number of output lines.
|
||||
|
||||
|
||||
|
||||
cuda::HoughCirclesDetector
|
||||
--------------------------
|
||||
.. ocv:class:: cuda::HoughCirclesDetector : public Algorithm
|
||||
|
||||
Base class for circles detector algorithm. ::
|
||||
|
||||
class CV_EXPORTS HoughCirclesDetector : public Algorithm
|
||||
{
|
||||
public:
|
||||
virtual void detect(InputArray src, OutputArray circles) = 0;
|
||||
|
||||
virtual void setDp(float dp) = 0;
|
||||
virtual float getDp() const = 0;
|
||||
|
||||
virtual void setMinDist(float minDist) = 0;
|
||||
virtual float getMinDist() const = 0;
|
||||
|
||||
virtual void setCannyThreshold(int cannyThreshold) = 0;
|
||||
virtual int getCannyThreshold() const = 0;
|
||||
|
||||
virtual void setVotesThreshold(int votesThreshold) = 0;
|
||||
virtual int getVotesThreshold() const = 0;
|
||||
|
||||
virtual void setMinRadius(int minRadius) = 0;
|
||||
virtual int getMinRadius() const = 0;
|
||||
|
||||
virtual void setMaxRadius(int maxRadius) = 0;
|
||||
virtual int getMaxRadius() const = 0;
|
||||
|
||||
virtual void setMaxCircles(int maxCircles) = 0;
|
||||
virtual int getMaxCircles() const = 0;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::HoughCirclesDetector::detect
|
||||
----------------------------------
|
||||
Finds circles in a grayscale image using the Hough transform.
|
||||
|
||||
.. ocv:function:: void cuda::HoughCirclesDetector::detect(InputArray src, OutputArray circles)
|
||||
|
||||
:param src: 8-bit, single-channel grayscale input image.
|
||||
|
||||
:param circles: Output vector of found circles. Each vector is encoded as a 3-element floating-point vector :math:`(x, y, radius)` .
|
||||
|
||||
.. seealso:: :ocv:func:`HoughCircles`
|
||||
|
||||
|
||||
|
||||
cuda::createHoughCirclesDetector
|
||||
--------------------------------
|
||||
Creates implementation for :ocv:class:`cuda::HoughCirclesDetector` .
|
||||
|
||||
.. ocv:function:: Ptr<HoughCirclesDetector> cuda::createHoughCirclesDetector(float dp, float minDist, int cannyThreshold, int votesThreshold, int minRadius, int maxRadius, int maxCircles = 4096)
|
||||
|
||||
:param dp: Inverse ratio of the accumulator resolution to the image resolution. For example, if ``dp=1`` , the accumulator has the same resolution as the input image. If ``dp=2`` , the accumulator has half as big width and height.
|
||||
|
||||
:param minDist: Minimum distance between the centers of the detected circles. If the parameter is too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is too large, some circles may be missed.
|
||||
|
||||
:param cannyThreshold: The higher threshold of the two passed to Canny edge detector (the lower one is twice smaller).
|
||||
|
||||
:param votesThreshold: The accumulator threshold for the circle centers at the detection stage. The smaller it is, the more false circles may be detected.
|
||||
|
||||
:param minRadius: Minimum circle radius.
|
||||
|
||||
:param maxRadius: Maximum circle radius.
|
||||
|
||||
:param maxCircles: Maximum number of output circles.
|
||||
|
||||
|
||||
|
||||
cuda::createGeneralizedHoughBallard
|
||||
-----------------------------------
|
||||
Creates implementation for generalized hough transform from [Ballard1981]_ .
|
||||
|
||||
.. ocv:function:: Ptr<GeneralizedHoughBallard> cuda::createGeneralizedHoughBallard()
|
||||
|
||||
|
||||
|
||||
cuda::createGeneralizedHoughGuil
|
||||
--------------------------------
|
||||
Creates implementation for generalized hough transform from [Guil1999]_ .
|
||||
|
||||
.. ocv:function:: Ptr<GeneralizedHoughGuil> cuda::createGeneralizedHoughGuil()
|
||||
|
||||
|
||||
|
||||
.. [Ballard1981] Ballard, D.H. (1981). Generalizing the Hough transform to detect arbitrary shapes. Pattern Recognition 13 (2): 111-122.
|
||||
.. [Guil1999] Guil, N., González-Linares, J.M. and Zapata, E.L. (1999). Bidimensional shape detection using an invariant approach. Pattern Recognition 32 (6): 1025-1038.
|
||||
@@ -1,231 +0,0 @@
|
||||
Image Processing
|
||||
================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::CannyEdgeDetector
|
||||
-----------------------
|
||||
.. ocv:class:: cuda::CannyEdgeDetector : public Algorithm
|
||||
|
||||
Base class for Canny Edge Detector. ::
|
||||
|
||||
class CV_EXPORTS CannyEdgeDetector : public Algorithm
|
||||
{
|
||||
public:
|
||||
virtual void detect(InputArray image, OutputArray edges) = 0;
|
||||
virtual void detect(InputArray dx, InputArray dy, OutputArray edges) = 0;
|
||||
|
||||
virtual void setLowThreshold(double low_thresh) = 0;
|
||||
virtual double getLowThreshold() const = 0;
|
||||
|
||||
virtual void setHighThreshold(double high_thresh) = 0;
|
||||
virtual double getHighThreshold() const = 0;
|
||||
|
||||
virtual void setAppertureSize(int apperture_size) = 0;
|
||||
virtual int getAppertureSize() const = 0;
|
||||
|
||||
virtual void setL2Gradient(bool L2gradient) = 0;
|
||||
virtual bool getL2Gradient() const = 0;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::CannyEdgeDetector::detect
|
||||
-------------------------------
|
||||
Finds edges in an image using the [Canny86]_ algorithm.
|
||||
|
||||
.. ocv:function:: void cuda::CannyEdgeDetector::detect(InputArray image, OutputArray edges)
|
||||
|
||||
.. ocv:function:: void cuda::CannyEdgeDetector::detect(InputArray dx, InputArray dy, OutputArray edges)
|
||||
|
||||
:param image: Single-channel 8-bit input image.
|
||||
|
||||
:param dx: First derivative of image in the vertical direction. Support only ``CV_32S`` type.
|
||||
|
||||
:param dy: First derivative of image in the horizontal direction. Support only ``CV_32S`` type.
|
||||
|
||||
:param edges: Output edge map. It has the same size and type as ``image`` .
|
||||
|
||||
|
||||
|
||||
cuda::createCannyEdgeDetector
|
||||
-----------------------------
|
||||
Creates implementation for :ocv:class:`cuda::CannyEdgeDetector` .
|
||||
|
||||
.. ocv:function:: Ptr<CannyEdgeDetector> cuda::createCannyEdgeDetector(double low_thresh, double high_thresh, int apperture_size = 3, bool L2gradient = false)
|
||||
|
||||
:param low_thresh: First threshold for the hysteresis procedure.
|
||||
|
||||
:param high_thresh: Second threshold for the hysteresis procedure.
|
||||
|
||||
:param apperture_size: Aperture size for the :ocv:func:`Sobel` operator.
|
||||
|
||||
:param L2gradient: Flag indicating whether a more accurate :math:`L_2` norm :math:`=\sqrt{(dI/dx)^2 + (dI/dy)^2}` should be used to compute the image gradient magnitude ( ``L2gradient=true`` ), or a faster default :math:`L_1` norm :math:`=|dI/dx|+|dI/dy|` is enough ( ``L2gradient=false`` ).
|
||||
|
||||
|
||||
|
||||
cuda::meanShiftFiltering
|
||||
------------------------
|
||||
Performs mean-shift filtering for each point of the source image.
|
||||
|
||||
.. ocv:function:: void cuda::meanShiftFiltering(InputArray src, OutputArray dst, int sp, int sr, TermCriteria criteria = TermCriteria(TermCriteria::MAX_ITER + TermCriteria::EPS, 5, 1), Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. Only ``CV_8UC4`` images are supported for now.
|
||||
|
||||
:param dst: Destination image containing the color of mapped points. It has the same size and type as ``src`` .
|
||||
|
||||
:param sp: Spatial window radius.
|
||||
|
||||
:param sr: Color window radius.
|
||||
|
||||
:param criteria: Termination criteria. See :ocv:class:`TermCriteria`.
|
||||
|
||||
It maps each point of the source image into another point. As a result, you have a new color and new position of each point.
|
||||
|
||||
|
||||
|
||||
cuda::meanShiftProc
|
||||
-------------------
|
||||
Performs a mean-shift procedure and stores information about processed points (their colors and positions) in two images.
|
||||
|
||||
.. ocv:function:: void cuda::meanShiftProc(InputArray src, OutputArray dstr, OutputArray dstsp, int sp, int sr, TermCriteria criteria = TermCriteria(TermCriteria::MAX_ITER + TermCriteria::EPS, 5, 1), Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. Only ``CV_8UC4`` images are supported for now.
|
||||
|
||||
:param dstr: Destination image containing the color of mapped points. The size and type is the same as ``src`` .
|
||||
|
||||
:param dstsp: Destination image containing the position of mapped points. The size is the same as ``src`` size. The type is ``CV_16SC2`` .
|
||||
|
||||
:param sp: Spatial window radius.
|
||||
|
||||
:param sr: Color window radius.
|
||||
|
||||
:param criteria: Termination criteria. See :ocv:class:`TermCriteria`.
|
||||
|
||||
.. seealso:: :ocv:func:`cuda::meanShiftFiltering`
|
||||
|
||||
|
||||
|
||||
cuda::meanShiftSegmentation
|
||||
---------------------------
|
||||
Performs a mean-shift segmentation of the source image and eliminates small segments.
|
||||
|
||||
.. ocv:function:: void cuda::meanShiftSegmentation(InputArray src, OutputArray dst, int sp, int sr, int minsize, TermCriteria criteria = TermCriteria(TermCriteria::MAX_ITER + TermCriteria::EPS, 5, 1))
|
||||
|
||||
:param src: Source image. Only ``CV_8UC4`` images are supported for now.
|
||||
|
||||
:param dst: Segmented image with the same size and type as ``src`` (host memory).
|
||||
|
||||
:param sp: Spatial window radius.
|
||||
|
||||
:param sr: Color window radius.
|
||||
|
||||
:param minsize: Minimum segment size. Smaller segments are merged.
|
||||
|
||||
:param criteria: Termination criteria. See :ocv:class:`TermCriteria`.
|
||||
|
||||
|
||||
|
||||
cuda::TemplateMatching
|
||||
----------------------
|
||||
.. ocv:class:: cuda::TemplateMatching : public Algorithm
|
||||
|
||||
Base class for Template Matching. ::
|
||||
|
||||
class CV_EXPORTS TemplateMatching : public Algorithm
|
||||
{
|
||||
public:
|
||||
virtual void match(InputArray image, InputArray templ, OutputArray result, Stream& stream = Stream::Null()) = 0;
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::TemplateMatching::match
|
||||
-----------------------------
|
||||
Computes a proximity map for a raster template and an image where the template is searched for.
|
||||
|
||||
.. ocv:function:: void cuda::TemplateMatching::match(InputArray image, InputArray templ, OutputArray result, Stream& stream = Stream::Null())
|
||||
|
||||
:param image: Source image.
|
||||
|
||||
:param templ: Template image with the size and type the same as ``image`` .
|
||||
|
||||
:param result: Map containing comparison results ( ``CV_32FC1`` ). If ``image`` is *W x H* and ``templ`` is *w x h*, then ``result`` must be *W-w+1 x H-h+1*.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::createTemplateMatching
|
||||
----------------------------
|
||||
Creates implementation for :ocv:class:`cuda::TemplateMatching` .
|
||||
|
||||
.. ocv:function:: Ptr<TemplateMatching> cuda::createTemplateMatching(int srcType, int method, Size user_block_size = Size())
|
||||
|
||||
:param srcType: Input source type. ``CV_32F`` and ``CV_8U`` depth images (1..4 channels) are supported for now.
|
||||
|
||||
:param method: Specifies the way to compare the template with the image.
|
||||
|
||||
:param user_block_size: You can use field `user_block_size` to set specific block size. If you leave its default value `Size(0,0)` then automatic estimation of block size will be used (which is optimized for speed). By varying `user_block_size` you can reduce memory requirements at the cost of speed.
|
||||
|
||||
The following methods are supported for the ``CV_8U`` depth images for now:
|
||||
|
||||
* ``CV_TM_SQDIFF``
|
||||
* ``CV_TM_SQDIFF_NORMED``
|
||||
* ``CV_TM_CCORR``
|
||||
* ``CV_TM_CCORR_NORMED``
|
||||
* ``CV_TM_CCOEFF``
|
||||
* ``CV_TM_CCOEFF_NORMED``
|
||||
|
||||
The following methods are supported for the ``CV_32F`` images for now:
|
||||
|
||||
* ``CV_TM_SQDIFF``
|
||||
* ``CV_TM_CCORR``
|
||||
|
||||
.. seealso:: :ocv:func:`matchTemplate`
|
||||
|
||||
|
||||
|
||||
cuda::bilateralFilter
|
||||
---------------------
|
||||
Performs bilateral filtering of passed image
|
||||
|
||||
.. ocv:function:: void cuda::bilateralFilter(InputArray src, OutputArray dst, int kernel_size, float sigma_color, float sigma_spatial, int borderMode=BORDER_DEFAULT, Stream& stream=Stream::Null())
|
||||
|
||||
:param src: Source image. Supports only (channles != 2 && depth() != CV_8S && depth() != CV_32S && depth() != CV_64F).
|
||||
|
||||
:param dst: Destination imagwe.
|
||||
|
||||
:param kernel_size: Kernel window size.
|
||||
|
||||
:param sigma_color: Filter sigma in the color space.
|
||||
|
||||
:param sigma_spatial: Filter sigma in the coordinate space.
|
||||
|
||||
:param borderMode: Border type. See :ocv:func:`borderInterpolate` for details. ``BORDER_REFLECT101`` , ``BORDER_REPLICATE`` , ``BORDER_CONSTANT`` , ``BORDER_REFLECT`` and ``BORDER_WRAP`` are supported for now.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`bilateralFilter`
|
||||
|
||||
|
||||
|
||||
cuda::blendLinear
|
||||
-----------------
|
||||
Performs linear blending of two images.
|
||||
|
||||
.. ocv:function:: void cuda::blendLinear(InputArray img1, InputArray img2, InputArray weights1, InputArray weights2, OutputArray result, Stream& stream = Stream::Null())
|
||||
|
||||
:param img1: First image. Supports only ``CV_8U`` and ``CV_32F`` depth.
|
||||
|
||||
:param img2: Second image. Must have the same size and the same type as ``img1`` .
|
||||
|
||||
:param weights1: Weights for first image. Must have tha same size as ``img1`` . Supports only ``CV_32F`` type.
|
||||
|
||||
:param weights2: Weights for second image. Must have tha same size as ``img2`` . Supports only ``CV_32F`` type.
|
||||
|
||||
:param result: Destination image.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
@@ -89,7 +89,7 @@ performance.
|
||||
*/
|
||||
CV_EXPORTS void cvtColor(InputArray src, OutputArray dst, int code, int dcn = 0, Stream& stream = Stream::Null());
|
||||
|
||||
enum
|
||||
enum DemosaicTypes
|
||||
{
|
||||
//! Bayer Demosaicing (Malvar, He, and Cutler)
|
||||
COLOR_BayerBG2BGR_MHT = 256,
|
||||
@@ -156,7 +156,7 @@ CV_EXPORTS void swapChannels(InputOutputArray image, const int dstOrder[4], Stre
|
||||
*/
|
||||
CV_EXPORTS void gammaCorrection(InputArray src, OutputArray dst, bool forward = true, Stream& stream = Stream::Null());
|
||||
|
||||
enum { ALPHA_OVER, ALPHA_IN, ALPHA_OUT, ALPHA_ATOP, ALPHA_XOR, ALPHA_PLUS, ALPHA_OVER_PREMUL, ALPHA_IN_PREMUL, ALPHA_OUT_PREMUL,
|
||||
enum AlphaCompTypes { ALPHA_OVER, ALPHA_IN, ALPHA_OUT, ALPHA_ATOP, ALPHA_XOR, ALPHA_PLUS, ALPHA_OVER_PREMUL, ALPHA_IN_PREMUL, ALPHA_OUT_PREMUL,
|
||||
ALPHA_ATOP_PREMUL, ALPHA_XOR_PREMUL, ALPHA_PLUS_PREMUL, ALPHA_PREMUL};
|
||||
|
||||
/** @brief Composites two images using alpha opacity values contained in each image.
|
||||
|
||||
@@ -1,8 +0,0 @@
|
||||
******************************************
|
||||
cudaoptflow. CUDA-accelerated Optical Flow
|
||||
******************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
optflow
|
||||
@@ -1,232 +0,0 @@
|
||||
Optical Flow
|
||||
============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
.. note::
|
||||
|
||||
* A general optical flow example can be found at opencv_source_code/samples/gpu/optical_flow.cpp
|
||||
* A general optical flow example using the Nvidia API can be found at opencv_source_code/samples/gpu/opticalflow_nvidia_api.cpp
|
||||
|
||||
|
||||
|
||||
cuda::BroxOpticalFlow
|
||||
---------------------
|
||||
.. ocv:class:: cuda::BroxOpticalFlow
|
||||
|
||||
Class computing the optical flow for two images using Brox et al Optical Flow algorithm ([Brox2004]_). ::
|
||||
|
||||
class BroxOpticalFlow
|
||||
{
|
||||
public:
|
||||
BroxOpticalFlow(float alpha_, float gamma_, float scale_factor_, int inner_iterations_, int outer_iterations_, int solver_iterations_);
|
||||
|
||||
//! Compute optical flow
|
||||
//! frame0 - source frame (supports only CV_32FC1 type)
|
||||
//! frame1 - frame to track (with the same size and type as frame0)
|
||||
//! u - flow horizontal component (along x axis)
|
||||
//! v - flow vertical component (along y axis)
|
||||
void operator ()(const GpuMat& frame0, const GpuMat& frame1, GpuMat& u, GpuMat& v, Stream& stream = Stream::Null());
|
||||
|
||||
//! flow smoothness
|
||||
float alpha;
|
||||
|
||||
//! gradient constancy importance
|
||||
float gamma;
|
||||
|
||||
//! pyramid scale factor
|
||||
float scale_factor;
|
||||
|
||||
//! number of lagged non-linearity iterations (inner loop)
|
||||
int inner_iterations;
|
||||
|
||||
//! number of warping iterations (number of pyramid levels)
|
||||
int outer_iterations;
|
||||
|
||||
//! number of linear system solver iterations
|
||||
int solver_iterations;
|
||||
|
||||
GpuMat buf;
|
||||
};
|
||||
|
||||
.. note::
|
||||
|
||||
* An example illustrating the Brox et al optical flow algorithm can be found at opencv_source_code/samples/gpu/brox_optical_flow.cpp
|
||||
|
||||
|
||||
|
||||
cuda::FarnebackOpticalFlow
|
||||
--------------------------
|
||||
.. ocv:class:: cuda::FarnebackOpticalFlow
|
||||
|
||||
Class computing a dense optical flow using the Gunnar Farneback’s algorithm. ::
|
||||
|
||||
class CV_EXPORTS FarnebackOpticalFlow
|
||||
{
|
||||
public:
|
||||
FarnebackOpticalFlow()
|
||||
{
|
||||
numLevels = 5;
|
||||
pyrScale = 0.5;
|
||||
fastPyramids = false;
|
||||
winSize = 13;
|
||||
numIters = 10;
|
||||
polyN = 5;
|
||||
polySigma = 1.1;
|
||||
flags = 0;
|
||||
}
|
||||
|
||||
int numLevels;
|
||||
double pyrScale;
|
||||
bool fastPyramids;
|
||||
int winSize;
|
||||
int numIters;
|
||||
int polyN;
|
||||
double polySigma;
|
||||
int flags;
|
||||
|
||||
void operator ()(const GpuMat &frame0, const GpuMat &frame1, GpuMat &flowx, GpuMat &flowy, Stream &s = Stream::Null());
|
||||
|
||||
void releaseMemory();
|
||||
|
||||
private:
|
||||
/* hidden */
|
||||
};
|
||||
|
||||
|
||||
|
||||
cuda::FarnebackOpticalFlow::operator ()
|
||||
---------------------------------------
|
||||
Computes a dense optical flow using the Gunnar Farneback’s algorithm.
|
||||
|
||||
.. ocv:function:: void cuda::FarnebackOpticalFlow::operator ()(const GpuMat &frame0, const GpuMat &frame1, GpuMat &flowx, GpuMat &flowy, Stream &s = Stream::Null())
|
||||
|
||||
:param frame0: First 8-bit gray-scale input image
|
||||
:param frame1: Second 8-bit gray-scale input image
|
||||
:param flowx: Flow horizontal component
|
||||
:param flowy: Flow vertical component
|
||||
:param s: Stream
|
||||
|
||||
.. seealso:: :ocv:func:`calcOpticalFlowFarneback`
|
||||
|
||||
|
||||
|
||||
cuda::FarnebackOpticalFlow::releaseMemory
|
||||
-----------------------------------------
|
||||
Releases unused auxiliary memory buffers.
|
||||
|
||||
.. ocv:function:: void cuda::FarnebackOpticalFlow::releaseMemory()
|
||||
|
||||
|
||||
|
||||
cuda::PyrLKOpticalFlow
|
||||
----------------------
|
||||
.. ocv:class:: cuda::PyrLKOpticalFlow
|
||||
|
||||
Class used for calculating an optical flow. ::
|
||||
|
||||
class PyrLKOpticalFlow
|
||||
{
|
||||
public:
|
||||
PyrLKOpticalFlow();
|
||||
|
||||
void sparse(const GpuMat& prevImg, const GpuMat& nextImg, const GpuMat& prevPts, GpuMat& nextPts,
|
||||
GpuMat& status, GpuMat* err = 0);
|
||||
|
||||
void dense(const GpuMat& prevImg, const GpuMat& nextImg, GpuMat& u, GpuMat& v, GpuMat* err = 0);
|
||||
|
||||
Size winSize;
|
||||
int maxLevel;
|
||||
int iters;
|
||||
bool useInitialFlow;
|
||||
|
||||
void releaseMemory();
|
||||
};
|
||||
|
||||
The class can calculate an optical flow for a sparse feature set or dense optical flow using the iterative Lucas-Kanade method with pyramids.
|
||||
|
||||
.. seealso:: :ocv:func:`calcOpticalFlowPyrLK`
|
||||
|
||||
.. note::
|
||||
|
||||
* An example of the Lucas Kanade optical flow algorithm can be found at opencv_source_code/samples/gpu/pyrlk_optical_flow.cpp
|
||||
|
||||
|
||||
|
||||
cuda::PyrLKOpticalFlow::sparse
|
||||
------------------------------
|
||||
Calculate an optical flow for a sparse feature set.
|
||||
|
||||
.. ocv:function:: void cuda::PyrLKOpticalFlow::sparse(const GpuMat& prevImg, const GpuMat& nextImg, const GpuMat& prevPts, GpuMat& nextPts, GpuMat& status, GpuMat* err = 0)
|
||||
|
||||
:param prevImg: First 8-bit input image (supports both grayscale and color images).
|
||||
|
||||
:param nextImg: Second input image of the same size and the same type as ``prevImg`` .
|
||||
|
||||
:param prevPts: Vector of 2D points for which the flow needs to be found. It must be one row matrix with CV_32FC2 type.
|
||||
|
||||
:param nextPts: Output vector of 2D points (with single-precision floating-point coordinates) containing the calculated new positions of input features in the second image. When ``useInitialFlow`` is true, the vector must have the same size as in the input.
|
||||
|
||||
:param status: Output status vector (CV_8UC1 type). Each element of the vector is set to 1 if the flow for the corresponding features has been found. Otherwise, it is set to 0.
|
||||
|
||||
:param err: Output vector (CV_32FC1 type) that contains the difference between patches around the original and moved points or min eigen value if ``getMinEigenVals`` is checked. It can be NULL, if not needed.
|
||||
|
||||
.. seealso:: :ocv:func:`calcOpticalFlowPyrLK`
|
||||
|
||||
|
||||
|
||||
cuda::PyrLKOpticalFlow::dense
|
||||
-----------------------------
|
||||
Calculate dense optical flow.
|
||||
|
||||
.. ocv:function:: void cuda::PyrLKOpticalFlow::dense(const GpuMat& prevImg, const GpuMat& nextImg, GpuMat& u, GpuMat& v, GpuMat* err = 0)
|
||||
|
||||
:param prevImg: First 8-bit grayscale input image.
|
||||
|
||||
:param nextImg: Second input image of the same size and the same type as ``prevImg`` .
|
||||
|
||||
:param u: Horizontal component of the optical flow of the same size as input images, 32-bit floating-point, single-channel
|
||||
|
||||
:param v: Vertical component of the optical flow of the same size as input images, 32-bit floating-point, single-channel
|
||||
|
||||
:param err: Output vector (CV_32FC1 type) that contains the difference between patches around the original and moved points or min eigen value if ``getMinEigenVals`` is checked. It can be NULL, if not needed.
|
||||
|
||||
|
||||
|
||||
cuda::PyrLKOpticalFlow::releaseMemory
|
||||
-------------------------------------
|
||||
Releases inner buffers memory.
|
||||
|
||||
.. ocv:function:: void cuda::PyrLKOpticalFlow::releaseMemory()
|
||||
|
||||
|
||||
|
||||
cuda::interpolateFrames
|
||||
-----------------------
|
||||
Interpolates frames (images) using provided optical flow (displacement field).
|
||||
|
||||
.. ocv:function:: void cuda::interpolateFrames(const GpuMat& frame0, const GpuMat& frame1, const GpuMat& fu, const GpuMat& fv, const GpuMat& bu, const GpuMat& bv, float pos, GpuMat& newFrame, GpuMat& buf, Stream& stream = Stream::Null())
|
||||
|
||||
:param frame0: First frame (32-bit floating point images, single channel).
|
||||
|
||||
:param frame1: Second frame. Must have the same type and size as ``frame0`` .
|
||||
|
||||
:param fu: Forward horizontal displacement.
|
||||
|
||||
:param fv: Forward vertical displacement.
|
||||
|
||||
:param bu: Backward horizontal displacement.
|
||||
|
||||
:param bv: Backward vertical displacement.
|
||||
|
||||
:param pos: New frame position.
|
||||
|
||||
:param newFrame: Output image.
|
||||
|
||||
:param buf: Temporary buffer, will have width x 6*height size, CV_32FC1 type and contain 6 GpuMat: occlusion masks for first frame, occlusion masks for second, interpolated forward horizontal flow, interpolated forward vertical flow, interpolated backward horizontal flow, interpolated backward vertical flow.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
.. [Brox2004] T. Brox, A. Bruhn, N. Papenberg, J. Weickert. *High accuracy optical flow estimation based on a theory for warping*. ECCV 2004.
|
||||
@@ -1,8 +0,0 @@
|
||||
**************************************************
|
||||
cudastereo. CUDA-accelerated Stereo Correspondence
|
||||
**************************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
stereo
|
||||
@@ -1,338 +0,0 @@
|
||||
Stereo Correspondence
|
||||
=====================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
.. note::
|
||||
|
||||
* A basic stereo matching example can be found at opencv_source_code/samples/gpu/stereo_match.cpp
|
||||
* A stereo matching example using several GPU's can be found at opencv_source_code/samples/gpu/stereo_multi.cpp
|
||||
* A stereo matching example using several GPU's and driver API can be found at opencv_source_code/samples/gpu/driver_api_stereo_multi.cpp
|
||||
|
||||
|
||||
|
||||
cuda::StereoBM
|
||||
--------------
|
||||
.. ocv:class:: cuda::StereoBM : public cv::StereoBM
|
||||
|
||||
Class computing stereo correspondence (disparity map) using the block matching algorithm. ::
|
||||
|
||||
.. seealso:: :ocv:class:`StereoBM`
|
||||
|
||||
|
||||
|
||||
cuda::createStereoBM
|
||||
--------------------
|
||||
Creates StereoBM object.
|
||||
|
||||
.. ocv:function:: Ptr<cuda::StereoBM> cuda::createStereoBM(int numDisparities = 64, int blockSize = 19)
|
||||
|
||||
:param numDisparities: the disparity search range. For each pixel algorithm will find the best disparity from 0 (default minimum disparity) to ``numDisparities``. The search range can then be shifted by changing the minimum disparity.
|
||||
|
||||
:param blockSize: the linear size of the blocks compared by the algorithm. The size should be odd (as the block is centered at the current pixel). Larger block size implies smoother, though less accurate disparity map. Smaller block size gives more detailed disparity map, but there is higher chance for algorithm to find a wrong correspondence.
|
||||
|
||||
|
||||
|
||||
cuda::StereoBeliefPropagation
|
||||
-----------------------------
|
||||
.. ocv:class:: cuda::StereoBeliefPropagation : public cv::StereoMatcher
|
||||
|
||||
Class computing stereo correspondence using the belief propagation algorithm. ::
|
||||
|
||||
class CV_EXPORTS StereoBeliefPropagation : public cv::StereoMatcher
|
||||
{
|
||||
public:
|
||||
using cv::StereoMatcher::compute;
|
||||
|
||||
virtual void compute(InputArray left, InputArray right, OutputArray disparity, Stream& stream) = 0;
|
||||
|
||||
//! version for user specified data term
|
||||
virtual void compute(InputArray data, OutputArray disparity, Stream& stream = Stream::Null()) = 0;
|
||||
|
||||
//! number of BP iterations on each level
|
||||
virtual int getNumIters() const = 0;
|
||||
virtual void setNumIters(int iters) = 0;
|
||||
|
||||
//! number of levels
|
||||
virtual int getNumLevels() const = 0;
|
||||
virtual void setNumLevels(int levels) = 0;
|
||||
|
||||
//! truncation of data cost
|
||||
virtual double getMaxDataTerm() const = 0;
|
||||
virtual void setMaxDataTerm(double max_data_term) = 0;
|
||||
|
||||
//! data weight
|
||||
virtual double getDataWeight() const = 0;
|
||||
virtual void setDataWeight(double data_weight) = 0;
|
||||
|
||||
//! truncation of discontinuity cost
|
||||
virtual double getMaxDiscTerm() const = 0;
|
||||
virtual void setMaxDiscTerm(double max_disc_term) = 0;
|
||||
|
||||
//! discontinuity single jump
|
||||
virtual double getDiscSingleJump() const = 0;
|
||||
virtual void setDiscSingleJump(double disc_single_jump) = 0;
|
||||
|
||||
virtual int getMsgType() const = 0;
|
||||
virtual void setMsgType(int msg_type) = 0;
|
||||
|
||||
static void estimateRecommendedParams(int width, int height, int& ndisp, int& iters, int& levels);
|
||||
};
|
||||
|
||||
|
||||
The class implements algorithm described in [Felzenszwalb2006]_ . It can compute own data cost (using a truncated linear model) or use a user-provided data cost.
|
||||
|
||||
.. note::
|
||||
|
||||
``StereoBeliefPropagation`` requires a lot of memory for message storage:
|
||||
|
||||
.. math::
|
||||
|
||||
width \_ step \cdot height \cdot ndisp \cdot 4 \cdot (1 + 0.25)
|
||||
|
||||
and for data cost storage:
|
||||
|
||||
.. math::
|
||||
|
||||
width\_step \cdot height \cdot ndisp \cdot (1 + 0.25 + 0.0625 + \dotsm + \frac{1}{4^{levels}})
|
||||
|
||||
``width_step`` is the number of bytes in a line including padding.
|
||||
|
||||
``StereoBeliefPropagation`` uses a truncated linear model for the data cost and discontinuity terms:
|
||||
|
||||
.. math::
|
||||
|
||||
DataCost = data \_ weight \cdot \min ( \lvert Img_Left(x,y)-Img_Right(x-d,y) \rvert , max \_ data \_ term)
|
||||
|
||||
.. math::
|
||||
|
||||
DiscTerm = \min (disc \_ single \_ jump \cdot \lvert f_1-f_2 \rvert , max \_ disc \_ term)
|
||||
|
||||
For more details, see [Felzenszwalb2006]_.
|
||||
|
||||
By default, ``StereoBeliefPropagation`` uses floating-point arithmetics and the ``CV_32FC1`` type for messages. But it can also use fixed-point arithmetics and the ``CV_16SC1`` message type for better performance. To avoid an overflow in this case, the parameters must satisfy the following requirement:
|
||||
|
||||
.. math::
|
||||
|
||||
10 \cdot 2^{levels-1} \cdot max \_ data \_ term < SHRT \_ MAX
|
||||
|
||||
.. seealso:: :ocv:class:`StereoMatcher`
|
||||
|
||||
|
||||
|
||||
cuda::createStereoBeliefPropagation
|
||||
-----------------------------------
|
||||
Creates StereoBeliefPropagation object.
|
||||
|
||||
.. ocv:function:: Ptr<cuda::StereoBeliefPropagation> cuda::createStereoBeliefPropagation(int ndisp = 64, int iters = 5, int levels = 5, int msg_type = CV_32F)
|
||||
|
||||
:param ndisp: Number of disparities.
|
||||
|
||||
:param iters: Number of BP iterations on each level.
|
||||
|
||||
:param levels: Number of levels.
|
||||
|
||||
:param msg_type: Type for messages. ``CV_16SC1`` and ``CV_32FC1`` types are supported.
|
||||
|
||||
|
||||
|
||||
cuda::StereoBeliefPropagation::estimateRecommendedParams
|
||||
--------------------------------------------------------
|
||||
Uses a heuristic method to compute the recommended parameters ( ``ndisp``, ``iters`` and ``levels`` ) for the specified image size ( ``width`` and ``height`` ).
|
||||
|
||||
.. ocv:function:: void cuda::StereoBeliefPropagation::estimateRecommendedParams(int width, int height, int& ndisp, int& iters, int& levels)
|
||||
|
||||
|
||||
|
||||
cuda::StereoBeliefPropagation::compute
|
||||
--------------------------------------
|
||||
Enables the stereo correspondence operator that finds the disparity for the specified data cost.
|
||||
|
||||
.. ocv:function:: void cuda::StereoBeliefPropagation::compute(InputArray data, OutputArray disparity, Stream& stream = Stream::Null())
|
||||
|
||||
:param data: User-specified data cost, a matrix of ``msg_type`` type and ``Size(<image columns>*ndisp, <image rows>)`` size.
|
||||
|
||||
:param disparity: Output disparity map. If ``disparity`` is empty, the output type is ``CV_16SC1`` . Otherwise, the type is retained.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::StereoConstantSpaceBP
|
||||
---------------------------
|
||||
.. ocv:class:: cuda::StereoConstantSpaceBP : public cuda::StereoBeliefPropagation
|
||||
|
||||
Class computing stereo correspondence using the constant space belief propagation algorithm. ::
|
||||
|
||||
class CV_EXPORTS StereoConstantSpaceBP : public cuda::StereoBeliefPropagation
|
||||
{
|
||||
public:
|
||||
//! number of active disparity on the first level
|
||||
virtual int getNrPlane() const = 0;
|
||||
virtual void setNrPlane(int nr_plane) = 0;
|
||||
|
||||
virtual bool getUseLocalInitDataCost() const = 0;
|
||||
virtual void setUseLocalInitDataCost(bool use_local_init_data_cost) = 0;
|
||||
|
||||
static void estimateRecommendedParams(int width, int height, int& ndisp, int& iters, int& levels, int& nr_plane);
|
||||
};
|
||||
|
||||
|
||||
The class implements algorithm described in [Yang2010]_. ``StereoConstantSpaceBP`` supports both local minimum and global minimum data cost initialization algorithms. For more details, see the paper mentioned above. By default, a local algorithm is used. To enable a global algorithm, set ``use_local_init_data_cost`` to ``false`` .
|
||||
|
||||
``StereoConstantSpaceBP`` uses a truncated linear model for the data cost and discontinuity terms:
|
||||
|
||||
.. math::
|
||||
|
||||
DataCost = data \_ weight \cdot \min ( \lvert I_2-I_1 \rvert , max \_ data \_ term)
|
||||
|
||||
.. math::
|
||||
|
||||
DiscTerm = \min (disc \_ single \_ jump \cdot \lvert f_1-f_2 \rvert , max \_ disc \_ term)
|
||||
|
||||
For more details, see [Yang2010]_.
|
||||
|
||||
By default, ``StereoConstantSpaceBP`` uses floating-point arithmetics and the ``CV_32FC1`` type for messages. But it can also use fixed-point arithmetics and the ``CV_16SC1`` message type for better performance. To avoid an overflow in this case, the parameters must satisfy the following requirement:
|
||||
|
||||
.. math::
|
||||
|
||||
10 \cdot 2^{levels-1} \cdot max \_ data \_ term < SHRT \_ MAX
|
||||
|
||||
|
||||
|
||||
cuda::createStereoConstantSpaceBP
|
||||
---------------------------------
|
||||
Creates StereoConstantSpaceBP object.
|
||||
|
||||
.. ocv:function:: Ptr<cuda::StereoConstantSpaceBP> cuda::createStereoConstantSpaceBP(int ndisp = 128, int iters = 8, int levels = 4, int nr_plane = 4, int msg_type = CV_32F)
|
||||
|
||||
:param ndisp: Number of disparities.
|
||||
|
||||
:param iters: Number of BP iterations on each level.
|
||||
|
||||
:param levels: Number of levels.
|
||||
|
||||
:param nr_plane: Number of disparity levels on the first level.
|
||||
|
||||
:param msg_type: Type for messages. ``CV_16SC1`` and ``CV_32FC1`` types are supported.
|
||||
|
||||
|
||||
|
||||
cuda::StereoConstantSpaceBP::estimateRecommendedParams
|
||||
------------------------------------------------------
|
||||
Uses a heuristic method to compute parameters (ndisp, iters, levelsand nrplane) for the specified image size (widthand height).
|
||||
|
||||
.. ocv:function:: void cuda::StereoConstantSpaceBP::estimateRecommendedParams(int width, int height, int& ndisp, int& iters, int& levels, int& nr_plane)
|
||||
|
||||
|
||||
|
||||
cuda::DisparityBilateralFilter
|
||||
------------------------------
|
||||
.. ocv:class:: cuda::DisparityBilateralFilter : public cv::Algorithm
|
||||
|
||||
Class refining a disparity map using joint bilateral filtering. ::
|
||||
|
||||
class CV_EXPORTS DisparityBilateralFilter : public cv::Algorithm
|
||||
{
|
||||
public:
|
||||
//! the disparity map refinement operator. Refine disparity map using joint bilateral filtering given a single color image.
|
||||
//! disparity must have CV_8U or CV_16S type, image must have CV_8UC1 or CV_8UC3 type.
|
||||
virtual void apply(InputArray disparity, InputArray image, OutputArray dst, Stream& stream = Stream::Null()) = 0;
|
||||
|
||||
virtual int getNumDisparities() const = 0;
|
||||
virtual void setNumDisparities(int numDisparities) = 0;
|
||||
|
||||
virtual int getRadius() const = 0;
|
||||
virtual void setRadius(int radius) = 0;
|
||||
|
||||
virtual int getNumIters() const = 0;
|
||||
virtual void setNumIters(int iters) = 0;
|
||||
|
||||
//! truncation of data continuity
|
||||
virtual double getEdgeThreshold() const = 0;
|
||||
virtual void setEdgeThreshold(double edge_threshold) = 0;
|
||||
|
||||
//! truncation of disparity continuity
|
||||
virtual double getMaxDiscThreshold() const = 0;
|
||||
virtual void setMaxDiscThreshold(double max_disc_threshold) = 0;
|
||||
|
||||
//! filter range sigma
|
||||
virtual double getSigmaRange() const = 0;
|
||||
virtual void setSigmaRange(double sigma_range) = 0;
|
||||
};
|
||||
|
||||
|
||||
The class implements [Yang2010]_ algorithm.
|
||||
|
||||
|
||||
|
||||
cuda::createDisparityBilateralFilter
|
||||
------------------------------------
|
||||
Creates DisparityBilateralFilter object.
|
||||
|
||||
.. ocv:function:: Ptr<cuda::DisparityBilateralFilter> cuda::createDisparityBilateralFilter(int ndisp = 64, int radius = 3, int iters = 1)
|
||||
|
||||
:param ndisp: Number of disparities.
|
||||
|
||||
:param radius: Filter radius.
|
||||
|
||||
:param iters: Number of iterations.
|
||||
|
||||
|
||||
|
||||
cuda::DisparityBilateralFilter::apply
|
||||
-------------------------------------
|
||||
Refines a disparity map using joint bilateral filtering.
|
||||
|
||||
.. ocv:function:: void cuda::DisparityBilateralFilter::apply(InputArray disparity, InputArray image, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param disparity: Input disparity map. ``CV_8UC1`` and ``CV_16SC1`` types are supported.
|
||||
|
||||
:param image: Input image. ``CV_8UC1`` and ``CV_8UC3`` types are supported.
|
||||
|
||||
:param dst: Destination disparity map. It has the same size and type as ``disparity`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::reprojectImageTo3D
|
||||
------------------------
|
||||
Reprojects a disparity image to 3D space.
|
||||
|
||||
.. ocv:function:: void cuda::reprojectImageTo3D(InputArray disp, OutputArray xyzw, InputArray Q, int dst_cn = 4, Stream& stream = Stream::Null())
|
||||
|
||||
:param disp: Input disparity image. ``CV_8U`` and ``CV_16S`` types are supported.
|
||||
|
||||
:param xyzw: Output 3- or 4-channel floating-point image of the same size as ``disp`` . Each element of ``xyzw(x,y)`` contains 3D coordinates ``(x,y,z)`` or ``(x,y,z,1)`` of the point ``(x,y)`` , computed from the disparity map.
|
||||
|
||||
:param Q: :math:`4 \times 4` perspective transformation matrix that can be obtained via :ocv:func:`stereoRectify` .
|
||||
|
||||
:param dst_cn: The number of channels for output image. Can be 3 or 4.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`reprojectImageTo3D`
|
||||
|
||||
|
||||
|
||||
cuda::drawColorDisp
|
||||
-------------------
|
||||
Colors a disparity image.
|
||||
|
||||
.. ocv:function:: void cuda::drawColorDisp(InputArray src_disp, OutputArray dst_disp, int ndisp, Stream& stream = Stream::Null())
|
||||
|
||||
:param src_disp: Source disparity image. ``CV_8UC1`` and ``CV_16SC1`` types are supported.
|
||||
|
||||
:param dst_disp: Output disparity image. It has the same size as ``src_disp`` . The type is ``CV_8UC4`` in ``BGRA`` format (alpha = 255).
|
||||
|
||||
:param ndisp: Number of disparities.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
This function draws a colored disparity map by converting disparity values from ``[0..ndisp)`` interval first to ``HSV`` color space (where different disparity values correspond to different hues) and then converting the pixels to ``RGB`` for visualization.
|
||||
|
||||
|
||||
|
||||
.. [Felzenszwalb2006] Pedro F. Felzenszwalb algorithm [Pedro F. Felzenszwalb and Daniel P. Huttenlocher. *Efficient belief propagation for early vision*. International Journal of Computer Vision, 70(1), October 2006
|
||||
.. [Yang2010] Q. Yang, L. Wang, and N. Ahuja. *A constant-space belief propagation algorithm for stereo matching*. In CVPR, 2010.
|
||||
@@ -1,8 +0,0 @@
|
||||
*******************************************
|
||||
cudawarping. CUDA-accelerated Image Warping
|
||||
*******************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
warping
|
||||
@@ -1,251 +0,0 @@
|
||||
Image Warping
|
||||
=============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
cuda::remap
|
||||
-----------
|
||||
Applies a generic geometrical transformation to an image.
|
||||
|
||||
.. ocv:function:: void cuda::remap(InputArray src, OutputArray dst, InputArray xmap, InputArray ymap, int interpolation, int borderMode = BORDER_CONSTANT, Scalar borderValue = Scalar(), Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image.
|
||||
|
||||
:param dst: Destination image with the size the same as ``xmap`` and the type the same as ``src`` .
|
||||
|
||||
:param xmap: X values. Only ``CV_32FC1`` type is supported.
|
||||
|
||||
:param ymap: Y values. Only ``CV_32FC1`` type is supported.
|
||||
|
||||
:param interpolation: Interpolation method (see :ocv:func:`resize` ). ``INTER_NEAREST`` , ``INTER_LINEAR`` and ``INTER_CUBIC`` are supported for now.
|
||||
|
||||
:param borderMode: Pixel extrapolation method (see :ocv:func:`borderInterpolate` ). ``BORDER_REFLECT101`` , ``BORDER_REPLICATE`` , ``BORDER_CONSTANT`` , ``BORDER_REFLECT`` and ``BORDER_WRAP`` are supported for now.
|
||||
|
||||
:param borderValue: Value used in case of a constant border. By default, it is 0.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
The function transforms the source image using the specified map:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \texttt{src} (xmap(x,y), ymap(x,y))
|
||||
|
||||
Values of pixels with non-integer coordinates are computed using the bilinear interpolation.
|
||||
|
||||
.. seealso:: :ocv:func:`remap`
|
||||
|
||||
|
||||
|
||||
cuda::resize
|
||||
------------
|
||||
Resizes an image.
|
||||
|
||||
.. ocv:function:: void cuda::resize(InputArray src, OutputArray dst, Size dsize, double fx=0, double fy=0, int interpolation = INTER_LINEAR, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image.
|
||||
|
||||
:param dst: Destination image with the same type as ``src`` . The size is ``dsize`` (when it is non-zero) or the size is computed from ``src.size()`` , ``fx`` , and ``fy`` .
|
||||
|
||||
:param dsize: Destination image size. If it is zero, it is computed as:
|
||||
|
||||
.. math::
|
||||
\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}
|
||||
|
||||
Either ``dsize`` or both ``fx`` and ``fy`` must be non-zero.
|
||||
|
||||
:param fx: Scale factor along the horizontal axis. If it is zero, it is computed as:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{(double)dsize.width/src.cols}
|
||||
|
||||
:param fy: Scale factor along the vertical axis. If it is zero, it is computed as:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{(double)dsize.height/src.rows}
|
||||
|
||||
:param interpolation: Interpolation method. ``INTER_NEAREST`` , ``INTER_LINEAR`` and ``INTER_CUBIC`` are supported for now.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`resize`
|
||||
|
||||
|
||||
|
||||
cuda::warpAffine
|
||||
----------------
|
||||
Applies an affine transformation to an image.
|
||||
|
||||
.. ocv:function:: void cuda::warpAffine(InputArray src, OutputArray dst, InputArray M, Size dsize, int flags = INTER_LINEAR, int borderMode = BORDER_CONSTANT, Scalar borderValue = Scalar(), Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. ``CV_8U`` , ``CV_16U`` , ``CV_32S`` , or ``CV_32F`` depth and 1, 3, or 4 channels are supported.
|
||||
|
||||
:param dst: Destination image with the same type as ``src`` . The size is ``dsize`` .
|
||||
|
||||
:param M: *2x3* transformation matrix.
|
||||
|
||||
:param dsize: Size of the destination image.
|
||||
|
||||
:param flags: Combination of interpolation methods (see :ocv:func:`resize`) and the optional flag ``WARP_INVERSE_MAP`` specifying that ``M`` is an inverse transformation ( ``dst=>src`` ). Only ``INTER_NEAREST`` , ``INTER_LINEAR`` , and ``INTER_CUBIC`` interpolation methods are supported.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`warpAffine`
|
||||
|
||||
|
||||
|
||||
cuda::buildWarpAffineMaps
|
||||
-------------------------
|
||||
Builds transformation maps for affine transformation.
|
||||
|
||||
.. ocv:function:: void cuda::buildWarpAffineMaps(InputArray M, bool inverse, Size dsize, OutputArray xmap, OutputArray ymap, Stream& stream = Stream::Null())
|
||||
|
||||
:param M: *2x3* transformation matrix.
|
||||
|
||||
:param inverse: Flag specifying that ``M`` is an inverse transformation ( ``dst=>src`` ).
|
||||
|
||||
:param dsize: Size of the destination image.
|
||||
|
||||
:param xmap: X values with ``CV_32FC1`` type.
|
||||
|
||||
:param ymap: Y values with ``CV_32FC1`` type.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`cuda::warpAffine` , :ocv:func:`cuda::remap`
|
||||
|
||||
|
||||
|
||||
cuda::warpPerspective
|
||||
---------------------
|
||||
Applies a perspective transformation to an image.
|
||||
|
||||
.. ocv:function:: void cuda::warpPerspective(InputArray src, OutputArray dst, InputArray M, Size dsize, int flags = INTER_LINEAR, int borderMode = BORDER_CONSTANT, Scalar borderValue = Scalar(), Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. ``CV_8U`` , ``CV_16U`` , ``CV_32S`` , or ``CV_32F`` depth and 1, 3, or 4 channels are supported.
|
||||
|
||||
:param dst: Destination image with the same type as ``src`` . The size is ``dsize`` .
|
||||
|
||||
:param M: *3x3* transformation matrix.
|
||||
|
||||
:param dsize: Size of the destination image.
|
||||
|
||||
:param flags: Combination of interpolation methods (see :ocv:func:`resize` ) and the optional flag ``WARP_INVERSE_MAP`` specifying that ``M`` is the inverse transformation ( ``dst => src`` ). Only ``INTER_NEAREST`` , ``INTER_LINEAR`` , and ``INTER_CUBIC`` interpolation methods are supported.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`warpPerspective`
|
||||
|
||||
|
||||
|
||||
cuda::buildWarpPerspectiveMaps
|
||||
------------------------------
|
||||
Builds transformation maps for perspective transformation.
|
||||
|
||||
.. ocv:function:: void cuda::buildWarpAffineMaps(InputArray M, bool inverse, Size dsize, OutputArray xmap, OutputArray ymap, Stream& stream = Stream::Null())
|
||||
|
||||
:param M: *3x3* transformation matrix.
|
||||
|
||||
:param inverse: Flag specifying that ``M`` is an inverse transformation ( ``dst=>src`` ).
|
||||
|
||||
:param dsize: Size of the destination image.
|
||||
|
||||
:param xmap: X values with ``CV_32FC1`` type.
|
||||
|
||||
:param ymap: Y values with ``CV_32FC1`` type.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`cuda::warpPerspective` , :ocv:func:`cuda::remap`
|
||||
|
||||
|
||||
|
||||
cuda::buildWarpPlaneMaps
|
||||
------------------------
|
||||
Builds plane warping maps.
|
||||
|
||||
.. ocv:function:: void cuda::buildWarpPlaneMaps(Size src_size, Rect dst_roi, InputArray K, InputArray R, InputArray T, float scale, OutputArray map_x, OutputArray map_y, Stream& stream = Stream::Null())
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::buildWarpCylindricalMaps
|
||||
------------------------------
|
||||
Builds cylindrical warping maps.
|
||||
|
||||
.. ocv:function:: void cuda::buildWarpCylindricalMaps(Size src_size, Rect dst_roi, InputArray K, InputArray R, float scale, OutputArray map_x, OutputArray map_y, Stream& stream = Stream::Null())
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::buildWarpSphericalMaps
|
||||
----------------------------
|
||||
Builds spherical warping maps.
|
||||
|
||||
.. ocv:function:: void cuda::buildWarpSphericalMaps(Size src_size, Rect dst_roi, InputArray K, InputArray R, float scale, OutputArray map_x, OutputArray map_y, Stream& stream = Stream::Null())
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
|
||||
|
||||
cuda::rotate
|
||||
------------
|
||||
Rotates an image around the origin (0,0) and then shifts it.
|
||||
|
||||
.. ocv:function:: void cuda::rotate(InputArray src, OutputArray dst, Size dsize, double angle, double xShift = 0, double yShift = 0, int interpolation = INTER_LINEAR, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image. Supports 1, 3 or 4 channels images with ``CV_8U`` , ``CV_16U`` or ``CV_32F`` depth.
|
||||
|
||||
:param dst: Destination image with the same type as ``src`` . The size is ``dsize`` .
|
||||
|
||||
:param dsize: Size of the destination image.
|
||||
|
||||
:param angle: Angle of rotation in degrees.
|
||||
|
||||
:param xShift: Shift along the horizontal axis.
|
||||
|
||||
:param yShift: Shift along the vertical axis.
|
||||
|
||||
:param interpolation: Interpolation method. Only ``INTER_NEAREST`` , ``INTER_LINEAR`` , and ``INTER_CUBIC`` are supported.
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`cuda::warpAffine`
|
||||
|
||||
|
||||
|
||||
cuda::pyrDown
|
||||
-------------
|
||||
Smoothes an image and downsamples it.
|
||||
|
||||
.. ocv:function:: void cuda::pyrDown(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image.
|
||||
|
||||
:param dst: Destination image. Will have ``Size((src.cols+1)/2, (src.rows+1)/2)`` size and the same type as ``src`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`pyrDown`
|
||||
|
||||
|
||||
|
||||
cuda::pyrUp
|
||||
-----------
|
||||
Upsamples an image and then smoothes it.
|
||||
|
||||
.. ocv:function:: void cuda::pyrUp(InputArray src, OutputArray dst, Stream& stream = Stream::Null())
|
||||
|
||||
:param src: Source image.
|
||||
|
||||
:param dst: Destination image. Will have ``Size(src.cols*2, src.rows*2)`` size and the same type as ``src`` .
|
||||
|
||||
:param stream: Stream for the asynchronous version.
|
||||
|
||||
.. seealso:: :ocv:func:`pyrUp`
|
||||
@@ -1,88 +0,0 @@
|
||||
Common Interfaces of Descriptor Extractors
|
||||
==========================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
Extractors of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to easily switch
|
||||
between different algorithms solving the same problem. This section is devoted to computing descriptors
|
||||
represented as vectors in a multidimensional space. All objects that implement the ``vector``
|
||||
descriptor extractors inherit the
|
||||
:ocv:class:`DescriptorExtractor` interface.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example explaining keypoint extraction can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
|
||||
* An example on descriptor evaluation can be found at opencv_source_code/samples/cpp/detector_descriptor_evaluation.cpp
|
||||
|
||||
DescriptorExtractor
|
||||
-------------------
|
||||
.. ocv:class:: DescriptorExtractor : public Algorithm
|
||||
|
||||
Abstract base class for computing descriptors for image keypoints. ::
|
||||
|
||||
class CV_EXPORTS DescriptorExtractor
|
||||
{
|
||||
public:
|
||||
virtual ~DescriptorExtractor();
|
||||
|
||||
void compute( InputArray image, vector<KeyPoint>& keypoints,
|
||||
OutputArray descriptors ) const;
|
||||
void compute( InputArrayOfArrays images, vector<vector<KeyPoint> >& keypoints,
|
||||
OutputArrayOfArrays descriptors ) const;
|
||||
|
||||
virtual void read( const FileNode& );
|
||||
virtual void write( FileStorage& ) const;
|
||||
|
||||
virtual int descriptorSize() const = 0;
|
||||
virtual int descriptorType() const = 0;
|
||||
virtual int defaultNorm() const = 0;
|
||||
|
||||
static Ptr<DescriptorExtractor> create( const String& descriptorExtractorType );
|
||||
|
||||
protected:
|
||||
...
|
||||
};
|
||||
|
||||
|
||||
In this interface, a keypoint descriptor can be represented as a
|
||||
dense, fixed-dimension vector of a basic type. Most descriptors
|
||||
follow this pattern as it simplifies computing
|
||||
distances between descriptors. Therefore, a collection of
|
||||
descriptors is represented as
|
||||
:ocv:class:`Mat` , where each row is a keypoint descriptor.
|
||||
|
||||
|
||||
|
||||
DescriptorExtractor::compute
|
||||
--------------------------------
|
||||
Computes the descriptors for a set of keypoints detected in an image (first variant) or image set (second variant).
|
||||
|
||||
.. ocv:function:: void DescriptorExtractor::compute( InputArray image, vector<KeyPoint>& keypoints, OutputArray descriptors ) const
|
||||
|
||||
.. ocv:function:: void DescriptorExtractor::compute( InputArrayOfArrays images, vector<vector<KeyPoint> >& keypoints, OutputArrayOfArrays descriptors ) const
|
||||
|
||||
.. ocv:pyfunction:: cv2.DescriptorExtractor_create.compute(image, keypoints[, descriptors]) -> keypoints, descriptors
|
||||
|
||||
:param image: Image.
|
||||
|
||||
:param images: Image set.
|
||||
|
||||
:param keypoints: Input collection of keypoints. Keypoints for which a descriptor cannot be computed are removed. Sometimes new keypoints can be added, for example: ``SIFT`` duplicates keypoint with several dominant orientations (for each orientation).
|
||||
|
||||
:param descriptors: Computed descriptors. In the second variant of the method ``descriptors[i]`` are descriptors computed for a ``keypoints[i]``. Row ``j`` is the ``keypoints`` (or ``keypoints[i]``) is the descriptor for keypoint ``j``-th keypoint.
|
||||
|
||||
|
||||
DescriptorExtractor::create
|
||||
-------------------------------
|
||||
Creates a descriptor extractor by name.
|
||||
|
||||
.. ocv:function:: Ptr<DescriptorExtractor> DescriptorExtractor::create( const String& descriptorExtractorType )
|
||||
|
||||
.. ocv:pyfunction:: cv2.DescriptorExtractor_create(descriptorExtractorType) -> retval
|
||||
|
||||
:param descriptorExtractorType: Descriptor extractor type.
|
||||
|
||||
The current implementation supports the following types of a descriptor extractor:
|
||||
|
||||
* ``"BRISK"`` -- :ocv:class:`BRISK`
|
||||
* ``"ORB"`` -- :ocv:class:`ORB`
|
||||
@@ -1,279 +0,0 @@
|
||||
Common Interfaces of Descriptor Matchers
|
||||
========================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
Matchers of keypoint descriptors in OpenCV have wrappers with a common interface that enables you to easily switch
|
||||
between different algorithms solving the same problem. This section is devoted to matching descriptors
|
||||
that are represented as vectors in a multidimensional space. All objects that implement ``vector``
|
||||
descriptor matchers inherit the
|
||||
:ocv:class:`DescriptorMatcher` interface.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example explaining keypoint matching can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
|
||||
* An example on descriptor matching evaluation can be found at opencv_source_code/samples/cpp/detector_descriptor_matcher_evaluation.cpp
|
||||
* An example on one to many image matching can be found at opencv_source_code/samples/cpp/matching_to_many_images.cpp
|
||||
|
||||
DescriptorMatcher
|
||||
-----------------
|
||||
.. ocv:class:: DescriptorMatcher : public Algorithm
|
||||
|
||||
Abstract base class for matching keypoint descriptors. It has two groups
|
||||
of match methods: for matching descriptors of an image with another image or
|
||||
with an image set. ::
|
||||
|
||||
class DescriptorMatcher
|
||||
{
|
||||
public:
|
||||
virtual ~DescriptorMatcher();
|
||||
|
||||
virtual void add( InputArrayOfArrays descriptors );
|
||||
|
||||
const vector<Mat>& getTrainDescriptors() const;
|
||||
virtual void clear();
|
||||
bool empty() const;
|
||||
virtual bool isMaskSupported() const = 0;
|
||||
|
||||
virtual void train();
|
||||
|
||||
/*
|
||||
* Group of methods to match descriptors from an image pair.
|
||||
*/
|
||||
void match( InputArray queryDescriptors, InputArray trainDescriptors,
|
||||
vector<DMatch>& matches, InputArray mask=noArray() ) const;
|
||||
void knnMatch( InputArray queryDescriptors, InputArray trainDescriptors,
|
||||
vector<vector<DMatch> >& matches, int k,
|
||||
InputArray mask=noArray(), bool compactResult=false ) const;
|
||||
void radiusMatch( InputArray queryDescriptors, InputArray trainDescriptors,
|
||||
vector<vector<DMatch> >& matches, float maxDistance,
|
||||
InputArray mask=noArray(), bool compactResult=false ) const;
|
||||
/*
|
||||
* Group of methods to match descriptors from one image to an image set.
|
||||
*/
|
||||
void match( InputArray queryDescriptors, vector<DMatch>& matches,
|
||||
InputArrayOfArrays masks=noArray() );
|
||||
void knnMatch( InputArray queryDescriptors, vector<vector<DMatch> >& matches,
|
||||
int k, InputArrayOfArrays masks=noArray(),
|
||||
bool compactResult=false );
|
||||
void radiusMatch( InputArray queryDescriptors, vector<vector<DMatch> >& matches,
|
||||
float maxDistance, InputArrayOfArrays masks=noArray(),
|
||||
bool compactResult=false );
|
||||
|
||||
virtual void read( const FileNode& );
|
||||
virtual void write( FileStorage& ) const;
|
||||
|
||||
virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const = 0;
|
||||
|
||||
static Ptr<DescriptorMatcher> create( const String& descriptorMatcherType );
|
||||
|
||||
protected:
|
||||
vector<Mat> trainDescCollection;
|
||||
vector<UMat> utrainDescCollection;
|
||||
...
|
||||
};
|
||||
|
||||
|
||||
DescriptorMatcher::add
|
||||
--------------------------
|
||||
Adds descriptors to train a CPU(``trainDescCollectionis``) or GPU(``utrainDescCollectionis``) descriptor collection. If the collection is not empty, the new descriptors are added to existing train descriptors.
|
||||
|
||||
.. ocv:function:: void DescriptorMatcher::add( InputArrayOfArrays descriptors )
|
||||
|
||||
:param descriptors: Descriptors to add. Each ``descriptors[i]`` is a set of descriptors from the same train image.
|
||||
|
||||
|
||||
DescriptorMatcher::getTrainDescriptors
|
||||
------------------------------------------
|
||||
Returns a constant link to the train descriptor collection ``trainDescCollection`` .
|
||||
|
||||
.. ocv:function:: const vector<Mat>& DescriptorMatcher::getTrainDescriptors() const
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
DescriptorMatcher::clear
|
||||
----------------------------
|
||||
Clears the train descriptor collections.
|
||||
|
||||
.. ocv:function:: void DescriptorMatcher::clear()
|
||||
|
||||
|
||||
|
||||
DescriptorMatcher::empty
|
||||
----------------------------
|
||||
Returns true if there are no train descriptors in the both collections.
|
||||
|
||||
.. ocv:function:: bool DescriptorMatcher::empty() const
|
||||
|
||||
|
||||
|
||||
DescriptorMatcher::isMaskSupported
|
||||
--------------------------------------
|
||||
Returns true if the descriptor matcher supports masking permissible matches.
|
||||
|
||||
.. ocv:function:: bool DescriptorMatcher::isMaskSupported()
|
||||
|
||||
|
||||
|
||||
DescriptorMatcher::train
|
||||
----------------------------
|
||||
Trains a descriptor matcher
|
||||
|
||||
.. ocv:function:: void DescriptorMatcher::train()
|
||||
|
||||
Trains a descriptor matcher (for example, the flann index). In all methods to match, the method ``train()`` is run every time before matching. Some descriptor matchers (for example, ``BruteForceMatcher``) have an empty implementation of this method. Other matchers really train their inner structures (for example, ``FlannBasedMatcher`` trains ``flann::Index`` ).
|
||||
|
||||
|
||||
|
||||
DescriptorMatcher::match
|
||||
----------------------------
|
||||
Finds the best match for each descriptor from a query set.
|
||||
|
||||
.. ocv:function:: void DescriptorMatcher::match( InputArray queryDescriptors, InputArray trainDescriptors, vector<DMatch>& matches, InputArray mask=noArray() ) const
|
||||
|
||||
.. ocv:function:: void DescriptorMatcher::match(InputArray queryDescriptors, vector<DMatch>& matches, InputArrayOfArrays masks=noArray() )
|
||||
|
||||
:param queryDescriptors: Query set of descriptors.
|
||||
|
||||
:param trainDescriptors: Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
|
||||
|
||||
:param matches: Matches. If a query descriptor is masked out in ``mask`` , no match is added for this descriptor. So, ``matches`` size may be smaller than the query descriptors count.
|
||||
|
||||
:param mask: Mask specifying permissible matches between an input query and train matrices of descriptors.
|
||||
|
||||
:param masks: Set of masks. Each ``masks[i]`` specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image ``trainDescCollection[i]``.
|
||||
|
||||
In the first variant of this method, the train descriptors are passed as an input argument. In the second variant of the method, train descriptors collection that was set by ``DescriptorMatcher::add`` is used. Optional mask (or masks) can be passed to specify which query and training descriptors can be matched. Namely, ``queryDescriptors[i]`` can be matched with ``trainDescriptors[j]`` only if ``mask.at<uchar>(i,j)`` is non-zero.
|
||||
|
||||
|
||||
|
||||
DescriptorMatcher::knnMatch
|
||||
-------------------------------
|
||||
Finds the k best matches for each descriptor from a query set.
|
||||
|
||||
.. ocv:function:: void DescriptorMatcher::knnMatch(InputArray queryDescriptors, InputArray trainDescriptors, vector<vector<DMatch> >& matches, int k, InputArray mask=noArray(), bool compactResult=false ) const
|
||||
|
||||
.. ocv:function:: void DescriptorMatcher::knnMatch( InputArray queryDescriptors, vector<vector<DMatch> >& matches, int k, InputArrayOfArrays masks=noArray(), bool compactResult=false )
|
||||
|
||||
:param queryDescriptors: Query set of descriptors.
|
||||
|
||||
:param trainDescriptors: Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
|
||||
|
||||
:param mask: Mask specifying permissible matches between an input query and train matrices of descriptors.
|
||||
|
||||
:param masks: Set of masks. Each ``masks[i]`` specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image ``trainDescCollection[i]``.
|
||||
|
||||
:param matches: Matches. Each ``matches[i]`` is k or less matches for the same query descriptor.
|
||||
|
||||
:param k: Count of best matches found per each query descriptor or less if a query descriptor has less than k possible matches in total.
|
||||
|
||||
:param compactResult: Parameter used when the mask (or masks) is not empty. If ``compactResult`` is false, the ``matches`` vector has the same size as ``queryDescriptors`` rows. If ``compactResult`` is true, the ``matches`` vector does not contain matches for fully masked-out query descriptors.
|
||||
|
||||
These extended variants of :ocv:func:`DescriptorMatcher::match` methods find several best matches for each query descriptor. The matches are returned in the distance increasing order. See :ocv:func:`DescriptorMatcher::match` for the details about query and train descriptors.
|
||||
|
||||
|
||||
|
||||
DescriptorMatcher::radiusMatch
|
||||
----------------------------------
|
||||
For each query descriptor, finds the training descriptors not farther than the specified distance.
|
||||
|
||||
.. ocv:function:: void DescriptorMatcher::radiusMatch( InputArray queryDescriptors, InputArray trainDescriptors, vector<vector<DMatch> >& matches, float maxDistance, InputArray mask=noArray(), bool compactResult=false ) const
|
||||
|
||||
.. ocv:function:: void DescriptorMatcher::radiusMatch( InputArray queryDescriptors, vector<vector<DMatch> >& matches, float maxDistance, InputArrayOfArrays masks=noArray(), bool compactResult=false )
|
||||
|
||||
:param queryDescriptors: Query set of descriptors.
|
||||
|
||||
:param trainDescriptors: Train set of descriptors. This set is not added to the train descriptors collection stored in the class object.
|
||||
|
||||
:param mask: Mask specifying permissible matches between an input query and train matrices of descriptors.
|
||||
|
||||
:param masks: Set of masks. Each ``masks[i]`` specifies permissible matches between the input query descriptors and stored train descriptors from the i-th image ``trainDescCollection[i]``.
|
||||
|
||||
:param matches: Found matches.
|
||||
|
||||
:param compactResult: Parameter used when the mask (or masks) is not empty. If ``compactResult`` is false, the ``matches`` vector has the same size as ``queryDescriptors`` rows. If ``compactResult`` is true, the ``matches`` vector does not contain matches for fully masked-out query descriptors.
|
||||
|
||||
:param maxDistance: Threshold for the distance between matched descriptors. Distance means here metric distance (e.g. Hamming distance), not the distance between coordinates (which is measured in Pixels)!
|
||||
|
||||
For each query descriptor, the methods find such training descriptors that the distance between the query descriptor and the training descriptor is equal or smaller than ``maxDistance``. Found matches are returned in the distance increasing order.
|
||||
|
||||
|
||||
|
||||
DescriptorMatcher::clone
|
||||
----------------------------
|
||||
Clones the matcher.
|
||||
|
||||
.. ocv:function:: Ptr<DescriptorMatcher> DescriptorMatcher::clone( bool emptyTrainData=false )
|
||||
|
||||
:param emptyTrainData: If ``emptyTrainData`` is false, the method creates a deep copy of the object, that is, copies both parameters and train data. If ``emptyTrainData`` is true, the method creates an object copy with the current parameters but with empty train data.
|
||||
|
||||
|
||||
|
||||
DescriptorMatcher::create
|
||||
-----------------------------
|
||||
Creates a descriptor matcher of a given type with the default parameters (using default constructor).
|
||||
|
||||
.. ocv:function:: Ptr<DescriptorMatcher> DescriptorMatcher::create( const String& descriptorMatcherType )
|
||||
|
||||
:param descriptorMatcherType: Descriptor matcher type. Now the following matcher types are supported:
|
||||
|
||||
*
|
||||
``BruteForce`` (it uses ``L2`` )
|
||||
*
|
||||
``BruteForce-L1``
|
||||
*
|
||||
``BruteForce-Hamming``
|
||||
*
|
||||
``BruteForce-Hamming(2)``
|
||||
*
|
||||
``FlannBased``
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
BFMatcher
|
||||
-----------------
|
||||
.. ocv:class:: BFMatcher : public DescriptorMatcher
|
||||
|
||||
Brute-force descriptor matcher. For each descriptor in the first set, this matcher finds the closest descriptor in the second set by trying each one. This descriptor matcher supports masking permissible matches of descriptor sets.
|
||||
|
||||
|
||||
BFMatcher::BFMatcher
|
||||
--------------------
|
||||
Brute-force matcher constructor.
|
||||
|
||||
.. ocv:function:: BFMatcher::BFMatcher( int normType=NORM_L2, bool crossCheck=false )
|
||||
|
||||
:param normType: One of ``NORM_L1``, ``NORM_L2``, ``NORM_HAMMING``, ``NORM_HAMMING2``. ``L1`` and ``L2`` norms are preferable choices for SIFT and SURF descriptors, ``NORM_HAMMING`` should be used with ORB, BRISK and BRIEF, ``NORM_HAMMING2`` should be used with ORB when ``WTA_K==3`` or ``4`` (see ORB::ORB constructor description).
|
||||
|
||||
:param crossCheck: If it is false, this is will be default BFMatcher behaviour when it finds the k nearest neighbors for each query descriptor. If ``crossCheck==true``, then the ``knnMatch()`` method with ``k=1`` will only return pairs ``(i,j)`` such that for ``i-th`` query descriptor the ``j-th`` descriptor in the matcher's collection is the nearest and vice versa, i.e. the ``BFMatcher`` will only return consistent pairs. Such technique usually produces best results with minimal number of outliers when there are enough matches. This is alternative to the ratio test, used by D. Lowe in SIFT paper.
|
||||
|
||||
|
||||
FlannBasedMatcher
|
||||
-----------------
|
||||
.. ocv:class:: FlannBasedMatcher : public DescriptorMatcher
|
||||
|
||||
Flann-based descriptor matcher. This matcher trains :ocv:class:`flann::Index_` on a train descriptor collection and calls its nearest search methods to find the best matches. So, this matcher may be faster when matching a large train collection than the brute force matcher. ``FlannBasedMatcher`` does not support masking permissible matches of descriptor sets because ``flann::Index`` does not support this. ::
|
||||
|
||||
class FlannBasedMatcher : public DescriptorMatcher
|
||||
{
|
||||
public:
|
||||
FlannBasedMatcher(
|
||||
const Ptr<flann::IndexParams>& indexParams=new flann::KDTreeIndexParams(),
|
||||
const Ptr<flann::SearchParams>& searchParams=new flann::SearchParams() );
|
||||
|
||||
virtual void add( InputArrayOfArrays descriptors );
|
||||
virtual void clear();
|
||||
|
||||
virtual void train();
|
||||
virtual bool isMaskSupported() const;
|
||||
|
||||
virtual Ptr<DescriptorMatcher> clone( bool emptyTrainData=false ) const;
|
||||
protected:
|
||||
...
|
||||
};
|
||||
|
||||
..
|
||||
@@ -1,179 +0,0 @@
|
||||
Common Interfaces of Feature Detectors
|
||||
======================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
Feature detectors in OpenCV have wrappers with a common interface that enables you to easily switch
|
||||
between different algorithms solving the same problem. All objects that implement keypoint detectors
|
||||
inherit the
|
||||
:ocv:class:`FeatureDetector` interface.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example explaining keypoint detection can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
|
||||
|
||||
FeatureDetector
|
||||
---------------
|
||||
.. ocv:class:: FeatureDetector : public Algorithm
|
||||
|
||||
Abstract base class for 2D image feature detectors. ::
|
||||
|
||||
class CV_EXPORTS FeatureDetector
|
||||
{
|
||||
public:
|
||||
virtual ~FeatureDetector();
|
||||
|
||||
void detect( InputArray image, vector<KeyPoint>& keypoints,
|
||||
InputArray mask=noArray() ) const;
|
||||
|
||||
void detect( InputArrayOfArrays images,
|
||||
vector<vector<KeyPoint> >& keypoints,
|
||||
InputArrayOfArrays masks=noArray() ) const;
|
||||
|
||||
virtual void read(const FileNode&);
|
||||
virtual void write(FileStorage&) const;
|
||||
|
||||
static Ptr<FeatureDetector> create( const String& detectorType );
|
||||
|
||||
protected:
|
||||
...
|
||||
};
|
||||
|
||||
FeatureDetector::detect
|
||||
---------------------------
|
||||
Detects keypoints in an image (first variant) or image set (second variant).
|
||||
|
||||
.. ocv:function:: void FeatureDetector::detect( InputArray image, vector<KeyPoint>& keypoints, InputArray mask=noArray() ) const
|
||||
|
||||
.. ocv:function:: void FeatureDetector::detect( InputArrayOfArrays images, vector<vector<KeyPoint> >& keypoints, InputArrayOfArrays masks=noArray() ) const
|
||||
|
||||
.. ocv:pyfunction:: cv2.FeatureDetector_create.detect(image[, mask]) -> keypoints
|
||||
|
||||
:param image: Image.
|
||||
|
||||
:param images: Image set.
|
||||
|
||||
:param keypoints: The detected keypoints. In the second variant of the method ``keypoints[i]`` is a set of keypoints detected in ``images[i]`` .
|
||||
|
||||
:param mask: Mask specifying where to look for keypoints (optional). It must be a 8-bit integer matrix with non-zero values in the region of interest.
|
||||
|
||||
:param masks: Masks for each input image specifying where to look for keypoints (optional). ``masks[i]`` is a mask for ``images[i]``.
|
||||
|
||||
FastFeatureDetector
|
||||
-------------------
|
||||
.. ocv:class:: FastFeatureDetector : public Feature2D
|
||||
|
||||
Wrapping class for feature detection using the
|
||||
:ocv:func:`FAST` method. ::
|
||||
|
||||
class FastFeatureDetector : public Feature2D
|
||||
{
|
||||
public:
|
||||
static Ptr<FastFeatureDetector> create( int threshold=1, bool nonmaxSuppression=true, type=FastFeatureDetector::TYPE_9_16 );
|
||||
};
|
||||
|
||||
GFTTDetector
|
||||
---------------------------
|
||||
.. ocv:class:: GFTTDetector : public FeatureDetector
|
||||
|
||||
Wrapping class for feature detection using the
|
||||
:ocv:func:`goodFeaturesToTrack` function. ::
|
||||
|
||||
class GFTTDetector : public Feature2D
|
||||
{
|
||||
public:
|
||||
enum { USE_HARRIS_DETECTOR=10000 };
|
||||
static Ptr<GFTTDetector> create( int maxCorners=1000, double qualityLevel=0.01,
|
||||
double minDistance=1, int blockSize=3,
|
||||
bool useHarrisDetector=false, double k=0.04 );
|
||||
};
|
||||
|
||||
MSER
|
||||
-------------------
|
||||
.. ocv:class:: MSER : public Feature2D
|
||||
|
||||
Maximally stable region detector ::
|
||||
|
||||
class MSER : public Feature2D
|
||||
{
|
||||
public:
|
||||
enum
|
||||
{
|
||||
DELTA=10000, MIN_AREA=10001, MAX_AREA=10002, PASS2_ONLY=10003,
|
||||
MAX_EVOLUTION=10004, AREA_THRESHOLD=10005,
|
||||
MIN_MARGIN=10006, EDGE_BLUR_SIZE=10007
|
||||
};
|
||||
|
||||
//! the full constructor
|
||||
static Ptr<MSER> create( int _delta=5, int _min_area=60, int _max_area=14400,
|
||||
double _max_variation=0.25, double _min_diversity=.2,
|
||||
int _max_evolution=200, double _area_threshold=1.01,
|
||||
double _min_margin=0.003, int _edge_blur_size=5 );
|
||||
|
||||
virtual void detectRegions( InputArray image,
|
||||
std::vector<std::vector<Point> >& msers,
|
||||
std::vector<Rect>& bboxes ) = 0;
|
||||
};
|
||||
|
||||
SimpleBlobDetector
|
||||
-------------------
|
||||
.. ocv:class:: SimpleBlobDetector : public FeatureDetector
|
||||
|
||||
Class for extracting blobs from an image. ::
|
||||
|
||||
class SimpleBlobDetector : public FeatureDetector
|
||||
{
|
||||
public:
|
||||
struct Params
|
||||
{
|
||||
Params();
|
||||
float thresholdStep;
|
||||
float minThreshold;
|
||||
float maxThreshold;
|
||||
size_t minRepeatability;
|
||||
float minDistBetweenBlobs;
|
||||
|
||||
bool filterByColor;
|
||||
uchar blobColor;
|
||||
|
||||
bool filterByArea;
|
||||
float minArea, maxArea;
|
||||
|
||||
bool filterByCircularity;
|
||||
float minCircularity, maxCircularity;
|
||||
|
||||
bool filterByInertia;
|
||||
float minInertiaRatio, maxInertiaRatio;
|
||||
|
||||
bool filterByConvexity;
|
||||
float minConvexity, maxConvexity;
|
||||
};
|
||||
|
||||
static Ptr<SimpleBlobDetector> create(const SimpleBlobDetector::Params
|
||||
¶meters = SimpleBlobDetector::Params());
|
||||
};
|
||||
|
||||
The class implements a simple algorithm for extracting blobs from an image:
|
||||
|
||||
#. Convert the source image to binary images by applying thresholding with several thresholds from ``minThreshold`` (inclusive) to ``maxThreshold`` (exclusive) with distance ``thresholdStep`` between neighboring thresholds.
|
||||
|
||||
#. Extract connected components from every binary image by :ocv:func:`findContours` and calculate their centers.
|
||||
|
||||
#. Group centers from several binary images by their coordinates. Close centers form one group that corresponds to one blob, which is controlled by the ``minDistBetweenBlobs`` parameter.
|
||||
|
||||
#. From the groups, estimate final centers of blobs and their radiuses and return as locations and sizes of keypoints.
|
||||
|
||||
This class performs several filtrations of returned blobs. You should set ``filterBy*`` to true/false to turn on/off corresponding filtration. Available filtrations:
|
||||
|
||||
* **By color**. This filter compares the intensity of a binary image at the center of a blob to ``blobColor``. If they differ, the blob is filtered out. Use ``blobColor = 0`` to extract dark blobs and ``blobColor = 255`` to extract light blobs.
|
||||
|
||||
* **By area**. Extracted blobs have an area between ``minArea`` (inclusive) and ``maxArea`` (exclusive).
|
||||
|
||||
* **By circularity**. Extracted blobs have circularity (:math:`\frac{4*\pi*Area}{perimeter * perimeter}`) between ``minCircularity`` (inclusive) and ``maxCircularity`` (exclusive).
|
||||
|
||||
* **By ratio of the minimum inertia to maximum inertia**. Extracted blobs have this ratio between ``minInertiaRatio`` (inclusive) and ``maxInertiaRatio`` (exclusive).
|
||||
|
||||
* **By convexity**. Extracted blobs have convexity (area / area of blob convex hull) between ``minConvexity`` (inclusive) and ``maxConvexity`` (exclusive).
|
||||
|
||||
|
||||
Default values of parameters are tuned to extract dark circular blobs.
|
||||
@@ -1,86 +0,0 @@
|
||||
Drawing Function of Keypoints and Matches
|
||||
=========================================
|
||||
|
||||
|
||||
|
||||
drawMatches
|
||||
---------------
|
||||
Draws the found matches of keypoints from two images.
|
||||
|
||||
.. ocv:function:: void drawMatches( InputArray img1, const vector<KeyPoint>& keypoints1, InputArray img2, const vector<KeyPoint>& keypoints2, const vector<DMatch>& matches1to2, InputOutputArray outImg, const Scalar& matchColor=Scalar::all(-1), const Scalar& singlePointColor=Scalar::all(-1), const vector<char>& matchesMask=vector<char>(), int flags=DrawMatchesFlags::DEFAULT )
|
||||
|
||||
.. ocv:function:: void drawMatches( InputArray img1, const vector<KeyPoint>& keypoints1, InputArray img2, const vector<KeyPoint>& keypoints2, const vector<vector<DMatch> >& matches1to2, InputOutputArray outImg, const Scalar& matchColor=Scalar::all(-1), const Scalar& singlePointColor=Scalar::all(-1), const vector<vector<char> >& matchesMask=vector<vector<char> >(), int flags=DrawMatchesFlags::DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.drawMatches(img1, keypoints1, img2, keypoints2, matches1to2[, outImg[, matchColor[, singlePointColor[, matchesMask[, flags]]]]]) -> outImg
|
||||
|
||||
.. ocv:pyfunction:: cv2.drawMatchesKnn(img1, keypoints1, img2, keypoints2, matches1to2[, outImg[, matchColor[, singlePointColor[, matchesMask[, flags]]]]]) -> outImg
|
||||
|
||||
|
||||
:param img1: First source image.
|
||||
|
||||
:param keypoints1: Keypoints from the first source image.
|
||||
|
||||
:param img2: Second source image.
|
||||
|
||||
:param keypoints2: Keypoints from the second source image.
|
||||
|
||||
:param matches1to2: Matches from the first image to the second one, which means that ``keypoints1[i]`` has a corresponding point in ``keypoints2[matches[i]]`` .
|
||||
|
||||
:param outImg: Output image. Its content depends on the ``flags`` value defining what is drawn in the output image. See possible ``flags`` bit values below.
|
||||
|
||||
:param matchColor: Color of matches (lines and connected keypoints). If ``matchColor==Scalar::all(-1)`` , the color is generated randomly.
|
||||
|
||||
:param singlePointColor: Color of single keypoints (circles), which means that keypoints do not have the matches. If ``singlePointColor==Scalar::all(-1)`` , the color is generated randomly.
|
||||
|
||||
:param matchesMask: Mask determining which matches are drawn. If the mask is empty, all matches are drawn.
|
||||
|
||||
:param flags: Flags setting drawing features. Possible ``flags`` bit values are defined by ``DrawMatchesFlags``.
|
||||
|
||||
This function draws matches of keypoints from two images in the output image. Match is a line connecting two keypoints (circles). The structure ``DrawMatchesFlags`` is defined as follows:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
struct DrawMatchesFlags
|
||||
{
|
||||
enum
|
||||
{
|
||||
DEFAULT = 0, // Output image matrix will be created (Mat::create),
|
||||
// i.e. existing memory of output image may be reused.
|
||||
// Two source images, matches, and single keypoints
|
||||
// will be drawn.
|
||||
// For each keypoint, only the center point will be
|
||||
// drawn (without a circle around the keypoint with the
|
||||
// keypoint size and orientation).
|
||||
DRAW_OVER_OUTIMG = 1, // Output image matrix will not be
|
||||
// created (using Mat::create). Matches will be drawn
|
||||
// on existing content of output image.
|
||||
NOT_DRAW_SINGLE_POINTS = 2, // Single keypoints will not be drawn.
|
||||
DRAW_RICH_KEYPOINTS = 4 // For each keypoint, the circle around
|
||||
// keypoint with keypoint size and orientation will
|
||||
// be drawn.
|
||||
};
|
||||
};
|
||||
|
||||
..
|
||||
|
||||
|
||||
|
||||
drawKeypoints
|
||||
-----------------
|
||||
Draws keypoints.
|
||||
|
||||
.. ocv:function:: void drawKeypoints( InputArray image, const vector<KeyPoint>& keypoints, InputOutputArray outImage, const Scalar& color=Scalar::all(-1), int flags=DrawMatchesFlags::DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.drawKeypoints(image, keypoints[, outImage[, color[, flags]]]) -> outImage
|
||||
|
||||
:param image: Source image.
|
||||
|
||||
:param keypoints: Keypoints from the source image.
|
||||
|
||||
:param outImage: Output image. Its content depends on the ``flags`` value defining what is drawn in the output image. See possible ``flags`` bit values below.
|
||||
|
||||
:param color: Color of keypoints.
|
||||
|
||||
:param flags: Flags setting drawing features. Possible ``flags`` bit values are defined by ``DrawMatchesFlags``. See details above in :ocv:func:`drawMatches` .
|
||||
|
||||
.. note:: For Python API, flags are modified as `cv2.DRAW_MATCHES_FLAGS_DEFAULT`, `cv2.DRAW_MATCHES_FLAGS_DRAW_RICH_KEYPOINTS`, `cv2.DRAW_MATCHES_FLAGS_DRAW_OVER_OUTIMG`, `cv2.DRAW_MATCHES_FLAGS_NOT_DRAW_SINGLE_POINTS`
|
||||
@@ -1,247 +0,0 @@
|
||||
Feature Detection and Description
|
||||
=================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
.. note::
|
||||
|
||||
* An example explaining keypoint detection and description can be found at opencv_source_code/samples/cpp/descriptor_extractor_matcher.cpp
|
||||
|
||||
FAST
|
||||
----
|
||||
Detects corners using the FAST algorithm
|
||||
|
||||
.. ocv:function:: void FAST( InputArray image, vector<KeyPoint>& keypoints, int threshold, bool nonmaxSuppression=true )
|
||||
.. ocv:function:: void FAST( InputArray image, vector<KeyPoint>& keypoints, int threshold, bool nonmaxSuppression, int type )
|
||||
|
||||
:param image: grayscale image where keypoints (corners) are detected.
|
||||
|
||||
:param keypoints: keypoints detected on the image.
|
||||
|
||||
:param threshold: threshold on difference between intensity of the central pixel and pixels of a circle around this pixel.
|
||||
|
||||
:param nonmaxSuppression: if true, non-maximum suppression is applied to detected corners (keypoints).
|
||||
|
||||
:param type: one of the three neighborhoods as defined in the paper: ``FastFeatureDetector::TYPE_9_16``, ``FastFeatureDetector::TYPE_7_12``, ``FastFeatureDetector::TYPE_5_8``
|
||||
|
||||
Detects corners using the FAST algorithm by [Rosten06]_.
|
||||
|
||||
.. note:: In Python API, types are given as ``cv2.FAST_FEATURE_DETECTOR_TYPE_5_8``, ``cv2.FAST_FEATURE_DETECTOR_TYPE_7_12`` and ``cv2.FAST_FEATURE_DETECTOR_TYPE_9_16``. For corner detection, use ``cv2.FAST.detect()`` method.
|
||||
|
||||
|
||||
.. [Rosten06] E. Rosten. Machine Learning for High-speed Corner Detection, 2006.
|
||||
|
||||
MSER
|
||||
----
|
||||
.. ocv:class:: MSER : public FeatureDetector
|
||||
|
||||
Maximally stable extremal region extractor. ::
|
||||
|
||||
class MSER : public CvMSERParams
|
||||
{
|
||||
public:
|
||||
// default constructor
|
||||
MSER();
|
||||
// constructor that initializes all the algorithm parameters
|
||||
MSER( int _delta, int _min_area, int _max_area,
|
||||
float _max_variation, float _min_diversity,
|
||||
int _max_evolution, double _area_threshold,
|
||||
double _min_margin, int _edge_blur_size );
|
||||
// runs the extractor on the specified image; returns the MSERs,
|
||||
// each encoded as a contour (vector<Point>, see findContours)
|
||||
// the optional mask marks the area where MSERs are searched for
|
||||
void detectRegions( InputArray image, vector<vector<Point> >& msers, vector<Rect>& bboxes ) const;
|
||||
};
|
||||
|
||||
The class encapsulates all the parameters of the MSER extraction algorithm (see
|
||||
http://en.wikipedia.org/wiki/Maximally_stable_extremal_regions). Also see http://code.opencv.org/projects/opencv/wiki/MSER for useful comments and parameters description.
|
||||
|
||||
.. note::
|
||||
|
||||
* (Python) A complete example showing the use of the MSER detector can be found at opencv_source_code/samples/python2/mser.py
|
||||
|
||||
|
||||
ORB
|
||||
---
|
||||
.. ocv:class:: ORB : public Feature2D
|
||||
|
||||
Class implementing the ORB (*oriented BRIEF*) keypoint detector and descriptor extractor, described in [RRKB11]_. The algorithm uses FAST in pyramids to detect stable keypoints, selects the strongest features using FAST or Harris response, finds their orientation using first-order moments and computes the descriptors using BRIEF (where the coordinates of random point pairs (or k-tuples) are rotated according to the measured orientation).
|
||||
|
||||
.. [RRKB11] Ethan Rublee, Vincent Rabaud, Kurt Konolige, Gary R. Bradski: ORB: An efficient alternative to SIFT or SURF. ICCV 2011: 2564-2571.
|
||||
|
||||
ORB::ORB
|
||||
--------
|
||||
The ORB constructor
|
||||
|
||||
.. ocv:function:: ORB::ORB(int nfeatures = 500, float scaleFactor = 1.2f, int nlevels = 8, int edgeThreshold = 31, int firstLevel = 0, int WTA_K=2, int scoreType=ORB::HARRIS_SCORE, int patchSize=31)
|
||||
|
||||
.. ocv:pyfunction:: cv2.ORB([, nfeatures[, scaleFactor[, nlevels[, edgeThreshold[, firstLevel[, WTA_K[, scoreType[, patchSize]]]]]]]]) -> <ORB object>
|
||||
|
||||
|
||||
:param nfeatures: The maximum number of features to retain.
|
||||
|
||||
:param scaleFactor: Pyramid decimation ratio, greater than 1. ``scaleFactor==2`` means the classical pyramid, where each next level has 4x less pixels than the previous, but such a big scale factor will degrade feature matching scores dramatically. On the other hand, too close to 1 scale factor will mean that to cover certain scale range you will need more pyramid levels and so the speed will suffer.
|
||||
|
||||
:param nlevels: The number of pyramid levels. The smallest level will have linear size equal to ``input_image_linear_size/pow(scaleFactor, nlevels)``.
|
||||
|
||||
:param edgeThreshold: This is size of the border where the features are not detected. It should roughly match the ``patchSize`` parameter.
|
||||
|
||||
:param firstLevel: It should be 0 in the current implementation.
|
||||
|
||||
:param WTA_K: The number of points that produce each element of the oriented BRIEF descriptor. The default value 2 means the BRIEF where we take a random point pair and compare their brightnesses, so we get 0/1 response. Other possible values are 3 and 4. For example, 3 means that we take 3 random points (of course, those point coordinates are random, but they are generated from the pre-defined seed, so each element of BRIEF descriptor is computed deterministically from the pixel rectangle), find point of maximum brightness and output index of the winner (0, 1 or 2). Such output will occupy 2 bits, and therefore it will need a special variant of Hamming distance, denoted as ``NORM_HAMMING2`` (2 bits per bin). When ``WTA_K=4``, we take 4 random points to compute each bin (that will also occupy 2 bits with possible values 0, 1, 2 or 3).
|
||||
|
||||
:param scoreType: The default HARRIS_SCORE means that Harris algorithm is used to rank features (the score is written to ``KeyPoint::score`` and is used to retain best ``nfeatures`` features); FAST_SCORE is alternative value of the parameter that produces slightly less stable keypoints, but it is a little faster to compute.
|
||||
|
||||
:param patchSize: size of the patch used by the oriented BRIEF descriptor. Of course, on smaller pyramid layers the perceived image area covered by a feature will be larger.
|
||||
|
||||
ORB::operator()
|
||||
---------------
|
||||
Finds keypoints in an image and computes their descriptors
|
||||
|
||||
.. ocv:function:: void ORB::operator()(InputArray image, InputArray mask, vector<KeyPoint>& keypoints, OutputArray descriptors, bool useProvidedKeypoints=false ) const
|
||||
|
||||
.. ocv:pyfunction:: cv2.ORB.detect(image[, mask]) -> keypoints
|
||||
.. ocv:pyfunction:: cv2.ORB.compute(image, keypoints[, descriptors]) -> keypoints, descriptors
|
||||
.. ocv:pyfunction:: cv2.ORB.detectAndCompute(image, mask[, descriptors[, useProvidedKeypoints]]) -> keypoints, descriptors
|
||||
|
||||
|
||||
:param image: The input 8-bit grayscale image.
|
||||
|
||||
:param mask: The operation mask.
|
||||
|
||||
:param keypoints: The output vector of keypoints.
|
||||
|
||||
:param descriptors: The output descriptors. Pass ``cv::noArray()`` if you do not need it.
|
||||
|
||||
:param useProvidedKeypoints: If it is true, then the method will use the provided vector of keypoints instead of detecting them.
|
||||
|
||||
|
||||
BRISK
|
||||
-----
|
||||
.. ocv:class:: BRISK : public Feature2D
|
||||
|
||||
Class implementing the BRISK keypoint detector and descriptor extractor, described in [LCS11]_.
|
||||
|
||||
.. [LCS11] Stefan Leutenegger, Margarita Chli and Roland Siegwart: BRISK: Binary Robust Invariant Scalable Keypoints. ICCV 2011: 2548-2555.
|
||||
|
||||
BRISK::BRISK
|
||||
------------
|
||||
The BRISK constructor
|
||||
|
||||
.. ocv:function:: BRISK::BRISK(int thresh=30, int octaves=3, float patternScale=1.0f)
|
||||
|
||||
.. ocv:pyfunction:: cv2.BRISK([, thresh[, octaves[, patternScale]]]) -> <BRISK object>
|
||||
|
||||
:param thresh: FAST/AGAST detection threshold score.
|
||||
|
||||
:param octaves: detection octaves. Use 0 to do single scale.
|
||||
|
||||
:param patternScale: apply this scale to the pattern used for sampling the neighbourhood of a keypoint.
|
||||
|
||||
BRISK::BRISK
|
||||
------------
|
||||
The BRISK constructor for a custom pattern
|
||||
|
||||
.. ocv:function:: BRISK::BRISK(std::vector<float> &radiusList, std::vector<int> &numberList, float dMax=5.85f, float dMin=8.2f, std::vector<int> indexChange=std::vector<int>())
|
||||
|
||||
.. ocv:pyfunction:: cv2.BRISK(radiusList, numberList[, dMax[, dMin[, indexChange]]]) -> <BRISK object>
|
||||
|
||||
:param radiusList: defines the radii (in pixels) where the samples around a keypoint are taken (for keypoint scale 1).
|
||||
|
||||
:param numberList: defines the number of sampling points on the sampling circle. Must be the same size as radiusList..
|
||||
|
||||
:param dMax: threshold for the short pairings used for descriptor formation (in pixels for keypoint scale 1).
|
||||
|
||||
:param dMin: threshold for the long pairings used for orientation determination (in pixels for keypoint scale 1).
|
||||
|
||||
:param indexChanges: index remapping of the bits.
|
||||
|
||||
BRISK::operator()
|
||||
-----------------
|
||||
Finds keypoints in an image and computes their descriptors
|
||||
|
||||
.. ocv:function:: void BRISK::operator()(InputArray image, InputArray mask, vector<KeyPoint>& keypoints, OutputArray descriptors, bool useProvidedKeypoints=false ) const
|
||||
|
||||
.. ocv:pyfunction:: cv2.BRISK.detect(image[, mask]) -> keypoints
|
||||
.. ocv:pyfunction:: cv2.BRISK.compute(image, keypoints[, descriptors]) -> keypoints, descriptors
|
||||
.. ocv:pyfunction:: cv2.BRISK.detectAndCompute(image, mask[, descriptors[, useProvidedKeypoints]]) -> keypoints, descriptors
|
||||
|
||||
:param image: The input 8-bit grayscale image.
|
||||
|
||||
:param mask: The operation mask.
|
||||
|
||||
:param keypoints: The output vector of keypoints.
|
||||
|
||||
:param descriptors: The output descriptors. Pass ``cv::noArray()`` if you do not need it.
|
||||
|
||||
:param useProvidedKeypoints: If it is true, then the method will use the provided vector of keypoints instead of detecting them.
|
||||
|
||||
KAZE
|
||||
----
|
||||
.. ocv:class:: KAZE : public Feature2D
|
||||
|
||||
Class implementing the KAZE keypoint detector and descriptor extractor, described in [ABD12]_. ::
|
||||
|
||||
class CV_EXPORTS_W KAZE : public Feature2D
|
||||
{
|
||||
public:
|
||||
CV_WRAP KAZE();
|
||||
CV_WRAP explicit KAZE(bool extended, bool upright, float threshold = 0.001f,
|
||||
int octaves = 4, int sublevels = 4, int diffusivity = DIFF_PM_G2);
|
||||
};
|
||||
|
||||
.. note:: AKAZE descriptor can only be used with KAZE or AKAZE keypoints
|
||||
|
||||
.. [ABD12] KAZE Features. Pablo F. Alcantarilla, Adrien Bartoli and Andrew J. Davison. In European Conference on Computer Vision (ECCV), Fiorenze, Italy, October 2012.
|
||||
|
||||
KAZE::KAZE
|
||||
----------
|
||||
The KAZE constructor
|
||||
|
||||
.. ocv:function:: KAZE::KAZE(bool extended, bool upright, float threshold, int octaves, int sublevels, int diffusivity)
|
||||
|
||||
:param extended: Set to enable extraction of extended (128-byte) descriptor.
|
||||
:param upright: Set to enable use of upright descriptors (non rotation-invariant).
|
||||
:param threshold: Detector response threshold to accept point
|
||||
:param octaves: Maximum octave evolution of the image
|
||||
:param sublevels: Default number of sublevels per scale level
|
||||
:param diffusivity: Diffusivity type. DIFF_PM_G1, DIFF_PM_G2, DIFF_WEICKERT or DIFF_CHARBONNIER
|
||||
|
||||
AKAZE
|
||||
-----
|
||||
.. ocv:class:: AKAZE : public Feature2D
|
||||
|
||||
Class implementing the AKAZE keypoint detector and descriptor extractor, described in [ANB13]_. ::
|
||||
|
||||
class CV_EXPORTS_W AKAZE : public Feature2D
|
||||
{
|
||||
public:
|
||||
CV_WRAP AKAZE();
|
||||
CV_WRAP explicit AKAZE(int descriptor_type, int descriptor_size = 0, int descriptor_channels = 3,
|
||||
float threshold = 0.001f, int octaves = 4, int sublevels = 4, int diffusivity = DIFF_PM_G2);
|
||||
};
|
||||
|
||||
.. note:: AKAZE descriptors can only be used with KAZE or AKAZE keypoints. Try to avoid using *extract* and *detect* instead of *operator()* due to performance reasons.
|
||||
|
||||
.. [ANB13] Fast Explicit Diffusion for Accelerated Features in Nonlinear Scale Spaces. Pablo F. Alcantarilla, Jesús Nuevo and Adrien Bartoli. In British Machine Vision Conference (BMVC), Bristol, UK, September 2013.
|
||||
|
||||
AKAZE::AKAZE
|
||||
------------
|
||||
The AKAZE constructor
|
||||
|
||||
.. ocv:function:: AKAZE::AKAZE(int descriptor_type, int descriptor_size, int descriptor_channels, float threshold, int octaves, int sublevels, int diffusivity)
|
||||
|
||||
:param descriptor_type: Type of the extracted descriptor: DESCRIPTOR_KAZE, DESCRIPTOR_KAZE_UPRIGHT, DESCRIPTOR_MLDB or DESCRIPTOR_MLDB_UPRIGHT.
|
||||
:param descriptor_size: Size of the descriptor in bits. 0 -> Full size
|
||||
:param descriptor_channels: Number of channels in the descriptor (1, 2, 3)
|
||||
:param threshold: Detector response threshold to accept point
|
||||
:param octaves: Maximum octave evolution of the image
|
||||
:param sublevels: Default number of sublevels per scale level
|
||||
:param diffusivity: Diffusivity type. DIFF_PM_G1, DIFF_PM_G2, DIFF_WEICKERT or DIFF_CHARBONNIER
|
||||
|
||||
SIFT
|
||||
----
|
||||
|
||||
.. ocv:class:: SIFT : public Feature2D
|
||||
|
||||
The SIFT algorithm has been moved to opencv_contrib/xfeatures2d module.
|
||||
@@ -1,15 +0,0 @@
|
||||
*********************************
|
||||
features2d. 2D Features Framework
|
||||
*********************************
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
feature_detection_and_description
|
||||
common_interfaces_of_feature_detectors
|
||||
common_interfaces_of_descriptor_extractors
|
||||
common_interfaces_of_descriptor_matchers
|
||||
drawing_function_of_keypoints_and_matches
|
||||
object_categorization
|
||||
@@ -1,213 +0,0 @@
|
||||
Object Categorization
|
||||
=====================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
This section describes approaches based on local 2D features and used to categorize objects.
|
||||
|
||||
.. note::
|
||||
|
||||
* A complete Bag-Of-Words sample can be found at opencv_source_code/samples/cpp/bagofwords_classification.cpp
|
||||
|
||||
* (Python) An example using the features2D framework to perform object categorization can be found at opencv_source_code/samples/python2/find_obj.py
|
||||
|
||||
BOWTrainer
|
||||
----------
|
||||
.. ocv:class:: BOWTrainer
|
||||
|
||||
Abstract base class for training the *bag of visual words* vocabulary from a set of descriptors.
|
||||
For details, see, for example, *Visual Categorization with Bags of Keypoints* by Gabriella Csurka, Christopher R. Dance,
|
||||
Lixin Fan, Jutta Willamowski, Cedric Bray, 2004. ::
|
||||
|
||||
class BOWTrainer
|
||||
{
|
||||
public:
|
||||
BOWTrainer(){}
|
||||
virtual ~BOWTrainer(){}
|
||||
|
||||
void add( const Mat& descriptors );
|
||||
const vector<Mat>& getDescriptors() const;
|
||||
int descriptorsCount() const;
|
||||
|
||||
virtual void clear();
|
||||
|
||||
virtual Mat cluster() const = 0;
|
||||
virtual Mat cluster( const Mat& descriptors ) const = 0;
|
||||
|
||||
protected:
|
||||
...
|
||||
};
|
||||
|
||||
BOWTrainer::add
|
||||
-------------------
|
||||
Adds descriptors to a training set.
|
||||
|
||||
.. ocv:function:: void BOWTrainer::add( const Mat& descriptors )
|
||||
|
||||
:param descriptors: Descriptors to add to a training set. Each row of the ``descriptors`` matrix is a descriptor.
|
||||
|
||||
The training set is clustered using ``clustermethod`` to construct the vocabulary.
|
||||
|
||||
BOWTrainer::getDescriptors
|
||||
------------------------------
|
||||
Returns a training set of descriptors.
|
||||
|
||||
.. ocv:function:: const vector<Mat>& BOWTrainer::getDescriptors() const
|
||||
|
||||
|
||||
|
||||
BOWTrainer::descriptorsCount
|
||||
---------------------------------
|
||||
Returns the count of all descriptors stored in the training set.
|
||||
|
||||
.. ocv:function:: int BOWTrainer::descriptorsCount() const
|
||||
|
||||
|
||||
|
||||
BOWTrainer::cluster
|
||||
-----------------------
|
||||
Clusters train descriptors.
|
||||
|
||||
.. ocv:function:: Mat BOWTrainer::cluster() const
|
||||
|
||||
.. ocv:function:: Mat BOWTrainer::cluster( const Mat& descriptors ) const
|
||||
|
||||
:param descriptors: Descriptors to cluster. Each row of the ``descriptors`` matrix is a descriptor. Descriptors are not added to the inner train descriptor set.
|
||||
|
||||
The vocabulary consists of cluster centers. So, this method returns the vocabulary. In the first variant of the method, train descriptors stored in the object are clustered. In the second variant, input descriptors are clustered.
|
||||
|
||||
BOWKMeansTrainer
|
||||
----------------
|
||||
.. ocv:class:: BOWKMeansTrainer : public BOWTrainer
|
||||
|
||||
:ocv:func:`kmeans` -based class to train visual vocabulary using the *bag of visual words* approach.
|
||||
::
|
||||
|
||||
class BOWKMeansTrainer : public BOWTrainer
|
||||
{
|
||||
public:
|
||||
BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(),
|
||||
int attempts=3, int flags=KMEANS_PP_CENTERS );
|
||||
virtual ~BOWKMeansTrainer(){}
|
||||
|
||||
// Returns trained vocabulary (i.e. cluster centers).
|
||||
virtual Mat cluster() const;
|
||||
virtual Mat cluster( const Mat& descriptors ) const;
|
||||
|
||||
protected:
|
||||
...
|
||||
};
|
||||
|
||||
BOWKMeansTrainer::BOWKMeansTrainer
|
||||
----------------------------------
|
||||
|
||||
The constructor.
|
||||
|
||||
.. ocv:function:: BOWKMeansTrainer::BOWKMeansTrainer( int clusterCount, const TermCriteria& termcrit=TermCriteria(), int attempts=3, int flags=KMEANS_PP_CENTERS )
|
||||
|
||||
See :ocv:func:`kmeans` function parameters.
|
||||
|
||||
BOWImgDescriptorExtractor
|
||||
-------------------------
|
||||
.. ocv:class:: BOWImgDescriptorExtractor
|
||||
|
||||
Class to compute an image descriptor using the *bag of visual words*. Such a computation consists of the following steps:
|
||||
|
||||
#. Compute descriptors for a given image and its keypoints set.
|
||||
#. Find the nearest visual words from the vocabulary for each keypoint descriptor.
|
||||
#. Compute the bag-of-words image descriptor as is a normalized histogram of vocabulary words encountered in the image. The ``i``-th bin of the histogram is a frequency of ``i``-th word of the vocabulary in the given image.
|
||||
|
||||
The class declaration is the following: ::
|
||||
|
||||
class BOWImgDescriptorExtractor
|
||||
{
|
||||
public:
|
||||
BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor,
|
||||
const Ptr<DescriptorMatcher>& dmatcher );
|
||||
BOWImgDescriptorExtractor( const Ptr<DescriptorMatcher>& dmatcher );
|
||||
virtual ~BOWImgDescriptorExtractor(){}
|
||||
|
||||
void setVocabulary( const Mat& vocabulary );
|
||||
const Mat& getVocabulary() const;
|
||||
void compute( InputArray image, vector<KeyPoint>& keypoints,
|
||||
OutputArray imgDescriptor,
|
||||
vector<vector<int> >* pointIdxsOfClusters=0,
|
||||
Mat* descriptors=0 );
|
||||
void compute( InputArray descriptors, OutputArray imgDescriptor,
|
||||
std::vector<std::vector<int> >* pointIdxsOfClusters=0 );
|
||||
int descriptorSize() const;
|
||||
int descriptorType() const;
|
||||
|
||||
protected:
|
||||
...
|
||||
};
|
||||
|
||||
|
||||
|
||||
|
||||
BOWImgDescriptorExtractor::BOWImgDescriptorExtractor
|
||||
--------------------------------------------------------
|
||||
The constructor.
|
||||
|
||||
.. ocv:function:: BOWImgDescriptorExtractor::BOWImgDescriptorExtractor( const Ptr<DescriptorExtractor>& dextractor, const Ptr<DescriptorMatcher>& dmatcher )
|
||||
.. ocv:function:: BOWImgDescriptorExtractor::BOWImgDescriptorExtractor( const Ptr<DescriptorMatcher>& dmatcher )
|
||||
|
||||
:param dextractor: Descriptor extractor that is used to compute descriptors for an input image and its keypoints.
|
||||
|
||||
:param dmatcher: Descriptor matcher that is used to find the nearest word of the trained vocabulary for each keypoint descriptor of the image.
|
||||
|
||||
|
||||
|
||||
BOWImgDescriptorExtractor::setVocabulary
|
||||
--------------------------------------------
|
||||
Sets a visual vocabulary.
|
||||
|
||||
.. ocv:function:: void BOWImgDescriptorExtractor::setVocabulary( const Mat& vocabulary )
|
||||
|
||||
:param vocabulary: Vocabulary (can be trained using the inheritor of :ocv:class:`BOWTrainer` ). Each row of the vocabulary is a visual word (cluster center).
|
||||
|
||||
|
||||
|
||||
BOWImgDescriptorExtractor::getVocabulary
|
||||
--------------------------------------------
|
||||
Returns the set vocabulary.
|
||||
|
||||
.. ocv:function:: const Mat& BOWImgDescriptorExtractor::getVocabulary() const
|
||||
|
||||
|
||||
|
||||
BOWImgDescriptorExtractor::compute
|
||||
--------------------------------------
|
||||
Computes an image descriptor using the set visual vocabulary.
|
||||
|
||||
.. ocv:function:: void BOWImgDescriptorExtractor::compute( InputArray image, vector<KeyPoint>& keypoints, OutputArray imgDescriptor, vector<vector<int> >* pointIdxsOfClusters=0, Mat* descriptors=0 )
|
||||
.. ocv:function:: void BOWImgDescriptorExtractor::compute( InputArray keypointDescriptors, OutputArray imgDescriptor, std::vector<std::vector<int> >* pointIdxsOfClusters=0 )
|
||||
|
||||
:param image: Image, for which the descriptor is computed.
|
||||
|
||||
:param keypoints: Keypoints detected in the input image.
|
||||
|
||||
:param keypointDescriptors: Computed descriptors to match with vocabulary.
|
||||
|
||||
:param imgDescriptor: Computed output image descriptor.
|
||||
|
||||
:param pointIdxsOfClusters: Indices of keypoints that belong to the cluster. This means that ``pointIdxsOfClusters[i]`` are keypoint indices that belong to the ``i`` -th cluster (word of vocabulary) returned if it is non-zero.
|
||||
|
||||
:param descriptors: Descriptors of the image keypoints that are returned if they are non-zero.
|
||||
|
||||
|
||||
|
||||
BOWImgDescriptorExtractor::descriptorSize
|
||||
---------------------------------------------
|
||||
Returns an image descriptor size if the vocabulary is set. Otherwise, it returns 0.
|
||||
|
||||
.. ocv:function:: int BOWImgDescriptorExtractor::descriptorSize() const
|
||||
|
||||
|
||||
|
||||
BOWImgDescriptorExtractor::descriptorType
|
||||
---------------------------------------------
|
||||
|
||||
Returns an image descriptor type.
|
||||
|
||||
.. ocv:function:: int BOWImgDescriptorExtractor::descriptorType() const
|
||||
@@ -1,9 +0,0 @@
|
||||
********************************************************
|
||||
flann. Clustering and Search in Multi-Dimensional Spaces
|
||||
********************************************************
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
flann_fast_approximate_nearest_neighbor_search
|
||||
flann_clustering
|
||||
@@ -1,20 +0,0 @@
|
||||
Clustering
|
||||
==========
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
flann::hierarchicalClustering<Distance>
|
||||
--------------------------------------------
|
||||
Clusters features using hierarchical k-means algorithm.
|
||||
|
||||
.. ocv:function:: template<typename Distance> int flann::hierarchicalClustering(const Mat& features, Mat& centers, const cvflann::KMeansIndexParams& params, Distance d = Distance())
|
||||
|
||||
:param features: The points to be clustered. The matrix must have elements of type ``Distance::ElementType``.
|
||||
|
||||
:param centers: The centers of the clusters obtained. The matrix must have type ``Distance::ResultType``. The number of rows in this matrix represents the number of clusters desired, however, because of the way the cut in the hierarchical tree is chosen, the number of clusters computed will be the highest number of the form ``(branching-1)*k+1`` that's lower than the number of clusters desired, where ``branching`` is the tree's branching factor (see description of the KMeansIndexParams).
|
||||
|
||||
:param params: Parameters used in the construction of the hierarchical k-means tree.
|
||||
|
||||
:param d: Distance to be used for clustering.
|
||||
|
||||
The method clusters the given feature vectors by constructing a hierarchical k-means tree and choosing a cut in the tree that minimizes the cluster's variance. It returns the number of clusters found.
|
||||
@@ -1,213 +0,0 @@
|
||||
Fast Approximate Nearest Neighbor Search
|
||||
========================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
This section documents OpenCV's interface to the FLANN library. FLANN (Fast Library for Approximate Nearest Neighbors) is a library that contains a collection of algorithms optimized for fast nearest neighbor search in large datasets and for high dimensional features. More information about FLANN can be found in [Muja2009]_ .
|
||||
|
||||
.. [Muja2009] Marius Muja, David G. Lowe. Fast Approximate Nearest Neighbors with Automatic Algorithm Configuration, 2009
|
||||
|
||||
flann::Index\_
|
||||
-----------------
|
||||
|
||||
.. ocv:class:: flann::Index_
|
||||
|
||||
The FLANN nearest neighbor index class. This class is templated with the type of elements for which the index is built.
|
||||
|
||||
|
||||
flann::Index_<T>::Index\_
|
||||
--------------------------
|
||||
Constructs a nearest neighbor search index for a given dataset.
|
||||
|
||||
.. ocv:function:: flann::Index_<T>::Index_(const Mat& features, const IndexParams& params)
|
||||
|
||||
:param features: Matrix of containing the features(points) to index. The size of the matrix is ``num_features x feature_dimensionality`` and the data type of the elements in the matrix must coincide with the type of the index.
|
||||
|
||||
:param params: Structure containing the index parameters. The type of index that will be constructed depends on the type of this parameter. See the description.
|
||||
|
||||
The method constructs a fast search structure from a set of features using the specified algorithm with specified parameters, as defined by ``params``. ``params`` is a reference to one of the following class ``IndexParams`` descendants:
|
||||
|
||||
*
|
||||
|
||||
**LinearIndexParams** When passing an object of this type, the index will perform a linear, brute-force search. ::
|
||||
|
||||
struct LinearIndexParams : public IndexParams
|
||||
{
|
||||
};
|
||||
|
||||
..
|
||||
|
||||
*
|
||||
|
||||
**KDTreeIndexParams** When passing an object of this type the index constructed will consist of a set of randomized kd-trees which will be searched in parallel. ::
|
||||
|
||||
struct KDTreeIndexParams : public IndexParams
|
||||
{
|
||||
KDTreeIndexParams( int trees = 4 );
|
||||
};
|
||||
|
||||
..
|
||||
|
||||
* **trees** The number of parallel kd-trees to use. Good values are in the range [1..16]
|
||||
|
||||
*
|
||||
|
||||
**KMeansIndexParams** When passing an object of this type the index constructed will be a hierarchical k-means tree. ::
|
||||
|
||||
struct KMeansIndexParams : public IndexParams
|
||||
{
|
||||
KMeansIndexParams(
|
||||
int branching = 32,
|
||||
int iterations = 11,
|
||||
flann_centers_init_t centers_init = CENTERS_RANDOM,
|
||||
float cb_index = 0.2 );
|
||||
};
|
||||
|
||||
..
|
||||
|
||||
* **branching** The branching factor to use for the hierarchical k-means tree
|
||||
|
||||
* **iterations** The maximum number of iterations to use in the k-means clustering stage when building the k-means tree. A value of -1 used here means that the k-means clustering should be iterated until convergence
|
||||
|
||||
* **centers_init** The algorithm to use for selecting the initial centers when performing a k-means clustering step. The possible values are ``CENTERS_RANDOM`` (picks the initial cluster centers randomly), ``CENTERS_GONZALES`` (picks the initial centers using Gonzales' algorithm) and ``CENTERS_KMEANSPP`` (picks the initial centers using the algorithm suggested in arthur_kmeanspp_2007 )
|
||||
|
||||
* **cb_index** This parameter (cluster boundary index) influences the way exploration is performed in the hierarchical kmeans tree. When ``cb_index`` is zero the next kmeans domain to be explored is chosen to be the one with the closest center. A value greater then zero also takes into account the size of the domain.
|
||||
|
||||
*
|
||||
**CompositeIndexParams** When using a parameters object of this type the index created combines the randomized kd-trees and the hierarchical k-means tree. ::
|
||||
|
||||
struct CompositeIndexParams : public IndexParams
|
||||
{
|
||||
CompositeIndexParams(
|
||||
int trees = 4,
|
||||
int branching = 32,
|
||||
int iterations = 11,
|
||||
flann_centers_init_t centers_init = CENTERS_RANDOM,
|
||||
float cb_index = 0.2 );
|
||||
};
|
||||
|
||||
*
|
||||
**LshIndexParams** When using a parameters object of this type the index created uses multi-probe LSH (by ``Multi-Probe LSH: Efficient Indexing for High-Dimensional Similarity Search`` by Qin Lv, William Josephson, Zhe Wang, Moses Charikar, Kai Li., Proceedings of the 33rd International Conference on Very Large Data Bases (VLDB). Vienna, Austria. September 2007) ::
|
||||
|
||||
struct LshIndexParams : public IndexParams
|
||||
{
|
||||
LshIndexParams(
|
||||
unsigned int table_number,
|
||||
unsigned int key_size,
|
||||
unsigned int multi_probe_level );
|
||||
};
|
||||
|
||||
..
|
||||
|
||||
* **table_number** the number of hash tables to use (between 10 and 30 usually).
|
||||
|
||||
|
||||
* **key_size** the size of the hash key in bits (between 10 and 20 usually).
|
||||
|
||||
|
||||
* **multi_probe_level** the number of bits to shift to check for neighboring buckets (0 is regular LSH, 2 is recommended).
|
||||
|
||||
*
|
||||
**AutotunedIndexParams** When passing an object of this type the index created is automatically tuned to offer the best performance, by choosing the optimal index type (randomized kd-trees, hierarchical kmeans, linear) and parameters for the dataset provided. ::
|
||||
|
||||
struct AutotunedIndexParams : public IndexParams
|
||||
{
|
||||
AutotunedIndexParams(
|
||||
float target_precision = 0.9,
|
||||
float build_weight = 0.01,
|
||||
float memory_weight = 0,
|
||||
float sample_fraction = 0.1 );
|
||||
};
|
||||
|
||||
..
|
||||
|
||||
* **target_precision** Is a number between 0 and 1 specifying the percentage of the approximate nearest-neighbor searches that return the exact nearest-neighbor. Using a higher value for this parameter gives more accurate results, but the search takes longer. The optimum value usually depends on the application.
|
||||
|
||||
|
||||
* **build_weight** Specifies the importance of the index build time raported to the nearest-neighbor search time. In some applications it's acceptable for the index build step to take a long time if the subsequent searches in the index can be performed very fast. In other applications it's required that the index be build as fast as possible even if that leads to slightly longer search times.
|
||||
|
||||
|
||||
* **memory_weight** Is used to specify the tradeoff between time (index build time and search time) and memory used by the index. A value less than 1 gives more importance to the time spent and a value greater than 1 gives more importance to the memory usage.
|
||||
|
||||
|
||||
* **sample_fraction** Is a number between 0 and 1 indicating what fraction of the dataset to use in the automatic parameter configuration algorithm. Running the algorithm on the full dataset gives the most accurate results, but for very large datasets can take longer than desired. In such case using just a fraction of the data helps speeding up this algorithm while still giving good approximations of the optimum parameters.
|
||||
|
||||
*
|
||||
**SavedIndexParams** This object type is used for loading a previously saved index from the disk. ::
|
||||
|
||||
struct SavedIndexParams : public IndexParams
|
||||
{
|
||||
SavedIndexParams( String filename );
|
||||
};
|
||||
|
||||
|
||||
..
|
||||
|
||||
* **filename** The filename in which the index was saved.
|
||||
|
||||
|
||||
flann::Index_<T>::knnSearch
|
||||
----------------------------
|
||||
Performs a K-nearest neighbor search for a given query point using the index.
|
||||
|
||||
.. ocv:function:: void flann::Index_<T>::knnSearch(const vector<T>& query, vector<int>& indices, vector<float>& dists, int knn, const SearchParams& params)
|
||||
|
||||
.. ocv:function:: void flann::Index_<T>::knnSearch(const Mat& queries, Mat& indices, Mat& dists, int knn, const SearchParams& params)
|
||||
|
||||
:param query: The query point
|
||||
|
||||
:param indices: Vector that will contain the indices of the K-nearest neighbors found. It must have at least knn size.
|
||||
|
||||
:param dists: Vector that will contain the distances to the K-nearest neighbors found. It must have at least knn size.
|
||||
|
||||
:param knn: Number of nearest neighbors to search for.
|
||||
|
||||
:param params:
|
||||
|
||||
Search parameters ::
|
||||
|
||||
struct SearchParams {
|
||||
SearchParams(int checks = 32);
|
||||
};
|
||||
|
||||
..
|
||||
|
||||
* **checks** The number of times the tree(s) in the index should be recursively traversed. A higher value for this parameter would give better search precision, but also take more time. If automatic configuration was used when the index was created, the number of checks required to achieve the specified precision was also computed, in which case this parameter is ignored.
|
||||
|
||||
|
||||
flann::Index_<T>::radiusSearch
|
||||
--------------------------------------
|
||||
Performs a radius nearest neighbor search for a given query point.
|
||||
|
||||
.. ocv:function:: int flann::Index_<T>::radiusSearch(const vector<T>& query, vector<int>& indices, vector<float>& dists, float radius, const SearchParams& params)
|
||||
|
||||
.. ocv:function:: int flann::Index_<T>::radiusSearch(const Mat& query, Mat& indices, Mat& dists, float radius, const SearchParams& params)
|
||||
|
||||
:param query: The query point
|
||||
|
||||
:param indices: Vector that will contain the indices of the points found within the search radius in decreasing order of the distance to the query point. If the number of neighbors in the search radius is bigger than the size of this vector, the ones that don't fit in the vector are ignored.
|
||||
|
||||
:param dists: Vector that will contain the distances to the points found within the search radius
|
||||
|
||||
:param radius: The search radius
|
||||
|
||||
:param params: Search parameters
|
||||
|
||||
|
||||
flann::Index_<T>::save
|
||||
------------------------------
|
||||
Saves the index to a file.
|
||||
|
||||
.. ocv:function:: void flann::Index_<T>::save(String filename)
|
||||
|
||||
:param filename: The file to save the index to
|
||||
|
||||
|
||||
flann::Index_<T>::getIndexParameters
|
||||
--------------------------------------------
|
||||
Returns the index parameters.
|
||||
|
||||
.. ocv:function:: const IndexParams* flann::Index_<T>::getIndexParameters()
|
||||
|
||||
The method is useful in the case of auto-tuned indices, when the parameters are chosen during the index construction. Then, the method can be used to retrieve the actual parameter values.
|
||||
@@ -1,17 +0,0 @@
|
||||
*************************************
|
||||
highgui. High-level GUI and Media I/O
|
||||
*************************************
|
||||
|
||||
While OpenCV was designed for use in full-scale
|
||||
applications and can be used within functionally rich UI frameworks (such as Qt*, WinForms*, or Cocoa*) or without any UI at all, sometimes there it is required to try functionality quickly and visualize the results. This is what the HighGUI module has been designed for.
|
||||
|
||||
It provides easy interface to:
|
||||
|
||||
* Create and manipulate windows that can display images and "remember" their content (no need to handle repaint events from OS).
|
||||
* Add trackbars to the windows, handle simple mouse events as well as keyboard commands.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
user_interface
|
||||
qt_new_functions
|
||||
@@ -1,336 +0,0 @@
|
||||
Qt New Functions
|
||||
================
|
||||
.. highlight:: cpp
|
||||
|
||||
.. image:: pics/qtgui.png
|
||||
|
||||
This figure explains new functionality implemented with Qt* GUI. The new GUI provides a statusbar, a toolbar, and a control panel. The control panel can have trackbars and buttonbars attached to it. If you cannot see the control panel, press Ctrl+P or right-click any Qt window and select **Display properties window**.
|
||||
|
||||
*
|
||||
To attach a trackbar, the window name parameter must be NULL.
|
||||
|
||||
*
|
||||
To attach a buttonbar, a button must be created.
|
||||
If the last bar attached to the control panel is a buttonbar, the new button is added to the right of the last button.
|
||||
If the last bar attached to the control panel is a trackbar, or the control panel is empty, a new buttonbar is created. Then, a new button is attached to it.
|
||||
|
||||
See below the example used to generate the figure: ::
|
||||
|
||||
int main(int argc, char *argv[])
|
||||
int value = 50;
|
||||
int value2 = 0;
|
||||
|
||||
cvNamedWindow("main1",CV_WINDOW_NORMAL);
|
||||
cvNamedWindow("main2",CV_WINDOW_AUTOSIZE | CV_GUI_NORMAL);
|
||||
|
||||
cvCreateTrackbar( "track1", "main1", &value, 255, NULL);//OK tested
|
||||
char* nameb1 = "button1";
|
||||
char* nameb2 = "button2";
|
||||
cvCreateButton(nameb1,callbackButton,nameb1,CV_CHECKBOX,1);
|
||||
|
||||
cvCreateButton(nameb2,callbackButton,nameb2,CV_CHECKBOX,0);
|
||||
cvCreateTrackbar( "track2", NULL, &value2, 255, NULL);
|
||||
cvCreateButton("button5",callbackButton1,NULL,CV_RADIOBOX,0);
|
||||
cvCreateButton("button6",callbackButton2,NULL,CV_RADIOBOX,1);
|
||||
|
||||
cvSetMouseCallback( "main2",on_mouse,NULL );
|
||||
|
||||
IplImage* img1 = cvLoadImage("files/flower.jpg");
|
||||
IplImage* img2 = cvCreateImage(cvGetSize(img1),8,3);
|
||||
CvCapture* video = cvCaptureFromFile("files/hockey.avi");
|
||||
IplImage* img3 = cvCreateImage(cvGetSize(cvQueryFrame(video)),8,3);
|
||||
|
||||
while(cvWaitKey(33) != 27)
|
||||
{
|
||||
cvAddS(img1,cvScalarAll(value),img2);
|
||||
cvAddS(cvQueryFrame(video),cvScalarAll(value2),img3);
|
||||
cvShowImage("main1",img2);
|
||||
cvShowImage("main2",img3);
|
||||
}
|
||||
|
||||
cvDestroyAllWindows();
|
||||
cvReleaseImage(&img1);
|
||||
cvReleaseImage(&img2);
|
||||
cvReleaseImage(&img3);
|
||||
cvReleaseCapture(&video);
|
||||
return 0;
|
||||
}
|
||||
|
||||
|
||||
setWindowProperty
|
||||
---------------------
|
||||
Changes parameters of a window dynamically.
|
||||
|
||||
.. ocv:function:: void setWindowProperty( const String& winname, int prop_id, double prop_value )
|
||||
|
||||
.. ocv:pyfunction:: cv2.setWindowProperty(winname, prop_id, prop_value) -> None
|
||||
|
||||
.. ocv:cfunction:: void cvSetWindowProperty( const char* name, int prop_id, double prop_value )
|
||||
|
||||
:param name: Name of the window.
|
||||
|
||||
:param prop_id: Window property to edit. The following operation flags are available:
|
||||
|
||||
* **CV_WND_PROP_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
|
||||
|
||||
* **CV_WND_PROP_AUTOSIZE** Change if the window is resizable (``CV_WINDOW_NORMAL`` or ``CV_WINDOW_AUTOSIZE`` ).
|
||||
|
||||
* **CV_WND_PROP_ASPECTRATIO** Change if the aspect ratio of the image is preserved ( ``CV_WINDOW_FREERATIO`` or ``CV_WINDOW_KEEPRATIO`` ).
|
||||
|
||||
|
||||
:param prop_value: New value of the window property. The following operation flags are available:
|
||||
|
||||
* **CV_WINDOW_NORMAL** Change the window to normal size or make the window resizable.
|
||||
|
||||
* **CV_WINDOW_AUTOSIZE** Constrain the size by the displayed image. The window is not resizable.
|
||||
|
||||
* **CV_WINDOW_FULLSCREEN** Change the window to fullscreen.
|
||||
|
||||
* **CV_WINDOW_FREERATIO** Make the window resizable without any ratio constraints.
|
||||
|
||||
* **CV_WINDOW_KEEPRATIO** Make the window resizable, but preserve the proportions of the displayed image.
|
||||
|
||||
|
||||
The function ``setWindowProperty`` enables changing properties of a window.
|
||||
|
||||
getWindowProperty
|
||||
---------------------
|
||||
Provides parameters of a window.
|
||||
|
||||
.. ocv:function:: double getWindowProperty( const String& winname, int prop_id )
|
||||
|
||||
.. ocv:pyfunction:: cv2.getWindowProperty(winname, prop_id) -> retval
|
||||
|
||||
.. ocv:cfunction:: double cvGetWindowProperty( const char* name, int prop_id )
|
||||
|
||||
:param name: Name of the window.
|
||||
|
||||
:param prop_id: Window property to retrieve. The following operation flags are available:
|
||||
|
||||
* **CV_WND_PROP_FULLSCREEN** Change if the window is fullscreen ( ``CV_WINDOW_NORMAL`` or ``CV_WINDOW_FULLSCREEN`` ).
|
||||
|
||||
* **CV_WND_PROP_AUTOSIZE** Change if the window is resizable (``CV_WINDOW_NORMAL`` or ``CV_WINDOW_AUTOSIZE`` ).
|
||||
|
||||
* **CV_WND_PROP_ASPECTRATIO** Change if the aspect ratio of the image is preserved (``CV_WINDOW_FREERATIO`` or ``CV_WINDOW_KEEPRATIO`` ).
|
||||
|
||||
|
||||
See
|
||||
:ocv:func:`setWindowProperty` to know the meaning of the returned values.
|
||||
|
||||
The function ``getWindowProperty`` returns properties of a window.
|
||||
|
||||
fontQt
|
||||
----------
|
||||
Creates the font to draw a text on an image.
|
||||
|
||||
.. ocv:function:: QtFont fontQt( const String& nameFont, int pointSize=-1, Scalar color=Scalar::all(0), int weight=QT_FONT_NORMAL, int style=QT_STYLE_NORMAL, int spacing=0 )
|
||||
|
||||
.. ocv:cfunction:: CvFont cvFontQt(const char* nameFont, int pointSize=-1, CvScalar color=cvScalarAll(0), int weight=CV_FONT_NORMAL, int style=CV_STYLE_NORMAL, int spacing=0)
|
||||
|
||||
:param nameFont: Name of the font. The name should match the name of a system font (such as *Times*). If the font is not found, a default one is used.
|
||||
|
||||
:param pointSize: Size of the font. If not specified, equal zero or negative, the point size of the font is set to a system-dependent default value. Generally, this is 12 points.
|
||||
|
||||
:param color: Color of the font in BGRA where A = 255 is fully transparent. Use the macro ``CV _ RGB`` for simplicity.
|
||||
|
||||
:param weight: Font weight. The following operation flags are available:
|
||||
|
||||
* **CV_FONT_LIGHT** Weight of 25
|
||||
|
||||
* **CV_FONT_NORMAL** Weight of 50
|
||||
|
||||
* **CV_FONT_DEMIBOLD** Weight of 63
|
||||
|
||||
* **CV_FONT_BOLD** Weight of 75
|
||||
|
||||
* **CV_FONT_BLACK** Weight of 87
|
||||
|
||||
You can also specify a positive integer for better control.
|
||||
|
||||
:param style: Font style. The following operation flags are available:
|
||||
|
||||
* **CV_STYLE_NORMAL** Normal font
|
||||
|
||||
* **CV_STYLE_ITALIC** Italic font
|
||||
|
||||
* **CV_STYLE_OBLIQUE** Oblique font
|
||||
|
||||
:param spacing: Spacing between characters. It can be negative or positive.
|
||||
|
||||
The function ``fontQt`` creates a ``CvFont`` object. This ``CvFont`` is not compatible with ``putText`` .
|
||||
|
||||
A basic usage of this function is the following: ::
|
||||
|
||||
CvFont font = fontQt(''Times'');
|
||||
addText( img1, ``Hello World !'', Point(50,50), font);
|
||||
|
||||
|
||||
addText
|
||||
-----------
|
||||
Creates the font to draw a text on an image.
|
||||
|
||||
.. ocv:function:: void addText( const Mat& img, const String& text, Point org, const QtFont& font )
|
||||
|
||||
.. ocv:cfunction:: void cvAddText( const CvArr* img, const char* text, CvPoint org, CvFont * arg2 )
|
||||
|
||||
:param img: 8-bit 3-channel image where the text should be drawn.
|
||||
|
||||
:param text: Text to write on an image.
|
||||
|
||||
:param org: Point(x,y) where the text should start on an image.
|
||||
|
||||
:param font: Font to use to draw a text.
|
||||
|
||||
The function ``addText`` draws
|
||||
*text*
|
||||
on an image
|
||||
*img*
|
||||
using a specific font
|
||||
*font*
|
||||
(see example :ocv:func:`fontQt` )
|
||||
|
||||
.. index:: displayOverlay
|
||||
|
||||
displayOverlay
|
||||
------------------
|
||||
Displays a text on a window image as an overlay for a specified duration.
|
||||
|
||||
.. ocv:function:: void displayOverlay( const String& winname, const String& text, int delayms=0 )
|
||||
|
||||
.. ocv:cfunction:: void cvDisplayOverlay(const char* name, const char* text, int delayms = 0)
|
||||
|
||||
:param name: Name of the window.
|
||||
|
||||
:param text: Overlay text to write on a window image.
|
||||
|
||||
:param delayms: The period (in milliseconds), during which the overlay text is displayed. If this function is called before the previous overlay text timed out, the timer is restarted and the text is updated. If this value is zero, the text never disappears.
|
||||
|
||||
The function ``displayOverlay`` displays useful information/tips on top of the window for a certain amount of time *delayms*. The function does not modify the image, displayed in the window, that is, after the specified delay the original content of the window is restored.
|
||||
|
||||
|
||||
displayStatusBar
|
||||
--------------------
|
||||
Displays a text on the window statusbar during the specified period of time.
|
||||
|
||||
.. ocv:function:: void displayStatusBar( const String& winname, const String& text, int delayms=0 )
|
||||
|
||||
.. ocv:cfunction:: void cvDisplayStatusBar(const char* name, const char* text, int delayms = 0)
|
||||
|
||||
:param name: Name of the window.
|
||||
|
||||
:param text: Text to write on the window statusbar.
|
||||
|
||||
:param delayms: Duration (in milliseconds) to display the text. If this function is called before the previous text timed out, the timer is restarted and the text is updated. If this value is zero, the text never disappears.
|
||||
|
||||
The function ``displayOverlay`` displays useful information/tips on top of the window for a certain amount of time
|
||||
*delayms*
|
||||
. This information is displayed on the window statusbar (the window must be created with the ``CV_GUI_EXPANDED`` flags).
|
||||
|
||||
setOpenGlDrawCallback
|
||||
------------------------
|
||||
Sets a callback function to be called to draw on top of displayed image.
|
||||
|
||||
.. ocv:function:: void setOpenGlDrawCallback( const String& winname, OpenGlDrawCallback onOpenGlDraw, void* userdata=0 )
|
||||
|
||||
.. ocv:cfunction:: void cvSetOpenGlDrawCallback( const char* window_name, CvOpenGlDrawCallback callback, void* userdata=NULL )
|
||||
|
||||
:param window_name: Name of the window.
|
||||
|
||||
:param onOpenGlDraw: Pointer to the function to be called every frame. This function should be prototyped as ``void Foo(void*)`` .
|
||||
|
||||
:param userdata: Pointer passed to the callback function. *(Optional)*
|
||||
|
||||
The function ``setOpenGlDrawCallback`` can be used to draw 3D data on the window. See the example of callback function below: ::
|
||||
|
||||
void on_opengl(void* param)
|
||||
{
|
||||
glLoadIdentity();
|
||||
|
||||
glTranslated(0.0, 0.0, -1.0);
|
||||
|
||||
glRotatef( 55, 1, 0, 0 );
|
||||
glRotatef( 45, 0, 1, 0 );
|
||||
glRotatef( 0, 0, 0, 1 );
|
||||
|
||||
static const int coords[6][4][3] = {
|
||||
{ { +1, -1, -1 }, { -1, -1, -1 }, { -1, +1, -1 }, { +1, +1, -1 } },
|
||||
{ { +1, +1, -1 }, { -1, +1, -1 }, { -1, +1, +1 }, { +1, +1, +1 } },
|
||||
{ { +1, -1, +1 }, { +1, -1, -1 }, { +1, +1, -1 }, { +1, +1, +1 } },
|
||||
{ { -1, -1, -1 }, { -1, -1, +1 }, { -1, +1, +1 }, { -1, +1, -1 } },
|
||||
{ { +1, -1, +1 }, { -1, -1, +1 }, { -1, -1, -1 }, { +1, -1, -1 } },
|
||||
{ { -1, -1, +1 }, { +1, -1, +1 }, { +1, +1, +1 }, { -1, +1, +1 } }
|
||||
};
|
||||
|
||||
for (int i = 0; i < 6; ++i) {
|
||||
glColor3ub( i*20, 100+i*10, i*42 );
|
||||
glBegin(GL_QUADS);
|
||||
for (int j = 0; j < 4; ++j) {
|
||||
glVertex3d(0.2 * coords[i][j][0], 0.2 * coords[i][j][1], 0.2 * coords[i][j][2]);
|
||||
}
|
||||
glEnd();
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
saveWindowParameters
|
||||
------------------------
|
||||
Saves parameters of the specified window.
|
||||
|
||||
.. ocv:function:: void saveWindowParameters( const String& windowName )
|
||||
|
||||
.. ocv:cfunction:: void cvSaveWindowParameters(const char* name)
|
||||
|
||||
:param name: Name of the window.
|
||||
|
||||
The function ``saveWindowParameters`` saves size, location, flags, trackbars value, zoom and panning location of the window
|
||||
``window_name`` .
|
||||
|
||||
loadWindowParameters
|
||||
------------------------
|
||||
Loads parameters of the specified window.
|
||||
|
||||
.. ocv:function:: void loadWindowParameters( const String& windowName )
|
||||
|
||||
.. ocv:cfunction:: void cvLoadWindowParameters(const char* name)
|
||||
|
||||
:param name: Name of the window.
|
||||
|
||||
The function ``loadWindowParameters`` loads size, location, flags, trackbars value, zoom and panning location of the window
|
||||
``window_name`` .
|
||||
|
||||
createButton
|
||||
----------------
|
||||
Attaches a button to the control panel.
|
||||
|
||||
.. ocv:function:: int createButton( const String& bar_name, ButtonCallback on_change, void* userdata=0, int type=QT_PUSH_BUTTON, bool initial_button_state=false )
|
||||
|
||||
.. ocv:cfunction:: int cvCreateButton( const char* button_name=NULL, CvButtonCallback on_change=NULL, void* userdata=NULL, int button_type=CV_PUSH_BUTTON, int initial_button_state=0 )
|
||||
|
||||
:param button_name: Name of the button.
|
||||
|
||||
:param on_change: Pointer to the function to be called every time the button changes its state. This function should be prototyped as ``void Foo(int state,*void);`` . *state* is the current state of the button. It could be -1 for a push button, 0 or 1 for a check/radio box button.
|
||||
|
||||
:param userdata: Pointer passed to the callback function.
|
||||
|
||||
:param button_type: Optional type of the button.
|
||||
|
||||
* **CV_PUSH_BUTTON** Push button
|
||||
|
||||
* **CV_CHECKBOX** Checkbox button
|
||||
|
||||
* **CV_RADIOBOX** Radiobox button. The radiobox on the same buttonbar (same line) are exclusive, that is only one can be selected at a time.
|
||||
|
||||
:param initial_button_state: Default state of the button. Use for checkbox and radiobox. Its value could be 0 or 1. *(Optional)*
|
||||
|
||||
The function ``createButton`` attaches a button to the control panel. Each button is added to a buttonbar to the right of the last button.
|
||||
A new buttonbar is created if nothing was attached to the control panel before, or if the last element attached to the control panel was a trackbar.
|
||||
|
||||
See below various examples of the ``createButton`` function call: ::
|
||||
|
||||
createButton(NULL,callbackButton);//create a push button "button 0", that will call callbackButton.
|
||||
createButton("button2",callbackButton,NULL,CV_CHECKBOX,0);
|
||||
createButton("button3",callbackButton,&value);
|
||||
createButton("button5",callbackButton1,NULL,CV_RADIOBOX);
|
||||
createButton("button6",callbackButton2,NULL,CV_PUSH_BUTTON,1);
|
||||
|
||||
..
|
||||
@@ -1,305 +0,0 @@
|
||||
User Interface
|
||||
==============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
createTrackbar
|
||||
------------------
|
||||
Creates a trackbar and attaches it to the specified window.
|
||||
|
||||
.. ocv:function:: int createTrackbar( const String& trackbarname, const String& winname, int* value, int count, TrackbarCallback onChange=0, void* userdata=0)
|
||||
|
||||
.. ocv:pyfunction:: cv2.createTrackbar(trackbarName, windowName, value, count, onChange) -> None
|
||||
|
||||
.. ocv:cfunction:: int cvCreateTrackbar( const char* trackbar_name, const char* window_name, int* value, int count, CvTrackbarCallback on_change=NULL )
|
||||
|
||||
:param trackbarname: Name of the created trackbar.
|
||||
|
||||
:param winname: Name of the window that will be used as a parent of the created trackbar.
|
||||
|
||||
:param value: Optional pointer to an integer variable whose value reflects the position of the slider. Upon creation, the slider position is defined by this variable.
|
||||
|
||||
:param count: Maximal position of the slider. The minimal position is always 0.
|
||||
|
||||
:param onChange: Pointer to the function to be called every time the slider changes position. This function should be prototyped as ``void Foo(int,void*);`` , where the first parameter is the trackbar position and the second parameter is the user data (see the next parameter). If the callback is the NULL pointer, no callbacks are called, but only ``value`` is updated.
|
||||
|
||||
:param userdata: User data that is passed as is to the callback. It can be used to handle trackbar events without using global variables.
|
||||
|
||||
The function ``createTrackbar`` creates a trackbar (a slider or range control) with the specified name and range, assigns a variable ``value`` to be a position synchronized with the trackbar and specifies the callback function ``onChange`` to be called on the trackbar position change. The created trackbar is displayed in the specified window ``winname``.
|
||||
|
||||
.. note::
|
||||
|
||||
**[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar should be attached to the control panel.
|
||||
|
||||
Clicking the label of each trackbar enables editing the trackbar values manually.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example of using the trackbar functionality can be found at opencv_source_code/samples/cpp/connected_components.cpp
|
||||
|
||||
getTrackbarPos
|
||||
------------------
|
||||
Returns the trackbar position.
|
||||
|
||||
.. ocv:function:: int getTrackbarPos( const String& trackbarname, const String& winname )
|
||||
|
||||
.. ocv:pyfunction:: cv2.getTrackbarPos(trackbarname, winname) -> retval
|
||||
|
||||
.. ocv:cfunction:: int cvGetTrackbarPos( const char* trackbar_name, const char* window_name )
|
||||
|
||||
:param trackbarname: Name of the trackbar.
|
||||
|
||||
:param winname: Name of the window that is the parent of the trackbar.
|
||||
|
||||
The function returns the current position of the specified trackbar.
|
||||
|
||||
.. note::
|
||||
|
||||
**[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar is attached to the control panel.
|
||||
|
||||
imshow
|
||||
----------
|
||||
Displays an image in the specified window.
|
||||
|
||||
.. ocv:function:: void imshow( const String& winname, InputArray mat )
|
||||
|
||||
.. ocv:pyfunction:: cv2.imshow(winname, mat) -> None
|
||||
|
||||
.. ocv:cfunction:: void cvShowImage( const char* name, const CvArr* image )
|
||||
|
||||
:param winname: Name of the window.
|
||||
|
||||
:param image: Image to be shown.
|
||||
|
||||
The function ``imshow`` displays an image in the specified window. If the window was created with the ``CV_WINDOW_AUTOSIZE`` flag, the image is shown with its original size. Otherwise, the image is scaled to fit the window. The function may scale the image, depending on its depth:
|
||||
|
||||
* If the image is 8-bit unsigned, it is displayed as is.
|
||||
|
||||
* If the image is 16-bit unsigned or 32-bit integer, the pixels are divided by 256. That is, the value range [0,255*256] is mapped to [0,255].
|
||||
|
||||
* If the image is 32-bit floating-point, the pixel values are multiplied by 255. That is, the value range [0,1] is mapped to [0,255].
|
||||
|
||||
If window was created with OpenGL support, ``imshow`` also support :ocv:class:`ogl::Buffer` , :ocv:class:`ogl::Texture2D` and :ocv:class:`cuda::GpuMat` as input.
|
||||
|
||||
.. note:: This function should be followed by ``waitKey`` function which displays the image for specified milliseconds. Otherwise, it won't display the image. For example, ``waitKey(0)`` will display the window infinitely until any keypress (it is suitable for image display). ``waitKey(25)`` will display a frame for 25 ms, after which display will be automatically closed. (If you put it in a loop to read videos, it will display the video frame-by-frame)
|
||||
|
||||
.. note::
|
||||
|
||||
[Windows Backend Only] Pressing Ctrl+C will copy the image to the clipboard.
|
||||
|
||||
namedWindow
|
||||
---------------
|
||||
Creates a window.
|
||||
|
||||
.. ocv:function:: void namedWindow( const String& winname, int flags=WINDOW_AUTOSIZE )
|
||||
|
||||
.. ocv:pyfunction:: cv2.namedWindow(winname[, flags]) -> None
|
||||
|
||||
.. ocv:cfunction:: int cvNamedWindow( const char* name, int flags=CV_WINDOW_AUTOSIZE )
|
||||
|
||||
:param name: Name of the window in the window caption that may be used as a window identifier.
|
||||
|
||||
:param flags: Flags of the window. The supported flags are:
|
||||
|
||||
* **WINDOW_NORMAL** If this is set, the user can resize the window (no constraint).
|
||||
|
||||
* **WINDOW_AUTOSIZE** If this is set, the window size is automatically adjusted to fit the displayed image (see :ocv:func:`imshow` ), and you cannot change the window size manually.
|
||||
|
||||
* **WINDOW_OPENGL** If this is set, the window will be created with OpenGL support.
|
||||
|
||||
The function ``namedWindow`` creates a window that can be used as a placeholder for images and trackbars. Created windows are referred to by their names.
|
||||
|
||||
If a window with the same name already exists, the function does nothing.
|
||||
|
||||
You can call :ocv:func:`destroyWindow` or :ocv:func:`destroyAllWindows` to close the window and de-allocate any associated memory usage. For a simple program, you do not really have to call these functions because all the resources and windows of the application are closed automatically by the operating system upon exit.
|
||||
|
||||
.. note::
|
||||
|
||||
Qt backend supports additional flags:
|
||||
|
||||
* **CV_WINDOW_NORMAL or CV_WINDOW_AUTOSIZE:** ``CV_WINDOW_NORMAL`` enables you to resize the window, whereas ``CV_WINDOW_AUTOSIZE`` adjusts automatically the window size to fit the displayed image (see :ocv:func:`imshow` ), and you cannot change the window size manually.
|
||||
|
||||
* **CV_WINDOW_FREERATIO or CV_WINDOW_KEEPRATIO:** ``CV_WINDOW_FREERATIO`` adjusts the image with no respect to its ratio, whereas ``CV_WINDOW_KEEPRATIO`` keeps the image ratio.
|
||||
|
||||
* **CV_GUI_NORMAL or CV_GUI_EXPANDED:** ``CV_GUI_NORMAL`` is the old way to draw the window without statusbar and toolbar, whereas ``CV_GUI_EXPANDED`` is a new enhanced GUI.
|
||||
|
||||
By default, ``flags == CV_WINDOW_AUTOSIZE | CV_WINDOW_KEEPRATIO | CV_GUI_EXPANDED``
|
||||
|
||||
|
||||
destroyWindow
|
||||
-------------
|
||||
Destroys a window.
|
||||
|
||||
.. ocv:function:: void destroyWindow( const String& winname )
|
||||
|
||||
.. ocv:pyfunction:: cv2.destroyWindow(winname) -> None
|
||||
|
||||
.. ocv:cfunction:: void cvDestroyWindow( const char* name )
|
||||
|
||||
:param winname: Name of the window to be destroyed.
|
||||
|
||||
The function ``destroyWindow`` destroys the window with the given name.
|
||||
|
||||
|
||||
destroyAllWindows
|
||||
-----------------
|
||||
Destroys all of the HighGUI windows.
|
||||
|
||||
.. ocv:function:: void destroyAllWindows()
|
||||
|
||||
.. ocv:pyfunction:: cv2.destroyAllWindows() -> None
|
||||
|
||||
.. ocv:cfunction:: void cvDestroyAllWindows()
|
||||
|
||||
The function ``destroyAllWindows`` destroys all of the opened HighGUI windows.
|
||||
|
||||
|
||||
MoveWindow
|
||||
----------
|
||||
Moves window to the specified position
|
||||
|
||||
.. ocv:function:: void moveWindow( const String& winname, int x, int y )
|
||||
|
||||
.. ocv:pyfunction:: cv2.moveWindow(winname, x, y) -> None
|
||||
|
||||
.. ocv:cfunction:: void cvMoveWindow( const char* name, int x, int y )
|
||||
|
||||
:param winname: Window name
|
||||
|
||||
:param x: The new x-coordinate of the window
|
||||
|
||||
:param y: The new y-coordinate of the window
|
||||
|
||||
|
||||
ResizeWindow
|
||||
------------
|
||||
Resizes window to the specified size
|
||||
|
||||
.. ocv:function:: void resizeWindow( const String& winname, int width, int height )
|
||||
|
||||
.. ocv:pyfunction:: cv2.resizeWindow(winname, width, height) -> None
|
||||
|
||||
.. ocv:cfunction:: void cvResizeWindow( const char* name, int width, int height )
|
||||
|
||||
:param winname: Window name
|
||||
|
||||
:param width: The new window width
|
||||
|
||||
:param height: The new window height
|
||||
|
||||
.. note::
|
||||
|
||||
* The specified window size is for the image area. Toolbars are not counted.
|
||||
|
||||
* Only windows created without CV_WINDOW_AUTOSIZE flag can be resized.
|
||||
|
||||
|
||||
SetMouseCallback
|
||||
----------------
|
||||
Sets mouse handler for the specified window
|
||||
|
||||
.. ocv:function:: void setMouseCallback( const String& winname, MouseCallback onMouse, void* userdata=0 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.setMouseCallback(windowName, onMouse [, param]) -> None
|
||||
|
||||
.. ocv:cfunction:: void cvSetMouseCallback( const char* window_name, CvMouseCallback on_mouse, void* param=NULL )
|
||||
|
||||
:param winname: Window name
|
||||
|
||||
:param onMouse: Mouse callback. See OpenCV samples, such as https://github.com/Itseez/opencv/tree/master/samples/cpp/ffilldemo.cpp, on how to specify and use the callback.
|
||||
|
||||
:param userdata: The optional parameter passed to the callback.
|
||||
|
||||
|
||||
getMouseWheelDelta
|
||||
------------------
|
||||
Gets the mouse-wheel motion delta, when handling mouse-wheel events EVENT_MOUSEWHEEL and EVENT_MOUSEHWHEEL.
|
||||
|
||||
.. ocv:function:: int getMouseWheelDelta(int flags)
|
||||
|
||||
:param flags: The mouse callback flags parameter.
|
||||
|
||||
For regular mice with a scroll-wheel, delta will be a multiple of 120. The value 120 corresponds to a one notch rotation of the wheel or the threshold for action to be taken and one such action should occur for each delta.
|
||||
Some high-precision mice with higher-resolution freely-rotating wheels may generate smaller values.
|
||||
|
||||
For EVENT_MOUSEWHEEL positive and negative values mean forward and backward scrolling, respectively.
|
||||
For EVENT_MOUSEHWHEEL, where available, positive and negative values mean right and left scrolling, respectively.
|
||||
|
||||
With the C API, the macro CV_GET_WHEEL_DELTA(flags) can be used alternatively.
|
||||
|
||||
.. note::
|
||||
|
||||
Mouse-wheel events are currently supported only on Windows.
|
||||
|
||||
setTrackbarPos
|
||||
------------------
|
||||
Sets the trackbar position.
|
||||
|
||||
.. ocv:function:: void setTrackbarPos( const String& trackbarname, const String& winname, int pos )
|
||||
|
||||
.. ocv:pyfunction:: cv2.setTrackbarPos(trackbarname, winname, pos) -> None
|
||||
|
||||
.. ocv:cfunction:: void cvSetTrackbarPos( const char* trackbar_name, const char* window_name, int pos )
|
||||
|
||||
:param trackbarname: Name of the trackbar.
|
||||
|
||||
:param winname: Name of the window that is the parent of trackbar.
|
||||
|
||||
:param pos: New position.
|
||||
|
||||
The function sets the position of the specified trackbar in the specified window.
|
||||
|
||||
.. note::
|
||||
|
||||
**[Qt Backend Only]** ``winname`` can be empty (or NULL) if the trackbar is attached to the control panel.
|
||||
|
||||
waitKey
|
||||
-----------
|
||||
Waits for a pressed key.
|
||||
|
||||
.. ocv:function:: int waitKey(int delay=0)
|
||||
|
||||
.. ocv:pyfunction:: cv2.waitKey([delay]) -> retval
|
||||
|
||||
.. ocv:cfunction:: int cvWaitKey( int delay=0 )
|
||||
|
||||
:param delay: Delay in milliseconds. 0 is the special value that means "forever".
|
||||
|
||||
The function ``waitKey`` waits for a key event infinitely (when
|
||||
:math:`\texttt{delay}\leq 0` ) or for ``delay`` milliseconds, when it is positive. Since the OS has a minimum time between switching threads, the function will not wait exactly ``delay`` ms, it will wait at least ``delay`` ms, depending on what else is running on your computer at that time. It returns the code of the pressed key or -1 if no key was pressed before the specified time had elapsed.
|
||||
|
||||
.. note::
|
||||
|
||||
This function is the only method in HighGUI that can fetch and handle events, so it needs to be called periodically for normal event processing unless HighGUI is used within an environment that takes care of event processing.
|
||||
|
||||
.. note::
|
||||
|
||||
The function only works if there is at least one HighGUI window created and the window is active. If there are several HighGUI windows, any of them can be active.
|
||||
|
||||
setOpenGlDrawCallback
|
||||
---------------------
|
||||
Set OpenGL render handler for the specified window.
|
||||
|
||||
.. ocv:function:: void setOpenGlDrawCallback(const string& winname, OpenGlDrawCallback onOpenGlDraw, void* userdata = 0)
|
||||
|
||||
:param winname: Window name
|
||||
|
||||
:param onOpenGlDraw: Draw callback.
|
||||
|
||||
:param userdata: The optional parameter passed to the callback.
|
||||
|
||||
setOpenGlContext
|
||||
----------------
|
||||
Sets the specified window as current OpenGL context.
|
||||
|
||||
.. ocv:function:: void setOpenGlContext(const String& winname)
|
||||
|
||||
:param winname: Window name
|
||||
|
||||
updateWindow
|
||||
------------
|
||||
Force window to redraw its context and call draw callback ( :ocv:func:`setOpenGlDrawCallback` ).
|
||||
|
||||
.. ocv:function:: void updateWindow(const String& winname)
|
||||
|
||||
:param winname: Window name
|
||||
@@ -1,10 +0,0 @@
|
||||
*****************************************
|
||||
imgcodecs. Image file reading and writing
|
||||
*****************************************
|
||||
|
||||
This module of the OpenCV help you read and write images to/from disk or memory.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
reading_and_writing_images
|
||||
@@ -1,187 +0,0 @@
|
||||
Reading and Writing Images
|
||||
==========================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
imdecode
|
||||
--------
|
||||
Reads an image from a buffer in memory.
|
||||
|
||||
.. ocv:function:: Mat imdecode( InputArray buf, int flags )
|
||||
|
||||
.. ocv:function:: Mat imdecode( InputArray buf, int flags, Mat* dst )
|
||||
|
||||
.. ocv:cfunction:: IplImage* cvDecodeImage( const CvMat* buf, int iscolor=CV_LOAD_IMAGE_COLOR)
|
||||
|
||||
.. ocv:cfunction:: CvMat* cvDecodeImageM( const CvMat* buf, int iscolor=CV_LOAD_IMAGE_COLOR)
|
||||
|
||||
.. ocv:pyfunction:: cv2.imdecode(buf, flags) -> retval
|
||||
|
||||
:param buf: Input array or vector of bytes.
|
||||
|
||||
:param flags: The same flags as in :ocv:func:`imread` .
|
||||
|
||||
:param dst: The optional output placeholder for the decoded matrix. It can save the image reallocations when the function is called repeatedly for images of the same size.
|
||||
|
||||
The function reads an image from the specified buffer in the memory.
|
||||
If the buffer is too short or contains invalid data, the empty matrix/image is returned.
|
||||
|
||||
See
|
||||
:ocv:func:`imread` for the list of supported formats and flags description.
|
||||
|
||||
.. note:: In the case of color images, the decoded images will have the channels stored in ``B G R`` order.
|
||||
|
||||
imencode
|
||||
--------
|
||||
Encodes an image into a memory buffer.
|
||||
|
||||
.. ocv:function:: bool imencode( const String& ext, InputArray img, vector<uchar>& buf, const vector<int>& params=vector<int>())
|
||||
|
||||
.. ocv:cfunction:: CvMat* cvEncodeImage( const char* ext, const CvArr* image, const int* params=0 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.imencode(ext, img[, params]) -> retval, buf
|
||||
|
||||
:param ext: File extension that defines the output format.
|
||||
|
||||
:param img: Image to be written.
|
||||
|
||||
:param buf: Output buffer resized to fit the compressed image.
|
||||
|
||||
:param params: Format-specific parameters. See :ocv:func:`imwrite` .
|
||||
|
||||
The function compresses the image and stores it in the memory buffer that is resized to fit the result.
|
||||
See
|
||||
:ocv:func:`imwrite` for the list of supported formats and flags description.
|
||||
|
||||
.. note:: ``cvEncodeImage`` returns single-row matrix of type ``CV_8UC1`` that contains encoded image as array of bytes.
|
||||
|
||||
imread
|
||||
------
|
||||
Loads an image from a file.
|
||||
|
||||
.. ocv:function:: Mat imread( const String& filename, int flags=IMREAD_COLOR )
|
||||
|
||||
.. ocv:pyfunction:: cv2.imread(filename[, flags]) -> retval
|
||||
|
||||
.. ocv:cfunction:: IplImage* cvLoadImage( const char* filename, int iscolor=CV_LOAD_IMAGE_COLOR )
|
||||
|
||||
.. ocv:cfunction:: CvMat* cvLoadImageM( const char* filename, int iscolor=CV_LOAD_IMAGE_COLOR )
|
||||
|
||||
:param filename: Name of file to be loaded.
|
||||
|
||||
:param flags: Flags specifying the color type of a loaded image:
|
||||
|
||||
* CV_LOAD_IMAGE_ANYDEPTH - If set, return 16-bit/32-bit image when the input has the corresponding depth, otherwise convert it to 8-bit.
|
||||
|
||||
* CV_LOAD_IMAGE_COLOR - If set, always convert image to the color one
|
||||
|
||||
* CV_LOAD_IMAGE_GRAYSCALE - If set, always convert image to the grayscale one
|
||||
|
||||
* **>0** Return a 3-channel color image.
|
||||
.. note:: In the current implementation the alpha channel, if any, is stripped from the output image. Use negative value if you need the alpha channel.
|
||||
|
||||
* **=0** Return a grayscale image.
|
||||
|
||||
* **<0** Return the loaded image as is (with alpha channel).
|
||||
|
||||
The function ``imread`` loads an image from the specified file and returns it. If the image cannot be read (because of missing file, improper permissions, unsupported or invalid format), the function returns an empty matrix ( ``Mat::data==NULL`` ). Currently, the following file formats are supported:
|
||||
|
||||
* Windows bitmaps - ``*.bmp, *.dib`` (always supported)
|
||||
|
||||
* JPEG files - ``*.jpeg, *.jpg, *.jpe`` (see the *Notes* section)
|
||||
|
||||
* JPEG 2000 files - ``*.jp2`` (see the *Notes* section)
|
||||
|
||||
* Portable Network Graphics - ``*.png`` (see the *Notes* section)
|
||||
|
||||
* WebP - ``*.webp`` (see the *Notes* section)
|
||||
|
||||
* Portable image format - ``*.pbm, *.pgm, *.ppm`` (always supported)
|
||||
|
||||
* Sun rasters - ``*.sr, *.ras`` (always supported)
|
||||
|
||||
* TIFF files - ``*.tiff, *.tif`` (see the *Notes* section)
|
||||
|
||||
.. note::
|
||||
|
||||
* The function determines the type of an image by the content, not by the file extension.
|
||||
|
||||
* On Microsoft Windows* OS and MacOSX*, the codecs shipped with an OpenCV image (libjpeg, libpng, libtiff, and libjasper) are used by default. So, OpenCV can always read JPEGs, PNGs, and TIFFs. On MacOSX, there is also an option to use native MacOSX image readers. But beware that currently these native image loaders give images with different pixel values because of the color management embedded into MacOSX.
|
||||
|
||||
* On Linux*, BSD flavors and other Unix-like open-source operating systems, OpenCV looks for codecs supplied with an OS image. Install the relevant packages (do not forget the development files, for example, "libjpeg-dev", in Debian* and Ubuntu*) to get the codec support or turn on the ``OPENCV_BUILD_3RDPARTY_LIBS`` flag in CMake.
|
||||
|
||||
.. note:: In the case of color images, the decoded images will have the channels stored in ``B G R`` order.
|
||||
|
||||
imwrite
|
||||
-----------
|
||||
Saves an image to a specified file.
|
||||
|
||||
.. ocv:function:: bool imwrite( const String& filename, InputArray img, const vector<int>& params=vector<int>() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.imwrite(filename, img[, params]) -> retval
|
||||
|
||||
.. ocv:cfunction:: int cvSaveImage( const char* filename, const CvArr* image, const int* params=0 )
|
||||
|
||||
:param filename: Name of the file.
|
||||
|
||||
:param image: Image to be saved.
|
||||
|
||||
:param params: Format-specific save parameters encoded as pairs ``paramId_1, paramValue_1, paramId_2, paramValue_2, ...`` . The following parameters are currently supported:
|
||||
|
||||
* For JPEG, it can be a quality ( ``CV_IMWRITE_JPEG_QUALITY`` ) from 0 to 100 (the higher is the better). Default value is 95.
|
||||
|
||||
* For WEBP, it can be a quality ( CV_IMWRITE_WEBP_QUALITY ) from 1 to 100 (the higher is the better).
|
||||
By default (without any parameter) and for quality above 100 the lossless compression is used.
|
||||
|
||||
* For PNG, it can be the compression level ( ``CV_IMWRITE_PNG_COMPRESSION`` ) from 0 to 9. A higher value means a smaller size and longer compression time. Default value is 3.
|
||||
|
||||
* For PPM, PGM, or PBM, it can be a binary format flag ( ``CV_IMWRITE_PXM_BINARY`` ), 0 or 1. Default value is 1.
|
||||
|
||||
The function ``imwrite`` saves the image to the specified file. The image format is chosen based on the ``filename`` extension (see
|
||||
:ocv:func:`imread` for the list of extensions). Only 8-bit (or 16-bit unsigned (``CV_16U``) in case of PNG, JPEG 2000, and TIFF) single-channel or 3-channel (with 'BGR' channel order) images can be saved using this function. If the format, depth or channel order is different, use
|
||||
:ocv:func:`Mat::convertTo` , and
|
||||
:ocv:func:`cvtColor` to convert it before saving. Or, use the universal :ocv:class:`FileStorage` I/O functions to save the image to XML or YAML format.
|
||||
|
||||
It is possible to store PNG images with an alpha channel using this function. To do this, create 8-bit (or 16-bit) 4-channel image BGRA, where the alpha channel goes last. Fully transparent pixels should have alpha set to 0, fully opaque pixels should have alpha set to 255/65535. The sample below shows how to create such a BGRA image and store to PNG file. It also demonstrates how to set custom compression parameters ::
|
||||
|
||||
#include <vector>
|
||||
#include <stdio.h>
|
||||
#include <opencv2/opencv.hpp>
|
||||
|
||||
using namespace cv;
|
||||
using namespace std;
|
||||
|
||||
void createAlphaMat(Mat &mat)
|
||||
{
|
||||
for (int i = 0; i < mat.rows; ++i) {
|
||||
for (int j = 0; j < mat.cols; ++j) {
|
||||
Vec4b& rgba = mat.at<Vec4b>(i, j);
|
||||
rgba[0] = UCHAR_MAX;
|
||||
rgba[1] = saturate_cast<uchar>((float (mat.cols - j)) / ((float)mat.cols) * UCHAR_MAX);
|
||||
rgba[2] = saturate_cast<uchar>((float (mat.rows - i)) / ((float)mat.rows) * UCHAR_MAX);
|
||||
rgba[3] = saturate_cast<uchar>(0.5 * (rgba[1] + rgba[2]));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
int main(int argv, char **argc)
|
||||
{
|
||||
// Create mat with alpha channel
|
||||
Mat mat(480, 640, CV_8UC4);
|
||||
createAlphaMat(mat);
|
||||
|
||||
vector<int> compression_params;
|
||||
compression_params.push_back(CV_IMWRITE_PNG_COMPRESSION);
|
||||
compression_params.push_back(9);
|
||||
|
||||
try {
|
||||
imwrite("alpha.png", mat, compression_params);
|
||||
}
|
||||
catch (runtime_error& ex) {
|
||||
fprintf(stderr, "Exception converting image to PNG format: %s\n", ex.what());
|
||||
return 1;
|
||||
}
|
||||
|
||||
fprintf(stdout, "Saved PNG file with alpha data.\n");
|
||||
return 0;
|
||||
}
|
||||
@@ -192,7 +192,7 @@ static ImageEncoder findEncoder( const String& _ext )
|
||||
if( !ext )
|
||||
return ImageEncoder();
|
||||
int len = 0;
|
||||
for( ext++; isalnum(ext[len]) && len < 128; len++ )
|
||||
for( ext++; len < 128 && isalnum(ext[len]); len++ )
|
||||
;
|
||||
|
||||
for( size_t i = 0; i < codecs.encoders.size(); i++ )
|
||||
@@ -206,7 +206,7 @@ static ImageEncoder findEncoder( const String& _ext )
|
||||
if( !descr )
|
||||
break;
|
||||
int j = 0;
|
||||
for( descr++; isalnum(descr[j]) && j < len; j++ )
|
||||
for( descr++; j < len && isalnum(descr[j]) ; j++ )
|
||||
{
|
||||
int c1 = tolower(ext[j]);
|
||||
int c2 = tolower(descr[j]);
|
||||
|
||||
@@ -1,110 +0,0 @@
|
||||
ColorMaps in OpenCV
|
||||
===================
|
||||
|
||||
applyColorMap
|
||||
-------------
|
||||
|
||||
Applies a GNU Octave/MATLAB equivalent colormap on a given image.
|
||||
|
||||
.. ocv:function:: void applyColorMap(InputArray src, OutputArray dst, int colormap)
|
||||
|
||||
:param src: The source image, grayscale or colored does not matter.
|
||||
:param dst: The result is the colormapped source image. Note: :ocv:func:`Mat::create` is called on dst.
|
||||
:param colormap: The colormap to apply, see the list of available colormaps below.
|
||||
|
||||
Currently the following GNU Octave/MATLAB equivalent colormaps are implemented:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
enum
|
||||
{
|
||||
COLORMAP_AUTUMN = 0,
|
||||
COLORMAP_BONE = 1,
|
||||
COLORMAP_JET = 2,
|
||||
COLORMAP_WINTER = 3,
|
||||
COLORMAP_RAINBOW = 4,
|
||||
COLORMAP_OCEAN = 5,
|
||||
COLORMAP_SUMMER = 6,
|
||||
COLORMAP_SPRING = 7,
|
||||
COLORMAP_COOL = 8,
|
||||
COLORMAP_HSV = 9,
|
||||
COLORMAP_PINK = 10,
|
||||
COLORMAP_HOT = 11
|
||||
}
|
||||
|
||||
|
||||
Description
|
||||
===========
|
||||
|
||||
The human perception isn't built for observing fine changes in grayscale images. Human eyes are more sensitive to observing changes between colors, so you often need to recolor your grayscale images to get a clue about them. OpenCV now comes with various colormaps to enhance the visualization in your computer vision application.
|
||||
|
||||
In OpenCV you only need :ocv:func:`applyColorMap` to apply a colormap on a given image. The following sample code reads the path to an image from command line, applies a Jet colormap on it and shows the result:
|
||||
|
||||
.. code-block:: cpp
|
||||
|
||||
#include <opencv2/core.hpp>
|
||||
#include <opencv2/imgproc.hpp>
|
||||
#include <opencv2/imgcodecs.hpp>
|
||||
#include <opencv2/highgui.hpp>
|
||||
using namespace cv;
|
||||
|
||||
#include <iostream>
|
||||
using namespace std;
|
||||
|
||||
int main(int argc, const char *argv[])
|
||||
{
|
||||
// We need an input image. (can be grayscale or color)
|
||||
if (argc < 2)
|
||||
{
|
||||
cerr << "We need an image to process here. Please run: colorMap [path_to_image]" << endl;
|
||||
return -1;
|
||||
}
|
||||
|
||||
Mat img_in = imread(argv[1]);
|
||||
|
||||
if(img_in.empty())
|
||||
{
|
||||
cerr << "Sample image (" << argv[1] << ") is empty. Please adjust your path, so it points to a valid input image!" << endl;
|
||||
return -1;
|
||||
}
|
||||
|
||||
// Holds the colormap version of the image:
|
||||
Mat img_color;
|
||||
// Apply the colormap:
|
||||
applyColorMap(img_in, img_color, COLORMAP_JET);
|
||||
// Show the result:
|
||||
imshow("colorMap", img_color);
|
||||
waitKey(0);
|
||||
|
||||
return 0;
|
||||
}
|
||||
|
||||
And here are the color scales for each of the available colormaps:
|
||||
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| Class | Scale |
|
||||
+=======================+===================================================+
|
||||
| COLORMAP_AUTUMN | .. image:: pics/colormaps/colorscale_autumn.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_BONE | .. image:: pics/colormaps/colorscale_bone.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_COOL | .. image:: pics/colormaps/colorscale_cool.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_HOT | .. image:: pics/colormaps/colorscale_hot.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_HSV | .. image:: pics/colormaps/colorscale_hsv.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_JET | .. image:: pics/colormaps/colorscale_jet.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_OCEAN | .. image:: pics/colormaps/colorscale_ocean.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_PINK | .. image:: pics/colormaps/colorscale_pink.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_RAINBOW | .. image:: pics/colormaps/colorscale_rainbow.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_SPRING | .. image:: pics/colormaps/colorscale_spring.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_SUMMER | .. image:: pics/colormaps/colorscale_summer.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
| COLORMAP_WINTER | .. image:: pics/colormaps/colorscale_winter.jpg |
|
||||
+-----------------------+---------------------------------------------------+
|
||||
@@ -1,634 +0,0 @@
|
||||
Drawing Functions
|
||||
=================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
Drawing functions work with matrices/images of arbitrary depth.
|
||||
The boundaries of the shapes can be rendered with antialiasing (implemented only for 8-bit images for now).
|
||||
All the functions include the parameter ``color`` that uses an RGB value (that may be constructed
|
||||
with the ``Scalar`` constructor
|
||||
) for color
|
||||
images and brightness for grayscale images. For color images, the channel ordering
|
||||
is normally *Blue, Green, Red*.
|
||||
This is what :ocv:func:`imshow`, :ocv:func:`imread`, and :ocv:func:`imwrite` expect.
|
||||
So, if you form a color using the
|
||||
``Scalar`` constructor, it should look like:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{Scalar} (blue \_ component, green \_ component, red \_ component[, alpha \_ component])
|
||||
|
||||
If you are using your own image rendering and I/O functions, you can use any channel ordering. The drawing functions process each channel independently and do not depend on the channel order or even on the used color space. The whole image can be converted from BGR to RGB or to a different color space using
|
||||
:ocv:func:`cvtColor` .
|
||||
|
||||
If a drawn figure is partially or completely outside the image, the drawing functions clip it. Also, many drawing functions can handle pixel coordinates specified with sub-pixel accuracy. This means that the coordinates can be passed as fixed-point numbers encoded as integers. The number of fractional bits is specified by the ``shift`` parameter and the real point coordinates are calculated as
|
||||
:math:`\texttt{Point}(x,y)\rightarrow\texttt{Point2f}(x*2^{-shift},y*2^{-shift})` . This feature is especially effective when rendering antialiased shapes.
|
||||
|
||||
.. note:: The functions do not support alpha-transparency when the target image is 4-channel. In this case, the ``color[3]`` is simply copied to the repainted pixels. Thus, if you want to paint semi-transparent shapes, you can paint them in a separate buffer and then blend it with the main image.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example on using variate drawing functions like line, rectangle, ... can be found at opencv_source_code/samples/cpp/drawing.cpp
|
||||
|
||||
circle
|
||||
----------
|
||||
Draws a circle.
|
||||
|
||||
.. ocv:function:: void circle( InputOutputArray img, Point center, int radius, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.circle(img, center, radius, color[, thickness[, lineType[, shift]]]) -> img
|
||||
|
||||
.. ocv:cfunction:: void cvCircle( CvArr* img, CvPoint center, int radius, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
|
||||
|
||||
:param img: Image where the circle is drawn.
|
||||
|
||||
:param center: Center of the circle.
|
||||
|
||||
:param radius: Radius of the circle.
|
||||
|
||||
:param color: Circle color.
|
||||
|
||||
:param thickness: Thickness of the circle outline, if positive. Negative thickness means that a filled circle is to be drawn.
|
||||
|
||||
:param lineType: Type of the circle boundary. See the :ocv:func:`line` description.
|
||||
|
||||
:param shift: Number of fractional bits in the coordinates of the center and in the radius value.
|
||||
|
||||
The function ``circle`` draws a simple or filled circle with a given center and radius.
|
||||
|
||||
clipLine
|
||||
------------
|
||||
Clips the line against the image rectangle.
|
||||
|
||||
.. ocv:function:: bool clipLine(Size imgSize, Point& pt1, Point& pt2)
|
||||
|
||||
.. ocv:function:: bool clipLine(Rect imgRect, Point& pt1, Point& pt2)
|
||||
|
||||
.. ocv:pyfunction:: cv2.clipLine(imgRect, pt1, pt2) -> retval, pt1, pt2
|
||||
|
||||
.. ocv:cfunction:: int cvClipLine( CvSize img_size, CvPoint* pt1, CvPoint* pt2 )
|
||||
|
||||
:param imgSize: Image size. The image rectangle is ``Rect(0, 0, imgSize.width, imgSize.height)`` .
|
||||
|
||||
:param imgRect: Image rectangle.
|
||||
|
||||
:param pt1: First line point.
|
||||
|
||||
:param pt2: Second line point.
|
||||
|
||||
The functions ``clipLine`` calculate a part of the line segment that is entirely within the specified rectangle.
|
||||
They return ``false`` if the line segment is completely outside the rectangle. Otherwise, they return ``true`` .
|
||||
|
||||
ellipse
|
||||
-----------
|
||||
Draws a simple or thick elliptic arc or fills an ellipse sector.
|
||||
|
||||
.. ocv:function:: void ellipse( InputOutputArray img, Point center, Size axes, double angle, double startAngle, double endAngle, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
|
||||
|
||||
.. ocv:function:: void ellipse( InputOutputArray img, const RotatedRect& box, const Scalar& color, int thickness=1, int lineType=LINE_8 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.ellipse(img, center, axes, angle, startAngle, endAngle, color[, thickness[, lineType[, shift]]]) -> img
|
||||
|
||||
.. ocv:pyfunction:: cv2.ellipse(img, box, color[, thickness[, lineType]]) -> img
|
||||
|
||||
.. ocv:cfunction:: void cvEllipse( CvArr* img, CvPoint center, CvSize axes, double angle, double start_angle, double end_angle, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
|
||||
|
||||
.. ocv:cfunction:: void cvEllipseBox( CvArr* img, CvBox2D box, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
|
||||
|
||||
:param img: Image.
|
||||
|
||||
:param center: Center of the ellipse.
|
||||
|
||||
:param axes: Half of the size of the ellipse main axes.
|
||||
|
||||
:param angle: Ellipse rotation angle in degrees.
|
||||
|
||||
:param startAngle: Starting angle of the elliptic arc in degrees.
|
||||
|
||||
:param endAngle: Ending angle of the elliptic arc in degrees.
|
||||
|
||||
:param box: Alternative ellipse representation via :ocv:class:`RotatedRect` or ``CvBox2D``. This means that the function draws an ellipse inscribed in the rotated rectangle.
|
||||
|
||||
:param color: Ellipse color.
|
||||
|
||||
:param thickness: Thickness of the ellipse arc outline, if positive. Otherwise, this indicates that a filled ellipse sector is to be drawn.
|
||||
|
||||
:param lineType: Type of the ellipse boundary. See the :ocv:func:`line` description.
|
||||
|
||||
:param shift: Number of fractional bits in the coordinates of the center and values of axes.
|
||||
|
||||
The functions ``ellipse`` with less parameters draw an ellipse outline, a filled ellipse, an elliptic arc, or a filled ellipse sector.
|
||||
A piecewise-linear curve is used to approximate the elliptic arc boundary. If you need more control of the ellipse rendering, you can retrieve the curve using
|
||||
:ocv:func:`ellipse2Poly` and then render it with
|
||||
:ocv:func:`polylines` or fill it with
|
||||
:ocv:func:`fillPoly` . If you use the first variant of the function and want to draw the whole ellipse, not an arc, pass ``startAngle=0`` and ``endAngle=360`` . The figure below explains the meaning of the parameters.
|
||||
|
||||
**Figure 1. Parameters of Elliptic Arc**
|
||||
|
||||
.. image:: pics/ellipse.png
|
||||
|
||||
ellipse2Poly
|
||||
----------------
|
||||
Approximates an elliptic arc with a polyline.
|
||||
|
||||
.. ocv:function:: void ellipse2Poly( Point center, Size axes, int angle, int arcStart, int arcEnd, int delta, vector<Point>& pts )
|
||||
|
||||
.. ocv:pyfunction:: cv2.ellipse2Poly(center, axes, angle, arcStart, arcEnd, delta) -> pts
|
||||
|
||||
:param center: Center of the arc.
|
||||
|
||||
:param axes: Half of the size of the ellipse main axes. See the :ocv:func:`ellipse` for details.
|
||||
|
||||
:param angle: Rotation angle of the ellipse in degrees. See the :ocv:func:`ellipse` for details.
|
||||
|
||||
:param arcStart: Starting angle of the elliptic arc in degrees.
|
||||
|
||||
:param arcEnd: Ending angle of the elliptic arc in degrees.
|
||||
|
||||
:param delta: Angle between the subsequent polyline vertices. It defines the approximation accuracy.
|
||||
|
||||
:param pts: Output vector of polyline vertices.
|
||||
|
||||
The function ``ellipse2Poly`` computes the vertices of a polyline that approximates the specified elliptic arc. It is used by
|
||||
:ocv:func:`ellipse` .
|
||||
|
||||
|
||||
fillConvexPoly
|
||||
------------------
|
||||
Fills a convex polygon.
|
||||
|
||||
.. ocv:function:: void fillConvexPoly( Mat& img, const Point* pts, int npts, const Scalar& color, int lineType=LINE_8, int shift=0 )
|
||||
|
||||
.. ocv:function:: void fillConvexPoly( InputOutputArray img, InputArray points, const Scalar& color, int lineType=LINE_8, int shift=0 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.fillConvexPoly(img, points, color[, lineType[, shift]]) -> img
|
||||
|
||||
.. ocv:cfunction:: void cvFillConvexPoly( CvArr* img, const CvPoint* pts, int npts, CvScalar color, int line_type=8, int shift=0 )
|
||||
|
||||
:param img: Image.
|
||||
|
||||
:param pts: Polygon vertices.
|
||||
|
||||
:param npts: Number of polygon vertices.
|
||||
|
||||
:param color: Polygon color.
|
||||
|
||||
:param lineType: Type of the polygon boundaries. See the :ocv:func:`line` description.
|
||||
|
||||
:param shift: Number of fractional bits in the vertex coordinates.
|
||||
|
||||
The function ``fillConvexPoly`` draws a filled convex polygon.
|
||||
This function is much faster than the function ``fillPoly`` . It can fill not only convex polygons but any monotonic polygon without self-intersections,
|
||||
that is, a polygon whose contour intersects every horizontal line (scan line) twice at the most (though, its top-most and/or the bottom edge could be horizontal).
|
||||
|
||||
|
||||
|
||||
fillPoly
|
||||
------------
|
||||
Fills the area bounded by one or more polygons.
|
||||
|
||||
.. ocv:function:: void fillPoly( Mat& img, const Point** pts, const int* npts, int ncontours, const Scalar& color, int lineType=LINE_8, int shift=0, Point offset=Point() )
|
||||
|
||||
.. ocv:function:: void fillPoly( InputOutputArray img, InputArrayOfArrays pts, const Scalar& color, int lineType=LINE_8, int shift=0, Point offset=Point() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.fillPoly(img, pts, color[, lineType[, shift[, offset]]]) -> img
|
||||
|
||||
.. ocv:cfunction:: void cvFillPoly( CvArr* img, CvPoint** pts, const int* npts, int contours, CvScalar color, int line_type=8, int shift=0 )
|
||||
|
||||
:param img: Image.
|
||||
|
||||
:param pts: Array of polygons where each polygon is represented as an array of points.
|
||||
|
||||
:param npts: Array of polygon vertex counters.
|
||||
|
||||
:param ncontours: Number of contours that bind the filled region.
|
||||
|
||||
:param color: Polygon color.
|
||||
|
||||
:param lineType: Type of the polygon boundaries. See the :ocv:func:`line` description.
|
||||
|
||||
:param shift: Number of fractional bits in the vertex coordinates.
|
||||
|
||||
:param offset: Optional offset of all points of the contours.
|
||||
|
||||
The function ``fillPoly`` fills an area bounded by several polygonal contours. The function can fill complex areas, for example,
|
||||
areas with holes, contours with self-intersections (some of their parts), and so forth.
|
||||
|
||||
|
||||
|
||||
getTextSize
|
||||
---------------
|
||||
Calculates the width and height of a text string.
|
||||
|
||||
.. ocv:function:: Size getTextSize(const String& text, int fontFace, double fontScale, int thickness, int* baseLine)
|
||||
|
||||
.. ocv:pyfunction:: cv2.getTextSize(text, fontFace, fontScale, thickness) -> retval, baseLine
|
||||
|
||||
.. ocv:cfunction:: void cvGetTextSize( const char* text_string, const CvFont* font, CvSize* text_size, int* baseline )
|
||||
|
||||
:param text: Input text string.
|
||||
|
||||
:param text_string: Input text string in C format.
|
||||
|
||||
:param fontFace: Font to use. See the :ocv:func:`putText` for details.
|
||||
|
||||
:param fontScale: Font scale. See the :ocv:func:`putText` for details.
|
||||
|
||||
:param thickness: Thickness of lines used to render the text. See :ocv:func:`putText` for details.
|
||||
|
||||
:param baseLine: Output parameter - y-coordinate of the baseline relative to the bottom-most text point.
|
||||
|
||||
:param baseline: Output parameter - y-coordinate of the baseline relative to the bottom-most text point.
|
||||
|
||||
:param font: Font description in terms of old C API.
|
||||
|
||||
:param text_size: Output parameter - The size of a box that contains the specified text.
|
||||
|
||||
The function ``getTextSize`` calculates and returns the size of a box that contains the specified text.
|
||||
That is, the following code renders some text, the tight box surrounding it, and the baseline: ::
|
||||
|
||||
String text = "Funny text inside the box";
|
||||
int fontFace = FONT_HERSHEY_SCRIPT_SIMPLEX;
|
||||
double fontScale = 2;
|
||||
int thickness = 3;
|
||||
|
||||
Mat img(600, 800, CV_8UC3, Scalar::all(0));
|
||||
|
||||
int baseline=0;
|
||||
Size textSize = getTextSize(text, fontFace,
|
||||
fontScale, thickness, &baseline);
|
||||
baseline += thickness;
|
||||
|
||||
// center the text
|
||||
Point textOrg((img.cols - textSize.width)/2,
|
||||
(img.rows + textSize.height)/2);
|
||||
|
||||
// draw the box
|
||||
rectangle(img, textOrg + Point(0, baseline),
|
||||
textOrg + Point(textSize.width, -textSize.height),
|
||||
Scalar(0,0,255));
|
||||
// ... and the baseline first
|
||||
line(img, textOrg + Point(0, thickness),
|
||||
textOrg + Point(textSize.width, thickness),
|
||||
Scalar(0, 0, 255));
|
||||
|
||||
// then put the text itself
|
||||
putText(img, text, textOrg, fontFace, fontScale,
|
||||
Scalar::all(255), thickness, 8);
|
||||
|
||||
|
||||
InitFont
|
||||
--------
|
||||
Initializes font structure (OpenCV 1.x API).
|
||||
|
||||
.. ocv:cfunction:: void cvInitFont( CvFont* font, int font_face, double hscale, double vscale, double shear=0, int thickness=1, int line_type=8 )
|
||||
|
||||
:param font: Pointer to the font structure initialized by the function
|
||||
|
||||
:param font_face: Font name identifier. Only a subset of Hershey fonts http://sources.isc.org/utils/misc/hershey-font.txt are supported now:
|
||||
|
||||
* **CV_FONT_HERSHEY_SIMPLEX** normal size sans-serif font
|
||||
|
||||
* **CV_FONT_HERSHEY_PLAIN** small size sans-serif font
|
||||
|
||||
* **CV_FONT_HERSHEY_DUPLEX** normal size sans-serif font (more complex than ``CV_FONT_HERSHEY_SIMPLEX`` )
|
||||
|
||||
* **CV_FONT_HERSHEY_COMPLEX** normal size serif font
|
||||
|
||||
* **CV_FONT_HERSHEY_TRIPLEX** normal size serif font (more complex than ``CV_FONT_HERSHEY_COMPLEX`` )
|
||||
|
||||
* **CV_FONT_HERSHEY_COMPLEX_SMALL** smaller version of ``CV_FONT_HERSHEY_COMPLEX``
|
||||
|
||||
* **CV_FONT_HERSHEY_SCRIPT_SIMPLEX** hand-writing style font
|
||||
|
||||
* **CV_FONT_HERSHEY_SCRIPT_COMPLEX** more complex variant of ``CV_FONT_HERSHEY_SCRIPT_SIMPLEX``
|
||||
|
||||
The parameter can be composited from one of the values above and an optional ``CV_FONT_ITALIC`` flag, which indicates italic or oblique font.
|
||||
|
||||
|
||||
:param hscale: Horizontal scale. If equal to ``1.0f`` , the characters have the original width depending on the font type. If equal to ``0.5f`` , the characters are of half the original width.
|
||||
|
||||
|
||||
:param vscale: Vertical scale. If equal to ``1.0f`` , the characters have the original height depending on the font type. If equal to ``0.5f`` , the characters are of half the original height.
|
||||
|
||||
|
||||
:param shear: Approximate tangent of the character slope relative to the vertical line. A zero value means a non-italic font, ``1.0f`` means about a 45 degree slope, etc.
|
||||
|
||||
|
||||
:param thickness: Thickness of the text strokes
|
||||
|
||||
|
||||
:param line_type: Type of the strokes, see :ocv:func:`line` description
|
||||
|
||||
|
||||
The function initializes the font structure that can be passed to text rendering functions.
|
||||
|
||||
.. seealso:: :ocv:cfunc:`PutText`
|
||||
|
||||
.. _Line:
|
||||
|
||||
line
|
||||
--------
|
||||
Draws a line segment connecting two points.
|
||||
|
||||
.. ocv:function:: void line( InputOutputArray img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.line(img, pt1, pt2, color[, thickness[, lineType[, shift]]]) -> img
|
||||
|
||||
.. ocv:cfunction:: void cvLine( CvArr* img, CvPoint pt1, CvPoint pt2, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
|
||||
|
||||
:param img: Image.
|
||||
|
||||
:param pt1: First point of the line segment.
|
||||
|
||||
:param pt2: Second point of the line segment.
|
||||
|
||||
:param color: Line color.
|
||||
|
||||
:param thickness: Line thickness.
|
||||
|
||||
:param lineType: Type of the line:
|
||||
|
||||
* **LINE_8** (or omitted) - 8-connected line.
|
||||
|
||||
* **LINE_4** - 4-connected line.
|
||||
|
||||
* **LINE_AA** - antialiased line.
|
||||
|
||||
:param shift: Number of fractional bits in the point coordinates.
|
||||
|
||||
The function ``line`` draws the line segment between ``pt1`` and ``pt2`` points in the image. The line is clipped by the image boundaries. For non-antialiased lines with integer coordinates, the 8-connected or 4-connected Bresenham algorithm is used. Thick lines are drawn with rounding endings.
|
||||
Antialiased lines are drawn using Gaussian filtering.
|
||||
|
||||
|
||||
arrowedLine
|
||||
----------------
|
||||
Draws a arrow segment pointing from the first point to the second one.
|
||||
|
||||
.. ocv:function:: void arrowedLine(InputOutputArray img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int lineType=8, int shift=0, double tipLength=0.1)
|
||||
|
||||
:param img: Image.
|
||||
|
||||
:param pt1: The point the arrow starts from.
|
||||
|
||||
:param pt2: The point the arrow points to.
|
||||
|
||||
:param color: Line color.
|
||||
|
||||
:param thickness: Line thickness.
|
||||
|
||||
:param lineType: Type of the line:
|
||||
|
||||
* **8** (or omitted) - 8-connected line.
|
||||
|
||||
* **4** - 4-connected line.
|
||||
|
||||
* **CV_AA** - antialiased line.
|
||||
|
||||
:param shift: Number of fractional bits in the point coordinates.
|
||||
|
||||
:param tipLength: The length of the arrow tip in relation to the arrow length
|
||||
|
||||
The function ``arrowedLine`` draws an arrow between ``pt1`` and ``pt2`` points in the image. See also :ocv:func:`line`.
|
||||
|
||||
|
||||
LineIterator
|
||||
------------
|
||||
.. ocv:class:: LineIterator
|
||||
|
||||
Class for iterating pixels on a raster line. ::
|
||||
|
||||
class LineIterator
|
||||
{
|
||||
public:
|
||||
// creates iterators for the line connecting pt1 and pt2
|
||||
// the line will be clipped on the image boundaries
|
||||
// the line is 8-connected or 4-connected
|
||||
// If leftToRight=true, then the iteration is always done
|
||||
// from the left-most point to the right most,
|
||||
// not to depend on the ordering of pt1 and pt2 parameters
|
||||
LineIterator(const Mat& img, Point pt1, Point pt2,
|
||||
int connectivity=8, bool leftToRight=false);
|
||||
// returns pointer to the current line pixel
|
||||
uchar* operator *();
|
||||
// move the iterator to the next pixel
|
||||
LineIterator& operator ++();
|
||||
LineIterator operator ++(int);
|
||||
Point pos() const;
|
||||
|
||||
// internal state of the iterator
|
||||
uchar* ptr;
|
||||
int err, count;
|
||||
int minusDelta, plusDelta;
|
||||
int minusStep, plusStep;
|
||||
};
|
||||
|
||||
The class ``LineIterator`` is used to get each pixel of a raster line. It can be treated as versatile implementation of the Bresenham algorithm where you can stop at each pixel and do some extra processing, for example, grab pixel values along the line or draw a line with an effect (for example, with XOR operation).
|
||||
|
||||
The number of pixels along the line is stored in ``LineIterator::count`` . The method ``LineIterator::pos`` returns the current position in the image ::
|
||||
|
||||
// grabs pixels along the line (pt1, pt2)
|
||||
// from 8-bit 3-channel image to the buffer
|
||||
LineIterator it(img, pt1, pt2, 8);
|
||||
LineIterator it2 = it;
|
||||
vector<Vec3b> buf(it.count);
|
||||
|
||||
for(int i = 0; i < it.count; i++, ++it)
|
||||
buf[i] = *(const Vec3b)*it;
|
||||
|
||||
// alternative way of iterating through the line
|
||||
for(int i = 0; i < it2.count; i++, ++it2)
|
||||
{
|
||||
Vec3b val = img.at<Vec3b>(it2.pos());
|
||||
CV_Assert(buf[i] == val);
|
||||
}
|
||||
|
||||
|
||||
rectangle
|
||||
-------------
|
||||
Draws a simple, thick, or filled up-right rectangle.
|
||||
|
||||
.. ocv:function:: void rectangle( InputOutputArray img, Point pt1, Point pt2, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
|
||||
|
||||
.. ocv:function:: void rectangle( Mat& img, Rect rec, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.rectangle(img, pt1, pt2, color[, thickness[, lineType[, shift]]]) -> img
|
||||
|
||||
.. ocv:cfunction:: void cvRectangle( CvArr* img, CvPoint pt1, CvPoint pt2, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
|
||||
|
||||
:param img: Image.
|
||||
|
||||
:param pt1: Vertex of the rectangle.
|
||||
|
||||
:param pt2: Vertex of the rectangle opposite to ``pt1`` .
|
||||
|
||||
:param rec: Alternative specification of the drawn rectangle.
|
||||
|
||||
:param color: Rectangle color or brightness (grayscale image).
|
||||
|
||||
:param thickness: Thickness of lines that make up the rectangle. Negative values, like ``CV_FILLED`` , mean that the function has to draw a filled rectangle.
|
||||
|
||||
:param lineType: Type of the line. See the :ocv:func:`line` description.
|
||||
|
||||
:param shift: Number of fractional bits in the point coordinates.
|
||||
|
||||
The function ``rectangle`` draws a rectangle outline or a filled rectangle whose two opposite corners are ``pt1`` and ``pt2``, or ``r.tl()`` and ``r.br()-Point(1,1)``.
|
||||
|
||||
|
||||
|
||||
polylines
|
||||
-------------
|
||||
Draws several polygonal curves.
|
||||
|
||||
.. ocv:function:: void polylines( Mat& img, const Point* const* pts, const int* npts, int ncontours, bool isClosed, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
|
||||
|
||||
.. ocv:function:: void polylines( InputOutputArray img, InputArrayOfArrays pts, bool isClosed, const Scalar& color, int thickness=1, int lineType=LINE_8, int shift=0 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.polylines(img, pts, isClosed, color[, thickness[, lineType[, shift]]]) -> img
|
||||
|
||||
.. ocv:cfunction:: void cvPolyLine( CvArr* img, CvPoint** pts, const int* npts, int contours, int is_closed, CvScalar color, int thickness=1, int line_type=8, int shift=0 )
|
||||
|
||||
:param img: Image.
|
||||
|
||||
:param pts: Array of polygonal curves.
|
||||
|
||||
:param npts: Array of polygon vertex counters.
|
||||
|
||||
:param ncontours: Number of curves.
|
||||
|
||||
:param isClosed: Flag indicating whether the drawn polylines are closed or not. If they are closed, the function draws a line from the last vertex of each curve to its first vertex.
|
||||
|
||||
:param color: Polyline color.
|
||||
|
||||
:param thickness: Thickness of the polyline edges.
|
||||
|
||||
:param lineType: Type of the line segments. See the :ocv:func:`line` description.
|
||||
|
||||
:param shift: Number of fractional bits in the vertex coordinates.
|
||||
|
||||
The function ``polylines`` draws one or more polygonal curves.
|
||||
|
||||
|
||||
drawContours
|
||||
----------------
|
||||
Draws contours outlines or filled contours.
|
||||
|
||||
.. ocv:function:: void drawContours( InputOutputArray image, InputArrayOfArrays contours, int contourIdx, const Scalar& color, int thickness=1, int lineType=LINE_8, InputArray hierarchy=noArray(), int maxLevel=INT_MAX, Point offset=Point() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.drawContours(image, contours, contourIdx, color[, thickness[, lineType[, hierarchy[, maxLevel[, offset]]]]]) -> image
|
||||
|
||||
.. ocv:cfunction:: void cvDrawContours( CvArr * img, CvSeq* contour, CvScalar external_color, CvScalar hole_color, int max_level, int thickness=1, int line_type=8, CvPoint offset=cvPoint(0,0) )
|
||||
|
||||
:param image: Destination image.
|
||||
|
||||
:param contours: All the input contours. Each contour is stored as a point vector.
|
||||
|
||||
:param contourIdx: Parameter indicating a contour to draw. If it is negative, all the contours are drawn.
|
||||
|
||||
:param color: Color of the contours.
|
||||
|
||||
:param thickness: Thickness of lines the contours are drawn with. If it is negative (for example, ``thickness=CV_FILLED`` ), the contour interiors are
|
||||
drawn.
|
||||
|
||||
:param lineType: Line connectivity. See :ocv:func:`line` for details.
|
||||
|
||||
:param hierarchy: Optional information about hierarchy. It is only needed if you want to draw only some of the contours (see ``maxLevel`` ).
|
||||
|
||||
:param maxLevel: Maximal level for drawn contours. If it is 0, only
|
||||
the specified contour is drawn. If it is 1, the function draws the contour(s) and all the nested contours. If it is 2, the function draws the contours, all the nested contours, all the nested-to-nested contours, and so on. This parameter is only taken into account when there is ``hierarchy`` available.
|
||||
|
||||
:param offset: Optional contour shift parameter. Shift all the drawn contours by the specified :math:`\texttt{offset}=(dx,dy)` .
|
||||
|
||||
:param contour: Pointer to the first contour.
|
||||
|
||||
:param external_color: Color of external contours.
|
||||
|
||||
:param hole_color: Color of internal contours (holes).
|
||||
|
||||
The function draws contour outlines in the image if
|
||||
:math:`\texttt{thickness} \ge 0` or fills the area bounded by the contours if
|
||||
:math:`\texttt{thickness}<0` . The example below shows how to retrieve connected components from the binary image and label them: ::
|
||||
|
||||
#include "opencv2/imgproc.hpp"
|
||||
#include "opencv2/highgui.hpp"
|
||||
|
||||
using namespace cv;
|
||||
using namespace std;
|
||||
|
||||
int main( int argc, char** argv )
|
||||
{
|
||||
Mat src;
|
||||
// the first command-line parameter must be a filename of the binary
|
||||
// (black-n-white) image
|
||||
if( argc != 2 || !(src=imread(argv[1], 0)).data)
|
||||
return -1;
|
||||
|
||||
Mat dst = Mat::zeros(src.rows, src.cols, CV_8UC3);
|
||||
|
||||
src = src > 1;
|
||||
namedWindow( "Source", 1 );
|
||||
imshow( "Source", src );
|
||||
|
||||
vector<vector<Point> > contours;
|
||||
vector<Vec4i> hierarchy;
|
||||
|
||||
findContours( src, contours, hierarchy,
|
||||
RETR_CCOMP, CHAIN_APPROX_SIMPLE );
|
||||
|
||||
// iterate through all the top-level contours,
|
||||
// draw each connected component with its own random color
|
||||
int idx = 0;
|
||||
for( ; idx >= 0; idx = hierarchy[idx][0] )
|
||||
{
|
||||
Scalar color( rand()&255, rand()&255, rand()&255 );
|
||||
drawContours( dst, contours, idx, color, FILLED, 8, hierarchy );
|
||||
}
|
||||
|
||||
namedWindow( "Components", 1 );
|
||||
imshow( "Components", dst );
|
||||
waitKey(0);
|
||||
}
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the drawContour functionality can be found at opencv_source_code/samples/cpp/contours2.cpp
|
||||
* An example using drawContours to clean up a background segmentation result at opencv_source_code/samples/cpp/segment_objects.cpp
|
||||
|
||||
* (Python) An example using the drawContour functionality can be found at opencv_source/samples/python2/contours.py
|
||||
|
||||
|
||||
putText
|
||||
-----------
|
||||
Draws a text string.
|
||||
|
||||
.. ocv:function:: void putText( InputOutputArray img, const String& text, Point org, int fontFace, double fontScale, Scalar color, int thickness=1, int lineType=LINE_8, bool bottomLeftOrigin=false )
|
||||
|
||||
.. ocv:pyfunction:: cv2.putText(img, text, org, fontFace, fontScale, color[, thickness[, lineType[, bottomLeftOrigin]]]) -> None
|
||||
|
||||
.. ocv:cfunction:: void cvPutText( CvArr* img, const char* text, CvPoint org, const CvFont* font, CvScalar color )
|
||||
|
||||
:param img: Image.
|
||||
|
||||
:param text: Text string to be drawn.
|
||||
|
||||
:param org: Bottom-left corner of the text string in the image.
|
||||
|
||||
:param font: ``CvFont`` structure initialized using :ocv:cfunc:`InitFont`.
|
||||
|
||||
:param fontFace: Font type. One of ``FONT_HERSHEY_SIMPLEX``, ``FONT_HERSHEY_PLAIN``, ``FONT_HERSHEY_DUPLEX``, ``FONT_HERSHEY_COMPLEX``, ``FONT_HERSHEY_TRIPLEX``, ``FONT_HERSHEY_COMPLEX_SMALL``, ``FONT_HERSHEY_SCRIPT_SIMPLEX``, or ``FONT_HERSHEY_SCRIPT_COMPLEX``,
|
||||
where each of the font ID's can be combined with ``FONT_ITALIC`` to get the slanted letters.
|
||||
|
||||
:param fontScale: Font scale factor that is multiplied by the font-specific base size.
|
||||
|
||||
:param color: Text color.
|
||||
|
||||
:param thickness: Thickness of the lines used to draw a text.
|
||||
|
||||
:param lineType: Line type. See the ``line`` for details.
|
||||
|
||||
:param bottomLeftOrigin: When true, the image data origin is at the bottom-left corner. Otherwise, it is at the top-left corner.
|
||||
|
||||
The function ``putText`` renders the specified text string in the image.
|
||||
Symbols that cannot be rendered using the specified font are
|
||||
replaced by question marks. See
|
||||
:ocv:func:`getTextSize` for a text rendering code example.
|
||||
@@ -1,662 +0,0 @@
|
||||
Feature Detection
|
||||
=================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
Canny
|
||||
---------
|
||||
Finds edges in an image using the [Canny86]_ algorithm.
|
||||
|
||||
.. ocv:function:: void Canny( InputArray image, OutputArray edges, double threshold1, double threshold2, int apertureSize=3, bool L2gradient=false )
|
||||
|
||||
.. ocv:pyfunction:: cv2.Canny(image, threshold1, threshold2[, edges[, apertureSize[, L2gradient]]]) -> edges
|
||||
|
||||
.. ocv:cfunction:: void cvCanny( const CvArr* image, CvArr* edges, double threshold1, double threshold2, int aperture_size=3 )
|
||||
|
||||
:param image: 8-bit input image.
|
||||
|
||||
:param edges: output edge map; single channels 8-bit image, which has the same size as ``image`` .
|
||||
|
||||
:param threshold1: first threshold for the hysteresis procedure.
|
||||
|
||||
:param threshold2: second threshold for the hysteresis procedure.
|
||||
|
||||
:param apertureSize: aperture size for the :ocv:func:`Sobel` operator.
|
||||
|
||||
:param L2gradient: a flag, indicating whether a more accurate :math:`L_2` norm :math:`=\sqrt{(dI/dx)^2 + (dI/dy)^2}` should be used to calculate the image gradient magnitude ( ``L2gradient=true`` ), or whether the default :math:`L_1` norm :math:`=|dI/dx|+|dI/dy|` is enough ( ``L2gradient=false`` ).
|
||||
|
||||
The function finds edges in the input image ``image`` and marks them in the output map ``edges`` using the Canny algorithm. The smallest value between ``threshold1`` and ``threshold2`` is used for edge linking. The largest value is used to find initial segments of strong edges. See
|
||||
http://en.wikipedia.org/wiki/Canny_edge_detector
|
||||
|
||||
.. note::
|
||||
|
||||
* An example on using the canny edge detector can be found at opencv_source_code/samples/cpp/edge.cpp
|
||||
|
||||
* (Python) An example on using the canny edge detector can be found at opencv_source_code/samples/python/edge.py
|
||||
|
||||
cornerEigenValsAndVecs
|
||||
----------------------
|
||||
Calculates eigenvalues and eigenvectors of image blocks for corner detection.
|
||||
|
||||
.. ocv:function:: void cornerEigenValsAndVecs( InputArray src, OutputArray dst, int blockSize, int ksize, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.cornerEigenValsAndVecs(src, blockSize, ksize[, dst[, borderType]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvCornerEigenValsAndVecs( const CvArr* image, CvArr* eigenvv, int block_size, int aperture_size=3 )
|
||||
|
||||
:param src: Input single-channel 8-bit or floating-point image.
|
||||
|
||||
:param dst: Image to store the results. It has the same size as ``src`` and the type ``CV_32FC(6)`` .
|
||||
|
||||
:param blockSize: Neighborhood size (see details below).
|
||||
|
||||
:param ksize: Aperture parameter for the :ocv:func:`Sobel` operator.
|
||||
|
||||
:param borderType: Pixel extrapolation method. See :ocv:func:`borderInterpolate` .
|
||||
|
||||
For every pixel
|
||||
:math:`p` , the function ``cornerEigenValsAndVecs`` considers a ``blockSize`` :math:`\times` ``blockSize`` neighborhood
|
||||
:math:`S(p)` . It calculates the covariation matrix of derivatives over the neighborhood as:
|
||||
|
||||
.. math::
|
||||
|
||||
M = \begin{bmatrix} \sum _{S(p)}(dI/dx)^2 & \sum _{S(p)}dI/dx dI/dy \\ \sum _{S(p)}dI/dx dI/dy & \sum _{S(p)}(dI/dy)^2 \end{bmatrix}
|
||||
|
||||
where the derivatives are computed using the
|
||||
:ocv:func:`Sobel` operator.
|
||||
|
||||
After that, it finds eigenvectors and eigenvalues of
|
||||
:math:`M` and stores them in the destination image as
|
||||
:math:`(\lambda_1, \lambda_2, x_1, y_1, x_2, y_2)` where
|
||||
|
||||
* :math:`\lambda_1, \lambda_2` are the non-sorted eigenvalues of :math:`M`
|
||||
|
||||
* :math:`x_1, y_1` are the eigenvectors corresponding to :math:`\lambda_1`
|
||||
|
||||
* :math:`x_2, y_2` are the eigenvectors corresponding to :math:`\lambda_2`
|
||||
|
||||
The output of the function can be used for robust edge or corner detection.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`cornerMinEigenVal`,
|
||||
:ocv:func:`cornerHarris`,
|
||||
:ocv:func:`preCornerDetect`
|
||||
|
||||
.. note::
|
||||
|
||||
* (Python) An example on how to use eigenvectors and eigenvalues to estimate image texture flow direction can be found at opencv_source_code/samples/python2/texture_flow.py
|
||||
|
||||
cornerHarris
|
||||
------------
|
||||
Harris corner detector.
|
||||
|
||||
.. ocv:function:: void cornerHarris( InputArray src, OutputArray dst, int blockSize, int ksize, double k, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.cornerHarris(src, blockSize, ksize, k[, dst[, borderType]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvCornerHarris( const CvArr* image, CvArr* harris_response, int block_size, int aperture_size=3, double k=0.04 )
|
||||
|
||||
:param src: Input single-channel 8-bit or floating-point image.
|
||||
|
||||
:param dst: Image to store the Harris detector responses. It has the type ``CV_32FC1`` and the same size as ``src`` .
|
||||
|
||||
:param blockSize: Neighborhood size (see the details on :ocv:func:`cornerEigenValsAndVecs` ).
|
||||
|
||||
:param ksize: Aperture parameter for the :ocv:func:`Sobel` operator.
|
||||
|
||||
:param k: Harris detector free parameter. See the formula below.
|
||||
|
||||
:param borderType: Pixel extrapolation method. See :ocv:func:`borderInterpolate` .
|
||||
|
||||
The function runs the Harris corner detector on the image. Similarly to
|
||||
:ocv:func:`cornerMinEigenVal` and
|
||||
:ocv:func:`cornerEigenValsAndVecs` , for each pixel
|
||||
:math:`(x, y)` it calculates a
|
||||
:math:`2\times2` gradient covariance matrix
|
||||
:math:`M^{(x,y)}` over a
|
||||
:math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood. Then, it computes the following characteristic:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \mathrm{det} M^{(x,y)} - k \cdot \left ( \mathrm{tr} M^{(x,y)} \right )^2
|
||||
|
||||
Corners in the image can be found as the local maxima of this response map.
|
||||
|
||||
|
||||
|
||||
cornerMinEigenVal
|
||||
-----------------
|
||||
Calculates the minimal eigenvalue of gradient matrices for corner detection.
|
||||
|
||||
.. ocv:function:: void cornerMinEigenVal( InputArray src, OutputArray dst, int blockSize, int ksize=3, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.cornerMinEigenVal(src, blockSize[, dst[, ksize[, borderType]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvCornerMinEigenVal( const CvArr* image, CvArr* eigenval, int block_size, int aperture_size=3 )
|
||||
|
||||
:param src: Input single-channel 8-bit or floating-point image.
|
||||
|
||||
:param dst: Image to store the minimal eigenvalues. It has the type ``CV_32FC1`` and the same size as ``src`` .
|
||||
|
||||
:param blockSize: Neighborhood size (see the details on :ocv:func:`cornerEigenValsAndVecs` ).
|
||||
|
||||
:param ksize: Aperture parameter for the :ocv:func:`Sobel` operator.
|
||||
|
||||
:param borderType: Pixel extrapolation method. See :ocv:func:`borderInterpolate` .
|
||||
|
||||
The function is similar to
|
||||
:ocv:func:`cornerEigenValsAndVecs` but it calculates and stores only the minimal eigenvalue of the covariance matrix of derivatives, that is,
|
||||
:math:`\min(\lambda_1, \lambda_2)` in terms of the formulae in the
|
||||
:ocv:func:`cornerEigenValsAndVecs` description.
|
||||
|
||||
|
||||
|
||||
cornerSubPix
|
||||
----------------
|
||||
Refines the corner locations.
|
||||
|
||||
.. ocv:function:: void cornerSubPix( InputArray image, InputOutputArray corners, Size winSize, Size zeroZone, TermCriteria criteria )
|
||||
|
||||
.. ocv:pyfunction:: cv2.cornerSubPix(image, corners, winSize, zeroZone, criteria) -> corners
|
||||
|
||||
.. ocv:cfunction:: void cvFindCornerSubPix( const CvArr* image, CvPoint2D32f* corners, int count, CvSize win, CvSize zero_zone, CvTermCriteria criteria )
|
||||
|
||||
:param image: Input image.
|
||||
|
||||
:param corners: Initial coordinates of the input corners and refined coordinates provided for output.
|
||||
|
||||
:param winSize: Half of the side length of the search window. For example, if ``winSize=Size(5,5)`` , then a :math:`5*2+1 \times 5*2+1 = 11 \times 11` search window is used.
|
||||
|
||||
:param zeroZone: Half of the size of the dead region in the middle of the search zone over which the summation in the formula below is not done. It is used sometimes to avoid possible singularities of the autocorrelation matrix. The value of (-1,-1) indicates that there is no such a size.
|
||||
|
||||
:param criteria: Criteria for termination of the iterative process of corner refinement. That is, the process of corner position refinement stops either after ``criteria.maxCount`` iterations or when the corner position moves by less than ``criteria.epsilon`` on some iteration.
|
||||
|
||||
The function iterates to find the sub-pixel accurate location of corners or radial saddle points, as shown on the figure below.
|
||||
|
||||
.. image:: pics/cornersubpix.png
|
||||
|
||||
Sub-pixel accurate corner locator is based on the observation that every vector from the center
|
||||
:math:`q` to a point
|
||||
:math:`p` located within a neighborhood of
|
||||
:math:`q` is orthogonal to the image gradient at
|
||||
:math:`p` subject to image and measurement noise. Consider the expression:
|
||||
|
||||
.. math::
|
||||
|
||||
\epsilon _i = {DI_{p_i}}^T \cdot (q - p_i)
|
||||
|
||||
where
|
||||
:math:`{DI_{p_i}}` is an image gradient at one of the points
|
||||
:math:`p_i` in a neighborhood of
|
||||
:math:`q` . The value of
|
||||
:math:`q` is to be found so that
|
||||
:math:`\epsilon_i` is minimized. A system of equations may be set up with
|
||||
:math:`\epsilon_i` set to zero:
|
||||
|
||||
.. math::
|
||||
|
||||
\sum _i(DI_{p_i} \cdot {DI_{p_i}}^T) - \sum _i(DI_{p_i} \cdot {DI_{p_i}}^T \cdot p_i)
|
||||
|
||||
where the gradients are summed within a neighborhood ("search window") of
|
||||
:math:`q` . Calling the first gradient term
|
||||
:math:`G` and the second gradient term
|
||||
:math:`b` gives:
|
||||
|
||||
.. math::
|
||||
|
||||
q = G^{-1} \cdot b
|
||||
|
||||
The algorithm sets the center of the neighborhood window at this new center
|
||||
:math:`q` and then iterates until the center stays within a set threshold.
|
||||
|
||||
|
||||
|
||||
goodFeaturesToTrack
|
||||
-------------------
|
||||
Determines strong corners on an image.
|
||||
|
||||
.. ocv:function:: void goodFeaturesToTrack( InputArray image, OutputArray corners, int maxCorners, double qualityLevel, double minDistance, InputArray mask=noArray(), int blockSize=3, bool useHarrisDetector=false, double k=0.04 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.goodFeaturesToTrack(image, maxCorners, qualityLevel, minDistance[, corners[, mask[, blockSize[, useHarrisDetector[, k]]]]]) -> corners
|
||||
|
||||
.. ocv:cfunction:: void cvGoodFeaturesToTrack( const CvArr* image, CvArr* eig_image, CvArr* temp_image, CvPoint2D32f* corners, int* corner_count, double quality_level, double min_distance, const CvArr* mask=NULL, int block_size=3, int use_harris=0, double k=0.04 )
|
||||
|
||||
:param image: Input 8-bit or floating-point 32-bit, single-channel image.
|
||||
|
||||
:param eig_image: The parameter is ignored.
|
||||
|
||||
:param temp_image: The parameter is ignored.
|
||||
|
||||
:param corners: Output vector of detected corners.
|
||||
|
||||
:param maxCorners: Maximum number of corners to return. If there are more corners than are found, the strongest of them is returned.
|
||||
|
||||
:param qualityLevel: Parameter characterizing the minimal accepted quality of image corners. The parameter value is multiplied by the best corner quality measure, which is the minimal eigenvalue (see :ocv:func:`cornerMinEigenVal` ) or the Harris function response (see :ocv:func:`cornerHarris` ). The corners with the quality measure less than the product are rejected. For example, if the best corner has the quality measure = 1500, and the ``qualityLevel=0.01`` , then all the corners with the quality measure less than 15 are rejected.
|
||||
|
||||
:param minDistance: Minimum possible Euclidean distance between the returned corners.
|
||||
|
||||
:param mask: Optional region of interest. If the image is not empty (it needs to have the type ``CV_8UC1`` and the same size as ``image`` ), it specifies the region in which the corners are detected.
|
||||
|
||||
:param blockSize: Size of an average block for computing a derivative covariation matrix over each pixel neighborhood. See :ocv:func:`cornerEigenValsAndVecs` .
|
||||
|
||||
:param useHarrisDetector: Parameter indicating whether to use a Harris detector (see :ocv:func:`cornerHarris`) or :ocv:func:`cornerMinEigenVal`.
|
||||
|
||||
:param k: Free parameter of the Harris detector.
|
||||
|
||||
The function finds the most prominent corners in the image or in the specified image region, as described in [Shi94]_:
|
||||
|
||||
#.
|
||||
Function calculates the corner quality measure at every source image pixel using the
|
||||
:ocv:func:`cornerMinEigenVal` or
|
||||
:ocv:func:`cornerHarris` .
|
||||
|
||||
#.
|
||||
Function performs a non-maximum suppression (the local maximums in *3 x 3* neighborhood are retained).
|
||||
|
||||
#.
|
||||
The corners with the minimal eigenvalue less than
|
||||
:math:`\texttt{qualityLevel} \cdot \max_{x,y} qualityMeasureMap(x,y)` are rejected.
|
||||
|
||||
#.
|
||||
The remaining corners are sorted by the quality measure in the descending order.
|
||||
|
||||
#.
|
||||
Function throws away each corner for which there is a stronger corner at a distance less than ``maxDistance``.
|
||||
|
||||
The function can be used to initialize a point-based tracker of an object.
|
||||
|
||||
.. note:: If the function is called with different values ``A`` and ``B`` of the parameter ``qualityLevel`` , and ``A`` > ``B``, the vector of returned corners with ``qualityLevel=A`` will be the prefix of the output vector with ``qualityLevel=B`` .
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`cornerMinEigenVal`,
|
||||
:ocv:func:`cornerHarris`,
|
||||
:ocv:func:`calcOpticalFlowPyrLK`,
|
||||
:ocv:func:`estimateRigidTransform`,
|
||||
|
||||
|
||||
HoughCircles
|
||||
------------
|
||||
Finds circles in a grayscale image using a modification of the Hough transform.
|
||||
|
||||
.. ocv:function:: void HoughCircles( InputArray image, OutputArray circles, int method, double dp, double minDist, double param1=100, double param2=100, int minRadius=0, int maxRadius=0 )
|
||||
|
||||
.. ocv:cfunction:: CvSeq* cvHoughCircles( CvArr* image, void* circle_storage, int method, double dp, double min_dist, double param1=100, double param2=100, int min_radius=0, int max_radius=0 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.HoughCircles(image, method, dp, minDist[, circles[, param1[, param2[, minRadius[, maxRadius]]]]]) -> circles
|
||||
|
||||
:param image: 8-bit, single-channel, grayscale input image.
|
||||
|
||||
:param circles: Output vector of found circles. Each vector is encoded as a 3-element floating-point vector :math:`(x, y, radius)` .
|
||||
|
||||
:param circle_storage: In C function this is a memory storage that will contain the output sequence of found circles.
|
||||
|
||||
:param method: Detection method to use. Currently, the only implemented method is ``CV_HOUGH_GRADIENT`` , which is basically *21HT* , described in [Yuen90]_.
|
||||
|
||||
:param dp: Inverse ratio of the accumulator resolution to the image resolution. For example, if ``dp=1`` , the accumulator has the same resolution as the input image. If ``dp=2`` , the accumulator has half as big width and height.
|
||||
|
||||
:param minDist: Minimum distance between the centers of the detected circles. If the parameter is too small, multiple neighbor circles may be falsely detected in addition to a true one. If it is too large, some circles may be missed.
|
||||
|
||||
:param param1: First method-specific parameter. In case of ``CV_HOUGH_GRADIENT`` , it is the higher threshold of the two passed to the :ocv:func:`Canny` edge detector (the lower one is twice smaller).
|
||||
|
||||
:param param2: Second method-specific parameter. In case of ``CV_HOUGH_GRADIENT`` , it is the accumulator threshold for the circle centers at the detection stage. The smaller it is, the more false circles may be detected. Circles, corresponding to the larger accumulator values, will be returned first.
|
||||
|
||||
:param minRadius: Minimum circle radius.
|
||||
|
||||
:param maxRadius: Maximum circle radius.
|
||||
|
||||
Example: ::
|
||||
|
||||
#include <opencv2/imgproc.hpp>
|
||||
#include <opencv2/highgui.hpp>
|
||||
#include <math.h>
|
||||
|
||||
using namespace cv;
|
||||
|
||||
int main(int argc, char** argv)
|
||||
{
|
||||
Mat img, gray;
|
||||
if( argc != 2 && !(img=imread(argv[1], 1)).data)
|
||||
return -1;
|
||||
cvtColor(img, gray, COLOR_BGR2GRAY);
|
||||
// smooth it, otherwise a lot of false circles may be detected
|
||||
GaussianBlur( gray, gray, Size(9, 9), 2, 2 );
|
||||
vector<Vec3f> circles;
|
||||
HoughCircles(gray, circles, HOUGH_GRADIENT,
|
||||
2, gray->rows/4, 200, 100 );
|
||||
for( size_t i = 0; i < circles.size(); i++ )
|
||||
{
|
||||
Point center(cvRound(circles[i][0]), cvRound(circles[i][1]));
|
||||
int radius = cvRound(circles[i][2]);
|
||||
// draw the circle center
|
||||
circle( img, center, 3, Scalar(0,255,0), -1, 8, 0 );
|
||||
// draw the circle outline
|
||||
circle( img, center, radius, Scalar(0,0,255), 3, 8, 0 );
|
||||
}
|
||||
namedWindow( "circles", 1 );
|
||||
imshow( "circles", img );
|
||||
return 0;
|
||||
}
|
||||
|
||||
.. note:: The elements of the output vector of found circles ("circles" in the above example) are sorted in descending order of accumulator values. This way, the centres with the most supporting pixels appear first.
|
||||
|
||||
.. note:: Usually the function detects the centers of circles well. However, it may fail to find correct radii. You can assist to the function by specifying the radius range ( ``minRadius`` and ``maxRadius`` ) if you know it. Or, you may ignore the returned radius, use only the center, and find the correct radius using an additional procedure.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`fitEllipse`,
|
||||
:ocv:func:`minEnclosingCircle`
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the Hough circle detector can be found at opencv_source_code/samples/cpp/houghcircles.cpp
|
||||
|
||||
HoughLines
|
||||
----------
|
||||
Finds lines in a binary image using the standard Hough transform.
|
||||
|
||||
.. ocv:function:: void HoughLines( InputArray image, OutputArray lines, double rho, double theta, int threshold, double srn=0, double stn=0, double min_theta=0, double max_theta=CV_PI )
|
||||
|
||||
.. ocv:pyfunction:: cv2.HoughLines(image, rho, theta, threshold[, lines[, srn[, stn[, min_theta[, max_theta]]]]]) -> lines
|
||||
|
||||
.. ocv:cfunction:: CvSeq* cvHoughLines2( CvArr* image, void* line_storage, int method, double rho, double theta, int threshold, double param1=0, double param2=0, double min_theta=0, double max_theta=CV_PI )
|
||||
|
||||
:param image: 8-bit, single-channel binary source image. The image may be modified by the function.
|
||||
|
||||
:param lines: Output vector of lines. Each line is represented by a two-element vector :math:`(\rho, \theta)` . :math:`\rho` is the distance from the coordinate origin :math:`(0,0)` (top-left corner of the image). :math:`\theta` is the line rotation angle in radians ( :math:`0 \sim \textrm{vertical line}, \pi/2 \sim \textrm{horizontal line}` ).
|
||||
|
||||
:param rho: Distance resolution of the accumulator in pixels.
|
||||
|
||||
:param theta: Angle resolution of the accumulator in radians.
|
||||
|
||||
:param threshold: Accumulator threshold parameter. Only those lines are returned that get enough votes ( :math:`>\texttt{threshold}` ).
|
||||
|
||||
:param srn: For the multi-scale Hough transform, it is a divisor for the distance resolution ``rho`` . The coarse accumulator distance resolution is ``rho`` and the accurate accumulator resolution is ``rho/srn`` . If both ``srn=0`` and ``stn=0`` , the classical Hough transform is used. Otherwise, both these parameters should be positive.
|
||||
|
||||
:param stn: For the multi-scale Hough transform, it is a divisor for the distance resolution ``theta``.
|
||||
|
||||
:param min_theta: For standard and multi-scale Hough transform, minimum angle to check for lines. Must fall between 0 and max_theta.
|
||||
|
||||
:param max_theta: For standard and multi-scale Hough transform, maximum angle to check for lines. Must fall between min_theta and CV_PI.
|
||||
|
||||
:param method: One of the following Hough transform variants:
|
||||
|
||||
* **CV_HOUGH_STANDARD** classical or standard Hough transform. Every line is represented by two floating-point numbers :math:`(\rho, \theta)` , where :math:`\rho` is a distance between (0,0) point and the line, and :math:`\theta` is the angle between x-axis and the normal to the line. Thus, the matrix must be (the created sequence will be) of ``CV_32FC2`` type
|
||||
|
||||
|
||||
* **CV_HOUGH_PROBABILISTIC** probabilistic Hough transform (more efficient in case if the picture contains a few long linear segments). It returns line segments rather than the whole line. Each segment is represented by starting and ending points, and the matrix must be (the created sequence will be) of the ``CV_32SC4`` type.
|
||||
|
||||
* **CV_HOUGH_MULTI_SCALE** multi-scale variant of the classical Hough transform. The lines are encoded the same way as ``CV_HOUGH_STANDARD``.
|
||||
|
||||
|
||||
:param param1: First method-dependent parameter:
|
||||
|
||||
* For the classical Hough transform, it is not used (0).
|
||||
|
||||
* For the probabilistic Hough transform, it is the minimum line length.
|
||||
|
||||
* For the multi-scale Hough transform, it is ``srn``.
|
||||
|
||||
:param param2: Second method-dependent parameter:
|
||||
|
||||
* For the classical Hough transform, it is not used (0).
|
||||
|
||||
* For the probabilistic Hough transform, it is the maximum gap between line segments lying on the same line to treat them as a single line segment (that is, to join them).
|
||||
|
||||
* For the multi-scale Hough transform, it is ``stn``.
|
||||
|
||||
The function implements the standard or standard multi-scale Hough transform algorithm for line detection. See http://homepages.inf.ed.ac.uk/rbf/HIPR2/hough.htm for a good explanation of Hough transform.
|
||||
See also the example in :ocv:func:`HoughLinesP` description.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the Hough line detector can be found at opencv_source_code/samples/cpp/houghlines.cpp
|
||||
|
||||
HoughLinesP
|
||||
-----------
|
||||
Finds line segments in a binary image using the probabilistic Hough transform.
|
||||
|
||||
.. ocv:function:: void HoughLinesP( InputArray image, OutputArray lines, double rho, double theta, int threshold, double minLineLength=0, double maxLineGap=0 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.HoughLinesP(image, rho, theta, threshold[, lines[, minLineLength[, maxLineGap]]]) -> lines
|
||||
|
||||
:param image: 8-bit, single-channel binary source image. The image may be modified by the function.
|
||||
|
||||
:param lines: Output vector of lines. Each line is represented by a 4-element vector :math:`(x_1, y_1, x_2, y_2)` , where :math:`(x_1,y_1)` and :math:`(x_2, y_2)` are the ending points of each detected line segment.
|
||||
|
||||
:param rho: Distance resolution of the accumulator in pixels.
|
||||
|
||||
:param theta: Angle resolution of the accumulator in radians.
|
||||
|
||||
:param threshold: Accumulator threshold parameter. Only those lines are returned that get enough votes ( :math:`>\texttt{threshold}` ).
|
||||
|
||||
:param minLineLength: Minimum line length. Line segments shorter than that are rejected.
|
||||
|
||||
:param maxLineGap: Maximum allowed gap between points on the same line to link them.
|
||||
|
||||
The function implements the probabilistic Hough transform algorithm for line detection, described in
|
||||
[Matas00]_. See the line detection example below: ::
|
||||
|
||||
/* This is a standalone program. Pass an image name as the first parameter
|
||||
of the program. Switch between standard and probabilistic Hough transform
|
||||
by changing "#if 1" to "#if 0" and back */
|
||||
#include <opencv2/imgproc.hpp>
|
||||
#include <opencv2/highgui.hpp>
|
||||
|
||||
using namespace cv;
|
||||
|
||||
int main(int argc, char** argv)
|
||||
{
|
||||
Mat src, dst, color_dst;
|
||||
if( argc != 2 || !(src=imread(argv[1], 0)).data)
|
||||
return -1;
|
||||
|
||||
Canny( src, dst, 50, 200, 3 );
|
||||
cvtColor( dst, color_dst, COLOR_GRAY2BGR );
|
||||
|
||||
#if 0
|
||||
vector<Vec2f> lines;
|
||||
HoughLines( dst, lines, 1, CV_PI/180, 100 );
|
||||
|
||||
for( size_t i = 0; i < lines.size(); i++ )
|
||||
{
|
||||
float rho = lines[i][0];
|
||||
float theta = lines[i][1];
|
||||
double a = cos(theta), b = sin(theta);
|
||||
double x0 = a*rho, y0 = b*rho;
|
||||
Point pt1(cvRound(x0 + 1000*(-b)),
|
||||
cvRound(y0 + 1000*(a)));
|
||||
Point pt2(cvRound(x0 - 1000*(-b)),
|
||||
cvRound(y0 - 1000*(a)));
|
||||
line( color_dst, pt1, pt2, Scalar(0,0,255), 3, 8 );
|
||||
}
|
||||
#else
|
||||
vector<Vec4i> lines;
|
||||
HoughLinesP( dst, lines, 1, CV_PI/180, 80, 30, 10 );
|
||||
for( size_t i = 0; i < lines.size(); i++ )
|
||||
{
|
||||
line( color_dst, Point(lines[i][0], lines[i][1]),
|
||||
Point(lines[i][2], lines[i][3]), Scalar(0,0,255), 3, 8 );
|
||||
}
|
||||
#endif
|
||||
namedWindow( "Source", 1 );
|
||||
imshow( "Source", src );
|
||||
|
||||
namedWindow( "Detected Lines", 1 );
|
||||
imshow( "Detected Lines", color_dst );
|
||||
|
||||
waitKey(0);
|
||||
return 0;
|
||||
}
|
||||
|
||||
This is a sample picture the function parameters have been tuned for:
|
||||
|
||||
.. image:: pics/building.jpg
|
||||
|
||||
And this is the output of the above program in case of the probabilistic Hough transform:
|
||||
|
||||
.. image:: pics/houghp.png
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:class:`LineSegmentDetector`
|
||||
|
||||
|
||||
|
||||
LineSegmentDetector
|
||||
-------------------
|
||||
Line segment detector class, following the algorithm described at [Rafael12]_.
|
||||
|
||||
.. ocv:class:: LineSegmentDetector : public Algorithm
|
||||
|
||||
|
||||
createLineSegmentDetector
|
||||
-------------------------
|
||||
Creates a smart pointer to a LineSegmentDetector object and initializes it.
|
||||
|
||||
.. ocv:function:: Ptr<LineSegmentDetector> createLineSegmentDetector(int _refine = LSD_REFINE_STD, double _scale = 0.8, double _sigma_scale = 0.6, double _quant = 2.0, double _ang_th = 22.5, double _log_eps = 0, double _density_th = 0.7, int _n_bins = 1024)
|
||||
|
||||
.. ocv:pyfunction:: cv2.createLineSegmentDetector([, _refine[, _scale[, _sigma_scale[, _quant[, _ang_th[, _log_eps[, _density_th[, _n_bins]]]]]]]]) -> retval
|
||||
|
||||
:param _refine: The way found lines will be refined:
|
||||
|
||||
* **LSD_REFINE_NONE** - No refinement applied.
|
||||
|
||||
* **LSD_REFINE_STD** - Standard refinement is applied. E.g. breaking arches into smaller straighter line approximations.
|
||||
|
||||
* **LSD_REFINE_ADV** - Advanced refinement. Number of false alarms is calculated, lines are refined through increase of precision, decrement in size, etc.
|
||||
|
||||
:param scale: The scale of the image that will be used to find the lines. Range (0..1].
|
||||
|
||||
:param sigma_scale: Sigma for Gaussian filter. It is computed as sigma = _sigma_scale/_scale.
|
||||
|
||||
:param quant: Bound to the quantization error on the gradient norm.
|
||||
|
||||
:param ang_th: Gradient angle tolerance in degrees.
|
||||
|
||||
:param log_eps: Detection threshold: -log10(NFA) > log_eps. Used only when advancent refinement is chosen.
|
||||
|
||||
:param density_th: Minimal density of aligned region points in the enclosing rectangle.
|
||||
|
||||
:param n_bins: Number of bins in pseudo-ordering of gradient modulus.
|
||||
|
||||
The LineSegmentDetector algorithm is defined using the standard values. Only advanced users may want to edit those, as to tailor it for their own application.
|
||||
|
||||
|
||||
LineSegmentDetector::detect
|
||||
---------------------------
|
||||
Finds lines in the input image. See the lsd_lines.cpp sample for possible usage.
|
||||
|
||||
.. ocv:function:: void LineSegmentDetector::detect(const InputArray _image, OutputArray _lines, OutputArray width = noArray(), OutputArray prec = noArray(), OutputArray nfa = noArray())
|
||||
|
||||
.. ocv:pyfunction:: cv2.createLineSegmentDetector.detect(_image[, _lines[, width[, prec[, nfa]]]]) -> _lines, width, prec, nfa
|
||||
|
||||
:param _image A grayscale (CV_8UC1) input image.
|
||||
If only a roi needs to be selected, use ::
|
||||
lsd_ptr->detect(image(roi), lines, ...);
|
||||
lines += Scalar(roi.x, roi.y, roi.x, roi.y);
|
||||
|
||||
:param lines: A vector of Vec4i elements specifying the beginning and ending point of a line. Where Vec4i is (x1, y1, x2, y2), point 1 is the start, point 2 - end. Returned lines are strictly oriented depending on the gradient.
|
||||
|
||||
:param width: Vector of widths of the regions, where the lines are found. E.g. Width of line.
|
||||
|
||||
:param prec: Vector of precisions with which the lines are found.
|
||||
|
||||
:param nfa: Vector containing number of false alarms in the line region, with precision of 10%. The bigger the value, logarithmically better the detection.
|
||||
|
||||
* -1 corresponds to 10 mean false alarms
|
||||
|
||||
* 0 corresponds to 1 mean false alarm
|
||||
|
||||
* 1 corresponds to 0.1 mean false alarms
|
||||
|
||||
This vector will be calculated only when the objects type is LSD_REFINE_ADV.
|
||||
|
||||
This is the output of the default parameters of the algorithm on the above shown image.
|
||||
|
||||
.. image:: pics/building_lsd.png
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the LineSegmentDetector can be found at opencv_source_code/samples/cpp/lsd_lines.cpp
|
||||
|
||||
LineSegmentDetector::drawSegments
|
||||
---------------------------------
|
||||
Draws the line segments on a given image.
|
||||
|
||||
.. ocv:function:: void LineSegmentDetector::drawSegments(InputOutputArray _image, InputArray lines)
|
||||
|
||||
.. ocv:pyfunction:: cv2.createLineSegmentDetector.drawSegments(_image, lines) -> _image
|
||||
|
||||
:param image: The image, where the liens will be drawn. Should be bigger or equal to the image, where the lines were found.
|
||||
|
||||
:param lines: A vector of the lines that needed to be drawn.
|
||||
|
||||
|
||||
LineSegmentDetector::compareSegments
|
||||
------------------------------------
|
||||
Draws two groups of lines in blue and red, counting the non overlapping (mismatching) pixels.
|
||||
|
||||
.. ocv:function:: int LineSegmentDetector::compareSegments(const Size& size, InputArray lines1, InputArray lines2, InputOutputArray _image = noArray())
|
||||
|
||||
.. ocv:pyfunction:: cv2.createLineSegmentDetector.compareSegments(size, lines1, lines2[, _image]) -> retval, _image
|
||||
|
||||
:param size: The size of the image, where lines1 and lines2 were found.
|
||||
|
||||
:param lines1: The first group of lines that needs to be drawn. It is visualized in blue color.
|
||||
|
||||
:param lines2: The second group of lines. They visualized in red color.
|
||||
|
||||
:param image: Optional image, where the lines will be drawn. The image should be color(3-channel) in order for lines1 and lines2 to be drawn in the above mentioned colors.
|
||||
|
||||
|
||||
|
||||
preCornerDetect
|
||||
---------------
|
||||
Calculates a feature map for corner detection.
|
||||
|
||||
.. ocv:function:: void preCornerDetect( InputArray src, OutputArray dst, int ksize, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.preCornerDetect(src, ksize[, dst[, borderType]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvPreCornerDetect( const CvArr* image, CvArr* corners, int aperture_size=3 )
|
||||
|
||||
:param src: Source single-channel 8-bit of floating-point image.
|
||||
|
||||
:param dst: Output image that has the type ``CV_32F`` and the same size as ``src`` .
|
||||
|
||||
:param ksize: Aperture size of the :ocv:func:`Sobel` .
|
||||
|
||||
:param borderType: Pixel extrapolation method. See :ocv:func:`borderInterpolate` .
|
||||
|
||||
The function calculates the complex spatial derivative-based function of the source image
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} = (D_x \texttt{src} )^2 \cdot D_{yy} \texttt{src} + (D_y \texttt{src} )^2 \cdot D_{xx} \texttt{src} - 2 D_x \texttt{src} \cdot D_y \texttt{src} \cdot D_{xy} \texttt{src}
|
||||
|
||||
where
|
||||
:math:`D_x`,:math:`D_y` are the first image derivatives,
|
||||
:math:`D_{xx}`,:math:`D_{yy}` are the second image derivatives, and
|
||||
:math:`D_{xy}` is the mixed derivative.
|
||||
|
||||
The corners can be found as local maximums of the functions, as shown below: ::
|
||||
|
||||
Mat corners, dilated_corners;
|
||||
preCornerDetect(image, corners, 3);
|
||||
// dilation with 3x3 rectangular structuring element
|
||||
dilate(corners, dilated_corners, Mat(), 1);
|
||||
Mat corner_mask = corners == dilated_corners;
|
||||
|
||||
.. [Canny86] J. Canny. *A Computational Approach to Edge Detection*, IEEE Trans. on Pattern Analysis and Machine Intelligence, 8(6), pp. 679-698 (1986).
|
||||
|
||||
.. [Matas00] Matas, J. and Galambos, C. and Kittler, J.V., *Robust Detection of Lines Using the Progressive Probabilistic Hough Transform*. CVIU 78 1, pp 119-137 (2000)
|
||||
|
||||
.. [Shi94] J. Shi and C. Tomasi. *Good Features to Track*. Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition, pages 593-600, June 1994.
|
||||
|
||||
.. [Yuen90] Yuen, H. K. and Princen, J. and Illingworth, J. and Kittler, J., *Comparative study of Hough transform methods for circle finding*. Image Vision Comput. 8 1, pp 71–77 (1990)
|
||||
|
||||
.. [Rafael12] Rafael Grompone von Gioi, Jérémie Jakubowicz, Jean-Michel Morel, and Gregory Randall, LSD: a Line Segment Detector, Image Processing On Line, vol. 2012. http://dx.doi.org/10.5201/ipol.2012.gjmr-lsd
|
||||
@@ -1,950 +0,0 @@
|
||||
Image Filtering
|
||||
===============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
Functions and classes described in this section are used to perform various linear or non-linear filtering operations on 2D images (represented as
|
||||
:ocv:func:`Mat`'s). It means that for each pixel location
|
||||
:math:`(x,y)` in the source image (normally, rectangular), its neighborhood is considered and used to compute the response. In case of a linear filter, it is a weighted sum of pixel values. In case of morphological operations, it is the minimum or maximum values, and so on. The computed response is stored in the destination image at the same location
|
||||
:math:`(x,y)` . It means that the output image will be of the same size as the input image. Normally, the functions support multi-channel arrays, in which case every channel is processed independently. Therefore, the output image will also have the same number of channels as the input one.
|
||||
|
||||
Another common feature of the functions and classes described in this section is that, unlike simple arithmetic functions, they need to extrapolate values of some non-existing pixels. For example, if you want to smooth an image using a Gaussian
|
||||
:math:`3 \times 3` filter, then, when processing the left-most pixels in each row, you need pixels to the left of them, that is, outside of the image. You can let these pixels be the same as the left-most image pixels ("replicated border" extrapolation method), or assume that all the non-existing pixels are zeros ("constant border" extrapolation method), and so on.
|
||||
OpenCV enables you to specify the extrapolation method. For details, see the function ``borderInterpolate`` and discussion of the ``borderType`` parameter in the section and various functions below. ::
|
||||
|
||||
/*
|
||||
Various border types, image boundaries are denoted with '|'
|
||||
|
||||
* BORDER_REPLICATE: aaaaaa|abcdefgh|hhhhhhh
|
||||
* BORDER_REFLECT: fedcba|abcdefgh|hgfedcb
|
||||
* BORDER_REFLECT_101: gfedcb|abcdefgh|gfedcba
|
||||
* BORDER_WRAP: cdefgh|abcdefgh|abcdefg
|
||||
* BORDER_CONSTANT: iiiiii|abcdefgh|iiiiiii with some specified 'i'
|
||||
*/
|
||||
|
||||
.. note::
|
||||
|
||||
* (Python) A complete example illustrating different morphological operations like erode/dilate, open/close, blackhat/tophat ... can be found at opencv_source_code/samples/python2/morphology.py
|
||||
|
||||
bilateralFilter
|
||||
-------------------
|
||||
Applies the bilateral filter to an image.
|
||||
|
||||
.. ocv:function:: void bilateralFilter( InputArray src, OutputArray dst, int d, double sigmaColor, double sigmaSpace, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.bilateralFilter(src, d, sigmaColor, sigmaSpace[, dst[, borderType]]) -> dst
|
||||
|
||||
:param src: Source 8-bit or floating-point, 1-channel or 3-channel image.
|
||||
|
||||
:param dst: Destination image of the same size and type as ``src`` .
|
||||
|
||||
:param d: Diameter of each pixel neighborhood that is used during filtering. If it is non-positive, it is computed from ``sigmaSpace`` .
|
||||
|
||||
:param sigmaColor: Filter sigma in the color space. A larger value of the parameter means that farther colors within the pixel neighborhood (see ``sigmaSpace`` ) will be mixed together, resulting in larger areas of semi-equal color.
|
||||
|
||||
:param sigmaSpace: Filter sigma in the coordinate space. A larger value of the parameter means that farther pixels will influence each other as long as their colors are close enough (see ``sigmaColor`` ). When ``d>0`` , it specifies the neighborhood size regardless of ``sigmaSpace`` . Otherwise, ``d`` is proportional to ``sigmaSpace`` .
|
||||
|
||||
The function applies bilateral filtering to the input image, as described in
|
||||
http://www.dai.ed.ac.uk/CVonline/LOCAL\_COPIES/MANDUCHI1/Bilateral\_Filtering.html
|
||||
``bilateralFilter`` can reduce unwanted noise very well while keeping edges fairly sharp. However, it is very slow compared to most filters.
|
||||
|
||||
*Sigma values*: For simplicity, you can set the 2 sigma values to be the same. If they are small (< 10), the filter will not have much effect, whereas if they are large (> 150), they will have a very strong effect, making the image look "cartoonish".
|
||||
|
||||
*Filter size*: Large filters (d > 5) are very slow, so it is recommended to use d=5 for real-time applications, and perhaps d=9 for offline applications that need heavy noise filtering.
|
||||
|
||||
This filter does not work inplace.
|
||||
|
||||
|
||||
blur
|
||||
----
|
||||
Blurs an image using the normalized box filter.
|
||||
|
||||
.. ocv:function:: void blur( InputArray src, OutputArray dst, Size ksize, Point anchor=Point(-1,-1), int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.blur(src, ksize[, dst[, anchor[, borderType]]]) -> dst
|
||||
|
||||
:param src: input image; it can have any number of channels, which are processed independently, but the depth should be ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32F`` or ``CV_64F``.
|
||||
|
||||
:param dst: output image of the same size and type as ``src``.
|
||||
|
||||
:param ksize: blurring kernel size.
|
||||
|
||||
:param anchor: anchor point; default value ``Point(-1,-1)`` means that the anchor is at the kernel center.
|
||||
|
||||
:param borderType: border mode used to extrapolate pixels outside of the image.
|
||||
|
||||
The function smoothes an image using the kernel:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{K} = \frac{1}{\texttt{ksize.width*ksize.height}} \begin{bmatrix} 1 & 1 & 1 & \cdots & 1 & 1 \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \hdotsfor{6} \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \end{bmatrix}
|
||||
|
||||
The call ``blur(src, dst, ksize, anchor, borderType)`` is equivalent to ``boxFilter(src, dst, src.type(), anchor, true, borderType)`` .
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`boxFilter`,
|
||||
:ocv:func:`bilateralFilter`,
|
||||
:ocv:func:`GaussianBlur`,
|
||||
:ocv:func:`medianBlur`
|
||||
|
||||
|
||||
boxFilter
|
||||
---------
|
||||
Blurs an image using the box filter.
|
||||
|
||||
.. ocv:function:: void boxFilter( InputArray src, OutputArray dst, int ddepth, Size ksize, Point anchor=Point(-1,-1), bool normalize=true, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.boxFilter(src, ddepth, ksize[, dst[, anchor[, normalize[, borderType]]]]) -> dst
|
||||
|
||||
:param src: input image.
|
||||
|
||||
:param dst: output image of the same size and type as ``src``.
|
||||
|
||||
:param ddepth: the output image depth (-1 to use ``src.depth()``).
|
||||
|
||||
:param ksize: blurring kernel size.
|
||||
|
||||
:param anchor: anchor point; default value ``Point(-1,-1)`` means that the anchor is at the kernel center.
|
||||
|
||||
:param normalize: flag, specifying whether the kernel is normalized by its area or not.
|
||||
|
||||
:param borderType: border mode used to extrapolate pixels outside of the image.
|
||||
|
||||
The function smoothes an image using the kernel:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{K} = \alpha \begin{bmatrix} 1 & 1 & 1 & \cdots & 1 & 1 \\ 1 & 1 & 1 & \cdots & 1 & 1 \\ \hdotsfor{6} \\ 1 & 1 & 1 & \cdots & 1 & 1 \end{bmatrix}
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
\alpha = \fork{\frac{1}{\texttt{ksize.width*ksize.height}}}{when \texttt{normalize=true}}{1}{otherwise}
|
||||
|
||||
Unnormalized box filter is useful for computing various integral characteristics over each pixel neighborhood, such as covariance matrices of image derivatives (used in dense optical flow algorithms, and so on). If you need to compute pixel sums over variable-size windows, use :ocv:func:`integral` .
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`blur`,
|
||||
:ocv:func:`bilateralFilter`,
|
||||
:ocv:func:`GaussianBlur`,
|
||||
:ocv:func:`medianBlur`,
|
||||
:ocv:func:`integral`
|
||||
|
||||
|
||||
|
||||
buildPyramid
|
||||
------------
|
||||
Constructs the Gaussian pyramid for an image.
|
||||
|
||||
.. ocv:function:: void buildPyramid( InputArray src, OutputArrayOfArrays dst, int maxlevel, int borderType=BORDER_DEFAULT )
|
||||
|
||||
:param src: Source image. Check :ocv:func:`pyrDown` for the list of supported types.
|
||||
|
||||
:param dst: Destination vector of ``maxlevel+1`` images of the same type as ``src`` . ``dst[0]`` will be the same as ``src`` . ``dst[1]`` is the next pyramid layer, a smoothed and down-sized ``src`` , and so on.
|
||||
|
||||
:param maxlevel: 0-based index of the last (the smallest) pyramid layer. It must be non-negative.
|
||||
|
||||
:param borderType: Pixel extrapolation method (BORDER_CONSTANT don't supported). See ``borderInterpolate`` for details.
|
||||
|
||||
The function constructs a vector of images and builds the Gaussian pyramid by recursively applying
|
||||
:ocv:func:`pyrDown` to the previously built pyramid layers, starting from ``dst[0]==src`` .
|
||||
|
||||
|
||||
dilate
|
||||
------
|
||||
Dilates an image by using a specific structuring element.
|
||||
|
||||
.. ocv:function:: void dilate( InputArray src, OutputArray dst, InputArray kernel, Point anchor=Point(-1,-1), int iterations=1, int borderType=BORDER_CONSTANT, const Scalar& borderValue=morphologyDefaultBorderValue() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.dilate(src, kernel[, dst[, anchor[, iterations[, borderType[, borderValue]]]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvDilate( const CvArr* src, CvArr* dst, IplConvKernel* element=NULL, int iterations=1 )
|
||||
|
||||
:param src: input image; the number of channels can be arbitrary, but the depth should be one of ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32F` or ``CV_64F``.
|
||||
|
||||
:param dst: output image of the same size and type as ``src``.
|
||||
|
||||
:param kernel: structuring element used for dilation; if ``elemenat=Mat()`` , a ``3 x 3`` rectangular structuring element is used. Kernel can be created using :ocv:func:`getStructuringElement`
|
||||
|
||||
:param anchor: position of the anchor within the element; default value ``(-1, -1)`` means that the anchor is at the element center.
|
||||
|
||||
:param iterations: number of times dilation is applied.
|
||||
|
||||
:param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
|
||||
|
||||
:param borderValue: border value in case of a constant border
|
||||
|
||||
The function dilates the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the maximum is taken:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \max _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')
|
||||
|
||||
The function supports the in-place mode. Dilation can be applied several ( ``iterations`` ) times. In case of multi-channel images, each channel is processed independently.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`erode`,
|
||||
:ocv:func:`morphologyEx`,
|
||||
:ocv:func:`getStructuringElement`
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the morphological dilate operation can be found at opencv_source_code/samples/cpp/morphology2.cpp
|
||||
|
||||
|
||||
erode
|
||||
-----
|
||||
Erodes an image by using a specific structuring element.
|
||||
|
||||
.. ocv:function:: void erode( InputArray src, OutputArray dst, InputArray kernel, Point anchor=Point(-1,-1), int iterations=1, int borderType=BORDER_CONSTANT, const Scalar& borderValue=morphologyDefaultBorderValue() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.erode(src, kernel[, dst[, anchor[, iterations[, borderType[, borderValue]]]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvErode( const CvArr* src, CvArr* dst, IplConvKernel* element=NULL, int iterations=1)
|
||||
|
||||
:param src: input image; the number of channels can be arbitrary, but the depth should be one of ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32F` or ``CV_64F``.
|
||||
|
||||
:param dst: output image of the same size and type as ``src``.
|
||||
|
||||
:param kernel: structuring element used for erosion; if ``element=Mat()`` , a ``3 x 3`` rectangular structuring element is used. Kernel can be created using :ocv:func:`getStructuringElement`.
|
||||
|
||||
:param anchor: position of the anchor within the element; default value ``(-1, -1)`` means that the anchor is at the element center.
|
||||
|
||||
:param iterations: number of times erosion is applied.
|
||||
|
||||
:param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
|
||||
|
||||
:param borderValue: border value in case of a constant border
|
||||
|
||||
The function erodes the source image using the specified structuring element that determines the shape of a pixel neighborhood over which the minimum is taken:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \min _{(x',y'): \, \texttt{element} (x',y') \ne0 } \texttt{src} (x+x',y+y')
|
||||
|
||||
The function supports the in-place mode. Erosion can be applied several ( ``iterations`` ) times. In case of multi-channel images, each channel is processed independently.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`dilate`,
|
||||
:ocv:func:`morphologyEx`,
|
||||
:ocv:func:`getStructuringElement`
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the morphological erode operation can be found at opencv_source_code/samples/cpp/morphology2.cpp
|
||||
|
||||
filter2D
|
||||
--------
|
||||
Convolves an image with the kernel.
|
||||
|
||||
.. ocv:function:: void filter2D( InputArray src, OutputArray dst, int ddepth, InputArray kernel, Point anchor=Point(-1,-1), double delta=0, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.filter2D(src, ddepth, kernel[, dst[, anchor[, delta[, borderType]]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvFilter2D( const CvArr* src, CvArr* dst, const CvMat* kernel, CvPoint anchor=cvPoint(-1,-1) )
|
||||
|
||||
:param src: input image.
|
||||
|
||||
:param dst: output image of the same size and the same number of channels as ``src``.
|
||||
|
||||
|
||||
:param ddepth: desired depth of the destination image; if it is negative, it will be the same as ``src.depth()``; the following combinations of ``src.depth()`` and ``ddepth`` are supported:
|
||||
* ``src.depth()`` = ``CV_8U``, ``ddepth`` = -1/``CV_16S``/``CV_32F``/``CV_64F``
|
||||
* ``src.depth()`` = ``CV_16U``/``CV_16S``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
|
||||
* ``src.depth()`` = ``CV_32F``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
|
||||
* ``src.depth()`` = ``CV_64F``, ``ddepth`` = -1/``CV_64F``
|
||||
|
||||
when ``ddepth=-1``, the output image will have the same depth as the source.
|
||||
|
||||
:param kernel: convolution kernel (or rather a correlation kernel), a single-channel floating point matrix; if you want to apply different kernels to different channels, split the image into separate color planes using :ocv:func:`split` and process them individually.
|
||||
|
||||
:param anchor: anchor of the kernel that indicates the relative position of a filtered point within the kernel; the anchor should lie within the kernel; default value (-1,-1) means that the anchor is at the kernel center.
|
||||
|
||||
:param delta: optional value added to the filtered pixels before storing them in ``dst``.
|
||||
|
||||
:param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
|
||||
|
||||
The function applies an arbitrary linear filter to an image. In-place operation is supported. When the aperture is partially outside the image, the function interpolates outlier pixel values according to the specified border mode.
|
||||
|
||||
The function does actually compute correlation, not the convolution:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \sum _{ \stackrel{0\leq x' < \texttt{kernel.cols},}{0\leq y' < \texttt{kernel.rows}} } \texttt{kernel} (x',y')* \texttt{src} (x+x'- \texttt{anchor.x} ,y+y'- \texttt{anchor.y} )
|
||||
|
||||
That is, the kernel is not mirrored around the anchor point. If you need a real convolution, flip the kernel using
|
||||
:ocv:func:`flip` and set the new anchor to ``(kernel.cols - anchor.x - 1, kernel.rows - anchor.y - 1)`` .
|
||||
|
||||
The function uses the DFT-based algorithm in case of sufficiently large kernels (~``11 x 11`` or larger) and the direct algorithm for small kernels.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`sepFilter2D`,
|
||||
:ocv:func:`dft`,
|
||||
:ocv:func:`matchTemplate`
|
||||
|
||||
|
||||
|
||||
GaussianBlur
|
||||
------------
|
||||
Blurs an image using a Gaussian filter.
|
||||
|
||||
.. ocv:function:: void GaussianBlur( InputArray src, OutputArray dst, Size ksize, double sigmaX, double sigmaY=0, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.GaussianBlur(src, ksize, sigmaX[, dst[, sigmaY[, borderType]]]) -> dst
|
||||
|
||||
:param src: input image; the image can have any number of channels, which are processed independently, but the depth should be ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32F`` or ``CV_64F``.
|
||||
|
||||
:param dst: output image of the same size and type as ``src``.
|
||||
|
||||
:param ksize: Gaussian kernel size. ``ksize.width`` and ``ksize.height`` can differ but they both must be positive and odd. Or, they can be zero's and then they are computed from ``sigma*`` .
|
||||
|
||||
:param sigmaX: Gaussian kernel standard deviation in X direction.
|
||||
|
||||
:param sigmaY: Gaussian kernel standard deviation in Y direction; if ``sigmaY`` is zero, it is set to be equal to ``sigmaX``, if both sigmas are zeros, they are computed from ``ksize.width`` and ``ksize.height`` , respectively (see :ocv:func:`getGaussianKernel` for details); to fully control the result regardless of possible future modifications of all this semantics, it is recommended to specify all of ``ksize``, ``sigmaX``, and ``sigmaY``.
|
||||
|
||||
:param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
|
||||
|
||||
The function convolves the source image with the specified Gaussian kernel. In-place filtering is supported.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`sepFilter2D`,
|
||||
:ocv:func:`filter2D`,
|
||||
:ocv:func:`blur`,
|
||||
:ocv:func:`boxFilter`,
|
||||
:ocv:func:`bilateralFilter`,
|
||||
:ocv:func:`medianBlur`
|
||||
|
||||
|
||||
getDerivKernels
|
||||
---------------
|
||||
Returns filter coefficients for computing spatial image derivatives.
|
||||
|
||||
.. ocv:function:: void getDerivKernels( OutputArray kx, OutputArray ky, int dx, int dy, int ksize, bool normalize=false, int ktype=CV_32F )
|
||||
|
||||
.. ocv:pyfunction:: cv2.getDerivKernels(dx, dy, ksize[, kx[, ky[, normalize[, ktype]]]]) -> kx, ky
|
||||
|
||||
:param kx: Output matrix of row filter coefficients. It has the type ``ktype`` .
|
||||
|
||||
:param ky: Output matrix of column filter coefficients. It has the type ``ktype`` .
|
||||
|
||||
:param dx: Derivative order in respect of x.
|
||||
|
||||
:param dy: Derivative order in respect of y.
|
||||
|
||||
:param ksize: Aperture size. It can be ``CV_SCHARR`` , 1, 3, 5, or 7.
|
||||
|
||||
:param normalize: Flag indicating whether to normalize (scale down) the filter coefficients or not. Theoretically, the coefficients should have the denominator :math:`=2^{ksize*2-dx-dy-2}` . If you are going to filter floating-point images, you are likely to use the normalized kernels. But if you compute derivatives of an 8-bit image, store the results in a 16-bit image, and wish to preserve all the fractional bits, you may want to set ``normalize=false`` .
|
||||
|
||||
:param ktype: Type of filter coefficients. It can be ``CV_32f`` or ``CV_64F`` .
|
||||
|
||||
The function computes and returns the filter coefficients for spatial image derivatives. When ``ksize=CV_SCHARR`` , the Scharr
|
||||
:math:`3 \times 3` kernels are generated (see
|
||||
:ocv:func:`Scharr` ). Otherwise, Sobel kernels are generated (see
|
||||
:ocv:func:`Sobel` ). The filters are normally passed to
|
||||
:ocv:func:`sepFilter2D` or to
|
||||
|
||||
|
||||
getGaussianKernel
|
||||
-----------------
|
||||
Returns Gaussian filter coefficients.
|
||||
|
||||
.. ocv:function:: Mat getGaussianKernel( int ksize, double sigma, int ktype=CV_64F )
|
||||
|
||||
.. ocv:pyfunction:: cv2.getGaussianKernel(ksize, sigma[, ktype]) -> retval
|
||||
|
||||
:param ksize: Aperture size. It should be odd ( :math:`\texttt{ksize} \mod 2 = 1` ) and positive.
|
||||
|
||||
:param sigma: Gaussian standard deviation. If it is non-positive, it is computed from ``ksize`` as \ ``sigma = 0.3*((ksize-1)*0.5 - 1) + 0.8`` .
|
||||
:param ktype: Type of filter coefficients. It can be ``CV_32F`` or ``CV_64F`` .
|
||||
|
||||
The function computes and returns the
|
||||
:math:`\texttt{ksize} \times 1` matrix of Gaussian filter coefficients:
|
||||
|
||||
.. math::
|
||||
|
||||
G_i= \alpha *e^{-(i-( \texttt{ksize} -1)/2)^2/(2* \texttt{sigma} )^2},
|
||||
|
||||
where
|
||||
:math:`i=0..\texttt{ksize}-1` and
|
||||
:math:`\alpha` is the scale factor chosen so that
|
||||
:math:`\sum_i G_i=1`.
|
||||
|
||||
Two of such generated kernels can be passed to
|
||||
:ocv:func:`sepFilter2D`. Those functions automatically recognize smoothing kernels (a symmetrical kernel with sum of weights equal to 1) and handle them accordingly. You may also use the higher-level
|
||||
:ocv:func:`GaussianBlur`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`sepFilter2D`,
|
||||
:ocv:func:`getDerivKernels`,
|
||||
:ocv:func:`getStructuringElement`,
|
||||
:ocv:func:`GaussianBlur`
|
||||
|
||||
|
||||
|
||||
getGaborKernel
|
||||
-----------------
|
||||
Returns Gabor filter coefficients.
|
||||
|
||||
.. ocv:function:: Mat getGaborKernel( Size ksize, double sigma, double theta, double lambd, double gamma, double psi = CV_PI*0.5, int ktype = CV_64F )
|
||||
|
||||
.. ocv:pyfunction:: cv2.getGaborKernel(ksize, sigma, theta, lambd, gamma[, psi[, ktype]]) -> retval
|
||||
|
||||
:param ksize: Size of the filter returned.
|
||||
|
||||
:param sigma: Standard deviation of the gaussian envelope.
|
||||
|
||||
:param theta: Orientation of the normal to the parallel stripes of a Gabor function.
|
||||
|
||||
:param lambd: Wavelength of the sinusoidal factor.
|
||||
|
||||
:param gamma: Spatial aspect ratio.
|
||||
|
||||
:param psi: Phase offset.
|
||||
|
||||
:param ktype: Type of filter coefficients. It can be ``CV_32F`` or ``CV_64F`` .
|
||||
|
||||
For more details about gabor filter equations and parameters, see: `Gabor Filter <http://en.wikipedia.org/wiki/Gabor_filter>`_.
|
||||
|
||||
|
||||
getStructuringElement
|
||||
---------------------
|
||||
Returns a structuring element of the specified size and shape for morphological operations.
|
||||
|
||||
.. ocv:function:: Mat getStructuringElement(int shape, Size ksize, Point anchor=Point(-1,-1))
|
||||
|
||||
.. ocv:pyfunction:: cv2.getStructuringElement(shape, ksize[, anchor]) -> retval
|
||||
|
||||
.. ocv:cfunction:: IplConvKernel* cvCreateStructuringElementEx( int cols, int rows, int anchor_x, int anchor_y, int shape, int* values=NULL )
|
||||
|
||||
:param shape: Element shape that could be one of the following:
|
||||
|
||||
* **MORPH_RECT** - a rectangular structuring element:
|
||||
|
||||
.. math::
|
||||
|
||||
E_{ij}=1
|
||||
|
||||
* **MORPH_ELLIPSE** - an elliptic structuring element, that is, a filled ellipse inscribed into the rectangle ``Rect(0, 0, esize.width, 0.esize.height)``
|
||||
|
||||
* **MORPH_CROSS** - a cross-shaped structuring element:
|
||||
|
||||
.. math::
|
||||
|
||||
E_{ij} = \fork{1}{if i=\texttt{anchor.y} or j=\texttt{anchor.x}}{0}{otherwise}
|
||||
|
||||
* **CV_SHAPE_CUSTOM** - custom structuring element (OpenCV 1.x API)
|
||||
|
||||
:param ksize: Size of the structuring element.
|
||||
|
||||
:param cols: Width of the structuring element
|
||||
|
||||
:param rows: Height of the structuring element
|
||||
|
||||
:param anchor: Anchor position within the element. The default value :math:`(-1, -1)` means that the anchor is at the center. Note that only the shape of a cross-shaped element depends on the anchor position. In other cases the anchor just regulates how much the result of the morphological operation is shifted.
|
||||
|
||||
:param anchor_x: x-coordinate of the anchor
|
||||
|
||||
:param anchor_y: y-coordinate of the anchor
|
||||
|
||||
:param values: integer array of ``cols``*``rows`` elements that specifies the custom shape of the structuring element, when ``shape=CV_SHAPE_CUSTOM``.
|
||||
|
||||
The function constructs and returns the structuring element that can be further passed to
|
||||
:ocv:func:`erode`,
|
||||
:ocv:func:`dilate` or
|
||||
:ocv:func:`morphologyEx` . But you can also construct an arbitrary binary mask yourself and use it as the structuring element.
|
||||
|
||||
.. note:: When using OpenCV 1.x C API, the created structuring element ``IplConvKernel* element`` must be released in the end using ``cvReleaseStructuringElement(&element)``.
|
||||
|
||||
|
||||
medianBlur
|
||||
----------
|
||||
Blurs an image using the median filter.
|
||||
|
||||
.. ocv:function:: void medianBlur( InputArray src, OutputArray dst, int ksize )
|
||||
|
||||
.. ocv:pyfunction:: cv2.medianBlur(src, ksize[, dst]) -> dst
|
||||
|
||||
:param src: input 1-, 3-, or 4-channel image; when ``ksize`` is 3 or 5, the image depth should be ``CV_8U``, ``CV_16U``, or ``CV_32F``, for larger aperture sizes, it can only be ``CV_8U``.
|
||||
|
||||
:param dst: destination array of the same size and type as ``src``.
|
||||
|
||||
:param ksize: aperture linear size; it must be odd and greater than 1, for example: 3, 5, 7 ...
|
||||
|
||||
The function smoothes an image using the median filter with the
|
||||
:math:`\texttt{ksize} \times \texttt{ksize}` aperture. Each channel of a multi-channel image is processed independently. In-place operation is supported.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`bilateralFilter`,
|
||||
:ocv:func:`blur`,
|
||||
:ocv:func:`boxFilter`,
|
||||
:ocv:func:`GaussianBlur`
|
||||
|
||||
|
||||
|
||||
morphologyEx
|
||||
------------
|
||||
Performs advanced morphological transformations.
|
||||
|
||||
.. ocv:function:: void morphologyEx( InputArray src, OutputArray dst, int op, InputArray kernel, Point anchor=Point(-1,-1), int iterations=1, int borderType=BORDER_CONSTANT, const Scalar& borderValue=morphologyDefaultBorderValue() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.morphologyEx(src, op, kernel[, dst[, anchor[, iterations[, borderType[, borderValue]]]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvMorphologyEx( const CvArr* src, CvArr* dst, CvArr* temp, IplConvKernel* element, int operation, int iterations=1 )
|
||||
|
||||
:param src: Source image. The number of channels can be arbitrary. The depth should be one of ``CV_8U``, ``CV_16U``, ``CV_16S``, ``CV_32F` or ``CV_64F``.
|
||||
|
||||
:param dst: Destination image of the same size and type as ``src`` .
|
||||
|
||||
:param kernel: Structuring element. It can be created using :ocv:func:`getStructuringElement`.
|
||||
|
||||
:param anchor: Anchor position with the kernel. Negative values mean that the anchor is at the kernel center.
|
||||
|
||||
:param op: Type of a morphological operation that can be one of the following:
|
||||
|
||||
* **MORPH_OPEN** - an opening operation
|
||||
|
||||
* **MORPH_CLOSE** - a closing operation
|
||||
|
||||
* **MORPH_GRADIENT** - a morphological gradient
|
||||
|
||||
* **MORPH_TOPHAT** - "top hat"
|
||||
|
||||
* **MORPH_BLACKHAT** - "black hat"
|
||||
|
||||
:param iterations: Number of times erosion and dilation are applied.
|
||||
|
||||
:param borderType: Pixel extrapolation method. See ``borderInterpolate`` for details.
|
||||
|
||||
:param borderValue: Border value in case of a constant border. The default value has a special meaning.
|
||||
|
||||
The function can perform advanced morphological transformations using an erosion and dilation as basic operations.
|
||||
|
||||
Opening operation:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} = \mathrm{open} ( \texttt{src} , \texttt{element} )= \mathrm{dilate} ( \mathrm{erode} ( \texttt{src} , \texttt{element} ))
|
||||
|
||||
Closing operation:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} = \mathrm{close} ( \texttt{src} , \texttt{element} )= \mathrm{erode} ( \mathrm{dilate} ( \texttt{src} , \texttt{element} ))
|
||||
|
||||
Morphological gradient:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} = \mathrm{morph\_grad} ( \texttt{src} , \texttt{element} )= \mathrm{dilate} ( \texttt{src} , \texttt{element} )- \mathrm{erode} ( \texttt{src} , \texttt{element} )
|
||||
|
||||
"Top hat":
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} = \mathrm{tophat} ( \texttt{src} , \texttt{element} )= \texttt{src} - \mathrm{open} ( \texttt{src} , \texttt{element} )
|
||||
|
||||
"Black hat":
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} = \mathrm{blackhat} ( \texttt{src} , \texttt{element} )= \mathrm{close} ( \texttt{src} , \texttt{element} )- \texttt{src}
|
||||
|
||||
Any of the operations can be done in-place. In case of multi-channel images, each channel is processed independently.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`dilate`,
|
||||
:ocv:func:`erode`,
|
||||
:ocv:func:`getStructuringElement`
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the morphologyEx function for the morphological opening and closing operations can be found at opencv_source_code/samples/cpp/morphology2.cpp
|
||||
|
||||
Laplacian
|
||||
---------
|
||||
Calculates the Laplacian of an image.
|
||||
|
||||
.. ocv:function:: void Laplacian( InputArray src, OutputArray dst, int ddepth, int ksize=1, double scale=1, double delta=0, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.Laplacian(src, ddepth[, dst[, ksize[, scale[, delta[, borderType]]]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvLaplace( const CvArr* src, CvArr* dst, int aperture_size=3 )
|
||||
|
||||
:param src: Source image.
|
||||
|
||||
:param dst: Destination image of the same size and the same number of channels as ``src`` .
|
||||
|
||||
:param ddepth: Desired depth of the destination image.
|
||||
|
||||
:param ksize: Aperture size used to compute the second-derivative filters. See :ocv:func:`getDerivKernels` for details. The size must be positive and odd.
|
||||
|
||||
:param scale: Optional scale factor for the computed Laplacian values. By default, no scaling is applied. See :ocv:func:`getDerivKernels` for details.
|
||||
|
||||
:param delta: Optional delta value that is added to the results prior to storing them in ``dst`` .
|
||||
|
||||
:param borderType: Pixel extrapolation method. See ``borderInterpolate`` for details.
|
||||
|
||||
The function calculates the Laplacian of the source image by adding up the second x and y derivatives calculated using the Sobel operator:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} = \Delta \texttt{src} = \frac{\partial^2 \texttt{src}}{\partial x^2} + \frac{\partial^2 \texttt{src}}{\partial y^2}
|
||||
|
||||
This is done when ``ksize > 1`` . When ``ksize == 1`` , the Laplacian is computed by filtering the image with the following
|
||||
:math:`3 \times 3` aperture:
|
||||
|
||||
.. math::
|
||||
|
||||
\vecthreethree {0}{1}{0}{1}{-4}{1}{0}{1}{0}
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`Sobel`,
|
||||
:ocv:func:`Scharr`
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the Laplace transformation for edge detection can be found at opencv_source_code/samples/cpp/laplace.cpp
|
||||
|
||||
pyrDown
|
||||
-------
|
||||
Blurs an image and downsamples it.
|
||||
|
||||
.. ocv:function:: void pyrDown( InputArray src, OutputArray dst, const Size& dstsize=Size(), int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.pyrDown(src[, dst[, dstsize[, borderType]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvPyrDown( const CvArr* src, CvArr* dst, int filter=CV_GAUSSIAN_5x5 )
|
||||
|
||||
:param src: input image.
|
||||
|
||||
:param dst: output image; it has the specified size and the same type as ``src``.
|
||||
|
||||
:param dstsize: size of the output image.
|
||||
|
||||
:param borderType: Pixel extrapolation method (BORDER_CONSTANT don't supported). See ``borderInterpolate`` for details.
|
||||
|
||||
By default, size of the output image is computed as ``Size((src.cols+1)/2, (src.rows+1)/2)``, but in any case, the following conditions should be satisfied:
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{array}{l}
|
||||
| \texttt{dstsize.width} *2-src.cols| \leq 2 \\ | \texttt{dstsize.height} *2-src.rows| \leq 2 \end{array}
|
||||
|
||||
The function performs the downsampling step of the Gaussian pyramid construction. First, it convolves the source image with the kernel:
|
||||
|
||||
.. math::
|
||||
|
||||
\frac{1}{256} \begin{bmatrix} 1 & 4 & 6 & 4 & 1 \\ 4 & 16 & 24 & 16 & 4 \\ 6 & 24 & 36 & 24 & 6 \\ 4 & 16 & 24 & 16 & 4 \\ 1 & 4 & 6 & 4 & 1 \end{bmatrix}
|
||||
|
||||
Then, it downsamples the image by rejecting even rows and columns.
|
||||
|
||||
pyrUp
|
||||
-----
|
||||
Upsamples an image and then blurs it.
|
||||
|
||||
.. ocv:function:: void pyrUp( InputArray src, OutputArray dst, const Size& dstsize=Size(), int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.pyrUp(src[, dst[, dstsize[, borderType]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: cvPyrUp( const CvArr* src, CvArr* dst, int filter=CV_GAUSSIAN_5x5 )
|
||||
|
||||
:param src: input image.
|
||||
|
||||
:param dst: output image. It has the specified size and the same type as ``src`` .
|
||||
|
||||
:param dstsize: size of the output image.
|
||||
|
||||
:param borderType: Pixel extrapolation method (only BORDER_DEFAULT supported). See ``borderInterpolate`` for details.
|
||||
|
||||
By default, size of the output image is computed as ``Size(src.cols*2, (src.rows*2)``, but in any case, the following conditions should be satisfied:
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{array}{l}
|
||||
| \texttt{dstsize.width} -src.cols*2| \leq ( \texttt{dstsize.width} \mod 2) \\ | \texttt{dstsize.height} -src.rows*2| \leq ( \texttt{dstsize.height} \mod 2) \end{array}
|
||||
|
||||
The function performs the upsampling step of the Gaussian pyramid construction, though it can actually be used to construct the Laplacian pyramid. First, it upsamples the source image by injecting even zero rows and columns and then convolves the result with the same kernel as in
|
||||
:ocv:func:`pyrDown` multiplied by 4.
|
||||
|
||||
.. note::
|
||||
|
||||
* (Python) An example of Laplacian Pyramid construction and merging can be found at opencv_source_code/samples/python2/lappyr.py
|
||||
|
||||
|
||||
pyrMeanShiftFiltering
|
||||
---------------------
|
||||
Performs initial step of meanshift segmentation of an image.
|
||||
|
||||
.. ocv:function:: void pyrMeanShiftFiltering( InputArray src, OutputArray dst, double sp, double sr, int maxLevel=1, TermCriteria termcrit=TermCriteria(TermCriteria::MAX_ITER+TermCriteria::EPS,5,1) )
|
||||
|
||||
.. ocv:pyfunction:: cv2.pyrMeanShiftFiltering(src, sp, sr[, dst[, maxLevel[, termcrit]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvPyrMeanShiftFiltering( const CvArr* src, CvArr* dst, double sp, double sr, int max_level=1, CvTermCriteria termcrit= cvTermCriteria(CV_TERMCRIT_ITER+CV_TERMCRIT_EPS,5,1))
|
||||
|
||||
:param src: The source 8-bit, 3-channel image.
|
||||
|
||||
:param dst: The destination image of the same format and the same size as the source.
|
||||
|
||||
:param sp: The spatial window radius.
|
||||
|
||||
:param sr: The color window radius.
|
||||
|
||||
:param maxLevel: Maximum level of the pyramid for the segmentation.
|
||||
|
||||
:param termcrit: Termination criteria: when to stop meanshift iterations.
|
||||
|
||||
|
||||
The function implements the filtering stage of meanshift segmentation, that is, the output of the function is the filtered "posterized" image with color gradients and fine-grain texture flattened. At every pixel
|
||||
``(X,Y)`` of the input image (or down-sized input image, see below) the function executes meanshift
|
||||
iterations, that is, the pixel ``(X,Y)`` neighborhood in the joint space-color hyperspace is considered:
|
||||
|
||||
.. math::
|
||||
|
||||
(x,y): X- \texttt{sp} \le x \le X+ \texttt{sp} , Y- \texttt{sp} \le y \le Y+ \texttt{sp} , ||(R,G,B)-(r,g,b)|| \le \texttt{sr}
|
||||
|
||||
|
||||
where ``(R,G,B)`` and ``(r,g,b)`` are the vectors of color components at ``(X,Y)`` and ``(x,y)``, respectively (though, the algorithm does not depend on the color space used, so any 3-component color space can be used instead). Over the neighborhood the average spatial value ``(X',Y')`` and average color vector ``(R',G',B')`` are found and they act as the neighborhood center on the next iteration:
|
||||
|
||||
.. math::
|
||||
|
||||
(X,Y)~(X',Y'), (R,G,B)~(R',G',B').
|
||||
|
||||
After the iterations over, the color components of the initial pixel (that is, the pixel from where the iterations started) are set to the final value (average color at the last iteration):
|
||||
|
||||
.. math::
|
||||
|
||||
I(X,Y) <- (R*,G*,B*)
|
||||
|
||||
When ``maxLevel > 0``, the gaussian pyramid of ``maxLevel+1`` levels is built, and the above procedure is run on the smallest layer first. After that, the results are propagated to the larger layer and the iterations are run again only on those pixels where the layer colors differ by more than ``sr`` from the lower-resolution layer of the pyramid. That makes boundaries of color regions sharper. Note that the results will be actually different from the ones obtained by running the meanshift procedure on the whole original image (i.e. when ``maxLevel==0``).
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using mean-shift image segmentation can be found at opencv_source_code/samples/cpp/meanshift_segmentation.cpp
|
||||
|
||||
sepFilter2D
|
||||
-----------
|
||||
Applies a separable linear filter to an image.
|
||||
|
||||
.. ocv:function:: void sepFilter2D( InputArray src, OutputArray dst, int ddepth, InputArray kernelX, InputArray kernelY, Point anchor=Point(-1,-1), double delta=0, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.sepFilter2D(src, ddepth, kernelX, kernelY[, dst[, anchor[, delta[, borderType]]]]) -> dst
|
||||
|
||||
:param src: Source image.
|
||||
|
||||
:param dst: Destination image of the same size and the same number of channels as ``src`` .
|
||||
|
||||
:param ddepth: Destination image depth. The following combination of ``src.depth()`` and ``ddepth`` are supported:
|
||||
* ``src.depth()`` = ``CV_8U``, ``ddepth`` = -1/``CV_16S``/``CV_32F``/``CV_64F``
|
||||
* ``src.depth()`` = ``CV_16U``/``CV_16S``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
|
||||
* ``src.depth()`` = ``CV_32F``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
|
||||
* ``src.depth()`` = ``CV_64F``, ``ddepth`` = -1/``CV_64F``
|
||||
|
||||
when ``ddepth=-1``, the destination image will have the same depth as the source.
|
||||
|
||||
:param kernelX: Coefficients for filtering each row.
|
||||
|
||||
:param kernelY: Coefficients for filtering each column.
|
||||
|
||||
:param anchor: Anchor position within the kernel. The default value :math:`(-1,-1)` means that the anchor is at the kernel center.
|
||||
|
||||
:param delta: Value added to the filtered results before storing them.
|
||||
|
||||
:param borderType: Pixel extrapolation method. See ``borderInterpolate`` for details.
|
||||
|
||||
The function applies a separable linear filter to the image. That is, first, every row of ``src`` is filtered with the 1D kernel ``kernelX`` . Then, every column of the result is filtered with the 1D kernel ``kernelY`` . The final result shifted by ``delta`` is stored in ``dst`` .
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`filter2D`,
|
||||
:ocv:func:`Sobel`,
|
||||
:ocv:func:`GaussianBlur`,
|
||||
:ocv:func:`boxFilter`,
|
||||
:ocv:func:`blur`
|
||||
|
||||
|
||||
Smooth
|
||||
------
|
||||
Smooths the image in one of several ways.
|
||||
|
||||
.. ocv:cfunction:: void cvSmooth( const CvArr* src, CvArr* dst, int smoothtype=CV_GAUSSIAN, int size1=3, int size2=0, double sigma1=0, double sigma2=0 )
|
||||
|
||||
:param src: The source image
|
||||
|
||||
:param dst: The destination image
|
||||
|
||||
:param smoothtype: Type of the smoothing:
|
||||
|
||||
* **CV_BLUR_NO_SCALE** linear convolution with :math:`\texttt{size1}\times\texttt{size2}` box kernel (all 1's). If you want to smooth different pixels with different-size box kernels, you can use the integral image that is computed using :ocv:func:`integral`
|
||||
|
||||
|
||||
* **CV_BLUR** linear convolution with :math:`\texttt{size1}\times\texttt{size2}` box kernel (all 1's) with subsequent scaling by :math:`1/(\texttt{size1}\cdot\texttt{size2})`
|
||||
|
||||
|
||||
* **CV_GAUSSIAN** linear convolution with a :math:`\texttt{size1}\times\texttt{size2}` Gaussian kernel
|
||||
|
||||
|
||||
* **CV_MEDIAN** median filter with a :math:`\texttt{size1}\times\texttt{size1}` square aperture
|
||||
|
||||
|
||||
* **CV_BILATERAL** bilateral filter with a :math:`\texttt{size1}\times\texttt{size1}` square aperture, color sigma= ``sigma1`` and spatial sigma= ``sigma2`` . If ``size1=0`` , the aperture square side is set to ``cvRound(sigma2*1.5)*2+1`` . Information about bilateral filtering can be found at http://www.dai.ed.ac.uk/CVonline/LOCAL\_COPIES/MANDUCHI1/Bilateral\_Filtering.html
|
||||
|
||||
|
||||
:param size1: The first parameter of the smoothing operation, the aperture width. Must be a positive odd number (1, 3, 5, ...)
|
||||
|
||||
:param size2: The second parameter of the smoothing operation, the aperture height. Ignored by ``CV_MEDIAN`` and ``CV_BILATERAL`` methods. In the case of simple scaled/non-scaled and Gaussian blur if ``size2`` is zero, it is set to ``size1`` . Otherwise it must be a positive odd number.
|
||||
|
||||
:param sigma1: In the case of a Gaussian parameter this parameter may specify Gaussian :math:`\sigma` (standard deviation). If it is zero, it is calculated from the kernel size:
|
||||
|
||||
.. math::
|
||||
|
||||
\sigma = 0.3 (n/2 - 1) + 0.8 \quad \text{where} \quad n= \begin{array}{l l} \mbox{\texttt{size1} for horizontal kernel} \\ \mbox{\texttt{size2} for vertical kernel} \end{array}
|
||||
|
||||
Using standard sigma for small kernels ( :math:`3\times 3` to :math:`7\times 7` ) gives better speed. If ``sigma1`` is not zero, while ``size1`` and ``size2`` are zeros, the kernel size is calculated from the sigma (to provide accurate enough operation).
|
||||
|
||||
The function smooths an image using one of several methods. Every of the methods has some features and restrictions listed below:
|
||||
|
||||
* Blur with no scaling works with single-channel images only and supports accumulation of 8-bit to 16-bit format (similar to :ocv:func:`Sobel` and :ocv:func:`Laplacian`) and 32-bit floating point to 32-bit floating-point format.
|
||||
|
||||
* Simple blur and Gaussian blur support 1- or 3-channel, 8-bit and 32-bit floating point images. These two methods can process images in-place.
|
||||
|
||||
* Median and bilateral filters work with 1- or 3-channel 8-bit images and can not process images in-place.
|
||||
|
||||
.. note:: The function is now obsolete. Use :ocv:func:`GaussianBlur`, :ocv:func:`blur`, :ocv:func:`medianBlur` or :ocv:func:`bilateralFilter`.
|
||||
|
||||
|
||||
Sobel
|
||||
-----
|
||||
Calculates the first, second, third, or mixed image derivatives using an extended Sobel operator.
|
||||
|
||||
.. ocv:function:: void Sobel( InputArray src, OutputArray dst, int ddepth, int dx, int dy, int ksize=3, double scale=1, double delta=0, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.Sobel(src, ddepth, dx, dy[, dst[, ksize[, scale[, delta[, borderType]]]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvSobel( const CvArr* src, CvArr* dst, int xorder, int yorder, int aperture_size=3 )
|
||||
|
||||
:param src: input image.
|
||||
|
||||
:param dst: output image of the same size and the same number of channels as ``src`` .
|
||||
|
||||
:param ddepth: output image depth; the following combinations of ``src.depth()`` and ``ddepth`` are supported:
|
||||
* ``src.depth()`` = ``CV_8U``, ``ddepth`` = -1/``CV_16S``/``CV_32F``/``CV_64F``
|
||||
* ``src.depth()`` = ``CV_16U``/``CV_16S``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
|
||||
* ``src.depth()`` = ``CV_32F``, ``ddepth`` = -1/``CV_32F``/``CV_64F``
|
||||
* ``src.depth()`` = ``CV_64F``, ``ddepth`` = -1/``CV_64F``
|
||||
|
||||
when ``ddepth=-1``, the destination image will have the same depth as the source; in the case of 8-bit input images it will result in truncated derivatives.
|
||||
|
||||
:param xorder: order of the derivative x.
|
||||
|
||||
:param yorder: order of the derivative y.
|
||||
|
||||
:param ksize: size of the extended Sobel kernel; it must be 1, 3, 5, or 7.
|
||||
|
||||
:param scale: optional scale factor for the computed derivative values; by default, no scaling is applied (see :ocv:func:`getDerivKernels` for details).
|
||||
|
||||
:param delta: optional delta value that is added to the results prior to storing them in ``dst``.
|
||||
|
||||
:param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
|
||||
|
||||
In all cases except one, the
|
||||
:math:`\texttt{ksize} \times
|
||||
\texttt{ksize}` separable kernel is used to calculate the
|
||||
derivative. When
|
||||
:math:`\texttt{ksize = 1}` , the
|
||||
:math:`3 \times 1` or
|
||||
:math:`1 \times 3` kernel is used (that is, no Gaussian smoothing is done). ``ksize = 1`` can only be used for the first or the second x- or y- derivatives.
|
||||
|
||||
There is also the special value ``ksize = CV_SCHARR`` (-1) that corresponds to the
|
||||
:math:`3\times3` Scharr
|
||||
filter that may give more accurate results than the
|
||||
:math:`3\times3` Sobel. The Scharr aperture is
|
||||
|
||||
.. math::
|
||||
|
||||
\vecthreethree{-3}{0}{3}{-10}{0}{10}{-3}{0}{3}
|
||||
|
||||
for the x-derivative, or transposed for the y-derivative.
|
||||
|
||||
The function calculates an image derivative by convolving the image with the appropriate kernel:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} = \frac{\partial^{xorder+yorder} \texttt{src}}{\partial x^{xorder} \partial y^{yorder}}
|
||||
|
||||
The Sobel operators combine Gaussian smoothing and differentiation,
|
||||
so the result is more or less resistant to the noise. Most often,
|
||||
the function is called with ( ``xorder`` = 1, ``yorder`` = 0, ``ksize`` = 3) or ( ``xorder`` = 0, ``yorder`` = 1, ``ksize`` = 3) to calculate the first x- or y- image
|
||||
derivative. The first case corresponds to a kernel of:
|
||||
|
||||
.. math::
|
||||
|
||||
\vecthreethree{-1}{0}{1}{-2}{0}{2}{-1}{0}{1}
|
||||
|
||||
The second case corresponds to a kernel of:
|
||||
|
||||
.. math::
|
||||
|
||||
\vecthreethree{-1}{-2}{-1}{0}{0}{0}{1}{2}{1}
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`Scharr`,
|
||||
:ocv:func:`Laplacian`,
|
||||
:ocv:func:`sepFilter2D`,
|
||||
:ocv:func:`filter2D`,
|
||||
:ocv:func:`GaussianBlur`,
|
||||
:ocv:func:`cartToPolar`
|
||||
|
||||
|
||||
|
||||
Scharr
|
||||
------
|
||||
Calculates the first x- or y- image derivative using Scharr operator.
|
||||
|
||||
.. ocv:function:: void Scharr( InputArray src, OutputArray dst, int ddepth, int dx, int dy, double scale=1, double delta=0, int borderType=BORDER_DEFAULT )
|
||||
|
||||
.. ocv:pyfunction:: cv2.Scharr(src, ddepth, dx, dy[, dst[, scale[, delta[, borderType]]]]) -> dst
|
||||
|
||||
:param src: input image.
|
||||
|
||||
:param dst: output image of the same size and the same number of channels as ``src``.
|
||||
|
||||
:param ddepth: output image depth (see :ocv:func:`Sobel` for the list of supported combination of ``src.depth()`` and ``ddepth``).
|
||||
|
||||
:param dx: order of the derivative x.
|
||||
|
||||
:param dy: order of the derivative y.
|
||||
|
||||
:param scale: optional scale factor for the computed derivative values; by default, no scaling is applied (see :ocv:func:`getDerivKernels` for details).
|
||||
|
||||
:param delta: optional delta value that is added to the results prior to storing them in ``dst``.
|
||||
|
||||
:param borderType: pixel extrapolation method (see ``borderInterpolate`` for details).
|
||||
|
||||
The function computes the first x- or y- spatial image derivative using the Scharr operator. The call
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{Scharr(src, dst, ddepth, dx, dy, scale, delta, borderType)}
|
||||
|
||||
is equivalent to
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{Sobel(src, dst, ddepth, dx, dy, CV\_SCHARR, scale, delta, borderType)} .
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`cartToPolar`
|
||||
@@ -1,735 +0,0 @@
|
||||
Geometric Image Transformations
|
||||
===============================
|
||||
.. highlight:: cpp
|
||||
|
||||
The functions in this section perform various geometrical transformations of 2D images. They do not change the image content but deform the pixel grid and map this deformed grid to the destination image. In fact, to avoid sampling artifacts, the mapping is done in the reverse order, from destination to the source. That is, for each pixel :math:`(x, y)` of the destination image, the functions compute coordinates of the corresponding "donor" pixel in the source image and copy the pixel value:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y)= \texttt{src} (f_x(x,y), f_y(x,y))
|
||||
|
||||
In case when you specify the forward mapping
|
||||
:math:`\left<g_x, g_y\right>: \texttt{src} \rightarrow \texttt{dst}` , the OpenCV functions first compute the corresponding inverse mapping
|
||||
:math:`\left<f_x, f_y\right>: \texttt{dst} \rightarrow \texttt{src}` and then use the above formula.
|
||||
|
||||
The actual implementations of the geometrical transformations, from the most generic
|
||||
:ocv:func:`remap` and to the simplest and the fastest
|
||||
:ocv:func:`resize` , need to solve two main problems with the above formula:
|
||||
|
||||
*
|
||||
Extrapolation of non-existing pixels. Similarly to the filtering functions described in the previous section, for some
|
||||
:math:`(x,y)` , either one of
|
||||
:math:`f_x(x,y)` , or
|
||||
:math:`f_y(x,y)` , or both of them may fall outside of the image. In this case, an extrapolation method needs to be used. OpenCV provides the same selection of extrapolation methods as in the filtering functions. In addition, it provides the method ``BORDER_TRANSPARENT`` . This means that the corresponding pixels in the destination image will not be modified at all.
|
||||
|
||||
*
|
||||
Interpolation of pixel values. Usually
|
||||
:math:`f_x(x,y)` and
|
||||
:math:`f_y(x,y)` are floating-point numbers. This means that
|
||||
:math:`\left<f_x, f_y\right>` can be either an affine or perspective transformation, or radial lens distortion correction, and so on. So, a pixel value at fractional coordinates needs to be retrieved. In the simplest case, the coordinates can be just rounded to the nearest integer coordinates and the corresponding pixel can be used. This is called a nearest-neighbor interpolation. However, a better result can be achieved by using more sophisticated `interpolation methods <http://en.wikipedia.org/wiki/Multivariate_interpolation>`_
|
||||
, where a polynomial function is fit into some neighborhood of the computed pixel
|
||||
:math:`(f_x(x,y), f_y(x,y))` , and then the value of the polynomial at
|
||||
:math:`(f_x(x,y), f_y(x,y))` is taken as the interpolated pixel value. In OpenCV, you can choose between several interpolation methods. See
|
||||
:ocv:func:`resize` for details.
|
||||
|
||||
convertMaps
|
||||
-----------
|
||||
Converts image transformation maps from one representation to another.
|
||||
|
||||
.. ocv:function:: void convertMaps( InputArray map1, InputArray map2, OutputArray dstmap1, OutputArray dstmap2, int dstmap1type, bool nninterpolation=false )
|
||||
|
||||
.. ocv:pyfunction:: cv2.convertMaps(map1, map2, dstmap1type[, dstmap1[, dstmap2[, nninterpolation]]]) -> dstmap1, dstmap2
|
||||
|
||||
:param map1: The first input map of type ``CV_16SC2`` , ``CV_32FC1`` , or ``CV_32FC2`` .
|
||||
|
||||
:param map2: The second input map of type ``CV_16UC1`` , ``CV_32FC1`` , or none (empty matrix), respectively.
|
||||
|
||||
:param dstmap1: The first output map that has the type ``dstmap1type`` and the same size as ``src`` .
|
||||
|
||||
:param dstmap2: The second output map.
|
||||
|
||||
:param dstmap1type: Type of the first output map that should be ``CV_16SC2`` , ``CV_32FC1`` , or ``CV_32FC2`` .
|
||||
|
||||
:param nninterpolation: Flag indicating whether the fixed-point maps are used for the nearest-neighbor or for a more complex interpolation.
|
||||
|
||||
The function converts a pair of maps for
|
||||
:ocv:func:`remap` from one representation to another. The following options ( ``(map1.type(), map2.type())`` :math:`\rightarrow` ``(dstmap1.type(), dstmap2.type())`` ) are supported:
|
||||
|
||||
*
|
||||
:math:`\texttt{(CV\_32FC1, CV\_32FC1)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` . This is the most frequently used conversion operation, in which the original floating-point maps (see
|
||||
:ocv:func:`remap` ) are converted to a more compact and much faster fixed-point representation. The first output array contains the rounded coordinates and the second array (created only when ``nninterpolation=false`` ) contains indices in the interpolation tables.
|
||||
|
||||
*
|
||||
:math:`\texttt{(CV\_32FC2)} \rightarrow \texttt{(CV\_16SC2, CV\_16UC1)}` . The same as above but the original maps are stored in one 2-channel matrix.
|
||||
|
||||
*
|
||||
Reverse conversion. Obviously, the reconstructed floating-point maps will not be exactly the same as the originals.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`remap`,
|
||||
:ocv:func:`undistort`,
|
||||
:ocv:func:`initUndistortRectifyMap`
|
||||
|
||||
|
||||
|
||||
getAffineTransform
|
||||
----------------------
|
||||
Calculates an affine transform from three pairs of the corresponding points.
|
||||
|
||||
.. ocv:function:: Mat getAffineTransform( InputArray src, InputArray dst )
|
||||
|
||||
.. ocv:function:: Mat getAffineTransform( const Point2f src[], const Point2f dst[] )
|
||||
|
||||
.. ocv:pyfunction:: cv2.getAffineTransform(src, dst) -> retval
|
||||
|
||||
.. ocv:cfunction:: CvMat* cvGetAffineTransform( const CvPoint2D32f * src, const CvPoint2D32f * dst, CvMat * map_matrix )
|
||||
|
||||
:param src: Coordinates of triangle vertices in the source image.
|
||||
|
||||
:param dst: Coordinates of the corresponding triangle vertices in the destination image.
|
||||
|
||||
The function calculates the :math:`2 \times 3` matrix of an affine transform so that:
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{bmatrix} x'_i \\ y'_i \end{bmatrix} = \texttt{map\_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
dst(i)=(x'_i,y'_i),
|
||||
src(i)=(x_i, y_i),
|
||||
i=0,1,2
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`warpAffine`,
|
||||
:ocv:func:`transform`
|
||||
|
||||
|
||||
|
||||
getPerspectiveTransform
|
||||
---------------------------
|
||||
Calculates a perspective transform from four pairs of the corresponding points.
|
||||
|
||||
.. ocv:function:: Mat getPerspectiveTransform( InputArray src, InputArray dst )
|
||||
|
||||
.. ocv:function:: Mat getPerspectiveTransform( const Point2f src[], const Point2f dst[] )
|
||||
|
||||
.. ocv:pyfunction:: cv2.getPerspectiveTransform(src, dst) -> retval
|
||||
|
||||
.. ocv:cfunction:: CvMat* cvGetPerspectiveTransform( const CvPoint2D32f* src, const CvPoint2D32f* dst, CvMat* map_matrix )
|
||||
|
||||
:param src: Coordinates of quadrangle vertices in the source image.
|
||||
|
||||
:param dst: Coordinates of the corresponding quadrangle vertices in the destination image.
|
||||
|
||||
The function calculates the :math:`3 \times 3` matrix of a perspective transform so that:
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{bmatrix} t_i x'_i \\ t_i y'_i \\ t_i \end{bmatrix} = \texttt{map\_matrix} \cdot \begin{bmatrix} x_i \\ y_i \\ 1 \end{bmatrix}
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
dst(i)=(x'_i,y'_i),
|
||||
src(i)=(x_i, y_i),
|
||||
i=0,1,2,3
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`findHomography`,
|
||||
:ocv:func:`warpPerspective`,
|
||||
:ocv:func:`perspectiveTransform`
|
||||
|
||||
|
||||
getRectSubPix
|
||||
-----------------
|
||||
Retrieves a pixel rectangle from an image with sub-pixel accuracy.
|
||||
|
||||
.. ocv:function:: void getRectSubPix( InputArray image, Size patchSize, Point2f center, OutputArray patch, int patchType=-1 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.getRectSubPix(image, patchSize, center[, patch[, patchType]]) -> patch
|
||||
|
||||
.. ocv:cfunction:: void cvGetRectSubPix( const CvArr* src, CvArr* dst, CvPoint2D32f center )
|
||||
|
||||
:param src: Source image.
|
||||
|
||||
:param patchSize: Size of the extracted patch.
|
||||
|
||||
:param center: Floating point coordinates of the center of the extracted rectangle within the source image. The center must be inside the image.
|
||||
|
||||
:param dst: Extracted patch that has the size ``patchSize`` and the same number of channels as ``src`` .
|
||||
|
||||
:param patchType: Depth of the extracted pixels. By default, they have the same depth as ``src`` .
|
||||
|
||||
The function ``getRectSubPix`` extracts pixels from ``src`` :
|
||||
|
||||
.. math::
|
||||
|
||||
dst(x, y) = src(x + \texttt{center.x} - ( \texttt{dst.cols} -1)*0.5, y + \texttt{center.y} - ( \texttt{dst.rows} -1)*0.5)
|
||||
|
||||
where the values of the pixels at non-integer coordinates are retrieved
|
||||
using bilinear interpolation. Every channel of multi-channel
|
||||
images is processed independently. While the center of the rectangle
|
||||
must be inside the image, parts of the rectangle may be
|
||||
outside. In this case, the replication border mode (see
|
||||
:ocv:func:`borderInterpolate` ) is used to extrapolate
|
||||
the pixel values outside of the image.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`warpAffine`,
|
||||
:ocv:func:`warpPerspective`
|
||||
|
||||
|
||||
getRotationMatrix2D
|
||||
-----------------------
|
||||
Calculates an affine matrix of 2D rotation.
|
||||
|
||||
.. ocv:function:: Mat getRotationMatrix2D( Point2f center, double angle, double scale )
|
||||
|
||||
.. ocv:pyfunction:: cv2.getRotationMatrix2D(center, angle, scale) -> retval
|
||||
|
||||
.. ocv:cfunction:: CvMat* cv2DRotationMatrix( CvPoint2D32f center, double angle, double scale, CvMat* map_matrix )
|
||||
|
||||
:param center: Center of the rotation in the source image.
|
||||
|
||||
:param angle: Rotation angle in degrees. Positive values mean counter-clockwise rotation (the coordinate origin is assumed to be the top-left corner).
|
||||
|
||||
:param scale: Isotropic scale factor.
|
||||
|
||||
:param map_matrix: The output affine transformation, 2x3 floating-point matrix.
|
||||
|
||||
The function calculates the following matrix:
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{bmatrix} \alpha & \beta & (1- \alpha ) \cdot \texttt{center.x} - \beta \cdot \texttt{center.y} \\ - \beta & \alpha & \beta \cdot \texttt{center.x} + (1- \alpha ) \cdot \texttt{center.y} \end{bmatrix}
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{array}{l} \alpha = \texttt{scale} \cdot \cos \texttt{angle} , \\ \beta = \texttt{scale} \cdot \sin \texttt{angle} \end{array}
|
||||
|
||||
The transformation maps the rotation center to itself. If this is not the target, adjust the shift.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`getAffineTransform`,
|
||||
:ocv:func:`warpAffine`,
|
||||
:ocv:func:`transform`
|
||||
|
||||
|
||||
|
||||
invertAffineTransform
|
||||
-------------------------
|
||||
Inverts an affine transformation.
|
||||
|
||||
.. ocv:function:: void invertAffineTransform(InputArray M, OutputArray iM)
|
||||
|
||||
.. ocv:pyfunction:: cv2.invertAffineTransform(M[, iM]) -> iM
|
||||
|
||||
:param M: Original affine transformation.
|
||||
|
||||
:param iM: Output reverse affine transformation.
|
||||
|
||||
The function computes an inverse affine transformation represented by
|
||||
:math:`2 \times 3` matrix ``M`` :
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{bmatrix} a_{11} & a_{12} & b_1 \\ a_{21} & a_{22} & b_2 \end{bmatrix}
|
||||
|
||||
The result is also a
|
||||
:math:`2 \times 3` matrix of the same type as ``M`` .
|
||||
|
||||
LinearPolar
|
||||
-----------
|
||||
Remaps an image to polar space.
|
||||
|
||||
.. ocv:cfunction:: void cvLinearPolar( const CvArr* src, CvArr* dst, CvPoint2D32f center, double maxRadius, int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS )
|
||||
|
||||
:param src: Source image
|
||||
|
||||
:param dst: Destination image
|
||||
|
||||
:param center: The transformation center;
|
||||
|
||||
:param maxRadius: Inverse magnitude scale parameter. See below
|
||||
|
||||
:param flags: A combination of interpolation methods and the following optional flags:
|
||||
|
||||
* **CV_WARP_FILL_OUTLIERS** fills all of the destination image pixels. If some of them correspond to outliers in the source image, they are set to zero
|
||||
|
||||
* **CV_WARP_INVERSE_MAP** See below
|
||||
|
||||
The function ``cvLinearPolar`` transforms the source image using the following transformation:
|
||||
|
||||
*
|
||||
Forward transformation (``CV_WARP_INVERSE_MAP`` is not set):
|
||||
|
||||
.. math::
|
||||
|
||||
dst( \phi , \rho ) = src(x,y)
|
||||
|
||||
|
||||
*
|
||||
Inverse transformation (``CV_WARP_INVERSE_MAP`` is set):
|
||||
|
||||
.. math::
|
||||
|
||||
dst(x,y) = src( \phi , \rho )
|
||||
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
\rho = (src.width/maxRadius) \cdot \sqrt{x^2 + y^2} , \phi =atan(y/x)
|
||||
|
||||
|
||||
The function can not operate in-place.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the LinearPolar operation can be found at opencv_source_code/samples/c/polar_transforms.c
|
||||
|
||||
|
||||
|
||||
LogPolar
|
||||
--------
|
||||
Remaps an image to log-polar space.
|
||||
|
||||
.. ocv:cfunction:: void cvLogPolar( const CvArr* src, CvArr* dst, CvPoint2D32f center, double M, int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS )
|
||||
|
||||
:param src: Source image
|
||||
|
||||
:param dst: Destination image
|
||||
|
||||
:param center: The transformation center; where the output precision is maximal
|
||||
|
||||
:param M: Magnitude scale parameter. See below
|
||||
|
||||
:param flags: A combination of interpolation methods and the following optional flags:
|
||||
|
||||
* **CV_WARP_FILL_OUTLIERS** fills all of the destination image pixels. If some of them correspond to outliers in the source image, they are set to zero
|
||||
|
||||
* **CV_WARP_INVERSE_MAP** See below
|
||||
|
||||
The function ``cvLogPolar`` transforms the source image using the following transformation:
|
||||
|
||||
*
|
||||
Forward transformation (``CV_WARP_INVERSE_MAP`` is not set):
|
||||
|
||||
.. math::
|
||||
|
||||
dst( \phi , \rho ) = src(x,y)
|
||||
|
||||
|
||||
*
|
||||
Inverse transformation (``CV_WARP_INVERSE_MAP`` is set):
|
||||
|
||||
.. math::
|
||||
|
||||
dst(x,y) = src( \phi , \rho )
|
||||
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
\rho = M \cdot \log{\sqrt{x^2 + y^2}} , \phi =atan(y/x)
|
||||
|
||||
|
||||
The function emulates the human "foveal" vision and can be used for fast scale and rotation-invariant template matching, for object tracking and so forth. The function can not operate in-place.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the geometric logpolar operation in 4 applications can be found at opencv_source_code/samples/cpp/logpolar_bsm.cpp
|
||||
|
||||
remap
|
||||
-----
|
||||
Applies a generic geometrical transformation to an image.
|
||||
|
||||
.. ocv:function:: void remap( InputArray src, OutputArray dst, InputArray map1, InputArray map2, int interpolation, int borderMode=BORDER_CONSTANT, const Scalar& borderValue=Scalar())
|
||||
|
||||
.. ocv:pyfunction:: cv2.remap(src, map1, map2, interpolation[, dst[, borderMode[, borderValue]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvRemap( const CvArr* src, CvArr* dst, const CvArr* mapx, const CvArr* mapy, int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS, CvScalar fillval=cvScalarAll(0) )
|
||||
|
||||
:param src: Source image.
|
||||
|
||||
:param dst: Destination image. It has the same size as ``map1`` and the same type as ``src`` .
|
||||
:param map1: The first map of either ``(x,y)`` points or just ``x`` values having the type ``CV_16SC2`` , ``CV_32FC1`` , or ``CV_32FC2`` . See :ocv:func:`convertMaps` for details on converting a floating point representation to fixed-point for speed.
|
||||
|
||||
:param map2: The second map of ``y`` values having the type ``CV_16UC1`` , ``CV_32FC1`` , or none (empty map if ``map1`` is ``(x,y)`` points), respectively.
|
||||
|
||||
:param interpolation: Interpolation method (see :ocv:func:`resize` ). The method ``INTER_AREA`` is not supported by this function.
|
||||
|
||||
:param borderMode: Pixel extrapolation method (see :ocv:func:`borderInterpolate` ). When \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image that corresponds to the "outliers" in the source image are not modified by the function.
|
||||
|
||||
:param borderValue: Value used in case of a constant border. By default, it is 0.
|
||||
|
||||
The function ``remap`` transforms the source image using the specified map:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \texttt{src} (map_x(x,y),map_y(x,y))
|
||||
|
||||
where values of pixels with non-integer coordinates are computed using one of available interpolation methods.
|
||||
:math:`map_x` and
|
||||
:math:`map_y` can be encoded as separate floating-point maps in
|
||||
:math:`map_1` and
|
||||
:math:`map_2` respectively, or interleaved floating-point maps of
|
||||
:math:`(x,y)` in
|
||||
:math:`map_1` , or
|
||||
fixed-point maps created by using
|
||||
:ocv:func:`convertMaps` . The reason you might want to convert from floating to fixed-point
|
||||
representations of a map is that they can yield much faster (~2x) remapping operations. In the converted case,
|
||||
:math:`map_1` contains pairs ``(cvFloor(x), cvFloor(y))`` and
|
||||
:math:`map_2` contains indices in a table of interpolation coefficients.
|
||||
|
||||
This function cannot operate in-place.
|
||||
|
||||
|
||||
|
||||
resize
|
||||
------
|
||||
Resizes an image.
|
||||
|
||||
.. ocv:function:: void resize( InputArray src, OutputArray dst, Size dsize, double fx=0, double fy=0, int interpolation=INTER_LINEAR )
|
||||
|
||||
.. ocv:pyfunction:: cv2.resize(src, dsize[, dst[, fx[, fy[, interpolation]]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvResize( const CvArr* src, CvArr* dst, int interpolation=CV_INTER_LINEAR )
|
||||
|
||||
:param src: input image.
|
||||
|
||||
:param dst: output image; it has the size ``dsize`` (when it is non-zero) or the size computed from ``src.size()``, ``fx``, and ``fy``; the type of ``dst`` is the same as of ``src``.
|
||||
|
||||
:param dsize: output image size; if it equals zero, it is computed as:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dsize = Size(round(fx*src.cols), round(fy*src.rows))}
|
||||
|
||||
|
||||
Either ``dsize`` or both ``fx`` and ``fy`` must be non-zero.
|
||||
|
||||
:param fx: scale factor along the horizontal axis; when it equals 0, it is computed as
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{(double)dsize.width/src.cols}
|
||||
|
||||
:param fy: scale factor along the vertical axis; when it equals 0, it is computed as
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{(double)dsize.height/src.rows}
|
||||
|
||||
:param interpolation: interpolation method:
|
||||
|
||||
* **INTER_NEAREST** - a nearest-neighbor interpolation
|
||||
|
||||
* **INTER_LINEAR** - a bilinear interpolation (used by default)
|
||||
|
||||
* **INTER_AREA** - resampling using pixel area relation. It may be a preferred method for image decimation, as it gives moire'-free results. But when the image is zoomed, it is similar to the ``INTER_NEAREST`` method.
|
||||
|
||||
* **INTER_CUBIC** - a bicubic interpolation over 4x4 pixel neighborhood
|
||||
|
||||
* **INTER_LANCZOS4** - a Lanczos interpolation over 8x8 pixel neighborhood
|
||||
|
||||
The function ``resize`` resizes the image ``src`` down to or up to the specified size.
|
||||
Note that the initial ``dst`` type or size are not taken into account. Instead, the size and type are derived from the ``src``,``dsize``,``fx`` , and ``fy`` . If you want to resize ``src`` so that it fits the pre-created ``dst`` , you may call the function as follows: ::
|
||||
|
||||
// explicitly specify dsize=dst.size(); fx and fy will be computed from that.
|
||||
resize(src, dst, dst.size(), 0, 0, interpolation);
|
||||
|
||||
|
||||
If you want to decimate the image by factor of 2 in each direction, you can call the function this way: ::
|
||||
|
||||
// specify fx and fy and let the function compute the destination image size.
|
||||
resize(src, dst, Size(), 0.5, 0.5, interpolation);
|
||||
|
||||
To shrink an image, it will generally look best with CV_INTER_AREA interpolation, whereas to enlarge an image, it will generally look best with CV_INTER_CUBIC (slow) or CV_INTER_LINEAR (faster but still looks OK).
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`warpAffine`,
|
||||
:ocv:func:`warpPerspective`,
|
||||
:ocv:func:`remap`
|
||||
|
||||
|
||||
warpAffine
|
||||
----------
|
||||
Applies an affine transformation to an image.
|
||||
|
||||
.. ocv:function:: void warpAffine( InputArray src, OutputArray dst, InputArray M, Size dsize, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar& borderValue=Scalar())
|
||||
|
||||
.. ocv:pyfunction:: cv2.warpAffine(src, M, dsize[, dst[, flags[, borderMode[, borderValue]]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvWarpAffine( const CvArr* src, CvArr* dst, const CvMat* map_matrix, int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS, CvScalar fillval=cvScalarAll(0) )
|
||||
|
||||
.. ocv:cfunction:: void cvGetQuadrangleSubPix( const CvArr* src, CvArr* dst, const CvMat* map_matrix )
|
||||
|
||||
:param src: input image.
|
||||
|
||||
:param dst: output image that has the size ``dsize`` and the same type as ``src`` .
|
||||
|
||||
:param M: :math:`2\times 3` transformation matrix.
|
||||
|
||||
:param dsize: size of the output image.
|
||||
|
||||
:param flags: combination of interpolation methods (see :ocv:func:`resize` ) and the optional flag ``WARP_INVERSE_MAP`` that means that ``M`` is the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` ).
|
||||
|
||||
:param borderMode: pixel extrapolation method (see :ocv:func:`borderInterpolate`); when \ ``borderMode=BORDER_TRANSPARENT`` , it means that the pixels in the destination image corresponding to the "outliers" in the source image are not modified by the function.
|
||||
|
||||
:param borderValue: value used in case of a constant border; by default, it is 0.
|
||||
|
||||
The function ``warpAffine`` transforms the source image using the specified matrix:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \texttt{src} ( \texttt{M} _{11} x + \texttt{M} _{12} y + \texttt{M} _{13}, \texttt{M} _{21} x + \texttt{M} _{22} y + \texttt{M} _{23})
|
||||
|
||||
when the flag ``WARP_INVERSE_MAP`` is set. Otherwise, the transformation is first inverted with
|
||||
:ocv:func:`invertAffineTransform` and then put in the formula above instead of ``M`` .
|
||||
The function cannot operate in-place.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`warpPerspective`,
|
||||
:ocv:func:`resize`,
|
||||
:ocv:func:`remap`,
|
||||
:ocv:func:`getRectSubPix`,
|
||||
:ocv:func:`transform`
|
||||
|
||||
|
||||
.. note:: ``cvGetQuadrangleSubPix`` is similar to ``cvWarpAffine``, but the outliers are extrapolated using replication border mode.
|
||||
|
||||
warpPerspective
|
||||
---------------
|
||||
Applies a perspective transformation to an image.
|
||||
|
||||
.. ocv:function:: void warpPerspective( InputArray src, OutputArray dst, InputArray M, Size dsize, int flags=INTER_LINEAR, int borderMode=BORDER_CONSTANT, const Scalar& borderValue=Scalar())
|
||||
|
||||
.. ocv:pyfunction:: cv2.warpPerspective(src, M, dsize[, dst[, flags[, borderMode[, borderValue]]]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvWarpPerspective( const CvArr* src, CvArr* dst, const CvMat* map_matrix, int flags=CV_INTER_LINEAR+CV_WARP_FILL_OUTLIERS, CvScalar fillval=cvScalarAll(0) )
|
||||
|
||||
:param src: input image.
|
||||
|
||||
:param dst: output image that has the size ``dsize`` and the same type as ``src`` .
|
||||
|
||||
:param M: :math:`3\times 3` transformation matrix.
|
||||
|
||||
:param dsize: size of the output image.
|
||||
|
||||
:param flags: combination of interpolation methods (``INTER_LINEAR`` or ``INTER_NEAREST``) and the optional flag ``WARP_INVERSE_MAP``, that sets ``M`` as the inverse transformation ( :math:`\texttt{dst}\rightarrow\texttt{src}` ).
|
||||
|
||||
:param borderMode: pixel extrapolation method (``BORDER_CONSTANT`` or ``BORDER_REPLICATE``).
|
||||
|
||||
:param borderValue: value used in case of a constant border; by default, it equals 0.
|
||||
|
||||
The function ``warpPerspective`` transforms the source image using the specified matrix:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \texttt{src} \left ( \frac{M_{11} x + M_{12} y + M_{13}}{M_{31} x + M_{32} y + M_{33}} ,
|
||||
\frac{M_{21} x + M_{22} y + M_{23}}{M_{31} x + M_{32} y + M_{33}} \right )
|
||||
|
||||
when the flag ``WARP_INVERSE_MAP`` is set. Otherwise, the transformation is first inverted with
|
||||
:ocv:func:`invert` and then put in the formula above instead of ``M`` .
|
||||
The function cannot operate in-place.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`warpAffine`,
|
||||
:ocv:func:`resize`,
|
||||
:ocv:func:`remap`,
|
||||
:ocv:func:`getRectSubPix`,
|
||||
:ocv:func:`perspectiveTransform`
|
||||
|
||||
|
||||
|
||||
|
||||
initUndistortRectifyMap
|
||||
-----------------------
|
||||
Computes the undistortion and rectification transformation map.
|
||||
|
||||
.. ocv:function:: void initUndistortRectifyMap( InputArray cameraMatrix, InputArray distCoeffs, InputArray R, InputArray newCameraMatrix, Size size, int m1type, OutputArray map1, OutputArray map2 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.initUndistortRectifyMap(cameraMatrix, distCoeffs, R, newCameraMatrix, size, m1type[, map1[, map2]]) -> map1, map2
|
||||
|
||||
.. ocv:cfunction:: void cvInitUndistortRectifyMap( const CvMat* camera_matrix, const CvMat* dist_coeffs, const CvMat * R, const CvMat* new_camera_matrix, CvArr* mapx, CvArr* mapy )
|
||||
.. ocv:cfunction:: void cvInitUndistortMap( const CvMat* camera_matrix, const CvMat* distortion_coeffs, CvArr* mapx, CvArr* mapy )
|
||||
|
||||
:param cameraMatrix: Input camera matrix :math:`A=\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}` .
|
||||
|
||||
:param distCoeffs: Input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5, or 8 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
|
||||
|
||||
:param R: Optional rectification transformation in the object space (3x3 matrix). ``R1`` or ``R2`` , computed by :ocv:func:`stereoRectify` can be passed here. If the matrix is empty, the identity transformation is assumed. In ``cvInitUndistortMap`` R assumed to be an identity matrix.
|
||||
|
||||
:param newCameraMatrix: New camera matrix :math:`A'=\vecthreethree{f_x'}{0}{c_x'}{0}{f_y'}{c_y'}{0}{0}{1}` .
|
||||
|
||||
:param size: Undistorted image size.
|
||||
|
||||
:param m1type: Type of the first output map that can be ``CV_32FC1`` or ``CV_16SC2`` . See :ocv:func:`convertMaps` for details.
|
||||
|
||||
:param map1: The first output map.
|
||||
|
||||
:param map2: The second output map.
|
||||
|
||||
The function computes the joint undistortion and rectification transformation and represents the result in the form of maps for
|
||||
:ocv:func:`remap` . The undistorted image looks like original, as if it is captured with a camera using the camera matrix ``=newCameraMatrix`` and zero distortion. In case of a monocular camera, ``newCameraMatrix`` is usually equal to ``cameraMatrix`` , or it can be computed by
|
||||
:ocv:func:`getOptimalNewCameraMatrix` for a better control over scaling. In case of a stereo camera, ``newCameraMatrix`` is normally set to ``P1`` or ``P2`` computed by
|
||||
:ocv:func:`stereoRectify` .
|
||||
|
||||
Also, this new camera is oriented differently in the coordinate space, according to ``R`` . That, for example, helps to align two heads of a stereo camera so that the epipolar lines on both images become horizontal and have the same y- coordinate (in case of a horizontally aligned stereo camera).
|
||||
|
||||
The function actually builds the maps for the inverse mapping algorithm that is used by
|
||||
:ocv:func:`remap` . That is, for each pixel
|
||||
:math:`(u, v)` in the destination (corrected and rectified) image, the function computes the corresponding coordinates in the source image (that is, in the original image from camera). The following process is applied:
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{array}{l} x \leftarrow (u - {c'}_x)/{f'}_x \\ y \leftarrow (v - {c'}_y)/{f'}_y \\{[X\,Y\,W]} ^T \leftarrow R^{-1}*[x \, y \, 1]^T \\ x' \leftarrow X/W \\ y' \leftarrow Y/W \\ x" \leftarrow x' (1 + k_1 r^2 + k_2 r^4 + k_3 r^6) + 2p_1 x' y' + p_2(r^2 + 2 x'^2) \\ y" \leftarrow y' (1 + k_1 r^2 + k_2 r^4 + k_3 r^6) + p_1 (r^2 + 2 y'^2) + 2 p_2 x' y' \\ map_x(u,v) \leftarrow x" f_x + c_x \\ map_y(u,v) \leftarrow y" f_y + c_y \end{array}
|
||||
|
||||
where
|
||||
:math:`(k_1, k_2, p_1, p_2[, k_3])` are the distortion coefficients.
|
||||
|
||||
In case of a stereo camera, this function is called twice: once for each camera head, after
|
||||
:ocv:func:`stereoRectify` , which in its turn is called after
|
||||
:ocv:func:`stereoCalibrate` . But if the stereo camera was not calibrated, it is still possible to compute the rectification transformations directly from the fundamental matrix using
|
||||
:ocv:func:`stereoRectifyUncalibrated` . For each camera, the function computes homography ``H`` as the rectification transformation in a pixel domain, not a rotation matrix ``R`` in 3D space. ``R`` can be computed from ``H`` as
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{R} = \texttt{cameraMatrix} ^{-1} \cdot \texttt{H} \cdot \texttt{cameraMatrix}
|
||||
|
||||
where ``cameraMatrix`` can be chosen arbitrarily.
|
||||
|
||||
|
||||
|
||||
|
||||
getDefaultNewCameraMatrix
|
||||
-------------------------
|
||||
Returns the default new camera matrix.
|
||||
|
||||
.. ocv:function:: Mat getDefaultNewCameraMatrix(InputArray cameraMatrix, Size imgsize=Size(), bool centerPrincipalPoint=false )
|
||||
|
||||
.. ocv:pyfunction:: cv2.getDefaultNewCameraMatrix(cameraMatrix[, imgsize[, centerPrincipalPoint]]) -> retval
|
||||
|
||||
:param cameraMatrix: Input camera matrix.
|
||||
|
||||
:param imgsize: Camera view image size in pixels.
|
||||
|
||||
:param centerPrincipalPoint: Location of the principal point in the new camera matrix. The parameter indicates whether this location should be at the image center or not.
|
||||
|
||||
The function returns the camera matrix that is either an exact copy of the input ``cameraMatrix`` (when ``centerPrinicipalPoint=false`` ), or the modified one (when ``centerPrincipalPoint=true``).
|
||||
|
||||
In the latter case, the new camera matrix will be:
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{bmatrix} f_x && 0 && ( \texttt{imgSize.width} -1)*0.5 \\ 0 && f_y && ( \texttt{imgSize.height} -1)*0.5 \\ 0 && 0 && 1 \end{bmatrix} ,
|
||||
|
||||
where
|
||||
:math:`f_x` and
|
||||
:math:`f_y` are
|
||||
:math:`(0,0)` and
|
||||
:math:`(1,1)` elements of ``cameraMatrix`` , respectively.
|
||||
|
||||
By default, the undistortion functions in OpenCV (see
|
||||
:ocv:func:`initUndistortRectifyMap`,
|
||||
:ocv:func:`undistort`) do not move the principal point. However, when you work with stereo, it is important to move the principal points in both views to the same y-coordinate (which is required by most of stereo correspondence algorithms), and may be to the same x-coordinate too. So, you can form the new camera matrix for each view where the principal points are located at the center.
|
||||
|
||||
|
||||
|
||||
|
||||
undistort
|
||||
-------------
|
||||
Transforms an image to compensate for lens distortion.
|
||||
|
||||
.. ocv:function:: void undistort( InputArray src, OutputArray dst, InputArray cameraMatrix, InputArray distCoeffs, InputArray newCameraMatrix=noArray() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.undistort(src, cameraMatrix, distCoeffs[, dst[, newCameraMatrix]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvUndistort2( const CvArr* src, CvArr* dst, const CvMat* camera_matrix, const CvMat* distortion_coeffs, const CvMat* new_camera_matrix=0 )
|
||||
|
||||
:param src: Input (distorted) image.
|
||||
|
||||
:param dst: Output (corrected) image that has the same size and type as ``src`` .
|
||||
|
||||
:param cameraMatrix: Input camera matrix :math:`A = \vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}` .
|
||||
|
||||
:param distCoeffs: Input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5, or 8 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
|
||||
|
||||
:param newCameraMatrix: Camera matrix of the distorted image. By default, it is the same as ``cameraMatrix`` but you may additionally scale and shift the result by using a different matrix.
|
||||
|
||||
The function transforms an image to compensate radial and tangential lens distortion.
|
||||
|
||||
The function is simply a combination of
|
||||
:ocv:func:`initUndistortRectifyMap` (with unity ``R`` ) and
|
||||
:ocv:func:`remap` (with bilinear interpolation). See the former function for details of the transformation being performed.
|
||||
|
||||
Those pixels in the destination image, for which there is no correspondent pixels in the source image, are filled with zeros (black color).
|
||||
|
||||
A particular subset of the source image that will be visible in the corrected image can be regulated by ``newCameraMatrix`` . You can use
|
||||
:ocv:func:`getOptimalNewCameraMatrix` to compute the appropriate ``newCameraMatrix`` depending on your requirements.
|
||||
|
||||
The camera matrix and the distortion parameters can be determined using
|
||||
:ocv:func:`calibrateCamera` . If the resolution of images is different from the resolution used at the calibration stage,
|
||||
:math:`f_x, f_y, c_x` and
|
||||
:math:`c_y` need to be scaled accordingly, while the distortion coefficients remain the same.
|
||||
|
||||
|
||||
|
||||
|
||||
undistortPoints
|
||||
-------------------
|
||||
Computes the ideal point coordinates from the observed point coordinates.
|
||||
|
||||
.. ocv:function:: void undistortPoints( InputArray src, OutputArray dst, InputArray cameraMatrix, InputArray distCoeffs, InputArray R=noArray(), InputArray P=noArray())
|
||||
|
||||
.. ocv:cfunction:: void cvUndistortPoints( const CvMat* src, CvMat* dst, const CvMat* camera_matrix, const CvMat* dist_coeffs, const CvMat* R=0, const CvMat* P=0 )
|
||||
|
||||
:param src: Observed point coordinates, 1xN or Nx1 2-channel (CV_32FC2 or CV_64FC2).
|
||||
|
||||
:param dst: Output ideal point coordinates after undistortion and reverse perspective transformation. If matrix ``P`` is identity or omitted, ``dst`` will contain normalized point coordinates.
|
||||
|
||||
:param cameraMatrix: Camera matrix :math:`\vecthreethree{f_x}{0}{c_x}{0}{f_y}{c_y}{0}{0}{1}` .
|
||||
|
||||
:param distCoeffs: Input vector of distortion coefficients :math:`(k_1, k_2, p_1, p_2[, k_3[, k_4, k_5, k_6]])` of 4, 5, or 8 elements. If the vector is NULL/empty, the zero distortion coefficients are assumed.
|
||||
|
||||
:param R: Rectification transformation in the object space (3x3 matrix). ``R1`` or ``R2`` computed by :ocv:func:`stereoRectify` can be passed here. If the matrix is empty, the identity transformation is used.
|
||||
|
||||
:param P: New camera matrix (3x3) or new projection matrix (3x4). ``P1`` or ``P2`` computed by :ocv:func:`stereoRectify` can be passed here. If the matrix is empty, the identity new camera matrix is used.
|
||||
|
||||
The function is similar to
|
||||
:ocv:func:`undistort` and
|
||||
:ocv:func:`initUndistortRectifyMap` but it operates on a sparse set of points instead of a raster image. Also the function performs a reverse transformation to
|
||||
:ocv:func:`projectPoints` . In case of a 3D object, it does not reconstruct its 3D coordinates, but for a planar object, it does, up to a translation vector, if the proper ``R`` is specified. ::
|
||||
|
||||
// (u,v) is the input point, (u', v') is the output point
|
||||
// camera_matrix=[fx 0 cx; 0 fy cy; 0 0 1]
|
||||
// P=[fx' 0 cx' tx; 0 fy' cy' ty; 0 0 1 tz]
|
||||
x" = (u - cx)/fx
|
||||
y" = (v - cy)/fy
|
||||
(x',y') = undistort(x",y",dist_coeffs)
|
||||
[X,Y,W]T = R*[x' y' 1]T
|
||||
x = X/W, y = Y/W
|
||||
// only performed if P=[fx' 0 cx' [tx]; 0 fy' cy' [ty]; 0 0 1 [tz]] is specified
|
||||
u' = x*fx' + cx'
|
||||
v' = y*fy' + cy',
|
||||
|
||||
where ``undistort()`` is an approximate iterative algorithm that estimates the normalized original point coordinates out of the normalized distorted point coordinates ("normalized" means that the coordinates do not depend on the camera matrix).
|
||||
|
||||
The function can be used for both a stereo camera head or a monocular camera (when R is empty).
|
||||
@@ -1,514 +0,0 @@
|
||||
Histograms
|
||||
==========
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
|
||||
calcHist
|
||||
------------
|
||||
Calculates a histogram of a set of arrays.
|
||||
|
||||
.. ocv:function:: void calcHist( const Mat* images, int nimages, const int* channels, InputArray mask, OutputArray hist, int dims, const int* histSize, const float** ranges, bool uniform=true, bool accumulate=false )
|
||||
|
||||
.. ocv:function:: void calcHist( const Mat* images, int nimages, const int* channels, InputArray mask, SparseMat& hist, int dims, const int* histSize, const float** ranges, bool uniform=true, bool accumulate=false )
|
||||
|
||||
.. ocv:pyfunction:: cv2.calcHist(images, channels, mask, histSize, ranges[, hist[, accumulate]]) -> hist
|
||||
|
||||
.. ocv:cfunction:: void cvCalcHist( IplImage** image, CvHistogram* hist, int accumulate=0, const CvArr* mask=NULL )
|
||||
|
||||
:param images: Source arrays. They all should have the same depth, ``CV_8U`` or ``CV_32F`` , and the same size. Each of them can have an arbitrary number of channels.
|
||||
|
||||
:param nimages: Number of source images.
|
||||
|
||||
:param channels: List of the ``dims`` channels used to compute the histogram. The first array channels are numerated from 0 to ``images[0].channels()-1`` , the second array channels are counted from ``images[0].channels()`` to ``images[0].channels() + images[1].channels()-1``, and so on.
|
||||
|
||||
:param mask: Optional mask. If the matrix is not empty, it must be an 8-bit array of the same size as ``images[i]`` . The non-zero mask elements mark the array elements counted in the histogram.
|
||||
|
||||
:param hist: Output histogram, which is a dense or sparse ``dims`` -dimensional array.
|
||||
|
||||
:param dims: Histogram dimensionality that must be positive and not greater than ``CV_MAX_DIMS`` (equal to 32 in the current OpenCV version).
|
||||
|
||||
:param histSize: Array of histogram sizes in each dimension.
|
||||
|
||||
:param ranges: Array of the ``dims`` arrays of the histogram bin boundaries in each dimension. When the histogram is uniform ( ``uniform`` =true), then for each dimension ``i`` it is enough to specify the lower (inclusive) boundary :math:`L_0` of the 0-th histogram bin and the upper (exclusive) boundary :math:`U_{\texttt{histSize}[i]-1}` for the last histogram bin ``histSize[i]-1`` . That is, in case of a uniform histogram each of ``ranges[i]`` is an array of 2 elements. When the histogram is not uniform ( ``uniform=false`` ), then each of ``ranges[i]`` contains ``histSize[i]+1`` elements: :math:`L_0, U_0=L_1, U_1=L_2, ..., U_{\texttt{histSize[i]}-2}=L_{\texttt{histSize[i]}-1}, U_{\texttt{histSize[i]}-1}` . The array elements, that are not between :math:`L_0` and :math:`U_{\texttt{histSize[i]}-1}` , are not counted in the histogram.
|
||||
|
||||
:param uniform: Flag indicating whether the histogram is uniform or not (see above).
|
||||
|
||||
:param accumulate: Accumulation flag. If it is set, the histogram is not cleared in the beginning when it is allocated. This feature enables you to compute a single histogram from several sets of arrays, or to update the histogram in time.
|
||||
|
||||
The functions ``calcHist`` calculate the histogram of one or more
|
||||
arrays. The elements of a tuple used to increment
|
||||
a histogram bin are taken from the corresponding
|
||||
input arrays at the same location. The sample below shows how to compute a 2D Hue-Saturation histogram for a color image. ::
|
||||
|
||||
#include <opencv2/imgproc.hpp>
|
||||
#include <opencv2/highgui.hpp>
|
||||
|
||||
using namespace cv;
|
||||
|
||||
int main( int argc, char** argv )
|
||||
{
|
||||
Mat src, hsv;
|
||||
if( argc != 2 || !(src=imread(argv[1], 1)).data )
|
||||
return -1;
|
||||
|
||||
cvtColor(src, hsv, COLOR_BGR2HSV);
|
||||
|
||||
// Quantize the hue to 30 levels
|
||||
// and the saturation to 32 levels
|
||||
int hbins = 30, sbins = 32;
|
||||
int histSize[] = {hbins, sbins};
|
||||
// hue varies from 0 to 179, see cvtColor
|
||||
float hranges[] = { 0, 180 };
|
||||
// saturation varies from 0 (black-gray-white) to
|
||||
// 255 (pure spectrum color)
|
||||
float sranges[] = { 0, 256 };
|
||||
const float* ranges[] = { hranges, sranges };
|
||||
MatND hist;
|
||||
// we compute the histogram from the 0-th and 1-st channels
|
||||
int channels[] = {0, 1};
|
||||
|
||||
calcHist( &hsv, 1, channels, Mat(), // do not use mask
|
||||
hist, 2, histSize, ranges,
|
||||
true, // the histogram is uniform
|
||||
false );
|
||||
double maxVal=0;
|
||||
minMaxLoc(hist, 0, &maxVal, 0, 0);
|
||||
|
||||
int scale = 10;
|
||||
Mat histImg = Mat::zeros(sbins*scale, hbins*10, CV_8UC3);
|
||||
|
||||
for( int h = 0; h < hbins; h++ )
|
||||
for( int s = 0; s < sbins; s++ )
|
||||
{
|
||||
float binVal = hist.at<float>(h, s);
|
||||
int intensity = cvRound(binVal*255/maxVal);
|
||||
rectangle( histImg, Point(h*scale, s*scale),
|
||||
Point( (h+1)*scale - 1, (s+1)*scale - 1),
|
||||
Scalar::all(intensity),
|
||||
CV_FILLED );
|
||||
}
|
||||
|
||||
namedWindow( "Source", 1 );
|
||||
imshow( "Source", src );
|
||||
|
||||
namedWindow( "H-S Histogram", 1 );
|
||||
imshow( "H-S Histogram", histImg );
|
||||
waitKey();
|
||||
}
|
||||
|
||||
.. note::
|
||||
|
||||
* An example for creating histograms of an image can be found at opencv_source_code/samples/cpp/demhist.cpp
|
||||
|
||||
* (Python) An example for creating color histograms can be found at opencv_source/samples/python2/color_histogram.py
|
||||
* (Python) An example illustrating RGB and grayscale histogram plotting can be found at opencv_source/samples/python2/hist.py
|
||||
|
||||
|
||||
calcBackProject
|
||||
-------------------
|
||||
Calculates the back projection of a histogram.
|
||||
|
||||
.. ocv:function:: void calcBackProject( const Mat* images, int nimages, const int* channels, InputArray hist, OutputArray backProject, const float** ranges, double scale=1, bool uniform=true )
|
||||
|
||||
.. ocv:function:: void calcBackProject( const Mat* images, int nimages, const int* channels, const SparseMat& hist, OutputArray backProject, const float** ranges, double scale=1, bool uniform=true )
|
||||
|
||||
.. ocv:pyfunction:: cv2.calcBackProject(images, channels, hist, ranges, scale[, dst]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvCalcBackProject( IplImage** image, CvArr* backProject, const CvHistogram* hist )
|
||||
|
||||
:param images: Source arrays. They all should have the same depth, ``CV_8U`` or ``CV_32F`` , and the same size. Each of them can have an arbitrary number of channels.
|
||||
|
||||
:param nimages: Number of source images.
|
||||
|
||||
:param channels: The list of channels used to compute the back projection. The number of channels must match the histogram dimensionality. The first array channels are numerated from 0 to ``images[0].channels()-1`` , the second array channels are counted from ``images[0].channels()`` to ``images[0].channels() + images[1].channels()-1``, and so on.
|
||||
|
||||
:param hist: Input histogram that can be dense or sparse.
|
||||
|
||||
:param backProject: Destination back projection array that is a single-channel array of the same size and depth as ``images[0]`` .
|
||||
|
||||
:param ranges: Array of arrays of the histogram bin boundaries in each dimension. See :ocv:func:`calcHist` .
|
||||
|
||||
:param scale: Optional scale factor for the output back projection.
|
||||
|
||||
:param uniform: Flag indicating whether the histogram is uniform or not (see above).
|
||||
|
||||
The functions ``calcBackProject`` calculate the back project of the histogram. That is, similarly to ``calcHist`` , at each location ``(x, y)`` the function collects the values from the selected channels in the input images and finds the corresponding histogram bin. But instead of incrementing it, the function reads the bin value, scales it by ``scale`` , and stores in ``backProject(x,y)`` . In terms of statistics, the function computes probability of each element value in respect with the empirical probability distribution represented by the histogram. See how, for example, you can find and track a bright-colored object in a scene:
|
||||
|
||||
#.
|
||||
Before tracking, show the object to the camera so that it covers almost the whole frame. Calculate a hue histogram. The histogram may have strong maximums, corresponding to the dominant colors in the object.
|
||||
|
||||
#.
|
||||
When tracking, calculate a back projection of a hue plane of each input video frame using that pre-computed histogram. Threshold the back projection to suppress weak colors. It may also make sense to suppress pixels with non-sufficient color saturation and too dark or too bright pixels.
|
||||
|
||||
#.
|
||||
Find connected components in the resulting picture and choose, for example, the largest component.
|
||||
|
||||
This is an approximate algorithm of the
|
||||
:ocv:func:`CamShift` color object tracker.
|
||||
|
||||
.. seealso:: :ocv:func:`calcHist`
|
||||
.. _compareHist:
|
||||
|
||||
compareHist
|
||||
-----------
|
||||
Compares two histograms.
|
||||
|
||||
.. ocv:function:: double compareHist( InputArray H1, InputArray H2, int method )
|
||||
|
||||
.. ocv:function:: double compareHist( const SparseMat& H1, const SparseMat& H2, int method )
|
||||
|
||||
.. ocv:pyfunction:: cv2.compareHist(H1, H2, method) -> retval
|
||||
|
||||
.. ocv:cfunction:: double cvCompareHist( const CvHistogram* hist1, const CvHistogram* hist2, int method )
|
||||
|
||||
:param H1: First compared histogram.
|
||||
|
||||
:param H2: Second compared histogram of the same size as ``H1`` .
|
||||
|
||||
:param method: Comparison method that could be one of the following:
|
||||
|
||||
* **CV_COMP_CORREL** Correlation
|
||||
|
||||
* **CV_COMP_CHISQR** Chi-Square
|
||||
|
||||
* **CV_COMP_CHISQR_ALT** Alternative Chi-Square
|
||||
|
||||
* **CV_COMP_INTERSECT** Intersection
|
||||
|
||||
* **CV_COMP_BHATTACHARYYA** Bhattacharyya distance
|
||||
|
||||
* **CV_COMP_HELLINGER** Synonym for ``CV_COMP_BHATTACHARYYA``
|
||||
|
||||
* **CV_COMP_KL_DIV** Kullback-Leibler divergence
|
||||
|
||||
The functions ``compareHist`` compare two dense or two sparse histograms using the specified method:
|
||||
|
||||
* Correlation (``method=CV_COMP_CORREL``)
|
||||
|
||||
.. math::
|
||||
|
||||
d(H_1,H_2) = \frac{\sum_I (H_1(I) - \bar{H_1}) (H_2(I) - \bar{H_2})}{\sqrt{\sum_I(H_1(I) - \bar{H_1})^2 \sum_I(H_2(I) - \bar{H_2})^2}}
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
\bar{H_k} = \frac{1}{N} \sum _J H_k(J)
|
||||
|
||||
and
|
||||
:math:`N` is a total number of histogram bins.
|
||||
|
||||
* Chi-Square (``method=CV_COMP_CHISQR``)
|
||||
|
||||
.. math::
|
||||
|
||||
d(H_1,H_2) = \sum _I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)}
|
||||
|
||||
* Alternative Chi-Square (``method=CV_COMP_CHISQR_ALT``)
|
||||
|
||||
.. math::
|
||||
|
||||
d(H_1,H_2) = 2 * \sum _I \frac{\left(H_1(I)-H_2(I)\right)^2}{H_1(I)+H_2(I)}
|
||||
|
||||
This alternative formula is regularly used for texture comparison. See e.g. [Puzicha1997]_.
|
||||
|
||||
* Intersection (``method=CV_COMP_INTERSECT``)
|
||||
|
||||
.. math::
|
||||
|
||||
d(H_1,H_2) = \sum _I \min (H_1(I), H_2(I))
|
||||
|
||||
* Bhattacharyya distance (``method=CV_COMP_BHATTACHARYYA`` or ``method=CV_COMP_HELLINGER``). In fact, OpenCV computes Hellinger distance, which is related to Bhattacharyya coefficient.
|
||||
|
||||
.. math::
|
||||
|
||||
d(H_1,H_2) = \sqrt{1 - \frac{1}{\sqrt{\bar{H_1} \bar{H_2} N^2}} \sum_I \sqrt{H_1(I) \cdot H_2(I)}}
|
||||
|
||||
* Kullback-Leibler divergence (``method=CV_COMP_KL_DIV``).
|
||||
|
||||
.. math::
|
||||
|
||||
d(H_1,H_2) = \sum _I H_1(I) \log \left(\frac{H_1(I)}{H_2(I)}\right)
|
||||
|
||||
The function returns
|
||||
:math:`d(H_1, H_2)` .
|
||||
|
||||
While the function works well with 1-, 2-, 3-dimensional dense histograms, it may not be suitable for high-dimensional sparse histograms. In such histograms, because of aliasing and sampling problems, the coordinates of non-zero histogram bins can slightly shift. To compare such histograms or more general sparse configurations of weighted points, consider using the
|
||||
:ocv:func:`EMD` function.
|
||||
|
||||
|
||||
|
||||
|
||||
EMD
|
||||
------
|
||||
Computes the "minimal work" distance between two weighted point configurations.
|
||||
|
||||
.. ocv:function:: float EMD( InputArray signature1, InputArray signature2, int distType, InputArray cost=noArray(), float* lowerBound=0, OutputArray flow=noArray() )
|
||||
|
||||
.. ocv:cfunction:: float cvCalcEMD2( const CvArr* signature1, const CvArr* signature2, int distance_type, CvDistanceFunction distance_func=NULL, const CvArr* cost_matrix=NULL, CvArr* flow=NULL, float* lower_bound=NULL, void* userdata=NULL )
|
||||
|
||||
:param signature1: First signature, a :math:`\texttt{size1}\times \texttt{dims}+1` floating-point matrix. Each row stores the point weight followed by the point coordinates. The matrix is allowed to have a single column (weights only) if the user-defined cost matrix is used.
|
||||
|
||||
:param signature2: Second signature of the same format as ``signature1`` , though the number of rows may be different. The total weights may be different. In this case an extra "dummy" point is added to either ``signature1`` or ``signature2`` .
|
||||
|
||||
:param distType: Used metric. ``CV_DIST_L1, CV_DIST_L2`` , and ``CV_DIST_C`` stand for one of the standard metrics. ``CV_DIST_USER`` means that a pre-calculated cost matrix ``cost`` is used.
|
||||
|
||||
:param distance_func: Custom distance function supported by the old interface. ``CvDistanceFunction`` is defined as: ::
|
||||
|
||||
typedef float (CV_CDECL * CvDistanceFunction)( const float* a,
|
||||
const float* b, void* userdata );
|
||||
|
||||
where ``a`` and ``b`` are point coordinates and ``userdata`` is the same as the last parameter.
|
||||
|
||||
:param cost: User-defined :math:`\texttt{size1}\times \texttt{size2}` cost matrix. Also, if a cost matrix is used, lower boundary ``lowerBound`` cannot be calculated because it needs a metric function.
|
||||
|
||||
:param lowerBound: Optional input/output parameter: lower boundary of a distance between the two signatures that is a distance between mass centers. The lower boundary may not be calculated if the user-defined cost matrix is used, the total weights of point configurations are not equal, or if the signatures consist of weights only (the signature matrices have a single column). You **must** initialize ``*lowerBound`` . If the calculated distance between mass centers is greater or equal to ``*lowerBound`` (it means that the signatures are far enough), the function does not calculate EMD. In any case ``*lowerBound`` is set to the calculated distance between mass centers on return. Thus, if you want to calculate both distance between mass centers and EMD, ``*lowerBound`` should be set to 0.
|
||||
|
||||
:param flow: Resultant :math:`\texttt{size1} \times \texttt{size2}` flow matrix: :math:`\texttt{flow}_{i,j}` is a flow from :math:`i` -th point of ``signature1`` to :math:`j` -th point of ``signature2`` .
|
||||
|
||||
:param userdata: Optional pointer directly passed to the custom distance function.
|
||||
|
||||
The function computes the earth mover distance and/or a lower boundary of the distance between the two weighted point configurations. One of the applications described in [RubnerSept98]_ is multi-dimensional histogram comparison for image retrieval. EMD is a transportation problem that is solved using some modification of a simplex algorithm, thus the complexity is exponential in the worst case, though, on average it is much faster. In the case of a real metric the lower boundary can be calculated even faster (using linear-time algorithm) and it can be used to determine roughly whether the two signatures are far enough so that they cannot relate to the same object.
|
||||
|
||||
|
||||
equalizeHist
|
||||
----------------
|
||||
Equalizes the histogram of a grayscale image.
|
||||
|
||||
.. ocv:function:: void equalizeHist( InputArray src, OutputArray dst )
|
||||
|
||||
.. ocv:pyfunction:: cv2.equalizeHist(src[, dst]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvEqualizeHist( const CvArr* src, CvArr* dst )
|
||||
|
||||
:param src: Source 8-bit single channel image.
|
||||
|
||||
:param dst: Destination image of the same size and type as ``src`` .
|
||||
|
||||
The function equalizes the histogram of the input image using the following algorithm:
|
||||
|
||||
#.
|
||||
Calculate the histogram
|
||||
:math:`H` for ``src`` .
|
||||
|
||||
#.
|
||||
Normalize the histogram so that the sum of histogram bins is 255.
|
||||
|
||||
#.
|
||||
Compute the integral of the histogram:
|
||||
|
||||
.. math::
|
||||
|
||||
H'_i = \sum _{0 \le j < i} H(j)
|
||||
|
||||
#.
|
||||
Transform the image using
|
||||
:math:`H'` as a look-up table:
|
||||
:math:`\texttt{dst}(x,y) = H'(\texttt{src}(x,y))`
|
||||
|
||||
The algorithm normalizes the brightness and increases the contrast of the image.
|
||||
|
||||
|
||||
Extra Histogram Functions (C API)
|
||||
---------------------------------
|
||||
|
||||
The rest of the section describes additional C functions operating on ``CvHistogram``.
|
||||
|
||||
CalcBackProjectPatch
|
||||
--------------------
|
||||
Locates a template within an image by using a histogram comparison.
|
||||
|
||||
.. ocv:cfunction:: void cvCalcBackProjectPatch( IplImage** images, CvArr* dst, CvSize patch_size, CvHistogram* hist, int method, double factor )
|
||||
|
||||
:param images: Source images (though, you may pass CvMat** as well).
|
||||
|
||||
:param dst: Destination image.
|
||||
|
||||
:param patch_size: Size of the patch slid though the source image.
|
||||
|
||||
:param hist: Histogram.
|
||||
|
||||
:param method: Comparison method passed to :ocv:cfunc:`CompareHist` (see the function description).
|
||||
|
||||
:param factor: Normalization factor for histograms that affects the normalization scale of the destination image. Pass 1 if not sure.
|
||||
|
||||
The function calculates the back projection by comparing histograms of the source image patches with the given histogram. The function is similar to :ocv:func:`matchTemplate`, but instead of comparing the raster patch with all its possible positions within the search window, the function ``CalcBackProjectPatch`` compares histograms. See the algorithm diagram below:
|
||||
|
||||
.. image:: pics/backprojectpatch.png
|
||||
|
||||
|
||||
CalcProbDensity
|
||||
---------------
|
||||
Divides one histogram by another.
|
||||
|
||||
.. ocv:cfunction:: void cvCalcProbDensity( const CvHistogram* hist1, const CvHistogram* hist2, CvHistogram* dst_hist, double scale=255 )
|
||||
|
||||
:param hist1: First histogram (the divisor).
|
||||
|
||||
:param hist2: Second histogram.
|
||||
|
||||
:param dst_hist: Destination histogram.
|
||||
|
||||
:param scale: Scale factor for the destination histogram.
|
||||
|
||||
The function calculates the object probability density from two histograms as:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{disthist} (I)= \forkthree{0}{if $\texttt{hist1}(I)=0$}{\texttt{scale}}{if $\texttt{hist1}(I) \ne 0$ and $\texttt{hist2}(I) > \texttt{hist1}(I)$}{\frac{\texttt{hist2}(I) \cdot \texttt{scale}}{\texttt{hist1}(I)}}{if $\texttt{hist1}(I) \ne 0$ and $\texttt{hist2}(I) \le \texttt{hist1}(I)$}
|
||||
|
||||
|
||||
ClearHist
|
||||
---------
|
||||
Clears the histogram.
|
||||
|
||||
.. ocv:cfunction:: void cvClearHist( CvHistogram* hist )
|
||||
|
||||
:param hist: Histogram.
|
||||
|
||||
The function sets all of the histogram bins to 0 in case of a dense histogram and removes all histogram bins in case of a sparse array.
|
||||
|
||||
|
||||
CopyHist
|
||||
--------
|
||||
Copies a histogram.
|
||||
|
||||
.. ocv:cfunction:: void cvCopyHist( const CvHistogram* src, CvHistogram** dst )
|
||||
|
||||
:param src: Source histogram.
|
||||
|
||||
:param dst: Pointer to the destination histogram.
|
||||
|
||||
The function makes a copy of the histogram. If the second histogram pointer ``*dst`` is NULL, a new histogram of the same size as ``src`` is created. Otherwise, both histograms must have equal types and sizes. Then the function copies the bin values of the source histogram to the destination histogram and sets the same bin value ranges as in ``src``.
|
||||
|
||||
.. _createhist:
|
||||
|
||||
CreateHist
|
||||
----------
|
||||
Creates a histogram.
|
||||
|
||||
.. ocv:cfunction:: CvHistogram* cvCreateHist( int dims, int* sizes, int type, float** ranges=NULL, int uniform=1 )
|
||||
|
||||
:param dims: Number of histogram dimensions.
|
||||
|
||||
:param sizes: Array of the histogram dimension sizes.
|
||||
|
||||
:param type: Histogram representation format. ``CV_HIST_ARRAY`` means that the histogram data is represented as a multi-dimensional dense array CvMatND. ``CV_HIST_SPARSE`` means that histogram data is represented as a multi-dimensional sparse array ``CvSparseMat``.
|
||||
|
||||
:param ranges: Array of ranges for the histogram bins. Its meaning depends on the ``uniform`` parameter value. The ranges are used when the histogram is calculated or backprojected to determine which histogram bin corresponds to which value/tuple of values from the input image(s).
|
||||
|
||||
:param uniform: Uniformity flag. If not zero, the histogram has evenly
|
||||
spaced bins and for every :math:`0<=i<cDims` ``ranges[i]``
|
||||
is an array of two numbers: lower and upper boundaries for the i-th
|
||||
histogram dimension.
|
||||
The whole range [lower,upper] is then split
|
||||
into ``dims[i]`` equal parts to determine the ``i``-th input
|
||||
tuple value ranges for every histogram bin. And if ``uniform=0`` ,
|
||||
then the ``i``-th element of the ``ranges`` array contains ``dims[i]+1`` elements: :math:`\texttt{lower}_0, \texttt{upper}_0,
|
||||
\texttt{lower}_1, \texttt{upper}_1 = \texttt{lower}_2,
|
||||
...
|
||||
\texttt{upper}_{dims[i]-1}`
|
||||
where :math:`\texttt{lower}_j` and :math:`\texttt{upper}_j`
|
||||
are lower and upper
|
||||
boundaries of the ``i``-th input tuple value for the ``j``-th
|
||||
bin, respectively. In either case, the input values that are beyond
|
||||
the specified range for a histogram bin are not counted by :ocv:cfunc:`CalcHist` and filled with 0 by :ocv:cfunc:`CalcBackProject`.
|
||||
|
||||
The function creates a histogram of the specified size and returns a pointer to the created histogram. If the array ``ranges`` is 0, the histogram bin ranges must be specified later via the function :ocv:cfunc:`SetHistBinRanges`. Though :ocv:cfunc:`CalcHist` and :ocv:cfunc:`CalcBackProject` may process 8-bit images without setting bin ranges, they assume they are equally spaced in 0 to 255 bins.
|
||||
|
||||
|
||||
GetMinMaxHistValue
|
||||
------------------
|
||||
Finds the minimum and maximum histogram bins.
|
||||
|
||||
.. ocv:cfunction:: void cvGetMinMaxHistValue( const CvHistogram* hist, float* min_value, float* max_value, int* min_idx=NULL, int* max_idx=NULL )
|
||||
|
||||
:param hist: Histogram.
|
||||
|
||||
:param min_value: Pointer to the minimum value of the histogram.
|
||||
|
||||
:param max_value: Pointer to the maximum value of the histogram.
|
||||
|
||||
:param min_idx: Pointer to the array of coordinates for the minimum.
|
||||
|
||||
:param max_idx: Pointer to the array of coordinates for the maximum.
|
||||
|
||||
The function finds the minimum and maximum histogram bins and their positions. All of output arguments are optional. Among several extremas with the same value the ones with the minimum index (in the lexicographical order) are returned. In case of several maximums or minimums, the earliest in the lexicographical order (extrema locations) is returned.
|
||||
|
||||
|
||||
MakeHistHeaderForArray
|
||||
----------------------
|
||||
Makes a histogram out of an array.
|
||||
|
||||
.. ocv:cfunction:: CvHistogram* cvMakeHistHeaderForArray( int dims, int* sizes, CvHistogram* hist, float* data, float** ranges=NULL, int uniform=1 )
|
||||
|
||||
:param dims: Number of the histogram dimensions.
|
||||
|
||||
:param sizes: Array of the histogram dimension sizes.
|
||||
|
||||
:param hist: Histogram header initialized by the function.
|
||||
|
||||
:param data: Array used to store histogram bins.
|
||||
|
||||
:param ranges: Histogram bin ranges. See :ocv:cfunc:`CreateHist` for details.
|
||||
|
||||
:param uniform: Uniformity flag. See :ocv:cfunc:`CreateHist` for details.
|
||||
|
||||
The function initializes the histogram, whose header and bins are allocated by the user. :ocv:cfunc:`ReleaseHist` does not need to be called afterwards. Only dense histograms can be initialized this way. The function returns ``hist``.
|
||||
|
||||
NormalizeHist
|
||||
-------------
|
||||
Normalizes the histogram.
|
||||
|
||||
.. ocv:cfunction:: void cvNormalizeHist( CvHistogram* hist, double factor )
|
||||
|
||||
:param hist: Pointer to the histogram.
|
||||
|
||||
:param factor: Normalization factor.
|
||||
|
||||
The function normalizes the histogram bins by scaling them so that the sum of the bins becomes equal to ``factor``.
|
||||
|
||||
|
||||
ReleaseHist
|
||||
-----------
|
||||
Releases the histogram.
|
||||
|
||||
.. ocv:cfunction:: void cvReleaseHist( CvHistogram** hist )
|
||||
|
||||
:param hist: Double pointer to the released histogram.
|
||||
|
||||
The function releases the histogram (header and the data). The pointer to the histogram is cleared by the function. If ``*hist`` pointer is already ``NULL``, the function does nothing.
|
||||
|
||||
|
||||
SetHistBinRanges
|
||||
----------------
|
||||
Sets the bounds of the histogram bins.
|
||||
|
||||
.. ocv:cfunction:: void cvSetHistBinRanges( CvHistogram* hist, float** ranges, int uniform=1 )
|
||||
|
||||
:param hist: Histogram.
|
||||
|
||||
:param ranges: Array of bin ranges arrays. See :ocv:cfunc:`CreateHist` for details.
|
||||
|
||||
:param uniform: Uniformity flag. See :ocv:cfunc:`CreateHist` for details.
|
||||
|
||||
This is a standalone function for setting bin ranges in the histogram. For a more detailed description of the parameters ``ranges`` and ``uniform``, see the :ocv:cfunc:`CalcHist` function that can initialize the ranges as well. Ranges for the histogram bins must be set before the histogram is calculated or the backproject of the histogram is calculated.
|
||||
|
||||
|
||||
ThreshHist
|
||||
----------
|
||||
Thresholds the histogram.
|
||||
|
||||
.. ocv:cfunction:: void cvThreshHist( CvHistogram* hist, double threshold )
|
||||
|
||||
:param hist: Pointer to the histogram.
|
||||
|
||||
:param threshold: Threshold level.
|
||||
|
||||
The function clears histogram bins that are below the specified threshold.
|
||||
|
||||
|
||||
.. [RubnerSept98] Y. Rubner. C. Tomasi, L.J. Guibas. *The Earth Mover’s Distance as a Metric for Image Retrieval*. Technical Report STAN-CS-TN-98-86, Department of Computer Science, Stanford University, September 1998.
|
||||
.. [Puzicha1997] Puzicha, J., Hofmann, T., and Buhmann, J. *Non-parametric similarity measures for unsupervised texture segmentation and image retrieval.* In Proc. IEEE Conf. Computer Vision and Pattern Recognition, San Juan, Puerto Rico, pp. 267-272, 1997.
|
||||
@@ -1,19 +0,0 @@
|
||||
*************************
|
||||
imgproc. Image Processing
|
||||
*************************
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
filtering
|
||||
geometric_transformations
|
||||
miscellaneous_transformations
|
||||
drawing_functions
|
||||
colormaps
|
||||
histograms
|
||||
structural_analysis_and_shape_descriptors
|
||||
motion_analysis_and_object_tracking
|
||||
feature_detection
|
||||
object_detection
|
||||
@@ -1,813 +0,0 @@
|
||||
Miscellaneous Image Transformations
|
||||
===================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
|
||||
adaptiveThreshold
|
||||
---------------------
|
||||
Applies an adaptive threshold to an array.
|
||||
|
||||
.. ocv:function:: void adaptiveThreshold( InputArray src, OutputArray dst, double maxValue, int adaptiveMethod, int thresholdType, int blockSize, double C )
|
||||
|
||||
.. ocv:pyfunction:: cv2.adaptiveThreshold(src, maxValue, adaptiveMethod, thresholdType, blockSize, C[, dst]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvAdaptiveThreshold( const CvArr* src, CvArr* dst, double max_value, int adaptive_method=CV_ADAPTIVE_THRESH_MEAN_C, int threshold_type=CV_THRESH_BINARY, int block_size=3, double param1=5 )
|
||||
|
||||
:param src: Source 8-bit single-channel image.
|
||||
|
||||
:param dst: Destination image of the same size and the same type as ``src`` .
|
||||
|
||||
:param maxValue: Non-zero value assigned to the pixels for which the condition is satisfied. See the details below.
|
||||
|
||||
:param adaptiveMethod: Adaptive thresholding algorithm to use, ``ADAPTIVE_THRESH_MEAN_C`` or ``ADAPTIVE_THRESH_GAUSSIAN_C`` . See the details below.
|
||||
|
||||
:param thresholdType: Thresholding type that must be either ``THRESH_BINARY`` or ``THRESH_BINARY_INV`` .
|
||||
|
||||
:param blockSize: Size of a pixel neighborhood that is used to calculate a threshold value for the pixel: 3, 5, 7, and so on.
|
||||
|
||||
:param C: Constant subtracted from the mean or weighted mean (see the details below). Normally, it is positive but may be zero or negative as well.
|
||||
|
||||
The function transforms a grayscale image to a binary image according to the formulae:
|
||||
|
||||
* **THRESH_BINARY**
|
||||
|
||||
.. math::
|
||||
|
||||
dst(x,y) = \fork{\texttt{maxValue}}{if $src(x,y) > T(x,y)$}{0}{otherwise}
|
||||
|
||||
* **THRESH_BINARY_INV**
|
||||
|
||||
.. math::
|
||||
|
||||
dst(x,y) = \fork{0}{if $src(x,y) > T(x,y)$}{\texttt{maxValue}}{otherwise}
|
||||
|
||||
where
|
||||
:math:`T(x,y)` is a threshold calculated individually for each pixel.
|
||||
|
||||
*
|
||||
For the method ``ADAPTIVE_THRESH_MEAN_C`` , the threshold value
|
||||
:math:`T(x,y)` is a mean of the
|
||||
:math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood of
|
||||
:math:`(x, y)` minus ``C`` .
|
||||
|
||||
*
|
||||
For the method ``ADAPTIVE_THRESH_GAUSSIAN_C`` , the threshold value
|
||||
:math:`T(x, y)` is a weighted sum (cross-correlation with a Gaussian window) of the
|
||||
:math:`\texttt{blockSize} \times \texttt{blockSize}` neighborhood of
|
||||
:math:`(x, y)` minus ``C`` . The default sigma (standard deviation) is used for the specified ``blockSize`` . See
|
||||
:ocv:func:`getGaussianKernel` .
|
||||
|
||||
The function can process the image in-place.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`threshold`,
|
||||
:ocv:func:`blur`,
|
||||
:ocv:func:`GaussianBlur`
|
||||
|
||||
|
||||
|
||||
cvtColor
|
||||
--------
|
||||
Converts an image from one color space to another.
|
||||
|
||||
.. ocv:function:: void cvtColor( InputArray src, OutputArray dst, int code, int dstCn=0 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.cvtColor(src, code[, dst[, dstCn]]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvCvtColor( const CvArr* src, CvArr* dst, int code )
|
||||
|
||||
:param src: input image: 8-bit unsigned, 16-bit unsigned ( ``CV_16UC...`` ), or single-precision floating-point.
|
||||
|
||||
:param dst: output image of the same size and depth as ``src``.
|
||||
|
||||
:param code: color space conversion code (see the description below).
|
||||
|
||||
:param dstCn: number of channels in the destination image; if the parameter is 0, the number of the channels is derived automatically from ``src`` and ``code`` .
|
||||
|
||||
The function converts an input image from one color
|
||||
space to another. In case of a transformation to-from RGB color space, the order of the channels should be specified explicitly (RGB or BGR).
|
||||
Note that the default color format in OpenCV is often referred to as RGB but it is actually BGR (the bytes are reversed). So the first byte in a standard (24-bit) color image will be an 8-bit Blue component, the second byte will be Green, and the third byte will be Red. The fourth, fifth, and sixth bytes would then be the second pixel (Blue, then Green, then Red), and so on.
|
||||
|
||||
The conventional ranges for R, G, and B channel values are:
|
||||
|
||||
*
|
||||
0 to 255 for ``CV_8U`` images
|
||||
|
||||
*
|
||||
0 to 65535 for ``CV_16U`` images
|
||||
|
||||
*
|
||||
0 to 1 for ``CV_32F`` images
|
||||
|
||||
In case of linear transformations, the range does not matter.
|
||||
But in case of a non-linear transformation, an input RGB image should be normalized to the proper value range to get the correct results, for example, for RGB
|
||||
:math:`\rightarrow` L*u*v* transformation. For example, if you have a 32-bit floating-point image directly converted from an 8-bit image without any scaling, then it will have the 0..255 value range instead of 0..1 assumed by the function. So, before calling ``cvtColor`` , you need first to scale the image down: ::
|
||||
|
||||
img *= 1./255;
|
||||
cvtColor(img, img, COLOR_BGR2Luv);
|
||||
|
||||
If you use ``cvtColor`` with 8-bit images, the conversion will have some information lost. For many applications, this will not be noticeable but it is recommended to use 32-bit images in applications that need the full range of colors or that convert an image before an operation and then convert back.
|
||||
|
||||
If conversion adds the alpha channel, its value will set to the maximum of corresponding channel range: 255 for ``CV_8U``, 65535 for ``CV_16U``, 1 for ``CV_32F``.
|
||||
|
||||
The function can do the following transformations:
|
||||
|
||||
*
|
||||
RGB :math:`\leftrightarrow` GRAY ( ``COLOR_BGR2GRAY, COLOR_RGB2GRAY, COLOR_GRAY2BGR, COLOR_GRAY2RGB`` )
|
||||
Transformations within RGB space like adding/removing the alpha channel, reversing the channel order, conversion to/from 16-bit RGB color (R5:G6:B5 or R5:G5:B5), as well as conversion to/from grayscale using:
|
||||
|
||||
.. math::
|
||||
|
||||
\text{RGB[A] to Gray:} \quad Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
|
||||
|
||||
and
|
||||
|
||||
.. math::
|
||||
|
||||
\text{Gray to RGB[A]:} \quad R \leftarrow Y, G \leftarrow Y, B \leftarrow Y, A \leftarrow \max (ChannelRange)
|
||||
|
||||
The conversion from a RGB image to gray is done with:
|
||||
|
||||
::
|
||||
|
||||
cvtColor(src, bwsrc, COLOR_RGB2GRAY);
|
||||
|
||||
..
|
||||
|
||||
More advanced channel reordering can also be done with
|
||||
:ocv:func:`mixChannels` .
|
||||
|
||||
*
|
||||
RGB
|
||||
:math:`\leftrightarrow` CIE XYZ.Rec 709 with D65 white point ( ``COLOR_BGR2XYZ, COLOR_RGB2XYZ, COLOR_XYZ2BGR, COLOR_XYZ2RGB`` ):
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{bmatrix} X \\ Y \\ Z
|
||||
\end{bmatrix} \leftarrow \begin{bmatrix} 0.412453 & 0.357580 & 0.180423 \\ 0.212671 & 0.715160 & 0.072169 \\ 0.019334 & 0.119193 & 0.950227
|
||||
\end{bmatrix} \cdot \begin{bmatrix} R \\ G \\ B
|
||||
\end{bmatrix}
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{bmatrix} R \\ G \\ B
|
||||
\end{bmatrix} \leftarrow \begin{bmatrix} 3.240479 & -1.53715 & -0.498535 \\ -0.969256 & 1.875991 & 0.041556 \\ 0.055648 & -0.204043 & 1.057311
|
||||
\end{bmatrix} \cdot \begin{bmatrix} X \\ Y \\ Z
|
||||
\end{bmatrix}
|
||||
|
||||
:math:`X`, :math:`Y` and
|
||||
:math:`Z` cover the whole value range (in case of floating-point images,
|
||||
:math:`Z` may exceed 1).
|
||||
|
||||
*
|
||||
RGB
|
||||
:math:`\leftrightarrow` YCrCb JPEG (or YCC) ( ``COLOR_BGR2YCrCb, COLOR_RGB2YCrCb, COLOR_YCrCb2BGR, COLOR_YCrCb2RGB`` )
|
||||
|
||||
.. math::
|
||||
|
||||
Y \leftarrow 0.299 \cdot R + 0.587 \cdot G + 0.114 \cdot B
|
||||
|
||||
.. math::
|
||||
|
||||
Cr \leftarrow (R-Y) \cdot 0.713 + delta
|
||||
|
||||
.. math::
|
||||
|
||||
Cb \leftarrow (B-Y) \cdot 0.564 + delta
|
||||
|
||||
.. math::
|
||||
|
||||
R \leftarrow Y + 1.403 \cdot (Cr - delta)
|
||||
|
||||
.. math::
|
||||
|
||||
G \leftarrow Y - 0.714 \cdot (Cr - delta) - 0.344 \cdot (Cb - delta)
|
||||
|
||||
.. math::
|
||||
|
||||
B \leftarrow Y + 1.773 \cdot (Cb - delta)
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
delta = \left \{ \begin{array}{l l} 128 & \mbox{for 8-bit images} \\ 32768 & \mbox{for 16-bit images} \\ 0.5 & \mbox{for floating-point images} \end{array} \right .
|
||||
|
||||
Y, Cr, and Cb cover the whole value range.
|
||||
|
||||
*
|
||||
RGB :math:`\leftrightarrow` HSV ( ``COLOR_BGR2HSV, COLOR_RGB2HSV, COLOR_HSV2BGR, COLOR_HSV2RGB`` )
|
||||
In case of 8-bit and 16-bit images,
|
||||
R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
|
||||
|
||||
.. math::
|
||||
|
||||
V \leftarrow max(R,G,B)
|
||||
|
||||
.. math::
|
||||
|
||||
S \leftarrow \fork{\frac{V-min(R,G,B)}{V}}{if $V \neq 0$}{0}{otherwise}
|
||||
|
||||
.. math::
|
||||
|
||||
H \leftarrow \forkthree{{60(G - B)}/{(V-min(R,G,B))}}{if $V=R$}{{120+60(B - R)}/{(V-min(R,G,B))}}{if $V=G$}{{240+60(R - G)}/{(V-min(R,G,B))}}{if $V=B$}
|
||||
|
||||
If
|
||||
:math:`H<0` then
|
||||
:math:`H \leftarrow H+360` . On output
|
||||
:math:`0 \leq V \leq 1`, :math:`0 \leq S \leq 1`, :math:`0 \leq H \leq 360` .
|
||||
|
||||
The values are then converted to the destination data type:
|
||||
|
||||
* 8-bit images
|
||||
|
||||
.. math::
|
||||
|
||||
V \leftarrow 255 V, S \leftarrow 255 S, H \leftarrow H/2 \text{(to fit to 0 to 255)}
|
||||
|
||||
* 16-bit images (currently not supported)
|
||||
|
||||
.. math::
|
||||
|
||||
V <- 65535 V, S <- 65535 S, H <- H
|
||||
|
||||
* 32-bit images
|
||||
H, S, and V are left as is
|
||||
|
||||
*
|
||||
RGB :math:`\leftrightarrow` HLS ( ``COLOR_BGR2HLS, COLOR_RGB2HLS, COLOR_HLS2BGR, COLOR_HLS2RGB`` ).
|
||||
In case of 8-bit and 16-bit images,
|
||||
R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
|
||||
|
||||
.. math::
|
||||
|
||||
V_{max} \leftarrow {max}(R,G,B)
|
||||
|
||||
.. math::
|
||||
|
||||
V_{min} \leftarrow {min}(R,G,B)
|
||||
|
||||
.. math::
|
||||
|
||||
L \leftarrow \frac{V_{max} + V_{min}}{2}
|
||||
|
||||
.. math::
|
||||
|
||||
S \leftarrow \fork { \frac{V_{max} - V_{min}}{V_{max} + V_{min}} }{if $L < 0.5$ }
|
||||
{ \frac{V_{max} - V_{min}}{2 - (V_{max} + V_{min})} }{if $L \ge 0.5$ }
|
||||
|
||||
.. math::
|
||||
|
||||
H \leftarrow \forkthree {{60(G - B)}/{S}}{if $V_{max}=R$ }
|
||||
{{120+60(B - R)}/{S}}{if $V_{max}=G$ }
|
||||
{{240+60(R - G)}/{S}}{if $V_{max}=B$ }
|
||||
|
||||
If
|
||||
:math:`H<0` then
|
||||
:math:`H \leftarrow H+360` . On output
|
||||
:math:`0 \leq L \leq 1`, :math:`0 \leq S \leq 1`, :math:`0 \leq H \leq 360` .
|
||||
|
||||
The values are then converted to the destination data type:
|
||||
|
||||
* 8-bit images
|
||||
|
||||
.. math::
|
||||
|
||||
V \leftarrow 255 \cdot V, S \leftarrow 255 \cdot S, H \leftarrow H/2 \; \text{(to fit to 0 to 255)}
|
||||
|
||||
* 16-bit images (currently not supported)
|
||||
|
||||
.. math::
|
||||
|
||||
V <- 65535 \cdot V, S <- 65535 \cdot S, H <- H
|
||||
|
||||
* 32-bit images
|
||||
H, S, V are left as is
|
||||
|
||||
*
|
||||
RGB :math:`\leftrightarrow` CIE L*a*b* ( ``COLOR_BGR2Lab, COLOR_RGB2Lab, COLOR_Lab2BGR, COLOR_Lab2RGB`` ).
|
||||
In case of 8-bit and 16-bit images,
|
||||
R, G, and B are converted to the floating-point format and scaled to fit the 0 to 1 range.
|
||||
|
||||
.. math::
|
||||
|
||||
\vecthree{X}{Y}{Z} \leftarrow \vecthreethree{0.412453}{0.357580}{0.180423}{0.212671}{0.715160}{0.072169}{0.019334}{0.119193}{0.950227} \cdot \vecthree{R}{G}{B}
|
||||
|
||||
.. math::
|
||||
|
||||
X \leftarrow X/X_n, \text{where} X_n = 0.950456
|
||||
|
||||
.. math::
|
||||
|
||||
Z \leftarrow Z/Z_n, \text{where} Z_n = 1.088754
|
||||
|
||||
.. math::
|
||||
|
||||
L \leftarrow \fork{116*Y^{1/3}-16}{for $Y>0.008856$}{903.3*Y}{for $Y \le 0.008856$}
|
||||
|
||||
.. math::
|
||||
|
||||
a \leftarrow 500 (f(X)-f(Y)) + delta
|
||||
|
||||
.. math::
|
||||
|
||||
b \leftarrow 200 (f(Y)-f(Z)) + delta
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
f(t)= \fork{t^{1/3}}{for $t>0.008856$}{7.787 t+16/116}{for $t\leq 0.008856$}
|
||||
|
||||
and
|
||||
|
||||
.. math::
|
||||
|
||||
delta = \fork{128}{for 8-bit images}{0}{for floating-point images}
|
||||
|
||||
This outputs
|
||||
:math:`0 \leq L \leq 100`, :math:`-127 \leq a \leq 127`, :math:`-127 \leq b \leq 127` . The values are then converted to the destination data type:
|
||||
|
||||
* 8-bit images
|
||||
|
||||
.. math::
|
||||
|
||||
L \leftarrow L*255/100, \; a \leftarrow a + 128, \; b \leftarrow b + 128
|
||||
|
||||
* 16-bit images
|
||||
(currently not supported)
|
||||
|
||||
* 32-bit images
|
||||
L, a, and b are left as is
|
||||
|
||||
*
|
||||
RGB :math:`\leftrightarrow` CIE L*u*v* ( ``COLOR_BGR2Luv, COLOR_RGB2Luv, COLOR_Luv2BGR, COLOR_Luv2RGB`` ).
|
||||
In case of 8-bit and 16-bit images,
|
||||
R, G, and B are converted to the floating-point format and scaled to fit 0 to 1 range.
|
||||
|
||||
.. math::
|
||||
|
||||
\vecthree{X}{Y}{Z} \leftarrow \vecthreethree{0.412453}{0.357580}{0.180423}{0.212671}{0.715160}{0.072169}{0.019334}{0.119193}{0.950227} \cdot \vecthree{R}{G}{B}
|
||||
|
||||
.. math::
|
||||
|
||||
L \leftarrow \fork{116 Y^{1/3}}{for $Y>0.008856$}{903.3 Y}{for $Y\leq 0.008856$}
|
||||
|
||||
.. math::
|
||||
|
||||
u' \leftarrow 4*X/(X + 15*Y + 3 Z)
|
||||
|
||||
.. math::
|
||||
|
||||
v' \leftarrow 9*Y/(X + 15*Y + 3 Z)
|
||||
|
||||
.. math::
|
||||
|
||||
u \leftarrow 13*L*(u' - u_n) \quad \text{where} \quad u_n=0.19793943
|
||||
|
||||
.. math::
|
||||
|
||||
v \leftarrow 13*L*(v' - v_n) \quad \text{where} \quad v_n=0.46831096
|
||||
|
||||
This outputs
|
||||
:math:`0 \leq L \leq 100`, :math:`-134 \leq u \leq 220`, :math:`-140 \leq v \leq 122` .
|
||||
|
||||
The values are then converted to the destination data type:
|
||||
|
||||
* 8-bit images
|
||||
|
||||
.. math::
|
||||
|
||||
L \leftarrow 255/100 L, \; u \leftarrow 255/354 (u + 134), \; v \leftarrow 255/262 (v + 140)
|
||||
|
||||
* 16-bit images
|
||||
(currently not supported)
|
||||
|
||||
* 32-bit images
|
||||
L, u, and v are left as is
|
||||
|
||||
The above formulae for converting RGB to/from various color spaces have been taken from multiple sources on the web, primarily from the Charles Poynton site
|
||||
http://www.poynton.com/ColorFAQ.html
|
||||
|
||||
*
|
||||
Bayer :math:`\rightarrow` RGB ( ``COLOR_BayerBG2BGR, COLOR_BayerGB2BGR, COLOR_BayerRG2BGR, COLOR_BayerGR2BGR, COLOR_BayerBG2RGB, COLOR_BayerGB2RGB, COLOR_BayerRG2RGB, COLOR_BayerGR2RGB`` ). The Bayer pattern is widely used in CCD and CMOS cameras. It enables you to get color pictures from a single plane where R,G, and B pixels (sensors of a particular component) are interleaved as follows:
|
||||
|
||||
.. image:: pics/bayer.png
|
||||
|
||||
The output RGB components of a pixel are interpolated from 1, 2, or
|
||||
4 neighbors of the pixel having the same color. There are several
|
||||
modifications of the above pattern that can be achieved by shifting
|
||||
the pattern one pixel left and/or one pixel up. The two letters
|
||||
:math:`C_1` and
|
||||
:math:`C_2` in the conversion constants ``CV_Bayer`` :math:`C_1 C_2` ``2BGR`` and ``CV_Bayer`` :math:`C_1 C_2` ``2RGB`` indicate the particular pattern
|
||||
type. These are components from the second row, second and third
|
||||
columns, respectively. For example, the above pattern has a very
|
||||
popular "BG" type.
|
||||
|
||||
|
||||
distanceTransform
|
||||
-----------------
|
||||
Calculates the distance to the closest zero pixel for each pixel of the source image.
|
||||
|
||||
.. ocv:function:: void distanceTransform( InputArray src, OutputArray dst, int distanceType, int maskSize, int dstType=CV_32F )
|
||||
|
||||
.. ocv:function:: void distanceTransform( InputArray src, OutputArray dst, OutputArray labels, int distanceType, int maskSize, int labelType=DIST_LABEL_CCOMP )
|
||||
|
||||
.. ocv:pyfunction:: cv2.distanceTransform(src, distanceType, maskSize[, dst]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvDistTransform( const CvArr* src, CvArr* dst, int distance_type=CV_DIST_L2, int mask_size=3, const float* mask=NULL, CvArr* labels=NULL, int labelType=CV_DIST_LABEL_CCOMP )
|
||||
|
||||
:param src: 8-bit, single-channel (binary) source image.
|
||||
|
||||
:param dst: Output image with calculated distances. It is a 8-bit or 32-bit floating-point, single-channel image of the same size as ``src`` .
|
||||
|
||||
:param distanceType: Type of distance. It can be ``CV_DIST_L1, CV_DIST_L2`` , or ``CV_DIST_C`` .
|
||||
|
||||
:param maskSize: Size of the distance transform mask. It can be 3, 5, or ``CV_DIST_MASK_PRECISE`` (the latter option is only supported by the first function). In case of the ``CV_DIST_L1`` or ``CV_DIST_C`` distance type, the parameter is forced to 3 because a :math:`3\times 3` mask gives the same result as :math:`5\times 5` or any larger aperture.
|
||||
|
||||
:param dstType: Type of output image. It can be ``CV_8U`` or ``CV_32F``. Type ``CV_8U`` can be used only for the first variant of the function and ``distanceType == CV_DIST_L1``.
|
||||
|
||||
:param labels: Optional output 2D array of labels (the discrete Voronoi diagram). It has the type ``CV_32SC1`` and the same size as ``src`` . See the details below.
|
||||
|
||||
:param labelType: Type of the label array to build. If ``labelType==DIST_LABEL_CCOMP`` then each connected component of zeros in ``src`` (as well as all the non-zero pixels closest to the connected component) will be assigned the same label. If ``labelType==DIST_LABEL_PIXEL`` then each zero pixel (and all the non-zero pixels closest to it) gets its own label.
|
||||
|
||||
The functions ``distanceTransform`` calculate the approximate or precise
|
||||
distance from every binary image pixel to the nearest zero pixel.
|
||||
For zero image pixels, the distance will obviously be zero.
|
||||
|
||||
When ``maskSize == CV_DIST_MASK_PRECISE`` and ``distanceType == CV_DIST_L2`` , the function runs the algorithm described in [Felzenszwalb04]_. This algorithm is parallelized with the TBB library.
|
||||
|
||||
In other cases, the algorithm
|
||||
[Borgefors86]_
|
||||
is used. This means that
|
||||
for a pixel the function finds the shortest path to the nearest zero pixel
|
||||
consisting of basic shifts: horizontal,
|
||||
vertical, diagonal, or knight's move (the latest is available for a
|
||||
:math:`5\times 5` mask). The overall distance is calculated as a sum of these
|
||||
basic distances. Since the distance function should be symmetric,
|
||||
all of the horizontal and vertical shifts must have the same cost (denoted as ``a`` ), all the diagonal shifts must have the
|
||||
same cost (denoted as ``b`` ), and all knight's moves must have
|
||||
the same cost (denoted as ``c`` ). For the ``CV_DIST_C`` and ``CV_DIST_L1`` types, the distance is calculated precisely,
|
||||
whereas for ``CV_DIST_L2`` (Euclidean distance) the distance
|
||||
can be calculated only with a relative error (a
|
||||
:math:`5\times 5` mask
|
||||
gives more accurate results). For ``a``,``b`` , and ``c`` , OpenCV uses the values suggested in the original paper:
|
||||
|
||||
.. table::
|
||||
|
||||
============== =================== ======================
|
||||
``CV_DIST_C`` :math:`(3\times 3)` a = 1, b = 1 \
|
||||
============== =================== ======================
|
||||
``CV_DIST_L1`` :math:`(3\times 3)` a = 1, b = 2 \
|
||||
``CV_DIST_L2`` :math:`(3\times 3)` a=0.955, b=1.3693 \
|
||||
``CV_DIST_L2`` :math:`(5\times 5)` a=1, b=1.4, c=2.1969 \
|
||||
============== =================== ======================
|
||||
|
||||
Typically, for a fast, coarse distance estimation ``CV_DIST_L2``, a
|
||||
:math:`3\times 3` mask is used. For a more accurate distance estimation ``CV_DIST_L2`` , a
|
||||
:math:`5\times 5` mask or the precise algorithm is used.
|
||||
Note that both the precise and the approximate algorithms are linear on the number of pixels.
|
||||
|
||||
The second variant of the function does not only compute the minimum distance for each pixel
|
||||
:math:`(x, y)` but also identifies the nearest connected
|
||||
component consisting of zero pixels (``labelType==DIST_LABEL_CCOMP``) or the nearest zero pixel (``labelType==DIST_LABEL_PIXEL``). Index of the component/pixel is stored in
|
||||
:math:`\texttt{labels}(x, y)` .
|
||||
When ``labelType==DIST_LABEL_CCOMP``, the function automatically finds connected components of zero pixels in the input image and marks them with distinct labels. When ``labelType==DIST_LABEL_CCOMP``, the function scans through the input image and marks all the zero pixels with distinct labels.
|
||||
|
||||
In this mode, the complexity is still linear.
|
||||
That is, the function provides a very fast way to compute the Voronoi diagram for a binary image.
|
||||
Currently, the second variant can use only the approximate distance transform algorithm, i.e. ``maskSize=CV_DIST_MASK_PRECISE`` is not supported yet.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example on using the distance transform can be found at opencv_source_code/samples/cpp/distrans.cpp
|
||||
|
||||
* (Python) An example on using the distance transform can be found at opencv_source/samples/python2/distrans.py
|
||||
|
||||
floodFill
|
||||
---------
|
||||
Fills a connected component with the given color.
|
||||
|
||||
.. ocv:function:: int floodFill( InputOutputArray image, Point seedPoint, Scalar newVal, Rect* rect=0, Scalar loDiff=Scalar(), Scalar upDiff=Scalar(), int flags=4 )
|
||||
|
||||
.. ocv:function:: int floodFill( InputOutputArray image, InputOutputArray mask, Point seedPoint, Scalar newVal, Rect* rect=0, Scalar loDiff=Scalar(), Scalar upDiff=Scalar(), int flags=4 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.floodFill(image, mask, seedPoint, newVal[, loDiff[, upDiff[, flags]]]) -> retval, image, mask, rect
|
||||
|
||||
.. ocv:cfunction:: void cvFloodFill( CvArr* image, CvPoint seed_point, CvScalar new_val, CvScalar lo_diff=cvScalarAll(0), CvScalar up_diff=cvScalarAll(0), CvConnectedComp* comp=NULL, int flags=4, CvArr* mask=NULL )
|
||||
|
||||
:param image: Input/output 1- or 3-channel, 8-bit, or floating-point image. It is modified by the function unless the ``FLOODFILL_MASK_ONLY`` flag is set in the second variant of the function. See the details below.
|
||||
|
||||
:param mask: Operation mask that should be a single-channel 8-bit image, 2 pixels wider and 2 pixels taller than ``image``. Since this is both an input and output parameter, you must take responsibility of initializing it. Flood-filling cannot go across non-zero pixels in the input mask. For example, an edge detector output can be used as a mask to stop filling at edges. On output, pixels in the mask corresponding to filled pixels in the image are set to 1 or to the a value specified in ``flags`` as described below. It is therefore possible to use the same mask in multiple calls to the function to make sure the filled areas do not overlap.
|
||||
|
||||
.. note:: Since the mask is larger than the filled image, a pixel :math:`(x, y)` in ``image`` corresponds to the pixel :math:`(x+1, y+1)` in the ``mask`` .
|
||||
|
||||
:param seedPoint: Starting point.
|
||||
|
||||
:param newVal: New value of the repainted domain pixels.
|
||||
|
||||
:param loDiff: Maximal lower brightness/color difference between the currently observed pixel and one of its neighbors belonging to the component, or a seed pixel being added to the component.
|
||||
|
||||
:param upDiff: Maximal upper brightness/color difference between the currently observed pixel and one of its neighbors belonging to the component, or a seed pixel being added to the component.
|
||||
|
||||
:param rect: Optional output parameter set by the function to the minimum bounding rectangle of the repainted domain.
|
||||
|
||||
:param flags: Operation flags. The first 8 bits contain a connectivity value. The default value of 4 means that only the four nearest neighbor pixels (those that share an edge) are considered. A connectivity value of 8 means that the eight nearest neighbor pixels (those that share a corner) will be considered. The next 8 bits (8-16) contain a value between 1 and 255 with which to fill the ``mask`` (the default value is 1). For example, ``4 | ( 255 << 8 )`` will consider 4 nearest neighbours and fill the mask with a value of 255. The following additional options occupy higher bits and therefore may be further combined with the connectivity and mask fill values using bit-wise or (``|``):
|
||||
|
||||
* **FLOODFILL_FIXED_RANGE** If set, the difference between the current pixel and seed pixel is considered. Otherwise, the difference between neighbor pixels is considered (that is, the range is floating).
|
||||
|
||||
* **FLOODFILL_MASK_ONLY** If set, the function does not change the image ( ``newVal`` is ignored), and only fills the mask with the value specified in bits 8-16 of ``flags`` as described above. This option only make sense in function variants that have the ``mask`` parameter.
|
||||
|
||||
The functions ``floodFill`` fill a connected component starting from the seed point with the specified color. The connectivity is determined by the color/brightness closeness of the neighbor pixels. The pixel at
|
||||
:math:`(x,y)` is considered to belong to the repainted domain if:
|
||||
|
||||
*
|
||||
.. math::
|
||||
|
||||
\texttt{src} (x',y')- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} (x',y')+ \texttt{upDiff}
|
||||
|
||||
in case of a grayscale image and floating range
|
||||
|
||||
*
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)- \texttt{loDiff} \leq \texttt{src} (x,y) \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)+ \texttt{upDiff}
|
||||
|
||||
in case of a grayscale image and fixed range
|
||||
|
||||
*
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{src} (x',y')_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} (x',y')_r+ \texttt{upDiff} _r,
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{src} (x',y')_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} (x',y')_g+ \texttt{upDiff} _g
|
||||
|
||||
and
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{src} (x',y')_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} (x',y')_b+ \texttt{upDiff} _b
|
||||
|
||||
in case of a color image and floating range
|
||||
|
||||
|
||||
*
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_r- \texttt{loDiff} _r \leq \texttt{src} (x,y)_r \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_r+ \texttt{upDiff} _r,
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_g- \texttt{loDiff} _g \leq \texttt{src} (x,y)_g \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_g+ \texttt{upDiff} _g
|
||||
|
||||
and
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_b- \texttt{loDiff} _b \leq \texttt{src} (x,y)_b \leq \texttt{src} ( \texttt{seedPoint} .x, \texttt{seedPoint} .y)_b+ \texttt{upDiff} _b
|
||||
|
||||
in case of a color image and fixed range
|
||||
|
||||
where
|
||||
:math:`src(x',y')` is the value of one of pixel neighbors that is already known to belong to the component. That is, to be added to the connected component, a color/brightness of the pixel should be close enough to:
|
||||
|
||||
*
|
||||
Color/brightness of one of its neighbors that already belong to the connected component in case of a floating range.
|
||||
|
||||
*
|
||||
Color/brightness of the seed point in case of a fixed range.
|
||||
|
||||
Use these functions to either mark a connected component with the specified color in-place, or build a mask and then extract the contour, or copy the region to another image, and so on.
|
||||
|
||||
.. seealso:: :ocv:func:`findContours`
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the FloodFill technique can be found at opencv_source_code/samples/cpp/ffilldemo.cpp
|
||||
|
||||
* (Python) An example using the FloodFill technique can be found at opencv_source_code/samples/python2/floodfill.cpp
|
||||
|
||||
integral
|
||||
--------
|
||||
Calculates the integral of an image.
|
||||
|
||||
.. ocv:function:: void integral( InputArray src, OutputArray sum, int sdepth=-1 )
|
||||
|
||||
.. ocv:function:: void integral( InputArray src, OutputArray sum, OutputArray sqsum, int sdepth=-1, int sqdepth=-1 )
|
||||
|
||||
.. ocv:function:: void integral( InputArray src, OutputArray sum, OutputArray sqsum, OutputArray tilted, int sdepth=-1, int sqdepth=-1 )
|
||||
|
||||
.. ocv:pyfunction:: cv2.integral(src[, sum[, sdepth]]) -> sum
|
||||
|
||||
.. ocv:pyfunction:: cv2.integral2(src[, sum[, sqsum[, sdepth[, sqdepth]]]]) -> sum, sqsum
|
||||
|
||||
.. ocv:pyfunction:: cv2.integral3(src[, sum[, sqsum[, tilted[, sdepth[, sqdepth]]]]]) -> sum, sqsum, tilted
|
||||
|
||||
.. ocv:cfunction:: void cvIntegral( const CvArr* image, CvArr* sum, CvArr* sqsum=NULL, CvArr* tilted_sum=NULL )
|
||||
|
||||
:param image: input image as :math:`W \times H`, 8-bit or floating-point (32f or 64f).
|
||||
|
||||
:param sum: integral image as :math:`(W+1)\times (H+1)` , 32-bit integer or floating-point (32f or 64f).
|
||||
|
||||
:param sqsum: integral image for squared pixel values; it is :math:`(W+1)\times (H+1)`, double-precision floating-point (64f) array.
|
||||
|
||||
:param tilted: integral for the image rotated by 45 degrees; it is :math:`(W+1)\times (H+1)` array with the same data type as ``sum``.
|
||||
|
||||
:param sdepth: desired depth of the integral and the tilted integral images, ``CV_32S``, ``CV_32F``, or ``CV_64F``.
|
||||
|
||||
:param sqdepth: desired depth of the integral image of squared pixel values, ``CV_32F`` or ``CV_64F``.
|
||||
|
||||
The functions calculate one or more integral images for the source image as follows:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{sum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{sqsum} (X,Y) = \sum _{x<X,y<Y} \texttt{image} (x,y)^2
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{tilted} (X,Y) = \sum _{y<Y,abs(x-X+1) \leq Y-y-1} \texttt{image} (x,y)
|
||||
|
||||
Using these integral images, you can calculate sum, mean, and standard deviation over a specific up-right or rotated rectangular region of the image in a constant time, for example:
|
||||
|
||||
.. math::
|
||||
|
||||
\sum _{x_1 \leq x < x_2, \, y_1 \leq y < y_2} \texttt{image} (x,y) = \texttt{sum} (x_2,y_2)- \texttt{sum} (x_1,y_2)- \texttt{sum} (x_2,y_1)+ \texttt{sum} (x_1,y_1)
|
||||
|
||||
It makes possible to do a fast blurring or fast block correlation with a variable window size, for example. In case of multi-channel images, sums for each channel are accumulated independently.
|
||||
|
||||
As a practical example, the next figure shows the calculation of the integral of a straight rectangle ``Rect(3,3,3,2)`` and of a tilted rectangle ``Rect(5,1,2,3)`` . The selected pixels in the original ``image`` are shown, as well as the relative pixels in the integral images ``sum`` and ``tilted`` .
|
||||
|
||||
.. image:: pics/integral.png
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
threshold
|
||||
---------
|
||||
Applies a fixed-level threshold to each array element.
|
||||
|
||||
.. ocv:function:: double threshold( InputArray src, OutputArray dst, double thresh, double maxval, int type )
|
||||
|
||||
.. ocv:pyfunction:: cv2.threshold(src, thresh, maxval, type[, dst]) -> retval, dst
|
||||
|
||||
.. ocv:cfunction:: double cvThreshold( const CvArr* src, CvArr* dst, double threshold, double max_value, int threshold_type )
|
||||
|
||||
:param src: input array (single-channel, 8-bit or 32-bit floating point).
|
||||
|
||||
:param dst: output array of the same size and type as ``src``.
|
||||
|
||||
:param thresh: threshold value.
|
||||
|
||||
:param maxval: maximum value to use with the ``THRESH_BINARY`` and ``THRESH_BINARY_INV`` thresholding types.
|
||||
|
||||
:param type: thresholding type (see the details below).
|
||||
|
||||
The function applies fixed-level thresholding
|
||||
to a single-channel array. The function is typically used to get a
|
||||
bi-level (binary) image out of a grayscale image (
|
||||
:ocv:func:`compare` could
|
||||
be also used for this purpose) or for removing a noise, that is, filtering
|
||||
out pixels with too small or too large values. There are several
|
||||
types of thresholding supported by the function. They are determined by ``type`` :
|
||||
|
||||
* **THRESH_BINARY**
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \fork{\texttt{maxval}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise}
|
||||
|
||||
* **THRESH_BINARY_INV**
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{maxval}}{otherwise}
|
||||
|
||||
* **THRESH_TRUNC**
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \fork{\texttt{threshold}}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise}
|
||||
|
||||
* **THRESH_TOZERO**
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \fork{\texttt{src}(x,y)}{if $\texttt{src}(x,y) > \texttt{thresh}$}{0}{otherwise}
|
||||
|
||||
* **THRESH_TOZERO_INV**
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) = \fork{0}{if $\texttt{src}(x,y) > \texttt{thresh}$}{\texttt{src}(x,y)}{otherwise}
|
||||
|
||||
Also, the special values ``THRESH_OTSU`` or ``THRESH_TRIANGLE`` may be combined with
|
||||
one of the above values. In these cases, the function determines the optimal threshold
|
||||
value using the Otsu's or Triangle algorithm and uses it instead of the specified ``thresh`` .
|
||||
The function returns the computed threshold value.
|
||||
Currently, the Otsu's and Triangle methods are implemented only for 8-bit images.
|
||||
|
||||
|
||||
.. image:: pics/threshold.png
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`adaptiveThreshold`,
|
||||
:ocv:func:`findContours`,
|
||||
:ocv:func:`compare`,
|
||||
:ocv:func:`min`,
|
||||
:ocv:func:`max`
|
||||
|
||||
|
||||
watershed
|
||||
---------
|
||||
Performs a marker-based image segmentation using the watershed algorithm.
|
||||
|
||||
.. ocv:function:: void watershed( InputArray image, InputOutputArray markers )
|
||||
|
||||
.. ocv:cfunction:: void cvWatershed( const CvArr* image, CvArr* markers )
|
||||
|
||||
.. ocv:pyfunction:: cv2.watershed(image, markers) -> markers
|
||||
|
||||
:param image: Input 8-bit 3-channel image.
|
||||
|
||||
:param markers: Input/output 32-bit single-channel image (map) of markers. It should have the same size as ``image`` .
|
||||
|
||||
The function implements one of the variants of watershed, non-parametric marker-based segmentation algorithm, described in [Meyer92]_.
|
||||
|
||||
Before passing the image to the function, you have to roughly outline the desired regions in the image ``markers`` with positive (``>0``) indices. So, every region is represented as one or more connected components with the pixel values 1, 2, 3, and so on. Such markers can be retrieved from a binary mask using :ocv:func:`findContours` and :ocv:func:`drawContours` (see the ``watershed.cpp`` demo). The markers are "seeds" of the future image regions. All the other pixels in ``markers`` , whose relation to the outlined regions is not known and should be defined by the algorithm, should be set to 0's. In the function output, each pixel in markers is set to a value of the "seed" components or to -1 at boundaries between the regions.
|
||||
|
||||
Visual demonstration and usage example of the function can be found in the OpenCV samples directory (see the ``watershed.cpp`` demo).
|
||||
|
||||
.. note:: Any two neighbor connected components are not necessarily separated by a watershed boundary (-1's pixels); for example, they can touch each other in the initial marker image passed to the function.
|
||||
|
||||
.. seealso:: :ocv:func:`findContours`
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the watershed algorithm can be found at opencv_source_code/samples/cpp/watershed.cpp
|
||||
|
||||
* (Python) An example using the watershed algorithm can be found at opencv_source_code/samples/python2/watershed.py
|
||||
|
||||
grabCut
|
||||
-------
|
||||
Runs the GrabCut algorithm.
|
||||
|
||||
.. ocv:function:: void grabCut( InputArray img, InputOutputArray mask, Rect rect, InputOutputArray bgdModel, InputOutputArray fgdModel, int iterCount, int mode=GC_EVAL )
|
||||
|
||||
.. ocv:pyfunction:: cv2.grabCut(img, mask, rect, bgdModel, fgdModel, iterCount[, mode]) -> mask, bgdModel, fgdModel
|
||||
|
||||
:param img: Input 8-bit 3-channel image.
|
||||
|
||||
:param mask: Input/output 8-bit single-channel mask. The mask is initialized by the function when ``mode`` is set to ``GC_INIT_WITH_RECT``. Its elements may have one of following values:
|
||||
|
||||
* **GC_BGD** defines an obvious background pixels.
|
||||
|
||||
* **GC_FGD** defines an obvious foreground (object) pixel.
|
||||
|
||||
* **GC_PR_BGD** defines a possible background pixel.
|
||||
|
||||
* **GC_PR_FGD** defines a possible foreground pixel.
|
||||
|
||||
:param rect: ROI containing a segmented object. The pixels outside of the ROI are marked as "obvious background". The parameter is only used when ``mode==GC_INIT_WITH_RECT`` .
|
||||
|
||||
:param bgdModel: Temporary array for the background model. Do not modify it while you are processing the same image.
|
||||
|
||||
:param fgdModel: Temporary arrays for the foreground model. Do not modify it while you are processing the same image.
|
||||
|
||||
:param iterCount: Number of iterations the algorithm should make before returning the result. Note that the result can be refined with further calls with ``mode==GC_INIT_WITH_MASK`` or ``mode==GC_EVAL`` .
|
||||
|
||||
:param mode: Operation mode that could be one of the following:
|
||||
|
||||
* **GC_INIT_WITH_RECT** The function initializes the state and the mask using the provided rectangle. After that it runs ``iterCount`` iterations of the algorithm.
|
||||
|
||||
* **GC_INIT_WITH_MASK** The function initializes the state using the provided mask. Note that ``GC_INIT_WITH_RECT`` and ``GC_INIT_WITH_MASK`` can be combined. Then, all the pixels outside of the ROI are automatically initialized with ``GC_BGD`` .
|
||||
|
||||
* **GC_EVAL** The value means that the algorithm should just resume.
|
||||
|
||||
The function implements the `GrabCut image segmentation algorithm <http://en.wikipedia.org/wiki/GrabCut>`_.
|
||||
See the sample ``grabcut.cpp`` to learn how to use the function.
|
||||
|
||||
.. [Borgefors86] Borgefors, Gunilla, *Distance transformations in digital images*. Comput. Vision Graph. Image Process. 34 3, pp 344–371 (1986)
|
||||
|
||||
.. [Felzenszwalb04] Felzenszwalb, Pedro F. and Huttenlocher, Daniel P. *Distance Transforms of Sampled Functions*, TR2004-1963, TR2004-1963 (2004)
|
||||
|
||||
.. [Meyer92] Meyer, F. *Color Image Segmentation*, ICIP92, 1992
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the GrabCut algorithm can be found at opencv_source_code/samples/cpp/grabcut.cpp
|
||||
|
||||
* (Python) An example using the GrabCut algorithm can be found at opencv_source_code/samples/python2/grabcut.py
|
||||
@@ -1,213 +0,0 @@
|
||||
Motion Analysis and Object Tracking
|
||||
===================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
accumulate
|
||||
--------------
|
||||
Adds an image to the accumulator.
|
||||
|
||||
.. ocv:function:: void accumulate( InputArray src, InputOutputArray dst, InputArray mask=noArray() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.accumulate(src, dst[, mask]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvAcc( const CvArr* image, CvArr* sum, const CvArr* mask=NULL )
|
||||
|
||||
:param src: Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
|
||||
|
||||
:param dst: Accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point.
|
||||
|
||||
:param mask: Optional operation mask.
|
||||
|
||||
The function adds ``src`` or some of its elements to ``dst`` :
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
|
||||
|
||||
The function supports multi-channel images. Each channel is processed independently.
|
||||
|
||||
The functions ``accumulate*`` can be used, for example, to collect statistics of a scene background viewed by a still camera and for the further foreground-background segmentation.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`accumulateSquare`,
|
||||
:ocv:func:`accumulateProduct`,
|
||||
:ocv:func:`accumulateWeighted`
|
||||
|
||||
|
||||
|
||||
accumulateSquare
|
||||
--------------------
|
||||
Adds the square of a source image to the accumulator.
|
||||
|
||||
.. ocv:function:: void accumulateSquare( InputArray src, InputOutputArray dst, InputArray mask=noArray() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.accumulateSquare(src, dst[, mask]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvSquareAcc( const CvArr* image, CvArr* sqsum, const CvArr* mask=NULL )
|
||||
|
||||
:param src: Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
|
||||
|
||||
:param dst: Accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point.
|
||||
|
||||
:param mask: Optional operation mask.
|
||||
|
||||
The function adds the input image ``src`` or its selected region, raised to a power of 2, to the accumulator ``dst`` :
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src} (x,y)^2 \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
|
||||
|
||||
The function supports multi-channel images. Each channel is processed independently.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`accumulateSquare`,
|
||||
:ocv:func:`accumulateProduct`,
|
||||
:ocv:func:`accumulateWeighted`
|
||||
|
||||
|
||||
|
||||
accumulateProduct
|
||||
---------------------
|
||||
Adds the per-element product of two input images to the accumulator.
|
||||
|
||||
.. ocv:function:: void accumulateProduct( InputArray src1, InputArray src2, InputOutputArray dst, InputArray mask=noArray() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.accumulateProduct(src1, src2, dst[, mask]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvMultiplyAcc( const CvArr* image1, const CvArr* image2, CvArr* acc, const CvArr* mask=NULL )
|
||||
|
||||
:param src1: First input image, 1- or 3-channel, 8-bit or 32-bit floating point.
|
||||
|
||||
:param src2: Second input image of the same type and the same size as ``src1`` .
|
||||
|
||||
:param dst: Accumulator with the same number of channels as input images, 32-bit or 64-bit floating-point.
|
||||
|
||||
:param mask: Optional operation mask.
|
||||
|
||||
The function adds the product of two images or their selected regions to the accumulator ``dst`` :
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) \leftarrow \texttt{dst} (x,y) + \texttt{src1} (x,y) \cdot \texttt{src2} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
|
||||
|
||||
The function supports multi-channel images. Each channel is processed independently.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`accumulate`,
|
||||
:ocv:func:`accumulateSquare`,
|
||||
:ocv:func:`accumulateWeighted`
|
||||
|
||||
|
||||
|
||||
accumulateWeighted
|
||||
----------------------
|
||||
Updates a running average.
|
||||
|
||||
.. ocv:function:: void accumulateWeighted( InputArray src, InputOutputArray dst, double alpha, InputArray mask=noArray() )
|
||||
|
||||
.. ocv:pyfunction:: cv2.accumulateWeighted(src, dst, alpha[, mask]) -> dst
|
||||
|
||||
.. ocv:cfunction:: void cvRunningAvg( const CvArr* image, CvArr* acc, double alpha, const CvArr* mask=NULL )
|
||||
|
||||
:param src: Input image as 1- or 3-channel, 8-bit or 32-bit floating point.
|
||||
|
||||
:param dst: Accumulator image with the same number of channels as input image, 32-bit or 64-bit floating-point.
|
||||
|
||||
:param alpha: Weight of the input image.
|
||||
|
||||
:param mask: Optional operation mask.
|
||||
|
||||
The function calculates the weighted sum of the input image ``src`` and the accumulator ``dst`` so that ``dst`` becomes a running average of a frame sequence:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{dst} (x,y) \leftarrow (1- \texttt{alpha} ) \cdot \texttt{dst} (x,y) + \texttt{alpha} \cdot \texttt{src} (x,y) \quad \text{if} \quad \texttt{mask} (x,y) \ne 0
|
||||
|
||||
That is, ``alpha`` regulates the update speed (how fast the accumulator "forgets" about earlier images).
|
||||
The function supports multi-channel images. Each channel is processed independently.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`accumulate`,
|
||||
:ocv:func:`accumulateSquare`,
|
||||
:ocv:func:`accumulateProduct`
|
||||
|
||||
|
||||
|
||||
phaseCorrelate
|
||||
--------------
|
||||
The function is used to detect translational shifts that occur between two images. The operation takes advantage of the Fourier shift theorem for detecting the translational shift in the frequency domain. It can be used for fast image registration as well as motion estimation. For more information please see http://en.wikipedia.org/wiki/Phase\_correlation .
|
||||
|
||||
Calculates the cross-power spectrum of two supplied source arrays. The arrays are padded if needed with :ocv:func:`getOptimalDFTSize`.
|
||||
|
||||
.. ocv:function:: Point2d phaseCorrelate(InputArray src1, InputArray src2, InputArray window = noArray(), double* response = 0)
|
||||
|
||||
:param src1: Source floating point array (CV_32FC1 or CV_64FC1)
|
||||
:param src2: Source floating point array (CV_32FC1 or CV_64FC1)
|
||||
:param window: Floating point array with windowing coefficients to reduce edge effects (optional).
|
||||
:param response: Signal power within the 5x5 centroid around the peak, between 0 and 1 (optional).
|
||||
|
||||
Return value: detected phase shift (sub-pixel) between the two arrays.
|
||||
|
||||
The function performs the following equations
|
||||
|
||||
* First it applies a Hanning window (see http://en.wikipedia.org/wiki/Hann\_function) to each image to remove possible edge effects. This window is cached until the array size changes to speed up processing time.
|
||||
|
||||
* Next it computes the forward DFTs of each source array:
|
||||
|
||||
.. math::
|
||||
|
||||
\mathbf{G}_a = \mathcal{F}\{src_1\}, \; \mathbf{G}_b = \mathcal{F}\{src_2\}
|
||||
|
||||
where
|
||||
:math:`\mathcal{F}` is the forward DFT.
|
||||
|
||||
* It then computes the cross-power spectrum of each frequency domain array:
|
||||
|
||||
.. math::
|
||||
|
||||
R = \frac{ \mathbf{G}_a \mathbf{G}_b^*}{|\mathbf{G}_a \mathbf{G}_b^*|}
|
||||
|
||||
* Next the cross-correlation is converted back into the time domain via the inverse DFT:
|
||||
|
||||
.. math::
|
||||
|
||||
r = \mathcal{F}^{-1}\{R\}
|
||||
|
||||
* Finally, it computes the peak location and computes a 5x5 weighted centroid around the peak to achieve sub-pixel accuracy.
|
||||
|
||||
.. math::
|
||||
|
||||
(\Delta x, \Delta y) = \texttt{weightedCentroid} \{\arg \max_{(x, y)}\{r\}\}
|
||||
|
||||
* If non-zero, the response parameter is computed as the sum of the elements of r within the 5x5 centroid around the peak location. It is normalized to a maximum of 1 (meaning there is a single peak) and will be smaller when there are multiple peaks.
|
||||
|
||||
.. seealso::
|
||||
:ocv:func:`dft`,
|
||||
:ocv:func:`getOptimalDFTSize`,
|
||||
:ocv:func:`idft`,
|
||||
:ocv:func:`mulSpectrums`
|
||||
:ocv:func:`createHanningWindow`
|
||||
|
||||
createHanningWindow
|
||||
-------------------------------
|
||||
This function computes a Hanning window coefficients in two dimensions. See http://en.wikipedia.org/wiki/Hann\_function and http://en.wikipedia.org/wiki/Window\_function for more information.
|
||||
|
||||
.. ocv:function:: void createHanningWindow(OutputArray dst, Size winSize, int type)
|
||||
|
||||
:param dst: Destination array to place Hann coefficients in
|
||||
:param winSize: The window size specifications
|
||||
:param type: Created array type
|
||||
|
||||
An example is shown below: ::
|
||||
|
||||
// create hanning window of size 100x100 and type CV_32F
|
||||
Mat hann;
|
||||
createHanningWindow(hann, Size(100, 100), CV_32F);
|
||||
|
||||
.. seealso::
|
||||
:ocv:func:`phaseCorrelate`
|
||||
@@ -1,79 +0,0 @@
|
||||
Object Detection
|
||||
================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
matchTemplate
|
||||
-----------------
|
||||
Compares a template against overlapped image regions.
|
||||
|
||||
.. ocv:function:: void matchTemplate( InputArray image, InputArray templ, OutputArray result, int method )
|
||||
|
||||
.. ocv:pyfunction:: cv2.matchTemplate(image, templ, method[, result]) -> result
|
||||
|
||||
.. ocv:cfunction:: void cvMatchTemplate( const CvArr* image, const CvArr* templ, CvArr* result, int method )
|
||||
|
||||
:param image: Image where the search is running. It must be 8-bit or 32-bit floating-point.
|
||||
|
||||
:param templ: Searched template. It must be not greater than the source image and have the same data type.
|
||||
|
||||
:param result: Map of comparison results. It must be single-channel 32-bit floating-point. If ``image`` is :math:`W \times H` and ``templ`` is :math:`w \times h` , then ``result`` is :math:`(W-w+1) \times (H-h+1)` .
|
||||
|
||||
:param method: Parameter specifying the comparison method (see below).
|
||||
|
||||
The function slides through ``image`` , compares the
|
||||
overlapped patches of size
|
||||
:math:`w \times h` against ``templ`` using the specified method and stores the comparison results in ``result`` . Here are the formulae for the available comparison
|
||||
methods (
|
||||
:math:`I` denotes ``image``, :math:`T` ``template``, :math:`R` ``result`` ). The summation is done over template and/or the
|
||||
image patch:
|
||||
:math:`x' = 0...w-1, y' = 0...h-1`
|
||||
|
||||
* method=CV\_TM\_SQDIFF
|
||||
|
||||
.. math::
|
||||
|
||||
R(x,y)= \sum _{x',y'} (T(x',y')-I(x+x',y+y'))^2
|
||||
|
||||
* method=CV\_TM\_SQDIFF\_NORMED
|
||||
|
||||
.. math::
|
||||
|
||||
R(x,y)= \frac{\sum_{x',y'} (T(x',y')-I(x+x',y+y'))^2}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
|
||||
|
||||
* method=CV\_TM\_CCORR
|
||||
|
||||
.. math::
|
||||
|
||||
R(x,y)= \sum _{x',y'} (T(x',y') \cdot I(x+x',y+y'))
|
||||
|
||||
* method=CV\_TM\_CCORR\_NORMED
|
||||
|
||||
.. math::
|
||||
|
||||
R(x,y)= \frac{\sum_{x',y'} (T(x',y') \cdot I(x+x',y+y'))}{\sqrt{\sum_{x',y'}T(x',y')^2 \cdot \sum_{x',y'} I(x+x',y+y')^2}}
|
||||
|
||||
* method=CV\_TM\_CCOEFF
|
||||
|
||||
.. math::
|
||||
|
||||
R(x,y)= \sum _{x',y'} (T'(x',y') \cdot I'(x+x',y+y'))
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{array}{l} T'(x',y')=T(x',y') - 1/(w \cdot h) \cdot \sum _{x'',y''} T(x'',y'') \\ I'(x+x',y+y')=I(x+x',y+y') - 1/(w \cdot h) \cdot \sum _{x'',y''} I(x+x'',y+y'') \end{array}
|
||||
|
||||
* method=CV\_TM\_CCOEFF\_NORMED
|
||||
|
||||
.. math::
|
||||
|
||||
R(x,y)= \frac{ \sum_{x',y'} (T'(x',y') \cdot I'(x+x',y+y')) }{ \sqrt{\sum_{x',y'}T'(x',y')^2 \cdot \sum_{x',y'} I'(x+x',y+y')^2} }
|
||||
|
||||
After the function finishes the comparison, the best matches can be found as global minimums (when ``CV_TM_SQDIFF`` was used) or maximums (when ``CV_TM_CCORR`` or ``CV_TM_CCOEFF`` was used) using the
|
||||
:ocv:func:`minMaxLoc` function. In case of a color image, template summation in the numerator and each sum in the denominator is done over all of the channels and separate mean values are used for each channel. That is, the function can take a color template and a color image. The result will still be a single-channel image, which is easier to analyze.
|
||||
|
||||
.. note::
|
||||
|
||||
* (Python) An example on how to match mouse selected regions in an image can be found at opencv_source_code/samples/python2/mouse_and_match.py
|
||||
@@ -1,746 +0,0 @@
|
||||
Structural Analysis and Shape Descriptors
|
||||
=========================================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
moments
|
||||
-----------
|
||||
Calculates all of the moments up to the third order of a polygon or rasterized shape.
|
||||
|
||||
.. ocv:function:: Moments moments( InputArray array, bool binaryImage=false )
|
||||
|
||||
.. ocv:pyfunction:: cv2.moments(array[, binaryImage]) -> retval
|
||||
|
||||
.. ocv:cfunction:: void cvMoments( const CvArr* arr, CvMoments* moments, int binary=0 )
|
||||
|
||||
:param array: Raster image (single-channel, 8-bit or floating-point 2D array) or an array ( :math:`1 \times N` or :math:`N \times 1` ) of 2D points (``Point`` or ``Point2f`` ).
|
||||
|
||||
:param binaryImage: If it is true, all non-zero image pixels are treated as 1's. The parameter is used for images only.
|
||||
|
||||
:param moments: Output moments.
|
||||
|
||||
The function computes moments, up to the 3rd order, of a vector shape or a rasterized shape. The results are returned in the structure ``Moments`` defined as: ::
|
||||
|
||||
class Moments
|
||||
{
|
||||
public:
|
||||
Moments();
|
||||
Moments(double m00, double m10, double m01, double m20, double m11,
|
||||
double m02, double m30, double m21, double m12, double m03 );
|
||||
Moments( const CvMoments& moments );
|
||||
operator CvMoments() const;
|
||||
|
||||
// spatial moments
|
||||
double m00, m10, m01, m20, m11, m02, m30, m21, m12, m03;
|
||||
// central moments
|
||||
double mu20, mu11, mu02, mu30, mu21, mu12, mu03;
|
||||
// central normalized moments
|
||||
double nu20, nu11, nu02, nu30, nu21, nu12, nu03;
|
||||
}
|
||||
|
||||
In case of a raster image, the spatial moments :math:`\texttt{Moments::m}_{ji}` are computed as:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{m} _{ji}= \sum _{x,y} \left ( \texttt{array} (x,y) \cdot x^j \cdot y^i \right )
|
||||
|
||||
The central moments
|
||||
:math:`\texttt{Moments::mu}_{ji}` are computed as:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{mu} _{ji}= \sum _{x,y} \left ( \texttt{array} (x,y) \cdot (x - \bar{x} )^j \cdot (y - \bar{y} )^i \right )
|
||||
|
||||
where
|
||||
:math:`(\bar{x}, \bar{y})` is the mass center:
|
||||
|
||||
.. math::
|
||||
|
||||
\bar{x} = \frac{\texttt{m}_{10}}{\texttt{m}_{00}} , \; \bar{y} = \frac{\texttt{m}_{01}}{\texttt{m}_{00}}
|
||||
|
||||
The normalized central moments
|
||||
:math:`\texttt{Moments::nu}_{ij}` are computed as:
|
||||
|
||||
.. math::
|
||||
|
||||
\texttt{nu} _{ji}= \frac{\texttt{mu}_{ji}}{\texttt{m}_{00}^{(i+j)/2+1}} .
|
||||
|
||||
.. note::
|
||||
|
||||
:math:`\texttt{mu}_{00}=\texttt{m}_{00}`,
|
||||
:math:`\texttt{nu}_{00}=1`
|
||||
:math:`\texttt{nu}_{10}=\texttt{mu}_{10}=\texttt{mu}_{01}=\texttt{mu}_{10}=0` , hence the values are not stored.
|
||||
|
||||
The moments of a contour are defined in the same way but computed using the Green's formula (see http://en.wikipedia.org/wiki/Green_theorem). So, due to a limited raster resolution, the moments computed for a contour are slightly different from the moments computed for the same rasterized contour.
|
||||
|
||||
.. note::
|
||||
|
||||
Since the contour moments are computed using Green formula, you may get seemingly odd results for contours with self-intersections, e.g. a zero area (``m00``) for butterfly-shaped contours.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:func:`contourArea`,
|
||||
:ocv:func:`arcLength`
|
||||
|
||||
|
||||
|
||||
HuMoments
|
||||
-------------
|
||||
Calculates seven Hu invariants.
|
||||
|
||||
.. ocv:function:: void HuMoments( const Moments& m, OutputArray hu )
|
||||
|
||||
.. ocv:function:: void HuMoments( const Moments& moments, double hu[7] )
|
||||
|
||||
.. ocv:pyfunction:: cv2.HuMoments(m[, hu]) -> hu
|
||||
|
||||
.. ocv:cfunction:: void cvGetHuMoments( CvMoments* moments, CvHuMoments* hu_moments )
|
||||
|
||||
:param moments: Input moments computed with :ocv:func:`moments` .
|
||||
:param hu: Output Hu invariants.
|
||||
|
||||
The function calculates seven Hu invariants (introduced in [Hu62]_; see also
|
||||
http://en.wikipedia.org/wiki/Image_moment) defined as:
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{array}{l} hu[0]= \eta _{20}+ \eta _{02} \\ hu[1]=( \eta _{20}- \eta _{02})^{2}+4 \eta _{11}^{2} \\ hu[2]=( \eta _{30}-3 \eta _{12})^{2}+ (3 \eta _{21}- \eta _{03})^{2} \\ hu[3]=( \eta _{30}+ \eta _{12})^{2}+ ( \eta _{21}+ \eta _{03})^{2} \\ hu[4]=( \eta _{30}-3 \eta _{12})( \eta _{30}+ \eta _{12})[( \eta _{30}+ \eta _{12})^{2}-3( \eta _{21}+ \eta _{03})^{2}]+(3 \eta _{21}- \eta _{03})( \eta _{21}+ \eta _{03})[3( \eta _{30}+ \eta _{12})^{2}-( \eta _{21}+ \eta _{03})^{2}] \\ hu[5]=( \eta _{20}- \eta _{02})[( \eta _{30}+ \eta _{12})^{2}- ( \eta _{21}+ \eta _{03})^{2}]+4 \eta _{11}( \eta _{30}+ \eta _{12})( \eta _{21}+ \eta _{03}) \\ hu[6]=(3 \eta _{21}- \eta _{03})( \eta _{21}+ \eta _{03})[3( \eta _{30}+ \eta _{12})^{2}-( \eta _{21}+ \eta _{03})^{2}]-( \eta _{30}-3 \eta _{12})( \eta _{21}+ \eta _{03})[3( \eta _{30}+ \eta _{12})^{2}-( \eta _{21}+ \eta _{03})^{2}] \\ \end{array}
|
||||
|
||||
where
|
||||
:math:`\eta_{ji}` stands for
|
||||
:math:`\texttt{Moments::nu}_{ji}` .
|
||||
|
||||
These values are proved to be invariants to the image scale, rotation, and reflection except the seventh one, whose sign is changed by reflection. This invariance is proved with the assumption of infinite image resolution. In case of raster images, the computed Hu invariants for the original and transformed images are a bit different.
|
||||
|
||||
.. seealso:: :ocv:func:`matchShapes`
|
||||
|
||||
connectedComponents
|
||||
-----------------------
|
||||
computes the connected components labeled image of boolean image ``image`` with 4 or 8 way connectivity - returns N, the total number of labels [0, N-1] where 0 represents the background label. ltype specifies the output label image type, an important consideration based on the total number of labels or alternatively the total number of pixels in the source image.
|
||||
|
||||
.. ocv:function:: int connectedComponents(InputArray image, OutputArray labels, int connectivity = 8, int ltype=CV_32S)
|
||||
|
||||
.. ocv:function:: int connectedComponentsWithStats(InputArray image, OutputArray labels, OutputArray stats, OutputArray centroids, int connectivity = 8, int ltype=CV_32S)
|
||||
|
||||
:param image: the image to be labeled
|
||||
|
||||
:param labels: destination labeled image
|
||||
|
||||
:param connectivity: 8 or 4 for 8-way or 4-way connectivity respectively
|
||||
|
||||
:param ltype: output image label type. Currently CV_32S and CV_16U are supported.
|
||||
|
||||
:param statsv: statistics output for each label, including the background label, see below for available statistics. Statistics are accessed via statsv(label, COLUMN) where available columns are defined below.
|
||||
|
||||
* **CC_STAT_LEFT** The leftmost (x) coordinate which is the inclusive start of the bounding box in the horizontal
|
||||
direction.
|
||||
|
||||
* **CC_STAT_TOP** The topmost (y) coordinate which is the inclusive start of the bounding box in the vertical
|
||||
direction.
|
||||
|
||||
* **CC_STAT_WIDTH** The horizontal size of the bounding box
|
||||
|
||||
* **CC_STAT_HEIGHT** The vertical size of the bounding box
|
||||
|
||||
* **CC_STAT_AREA** The total area (in pixels) of the connected component
|
||||
|
||||
:param centroids: floating point centroid (x,y) output for each label, including the background label
|
||||
|
||||
|
||||
findContours
|
||||
----------------
|
||||
Finds contours in a binary image.
|
||||
|
||||
.. ocv:function:: void findContours( InputOutputArray image, OutputArrayOfArrays contours, OutputArray hierarchy, int mode, int method, Point offset=Point())
|
||||
|
||||
.. ocv:function:: void findContours( InputOutputArray image, OutputArrayOfArrays contours, int mode, int method, Point offset=Point())
|
||||
|
||||
.. ocv:pyfunction:: cv2.findContours(image, mode, method[, contours[, hierarchy[, offset]]]) -> image, contours, hierarchy
|
||||
|
||||
.. ocv:cfunction:: int cvFindContours( CvArr* image, CvMemStorage* storage, CvSeq** first_contour, int header_size=sizeof(CvContour), int mode=CV_RETR_LIST, int method=CV_CHAIN_APPROX_SIMPLE, CvPoint offset=cvPoint(0,0) )
|
||||
|
||||
:param image: Source, an 8-bit single-channel image. Non-zero pixels are treated as 1's. Zero pixels remain 0's, so the image is treated as ``binary`` . You can use :ocv:func:`compare` , :ocv:func:`inRange` , :ocv:func:`threshold` , :ocv:func:`adaptiveThreshold` , :ocv:func:`Canny` , and others to create a binary image out of a grayscale or color one. The function modifies the ``image`` while extracting the contours. If mode equals to ``CV_RETR_CCOMP`` or ``CV_RETR_FLOODFILL``, the input can also be a 32-bit integer image of labels (``CV_32SC1``).
|
||||
|
||||
:param contours: Detected contours. Each contour is stored as a vector of points.
|
||||
|
||||
:param hierarchy: Optional output vector, containing information about the image topology. It has as many elements as the number of contours. For each i-th contour ``contours[i]`` , the elements ``hierarchy[i][0]`` , ``hiearchy[i][1]`` , ``hiearchy[i][2]`` , and ``hiearchy[i][3]`` are set to 0-based indices in ``contours`` of the next and previous contours at the same hierarchical level, the first child contour and the parent contour, respectively. If for the contour ``i`` there are no next, previous, parent, or nested contours, the corresponding elements of ``hierarchy[i]`` will be negative.
|
||||
|
||||
:param mode: Contour retrieval mode (if you use Python see also a note below).
|
||||
|
||||
* **CV_RETR_EXTERNAL** retrieves only the extreme outer contours. It sets ``hierarchy[i][2]=hierarchy[i][3]=-1`` for all the contours.
|
||||
|
||||
* **CV_RETR_LIST** retrieves all of the contours without establishing any hierarchical relationships.
|
||||
|
||||
* **CV_RETR_CCOMP** retrieves all of the contours and organizes them into a two-level hierarchy. At the top level, there are external boundaries of the components. At the second level, there are boundaries of the holes. If there is another contour inside a hole of a connected component, it is still put at the top level.
|
||||
|
||||
* **CV_RETR_TREE** retrieves all of the contours and reconstructs a full hierarchy of nested contours. This full hierarchy is built and shown in the OpenCV ``contours.c`` demo.
|
||||
|
||||
:param method: Contour approximation method (if you use Python see also a note below).
|
||||
|
||||
* **CV_CHAIN_APPROX_NONE** stores absolutely all the contour points. That is, any 2 subsequent points ``(x1,y1)`` and ``(x2,y2)`` of the contour will be either horizontal, vertical or diagonal neighbors, that is, ``max(abs(x1-x2),abs(y2-y1))==1``.
|
||||
|
||||
* **CV_CHAIN_APPROX_SIMPLE** compresses horizontal, vertical, and diagonal segments and leaves only their end points. For example, an up-right rectangular contour is encoded with 4 points.
|
||||
|
||||
* **CV_CHAIN_APPROX_TC89_L1,CV_CHAIN_APPROX_TC89_KCOS** applies one of the flavors of the Teh-Chin chain approximation algorithm. See [TehChin89]_ for details.
|
||||
|
||||
:param offset: Optional offset by which every contour point is shifted. This is useful if the contours are extracted from the image ROI and then they should be analyzed in the whole image context.
|
||||
|
||||
The function retrieves contours from the binary image using the algorithm
|
||||
[Suzuki85]_. The contours are a useful tool for shape analysis and object detection and recognition. See ``squares.c`` in the OpenCV sample directory.
|
||||
|
||||
.. note:: Source ``image`` is modified by this function. Also, the function does not take into account 1-pixel border of the image (it's filled with 0's and used for neighbor analysis in the algorithm), therefore the contours touching the image border will be clipped.
|
||||
|
||||
.. note:: If you use the new Python interface then the ``CV_`` prefix has to be omitted in contour retrieval mode and contour approximation method parameters (for example, use ``cv2.RETR_LIST`` and ``cv2.CHAIN_APPROX_NONE`` parameters). If you use the old Python interface then these parameters have the ``CV_`` prefix (for example, use ``cv.CV_RETR_LIST`` and ``cv.CV_CHAIN_APPROX_NONE``).
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the findContour functionality can be found at opencv_source_code/samples/cpp/contours2.cpp
|
||||
* An example using findContours to clean up a background segmentation result at opencv_source_code/samples/cpp/segment_objects.cpp
|
||||
|
||||
* (Python) An example using the findContour functionality can be found at opencv_source/samples/python2/contours.py
|
||||
* (Python) An example of detecting squares in an image can be found at opencv_source/samples/python2/squares.py
|
||||
|
||||
|
||||
approxPolyDP
|
||||
----------------
|
||||
Approximates a polygonal curve(s) with the specified precision.
|
||||
|
||||
.. ocv:function:: void approxPolyDP( InputArray curve, OutputArray approxCurve, double epsilon, bool closed )
|
||||
|
||||
.. ocv:pyfunction:: cv2.approxPolyDP(curve, epsilon, closed[, approxCurve]) -> approxCurve
|
||||
|
||||
.. ocv:cfunction:: CvSeq* cvApproxPoly( const void* src_seq, int header_size, CvMemStorage* storage, int method, double eps, int recursive=0 )
|
||||
|
||||
:param curve: Input vector of a 2D point stored in:
|
||||
|
||||
* ``std::vector`` or ``Mat`` (C++ interface)
|
||||
|
||||
* ``Nx2`` numpy array (Python interface)
|
||||
|
||||
* ``CvSeq`` or `` ``CvMat`` (C interface)
|
||||
|
||||
:param approxCurve: Result of the approximation. The type should match the type of the input curve. In case of C interface the approximated curve is stored in the memory storage and pointer to it is returned.
|
||||
|
||||
:param epsilon: Parameter specifying the approximation accuracy. This is the maximum distance between the original curve and its approximation.
|
||||
|
||||
:param closed: If true, the approximated curve is closed (its first and last vertices are connected). Otherwise, it is not closed.
|
||||
|
||||
:param header_size: Header size of the approximated curve. Normally, ``sizeof(CvContour)`` is used.
|
||||
|
||||
:param storage: Memory storage where the approximated curve is stored.
|
||||
|
||||
:param method: Contour approximation algorithm. Only ``CV_POLY_APPROX_DP`` is supported.
|
||||
|
||||
:param recursive: Recursion flag. If it is non-zero and ``curve`` is ``CvSeq*``, the function ``cvApproxPoly`` approximates all the contours accessible from ``curve`` by ``h_next`` and ``v_next`` links.
|
||||
|
||||
The functions ``approxPolyDP`` approximate a curve or a polygon with another curve/polygon with less vertices so that the distance between them is less or equal to the specified precision. It uses the Douglas-Peucker algorithm
|
||||
http://en.wikipedia.org/wiki/Ramer-Douglas-Peucker_algorithm
|
||||
|
||||
See https://github.com/Itseez/opencv/tree/master/samples/cpp/contours2.cpp for the function usage model.
|
||||
|
||||
|
||||
ApproxChains
|
||||
-------------
|
||||
Approximates Freeman chain(s) with a polygonal curve.
|
||||
|
||||
.. ocv:cfunction:: CvSeq* cvApproxChains( CvSeq* src_seq, CvMemStorage* storage, int method=CV_CHAIN_APPROX_SIMPLE, double parameter=0, int minimal_perimeter=0, int recursive=0 )
|
||||
|
||||
:param src_seq: Pointer to the approximated Freeman chain that can refer to other chains.
|
||||
|
||||
:param storage: Storage location for the resulting polylines.
|
||||
|
||||
:param method: Approximation method (see the description of the function :ocv:cfunc:`FindContours` ).
|
||||
|
||||
:param parameter: Method parameter (not used now).
|
||||
|
||||
:param minimal_perimeter: Approximates only those contours whose perimeters are not less than ``minimal_perimeter`` . Other chains are removed from the resulting structure.
|
||||
|
||||
:param recursive: Recursion flag. If it is non-zero, the function approximates all chains that can be obtained from ``chain`` by using the ``h_next`` or ``v_next`` links. Otherwise, the single input chain is approximated.
|
||||
|
||||
This is a standalone contour approximation routine, not represented in the new interface. When :ocv:cfunc:`FindContours` retrieves contours as Freeman chains, it calls the function to get approximated contours, represented as polygons.
|
||||
|
||||
|
||||
arcLength
|
||||
-------------
|
||||
Calculates a contour perimeter or a curve length.
|
||||
|
||||
.. ocv:function:: double arcLength( InputArray curve, bool closed )
|
||||
|
||||
.. ocv:pyfunction:: cv2.arcLength(curve, closed) -> retval
|
||||
|
||||
.. ocv:cfunction:: double cvArcLength( const void* curve, CvSlice slice=CV_WHOLE_SEQ, int is_closed=-1 )
|
||||
|
||||
:param curve: Input vector of 2D points, stored in ``std::vector`` or ``Mat``.
|
||||
|
||||
:param closed: Flag indicating whether the curve is closed or not.
|
||||
|
||||
The function computes a curve length or a closed contour perimeter.
|
||||
|
||||
|
||||
|
||||
boundingRect
|
||||
----------------
|
||||
Calculates the up-right bounding rectangle of a point set.
|
||||
|
||||
.. ocv:function:: Rect boundingRect( InputArray points )
|
||||
|
||||
.. ocv:pyfunction:: cv2.boundingRect(points) -> retval
|
||||
|
||||
.. ocv:cfunction:: CvRect cvBoundingRect( CvArr* points, int update=0 )
|
||||
|
||||
:param points: Input 2D point set, stored in ``std::vector`` or ``Mat``.
|
||||
|
||||
The function calculates and returns the minimal up-right bounding rectangle for the specified point set.
|
||||
|
||||
|
||||
contourArea
|
||||
---------------
|
||||
Calculates a contour area.
|
||||
|
||||
.. ocv:function:: double contourArea( InputArray contour, bool oriented=false )
|
||||
|
||||
.. ocv:pyfunction:: cv2.contourArea(contour[, oriented]) -> retval
|
||||
|
||||
.. ocv:cfunction:: double cvContourArea( const CvArr* contour, CvSlice slice=CV_WHOLE_SEQ, int oriented=0 )
|
||||
|
||||
:param contour: Input vector of 2D points (contour vertices), stored in ``std::vector`` or ``Mat``.
|
||||
|
||||
:param oriented: Oriented area flag. If it is true, the function returns a signed area value, depending on the contour orientation (clockwise or counter-clockwise). Using this feature you can determine orientation of a contour by taking the sign of an area. By default, the parameter is ``false``, which means that the absolute value is returned.
|
||||
|
||||
The function computes a contour area. Similarly to
|
||||
:ocv:func:`moments` , the area is computed using the Green formula. Thus, the returned area and the number of non-zero pixels, if you draw the contour using
|
||||
:ocv:func:`drawContours` or
|
||||
:ocv:func:`fillPoly` , can be different.
|
||||
Also, the function will most certainly give a wrong results for contours with self-intersections.
|
||||
|
||||
Example: ::
|
||||
|
||||
vector<Point> contour;
|
||||
contour.push_back(Point2f(0, 0));
|
||||
contour.push_back(Point2f(10, 0));
|
||||
contour.push_back(Point2f(10, 10));
|
||||
contour.push_back(Point2f(5, 4));
|
||||
|
||||
double area0 = contourArea(contour);
|
||||
vector<Point> approx;
|
||||
approxPolyDP(contour, approx, 5, true);
|
||||
double area1 = contourArea(approx);
|
||||
|
||||
cout << "area0 =" << area0 << endl <<
|
||||
"area1 =" << area1 << endl <<
|
||||
"approx poly vertices" << approx.size() << endl;
|
||||
|
||||
|
||||
|
||||
convexHull
|
||||
--------------
|
||||
Finds the convex hull of a point set.
|
||||
|
||||
.. ocv:function:: void convexHull( InputArray points, OutputArray hull, bool clockwise=false, bool returnPoints=true )
|
||||
|
||||
.. ocv:pyfunction:: cv2.convexHull(points[, hull[, clockwise[, returnPoints]]]) -> hull
|
||||
|
||||
.. ocv:cfunction:: CvSeq* cvConvexHull2( const CvArr* input, void* hull_storage=NULL, int orientation=CV_CLOCKWISE, int return_points=0 )
|
||||
|
||||
:param points: Input 2D point set, stored in ``std::vector`` or ``Mat``.
|
||||
|
||||
:param hull: Output convex hull. It is either an integer vector of indices or vector of points. In the first case, the ``hull`` elements are 0-based indices of the convex hull points in the original array (since the set of convex hull points is a subset of the original point set). In the second case, ``hull`` elements are the convex hull points themselves.
|
||||
|
||||
:param hull_storage: Output memory storage in the old API (``cvConvexHull2`` returns a sequence containing the convex hull points or their indices).
|
||||
|
||||
:param clockwise: Orientation flag. If it is true, the output convex hull is oriented clockwise. Otherwise, it is oriented counter-clockwise. The assumed coordinate system has its X axis pointing to the right, and its Y axis pointing upwards.
|
||||
|
||||
:param orientation: Convex hull orientation parameter in the old API, ``CV_CLOCKWISE`` or ``CV_COUNTERCLOCKWISE``.
|
||||
|
||||
:param returnPoints: Operation flag. In case of a matrix, when the flag is true, the function returns convex hull points. Otherwise, it returns indices of the convex hull points. When the output array is ``std::vector``, the flag is ignored, and the output depends on the type of the vector: ``std::vector<int>`` implies ``returnPoints=true``, ``std::vector<Point>`` implies ``returnPoints=false``.
|
||||
|
||||
The functions find the convex hull of a 2D point set using the Sklansky's algorithm
|
||||
[Sklansky82]_
|
||||
that has
|
||||
*O(N logN)* complexity in the current implementation. See the OpenCV sample ``convexhull.cpp`` that demonstrates the usage of different function variants.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the convexHull functionality can be found at opencv_source_code/samples/cpp/convexhull.cpp
|
||||
|
||||
|
||||
convexityDefects
|
||||
----------------
|
||||
Finds the convexity defects of a contour.
|
||||
|
||||
.. ocv:function:: void convexityDefects( InputArray contour, InputArray convexhull, OutputArray convexityDefects )
|
||||
|
||||
.. ocv:pyfunction:: cv2.convexityDefects(contour, convexhull[, convexityDefects]) -> convexityDefects
|
||||
|
||||
.. ocv:cfunction:: CvSeq* cvConvexityDefects( const CvArr* contour, const CvArr* convexhull, CvMemStorage* storage=NULL )
|
||||
|
||||
:param contour: Input contour.
|
||||
|
||||
:param convexhull: Convex hull obtained using :ocv:func:`convexHull` that should contain indices of the contour points that make the hull.
|
||||
|
||||
:param convexityDefects: The output vector of convexity defects. In C++ and the new Python/Java interface each convexity defect is represented as 4-element integer vector (a.k.a. ``cv::Vec4i``): ``(start_index, end_index, farthest_pt_index, fixpt_depth)``, where indices are 0-based indices in the original contour of the convexity defect beginning, end and the farthest point, and ``fixpt_depth`` is fixed-point approximation (with 8 fractional bits) of the distance between the farthest contour point and the hull. That is, to get the floating-point value of the depth will be ``fixpt_depth/256.0``. In C interface convexity defect is represented by ``CvConvexityDefect`` structure - see below.
|
||||
|
||||
:param storage: Container for the output sequence of convexity defects. If it is NULL, the contour or hull (in that order) storage is used.
|
||||
|
||||
The function finds all convexity defects of the input contour and returns a sequence of the ``CvConvexityDefect`` structures, where ``CvConvexityDetect`` is defined as: ::
|
||||
|
||||
struct CvConvexityDefect
|
||||
{
|
||||
CvPoint* start; // point of the contour where the defect begins
|
||||
CvPoint* end; // point of the contour where the defect ends
|
||||
CvPoint* depth_point; // the farthest from the convex hull point within the defect
|
||||
float depth; // distance between the farthest point and the convex hull
|
||||
};
|
||||
|
||||
The figure below displays convexity defects of a hand contour:
|
||||
|
||||
.. image:: pics/defects.png
|
||||
|
||||
fitEllipse
|
||||
--------------
|
||||
Fits an ellipse around a set of 2D points.
|
||||
|
||||
.. ocv:function:: RotatedRect fitEllipse( InputArray points )
|
||||
|
||||
.. ocv:pyfunction:: cv2.fitEllipse(points) -> retval
|
||||
|
||||
.. ocv:cfunction:: CvBox2D cvFitEllipse2( const CvArr* points )
|
||||
|
||||
:param points: Input 2D point set, stored in:
|
||||
|
||||
* ``std::vector<>`` or ``Mat`` (C++ interface)
|
||||
|
||||
* ``CvSeq*`` or ``CvMat*`` (C interface)
|
||||
|
||||
* Nx2 numpy array (Python interface)
|
||||
|
||||
The function calculates the ellipse that fits (in a least-squares sense) a set of 2D points best of all. It returns the rotated rectangle in which the ellipse is inscribed. The algorithm [Fitzgibbon95]_ is used.
|
||||
Developer should keep in mind that it is possible that the returned ellipse/rotatedRect data contains negative indices, due to the data points being close to the border of the containing Mat element.
|
||||
|
||||
.. note::
|
||||
|
||||
* An example using the fitEllipse technique can be found at opencv_source_code/samples/cpp/fitellipse.cpp
|
||||
|
||||
|
||||
fitLine
|
||||
-----------
|
||||
Fits a line to a 2D or 3D point set.
|
||||
|
||||
.. ocv:function:: void fitLine( InputArray points, OutputArray line, int distType, double param, double reps, double aeps )
|
||||
|
||||
.. ocv:pyfunction:: cv2.fitLine(points, distType, param, reps, aeps[, line]) -> line
|
||||
|
||||
.. ocv:cfunction:: void cvFitLine( const CvArr* points, int dist_type, double param, double reps, double aeps, float* line )
|
||||
|
||||
:param points: Input vector of 2D or 3D points, stored in ``std::vector<>`` or ``Mat``.
|
||||
|
||||
:param line: Output line parameters. In case of 2D fitting, it should be a vector of 4 elements (like ``Vec4f``) - ``(vx, vy, x0, y0)``, where ``(vx, vy)`` is a normalized vector collinear to the line and ``(x0, y0)`` is a point on the line. In case of 3D fitting, it should be a vector of 6 elements (like ``Vec6f``) - ``(vx, vy, vz, x0, y0, z0)``, where ``(vx, vy, vz)`` is a normalized vector collinear to the line and ``(x0, y0, z0)`` is a point on the line.
|
||||
|
||||
:param distType: Distance used by the M-estimator (see the discussion below).
|
||||
|
||||
:param param: Numerical parameter ( ``C`` ) for some types of distances. If it is 0, an optimal value is chosen.
|
||||
|
||||
:param reps: Sufficient accuracy for the radius (distance between the coordinate origin and the line).
|
||||
|
||||
:param aeps: Sufficient accuracy for the angle. 0.01 would be a good default value for ``reps`` and ``aeps``.
|
||||
|
||||
The function ``fitLine`` fits a line to a 2D or 3D point set by minimizing
|
||||
:math:`\sum_i \rho(r_i)` where
|
||||
:math:`r_i` is a distance between the
|
||||
:math:`i^{th}` point, the line and
|
||||
:math:`\rho(r)` is a distance function, one of the following:
|
||||
|
||||
* distType=CV\_DIST\_L2
|
||||
|
||||
.. math::
|
||||
|
||||
\rho (r) = r^2/2 \quad \text{(the simplest and the fastest least-squares method)}
|
||||
|
||||
* distType=CV\_DIST\_L1
|
||||
|
||||
.. math::
|
||||
|
||||
\rho (r) = r
|
||||
|
||||
* distType=CV\_DIST\_L12
|
||||
|
||||
.. math::
|
||||
|
||||
\rho (r) = 2 \cdot ( \sqrt{1 + \frac{r^2}{2}} - 1)
|
||||
|
||||
* distType=CV\_DIST\_FAIR
|
||||
|
||||
.. math::
|
||||
|
||||
\rho \left (r \right ) = C^2 \cdot \left ( \frac{r}{C} - \log{\left(1 + \frac{r}{C}\right)} \right ) \quad \text{where} \quad C=1.3998
|
||||
|
||||
* distType=CV\_DIST\_WELSCH
|
||||
|
||||
.. math::
|
||||
|
||||
\rho \left (r \right ) = \frac{C^2}{2} \cdot \left ( 1 - \exp{\left(-\left(\frac{r}{C}\right)^2\right)} \right ) \quad \text{where} \quad C=2.9846
|
||||
|
||||
* distType=CV\_DIST\_HUBER
|
||||
|
||||
.. math::
|
||||
|
||||
\rho (r) = \fork{r^2/2}{if $r < C$}{C \cdot (r-C/2)}{otherwise} \quad \text{where} \quad C=1.345
|
||||
|
||||
The algorithm is based on the M-estimator (
|
||||
http://en.wikipedia.org/wiki/M-estimator
|
||||
) technique that iteratively fits the line using the weighted least-squares algorithm. After each iteration the weights
|
||||
:math:`w_i` are adjusted to be inversely proportional to
|
||||
:math:`\rho(r_i)` .
|
||||
|
||||
.. Sample code:
|
||||
|
||||
* (Python) An example of robust line fitting can be found at opencv_source_code/samples/python2/fitline.py
|
||||
|
||||
|
||||
isContourConvex
|
||||
-------------------
|
||||
Tests a contour convexity.
|
||||
|
||||
.. ocv:function:: bool isContourConvex( InputArray contour )
|
||||
|
||||
.. ocv:pyfunction:: cv2.isContourConvex(contour) -> retval
|
||||
|
||||
.. ocv:cfunction:: int cvCheckContourConvexity( const CvArr* contour )
|
||||
|
||||
:param contour: Input vector of 2D points, stored in:
|
||||
|
||||
* ``std::vector<>`` or ``Mat`` (C++ interface)
|
||||
|
||||
* ``CvSeq*`` or ``CvMat*`` (C interface)
|
||||
|
||||
* Nx2 numpy array (Python interface)
|
||||
|
||||
The function tests whether the input contour is convex or not. The contour must be simple, that is, without self-intersections. Otherwise, the function output is undefined.
|
||||
|
||||
|
||||
|
||||
minAreaRect
|
||||
---------------
|
||||
Finds a rotated rectangle of the minimum area enclosing the input 2D point set.
|
||||
|
||||
.. ocv:function:: RotatedRect minAreaRect( InputArray points )
|
||||
|
||||
.. ocv:pyfunction:: cv2.minAreaRect(points) -> retval
|
||||
|
||||
.. ocv:cfunction:: CvBox2D cvMinAreaRect2( const CvArr* points, CvMemStorage* storage=NULL )
|
||||
|
||||
:param points: Input vector of 2D points, stored in:
|
||||
|
||||
* ``std::vector<>`` or ``Mat`` (C++ interface)
|
||||
|
||||
* ``CvSeq*`` or ``CvMat*`` (C interface)
|
||||
|
||||
* Nx2 numpy array (Python interface)
|
||||
|
||||
The function calculates and returns the minimum-area bounding rectangle (possibly rotated) for a specified point set. See the OpenCV sample ``minarea.cpp`` .
|
||||
Developer should keep in mind that the returned rotatedRect can contain negative indices when data is close the the containing Mat element boundary.
|
||||
|
||||
|
||||
boxPoints
|
||||
-----------
|
||||
Finds the four vertices of a rotated rect. Useful to draw the rotated rectangle.
|
||||
|
||||
.. ocv:function:: void boxPoints(RotatedRect box, OutputArray points)
|
||||
|
||||
.. ocv:pyfunction:: cv2.boxPoints(box[, points]) -> points
|
||||
|
||||
.. ocv:cfunction:: void cvBoxPoints( CvBox2D box, CvPoint2D32f pt[4] )
|
||||
|
||||
:param box: The input rotated rectangle. It may be the output of .. ocv:function:: minAreaRect.
|
||||
|
||||
:param points: The output array of four vertices of rectangles.
|
||||
|
||||
The function finds the four vertices of a rotated rectangle. This function is useful to draw the rectangle. In C++, instead of using this function, you can directly use box.points() method. Please visit the `tutorial on bounding rectangle <http://docs.opencv.org/doc/tutorials/imgproc/shapedescriptors/bounding_rects_circles/bounding_rects_circles.html#bounding-rects-circles>`_ for more information.
|
||||
|
||||
|
||||
|
||||
minEnclosingTriangle
|
||||
----------------------
|
||||
Finds a triangle of minimum area enclosing a 2D point set and returns its area.
|
||||
|
||||
.. ocv:function:: double minEnclosingTriangle( InputArray points, OutputArray triangle )
|
||||
|
||||
.. ocv:pyfunction:: cv2.minEnclosingTriangle(points[, triangle]) -> retval, triangle
|
||||
|
||||
:param points: Input vector of 2D points with depth ``CV_32S`` or ``CV_32F``, stored in:
|
||||
|
||||
* ``std::vector<>`` or ``Mat`` (C++ interface)
|
||||
|
||||
* Nx2 numpy array (Python interface)
|
||||
|
||||
:param triangle: Output vector of three 2D points defining the vertices of the triangle. The depth of the OutputArray must be ``CV_32F``.
|
||||
|
||||
The function finds a triangle of minimum area enclosing the given set of 2D points and returns its area. The output for a given 2D point set is shown in the image below. 2D points are depicted in *red* and the enclosing triangle in *yellow*.
|
||||
|
||||
.. image:: pics/minenclosingtriangle.png
|
||||
:height: 250px
|
||||
:width: 250px
|
||||
:alt: Sample output of the minimum enclosing triangle function
|
||||
|
||||
The implementation of the algorithm is based on O'Rourke's [ORourke86]_ and Klee and Laskowski's [KleeLaskowski85]_ papers. O'Rourke provides a
|
||||
:math:`\theta(n)`
|
||||
algorithm for finding the minimal enclosing triangle of a 2D convex polygon with ``n`` vertices. Since the :ocv:func:`minEnclosingTriangle` function takes a 2D point set as input an additional preprocessing step of computing the convex hull of the 2D point set is required. The complexity of the :ocv:func:`convexHull` function is
|
||||
:math:`O(n log(n))` which is higher than
|
||||
:math:`\theta(n)`.
|
||||
Thus the overall complexity of the function is
|
||||
:math:`O(n log(n))`.
|
||||
|
||||
.. note:: See ``opencv_source/samples/cpp/minarea.cpp`` for a usage example.
|
||||
|
||||
|
||||
|
||||
minEnclosingCircle
|
||||
----------------------
|
||||
Finds a circle of the minimum area enclosing a 2D point set.
|
||||
|
||||
.. ocv:function:: void minEnclosingCircle( InputArray points, Point2f& center, float& radius )
|
||||
|
||||
.. ocv:pyfunction:: cv2.minEnclosingCircle(points) -> center, radius
|
||||
|
||||
.. ocv:cfunction:: int cvMinEnclosingCircle( const CvArr* points, CvPoint2D32f* center, float* radius )
|
||||
|
||||
:param points: Input vector of 2D points, stored in:
|
||||
|
||||
* ``std::vector<>`` or ``Mat`` (C++ interface)
|
||||
|
||||
* ``CvSeq*`` or ``CvMat*`` (C interface)
|
||||
|
||||
* Nx2 numpy array (Python interface)
|
||||
|
||||
:param center: Output center of the circle.
|
||||
|
||||
:param radius: Output radius of the circle.
|
||||
|
||||
The function finds the minimal enclosing circle of a 2D point set using an iterative algorithm. See the OpenCV sample ``minarea.cpp`` .
|
||||
|
||||
|
||||
|
||||
matchShapes
|
||||
---------------
|
||||
Compares two shapes.
|
||||
|
||||
.. ocv:function:: double matchShapes( InputArray contour1, InputArray contour2, int method, double parameter )
|
||||
|
||||
.. ocv:pyfunction:: cv2.matchShapes(contour1, contour2, method, parameter) -> retval
|
||||
|
||||
.. ocv:cfunction:: double cvMatchShapes( const void* object1, const void* object2, int method, double parameter=0 )
|
||||
|
||||
:param object1: First contour or grayscale image.
|
||||
|
||||
:param object2: Second contour or grayscale image.
|
||||
|
||||
:param method: Comparison method: ``CV_CONTOURS_MATCH_I1`` , \ ``CV_CONTOURS_MATCH_I2`` \
|
||||
or ``CV_CONTOURS_MATCH_I3`` (see the details below).
|
||||
|
||||
:param parameter: Method-specific parameter (not supported now).
|
||||
|
||||
The function compares two shapes. All three implemented methods use the Hu invariants (see
|
||||
:ocv:func:`HuMoments` ) as follows (
|
||||
:math:`A` denotes ``object1``,:math:`B` denotes ``object2`` ):
|
||||
|
||||
* method=CV_CONTOURS_MATCH_I1
|
||||
|
||||
.. math::
|
||||
|
||||
I_1(A,B) = \sum _{i=1...7} \left | \frac{1}{m^A_i} - \frac{1}{m^B_i} \right |
|
||||
|
||||
* method=CV_CONTOURS_MATCH_I2
|
||||
|
||||
.. math::
|
||||
|
||||
I_2(A,B) = \sum _{i=1...7} \left | m^A_i - m^B_i \right |
|
||||
|
||||
* method=CV_CONTOURS_MATCH_I3
|
||||
|
||||
.. math::
|
||||
|
||||
I_3(A,B) = \max _{i=1...7} \frac{ \left| m^A_i - m^B_i \right| }{ \left| m^A_i \right| }
|
||||
|
||||
where
|
||||
|
||||
.. math::
|
||||
|
||||
\begin{array}{l} m^A_i = \mathrm{sign} (h^A_i) \cdot \log{h^A_i} \\ m^B_i = \mathrm{sign} (h^B_i) \cdot \log{h^B_i} \end{array}
|
||||
|
||||
and
|
||||
:math:`h^A_i, h^B_i` are the Hu moments of
|
||||
:math:`A` and
|
||||
:math:`B` , respectively.
|
||||
|
||||
|
||||
|
||||
pointPolygonTest
|
||||
--------------------
|
||||
Performs a point-in-contour test.
|
||||
|
||||
.. ocv:function:: double pointPolygonTest( InputArray contour, Point2f pt, bool measureDist )
|
||||
|
||||
.. ocv:pyfunction:: cv2.pointPolygonTest(contour, pt, measureDist) -> retval
|
||||
|
||||
.. ocv:cfunction:: double cvPointPolygonTest( const CvArr* contour, CvPoint2D32f pt, int measure_dist )
|
||||
|
||||
:param contour: Input contour.
|
||||
|
||||
:param pt: Point tested against the contour.
|
||||
|
||||
:param measureDist: If true, the function estimates the signed distance from the point to the nearest contour edge. Otherwise, the function only checks if the point is inside a contour or not.
|
||||
|
||||
The function determines whether the
|
||||
point is inside a contour, outside, or lies on an edge (or coincides
|
||||
with a vertex). It returns positive (inside), negative (outside), or zero (on an edge) value,
|
||||
correspondingly. When ``measureDist=false`` , the return value
|
||||
is +1, -1, and 0, respectively. Otherwise, the return value
|
||||
is a signed distance between the point and the nearest contour
|
||||
edge.
|
||||
|
||||
See below a sample output of the function where each image pixel is tested against the contour.
|
||||
|
||||
.. image:: pics/pointpolygon.png
|
||||
|
||||
.. [Fitzgibbon95] Andrew W. Fitzgibbon, R.B.Fisher. *A Buyer's Guide to Conic Fitting*. Proc.5th British Machine Vision Conference, Birmingham, pp. 513-522, 1995.
|
||||
|
||||
.. [Hu62] M. Hu. *Visual Pattern Recognition by Moment Invariants*, IRE Transactions on Information Theory, 8:2, pp. 179-187, 1962.
|
||||
|
||||
.. [KleeLaskowski85] Klee, V. and Laskowski, M.C., *Finding the smallest triangles containing a given convex polygon*, Journal of Algorithms, vol. 6, no. 3, pp. 359-375 (1985)
|
||||
|
||||
.. [ORourke86] O’Rourke, J., Aggarwal, A., Maddila, S., and Baldwin, M., *An optimal algorithm for finding minimal enclosing triangles*, Journal of Algorithms, vol. 7, no. 2, pp. 258-269 (1986)
|
||||
|
||||
.. [Sklansky82] Sklansky, J., *Finding the Convex Hull of a Simple Polygon*. PRL 1 $number, pp 79-83 (1982)
|
||||
|
||||
.. [Suzuki85] Suzuki, S. and Abe, K., *Topological Structural Analysis of Digitized Binary Images by Border Following*. CVGIP 30 1, pp 32-46 (1985)
|
||||
|
||||
.. [TehChin89] Teh, C.H. and Chin, R.T., *On the Detection of Dominant Points on Digital Curve*. PAMI 11 8, pp 859-872 (1989)
|
||||
|
||||
|
||||
|
||||
rotatedRectangleIntersection
|
||||
-------------------------------
|
||||
Finds out if there is any intersection between two rotated rectangles. If there is then the vertices of the interesecting region are returned as well.
|
||||
|
||||
.. ocv:function:: int rotatedRectangleIntersection( const RotatedRect& rect1, const RotatedRect& rect2, OutputArray intersectingRegion )
|
||||
.. ocv:pyfunction:: cv2.rotatedRectangleIntersection( rect1, rect2 ) -> retval, intersectingRegion
|
||||
|
||||
:param rect1: First rectangle
|
||||
|
||||
:param rect2: Second rectangle
|
||||
|
||||
:param intersectingRegion: The output array of the verticies of the intersecting region. It returns at most 8 vertices. Stored as ``std::vector<cv::Point2f>`` or ``cv::Mat`` as Mx1 of type CV_32FC2.
|
||||
|
||||
:param pointCount: The number of vertices.
|
||||
|
||||
The following values are returned by the function:
|
||||
|
||||
* INTERSECT_NONE=0 - No intersection
|
||||
|
||||
* INTERSECT_PARTIAL=1 - There is a partial intersection
|
||||
|
||||
* INTERSECT_FULL=2 - One of the rectangle is fully enclosed in the other
|
||||
|
||||
Below are some examples of intersection configurations. The hatched pattern indicates the intersecting region and the red vertices are returned by the function.
|
||||
|
||||
.. image:: pics/intersection.png
|
||||
@@ -271,7 +271,8 @@ enum InterpolationFlags{
|
||||
WARP_INVERSE_MAP = 16
|
||||
};
|
||||
|
||||
enum { INTER_BITS = 5,
|
||||
enum InterpolationMasks {
|
||||
INTER_BITS = 5,
|
||||
INTER_BITS2 = INTER_BITS * 2,
|
||||
INTER_TAB_SIZE = 1 << INTER_BITS,
|
||||
INTER_TAB_SIZE2 = INTER_TAB_SIZE * INTER_TAB_SIZE
|
||||
@@ -329,7 +330,8 @@ enum AdaptiveThresholdTypes {
|
||||
};
|
||||
|
||||
//! cv::undistort mode
|
||||
enum { PROJ_SPHERICAL_ORTHO = 0,
|
||||
enum UndistortTypes {
|
||||
PROJ_SPHERICAL_ORTHO = 0,
|
||||
PROJ_SPHERICAL_EQRECT = 1
|
||||
};
|
||||
|
||||
|
||||
@@ -894,9 +894,139 @@ struct VResizeCubicVec_32f
|
||||
}
|
||||
};
|
||||
|
||||
#if CV_SSE4_1
|
||||
|
||||
struct VResizeLanczos4Vec_32f16u
|
||||
{
|
||||
int operator()(const uchar** _src, uchar* _dst, const uchar* _beta, int width ) const
|
||||
{
|
||||
const float** src = (const float**)_src;
|
||||
const float* beta = (const float*)_beta;
|
||||
const float *S0 = src[0], *S1 = src[1], *S2 = src[2], *S3 = src[3],
|
||||
*S4 = src[4], *S5 = src[5], *S6 = src[6], *S7 = src[7];
|
||||
short * dst = (short*)_dst;
|
||||
int x = 0;
|
||||
__m128 v_b0 = _mm_set1_ps(beta[0]), v_b1 = _mm_set1_ps(beta[1]),
|
||||
v_b2 = _mm_set1_ps(beta[2]), v_b3 = _mm_set1_ps(beta[3]),
|
||||
v_b4 = _mm_set1_ps(beta[4]), v_b5 = _mm_set1_ps(beta[5]),
|
||||
v_b6 = _mm_set1_ps(beta[6]), v_b7 = _mm_set1_ps(beta[7]);
|
||||
|
||||
for( ; x <= width - 8; x += 8 )
|
||||
{
|
||||
__m128 v_dst0 = _mm_mul_ps(v_b0, _mm_loadu_ps(S0 + x));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b1, _mm_loadu_ps(S1 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b2, _mm_loadu_ps(S2 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b3, _mm_loadu_ps(S3 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b4, _mm_loadu_ps(S4 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b5, _mm_loadu_ps(S5 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b6, _mm_loadu_ps(S6 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b7, _mm_loadu_ps(S7 + x)));
|
||||
|
||||
__m128 v_dst1 = _mm_mul_ps(v_b0, _mm_loadu_ps(S0 + x + 4));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b1, _mm_loadu_ps(S1 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b2, _mm_loadu_ps(S2 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b3, _mm_loadu_ps(S3 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b4, _mm_loadu_ps(S4 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b5, _mm_loadu_ps(S5 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b6, _mm_loadu_ps(S6 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b7, _mm_loadu_ps(S7 + x + 4)));
|
||||
|
||||
__m128i v_dsti0 = _mm_cvtps_epi32(v_dst0);
|
||||
__m128i v_dsti1 = _mm_cvtps_epi32(v_dst1);
|
||||
|
||||
_mm_storeu_si128((__m128i *)(dst + x), _mm_packus_epi32(v_dsti0, v_dsti1));
|
||||
}
|
||||
|
||||
return x;
|
||||
}
|
||||
};
|
||||
|
||||
#else
|
||||
|
||||
typedef VResizeNoVec VResizeLanczos4Vec_32f16u;
|
||||
typedef VResizeNoVec VResizeLanczos4Vec_32f16s;
|
||||
typedef VResizeNoVec VResizeLanczos4Vec_32f;
|
||||
|
||||
#endif
|
||||
|
||||
struct VResizeLanczos4Vec_32f16s
|
||||
{
|
||||
int operator()(const uchar** _src, uchar* _dst, const uchar* _beta, int width ) const
|
||||
{
|
||||
const float** src = (const float**)_src;
|
||||
const float* beta = (const float*)_beta;
|
||||
const float *S0 = src[0], *S1 = src[1], *S2 = src[2], *S3 = src[3],
|
||||
*S4 = src[4], *S5 = src[5], *S6 = src[6], *S7 = src[7];
|
||||
short * dst = (short*)_dst;
|
||||
int x = 0;
|
||||
__m128 v_b0 = _mm_set1_ps(beta[0]), v_b1 = _mm_set1_ps(beta[1]),
|
||||
v_b2 = _mm_set1_ps(beta[2]), v_b3 = _mm_set1_ps(beta[3]),
|
||||
v_b4 = _mm_set1_ps(beta[4]), v_b5 = _mm_set1_ps(beta[5]),
|
||||
v_b6 = _mm_set1_ps(beta[6]), v_b7 = _mm_set1_ps(beta[7]);
|
||||
|
||||
for( ; x <= width - 8; x += 8 )
|
||||
{
|
||||
__m128 v_dst0 = _mm_mul_ps(v_b0, _mm_loadu_ps(S0 + x));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b1, _mm_loadu_ps(S1 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b2, _mm_loadu_ps(S2 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b3, _mm_loadu_ps(S3 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b4, _mm_loadu_ps(S4 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b5, _mm_loadu_ps(S5 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b6, _mm_loadu_ps(S6 + x)));
|
||||
v_dst0 = _mm_add_ps(v_dst0, _mm_mul_ps(v_b7, _mm_loadu_ps(S7 + x)));
|
||||
|
||||
__m128 v_dst1 = _mm_mul_ps(v_b0, _mm_loadu_ps(S0 + x + 4));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b1, _mm_loadu_ps(S1 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b2, _mm_loadu_ps(S2 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b3, _mm_loadu_ps(S3 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b4, _mm_loadu_ps(S4 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b5, _mm_loadu_ps(S5 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b6, _mm_loadu_ps(S6 + x + 4)));
|
||||
v_dst1 = _mm_add_ps(v_dst1, _mm_mul_ps(v_b7, _mm_loadu_ps(S7 + x + 4)));
|
||||
|
||||
__m128i v_dsti0 = _mm_cvtps_epi32(v_dst0);
|
||||
__m128i v_dsti1 = _mm_cvtps_epi32(v_dst1);
|
||||
|
||||
_mm_storeu_si128((__m128i *)(dst + x), _mm_packs_epi32(v_dsti0, v_dsti1));
|
||||
}
|
||||
|
||||
return x;
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
struct VResizeLanczos4Vec_32f
|
||||
{
|
||||
int operator()(const uchar** _src, uchar* _dst, const uchar* _beta, int width ) const
|
||||
{
|
||||
const float** src = (const float**)_src;
|
||||
const float* beta = (const float*)_beta;
|
||||
const float *S0 = src[0], *S1 = src[1], *S2 = src[2], *S3 = src[3],
|
||||
*S4 = src[4], *S5 = src[5], *S6 = src[6], *S7 = src[7];
|
||||
float* dst = (float*)_dst;
|
||||
int x = 0;
|
||||
|
||||
__m128 v_b0 = _mm_set1_ps(beta[0]), v_b1 = _mm_set1_ps(beta[1]),
|
||||
v_b2 = _mm_set1_ps(beta[2]), v_b3 = _mm_set1_ps(beta[3]),
|
||||
v_b4 = _mm_set1_ps(beta[4]), v_b5 = _mm_set1_ps(beta[5]),
|
||||
v_b6 = _mm_set1_ps(beta[6]), v_b7 = _mm_set1_ps(beta[7]);
|
||||
|
||||
for( ; x <= width - 4; x += 4 )
|
||||
{
|
||||
__m128 v_dst = _mm_mul_ps(v_b0, _mm_loadu_ps(S0 + x));
|
||||
v_dst = _mm_add_ps(v_dst, _mm_mul_ps(v_b1, _mm_loadu_ps(S1 + x)));
|
||||
v_dst = _mm_add_ps(v_dst, _mm_mul_ps(v_b2, _mm_loadu_ps(S2 + x)));
|
||||
v_dst = _mm_add_ps(v_dst, _mm_mul_ps(v_b3, _mm_loadu_ps(S3 + x)));
|
||||
v_dst = _mm_add_ps(v_dst, _mm_mul_ps(v_b4, _mm_loadu_ps(S4 + x)));
|
||||
v_dst = _mm_add_ps(v_dst, _mm_mul_ps(v_b5, _mm_loadu_ps(S5 + x)));
|
||||
v_dst = _mm_add_ps(v_dst, _mm_mul_ps(v_b6, _mm_loadu_ps(S6 + x)));
|
||||
v_dst = _mm_add_ps(v_dst, _mm_mul_ps(v_b7, _mm_loadu_ps(S7 + x)));
|
||||
|
||||
_mm_storeu_ps(dst + x, v_dst);
|
||||
}
|
||||
|
||||
return x;
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
#elif CV_NEON
|
||||
|
||||
@@ -4071,6 +4201,10 @@ public:
|
||||
uint16x8_t v_scale = vdupq_n_u16(INTER_TAB_SIZE2-1);
|
||||
for ( ; x1 <= bcols - 8; x1 += 8)
|
||||
vst1q_u16(A + x1, vandq_u16(vld1q_u16(sA + x1), v_scale));
|
||||
#elif CV_SSE2
|
||||
__m128i v_scale = _mm_set1_epi16(INTER_TAB_SIZE2-1);
|
||||
for ( ; x1 <= bcols - 8; x1 += 8)
|
||||
_mm_storeu_si128((__m128i *)(A + x1), _mm_and_si128(_mm_loadu_si128((const __m128i *)(sA + x1)), v_scale));
|
||||
#endif
|
||||
|
||||
for( ; x1 < bcols; x1++ )
|
||||
|
||||
@@ -79,7 +79,7 @@ static bool findCircle( Point2f pt0, Point2f pt1, Point2f pt2,
|
||||
}
|
||||
|
||||
center->x = center->y = 0.f;
|
||||
radius = 0;
|
||||
*radius = 0;
|
||||
return false;
|
||||
}
|
||||
|
||||
|
||||
@@ -50,6 +50,99 @@ static IppStatus sts = ippInit();
|
||||
namespace cv
|
||||
{
|
||||
|
||||
template <typename T, typename ST, typename QT>
|
||||
struct Integral_SIMD
|
||||
{
|
||||
bool operator()(const T *, size_t,
|
||||
ST *, size_t,
|
||||
QT *, size_t,
|
||||
ST *, size_t,
|
||||
Size, int) const
|
||||
{
|
||||
return false;
|
||||
}
|
||||
};
|
||||
|
||||
#if CV_SSE2
|
||||
|
||||
template <>
|
||||
struct Integral_SIMD<uchar, int, double>
|
||||
{
|
||||
Integral_SIMD()
|
||||
{
|
||||
haveSSE2 = checkHardwareSupport(CV_CPU_SSE2);
|
||||
}
|
||||
|
||||
bool operator()(const uchar * src, size_t _srcstep,
|
||||
int * sum, size_t _sumstep,
|
||||
double * sqsum, size_t,
|
||||
int * tilted, size_t,
|
||||
Size size, int cn) const
|
||||
{
|
||||
if (sqsum || tilted || cn != 1 || !haveSSE2)
|
||||
return false;
|
||||
|
||||
// the first iteration
|
||||
memset(sum, 0, (size.width + 1) * sizeof(int));
|
||||
|
||||
__m128i v_zero = _mm_setzero_si128(), prev = v_zero;
|
||||
int j = 0;
|
||||
|
||||
// the others
|
||||
for (int i = 0; i < size.height; ++i)
|
||||
{
|
||||
const uchar * src_row = src + _srcstep * i;
|
||||
int * prev_sum_row = (int *)((uchar *)sum + _sumstep * i) + 1;
|
||||
int * sum_row = (int *)((uchar *)sum + _sumstep * (i + 1)) + 1;
|
||||
|
||||
sum_row[-1] = 0;
|
||||
|
||||
prev = v_zero;
|
||||
j = 0;
|
||||
|
||||
for ( ; j + 7 < size.width; j += 8)
|
||||
{
|
||||
__m128i vsuml = _mm_loadu_si128((const __m128i *)(prev_sum_row + j));
|
||||
__m128i vsumh = _mm_loadu_si128((const __m128i *)(prev_sum_row + j + 4));
|
||||
|
||||
__m128i el8shr0 = _mm_loadl_epi64((const __m128i *)(src_row + j));
|
||||
__m128i el8shr1 = _mm_slli_si128(el8shr0, 1);
|
||||
__m128i el8shr2 = _mm_slli_si128(el8shr0, 2);
|
||||
__m128i el8shr3 = _mm_slli_si128(el8shr0, 3);
|
||||
|
||||
vsuml = _mm_add_epi32(vsuml, prev);
|
||||
vsumh = _mm_add_epi32(vsumh, prev);
|
||||
|
||||
__m128i el8shr12 = _mm_add_epi16(_mm_unpacklo_epi8(el8shr1, v_zero),
|
||||
_mm_unpacklo_epi8(el8shr2, v_zero));
|
||||
__m128i el8shr03 = _mm_add_epi16(_mm_unpacklo_epi8(el8shr0, v_zero),
|
||||
_mm_unpacklo_epi8(el8shr3, v_zero));
|
||||
__m128i el8 = _mm_add_epi16(el8shr12, el8shr03);
|
||||
|
||||
__m128i el4h = _mm_add_epi16(_mm_unpackhi_epi16(el8, v_zero),
|
||||
_mm_unpacklo_epi16(el8, v_zero));
|
||||
|
||||
vsuml = _mm_add_epi32(vsuml, _mm_unpacklo_epi16(el8, v_zero));
|
||||
vsumh = _mm_add_epi32(vsumh, el4h);
|
||||
|
||||
_mm_storeu_si128((__m128i *)(sum_row + j), vsuml);
|
||||
_mm_storeu_si128((__m128i *)(sum_row + j + 4), vsumh);
|
||||
|
||||
prev = _mm_add_epi32(prev, _mm_shuffle_epi32(el4h, _MM_SHUFFLE(3, 3, 3, 3)));
|
||||
}
|
||||
|
||||
for (int v = sum_row[j - 1] - prev_sum_row[j - 1]; j < size.width; ++j)
|
||||
sum_row[j] = (v += src_row[j]) + prev_sum_row[j];
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
bool haveSSE2;
|
||||
};
|
||||
|
||||
#endif
|
||||
|
||||
template<typename T, typename ST, typename QT>
|
||||
void integral_( const T* src, size_t _srcstep, ST* sum, size_t _sumstep,
|
||||
QT* sqsum, size_t _sqsumstep, ST* tilted, size_t _tiltedstep,
|
||||
@@ -57,6 +150,13 @@ void integral_( const T* src, size_t _srcstep, ST* sum, size_t _sumstep,
|
||||
{
|
||||
int x, y, k;
|
||||
|
||||
if (Integral_SIMD<T, ST, QT>()(src, _srcstep,
|
||||
sum, _sumstep,
|
||||
sqsum, _sqsumstep,
|
||||
tilted, _tiltedstep,
|
||||
size, cn))
|
||||
return;
|
||||
|
||||
int srcstep = (int)(_srcstep/sizeof(T));
|
||||
int sumstep = (int)(_sumstep/sizeof(ST));
|
||||
int tiltedstep = (int)(_tiltedstep/sizeof(ST));
|
||||
|
||||
@@ -32,8 +32,6 @@ endforeach()
|
||||
# scripts
|
||||
set(scripts_gen_java "${CMAKE_CURRENT_SOURCE_DIR}/generator/gen_java.py")
|
||||
set(scripts_hdr_parser "${CMAKE_CURRENT_SOURCE_DIR}/../python/src2/hdr_parser.py")
|
||||
set(scripts_gen_javadoc "${CMAKE_CURRENT_SOURCE_DIR}/generator/gen_javadoc.py")
|
||||
set(scripts_rst_parser "${CMAKE_CURRENT_SOURCE_DIR}/generator/rst_parser.py")
|
||||
|
||||
# handwritten C/C++ and Java sources
|
||||
file(GLOB handwrittren_h_sources "${CMAKE_CURRENT_SOURCE_DIR}/generator/src/cpp/*.h" "${CMAKE_CURRENT_SOURCE_DIR}/generator/src/cpp/*.hpp")
|
||||
@@ -75,13 +73,6 @@ foreach(module ${OPENCV_JAVA_MODULES})
|
||||
endif()
|
||||
endforeach()
|
||||
|
||||
# rst documentation used for javadoc generation
|
||||
set(javadoc_rst_sources "")
|
||||
foreach(module ${OPENCV_JAVA_MODULES})
|
||||
file(GLOB_RECURSE refman_rst_headers "${OPENCV_MODULE_opencv_${module}_LOCATION}/*.rst")
|
||||
list(APPEND javadoc_rst_sources ${refman_rst_headers})
|
||||
endforeach()
|
||||
|
||||
# generated cpp files
|
||||
set(generated_cpp_sources "")
|
||||
foreach(module ${OPENCV_JAVA_MODULES})
|
||||
@@ -112,13 +103,6 @@ foreach(module ${OPENCV_JAVA_MODULES})
|
||||
list(APPEND generated_java_sources ${generated_java_sources_${module}})
|
||||
endforeach()
|
||||
|
||||
# generated java files with javadoc
|
||||
set(documented_java_files "")
|
||||
foreach(java_file ${generated_java_sources} ${handwrittren_java_sources})
|
||||
get_filename_component(java_file_name "${java_file}" NAME_WE)
|
||||
list(APPEND documented_java_files "${CMAKE_CURRENT_BINARY_DIR}/${java_file_name}-jdoc.java")
|
||||
endforeach()
|
||||
|
||||
######################################################################################################################################
|
||||
|
||||
# step 1: generate .cpp/.java from OpenCV headers
|
||||
@@ -132,18 +116,8 @@ foreach(module ${OPENCV_JAVA_MODULES})
|
||||
)
|
||||
endforeach()
|
||||
|
||||
# step 2: generate javadoc comments
|
||||
set(step2_depends ${step1_depends} ${scripts_gen_javadoc} ${scripts_rst_parser} ${javadoc_rst_sources} ${generated_java_sources} ${handwrittren_java_sources})
|
||||
string(REPLACE ";" "," OPENCV_JAVA_MODULES_STR "${OPENCV_JAVA_MODULES}")
|
||||
add_custom_command(OUTPUT ${documented_java_files}
|
||||
COMMAND ${PYTHON_DEFUALT_EXECUTABLE} "${scripts_gen_javadoc}" --modules ${OPENCV_JAVA_MODULES_STR} "${CMAKE_CURRENT_SOURCE_DIR}/generator/src/java" "${CMAKE_CURRENT_BINARY_DIR}" 2> "${CMAKE_CURRENT_BINARY_DIR}/get_javadoc_errors.log"
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
DEPENDS ${step2_depends}
|
||||
VERBATIM
|
||||
)
|
||||
|
||||
# step 3: copy files to destination
|
||||
set(step3_input_files ${documented_java_files} ${handwrittren_aidl_sources})
|
||||
set(step3_input_files ${generated_java_sources} ${handwrittren_java_sources} ${handwrittren_aidl_sources})
|
||||
set(copied_files "")
|
||||
foreach(java_file ${step3_input_files})
|
||||
get_filename_component(java_file_name "${java_file}" NAME)
|
||||
@@ -154,7 +128,7 @@ foreach(java_file ${step3_input_files})
|
||||
add_custom_command(OUTPUT "${output_name}"
|
||||
COMMAND ${CMAKE_COMMAND} -E copy "${java_file}" "${output_name}"
|
||||
MAIN_DEPENDENCY "${java_file}"
|
||||
DEPENDS ${step2_depends}
|
||||
DEPENDS ${step1_depends} ${generated_java_sources} ${handwrittren_java_sources}
|
||||
COMMENT "Generating src/org/opencv/${java_file_name}"
|
||||
)
|
||||
list(APPEND copied_files "${output_name}")
|
||||
|
||||
@@ -1,290 +0,0 @@
|
||||
#!/usr/bin/env python
|
||||
|
||||
import os, sys, re, string, glob
|
||||
from optparse import OptionParser
|
||||
|
||||
# Black list for classes and methods that does not implemented in Java API
|
||||
# Created to exclude referencies to them in @see tag
|
||||
JAVADOC_ENTITY_BLACK_LIST = set(["org.opencv.core.Core#abs", \
|
||||
"org.opencv.core.Core#theRNG", \
|
||||
"org.opencv.core.Core#extractImageCOI", \
|
||||
"org.opencv.core.PCA", \
|
||||
"org.opencv.core.SVD", \
|
||||
"org.opencv.core.RNG", \
|
||||
"org.opencv.imgproc.Imgproc#createMorphologyFilter", \
|
||||
"org.opencv.imgproc.Imgproc#createLinearFilter", \
|
||||
"org.opencv.imgproc.Imgproc#createSeparableLinearFilter", \
|
||||
"org.opencv.imgproc.FilterEngine"])
|
||||
|
||||
class JavadocGenerator(object):
|
||||
def __init__(self, definitions = {}, modules= [], javadoc_marker = "//javadoc:"):
|
||||
self.definitions = definitions
|
||||
self.javadoc_marker = javadoc_marker
|
||||
self.markers_processed = 0
|
||||
self.markers_documented = 0
|
||||
self.params_documented = 0
|
||||
self.params_undocumented = 0
|
||||
self.known_modules = modules
|
||||
self.verbose = False
|
||||
self.show_warnings = True
|
||||
self.show_errors = True
|
||||
|
||||
def parceJavadocMarker(self, line):
|
||||
assert line.lstrip().startswith(self.javadoc_marker)
|
||||
offset = line[:line.find(self.javadoc_marker)]
|
||||
line = line.strip()[len(self.javadoc_marker):]
|
||||
args_start = line.rfind("(")
|
||||
args_end = line.rfind(")")
|
||||
assert args_start * args_end > 0
|
||||
if args_start >= 0:
|
||||
assert args_start < args_end
|
||||
name = line[:args_start].strip()
|
||||
if name.startswith("java"):
|
||||
name = name[4:]
|
||||
return (name, offset, filter(None, list(arg.strip() for arg in line[args_start+1:args_end].split(","))))
|
||||
name = line.strip()
|
||||
if name.startswith("java"):
|
||||
name = name[4:]
|
||||
return (name, offset, [])
|
||||
|
||||
def document(self, infile, outfile):
|
||||
inf = open(infile, "rt")
|
||||
outf = open(outfile, "wt")
|
||||
module = os.path.splitext(os.path.basename(infile))[0].split("+")[0]
|
||||
if module not in self.known_modules:
|
||||
module = "unknown"
|
||||
try:
|
||||
for l in inf.readlines():
|
||||
org = l
|
||||
l = l.replace(" ", "").replace("\t", "")#remove all whitespace
|
||||
if l.startswith(self.javadoc_marker):
|
||||
marker = self.parceJavadocMarker(l)
|
||||
self.markers_processed += 1
|
||||
decl = self.definitions.get(marker[0],None)
|
||||
if decl:
|
||||
javadoc = self.makeJavadoc(decl, marker[2])
|
||||
if self.verbose:
|
||||
print
|
||||
print("Javadoc for \"%s\" File: %s line %s" % (decl["name"], decl["file"], decl["line"]))
|
||||
print(javadoc)
|
||||
for line in javadoc.split("\n"):
|
||||
outf.write(marker[1] + line + "\n")
|
||||
self.markers_documented += 1
|
||||
elif self.show_errors:
|
||||
sys.stderr.write("gen_javadoc error: could not find documentation for %s (module: %s)" % (l.lstrip()[len(self.javadoc_marker):-1].strip(), module))
|
||||
else:
|
||||
outf.write(org.replace("\t", " ").rstrip()+"\n")
|
||||
except:
|
||||
inf.close()
|
||||
outf.close()
|
||||
os.remove(outfile)
|
||||
raise
|
||||
else:
|
||||
inf.close()
|
||||
outf.close()
|
||||
|
||||
def FinishParagraph(self, text):
|
||||
return text[:-1] + "</p>\n"
|
||||
|
||||
def ReformatForJavadoc(self, s):
|
||||
out = ""
|
||||
in_paragraph = False
|
||||
in_list = False
|
||||
for term in s.split("\n"):
|
||||
in_list_item = False
|
||||
if term.startswith("*"):
|
||||
in_list_item = True
|
||||
if in_paragraph:
|
||||
out = self.FinishParagraph(out)
|
||||
in_paragraph = False
|
||||
if not in_list:
|
||||
out += " * <ul>\n"
|
||||
in_list = True
|
||||
term = " <li>" + term[1:]
|
||||
|
||||
if term.startswith("#."):
|
||||
in_list_item = True
|
||||
if in_paragraph:
|
||||
out = self.FinishParagraph(out)
|
||||
in_paragraph = False
|
||||
if not in_list:
|
||||
out += " * <ul>\n"
|
||||
in_list = True
|
||||
term = " <li>" + term[2:]
|
||||
|
||||
if not term:
|
||||
if in_paragraph:
|
||||
out = self.FinishParagraph(out)
|
||||
in_paragraph = False
|
||||
out += " *\n"
|
||||
else:
|
||||
if in_list and not in_list_item:
|
||||
in_list = False
|
||||
if out.endswith(" *\n"):
|
||||
out = out[:-3] + " * </ul>\n *\n"
|
||||
else:
|
||||
out += " * </ul>\n"
|
||||
pos_start = 0
|
||||
pos_end = min(77, len(term)-1)
|
||||
while pos_start < pos_end:
|
||||
if pos_end - pos_start == 77:
|
||||
while pos_end >= pos_start+60:
|
||||
if not term[pos_end].isspace():
|
||||
pos_end -= 1
|
||||
else:
|
||||
break
|
||||
if pos_end < pos_start+60:
|
||||
pos_end = min(pos_start + 77, len(term)-1)
|
||||
while pos_end < len(term):
|
||||
if not term[pos_end].isspace():
|
||||
pos_end += 1
|
||||
else:
|
||||
break
|
||||
if in_paragraph or term.startswith("@") or in_list_item:
|
||||
out += " * "
|
||||
else:
|
||||
in_paragraph = True
|
||||
out += " * <p>"
|
||||
out += term[pos_start:pos_end+1].rstrip() + "\n"
|
||||
pos_start = pos_end + 1
|
||||
pos_end = min(pos_start + 77, len(term)-1)
|
||||
|
||||
if in_paragraph:
|
||||
out = self.FinishParagraph(out)
|
||||
if in_list:
|
||||
out += " * </ul>\n"
|
||||
return out
|
||||
|
||||
def getJavaName(self, decl, methodSeparator = "."):
|
||||
name = "org.opencv."
|
||||
name += decl["module"]
|
||||
if "class" in decl:
|
||||
name += "." + decl["class"]
|
||||
else:
|
||||
name += "." + decl["module"].capitalize()
|
||||
if "method" in decl:
|
||||
name += methodSeparator + decl["method"]
|
||||
return name
|
||||
|
||||
def getDocURL(self, decl):
|
||||
url = "http://docs.opencv.org/modules/"
|
||||
url += decl["module"]
|
||||
url += "/doc/"
|
||||
url += os.path.basename(decl["file"]).replace(".rst",".html")
|
||||
url += "#" + decl["name"].replace("::","-").replace("()","").replace("=","").strip().rstrip("_").replace(" ","-").replace("_","-").lower()
|
||||
return url
|
||||
|
||||
def makeJavadoc(self, decl, args = None):
|
||||
doc = ""
|
||||
prefix = "/**\n"
|
||||
|
||||
if decl.get("isclass", False):
|
||||
decl_type = "class"
|
||||
elif decl.get("isstruct", False):
|
||||
decl_type = "struct"
|
||||
elif "class" in decl:
|
||||
decl_type = "method"
|
||||
else:
|
||||
decl_type = "function"
|
||||
|
||||
# brief goes first
|
||||
if "brief" in decl:
|
||||
doc += prefix + self.ReformatForJavadoc(decl["brief"])
|
||||
prefix = " *\n"
|
||||
elif "long" not in decl:
|
||||
if self.show_warnings:
|
||||
print >> sys.stderr, "gen_javadoc warning: no description for " + decl_type + " \"%s\" File: %s (line %s)" % (func["name"], func["file"], func["line"])
|
||||
doc += prefix + self.ReformatForJavadoc("This " + decl_type + " is undocumented")
|
||||
prefix = " *\n"
|
||||
|
||||
# long goes after brief
|
||||
if "long" in decl:
|
||||
doc += prefix + self.ReformatForJavadoc(decl["long"])
|
||||
prefix = " *\n"
|
||||
|
||||
# @param tags
|
||||
if args and (decl_type == "method" or decl_type == "function"):
|
||||
documented_params = decl.get("params",{})
|
||||
for arg in args:
|
||||
arg_doc = documented_params.get(arg, None)
|
||||
if not arg_doc:
|
||||
arg_doc = "a " + arg
|
||||
if self.show_warnings:
|
||||
sys.stderr.write("gen_javadoc warning: parameter \"%s\" of \"%s\" is undocumented. File: %s (line %s)" % (arg, decl["name"], decl["file"], decl["line"]))
|
||||
self.params_undocumented += 1
|
||||
else:
|
||||
self.params_documented += 1
|
||||
doc += prefix + self.ReformatForJavadoc("@param " + arg + " " + arg_doc)
|
||||
prefix = ""
|
||||
prefix = " *\n"
|
||||
|
||||
# @see tags
|
||||
# always link to documentation
|
||||
doc += prefix + " * @see <a href=\"" + self.getDocURL(decl) + "\">" + self.getJavaName(decl) + "</a>\n"
|
||||
prefix = ""
|
||||
# other links
|
||||
if "seealso" in decl:
|
||||
for see in decl["seealso"]:
|
||||
seedecl = self.definitions.get(see,None)
|
||||
if seedecl:
|
||||
javadoc_name = self.getJavaName(seedecl, "#")
|
||||
if (javadoc_name not in JAVADOC_ENTITY_BLACK_LIST):
|
||||
doc += prefix + " * @see " + javadoc_name + "\n"
|
||||
prefix = " *\n"
|
||||
|
||||
#doc += prefix + " * File: " + decl["file"] + " (line " + str(decl["line"]) + ")\n"
|
||||
|
||||
return (doc + " */").replace("::",".")
|
||||
|
||||
def printSummary(self):
|
||||
print("Javadoc Generator Summary:")
|
||||
print(" Total markers: %s" % self.markers_processed)
|
||||
print( " Undocumented markers: %s" % (self.markers_processed - self.markers_documented))
|
||||
print( " Generated comments: %s" % self.markers_documented)
|
||||
|
||||
print
|
||||
print(" Documented params: %s" % self.params_documented)
|
||||
print(" Undocumented params: %s" % self.params_undocumented)
|
||||
print
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
selfpath = os.path.dirname(os.path.abspath(sys.argv[0]))
|
||||
hdr_parser_path = os.path.join(selfpath, "../../python/src2")
|
||||
|
||||
sys.path.append(selfpath)
|
||||
sys.path.append(hdr_parser_path)
|
||||
import hdr_parser
|
||||
import rst_parser
|
||||
|
||||
parser = OptionParser()
|
||||
parser.add_option("-v", "--verbose", dest="verbose", help="Print verbose log to stdout", action="store_true", default=False)
|
||||
parser.add_option("", "--no-warnings", dest="warnings", help="Hide warning messages", action="store_false", default=True)
|
||||
parser.add_option("", "--no-errors", dest="errors", help="Hide error messages", action="store_false", default=True)
|
||||
parser.add_option("", "--modules", dest="modules", help="comma-separated list of modules to generate comments", metavar="MODS", default=",".join(rst_parser.allmodules))
|
||||
|
||||
(options, args) = parser.parse_args(sys.argv)
|
||||
options.modules = options.modules.split(",")
|
||||
|
||||
if len(args) < 2 or len(options.modules) < 1:
|
||||
parser.print_help()
|
||||
exit(0)
|
||||
|
||||
parser = rst_parser.RstParser(hdr_parser.CppHeaderParser())
|
||||
for m in options.modules:
|
||||
parser.parse(m, os.path.join(selfpath, "../../" + m))
|
||||
|
||||
parser.printSummary()
|
||||
|
||||
generator = JavadocGenerator(parser.definitions, options.modules)
|
||||
generator.verbose = options.verbose
|
||||
generator.show_warnings = options.warnings
|
||||
generator.show_errors = options.errors
|
||||
|
||||
for path in args:
|
||||
folder = os.path.abspath(path)
|
||||
for jfile in [f for f in glob.glob(os.path.join(folder,"*.java")) if not f.endswith("-jdoc.java")]:
|
||||
outfile = os.path.abspath(os.path.basename(jfile).replace(".java", "-jdoc.java"))
|
||||
generator.document(jfile, outfile)
|
||||
|
||||
generator.printSummary()
|
||||
@@ -1,774 +0,0 @@
|
||||
#!/usr/bin/env python
|
||||
|
||||
from __future__ import print_function
|
||||
import os, sys, re, string, fnmatch
|
||||
allmodules = ["core", "flann", "imgproc", "imgcodecs", "videoio", "highgui", "video", "features2d", "calib3d", "objdetect", "legacy", "contrib", "cuda", "androidcamera", "java", "python", "stitching", "ts", "photo", "videostab", "softcascade", "superres"]
|
||||
verbose = False
|
||||
show_warnings = True
|
||||
show_errors = True
|
||||
show_critical_errors = True
|
||||
|
||||
params_blacklist = {
|
||||
"fromarray" : ("object", "allowND"), # python only function
|
||||
"reprojectImageTo3D" : ("ddepth"), # python only argument
|
||||
"composeRT" : ("d*d*"), # wildchards in parameter names are not supported by this parser
|
||||
"error" : "args", # parameter of supporting macro
|
||||
"getConvertElem" : ("from", "cn", "to", "beta", "alpha"), # arguments of returned functions
|
||||
"gpu::swapChannels" : ("dstOrder") # parameter is not parsed correctly by the hdr_parser
|
||||
}
|
||||
|
||||
ERROR_001_SECTIONFAILURE = 1
|
||||
WARNING_002_HDRWHITESPACE = 2
|
||||
ERROR_003_PARENTHESES = 3
|
||||
WARNING_004_TABS = 4
|
||||
ERROR_005_REDEFENITIONPARAM = 5
|
||||
ERROR_006_REDEFENITIONFUNC = 6
|
||||
WARNING_007_UNDOCUMENTEDPARAM = 7
|
||||
WARNING_008_MISSINGPARAM = 8
|
||||
WARNING_009_HDRMISMATCH = 9
|
||||
ERROR_010_NOMODULE = 10
|
||||
ERROR_011_EOLEXPECTED = 11
|
||||
|
||||
params_mapping = {
|
||||
"composeRT" : {
|
||||
"dr3dr1" : "d*d*",
|
||||
"dr3dr2" : "d*d*",
|
||||
"dr3dt1" : "d*d*",
|
||||
"dr3dt2" : "d*d*",
|
||||
"dt3dr1" : "d*d*",
|
||||
"dt3dr2" : "d*d*",
|
||||
"dt3dt1" : "d*d*",
|
||||
"dt3dt2" : "d*d*"
|
||||
},
|
||||
"CvSVM::train_auto" : {
|
||||
"coeffGrid" : "\\*Grid",
|
||||
"degreeGrid" : "\\*Grid",
|
||||
"gammaGrid" : "\\*Grid",
|
||||
"nuGrid" : "\\*Grid",
|
||||
"pGrid" : "\\*Grid"
|
||||
}
|
||||
}
|
||||
|
||||
known_text_sections_names = ["Appendix", "Results", "Prerequisites", "Introduction", "Description"]
|
||||
|
||||
class DeclarationParser(object):
|
||||
def __init__(self, line=None):
|
||||
if line is None:
|
||||
self.fdecl = ""
|
||||
self.lang = ""
|
||||
self.balance = 0
|
||||
return
|
||||
self.lang = self.getLang(line)
|
||||
assert self.lang is not None
|
||||
self.fdecl = line[line.find("::")+2:].strip()
|
||||
self.balance = self.fdecl.count("(") - self.fdecl.count(")")
|
||||
assert self.balance >= 0
|
||||
|
||||
def append(self, line):
|
||||
self.fdecl += line
|
||||
self.balance = self.fdecl.count("(") - self.fdecl.count(")")
|
||||
|
||||
def isready(self):
|
||||
return self.balance == 0
|
||||
|
||||
@classmethod
|
||||
def getLang(cls, line):
|
||||
if line.startswith(".. ocv:function::"):
|
||||
return "C++"
|
||||
if line.startswith(".. ocv:cfunction::"):
|
||||
return "C"
|
||||
if line.startswith(".. ocv:pyfunction::"):
|
||||
return "Python2"
|
||||
if line.startswith(".. ocv:jfunction::"):
|
||||
return "Java"
|
||||
return None
|
||||
|
||||
def hasDeclaration(self, line):
|
||||
return self.getLang(line) is not None
|
||||
|
||||
class ParamParser(object):
|
||||
def __init__(self, line=None):
|
||||
if line is None:
|
||||
self.prefix = ""
|
||||
self.name = ""
|
||||
self.comment = ""
|
||||
self.active = False
|
||||
return
|
||||
offset = line.find(":param")
|
||||
assert offset > 0
|
||||
self.prefix = line[:offset]
|
||||
assert self.prefix == " "*len(self.prefix), ":param definition should be prefixed with spaces"
|
||||
line = line[offset + 6:].lstrip()
|
||||
name_end = line.find(":")
|
||||
assert name_end > 0
|
||||
self.name = line[:name_end]
|
||||
self.comment = line[name_end+1:].lstrip()
|
||||
self.active = True
|
||||
|
||||
def append(self, line):
|
||||
assert self.active
|
||||
if (self.hasDeclaration(line)):
|
||||
self.active = False
|
||||
elif line.startswith(self.prefix) or not line:
|
||||
self.comment += "\n" + line.lstrip()
|
||||
else:
|
||||
self.active = False
|
||||
|
||||
@classmethod
|
||||
def hasDeclaration(cls, line):
|
||||
return line.lstrip().startswith(":param")
|
||||
|
||||
class RstParser(object):
|
||||
def __init__(self, cpp_parser):
|
||||
self.cpp_parser = cpp_parser
|
||||
self.definitions = {}
|
||||
self.sections_parsed = 0
|
||||
self.sections_total = 0
|
||||
self.sections_skipped = 0
|
||||
|
||||
def parse(self, module_name, module_path=None):
|
||||
if module_path is None:
|
||||
module_path = "../" + module_name
|
||||
|
||||
doclist = []
|
||||
for root, dirs, files in os.walk(os.path.join(module_path,"doc")):
|
||||
for filename in fnmatch.filter(files, "*.rst"):
|
||||
doclist.append(os.path.join(root, filename))
|
||||
|
||||
for doc in doclist:
|
||||
self.parse_rst_file(module_name, doc)
|
||||
|
||||
def parse_section_safe(self, module_name, section_name, file_name, lineno, lines):
|
||||
try:
|
||||
self.parse_section(module_name, section_name, file_name, lineno, lines)
|
||||
except AssertionError as args:
|
||||
if show_errors:
|
||||
print("RST parser error E%03d: assertion in \"%s\" at %s:%s" % (ERROR_001_SECTIONFAILURE, section_name, file_name, lineno), file=sys.stderr)
|
||||
print(" Details: %s" % args, file=sys.stderr)
|
||||
|
||||
def parse_section(self, module_name, section_name, file_name, lineno, lines):
|
||||
self.sections_total += 1
|
||||
# skip sections having whitespace in name
|
||||
#if section_name.find(" ") >= 0 and section_name.find("::operator") < 0:
|
||||
if (section_name.find(" ") >= 0 and not bool(re.match(r"(\w+::)*operator\s*(\w+|>>|<<|\(\)|->|\+\+|--|=|==|\+=|-=)", section_name)) ) or section_name.endswith(":"):
|
||||
if show_errors:
|
||||
print("RST parser warning W%03d: SKIPPED: \"%s\" File: %s:%s" % (WARNING_002_HDRWHITESPACE, section_name, file_name, lineno), file=sys.stderr)
|
||||
self.sections_skipped += 1
|
||||
return
|
||||
|
||||
func = {}
|
||||
func["name"] = section_name
|
||||
func["file"] = file_name
|
||||
func["line"] = lineno
|
||||
func["module"] = module_name
|
||||
|
||||
# parse section name
|
||||
section_name = self.parse_namespace(func, section_name)
|
||||
class_separator_idx = section_name.find("::")
|
||||
if class_separator_idx > 0:
|
||||
func["class"] = section_name[:class_separator_idx]
|
||||
func["method"] = section_name[class_separator_idx+2:]
|
||||
else:
|
||||
func["method"] = section_name
|
||||
|
||||
capturing_seealso = False
|
||||
skip_code_lines = False
|
||||
expected_brief = True
|
||||
was_code_line = False
|
||||
fdecl = DeclarationParser()
|
||||
pdecl = ParamParser()
|
||||
ll = None
|
||||
|
||||
for l in lines:
|
||||
# read tail of function/method declaration if needed
|
||||
if not fdecl.isready():
|
||||
fdecl.append(ll)
|
||||
if fdecl.isready():
|
||||
self.add_new_fdecl(func, fdecl)
|
||||
continue
|
||||
|
||||
# continue capture seealso
|
||||
if capturing_seealso:
|
||||
if not l or l.startswith(" "):
|
||||
seealso = func.get("seealso", [])
|
||||
seealso.extend(l.split(","))
|
||||
func["seealso"] = seealso
|
||||
continue
|
||||
else:
|
||||
capturing_seealso = False
|
||||
|
||||
ll = l.strip()
|
||||
if ll == "..":
|
||||
expected_brief = False
|
||||
skip_code_lines = False
|
||||
continue
|
||||
|
||||
# skip lines if line-skipping mode is activated
|
||||
if skip_code_lines:
|
||||
if not l:
|
||||
continue
|
||||
if not l.startswith(" "):
|
||||
skip_code_lines = False
|
||||
|
||||
if ll.startswith(".. code-block::") or ll.startswith(".. image::"):
|
||||
skip_code_lines = True
|
||||
|
||||
continue
|
||||
|
||||
# todo: parse structure members; skip them for now
|
||||
if ll.startswith(".. ocv:member::"):
|
||||
#print ll
|
||||
skip_code_lines = True
|
||||
continue
|
||||
|
||||
#ignore references (todo: collect them)
|
||||
if l.startswith(".. ["):
|
||||
continue
|
||||
|
||||
if ll.startswith(".. "):
|
||||
expected_brief = False
|
||||
elif ll.endswith("::"):
|
||||
# turn on line-skipping mode for code fragments
|
||||
#print ll
|
||||
skip_code_lines = True
|
||||
ll = ll[:len(ll)-2]
|
||||
|
||||
# continue param parsing (process params after processing .. at the beginning of the line and :: at the end)
|
||||
if pdecl.active:
|
||||
pdecl.append(l)
|
||||
if pdecl.active:
|
||||
continue
|
||||
else:
|
||||
self.add_new_pdecl(func, pdecl)
|
||||
# do not continue - current line can contain next parameter definition
|
||||
|
||||
# parse ".. seealso::" blocks
|
||||
if ll.startswith(".. seealso::"):
|
||||
if ll.endswith(".. seealso::"):
|
||||
capturing_seealso = True
|
||||
else:
|
||||
seealso = func.get("seealso", [])
|
||||
seealso.extend(ll[ll.find("::")+2:].split(","))
|
||||
func["seealso"] = seealso
|
||||
continue
|
||||
|
||||
# skip ".. index::"
|
||||
if ll.startswith(".. index::"):
|
||||
continue
|
||||
|
||||
# parse class & struct definitions
|
||||
if ll.startswith(".. ocv:class::"):
|
||||
func["class"] = ll[ll.find("::")+2:].strip()
|
||||
if "method" in func:
|
||||
del func["method"]
|
||||
func["isclass"] = True
|
||||
expected_brief = True
|
||||
continue
|
||||
|
||||
if ll.startswith(".. ocv:struct::"):
|
||||
func["class"] = ll[ll.find("::")+2:].strip()
|
||||
if "method" in func:
|
||||
del func["method"]
|
||||
func["isstruct"] = True
|
||||
expected_brief = True
|
||||
continue
|
||||
|
||||
# parse function/method definitions
|
||||
if fdecl.hasDeclaration(ll):
|
||||
fdecl = DeclarationParser(ll)
|
||||
if fdecl.isready():
|
||||
self.add_new_fdecl(func, fdecl)
|
||||
continue
|
||||
|
||||
# parse parameters
|
||||
if pdecl.hasDeclaration(l):
|
||||
pdecl = ParamParser(l)
|
||||
continue
|
||||
|
||||
# record brief description
|
||||
if expected_brief:
|
||||
func["brief"] = func.get("brief", "") + "\n" + ll
|
||||
if skip_code_lines:
|
||||
expected_brief = False # force end brief if code block begins
|
||||
continue
|
||||
|
||||
# record other lines as long description
|
||||
if (skip_code_lines):
|
||||
ll = ll.replace("/*", "/ *")
|
||||
ll = ll.replace("*/", "* /")
|
||||
if (was_code_line):
|
||||
func["long"] = func.get("long", "") + "\n" + ll + "\n"
|
||||
else:
|
||||
was_code_line = True
|
||||
func["long"] = func.get("long", "") + ll +"\n<code>\n\n // C++ code:\n\n"
|
||||
else:
|
||||
if (was_code_line):
|
||||
func["long"] = func.get("long", "") + "\n" + ll + "\n</code>\n"
|
||||
was_code_line = False
|
||||
else:
|
||||
func["long"] = func.get("long", "") + "\n" + ll
|
||||
# endfor l in lines
|
||||
|
||||
if fdecl.balance != 0:
|
||||
if show_critical_errors:
|
||||
print("RST parser error E%03d: invalid parentheses balance in \"%s\" at %s:%s" % (ERROR_003_PARENTHESES, section_name, file_name, lineno), file=sys.stderr)
|
||||
return
|
||||
|
||||
# save last parameter if needed
|
||||
if pdecl.active:
|
||||
self.add_new_pdecl(func, pdecl)
|
||||
|
||||
# add definition to list
|
||||
func = self.normalize(func)
|
||||
if self.validate(func):
|
||||
self.definitions[func["name"]] = func
|
||||
self.sections_parsed += 1
|
||||
if verbose:
|
||||
self.print_info(func)
|
||||
elif func:
|
||||
if func["name"] in known_text_sections_names:
|
||||
if show_errors:
|
||||
print("RST parser warning W%03d: SKIPPED: \"%s\" File: %s:%s" % (WARNING_002_HDRWHITESPACE, section_name, file_name, lineno), file=sys.stderr)
|
||||
self.sections_skipped += 1
|
||||
elif show_errors:
|
||||
self.print_info(func, True, sys.stderr)
|
||||
|
||||
def parse_rst_file(self, module_name, doc):
|
||||
doc = os.path.abspath(doc)
|
||||
lineno = 0
|
||||
whitespace_warnings = 0
|
||||
max_whitespace_warnings = 10
|
||||
|
||||
lines = []
|
||||
flineno = 0
|
||||
fname = ""
|
||||
prev_line = None
|
||||
|
||||
df = open(doc, "rt")
|
||||
for l in df.readlines():
|
||||
lineno += 1
|
||||
# handle tabs
|
||||
if l.find("\t") >= 0:
|
||||
whitespace_warnings += 1
|
||||
if whitespace_warnings <= max_whitespace_warnings and show_warnings:
|
||||
print("RST parser warning W%03d: tab symbol instead of space is used at %s:%s" % (WARNING_004_TABS, doc, lineno), file=sys.stderr)
|
||||
l = l.replace("\t", " ")
|
||||
|
||||
# handle first line
|
||||
if prev_line == None:
|
||||
prev_line = l.rstrip()
|
||||
continue
|
||||
|
||||
ll = l.rstrip()
|
||||
if len(prev_line) > 0 and len(ll) >= len(prev_line) and (ll == "-" * len(ll) or ll == "+" * len(ll) or ll == "=" * len(ll)):
|
||||
# new function candidate
|
||||
if len(lines) > 1:
|
||||
self.parse_section_safe(module_name, fname, doc, flineno, lines[:len(lines)-1])
|
||||
lines = []
|
||||
flineno = lineno-1
|
||||
fname = prev_line.strip()
|
||||
elif flineno > 0:
|
||||
lines.append(ll)
|
||||
prev_line = ll
|
||||
df.close()
|
||||
|
||||
# don't forget about the last function section in file!!!
|
||||
if len(lines) > 1:
|
||||
self.parse_section_safe(module_name, fname, doc, flineno, lines)
|
||||
|
||||
@classmethod
|
||||
def parse_namespace(cls, func, section_name):
|
||||
known_namespaces = ["cv", "gpu", "flann", "superres"]
|
||||
l = section_name.strip()
|
||||
for namespace in known_namespaces:
|
||||
if l.startswith(namespace + "::"):
|
||||
func["namespace"] = namespace
|
||||
return l[len(namespace)+2:]
|
||||
return section_name
|
||||
|
||||
def add_new_fdecl(self, func, decl):
|
||||
if decl.fdecl.endswith(";"):
|
||||
print("RST parser error E%03d: unexpected semicolon at the end of declaration in \"%s\" at %s:%s" \
|
||||
% (ERROR_011_EOLEXPECTED, func["name"], func["file"], func["line"]), file=sys.stderr)
|
||||
decls = func.get("decls", [])
|
||||
if (decl.lang == "C++" or decl.lang == "C"):
|
||||
rst_decl = self.cpp_parser.parse_func_decl_no_wrap(decl.fdecl)
|
||||
decls.append( [decl.lang, decl.fdecl, rst_decl] )
|
||||
else:
|
||||
decls.append( [decl.lang, decl.fdecl] )
|
||||
func["decls"] = decls
|
||||
|
||||
@classmethod
|
||||
def add_new_pdecl(cls, func, decl):
|
||||
params = func.get("params", {})
|
||||
if decl.name in params:
|
||||
if show_errors:
|
||||
#check black_list
|
||||
if decl.name not in params_blacklist.get(func["name"], []):
|
||||
print("RST parser error E%03d: redefinition of parameter \"%s\" in \"%s\" at %s:%s" \
|
||||
% (ERROR_005_REDEFENITIONPARAM, decl.name, func["name"], func["file"], func["line"]), file=sys.stderr)
|
||||
else:
|
||||
params[decl.name] = decl.comment
|
||||
func["params"] = params
|
||||
|
||||
def print_info(self, func, skipped=False, out = sys.stdout):
|
||||
print(file=out)
|
||||
if skipped:
|
||||
print("SKIPPED DEFINITION:", file=out)
|
||||
print("name: %s" % (func.get("name","~empty~")), file=out)
|
||||
print("file: %s:%s" % (func.get("file","~empty~"), func.get("line","~empty~")), file=out)
|
||||
print("is class: %s" % func.get("isclass", False), file=out)
|
||||
print("is struct: %s" % func.get("isstruct", False), file=out)
|
||||
print("module: %s" % func.get("module","~unknown~"), file=out)
|
||||
print("namespace: %s" % func.get("namespace", "~empty~"), file=out)
|
||||
print("class: %s" % (func.get("class","~empty~")), file=out)
|
||||
print("method: %s" % (func.get("method","~empty~")), file=out)
|
||||
print("brief: %s" % (func.get("brief","~empty~")), file=out)
|
||||
if "decls" in func:
|
||||
print("declarations:", file=out)
|
||||
for d in func["decls"]:
|
||||
print(" %7s: %s" % (d[0], re.sub(r"[ ]+", " ", d[1])), file=out)
|
||||
if "seealso" in func:
|
||||
print("seealso: ", func["seealso"], file=out)
|
||||
if "params" in func:
|
||||
print("parameters:", file=out)
|
||||
for name, comment in func["params"].items():
|
||||
print("%23s: %s" % (name, comment), file=out)
|
||||
print("long: %s" % (func.get("long","~empty~")), file=out)
|
||||
print(file=out)
|
||||
|
||||
def validate(self, func):
|
||||
if func.get("decls", None) is None:
|
||||
if not func.get("isclass", False) and not func.get("isstruct", False):
|
||||
return False
|
||||
if func["name"] in self.definitions:
|
||||
if show_errors:
|
||||
print("RST parser error E%03d: \"%s\" from: %s:%s is already documented at %s:%s" \
|
||||
% (ERROR_006_REDEFENITIONFUNC, func["name"], func["file"], func["line"], self.definitions[func["name"]]["file"], self.definitions[func["name"]]["line"]), file=sys.stderr)
|
||||
return False
|
||||
return self.validateParams(func)
|
||||
|
||||
def validateParams(self, func):
|
||||
documentedParams = list(func.get("params", {}).keys())
|
||||
params = []
|
||||
|
||||
for decl in func.get("decls", []):
|
||||
if len(decl) > 2:
|
||||
args = decl[2][3] # decl[2] -> [ funcname, return_ctype, [modifiers], [args] ]
|
||||
for arg in args:
|
||||
# arg -> [ ctype, name, def val, [mod], argno ]
|
||||
if arg[0] != "...":
|
||||
params.append(arg[1])
|
||||
params = list(set(params))#unique
|
||||
|
||||
# 1. all params are documented
|
||||
for p in params:
|
||||
if p not in documentedParams and show_warnings:
|
||||
print("RST parser warning W%03d: parameter \"%s\" of \"%s\" is undocumented. %s:%s" % (WARNING_007_UNDOCUMENTEDPARAM, p, func["name"], func["file"], func["line"]), file=sys.stderr)
|
||||
|
||||
# 2. only real params are documented
|
||||
for p in documentedParams:
|
||||
if p not in params and show_warnings:
|
||||
if p not in params_blacklist.get(func["name"], []):
|
||||
print("RST parser warning W%03d: unexisting parameter \"%s\" of \"%s\" is documented at %s:%s" % (WARNING_008_MISSINGPARAM, p, func["name"], func["file"], func["line"]), file=sys.stderr)
|
||||
return True
|
||||
|
||||
def normalize(self, func):
|
||||
if not func:
|
||||
return func
|
||||
fnname = func["name"]
|
||||
fnname = self.normalizeText(fnname)
|
||||
fnname = re.sub(r'_\?D$', "_nD", fnname) # tailing _?D can be mapped to _nD
|
||||
fnname = re.sub(r'\?D$', "ND", fnname) # tailing ?D can be mapped to ND
|
||||
fnname = re.sub(r'\(s\)$', "s", fnname) # tailing (s) can be mapped to s
|
||||
func["name"] = fnname
|
||||
if "method" in func:
|
||||
func["method"] = self.normalizeText(func["method"])
|
||||
if "class" in func:
|
||||
func["class"] = self.normalizeText(func["class"])
|
||||
if "brief" in func:
|
||||
func["brief"] = self.normalizeText(func.get("brief", None))
|
||||
if not func["brief"]:
|
||||
del func["brief"]
|
||||
if "long" in func:
|
||||
func["long"] = self.normalizeText(func.get("long", None))
|
||||
if not func["long"]:
|
||||
del func["long"]
|
||||
if "decls" in func:
|
||||
func["decls"].sort()
|
||||
if "params" in func:
|
||||
params = {}
|
||||
for name, comment in func["params"].items():
|
||||
cmt = self.normalizeText(comment)
|
||||
if cmt:
|
||||
params[name] = cmt
|
||||
# expand some wellknown params
|
||||
pmap = params_mapping.get(fnname)
|
||||
if pmap:
|
||||
for name, alias in pmap.items():
|
||||
params[name] = params[alias]
|
||||
func["params"] = params
|
||||
if "seealso" in func:
|
||||
seealso = []
|
||||
for see in func["seealso"]:
|
||||
item = self.normalizeText(see.rstrip(".")).strip("\"")
|
||||
if item and (item.find(" ") < 0 or item.find("::operator") > 0):
|
||||
seealso.append(item)
|
||||
func["seealso"] = list(set(seealso))
|
||||
if not func["seealso"]:
|
||||
del func["seealso"]
|
||||
|
||||
# special case for old C functions - section name should omit "cv" prefix
|
||||
if not func.get("isclass", False) and not func.get("isstruct", False):
|
||||
self.fixOldCFunctionName(func)
|
||||
return func
|
||||
|
||||
def fixOldCFunctionName(self, func):
|
||||
if not "decls" in func:
|
||||
return
|
||||
fname = None
|
||||
for decl in func["decls"]:
|
||||
if decl[0] != "C" and decl[0] != "Python1":
|
||||
return
|
||||
if decl[0] == "C":
|
||||
fname = decl[2][0]
|
||||
if fname is None:
|
||||
return
|
||||
|
||||
fname = fname.replace(".", "::")
|
||||
if fname.startswith("cv::cv"):
|
||||
if fname[6:] == func.get("name", "").replace("*", "_n"):
|
||||
func["name"] = fname[4:]
|
||||
func["method"] = fname[4:]
|
||||
elif show_warnings:
|
||||
print("RST parser warning W%03d: \"%s\" - section name is \"%s\" instead of \"%s\" at %s:%s" % (WARNING_009_HDRMISMATCH, fname, func["name"], fname[6:], func["file"], func["line"]), file=sys.stderr)
|
||||
#self.print_info(func)
|
||||
|
||||
def normalizeText(self, s):
|
||||
if s is None:
|
||||
return s
|
||||
|
||||
s = re.sub(r"\.\. math::[ \r]*\n+((.|\n)*?)(\n[ \r]*\n|$)", mathReplace2, s)
|
||||
s = re.sub(r":math:`([^`]+?)`", mathReplace, s)
|
||||
s = re.sub(r" *:sup:", "^", s)
|
||||
|
||||
s = s.replace(":ocv:class:", "")
|
||||
s = s.replace(":ocv:struct:", "")
|
||||
s = s.replace(":ocv:func:", "")
|
||||
s = s.replace(":ocv:cfunc:","")
|
||||
s = s.replace(":c:type:", "")
|
||||
s = s.replace(":c:func:", "")
|
||||
s = s.replace(":ref:", "")
|
||||
s = s.replace(":math:", "")
|
||||
s = s.replace(":func:", "")
|
||||
|
||||
s = s.replace("]_", "]")
|
||||
s = s.replace(".. note::", "Note:")
|
||||
s = s.replace(".. table::", "")
|
||||
s = s.replace(".. ocv:function::", "")
|
||||
s = s.replace(".. ocv:cfunction::", "")
|
||||
|
||||
# remove ".. identifier:" lines
|
||||
s = re.sub(r"(^|\n)\.\. [a-zA-Z_0-9]+(::[a-zA-Z_0-9]+)?:(\n|$)", "\n ", s)
|
||||
# unwrap urls
|
||||
s = re.sub(r"`([^`<]+ )<(https?://[^>]+)>`_", "\\1(\\2)", s)
|
||||
# remove tailing ::
|
||||
s = re.sub(r"::(\n|$)", "\\1", s)
|
||||
|
||||
# normalize line endings
|
||||
s = re.sub(r"\r\n", "\n", s)
|
||||
# remove extra line breaks before/after _ or ,
|
||||
s = re.sub(r"\n[ ]*([_,])\n", r"\1 ", s)
|
||||
# remove extra line breaks after `
|
||||
#s = re.sub(r"`\n", "` ", s)
|
||||
# remove extra space after ( and before .,)
|
||||
s = re.sub(r"\([\n ]+", "(", s)
|
||||
s = re.sub(r"[\n ]+(\.|,|\))", "\\1", s)
|
||||
# remove extra line breaks after ".. note::"
|
||||
s = re.sub(r"\.\. note::\n+", ".. note:: ", s)
|
||||
# remove extra line breaks before *
|
||||
s = re.sub(r"\n+\*", "\n*", s)
|
||||
# remove extra line breaks after *
|
||||
s = re.sub(r"\n\*\n+", "\n* ", s)
|
||||
# remove extra line breaks before #.
|
||||
s = re.sub(r"\n+#\.", "\n#.", s)
|
||||
# remove extra line breaks after #.
|
||||
s = re.sub(r"\n#\.\n+", "\n#. ", s)
|
||||
# remove extra line breaks before `
|
||||
#s = re.sub(r"\n[ ]*`", " `", s)
|
||||
# remove trailing whitespaces
|
||||
s = re.sub(r"[ ]+$", "", s)
|
||||
# remove .. for references
|
||||
#s = re.sub(r"\.\. \[", "[", s)
|
||||
# unescape
|
||||
s = re.sub(r"\\(.)", "\\1", s)
|
||||
|
||||
# remove whitespace before .
|
||||
s = re.sub(r"[ ]+\.", ".", s)
|
||||
# remove tailing whitespace
|
||||
s = re.sub(r" +(\n|$)", "\\1", s)
|
||||
# remove leading whitespace
|
||||
s = re.sub(r"(^|\n) +", "\\1", s)
|
||||
# compress line breaks
|
||||
s = re.sub(r"\n\n+", "\n\n", s)
|
||||
# remove other newlines
|
||||
s = re.sub(r"([^.\n\\=])\n([^*#\n]|\*[^ ])", "\\1 \\2", s)
|
||||
# compress whitespace
|
||||
s = re.sub(r" +", " ", s)
|
||||
|
||||
# restore math
|
||||
s = re.sub(r" *<BR> *", "\n", s)
|
||||
|
||||
# remove extra space before .
|
||||
s = re.sub(r"[\n ]+\.", ".", s)
|
||||
|
||||
s = s.replace("**", "")
|
||||
s = re.sub(r"``([^\n]+?)``", "<code>\\1</code>", s)
|
||||
s = s.replace("``", "\"")
|
||||
s = s.replace("`", "\"")
|
||||
s = s.replace("\"\"", "\"")
|
||||
|
||||
s = s.strip()
|
||||
return s
|
||||
|
||||
def printSummary(self):
|
||||
print("RST Parser Summary:")
|
||||
print(" Total sections: %s" % self.sections_total)
|
||||
print(" Skipped sections: %s" % self.sections_skipped)
|
||||
print(" Parsed sections: %s" % self.sections_parsed)
|
||||
print(" Invalid sections: %s" % (self.sections_total - self.sections_parsed - self.sections_skipped))
|
||||
|
||||
# statistic by language
|
||||
stat = {}
|
||||
classes = 0
|
||||
structs = 0
|
||||
for name, d in self.definitions.items():
|
||||
if d.get("isclass", False):
|
||||
classes += 1
|
||||
elif d.get("isstruct", False):
|
||||
structs += 1
|
||||
else:
|
||||
for decl in d.get("decls", []):
|
||||
stat[decl[0]] = stat.get(decl[0], 0) + 1
|
||||
|
||||
print()
|
||||
print(" classes documented: %s" % classes)
|
||||
print(" structs documented: %s" % structs)
|
||||
for lang in sorted(stat.items()):
|
||||
print(" %7s functions documented: %s" % lang)
|
||||
print()
|
||||
|
||||
def mathReplace2(match):
|
||||
m = mathReplace(match)
|
||||
#print "%s ===> %s" % (match.group(0), m)
|
||||
return "\n\n"+m+"<BR><BR>"
|
||||
|
||||
def hdotsforReplace(match):
|
||||
return '... '*int(match.group(1))
|
||||
|
||||
def matrixReplace(match):
|
||||
m = match.group(2)
|
||||
m = re.sub(r" *& *", " ", m)
|
||||
return m
|
||||
|
||||
def mathReplace(match):
|
||||
m = match.group(1)
|
||||
|
||||
m = m.replace("\n", "<BR>")
|
||||
m = m.replace("<", "<")
|
||||
m = m.replace(">", ">")
|
||||
m = re.sub(r"\\text(tt|rm)?{(.*?)}", "\\2", m)
|
||||
m = re.sub(r"\\mbox{(.*?)}", "\\1", m)
|
||||
m = re.sub(r"\\mathrm{(.*?)}", "\\1", m)
|
||||
m = re.sub(r"\\vecthree{(.*?)}{(.*?)}{(.*?)}", "[\\1 \\2 \\3]", m)
|
||||
m = re.sub(r"\\bar{(.*?)}", "\\1`", m)
|
||||
m = re.sub(r"\\sqrt\[(\d)*\]{(.*?)}", "sqrt\\1(\\2)", m)
|
||||
m = re.sub(r"\\sqrt{(.*?)}", "sqrt(\\1)", m)
|
||||
m = re.sub(r"\\frac{(.*?)}{(.*?)}", "(\\1)/(\\2)", m)
|
||||
m = re.sub(r"\\fork{(.*?)}{(.*?)}{(.*?)}{(.*?)}", "\\1 \\2; \\3 \\4", m)
|
||||
m = re.sub(r"\\forkthree{(.*?)}{(.*?)}{(.*?)}{(.*?)}{(.*?)}{(.*?)}", "\\1 \\2; \\3 \\4; \\5 \\6", m)
|
||||
m = re.sub(r"\\stackrel{(.*?)}{(.*?)}", "\\1 \\2", m)
|
||||
m = re.sub(r"\\sum _{(.*?)}", "sum{by: \\1}", m)
|
||||
|
||||
m = re.sub(r" +", " ", m)
|
||||
m = re.sub(r"\\begin{(?P<gtype>array|bmatrix)}(?:{[\|lcr\. ]+})? *(.*?)\\end{(?P=gtype)}", matrixReplace, m)
|
||||
m = re.sub(r"\\hdotsfor{(\d+)}", hdotsforReplace, m)
|
||||
m = re.sub(r"\\vecthreethree{(.*?)}{(.*?)}{(.*?)}{(.*?)}{(.*?)}{(.*?)}{(.*?)}{(.*?)}{(.*?)}", "<BR>|\\1 \\2 \\3|<BR>|\\4 \\5 \\6|<BR>|\\7 \\8 \\9|<BR>", m)
|
||||
|
||||
m = re.sub(r"\\left[ ]*\\lfloor[ ]*", "[", m)
|
||||
m = re.sub(r"[ ]*\\right[ ]*\\rfloor", "]", m)
|
||||
m = re.sub(r"\\left[ ]*\([ ]*", "(", m)
|
||||
m = re.sub(r"[ ]*\\right[ ]*\)", ")", m)
|
||||
m = re.sub(r"([^\\])\$", "\\1", m)
|
||||
|
||||
m = m.replace("\\times", "x")
|
||||
m = m.replace("\\pm", "+-")
|
||||
m = m.replace("\\cdot", "*")
|
||||
m = m.replace("\\sim", "~")
|
||||
m = m.replace("\\leftarrow", "<-")
|
||||
m = m.replace("\\rightarrow", "->")
|
||||
m = m.replace("\\leftrightarrow", "<->")
|
||||
m = re.sub(r" *\\neg *", " !", m)
|
||||
m = re.sub(r" *\\neq? *", " != ", m)
|
||||
m = re.sub(r" *\\geq? *", " >= ", m)
|
||||
m = re.sub(r" *\\leq? *", " <= ", m)
|
||||
m = re.sub(r" *\\vee *", " V ", m)
|
||||
m = re.sub(r" *\\oplus *", " (+) ", m)
|
||||
m = re.sub(r" *\\mod *", " mod ", m)
|
||||
m = re.sub(r"( *)\\partial *", "\\1d", m)
|
||||
|
||||
m = re.sub(r"( *)\\quad *", "\\1 ", m)
|
||||
m = m.replace("\\,", " ")
|
||||
m = m.replace("\\:", " ")
|
||||
m = m.replace("\\;", " ")
|
||||
m = m.replace("\\!", "")
|
||||
|
||||
m = m.replace("\\\\", "<BR>")
|
||||
m = m.replace("\\wedge", "/\\\\")
|
||||
m = re.sub(r"\\(.)", "\\1", m)
|
||||
|
||||
m = re.sub(r"\([ ]+", "(", m)
|
||||
m = re.sub(r"[ ]+(\.|,|\))(<BR>| |$)", "\\1\\2", m)
|
||||
m = re.sub(r" +\|[ ]+([a-zA-Z0-9_(])", " |\\1", m)
|
||||
m = re.sub(r"([a-zA-Z0-9_)}])[ ]+(\(|\|)", "\\1\\2", m)
|
||||
|
||||
m = re.sub(r"{\((-?[a-zA-Z0-9_]+)\)}", "\\1", m)
|
||||
m = re.sub(r"{(-?[a-zA-Z0-9_]+)}", "(\\1)", m)
|
||||
m = re.sub(r"\(([0-9]+)\)", "\\1", m)
|
||||
m = m.replace("{", "(")
|
||||
m = m.replace("}", ")")
|
||||
|
||||
#print "%s ===> %s" % (match.group(0), m)
|
||||
return "<em>" + m + "</em>"
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage:\n", os.path.basename(sys.argv[0]), " <module path>")
|
||||
exit(0)
|
||||
|
||||
if len(sys.argv) >= 3:
|
||||
if sys.argv[2].lower() == "verbose":
|
||||
verbose = True
|
||||
|
||||
rst_parser_dir = os.path.dirname(os.path.abspath(sys.argv[0]))
|
||||
hdr_parser_path = os.path.join(rst_parser_dir, "../../python/src2")
|
||||
|
||||
sys.path.append(hdr_parser_path)
|
||||
import hdr_parser
|
||||
|
||||
module = sys.argv[1]
|
||||
|
||||
if module != "all" and not os.path.isdir(os.path.join(rst_parser_dir, "../../" + module)):
|
||||
print("RST parser error E%03d: module \"%s\" could not be found." % (ERROR_010_NOMODULE, module))
|
||||
exit(1)
|
||||
|
||||
parser = RstParser(hdr_parser.CppHeaderParser())
|
||||
|
||||
if module == "all":
|
||||
for m in allmodules:
|
||||
parser.parse(m, os.path.join(rst_parser_dir, "../../" + m))
|
||||
else:
|
||||
parser.parse(module, os.path.join(rst_parser_dir, "../../" + module))
|
||||
|
||||
# summary
|
||||
parser.printSummary()
|
||||
@@ -1,147 +0,0 @@
|
||||
.. _Boosting:
|
||||
|
||||
Boosting
|
||||
========
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
A common machine learning task is supervised learning. In supervised learning, the goal is to learn the functional relationship
|
||||
:math:`F: y = F(x)` between the input
|
||||
:math:`x` and the output
|
||||
:math:`y` . Predicting the qualitative output is called *classification*, while predicting the quantitative output is called *regression*.
|
||||
|
||||
Boosting is a powerful learning concept that provides a solution to the supervised classification learning task. It combines the performance of many "weak" classifiers to produce a powerful committee [HTF01]_. A weak classifier is only required to be better than chance, and thus can be very simple and computationally inexpensive. However, many of them smartly combine results to a strong classifier that often outperforms most "monolithic" strong classifiers such as SVMs and Neural Networks.
|
||||
|
||||
Decision trees are the most popular weak classifiers used in boosting schemes. Often the simplest decision trees with only a single split node per tree (called ``stumps`` ) are sufficient.
|
||||
|
||||
The boosted model is based on
|
||||
:math:`N` training examples
|
||||
:math:`{(x_i,y_i)}1N` with
|
||||
:math:`x_i \in{R^K}` and
|
||||
:math:`y_i \in{-1, +1}` .
|
||||
:math:`x_i` is a
|
||||
:math:`K` -component vector. Each component encodes a feature relevant to the learning task at hand. The desired two-class output is encoded as -1 and +1.
|
||||
|
||||
Different variants of boosting are known as Discrete Adaboost, Real AdaBoost, LogitBoost, and Gentle AdaBoost [FHT98]_. All of them are very similar in their overall structure. Therefore, this chapter focuses only on the standard two-class Discrete AdaBoost algorithm, outlined below. Initially the same weight is assigned to each sample (step 2). Then, a weak classifier
|
||||
:math:`f_{m(x)}` is trained on the weighted training data (step 3a). Its weighted training error and scaling factor
|
||||
:math:`c_m` is computed (step 3b). The weights are increased for training samples that have been misclassified (step 3c). All weights are then normalized, and the process of finding the next weak classifier continues for another
|
||||
:math:`M` -1 times. The final classifier
|
||||
:math:`F(x)` is the sign of the weighted sum over the individual weak classifiers (step 4).
|
||||
|
||||
**Two-class Discrete AdaBoost Algorithm**
|
||||
|
||||
#.
|
||||
Set
|
||||
:math:`N` examples
|
||||
:math:`{(x_i,y_i)}1N` with
|
||||
:math:`x_i \in{R^K}, y_i \in{-1, +1}` .
|
||||
|
||||
#.
|
||||
Assign weights as
|
||||
:math:`w_i = 1/N, i = 1,...,N` .
|
||||
|
||||
#.
|
||||
Repeat for :math:`m = 1,2,...,M` :
|
||||
|
||||
3.1. Fit the classifier :math:`f_m(x) \in{-1,1}`, using weights :math:`w_i` on the training data.
|
||||
|
||||
3.2. Compute :math:`err_m = E_w [1_{(y \neq f_m(x))}], c_m = log((1 - err_m)/err_m)` .
|
||||
|
||||
3.3. Set :math:`w_i \Leftarrow w_i exp[c_m 1_{(y_i \neq f_m(x_i))}], i = 1,2,...,N,` and renormalize so that :math:`\Sigma i w_i = 1` .
|
||||
|
||||
|
||||
#. Classify new samples *x* using the formula: :math:`\textrm{sign} (\Sigma m = 1M c_m f_m(x))` .
|
||||
|
||||
|
||||
.. note:: Similar to the classical boosting methods, the current implementation supports two-class classifiers only. For ``M > 2`` classes, there is the **AdaBoost.MH** algorithm (described in [FHT98]_) that reduces the problem to the two-class problem, yet with a much larger training set.
|
||||
|
||||
To reduce computation time for boosted models without substantially losing accuracy, the influence trimming technique can be employed. As the training algorithm proceeds and the number of trees in the ensemble is increased, a larger number of the training samples are classified correctly and with increasing confidence, thereby those samples receive smaller weights on the subsequent iterations. Examples with a very low relative weight have a small impact on the weak classifier training. Thus, such examples may be excluded during the weak classifier training without having much effect on the induced classifier. This process is controlled with the ``weight_trim_rate`` parameter. Only examples with the summary fraction ``weight_trim_rate`` of the total weight mass are used in the weak classifier training. Note that the weights for
|
||||
**all**
|
||||
training examples are recomputed at each training iteration. Examples deleted at a particular iteration may be used again for learning some of the weak classifiers further [FHT98]_.
|
||||
|
||||
.. [HTF01] Hastie, T., Tibshirani, R., Friedman, J. H. *The Elements of Statistical Learning: Data Mining, Inference, and Prediction. Springer Series in Statistics*. 2001.
|
||||
|
||||
.. [FHT98] Friedman, J. H., Hastie, T. and Tibshirani, R. Additive Logistic Regression: a Statistical View of Boosting. Technical Report, Dept. of Statistics*, Stanford University, 1998.
|
||||
|
||||
Boost::Params
|
||||
-------------
|
||||
.. ocv:struct:: Boost::Params : public DTree::Params
|
||||
|
||||
Boosting training parameters.
|
||||
|
||||
The structure is derived from ``DTrees::Params`` but not all of the decision tree parameters are supported. In particular, cross-validation is not supported.
|
||||
|
||||
All parameters are public. You can initialize them by a constructor and then override some of them directly if you want.
|
||||
|
||||
Boost::Params::Params
|
||||
----------------------------
|
||||
The constructors.
|
||||
|
||||
.. ocv:function:: Boost::Params::Params()
|
||||
|
||||
.. ocv:function:: Boost::Params::Params( int boostType, int weakCount, double weightTrimRate, int maxDepth, bool useSurrogates, const Mat& priors )
|
||||
|
||||
:param boost_type: Type of the boosting algorithm. Possible values are:
|
||||
|
||||
* **Boost::DISCRETE** Discrete AdaBoost.
|
||||
* **Boost::REAL** Real AdaBoost. It is a technique that utilizes confidence-rated predictions and works well with categorical data.
|
||||
* **Boost::LOGIT** LogitBoost. It can produce good regression fits.
|
||||
* **Boost::GENTLE** Gentle AdaBoost. It puts less weight on outlier data points and for that reason is often good with regression data.
|
||||
|
||||
Gentle AdaBoost and Real AdaBoost are often the preferable choices.
|
||||
|
||||
:param weak_count: The number of weak classifiers.
|
||||
|
||||
:param weight_trim_rate: A threshold between 0 and 1 used to save computational time. Samples with summary weight :math:`\leq 1 - weight\_trim\_rate` do not participate in the *next* iteration of training. Set this parameter to 0 to turn off this functionality.
|
||||
|
||||
See ``DTrees::Params`` for description of other parameters.
|
||||
|
||||
Default parameters are:
|
||||
|
||||
::
|
||||
|
||||
Boost::Params::Params()
|
||||
{
|
||||
boostType = Boost::REAL;
|
||||
weakCount = 100;
|
||||
weightTrimRate = 0.95;
|
||||
CVFolds = 0;
|
||||
maxDepth = 1;
|
||||
}
|
||||
|
||||
Boost
|
||||
-------
|
||||
.. ocv:class:: Boost : public DTrees
|
||||
|
||||
Boosted tree classifier derived from ``DTrees``
|
||||
|
||||
Boost::create
|
||||
----------------
|
||||
Creates the empty model
|
||||
|
||||
.. ocv:function:: Ptr<Boost> Boost::create(const Params& params=Params())
|
||||
|
||||
Use ``StatModel::train`` to train the model, ``StatModel::train<Boost>(traindata, params)`` to create and train the model, ``StatModel::load<Boost>(filename)`` to load the pre-trained model.
|
||||
|
||||
Boost::getBParams
|
||||
-----------------
|
||||
Returns the boosting parameters
|
||||
|
||||
.. ocv:function:: Params Boost::getBParams() const
|
||||
|
||||
The method returns the training parameters.
|
||||
|
||||
Boost::setBParams
|
||||
-----------------
|
||||
Sets the boosting parameters
|
||||
|
||||
.. ocv:function:: void Boost::setBParams( const Params& p )
|
||||
|
||||
:param p: Training parameters of type Boost::Params.
|
||||
|
||||
The method sets the training parameters.
|
||||
|
||||
Prediction with Boost
|
||||
---------------------
|
||||
|
||||
StatModel::predict(samples, results, flags) should be used. Pass ``flags=StatModel::RAW_OUTPUT`` to get the raw sum from Boost classifier.
|
||||
@@ -1,241 +0,0 @@
|
||||
Decision Trees
|
||||
==============
|
||||
|
||||
The ML classes discussed in this section implement Classification and Regression Tree algorithms described in [Breiman84]_.
|
||||
|
||||
The class ``cv::ml::DTrees`` represents a single decision tree or a collection of decision trees. It's also a base class for ``RTrees`` and ``Boost``.
|
||||
|
||||
A decision tree is a binary tree (tree where each non-leaf node has two child nodes). It can be used either for classification or for regression. For classification, each tree leaf is marked with a class label; multiple leaves may have the same label. For regression, a constant is also assigned to each tree leaf, so the approximation function is piecewise constant.
|
||||
|
||||
Predicting with Decision Trees
|
||||
------------------------------
|
||||
|
||||
To reach a leaf node and to obtain a response for the input feature
|
||||
vector, the prediction procedure starts with the root node. From each
|
||||
non-leaf node the procedure goes to the left (selects the left
|
||||
child node as the next observed node) or to the right based on the
|
||||
value of a certain variable whose index is stored in the observed
|
||||
node. The following variables are possible:
|
||||
|
||||
*
|
||||
**Ordered variables.** The variable value is compared with a threshold that is also stored in the node. If the value is less than the threshold, the procedure goes to the left. Otherwise, it goes to the right. For example, if the weight is less than 1 kilogram, the procedure goes to the left, else to the right.
|
||||
*
|
||||
**Categorical variables.** A discrete variable value is tested to see whether it belongs to a certain subset of values (also stored in the node) from a limited set of values the variable could take. If it does, the procedure goes to the left. Otherwise, it goes to the right. For example, if the color is green or red, go to the left, else to the right.
|
||||
|
||||
So, in each node, a pair of entities (``variable_index`` , ``decision_rule
|
||||
(threshold/subset)`` ) is used. This pair is called a *split* (split on
|
||||
the variable ``variable_index`` ). Once a leaf node is reached, the value
|
||||
assigned to this node is used as the output of the prediction procedure.
|
||||
|
||||
Sometimes, certain features of the input vector are missed (for example, in the darkness it is difficult to determine the object color), and the prediction procedure may get stuck in the certain node (in the mentioned example, if the node is split by color). To avoid such situations, decision trees use so-called *surrogate splits*. That is, in addition to the best "primary" split, every tree node may also be split to one or more other variables with nearly the same results.
|
||||
|
||||
Training Decision Trees
|
||||
-----------------------
|
||||
|
||||
The tree is built recursively, starting from the root node. All training data (feature vectors and responses) is used to split the root node. In each node the optimum decision rule (the best "primary" split) is found based on some criteria. In machine learning, ``gini`` "purity" criteria are used for classification, and sum of squared errors is used for regression. Then, if necessary, the surrogate splits are found. They resemble the results of the primary split on the training data. All the data is divided using the primary and the surrogate splits (like it is done in the prediction procedure) between the left and the right child node. Then, the procedure recursively splits both left and right nodes. At each node the recursive procedure may stop (that is, stop splitting the node further) in one of the following cases:
|
||||
|
||||
* Depth of the constructed tree branch has reached the specified maximum value.
|
||||
|
||||
* Number of training samples in the node is less than the specified threshold when it is not statistically representative to split the node further.
|
||||
|
||||
* All the samples in the node belong to the same class or, in case of regression, the variation is too small.
|
||||
|
||||
* The best found split does not give any noticeable improvement compared to a random choice.
|
||||
|
||||
When the tree is built, it may be pruned using a cross-validation procedure, if necessary. That is, some branches of the tree that may lead to the model overfitting are cut off. Normally, this procedure is only applied to standalone decision trees. Usually tree ensembles build trees that are small enough and use their own protection schemes against overfitting.
|
||||
|
||||
Variable Importance
|
||||
-------------------
|
||||
|
||||
Besides the prediction that is an obvious use of decision trees, the tree can be also used for various data analyses. One of the key properties of the constructed decision tree algorithms is an ability to compute the importance (relative decisive power) of each variable. For example, in a spam filter that uses a set of words occurred in the message as a feature vector, the variable importance rating can be used to determine the most "spam-indicating" words and thus help keep the dictionary size reasonable.
|
||||
|
||||
Importance of each variable is computed over all the splits on this variable in the tree, primary and surrogate ones. Thus, to compute variable importance correctly, the surrogate splits must be enabled in the training parameters, even if there is no missing data.
|
||||
|
||||
|
||||
DTrees::Split
|
||||
-------------
|
||||
.. ocv:class:: DTrees::Split
|
||||
|
||||
The class represents split in a decision tree. It has public members:
|
||||
|
||||
.. ocv:member:: int varIdx
|
||||
|
||||
Index of variable on which the split is created.
|
||||
|
||||
.. ocv:member:: bool inversed
|
||||
|
||||
If true, then the inverse split rule is used (i.e. left and right branches are exchanged in the rule expressions below).
|
||||
|
||||
.. ocv:member:: float quality
|
||||
|
||||
The split quality, a positive number. It is used to choose the best split.
|
||||
|
||||
.. ocv:member:: int next
|
||||
|
||||
Index of the next split in the list of splits for the node
|
||||
|
||||
.. ocv:member:: float c
|
||||
|
||||
The threshold value in case of split on an ordered variable. The rule is: ::
|
||||
|
||||
if var_value < c
|
||||
then next_node<-left
|
||||
else next_node<-right
|
||||
|
||||
.. ocv:member:: int subsetOfs
|
||||
|
||||
Offset of the bitset used by the split on a categorical variable. The rule is: ::
|
||||
|
||||
if bitset[var_value] == 1
|
||||
then next_node <- left
|
||||
else next_node <- right
|
||||
|
||||
DTrees::Node
|
||||
------------
|
||||
.. ocv:class:: DTrees::Node
|
||||
|
||||
The class represents a decision tree node. It has public members:
|
||||
|
||||
.. ocv:member:: double value
|
||||
|
||||
Value at the node: a class label in case of classification or estimated function value in case of regression.
|
||||
|
||||
.. ocv:member:: int classIdx
|
||||
|
||||
Class index normalized to 0..class_count-1 range and assigned to the node. It is used internally in classification trees and tree ensembles.
|
||||
|
||||
.. ocv:member:: int parent
|
||||
|
||||
Index of the parent node
|
||||
|
||||
.. ocv:member:: int left
|
||||
|
||||
Index of the left child node
|
||||
|
||||
.. ocv:member:: int right
|
||||
|
||||
Index of right child node.
|
||||
|
||||
.. ocv:member:: int defaultDir
|
||||
|
||||
Default direction where to go (-1: left or +1: right). It helps in the case of missing values.
|
||||
|
||||
.. ocv:member:: int split
|
||||
|
||||
Index of the first split
|
||||
|
||||
DTrees::Params
|
||||
---------------
|
||||
.. ocv:class:: DTrees::Params
|
||||
|
||||
The structure contains all the decision tree training parameters. You can initialize it by default constructor and then override any parameters directly before training, or the structure may be fully initialized using the advanced variant of the constructor.
|
||||
|
||||
DTrees::Params::Params
|
||||
----------------------------
|
||||
The constructors
|
||||
|
||||
.. ocv:function:: DTrees::Params::Params()
|
||||
|
||||
.. ocv:function:: DTrees::Params::Params( int maxDepth, int minSampleCount, double regressionAccuracy, bool useSurrogates, int maxCategories, int CVFolds, bool use1SERule, bool truncatePrunedTree, const Mat& priors )
|
||||
|
||||
:param maxDepth: The maximum possible depth of the tree. That is the training algorithms attempts to split a node while its depth is less than ``maxDepth``. The root node has zero depth. The actual depth may be smaller if the other termination criteria are met (see the outline of the training procedure in the beginning of the section), and/or if the tree is pruned.
|
||||
|
||||
:param minSampleCount: If the number of samples in a node is less than this parameter then the node will not be split.
|
||||
|
||||
:param regressionAccuracy: Termination criteria for regression trees. If all absolute differences between an estimated value in a node and values of train samples in this node are less than this parameter then the node will not be split further.
|
||||
|
||||
:param useSurrogates: If true then surrogate splits will be built. These splits allow to work with missing data and compute variable importance correctly. .. note:: currently it's not implemented.
|
||||
|
||||
:param maxCategories: Cluster possible values of a categorical variable into ``K<=maxCategories`` clusters to find a suboptimal split. If a discrete variable, on which the training procedure tries to make a split, takes more than ``maxCategories`` values, the precise best subset estimation may take a very long time because the algorithm is exponential. Instead, many decision trees engines (including our implementation) try to find sub-optimal split in this case by clustering all the samples into ``maxCategories`` clusters that is some categories are merged together. The clustering is applied only in ``n > 2``-class classification problems for categorical variables with ``N > max_categories`` possible values. In case of regression and 2-class classification the optimal split can be found efficiently without employing clustering, thus the parameter is not used in these cases.
|
||||
|
||||
:param CVFolds: If ``CVFolds > 1`` then algorithms prunes the built decision tree using ``K``-fold cross-validation procedure where ``K`` is equal to ``CVFolds``.
|
||||
|
||||
:param use1SERule: If true then a pruning will be harsher. This will make a tree more compact and more resistant to the training data noise but a bit less accurate.
|
||||
|
||||
:param truncatePrunedTree: If true then pruned branches are physically removed from the tree. Otherwise they are retained and it is possible to get results from the original unpruned (or pruned less aggressively) tree.
|
||||
|
||||
:param priors: The array of a priori class probabilities, sorted by the class label value. The parameter can be used to tune the decision tree preferences toward a certain class. For example, if you want to detect some rare anomaly occurrence, the training base will likely contain much more normal cases than anomalies, so a very good classification performance will be achieved just by considering every case as normal. To avoid this, the priors can be specified, where the anomaly probability is artificially increased (up to 0.5 or even greater), so the weight of the misclassified anomalies becomes much bigger, and the tree is adjusted properly. You can also think about this parameter as weights of prediction categories which determine relative weights that you give to misclassification. That is, if the weight of the first category is 1 and the weight of the second category is 10, then each mistake in predicting the second category is equivalent to making 10 mistakes in predicting the first category.
|
||||
|
||||
The default constructor initializes all the parameters with the default values tuned for the standalone classification tree:
|
||||
|
||||
::
|
||||
|
||||
DTrees::Params::Params()
|
||||
{
|
||||
maxDepth = INT_MAX;
|
||||
minSampleCount = 10;
|
||||
regressionAccuracy = 0.01f;
|
||||
useSurrogates = false;
|
||||
maxCategories = 10;
|
||||
CVFolds = 10;
|
||||
use1SERule = true;
|
||||
truncatePrunedTree = true;
|
||||
priors = Mat();
|
||||
}
|
||||
|
||||
|
||||
DTrees
|
||||
------
|
||||
|
||||
.. ocv:class:: DTrees : public StatModel
|
||||
|
||||
The class represents a single decision tree or a collection of decision trees. The current public interface of the class allows user to train only a single decision tree, however the class is capable of storing multiple decision trees and using them for prediction (by summing responses or using a voting schemes), and the derived from DTrees classes (such as ``RTrees`` and ``Boost``) use this capability to implement decision tree ensembles.
|
||||
|
||||
DTrees::create
|
||||
----------------
|
||||
Creates the empty model
|
||||
|
||||
.. ocv:function:: Ptr<DTrees> DTrees::create(const Params& params=Params())
|
||||
|
||||
The static method creates empty decision tree with the specified parameters. It should be then trained using ``train`` method (see ``StatModel::train``). Alternatively, you can load the model from file using ``StatModel::load<DTrees>(filename)``.
|
||||
|
||||
DTrees::getDParams
|
||||
------------------
|
||||
Returns the training parameters
|
||||
|
||||
.. ocv:function:: Params DTrees::getDParams() const
|
||||
|
||||
The method returns the training parameters.
|
||||
|
||||
DTrees::setDParams
|
||||
-------------------
|
||||
Sets the training parameters
|
||||
|
||||
.. ocv:function:: void DTrees::setDParams( const Params& p )
|
||||
|
||||
:param p: Training parameters of type DTrees::Params.
|
||||
|
||||
The method sets the training parameters.
|
||||
|
||||
|
||||
DTrees::getRoots
|
||||
-------------------
|
||||
Returns indices of root nodes
|
||||
|
||||
.. ocv:function:: std::vector<int>& DTrees::getRoots() const
|
||||
|
||||
DTrees::getNodes
|
||||
-------------------
|
||||
Returns all the nodes
|
||||
|
||||
.. ocv:function:: std::vector<Node>& DTrees::getNodes() const
|
||||
|
||||
all the node indices, mentioned above (left, right, parent, root indices) are indices in the returned vector
|
||||
|
||||
DTrees::getSplits
|
||||
-------------------
|
||||
Returns all the splits
|
||||
|
||||
.. ocv:function:: std::vector<Split>& DTrees::getSplits() const
|
||||
|
||||
all the split indices, mentioned above (split, next etc.) are indices in the returned vector
|
||||
|
||||
DTrees::getSubsets
|
||||
-------------------
|
||||
Returns all the bitsets for categorical splits
|
||||
|
||||
.. ocv:function:: std::vector<int>& DTrees::getSubsets() const
|
||||
|
||||
``Split::subsetOfs`` is an offset in the returned vector
|
||||
|
||||
.. [Breiman84] Breiman, L., Friedman, J. Olshen, R. and Stone, C. (1984), *Classification and Regression Trees*, Wadsworth.
|
||||
@@ -1,219 +0,0 @@
|
||||
|
||||
.. _ML_Expectation Maximization:
|
||||
|
||||
|
||||
Expectation Maximization
|
||||
========================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
The Expectation Maximization(EM) algorithm estimates the parameters of the multivariate probability density function in the form of a Gaussian mixture distribution with a specified number of mixtures.
|
||||
|
||||
Consider the set of the N feature vectors
|
||||
{ :math:`x_1, x_2,...,x_{N}` } from a d-dimensional Euclidean space drawn from a Gaussian mixture:
|
||||
|
||||
.. math::
|
||||
|
||||
p(x;a_k,S_k, \pi _k) = \sum _{k=1}^{m} \pi _kp_k(x), \quad \pi _k \geq 0, \quad \sum _{k=1}^{m} \pi _k=1,
|
||||
|
||||
.. math::
|
||||
|
||||
p_k(x)= \varphi (x;a_k,S_k)= \frac{1}{(2\pi)^{d/2}\mid{S_k}\mid^{1/2}} exp \left \{ - \frac{1}{2} (x-a_k)^TS_k^{-1}(x-a_k) \right \} ,
|
||||
|
||||
where
|
||||
:math:`m` is the number of mixtures,
|
||||
:math:`p_k` is the normal distribution
|
||||
density with the mean
|
||||
:math:`a_k` and covariance matrix
|
||||
:math:`S_k`,
|
||||
:math:`\pi_k` is the weight of the k-th mixture. Given the number of mixtures
|
||||
:math:`M` and the samples
|
||||
:math:`x_i`,
|
||||
:math:`i=1..N` the algorithm finds the
|
||||
maximum-likelihood estimates (MLE) of all the mixture parameters,
|
||||
that is,
|
||||
:math:`a_k`,
|
||||
:math:`S_k` and
|
||||
:math:`\pi_k` :
|
||||
|
||||
.. math::
|
||||
|
||||
L(x, \theta )=logp(x, \theta )= \sum _{i=1}^{N}log \left ( \sum _{k=1}^{m} \pi _kp_k(x) \right ) \to \max _{ \theta \in \Theta },
|
||||
|
||||
.. math::
|
||||
|
||||
\Theta = \left \{ (a_k,S_k, \pi _k): a_k \in \mathbbm{R} ^d,S_k=S_k^T>0,S_k \in \mathbbm{R} ^{d \times d}, \pi _k \geq 0, \sum _{k=1}^{m} \pi _k=1 \right \} .
|
||||
|
||||
The EM algorithm is an iterative procedure. Each iteration includes
|
||||
two steps. At the first step (Expectation step or E-step), you find a
|
||||
probability
|
||||
:math:`p_{i,k}` (denoted
|
||||
:math:`\alpha_{i,k}` in the formula below) of
|
||||
sample ``i`` to belong to mixture ``k`` using the currently
|
||||
available mixture parameter estimates:
|
||||
|
||||
.. math::
|
||||
|
||||
\alpha _{ki} = \frac{\pi_k\varphi(x;a_k,S_k)}{\sum\limits_{j=1}^{m}\pi_j\varphi(x;a_j,S_j)} .
|
||||
|
||||
At the second step (Maximization step or M-step), the mixture parameter estimates are refined using the computed probabilities:
|
||||
|
||||
.. math::
|
||||
|
||||
\pi _k= \frac{1}{N} \sum _{i=1}^{N} \alpha _{ki}, \quad a_k= \frac{\sum\limits_{i=1}^{N}\alpha_{ki}x_i}{\sum\limits_{i=1}^{N}\alpha_{ki}} , \quad S_k= \frac{\sum\limits_{i=1}^{N}\alpha_{ki}(x_i-a_k)(x_i-a_k)^T}{\sum\limits_{i=1}^{N}\alpha_{ki}}
|
||||
|
||||
Alternatively, the algorithm may start with the M-step when the initial values for
|
||||
:math:`p_{i,k}` can be provided. Another alternative when
|
||||
:math:`p_{i,k}` are unknown is to use a simpler clustering algorithm to pre-cluster the input samples and thus obtain initial
|
||||
:math:`p_{i,k}` . Often (including machine learning) the
|
||||
``k-means`` algorithm is used for that purpose.
|
||||
|
||||
One of the main problems of the EM algorithm is a large number
|
||||
of parameters to estimate. The majority of the parameters reside in
|
||||
covariance matrices, which are
|
||||
:math:`d \times d` elements each
|
||||
where
|
||||
:math:`d` is the feature space dimensionality. However, in
|
||||
many practical problems, the covariance matrices are close to diagonal
|
||||
or even to
|
||||
:math:`\mu_k*I` , where
|
||||
:math:`I` is an identity matrix and
|
||||
:math:`\mu_k` is a mixture-dependent "scale" parameter. So, a robust computation
|
||||
scheme could start with harder constraints on the covariance
|
||||
matrices and then use the estimated parameters as an input for a less
|
||||
constrained optimization problem (often a diagonal covariance matrix is
|
||||
already a good enough approximation).
|
||||
|
||||
**References:**
|
||||
|
||||
*
|
||||
Bilmes98 J. A. Bilmes. *A Gentle Tutorial of the EM Algorithm and its Application to Parameter Estimation for Gaussian Mixture and Hidden Markov Models*. Technical Report TR-97-021, International Computer Science Institute and Computer Science Division, University of California at Berkeley, April 1998.
|
||||
|
||||
EM
|
||||
--
|
||||
.. ocv:class:: EM : public StatModel
|
||||
|
||||
The class implements the EM algorithm as described in the beginning of this section.
|
||||
|
||||
EM::Params
|
||||
----------
|
||||
.. ocv:class:: EM::Params
|
||||
|
||||
The class describes EM training parameters.
|
||||
|
||||
EM::Params::Params
|
||||
------------------
|
||||
The constructor
|
||||
|
||||
.. ocv:function:: EM::Params::Params( int nclusters=DEFAULT_NCLUSTERS, int covMatType=EM::COV_MAT_DIAGONAL,const TermCriteria& termCrit=TermCriteria(TermCriteria::COUNT+TermCriteria::EPS, EM::DEFAULT_MAX_ITERS, 1e-6))
|
||||
|
||||
:param nclusters: The number of mixture components in the Gaussian mixture model. Default value of the parameter is ``EM::DEFAULT_NCLUSTERS=5``. Some of EM implementation could determine the optimal number of mixtures within a specified value range, but that is not the case in ML yet.
|
||||
|
||||
:param covMatType: Constraint on covariance matrices which defines type of matrices. Possible values are:
|
||||
|
||||
* **EM::COV_MAT_SPHERICAL** A scaled identity matrix :math:`\mu_k * I`. There is the only parameter :math:`\mu_k` to be estimated for each matrix. The option may be used in special cases, when the constraint is relevant, or as a first step in the optimization (for example in case when the data is preprocessed with PCA). The results of such preliminary estimation may be passed again to the optimization procedure, this time with ``covMatType=EM::COV_MAT_DIAGONAL``.
|
||||
|
||||
* **EM::COV_MAT_DIAGONAL** A diagonal matrix with positive diagonal elements. The number of free parameters is ``d`` for each matrix. This is most commonly used option yielding good estimation results.
|
||||
|
||||
* **EM::COV_MAT_GENERIC** A symmetric positively defined matrix. The number of free parameters in each matrix is about :math:`d^2/2`. It is not recommended to use this option, unless there is pretty accurate initial estimation of the parameters and/or a huge number of training samples.
|
||||
|
||||
:param termCrit: The termination criteria of the EM algorithm. The EM algorithm can be terminated by the number of iterations ``termCrit.maxCount`` (number of M-steps) or when relative change of likelihood logarithm is less than ``termCrit.epsilon``. Default maximum number of iterations is ``EM::DEFAULT_MAX_ITERS=100``.
|
||||
|
||||
|
||||
EM::create
|
||||
----------
|
||||
Creates empty EM model
|
||||
|
||||
.. ocv:function:: Ptr<EM> EM::create(const Params& params=Params())
|
||||
|
||||
:param params: EM parameters
|
||||
|
||||
The model should be trained then using ``StatModel::train(traindata, flags)`` method. Alternatively, you can use one of the ``EM::train*`` methods or load it from file using ``StatModel::load<EM>(filename)``.
|
||||
|
||||
EM::train
|
||||
---------
|
||||
Static methods that estimate the Gaussian mixture parameters from a samples set
|
||||
|
||||
.. ocv:function:: Ptr<EM> EM::train(InputArray samples, OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray(), const Params& params=Params())
|
||||
|
||||
.. ocv:function:: bool EM::train_startWithE(InputArray samples, InputArray means0, InputArray covs0=noArray(), InputArray weights0=noArray(), OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray(), const Params& params=Params())
|
||||
|
||||
.. ocv:function:: bool EM::train_startWithM(InputArray samples, InputArray probs0, OutputArray logLikelihoods=noArray(), OutputArray labels=noArray(), OutputArray probs=noArray(), const Params& params=Params())
|
||||
|
||||
:param samples: Samples from which the Gaussian mixture model will be estimated. It should be a one-channel matrix, each row of which is a sample. If the matrix does not have ``CV_64F`` type it will be converted to the inner matrix of such type for the further computing.
|
||||
|
||||
:param means0: Initial means :math:`a_k` of mixture components. It is a one-channel matrix of :math:`nclusters \times dims` size. If the matrix does not have ``CV_64F`` type it will be converted to the inner matrix of such type for the further computing.
|
||||
|
||||
:param covs0: The vector of initial covariance matrices :math:`S_k` of mixture components. Each of covariance matrices is a one-channel matrix of :math:`dims \times dims` size. If the matrices do not have ``CV_64F`` type they will be converted to the inner matrices of such type for the further computing.
|
||||
|
||||
:param weights0: Initial weights :math:`\pi_k` of mixture components. It should be a one-channel floating-point matrix with :math:`1 \times nclusters` or :math:`nclusters \times 1` size.
|
||||
|
||||
:param probs0: Initial probabilities :math:`p_{i,k}` of sample :math:`i` to belong to mixture component :math:`k`. It is a one-channel floating-point matrix of :math:`nsamples \times nclusters` size.
|
||||
|
||||
:param logLikelihoods: The optional output matrix that contains a likelihood logarithm value for each sample. It has :math:`nsamples \times 1` size and ``CV_64FC1`` type.
|
||||
|
||||
:param labels: The optional output "class label" for each sample: :math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N` (indices of the most probable mixture component for each sample). It has :math:`nsamples \times 1` size and ``CV_32SC1`` type.
|
||||
|
||||
:param probs: The optional output matrix that contains posterior probabilities of each Gaussian mixture component given the each sample. It has :math:`nsamples \times nclusters` size and ``CV_64FC1`` type.
|
||||
|
||||
:param params: The Gaussian mixture params, see ``EM::Params`` description above.
|
||||
|
||||
Three versions of training method differ in the initialization of Gaussian mixture model parameters and start step:
|
||||
|
||||
* **train** - Starts with Expectation step. Initial values of the model parameters will be estimated by the k-means algorithm.
|
||||
|
||||
* **trainE** - Starts with Expectation step. You need to provide initial means :math:`a_k` of mixture components. Optionally you can pass initial weights :math:`\pi_k` and covariance matrices :math:`S_k` of mixture components.
|
||||
|
||||
* **trainM** - Starts with Maximization step. You need to provide initial probabilities :math:`p_{i,k}` to use this option.
|
||||
|
||||
The methods return ``true`` if the Gaussian mixture model was trained successfully, otherwise it returns ``false``.
|
||||
|
||||
Unlike many of the ML models, EM is an unsupervised learning algorithm and it does not take responses (class labels or function values) as input. Instead, it computes the
|
||||
*Maximum Likelihood Estimate* of the Gaussian mixture parameters from an input sample set, stores all the parameters inside the structure:
|
||||
:math:`p_{i,k}` in ``probs``,
|
||||
:math:`a_k` in ``means`` ,
|
||||
:math:`S_k` in ``covs[k]``,
|
||||
:math:`\pi_k` in ``weights`` , and optionally computes the output "class label" for each sample:
|
||||
:math:`\texttt{labels}_i=\texttt{arg max}_k(p_{i,k}), i=1..N` (indices of the most probable mixture component for each sample).
|
||||
|
||||
The trained model can be used further for prediction, just like any other classifier. The trained model is similar to the
|
||||
``NormalBayesClassifier``.
|
||||
|
||||
EM::predict2
|
||||
------------
|
||||
Returns a likelihood logarithm value and an index of the most probable mixture component for the given sample.
|
||||
|
||||
.. ocv:function:: Vec2d EM::predict2(InputArray sample, OutputArray probs=noArray()) const
|
||||
|
||||
:param sample: A sample for classification. It should be a one-channel matrix of :math:`1 \times dims` or :math:`dims \times 1` size.
|
||||
|
||||
:param probs: Optional output matrix that contains posterior probabilities of each component given the sample. It has :math:`1 \times nclusters` size and ``CV_64FC1`` type.
|
||||
|
||||
The method returns a two-element ``double`` vector. Zero element is a likelihood logarithm value for the sample. First element is an index of the most probable mixture component for the given sample.
|
||||
|
||||
|
||||
EM::getMeans
|
||||
------------
|
||||
Returns the cluster centers (means of the Gaussian mixture)
|
||||
|
||||
.. ocv:function:: Mat EM::getMeans() const
|
||||
|
||||
Returns matrix with the number of rows equal to the number of mixtures and number of columns equal to the space dimensionality.
|
||||
|
||||
|
||||
EM::getWeights
|
||||
--------------
|
||||
Returns weights of the mixtures
|
||||
|
||||
.. ocv:function:: Mat EM::getWeights() const
|
||||
|
||||
Returns vector with the number of elements equal to the number of mixtures.
|
||||
|
||||
|
||||
EM::getCovs
|
||||
--------------
|
||||
Returns covariation matrices
|
||||
|
||||
.. ocv:function:: void EM::getCovs(std::vector<Mat>& covs) const
|
||||
|
||||
Returns vector of covariation matrices. Number of matrices is the number of gaussian mixtures, each matrix is a square floating-point matrix NxN, where N is the space dimensionality.
|
||||
@@ -1,71 +0,0 @@
|
||||
K-Nearest Neighbors
|
||||
===================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
The algorithm caches all training samples and predicts the response for a new sample by analyzing a certain number (**K**) of the nearest neighbors of the sample using voting, calculating weighted sum, and so on. The method is sometimes referred to as "learning by example" because for prediction it looks for the feature vector with a known response that is closest to the given vector.
|
||||
|
||||
KNearest
|
||||
----------
|
||||
.. ocv:class:: KNearest : public StatModel
|
||||
|
||||
The class implements K-Nearest Neighbors model as described in the beginning of this section.
|
||||
|
||||
.. note::
|
||||
|
||||
* (Python) An example of digit recognition using KNearest can be found at opencv_source/samples/python2/digits.py
|
||||
* (Python) An example of grid search digit recognition using KNearest can be found at opencv_source/samples/python2/digits_adjust.py
|
||||
* (Python) An example of video digit recognition using KNearest can be found at opencv_source/samples/python2/digits_video.py
|
||||
|
||||
KNearest::create
|
||||
----------------------
|
||||
Creates the empty model
|
||||
|
||||
.. ocv:function:: Ptr<KNearest> KNearest::create(const Params& params=Params())
|
||||
|
||||
:param params: The model parameters: default number of neighbors to use in predict method (in ``KNearest::findNearest`` this number must be passed explicitly) and the flag on whether classification or regression model should be trained.
|
||||
|
||||
The static method creates empty KNearest classifier. It should be then trained using ``train`` method (see ``StatModel::train``). Alternatively, you can load boost model from file using ``StatModel::load<KNearest>(filename)``.
|
||||
|
||||
|
||||
KNearest::findNearest
|
||||
------------------------
|
||||
Finds the neighbors and predicts responses for input vectors.
|
||||
|
||||
.. ocv:function:: float KNearest::findNearest( InputArray samples, int k, OutputArray results, OutputArray neighborResponses=noArray(), OutputArray dist=noArray() ) const
|
||||
|
||||
:param samples: Input samples stored by rows. It is a single-precision floating-point matrix of ``<number_of_samples> * k`` size.
|
||||
|
||||
:param k: Number of used nearest neighbors. Should be greater than 1.
|
||||
|
||||
:param results: Vector with results of prediction (regression or classification) for each input sample. It is a single-precision floating-point vector with ``<number_of_samples>`` elements.
|
||||
|
||||
:param neighborResponses: Optional output values for corresponding neighbors. It is a single-precision floating-point matrix of ``<number_of_samples> * k`` size.
|
||||
|
||||
:param dist: Optional output distances from the input vectors to the corresponding neighbors. It is a single-precision floating-point matrix of ``<number_of_samples> * k`` size.
|
||||
|
||||
For each input vector (a row of the matrix ``samples``), the method finds the ``k`` nearest neighbors. In case of regression, the predicted result is a mean value of the particular vector's neighbor responses. In case of classification, the class is determined by voting.
|
||||
|
||||
For each input vector, the neighbors are sorted by their distances to the vector.
|
||||
|
||||
In case of C++ interface you can use output pointers to empty matrices and the function will allocate memory itself.
|
||||
|
||||
If only a single input vector is passed, all output matrices are optional and the predicted value is returned by the method.
|
||||
|
||||
The function is parallelized with the TBB library.
|
||||
|
||||
KNearest::getDefaultK
|
||||
---------------------
|
||||
Returns the default number of neighbors
|
||||
|
||||
.. ocv:function:: int KNearest::getDefaultK() const
|
||||
|
||||
The function returns the default number of neighbors that is used in a simpler ``predict`` method, not ``findNearest``.
|
||||
|
||||
KNearest::setDefaultK
|
||||
---------------------
|
||||
Returns the default number of neighbors
|
||||
|
||||
.. ocv:function:: void KNearest::setDefaultK(int k)
|
||||
|
||||
The function sets the default number of neighbors that is used in a simpler ``predict`` method, not ``findNearest``.
|
||||
@@ -1,178 +0,0 @@
|
||||
Logistic Regression
|
||||
===================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
ML implements logistic regression, which is a probabilistic classification technique. Logistic Regression is a binary classification algorithm which is closely related to Support Vector Machines (SVM).
|
||||
Like SVM, Logistic Regression can be extended to work on multi-class classification problems like digit recognition (i.e. recognizing digitis like 0,1 2, 3,... from the given images).
|
||||
This version of Logistic Regression supports both binary and multi-class classifications (for multi-class it creates a multiple 2-class classifiers).
|
||||
In order to train the logistic regression classifier, Batch Gradient Descent and Mini-Batch Gradient Descent algorithms are used (see [BatchDesWiki]_).
|
||||
Logistic Regression is a discriminative classifier (see [LogRegTomMitch]_ for more details). Logistic Regression is implemented as a C++ class in ``LogisticRegression``.
|
||||
|
||||
|
||||
In Logistic Regression, we try to optimize the training paramater
|
||||
:math:`\theta`
|
||||
such that the hypothesis
|
||||
:math:`0 \leq h_\theta(x) \leq 1` is acheived.
|
||||
We have
|
||||
:math:`h_\theta(x) = g(h_\theta(x))`
|
||||
and
|
||||
:math:`g(z) = \frac{1}{1+e^{-z}}`
|
||||
as the logistic or sigmoid function.
|
||||
The term "Logistic" in Logistic Regression refers to this function.
|
||||
For given data of a binary classification problem of classes 0 and 1,
|
||||
one can determine that the given data instance belongs to class 1 if
|
||||
:math:`h_\theta(x) \geq 0.5`
|
||||
or class 0 if
|
||||
:math:`h_\theta(x) < 0.5`
|
||||
.
|
||||
|
||||
In Logistic Regression, choosing the right parameters is of utmost importance for reducing the training error and ensuring high training accuracy.
|
||||
``LogisticRegression::Params`` is the structure that defines parameters that are required to train a Logistic Regression classifier.
|
||||
The learning rate is determined by ``LogisticRegression::Params.alpha``. It determines how faster we approach the solution.
|
||||
It is a positive real number. Optimization algorithms like Batch Gradient Descent and Mini-Batch Gradient Descent are supported in ``LogisticRegression``.
|
||||
It is important that we mention the number of iterations these optimization algorithms have to run.
|
||||
The number of iterations are mentioned by ``LogisticRegression::Params.num_iters``.
|
||||
The number of iterations can be thought as number of steps taken and learning rate specifies if it is a long step or a short step. These two parameters define how fast we arrive at a possible solution.
|
||||
In order to compensate for overfitting regularization is performed, which can be enabled by setting ``LogisticRegression::Params.regularized`` to a positive integer (greater than zero).
|
||||
One can specify what kind of regularization has to be performed by setting ``LogisticRegression::Params.norm`` to ``LogisticRegression::REG_L1`` or ``LogisticRegression::REG_L2`` values.
|
||||
``LogisticRegression`` provides a choice of 2 training methods with Batch Gradient Descent or the Mini-Batch Gradient Descent. To specify this, set ``LogisticRegression::Params.train_method`` to either ``LogisticRegression::BATCH`` or ``LogisticRegression::MINI_BATCH``.
|
||||
If ``LogisticRegression::Params`` is set to ``LogisticRegression::MINI_BATCH``, the size of the mini batch has to be to a postive integer using ``LogisticRegression::Params.mini_batch_size``.
|
||||
|
||||
A sample set of training parameters for the Logistic Regression classifier can be initialized as follows:
|
||||
|
||||
::
|
||||
|
||||
LogisticRegression::Params params;
|
||||
params.alpha = 0.5;
|
||||
params.num_iters = 10000;
|
||||
params.norm = LogisticRegression::REG_L2;
|
||||
params.regularized = 1;
|
||||
params.train_method = LogisticRegression::MINI_BATCH;
|
||||
params.mini_batch_size = 10;
|
||||
|
||||
**References:**
|
||||
|
||||
.. [LogRegWiki] http://en.wikipedia.org/wiki/Logistic_regression. Wikipedia article about the Logistic Regression algorithm.
|
||||
|
||||
.. [RenMalik2003] Learning a Classification Model for Segmentation. Proc. CVPR, Nice, France (2003).
|
||||
|
||||
.. [LogRegTomMitch] http://www.cs.cmu.edu/~tom/NewChapters.html. "Generative and Discriminative Classifiers: Naive Bayes and Logistic Regression" in Machine Learning, Tom Mitchell.
|
||||
|
||||
.. [BatchDesWiki] http://en.wikipedia.org/wiki/Gradient_descent_optimization. Wikipedia article about Gradient Descent based optimization.
|
||||
|
||||
LogisticRegression::Params
|
||||
--------------------------
|
||||
.. ocv:struct:: LogisticRegression::Params
|
||||
|
||||
Parameters of the Logistic Regression training algorithm. You can initialize the structure using a constructor or declaring the variable and initializing the the individual parameters.
|
||||
|
||||
The training parameters for Logistic Regression:
|
||||
|
||||
.. ocv:member:: double alpha
|
||||
|
||||
The learning rate of the optimization algorithm. The higher the value, faster the rate and vice versa. If the value is too high, the learning algorithm may overshoot the optimal parameters and result in lower training accuracy. If the value is too low, the learning algorithm converges towards the optimal parameters very slowly. The value must a be a positive real number. You can experiment with different values with small increments as in 0.0001, 0.0003, 0.001, 0.003, 0.01, 0.03, 0.1, 0.3, ... and select the learning rate with less training error.
|
||||
|
||||
.. ocv:member:: int num_iters
|
||||
|
||||
The number of iterations required for the learing algorithm (Gradient Descent or Mini Batch Gradient Descent). It has to be a positive integer. You can try different number of iterations like in 100, 1000, 2000, 3000, 5000, 10000, .. so on.
|
||||
|
||||
.. ocv:member:: int norm
|
||||
|
||||
The type of normalization applied. It takes value ``LogisticRegression::L1`` or ``LogisticRegression::L2``.
|
||||
|
||||
.. ocv:member:: int regularized
|
||||
|
||||
It should be set to postive integer (greater than zero) in order to enable regularization.
|
||||
|
||||
.. ocv:member:: int train_method
|
||||
|
||||
The kind of training method used to train the classifier. It should be set to either ``LogisticRegression::BATCH`` or ``LogisticRegression::MINI_BATCH``.
|
||||
|
||||
.. ocv:member:: int mini_batch_size
|
||||
|
||||
If the training method is set to LogisticRegression::MINI_BATCH, it has to be set to positive integer. It can range from 1 to number of training samples.
|
||||
|
||||
.. ocv:member:: cv::TermCriteria term_crit
|
||||
|
||||
Sets termination criteria for training algorithm.
|
||||
|
||||
LogisticRegression::Params::Params
|
||||
----------------------------------
|
||||
The constructors
|
||||
|
||||
.. ocv:function:: LogisticRegression::Params::Params(double learning_rate = 0.001, int iters = 1000, int method = LogisticRegression::BATCH, int normlization = LogisticRegression::REG_L2, int reg = 1, int batch_size = 1)
|
||||
|
||||
:param learning_rate: Specifies the learning rate.
|
||||
|
||||
:param iters: Specifies the number of iterations.
|
||||
|
||||
:param train_method: Specifies the kind of training method used. It should be set to either ``LogisticRegression::BATCH`` or ``LogisticRegression::MINI_BATCH``. If using ``LogisticRegression::MINI_BATCH``, set ``LogisticRegression::Params.mini_batch_size`` to a positive integer.
|
||||
|
||||
:param normalization: Specifies the kind of regularization to be applied. ``LogisticRegression::REG_L1`` or ``LogisticRegression::REG_L2`` (L1 norm or L2 norm). To use this, set ``LogisticRegression::Params.regularized`` to a integer greater than zero.
|
||||
|
||||
:param reg: To enable or disable regularization. Set to positive integer (greater than zero) to enable and to 0 to disable.
|
||||
|
||||
:param mini_batch_size: Specifies the number of training samples taken in each step of Mini-Batch Gradient Descent. Will only be used if using ``LogisticRegression::MINI_BATCH`` training algorithm. It has to take values less than the total number of training samples.
|
||||
|
||||
By initializing this structure, one can set all the parameters required for Logistic Regression classifier.
|
||||
|
||||
LogisticRegression
|
||||
------------------
|
||||
|
||||
.. ocv:class:: LogisticRegression : public StatModel
|
||||
|
||||
Implements Logistic Regression classifier.
|
||||
|
||||
LogisticRegression::create
|
||||
--------------------------
|
||||
Creates empty model.
|
||||
|
||||
.. ocv:function:: Ptr<LogisticRegression> LogisticRegression::create( const Params& params = Params() )
|
||||
|
||||
:param params: The training parameters for the classifier of type ``LogisticRegression::Params``.
|
||||
|
||||
Creates Logistic Regression model with parameters given.
|
||||
|
||||
LogisticRegression::train
|
||||
-------------------------
|
||||
Trains the Logistic Regression classifier and returns true if successful.
|
||||
|
||||
.. ocv:function:: bool LogisticRegression::train( const Ptr<TrainData>& trainData, int flags=0 )
|
||||
|
||||
:param trainData: Instance of ml::TrainData class holding learning data.
|
||||
|
||||
:param flags: Not used.
|
||||
|
||||
LogisticRegression::predict
|
||||
---------------------------
|
||||
Predicts responses for input samples and returns a float type.
|
||||
|
||||
.. ocv:function:: void LogisticRegression::predict( InputArray samples, OutputArray results=noArray(), int flags=0 ) const
|
||||
|
||||
:param samples: The input data for the prediction algorithm. Matrix [m x n], where each row contains variables (features) of one object being classified. Should have data type ``CV_32F``.
|
||||
|
||||
:param results: Predicted labels as a column matrix of type ``CV_32S``.
|
||||
|
||||
:param flags: Not used.
|
||||
|
||||
|
||||
LogisticRegression::get_learnt_thetas
|
||||
-------------------------------------
|
||||
This function returns the trained paramters arranged across rows. For a two class classifcation problem, it returns a row matrix.
|
||||
|
||||
.. ocv:function:: Mat LogisticRegression::get_learnt_thetas() const
|
||||
|
||||
It returns learnt paramters of the Logistic Regression as a matrix of type ``CV_32F``.
|
||||
|
||||
LogisticRegression::read
|
||||
------------------------
|
||||
This function reads the trained LogisticRegression clasifier from disk.
|
||||
|
||||
.. ocv:function:: void LogisticRegression::read(const FileNode& fn)
|
||||
|
||||
LogisticRegression::write
|
||||
-------------------------
|
||||
This function writes the trained LogisticRegression clasifier to disk.
|
||||
|
||||
.. ocv:function:: void LogisticRegression::write(FileStorage& fs) const
|
||||
@@ -1,22 +0,0 @@
|
||||
********************
|
||||
ml. Machine Learning
|
||||
********************
|
||||
|
||||
The Machine Learning Library (MLL) is a set of classes and functions for statistical classification, regression, and clustering of data.
|
||||
|
||||
Most of the classification and regression algorithms are implemented as C++ classes. As the algorithms have different sets of features (like an ability to handle missing measurements or categorical input variables), there is a little common ground between the classes. This common ground is defined by the class `CvStatModel` that all the other ML classes are derived from.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
statistical_models
|
||||
normal_bayes_classifier
|
||||
k_nearest_neighbors
|
||||
support_vector_machines
|
||||
decision_trees
|
||||
boosting
|
||||
random_trees
|
||||
expectation_maximization
|
||||
neural_networks
|
||||
logistic_regression
|
||||
mldata
|
||||
@@ -1,126 +0,0 @@
|
||||
Training Data
|
||||
===================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
In machine learning algorithms there is notion of training data. Training data includes several components:
|
||||
|
||||
* A set of training samples. Each training sample is a vector of values (in Computer Vision it's sometimes referred to as feature vector). Usually all the vectors have the same number of components (features); OpenCV ml module assumes that. Each feature can be ordered (i.e. its values are floating-point numbers that can be compared with each other and strictly ordered, i.e. sorted) or categorical (i.e. its value belongs to a fixed set of values that can be integers, strings etc.).
|
||||
|
||||
* Optional set of responses corresponding to the samples. Training data with no responses is used in unsupervised learning algorithms that learn structure of the supplied data based on distances between different samples. Training data with responses is used in supervised learning algorithms, which learn the function mapping samples to responses. Usually the responses are scalar values, ordered (when we deal with regression problem) or categorical (when we deal with classification problem; in this case the responses are often called "labels"). Some algorithms, most noticeably Neural networks, can handle not only scalar, but also multi-dimensional or vector responses.
|
||||
|
||||
* Another optional component is the mask of missing measurements. Most algorithms require all the components in all the training samples be valid, but some other algorithms, such as decision tress, can handle the cases of missing measurements.
|
||||
|
||||
* In the case of classification problem user may want to give different weights to different classes. This is useful, for example, when
|
||||
* user wants to shift prediction accuracy towards lower false-alarm rate or higher hit-rate.
|
||||
* user wants to compensate for significantly different amounts of training samples from different classes.
|
||||
|
||||
* In addition to that, each training sample may be given a weight, if user wants the algorithm to pay special attention to certain training samples and adjust the training model accordingly.
|
||||
|
||||
* Also, user may wish not to use the whole training data at once, but rather use parts of it, e.g. to do parameter optimization via cross-validation procedure.
|
||||
|
||||
As you can see, training data can have rather complex structure; besides, it may be very big and/or not entirely available, so there is need to make abstraction for this concept. In OpenCV ml there is ``cv::ml::TrainData`` class for that.
|
||||
|
||||
TrainData
|
||||
---------
|
||||
.. ocv:class:: TrainData
|
||||
|
||||
Class encapsulating training data. Please note that the class only specifies the interface of training data, but not implementation. All the statistical model classes in ml take Ptr<TrainData>. In other words, you can create your own class derived from ``TrainData`` and supply smart pointer to the instance of this class into ``StatModel::train``.
|
||||
|
||||
TrainData::loadFromCSV
|
||||
----------------------
|
||||
Reads the dataset from a .csv file and returns the ready-to-use training data.
|
||||
|
||||
.. ocv:function:: Ptr<TrainData> loadFromCSV(const String& filename, int headerLineCount, int responseStartIdx=-1, int responseEndIdx=-1, const String& varTypeSpec=String(), char delimiter=',', char missch='?')
|
||||
|
||||
:param filename: The input file name
|
||||
|
||||
:param headerLineCount: The number of lines in the beginning to skip; besides the header, the function also skips empty lines and lines staring with '#'
|
||||
|
||||
:param responseStartIdx: Index of the first output variable. If -1, the function considers the last variable as the response
|
||||
|
||||
:param responseEndIdx: Index of the last output variable + 1. If -1, then there is single response variable at ``responseStartIdx``.
|
||||
|
||||
:param varTypeSpec: The optional text string that specifies the variables' types. It has the format ``ord[n1-n2,n3,n4-n5,...]cat[n6,n7-n8,...]``. That is, variables from n1 to n2 (inclusive range), n3, n4 to n5 ... are considered ordered and n6, n7 to n8 ... are considered as categorical. The range [n1..n2] + [n3] + [n4..n5] + ... + [n6] + [n7..n8] should cover all the variables. If varTypeSpec is not specified, then algorithm uses the following rules:
|
||||
1. all input variables are considered ordered by default. If some column contains has non-numerical values, e.g. 'apple', 'pear', 'apple', 'apple', 'mango', the corresponding variable is considered categorical.
|
||||
2. if there are several output variables, they are all considered as ordered. Error is reported when non-numerical values are used.
|
||||
3. if there is a single output variable, then if its values are non-numerical or are all integers, then it's considered categorical. Otherwise, it's considered ordered.
|
||||
|
||||
:param delimiter: The character used to separate values in each line.
|
||||
|
||||
:param missch: The character used to specify missing measurements. It should not be a digit. Although it's a non-numerical value, it surely does not affect the decision of whether the variable ordered or categorical.
|
||||
|
||||
TrainData::create
|
||||
-----------------
|
||||
Creates training data from in-memory arrays.
|
||||
|
||||
.. ocv:function:: Ptr<TrainData> create(InputArray samples, int layout, InputArray responses, InputArray varIdx=noArray(), InputArray sampleIdx=noArray(), InputArray sampleWeights=noArray(), InputArray varType=noArray())
|
||||
|
||||
:param samples: matrix of samples. It should have ``CV_32F`` type.
|
||||
|
||||
:param layout: it's either ``ROW_SAMPLE``, which means that each training sample is a row of ``samples``, or ``COL_SAMPLE``, which means that each training sample occupies a column of ``samples``.
|
||||
|
||||
:param responses: matrix of responses. If the responses are scalar, they should be stored as a single row or as a single column. The matrix should have type ``CV_32F`` or ``CV_32S`` (in the former case the responses are considered as ordered by default; in the latter case - as categorical)
|
||||
|
||||
:param varIdx: vector specifying which variables to use for training. It can be an integer vector (``CV_32S``) containing 0-based variable indices or byte vector (``CV_8U``) containing a mask of active variables.
|
||||
|
||||
:param sampleIdx: vector specifying which samples to use for training. It can be an integer vector (``CV_32S``) containing 0-based sample indices or byte vector (``CV_8U``) containing a mask of training samples.
|
||||
|
||||
:param sampleWeights: optional vector with weights for each sample. It should have ``CV_32F`` type.
|
||||
|
||||
:param varType: optional vector of type ``CV_8U`` and size <number_of_variables_in_samples> + <number_of_variables_in_responses>, containing types of each input and output variable. The ordered variables are denoted by value ``VAR_ORDERED``, and categorical - by ``VAR_CATEGORICAL``.
|
||||
|
||||
|
||||
TrainData::getTrainSamples
|
||||
--------------------------
|
||||
Returns matrix of train samples
|
||||
|
||||
.. ocv:function:: Mat TrainData::getTrainSamples(int layout=ROW_SAMPLE, bool compressSamples=true, bool compressVars=true) const
|
||||
|
||||
:param layout: The requested layout. If it's different from the initial one, the matrix is transposed.
|
||||
|
||||
:param compressSamples: if true, the function returns only the training samples (specified by sampleIdx)
|
||||
|
||||
:param compressVars: if true, the function returns the shorter training samples, containing only the active variables.
|
||||
|
||||
In current implementation the function tries to avoid physical data copying and returns the matrix stored inside TrainData (unless the transposition or compression is needed).
|
||||
|
||||
|
||||
TrainData::getTrainResponses
|
||||
----------------------------
|
||||
Returns the vector of responses
|
||||
|
||||
.. ocv:function:: Mat TrainData::getTrainResponses() const
|
||||
|
||||
The function returns ordered or the original categorical responses. Usually it's used in regression algorithms.
|
||||
|
||||
|
||||
TrainData::getClassLabels
|
||||
----------------------------
|
||||
Returns the vector of class labels
|
||||
|
||||
.. ocv:function:: Mat TrainData::getClassLabels() const
|
||||
|
||||
The function returns vector of unique labels occurred in the responses.
|
||||
|
||||
|
||||
TrainData::getTrainNormCatResponses
|
||||
-----------------------------------
|
||||
Returns the vector of normalized categorical responses
|
||||
|
||||
.. ocv:function:: Mat TrainData::getTrainNormCatResponses() const
|
||||
|
||||
The function returns vector of responses. Each response is integer from 0 to <number of classes>-1. The actual label value can be retrieved then from the class label vector, see ``TrainData::getClassLabels``.
|
||||
|
||||
TrainData::setTrainTestSplitRatio
|
||||
-----------------------------------
|
||||
Splits the training data into the training and test parts
|
||||
|
||||
.. ocv:function:: void TrainData::setTrainTestSplitRatio(double ratio, bool shuffle=true)
|
||||
|
||||
The function selects a subset of specified relative size and then returns it as the training set. If the function is not called, all the data is used for training. Please, note that for each of ``TrainData::getTrain*`` there is corresponding ``TrainData::getTest*``, so that the test subset can be retrieved and processed as well.
|
||||
|
||||
|
||||
Other methods
|
||||
-------------
|
||||
The class includes many other methods that can be used to access normalized categorical input variables, access training data by parts, so that does not have to fit into the memory etc.
|
||||
@@ -1,241 +0,0 @@
|
||||
Neural Networks
|
||||
===============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
ML implements feed-forward artificial neural networks or, more particularly, multi-layer perceptrons (MLP), the most commonly used type of neural networks. MLP consists of the input layer, output layer, and one or more hidden layers. Each layer of MLP includes one or more neurons directionally linked with the neurons from the previous and the next layer. The example below represents a 3-layer perceptron with three inputs, two outputs, and the hidden layer including five neurons:
|
||||
|
||||
.. image:: pics/mlp.png
|
||||
|
||||
All the neurons in MLP are similar. Each of them has several input links (it takes the output values from several neurons in the previous layer as input) and several output links (it passes the response to several neurons in the next layer). The values retrieved from the previous layer are summed up with certain weights, individual for each neuron, plus the bias term. The sum is transformed using the activation function
|
||||
:math:`f` that may be also different for different neurons.
|
||||
|
||||
.. image:: pics/neuron_model.png
|
||||
|
||||
In other words, given the outputs
|
||||
:math:`x_j` of the layer
|
||||
:math:`n` , the outputs
|
||||
:math:`y_i` of the layer
|
||||
:math:`n+1` are computed as:
|
||||
|
||||
.. math::
|
||||
|
||||
u_i = \sum _j (w^{n+1}_{i,j}*x_j) + w^{n+1}_{i,bias}
|
||||
|
||||
.. math::
|
||||
|
||||
y_i = f(u_i)
|
||||
|
||||
Different activation functions may be used. ML implements three standard functions:
|
||||
|
||||
*
|
||||
Identity function ( ``ANN_MLP::IDENTITY`` ):
|
||||
:math:`f(x)=x`
|
||||
*
|
||||
Symmetrical sigmoid ( ``ANN_MLP::SIGMOID_SYM`` ):
|
||||
:math:`f(x)=\beta*(1-e^{-\alpha x})/(1+e^{-\alpha x}` ), which is the default choice for MLP. The standard sigmoid with
|
||||
:math:`\beta =1, \alpha =1` is shown below:
|
||||
|
||||
.. image:: pics/sigmoid_bipolar.png
|
||||
|
||||
*
|
||||
Gaussian function ( ``ANN_MLP::GAUSSIAN`` ):
|
||||
:math:`f(x)=\beta e^{-\alpha x*x}` , which is not completely supported at the moment.
|
||||
|
||||
In ML, all the neurons have the same activation functions, with the same free parameters (
|
||||
:math:`\alpha, \beta` ) that are specified by user and are not altered by the training algorithms.
|
||||
|
||||
So, the whole trained network works as follows:
|
||||
|
||||
#. Take the feature vector as input. The vector size is equal to the size of the input layer.
|
||||
|
||||
#. Pass values as input to the first hidden layer.
|
||||
|
||||
#. Compute outputs of the hidden layer using the weights and the activation functions.
|
||||
|
||||
#. Pass outputs further downstream until you compute the output layer.
|
||||
|
||||
So, to compute the network, you need to know all the
|
||||
weights
|
||||
:math:`w^{n+1)}_{i,j}` . The weights are computed by the training
|
||||
algorithm. The algorithm takes a training set, multiple input vectors
|
||||
with the corresponding output vectors, and iteratively adjusts the
|
||||
weights to enable the network to give the desired response to the
|
||||
provided input vectors.
|
||||
|
||||
The larger the network size (the number of hidden layers and their sizes) is,
|
||||
the more the potential network flexibility is. The error on the
|
||||
training set could be made arbitrarily small. But at the same time the
|
||||
learned network also "learns" the noise present in the training set,
|
||||
so the error on the test set usually starts increasing after the network
|
||||
size reaches a limit. Besides, the larger networks are trained much
|
||||
longer than the smaller ones, so it is reasonable to pre-process the data,
|
||||
using
|
||||
:ocv:funcx:`PCA::operator()` or similar technique, and train a smaller network
|
||||
on only essential features.
|
||||
|
||||
Another MLP feature is an inability to handle categorical
|
||||
data as is. However, there is a workaround. If a certain feature in the
|
||||
input or output (in case of ``n`` -class classifier for
|
||||
:math:`n>2` ) layer is categorical and can take
|
||||
:math:`M>2` different values, it makes sense to represent it as a binary tuple of ``M`` elements, where the ``i`` -th element is 1 if and only if the
|
||||
feature is equal to the ``i`` -th value out of ``M`` possible. It
|
||||
increases the size of the input/output layer but speeds up the
|
||||
training algorithm convergence and at the same time enables "fuzzy" values
|
||||
of such variables, that is, a tuple of probabilities instead of a fixed value.
|
||||
|
||||
ML implements two algorithms for training MLP's. The first algorithm is a classical
|
||||
random sequential back-propagation algorithm.
|
||||
The second (default) one is a batch RPROP algorithm.
|
||||
|
||||
.. [BackPropWikipedia] http://en.wikipedia.org/wiki/Backpropagation. Wikipedia article about the back-propagation algorithm.
|
||||
|
||||
.. [LeCun98] Y. LeCun, L. Bottou, G.B. Orr and K.-R. Muller, *Efficient backprop*, in Neural Networks---Tricks of the Trade, Springer Lecture Notes in Computer Sciences 1524, pp.5-50, 1998.
|
||||
|
||||
.. [RPROP93] M. Riedmiller and H. Braun, *A Direct Adaptive Method for Faster Backpropagation Learning: The RPROP Algorithm*, Proc. ICNN, San Francisco (1993).
|
||||
|
||||
|
||||
ANN_MLP::Params
|
||||
---------------------
|
||||
.. ocv:class:: ANN_MLP::Params
|
||||
|
||||
Parameters of the MLP and of the training algorithm. You can initialize the structure by a constructor or the individual parameters can be adjusted after the structure is created.
|
||||
|
||||
The network structure:
|
||||
|
||||
.. ocv:member:: Mat layerSizes
|
||||
|
||||
The number of elements in each layer of network. The very first element specifies the number of elements in the input layer. The last element - number of elements in the output layer.
|
||||
|
||||
.. ocv:member:: int activateFunc
|
||||
|
||||
The activation function. Currently the only fully supported activation function is ``ANN_MLP::SIGMOID_SYM``.
|
||||
|
||||
.. ocv:member:: double fparam1
|
||||
|
||||
The first parameter of activation function, 0 by default.
|
||||
|
||||
.. ocv:member:: double fparam2
|
||||
|
||||
The second parameter of the activation function, 0 by default.
|
||||
|
||||
.. note::
|
||||
|
||||
If you are using the default ``ANN_MLP::SIGMOID_SYM`` activation function with the default parameter values fparam1=0 and fparam2=0 then the function used is y = 1.7159*tanh(2/3 * x), so the output will range from [-1.7159, 1.7159], instead of [0,1].
|
||||
|
||||
The back-propagation algorithm parameters:
|
||||
|
||||
.. ocv:member:: double bpDWScale
|
||||
|
||||
Strength of the weight gradient term. The recommended value is about 0.1.
|
||||
|
||||
.. ocv:member:: double bpMomentScale
|
||||
|
||||
Strength of the momentum term (the difference between weights on the 2 previous iterations). This parameter provides some inertia to smooth the random fluctuations of the weights. It can vary from 0 (the feature is disabled) to 1 and beyond. The value 0.1 or so is good enough
|
||||
|
||||
The RPROP algorithm parameters (see [RPROP93]_ for details):
|
||||
|
||||
.. ocv:member:: double prDW0
|
||||
|
||||
Initial value :math:`\Delta_0` of update-values :math:`\Delta_{ij}`.
|
||||
|
||||
.. ocv:member:: double rpDWPlus
|
||||
|
||||
Increase factor :math:`\eta^+`. It must be >1.
|
||||
|
||||
.. ocv:member:: double rpDWMinus
|
||||
|
||||
Decrease factor :math:`\eta^-`. It must be <1.
|
||||
|
||||
.. ocv:member:: double rpDWMin
|
||||
|
||||
Update-values lower limit :math:`\Delta_{min}`. It must be positive.
|
||||
|
||||
.. ocv:member:: double rpDWMax
|
||||
|
||||
Update-values upper limit :math:`\Delta_{max}`. It must be >1.
|
||||
|
||||
|
||||
ANN_MLP::Params::Params
|
||||
--------------------------------------------
|
||||
Construct the parameter structure
|
||||
|
||||
.. ocv:function:: ANN_MLP::Params()
|
||||
|
||||
.. ocv:function:: ANN_MLP::Params::Params( const Mat& layerSizes, int activateFunc, double fparam1, double fparam2, TermCriteria termCrit, int trainMethod, double param1, double param2=0 )
|
||||
|
||||
:param layerSizes: Integer vector specifying the number of neurons in each layer including the input and output layers.
|
||||
|
||||
:param activateFunc: Parameter specifying the activation function for each neuron: one of ``ANN_MLP::IDENTITY``, ``ANN_MLP::SIGMOID_SYM``, and ``ANN_MLP::GAUSSIAN``.
|
||||
|
||||
:param fparam1: The first parameter of the activation function, :math:`\alpha`. See the formulas in the introduction section.
|
||||
|
||||
:param fparam2: The second parameter of the activation function, :math:`\beta`. See the formulas in the introduction section.
|
||||
|
||||
:param termCrit: Termination criteria of the training algorithm. You can specify the maximum number of iterations (``maxCount``) and/or how much the error could change between the iterations to make the algorithm continue (``epsilon``).
|
||||
|
||||
:param train_method: Training method of the MLP. Possible values are:
|
||||
|
||||
* **ANN_MLP_TrainParams::BACKPROP** The back-propagation algorithm.
|
||||
|
||||
* **ANN_MLP_TrainParams::RPROP** The RPROP algorithm.
|
||||
|
||||
:param param1: Parameter of the training method. It is ``rp_dw0`` for ``RPROP`` and ``bp_dw_scale`` for ``BACKPROP``.
|
||||
|
||||
:param param2: Parameter of the training method. It is ``rp_dw_min`` for ``RPROP`` and ``bp_moment_scale`` for ``BACKPROP``.
|
||||
|
||||
By default the RPROP algorithm is used:
|
||||
|
||||
::
|
||||
|
||||
ANN_MLP_TrainParams::ANN_MLP_TrainParams()
|
||||
{
|
||||
layerSizes = Mat();
|
||||
activateFun = SIGMOID_SYM;
|
||||
fparam1 = fparam2 = 0;
|
||||
term_crit = TermCriteria( TermCriteria::MAX_ITER + TermCriteria::EPS, 1000, 0.01 );
|
||||
train_method = RPROP;
|
||||
bpDWScale = bpMomentScale = 0.1;
|
||||
rpDW0 = 0.1; rpDWPlus = 1.2; rpDWMinus = 0.5;
|
||||
rpDWMin = FLT_EPSILON; rpDWMax = 50.;
|
||||
}
|
||||
|
||||
ANN_MLP
|
||||
---------
|
||||
.. ocv:class:: ANN_MLP : public StatModel
|
||||
|
||||
MLP model.
|
||||
|
||||
Unlike many other models in ML that are constructed and trained at once, in the MLP model these steps are separated. First, a network with the specified topology is created using the non-default constructor or the method :ocv:func:`ANN_MLP::create`. All the weights are set to zeros. Then, the network is trained using a set of input and output vectors. The training procedure can be repeated more than once, that is, the weights can be adjusted based on the new training data.
|
||||
|
||||
|
||||
ANN_MLP::create
|
||||
--------------------
|
||||
Creates empty model
|
||||
|
||||
.. ocv:function:: Ptr<ANN_MLP> ANN_MLP::create(const Params& params=Params())
|
||||
|
||||
Use ``StatModel::train`` to train the model, ``StatModel::train<ANN_MLP>(traindata, params)`` to create and train the model, ``StatModel::load<ANN_MLP>(filename)`` to load the pre-trained model. Note that the train method has optional flags, and the following flags are handled by ``ANN_MLP``:
|
||||
|
||||
* **UPDATE_WEIGHTS** Algorithm updates the network weights, rather than computes them from scratch. In the latter case the weights are initialized using the Nguyen-Widrow algorithm.
|
||||
|
||||
* **NO_INPUT_SCALE** Algorithm does not normalize the input vectors. If this flag is not set, the training algorithm normalizes each input feature independently, shifting its mean value to 0 and making the standard deviation equal to 1. If the network is assumed to be updated frequently, the new training data could be much different from original one. In this case, you should take care of proper normalization.
|
||||
|
||||
* **NO_OUTPUT_SCALE** Algorithm does not normalize the output vectors. If the flag is not set, the training algorithm normalizes each output feature independently, by transforming it to the certain range depending on the used activation function.
|
||||
|
||||
|
||||
ANN_MLP::setParams
|
||||
-------------------
|
||||
Sets the new network parameters
|
||||
|
||||
.. ocv:function:: void ANN_MLP::setParams(const Params& params)
|
||||
|
||||
:param params: The new parameters
|
||||
|
||||
The existing network, if any, will be destroyed and new empty one will be created. It should be re-trained after that.
|
||||
|
||||
ANN_MLP::getParams
|
||||
-------------------
|
||||
Retrieves the current network parameters
|
||||
|
||||
.. ocv:function:: Params ANN_MLP::getParams() const
|
||||
@@ -1,34 +0,0 @@
|
||||
.. _Bayes Classifier:
|
||||
|
||||
Normal Bayes Classifier
|
||||
=======================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
This simple classification model assumes that feature vectors from each class are normally distributed (though, not necessarily independently distributed). So, the whole data distribution function is assumed to be a Gaussian mixture, one component per class. Using the training data the algorithm estimates mean vectors and covariance matrices for every class, and then it uses them for prediction.
|
||||
|
||||
.. [Fukunaga90] K. Fukunaga. *Introduction to Statistical Pattern Recognition*. second ed., New York: Academic Press, 1990.
|
||||
|
||||
NormalBayesClassifier
|
||||
-----------------------
|
||||
.. ocv:class:: NormalBayesClassifier : public StatModel
|
||||
|
||||
Bayes classifier for normally distributed data.
|
||||
|
||||
NormalBayesClassifier::create
|
||||
-----------------------------
|
||||
Creates empty model
|
||||
|
||||
.. ocv:function:: Ptr<NormalBayesClassifier> NormalBayesClassifier::create(const NormalBayesClassifier::Params& params=Params())
|
||||
|
||||
:param params: The model parameters. There is none so far, the structure is used as a placeholder for possible extensions.
|
||||
|
||||
Use ``StatModel::train`` to train the model, ``StatModel::train<NormalBayesClassifier>(traindata, params)`` to create and train the model, ``StatModel::load<NormalBayesClassifier>(filename)`` to load the pre-trained model.
|
||||
|
||||
NormalBayesClassifier::predictProb
|
||||
----------------------------------
|
||||
Predicts the response for sample(s).
|
||||
|
||||
.. ocv:function:: float NormalBayesClassifier::predictProb( InputArray inputs, OutputArray outputs, OutputArray outputProbs, int flags=0 ) const
|
||||
|
||||
The method estimates the most probable classes for input vectors. Input vectors (one or more) are stored as rows of the matrix ``inputs``. In case of multiple input vectors, there should be one output vector ``outputs``. The predicted class for a single input vector is returned by the method. The vector ``outputProbs`` contains the output probabilities corresponding to each element of ``result``.
|
||||
@@ -1,103 +0,0 @@
|
||||
.. _Random Trees:
|
||||
|
||||
Random Trees
|
||||
============
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
Random trees have been introduced by Leo Breiman and Adele Cutler:
|
||||
http://www.stat.berkeley.edu/users/breiman/RandomForests/
|
||||
. The algorithm can deal with both classification and regression problems. Random trees is a collection (ensemble) of tree predictors that is called
|
||||
*forest*
|
||||
further in this section (the term has been also introduced by L. Breiman). The classification works as follows: the random trees classifier takes the input feature vector, classifies it with every tree in the forest, and outputs the class label that received the majority of "votes". In case of a regression, the classifier response is the average of the responses over all the trees in the forest.
|
||||
|
||||
All the trees are trained with the same parameters but on different training sets. These sets are generated from the original training set using the bootstrap procedure: for each training set, you randomly select the same number of vectors as in the original set ( ``=N`` ). The vectors are chosen with replacement. That is, some vectors will occur more than once and some will be absent. At each node of each trained tree, not all the variables are used to find the best split, but a random subset of them. With each node a new subset is generated. However, its size is fixed for all the nodes and all the trees. It is a training parameter set to
|
||||
:math:`\sqrt{number\_of\_variables}` by default. None of the built trees are pruned.
|
||||
|
||||
In random trees there is no need for any accuracy estimation procedures, such as cross-validation or bootstrap, or a separate test set to get an estimate of the training error. The error is estimated internally during the training. When the training set for the current tree is drawn by sampling with replacement, some vectors are left out (so-called
|
||||
*oob (out-of-bag) data*
|
||||
). The size of oob data is about ``N/3`` . The classification error is estimated by using this oob-data as follows:
|
||||
|
||||
#.
|
||||
Get a prediction for each vector, which is oob relative to the i-th tree, using the very i-th tree.
|
||||
|
||||
#.
|
||||
After all the trees have been trained, for each vector that has ever been oob, find the class-*winner* for it (the class that has got the majority of votes in the trees where the vector was oob) and compare it to the ground-truth response.
|
||||
|
||||
#.
|
||||
Compute the classification error estimate as a ratio of the number of misclassified oob vectors to all the vectors in the original data. In case of regression, the oob-error is computed as the squared error for oob vectors difference divided by the total number of vectors.
|
||||
|
||||
|
||||
For the random trees usage example, please, see letter_recog.cpp sample in OpenCV distribution.
|
||||
|
||||
**References:**
|
||||
|
||||
* *Machine Learning*, Wald I, July 2002. http://stat-www.berkeley.edu/users/breiman/wald2002-1.pdf
|
||||
|
||||
* *Looking Inside the Black Box*, Wald II, July 2002. http://stat-www.berkeley.edu/users/breiman/wald2002-2.pdf
|
||||
|
||||
* *Software for the Masses*, Wald III, July 2002. http://stat-www.berkeley.edu/users/breiman/wald2002-3.pdf
|
||||
|
||||
* And other articles from the web site http://www.stat.berkeley.edu/users/breiman/RandomForests/cc_home.htm
|
||||
|
||||
RTrees::Params
|
||||
--------------
|
||||
.. ocv:struct:: RTrees::Params : public DTrees::Params
|
||||
|
||||
Training parameters of random trees.
|
||||
|
||||
The set of training parameters for the forest is a superset of the training parameters for a single tree. However, random trees do not need all the functionality/features of decision trees. Most noticeably, the trees are not pruned, so the cross-validation parameters are not used.
|
||||
|
||||
|
||||
RTrees::Params::Params
|
||||
-----------------------
|
||||
The constructors
|
||||
|
||||
.. ocv:function:: RTrees::Params::Params()
|
||||
|
||||
.. ocv:function:: RTrees::Params::Params( int maxDepth, int minSampleCount, double regressionAccuracy, bool useSurrogates, int maxCategories, const Mat& priors, bool calcVarImportance, int nactiveVars, TermCriteria termCrit )
|
||||
|
||||
:param maxDepth: the depth of the tree. A low value will likely underfit and conversely a high value will likely overfit. The optimal value can be obtained using cross validation or other suitable methods.
|
||||
|
||||
:param minSampleCount: minimum samples required at a leaf node for it to be split. A reasonable value is a small percentage of the total data e.g. 1%.
|
||||
|
||||
:param maxCategories: Cluster possible values of a categorical variable into ``K <= maxCategories`` clusters to find a suboptimal split. If a discrete variable, on which the training procedure tries to make a split, takes more than ``max_categories`` values, the precise best subset estimation may take a very long time because the algorithm is exponential. Instead, many decision trees engines (including ML) try to find sub-optimal split in this case by clustering all the samples into ``maxCategories`` clusters that is some categories are merged together. The clustering is applied only in ``n``>2-class classification problems for categorical variables with ``N > max_categories`` possible values. In case of regression and 2-class classification the optimal split can be found efficiently without employing clustering, thus the parameter is not used in these cases.
|
||||
|
||||
:param calcVarImportance: If true then variable importance will be calculated and then it can be retrieved by ``RTrees::getVarImportance``.
|
||||
|
||||
:param nactiveVars: The size of the randomly selected subset of features at each tree node and that are used to find the best split(s). If you set it to 0 then the size will be set to the square root of the total number of features.
|
||||
|
||||
:param termCrit: The termination criteria that specifies when the training algorithm stops - either when the specified number of trees is trained and added to the ensemble or when sufficient accuracy (measured as OOB error) is achieved. Typically the more trees you have the better the accuracy. However, the improvement in accuracy generally diminishes and asymptotes pass a certain number of trees. Also to keep in mind, the number of tree increases the prediction time linearly.
|
||||
|
||||
The default constructor sets all parameters to default values which are different from default values of ``DTrees::Params``:
|
||||
|
||||
::
|
||||
|
||||
RTrees::Params::Params() : DTrees::Params( 5, 10, 0, false, 10, 0, false, false, Mat() ),
|
||||
calcVarImportance(false), nactiveVars(0)
|
||||
{
|
||||
termCrit = cvTermCriteria( TermCriteria::MAX_ITERS + TermCriteria::EPS, 50, 0.1 );
|
||||
}
|
||||
|
||||
|
||||
RTrees
|
||||
--------
|
||||
.. ocv:class:: RTrees : public DTrees
|
||||
|
||||
The class implements the random forest predictor as described in the beginning of this section.
|
||||
|
||||
RTrees::create
|
||||
---------------
|
||||
Creates the empty model
|
||||
|
||||
.. ocv:function:: bool RTrees::create(const RTrees::Params& params=Params())
|
||||
|
||||
Use ``StatModel::train`` to train the model, ``StatModel::train<RTrees>(traindata, params)`` to create and train the model, ``StatModel::load<RTrees>(filename)`` to load the pre-trained model.
|
||||
|
||||
RTrees::getVarImportance
|
||||
----------------------------
|
||||
Returns the variable importance array.
|
||||
|
||||
.. ocv:function:: Mat RTrees::getVarImportance() const
|
||||
|
||||
The method returns the variable importance vector, computed at the training stage when ``RTParams::calcVarImportance`` is set to true. If this flag was set to false, the empty matrix is returned.
|
||||
@@ -1,112 +0,0 @@
|
||||
Statistical Models
|
||||
==================
|
||||
|
||||
.. highlight:: cpp
|
||||
|
||||
.. index:: StatModel
|
||||
|
||||
StatModel
|
||||
-----------
|
||||
.. ocv:class:: StatModel
|
||||
|
||||
Base class for statistical models in OpenCV ML.
|
||||
|
||||
|
||||
StatModel::train
|
||||
------------------------
|
||||
Trains the statistical model
|
||||
|
||||
.. ocv:function:: bool StatModel::train( const Ptr<TrainData>& trainData, int flags=0 )
|
||||
|
||||
.. ocv:function:: bool StatModel::train( InputArray samples, int layout, InputArray responses )
|
||||
|
||||
.. ocv:function:: Ptr<_Tp> StatModel::train(const Ptr<TrainData>& data, const _Tp::Params& p, int flags=0 )
|
||||
|
||||
.. ocv:function:: Ptr<_Tp> StatModel::train(InputArray samples, int layout, InputArray responses, const _Tp::Params& p, int flags=0 )
|
||||
|
||||
:param trainData: training data that can be loaded from file using ``TrainData::loadFromCSV`` or created with ``TrainData::create``.
|
||||
|
||||
:param samples: training samples
|
||||
|
||||
:param layout: ``ROW_SAMPLE`` (training samples are the matrix rows) or ``COL_SAMPLE`` (training samples are the matrix columns)
|
||||
|
||||
:param responses: vector of responses associated with the training samples.
|
||||
|
||||
:param p: the stat model parameters.
|
||||
|
||||
:param flags: optional flags, depending on the model. Some of the models can be updated with the new training samples, not completely overwritten (such as ``NormalBayesClassifier`` or ``ANN_MLP``).
|
||||
|
||||
There are 2 instance methods and 2 static (class) template methods. The first two train the already created model (the very first method must be overwritten in the derived classes). And the latter two variants are convenience methods that construct empty model and then call its train method.
|
||||
|
||||
|
||||
StatModel::isTrained
|
||||
-----------------------------
|
||||
Returns true if the model is trained
|
||||
|
||||
.. ocv:function:: bool StatModel::isTrained()
|
||||
|
||||
The method must be overwritten in the derived classes.
|
||||
|
||||
StatModel::isClassifier
|
||||
-----------------------------
|
||||
Returns true if the model is classifier
|
||||
|
||||
.. ocv:function:: bool StatModel::isClassifier()
|
||||
|
||||
The method must be overwritten in the derived classes.
|
||||
|
||||
StatModel::getVarCount
|
||||
-----------------------------
|
||||
Returns the number of variables in training samples
|
||||
|
||||
.. ocv:function:: int StatModel::getVarCount()
|
||||
|
||||
The method must be overwritten in the derived classes.
|
||||
|
||||
StatModel::predict
|
||||
------------------
|
||||
Predicts response(s) for the provided sample(s)
|
||||
|
||||
.. ocv:function:: float StatModel::predict( InputArray samples, OutputArray results=noArray(), int flags=0 ) const
|
||||
|
||||
:param samples: The input samples, floating-point matrix
|
||||
|
||||
:param results: The optional output matrix of results.
|
||||
|
||||
:param flags: The optional flags, model-dependent. Some models, such as ``Boost``, ``SVM`` recognize ``StatModel::RAW_OUTPUT`` flag, which makes the method return the raw results (the sum), not the class label.
|
||||
|
||||
|
||||
StatModel::calcError
|
||||
-------------------------
|
||||
Computes error on the training or test dataset
|
||||
|
||||
.. ocv:function:: float StatModel::calcError( const Ptr<TrainData>& data, bool test, OutputArray resp ) const
|
||||
|
||||
:param data: the training data
|
||||
|
||||
:param test: if true, the error is computed over the test subset of the data, otherwise it's computed over the training subset of the data. Please note that if you loaded a completely different dataset to evaluate already trained classifier, you will probably want not to set the test subset at all with ``TrainData::setTrainTestSplitRatio`` and specify ``test=false``, so that the error is computed for the whole new set. Yes, this sounds a bit confusing.
|
||||
|
||||
:param resp: the optional output responses.
|
||||
|
||||
The method uses ``StatModel::predict`` to compute the error. For regression models the error is computed as RMS, for classifiers - as a percent of missclassified samples (0%-100%).
|
||||
|
||||
|
||||
StatModel::save
|
||||
-----------------
|
||||
Saves the model to a file.
|
||||
|
||||
.. ocv:function:: void StatModel::save( const String& filename )
|
||||
|
||||
In order to make this method work, the derived class must overwrite ``Algorithm::write(FileStorage& fs)``.
|
||||
|
||||
StatModel::load
|
||||
-----------------
|
||||
Loads model from the file
|
||||
|
||||
.. ocv:function:: Ptr<_Tp> StatModel::load( const String& filename )
|
||||
|
||||
This is static template method of StatModel. It's usage is following (in the case of SVM): ::
|
||||
|
||||
Ptr<SVM> svm = StatModel::load<SVM>("my_svm_model.xml");
|
||||
|
||||
In order to make this method work, the derived class must overwrite ``Algorithm::read(const FileNode& fn)``.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user