mirror of
https://github.com/opencv/opencv.git
synced 2026-07-31 00:03:03 +04:00
merged 2.4 into trunk
This commit is contained in:
Vadim Pisarevsky
@@ -171,8 +171,49 @@ RotatedRect
|
||||
-----------
|
||||
.. ocv:class:: RotatedRect
|
||||
|
||||
Template class for rotated rectangles specified by the center, size, and the rotation angle in degrees.
|
||||
The class represents rotated (i.e. not up-right) rectangles on a plane. Each rectangle is specified by the center point (mass center), length of each side (represented by cv::Size2f structure) and the rotation angle in degrees.
|
||||
|
||||
.. ocv:function:: RotatedRect::RotatedRect()
|
||||
.. ocv:function:: RotatedRect::RotatedRect(const Point2f& center, const Size2f& size, float angle)
|
||||
.. ocv:function:: RotatedRect::RotatedRect(const CvBox2D& box)
|
||||
|
||||
:param center: The rectangle mass center.
|
||||
:param size: Width and height of the rectangle.
|
||||
:param angle: The rotation angle in a clockwise direction. When the angle is 0, 90, 180, 270 etc., the rectangle becomes an up-right rectangle.
|
||||
:param box: The rotated rectangle parameters as the obsolete CvBox2D structure.
|
||||
|
||||
.. ocv:function:: void RotatedRect::points(Point2f* pts) const
|
||||
.. ocv:function:: Rect RotatedRect::boundingRect() const
|
||||
.. ocv:function:: RotatedRect::operator CvBox2D() const
|
||||
|
||||
:param pts: The points array for storing rectangle vertices.
|
||||
|
||||
The sample below demonstrates how to use RotatedRect:
|
||||
|
||||
::
|
||||
|
||||
Mat image(200, 200, CV_8UC3, Scalar(0));
|
||||
RotatedRect rRect = RotatedRect(Point2f(100,100), Size2f(100,50), 30);
|
||||
|
||||
Point2f vertices[4];
|
||||
rRect.points(vertices);
|
||||
for (int i = 0; i < 4; i++)
|
||||
line(image, vertices[i], vertices[(i+1)%4], Scalar(0,255,0));
|
||||
|
||||
Rect brect = rRect.boundingRect();
|
||||
rectangle(image, brect, Scalar(255,0,0));
|
||||
|
||||
imshow("rectangles", image);
|
||||
waitKey(0);
|
||||
|
||||
.. image:: pics/rotatedrect.png
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ocv:cfunc:`CamShift`,
|
||||
:ocv:func:`fitEllipse`,
|
||||
:ocv:func:`minAreaRect`,
|
||||
:ocv:struct:`CvBox2D`
|
||||
|
||||
TermCriteria
|
||||
------------
|
||||
@@ -1773,6 +1814,84 @@ To use ``Mat_`` for multi-channel images/matrices, pass ``Vec`` as a ``Mat_`` pa
|
||||
img(i,j)[2] ^= (uchar)(i ^ j);
|
||||
|
||||
|
||||
InputArray
|
||||
----------
|
||||
|
||||
This is the proxy class for passing read-only input arrays into OpenCV functions. It is defined as ::
|
||||
|
||||
typedef const _InputArray& InputArray;
|
||||
|
||||
where ``_InputArray`` is a class that can be constructed from ``Mat``, ``Mat_<T>``, ``Matx<T, m, n>``, ``std::vector<T>``, ``std::vector<std::vector<T> >`` or ``std::vector<Mat>``. It can also be constructed from a matrix expression.
|
||||
|
||||
Since this is mostly implementation-level class, and its interface may change in future versions, we do not describe it in details. There are a few key things, though, that should be kept in mind:
|
||||
|
||||
* When you see in the reference manual or in OpenCV source code a function that takes ``InputArray``, it means that you can actually pass ``Mat``, ``Matx``, ``vector<T>`` etc. (see above the complete list).
|
||||
|
||||
* Optional input arguments: If some of the input arrays may be empty, pass ``cv::noArray()`` (or simply ``cv::Mat()`` as you probably did before).
|
||||
|
||||
* The class is designed solely for passing parameters. That is, normally you *should not* declare class members, local and global variables of this type.
|
||||
|
||||
* If you want to design your own function or a class method that can operate of arrays of multiple types, you can use ``InputArray`` (or ``OutputArray``) for the respective parameters. Inside a function you should use ``_InputArray::getMat()`` method to construct a matrix header for the array (without copying data). ``_InputArray::kind()`` can be used to distinguish ``Mat`` from ``vector<>`` etc., but normally it is not needed.
|
||||
|
||||
Here is how you can use a function that takes ``InputArray`` ::
|
||||
|
||||
std::vector<Point2f> vec;
|
||||
// points or a circle
|
||||
for( int i = 0; i < 30; i++ )
|
||||
vec.push_back(Point2f((float)(100 + 30*cos(i*CV_PI*2/5)),
|
||||
(float)(100 - 30*sin(i*CV_PI*2/5))));
|
||||
cv::transform(vec, vec, cv::Matx23f(0.707, -0.707, 10, 0.707, 0.707, 20));
|
||||
|
||||
That is, we form an STL vector containing points, and apply in-place affine transformation to the vector using the 2x3 matrix created inline as ``Matx<float, 2, 3>`` instance.
|
||||
|
||||
Here is how such a function can be implemented (for simplicity, we implement a very specific case of it, according to the assertion statement inside) ::
|
||||
|
||||
void myAffineTransform(InputArray _src, OutputArray _dst, InputArray _m)
|
||||
{
|
||||
// get Mat headers for input arrays. This is O(1) operation,
|
||||
// unless _src and/or _m are matrix expressions.
|
||||
Mat src = _src.getMat(), m = _m.getMat();
|
||||
CV_Assert( src.type() == CV_32FC2 && m.type() == CV_32F && m.size() == Size(3, 2) );
|
||||
|
||||
// [re]create the output array so that it has the proper size and type.
|
||||
// In case of Mat it calls Mat::create, in case of STL vector it calls vector::resize.
|
||||
_dst.create(src.size(), src.type());
|
||||
Mat dst = _dst.getMat();
|
||||
|
||||
for( int i = 0; i < src.rows; i++ )
|
||||
for( int j = 0; j < src.cols; j++ )
|
||||
{
|
||||
Point2f pt = src.at<Point2f>(i, j);
|
||||
dst.at<Point2f>(i, j) = Point2f(m.at<float>(0, 0)*pt.x +
|
||||
m.at<float>(0, 1)*pt.y +
|
||||
m.at<float>(0, 2),
|
||||
m.at<float>(1, 0)*pt.x +
|
||||
m.at<float>(1, 1)*pt.y +
|
||||
m.at<float>(1, 2));
|
||||
}
|
||||
}
|
||||
|
||||
There is another related type, ``InputArrayOfArrays``, which is currently defined as a synonym for ``InputArray``: ::
|
||||
|
||||
typedef InputArray InputArrayOfArrays;
|
||||
|
||||
It denotes function arguments that are either vectors of vectors or vectors of matrices. A separate synonym is needed to generate Python/Java etc. wrappers properly. At the function implementation level their use is similar, but ``_InputArray::getMat(idx)`` should be used to get header for the idx-th component of the outer vector and ``_InputArray::size().area()`` should be used to find the number of components (vectors/matrices) of the outer vector.
|
||||
|
||||
|
||||
OutputArray
|
||||
-----------
|
||||
|
||||
This type is very similar to ``InputArray`` except that it is used for input/output and output function parameters. Just like with ``InputArray``, OpenCV users should not care about ``OutputArray``, they just pass ``Mat``, ``vector<T>`` etc. to the functions. The same limitation as for ``InputArray``: **Do not explicitly create OutputArray instances** applies here too.
|
||||
|
||||
If you want to make your function polymorphic (i.e. accept different arrays as output parameters), it is also not very difficult. Take the sample above as the reference. Note that ``_OutputArray::create()`` needs to be called before ``_OutputArray::getMat()``. This way you guarantee that the output array is properly allocated.
|
||||
|
||||
Optional output parameters. If you do not need certain output array to be computed and returned to you, pass ``cv::noArray()``, just like you would in the case of optional input array. At the implementation level, use ``_OutputArray::needed()`` to check if certain output array needs to be computed or not.
|
||||
|
||||
There are several synonyms for ``OutputArray`` that are used to assist automatic Python/Java/... wrapper generators: ::
|
||||
|
||||
typedef OutputArray OutputArrayOfArrays;
|
||||
typedef OutputArray InputOutputArray;
|
||||
typedef OutputArray InputOutputArrayOfArrays;
|
||||
|
||||
NAryMatIterator
|
||||
---------------
|
||||
@@ -2189,3 +2308,160 @@ It simplifies notation of some operations. ::
|
||||
M.ref(1, 2, 3) = M(4, 5, 6) + M(7, 8, 9);
|
||||
|
||||
|
||||
Algorithm
|
||||
---------
|
||||
|
||||
This is a base class for all more or less complex algorithms in OpenCV, especially for classes of algorithms, for which there can be multiple implementations. The examples are stereo correspondence (for which there are algorithms like block matching, semi-global block matching, graph-cut etc.), background subtraction (which can be done using mixture-of-gaussians models, codebook-based algorithm etc.), optical flow (block matching, Lucas-Kanade, Horn-Schunck etc.).
|
||||
|
||||
The class provides the following features for all derived classes:
|
||||
|
||||
* so called "virtual constructor". That is, each Algorithm derivative is registered at program start and you can get the list of registered algorithms and create instance of a particular algorithm by its name (see ``Algorithm::create``). If you plan to add your own algorithms, it is good practice to add a unique prefix to your algorithms to distinguish them from other algorithms.
|
||||
|
||||
* setting/retrieving algorithm parameters by name. If you used video capturing functionality from OpenCV highgui module, you are probably familar with ``cvSetCaptureProperty()``, ``cvGetCaptureProperty()``, ``VideoCapture::set()`` and ``VideoCapture::get()``. ``Algorithm`` provides similar method where instead of integer id's you specify the parameter names as text strings. See ``Algorithm::set`` and ``Algorithm::get`` for details.
|
||||
|
||||
* reading and writing parameters from/to XML or YAML files. Every Algorithm derivative can store all its parameters and then read them back. There is no need to re-implement it each time.
|
||||
|
||||
Here is example of SIFT use in your application via Algorithm interface: ::
|
||||
|
||||
#include "opencv2/opencv.hpp"
|
||||
|
||||
...
|
||||
|
||||
initModule_nonfree(); // to load SURF/SIFT etc.
|
||||
|
||||
Ptr<Feature2D> sift = Algorithm::create<Feature2D>("Feature2D.SIFT");
|
||||
|
||||
FileStorage fs("sift_params.xml", FileStorage::READ);
|
||||
if( fs.isOpened() ) // if we have file with parameters, read them
|
||||
{
|
||||
sift.read(fs["sift_params"]);
|
||||
fs.release();
|
||||
}
|
||||
else // else modify the parameters and store them; user can later edit the file to use different parameters
|
||||
{
|
||||
sift.set("contrastThreshold", 0.01f); // lower the contrast threshold, compared to the default value
|
||||
|
||||
{
|
||||
WriteStructContext ws(fs, "sift_params", CV_NODE_MAP);
|
||||
sift.write(fs);
|
||||
}
|
||||
}
|
||||
|
||||
Mat image = imread("myimage.png", 0), descriptors;
|
||||
vector<KeyPoint> keypoints;
|
||||
sift(image, noArray(), keypoints, descriptors);
|
||||
|
||||
|
||||
Algorithm::get
|
||||
--------------
|
||||
Returns the algorithm parameter
|
||||
|
||||
.. ocv:function:: template<typename _Tp> typename ParamType<_Tp>::member_type get(const string& name) const
|
||||
|
||||
:param name: The parameter name.
|
||||
|
||||
The method returns value of the particular parameter. Since the compiler can not deduce the type of the returned parameter, you should specify it explicitly in angle brackets. Here are the allowed forms of get:
|
||||
|
||||
* myalgo.get<int>("param_name")
|
||||
* myalgo.get<double>("param_name")
|
||||
* myalgo.get<bool>("param_name")
|
||||
* myalgo.get<string>("param_name")
|
||||
* myalgo.get<Mat>("param_name")
|
||||
* myalgo.get<vector<Mat> >("param_name")
|
||||
* myalgo.get<Algorithm>("param_name") (it returns Ptr<Algorithm>).
|
||||
|
||||
In some cases the actual type of the parameter can be cast to the specified type, e.g. integer parameter can be cast to double, ``bool`` can be cast to ``int``. But "dangerous" transformations (string<->number, double->int, 1x1 Mat<->number, ...) are not performed and the method will throw an exception. In the case of ``Mat`` or ``vector<Mat>`` parameters the method does not clone the matrix data, so do not modify the matrices. Use ``Algorithm::set`` instead - slower, but more safe.
|
||||
|
||||
|
||||
Algorithm::set
|
||||
--------------
|
||||
Sets the algorithm parameter
|
||||
|
||||
.. ocv:function:: void set(const string& name, int value)
|
||||
.. ocv:function:: void set(const string& name, double value)
|
||||
.. ocv:function:: void set(const string& name, bool value)
|
||||
.. ocv:function:: void set(const string& name, const string& value)
|
||||
.. ocv:function:: void set(const string& name, const Mat& value)
|
||||
.. ocv:function:: void set(const string& name, const vector<Mat>& value)
|
||||
.. ocv:function:: void set(const string& name, const Ptr<Algorithm>& value)
|
||||
|
||||
:param name: The parameter name.
|
||||
:param value: The parameter value.
|
||||
|
||||
The method sets value of the particular parameter. Some of the algorithm parameters may be declared as read-only. If you try to set such a parameter, you will get exception with the corresponding error message.
|
||||
|
||||
|
||||
Algorithm::write
|
||||
----------------
|
||||
Stores algorithm parameters in a file storage
|
||||
|
||||
.. ocv:function:: void write(FileStorage& fs) const
|
||||
|
||||
:param fs: File storage.
|
||||
|
||||
The method stores all the algorithm parameters (in alphabetic order) to the file storage. The method is virtual. If you define your own Algorithm derivative, your can override the method and store some extra information. However, it's rarely needed. Here are some examples:
|
||||
|
||||
* SIFT feature detector (from nonfree module). The class only stores algorithm parameters and no keypoints or their descriptors. Therefore, it's enough to store the algorithm parameters, which is what ``Algorithm::write()`` does. Therefore, there is no dedicated ``SIFT::write()``.
|
||||
|
||||
* Background subtractor (from video module). It has the algorithm parameters and also it has the current background model. However, the background model is not stored. First, it's rather big. Then, if you have stored the background model, it would likely become irrelevant on the next run (because of shifted camera, changed background, different lighting etc.). Therefore, ``BackgroundSubtractorMOG`` and ``BackgroundSubtractorMOG2`` also rely on the standard ``Algorithm::write()`` to store just the algorithm parameters.
|
||||
|
||||
* Expectation Maximization (from ml module). The algorithm finds mixture of gaussians that approximates user data best of all. In this case the model may be re-used on the next run to test new data against the trained statistical model. So EM needs to store the model. However, since the model is described by a few parameters that are available as read-only algorithm parameters (i.e. they are available via ``EM::get()``), EM also relies on ``Algorithm::write()`` to store both EM parameters and the model (represented by read-only algorithm parameters).
|
||||
|
||||
|
||||
Algorithm::read
|
||||
---------------
|
||||
Reads algorithm parameters from a file storage
|
||||
|
||||
.. ocv:function:: void read(const FileNode& fn)
|
||||
|
||||
:param fn: File node of the file storage.
|
||||
|
||||
The method reads all the algorithm parameters from the specified node of a file storage. Similarly to ``Algorithm::write()``, if you implement an algorithm that needs to read some extra data and/or re-compute some internal data, you may override the method.
|
||||
|
||||
Algorithm::getList
|
||||
------------------
|
||||
Returns the list of registered algorithms
|
||||
|
||||
.. ocv:function:: void read(vector<string>& algorithms)
|
||||
|
||||
:param algorithms: The output vector of algorithm names.
|
||||
|
||||
This static method returns the list of registered algorithms in alphabetical order.
|
||||
|
||||
|
||||
Algorithm::getList
|
||||
------------------
|
||||
Returns the list of registered algorithms
|
||||
|
||||
.. ocv:function:: void read(vector<string>& algorithms)
|
||||
|
||||
:param algorithms: The output vector of algorithm names.
|
||||
|
||||
This static method returns the list of registered algorithms in alphabetical order.
|
||||
|
||||
|
||||
Algorithm::create
|
||||
-----------------
|
||||
Creates algorithm instance by name
|
||||
|
||||
.. ocv:function:: template<typename _Tp> Ptr<_Tp> create(const string& name)
|
||||
|
||||
:param name: The algorithm name, one of the names returned by ``Algorithm::getList()``.
|
||||
|
||||
This static method creates a new instance of the specified algorithm. If there is no such algorithm, the method will silently return null pointer (that can be checked by ``Ptr::empty()`` method). Also, you should specify the particular ``Algorithm`` subclass as ``_Tp`` (or simply ``Algorithm`` if you do not know it at that point). ::
|
||||
|
||||
Ptr<BackgroundSubtractor> bgfg = Algorithm::create<BackgroundSubtractor>("BackgroundSubtractor.MOG2");
|
||||
|
||||
.. note:: This is important note about seemingly mysterious behavior of ``Algorithm::create()`` when it returns NULL while it should not. The reason is simple - ``Algorithm::create()`` resides in OpenCV`s core module and the algorithms are implemented in other modules. If you create algorithms dynamically, C++ linker may decide to throw away the modules where the actual algorithms are implemented, since you do not call any functions from the modules. To avoid this problem, you need to call ``initModule_<modulename>();`` somewhere in the beginning of the program before ``Algorithm::create()``. For example, call ``initModule_nonfree()`` in order to use SURF/SIFT, call ``initModule_ml()`` to use expectation maximization etc.
|
||||
|
||||
Creating Own Algorithms
|
||||
-----------------------
|
||||
|
||||
The above methods are usually enough for users. If you want to make your own algorithm, derived from ``Algorithm``, you should basically follow a few conventions and add a little semi-standard piece of code to your class:
|
||||
|
||||
* Make a class and specify ``Algorithm`` as its base class.
|
||||
* The algorithm parameters should be the class members. See ``Algorithm::get()`` for the list of possible types of the parameters.
|
||||
* Add public virtual method ``AlgorithmInfo* info() const;`` to your class.
|
||||
* Add constructor function, ``AlgorithmInfo`` instance and implement the ``info()`` method. The simplest way is to take http://code.opencv.org/svn/opencv/trunk/opencv/modules/ml/src/ml_init.cpp as the reference and modify it according to the list of your parameters.
|
||||
* Add some public function (e.g. ``initModule_<mymodule>()``) that calls info() of your algorithm and put it into the same source file as ``info()`` implementation. This is to force C++ linker to include this object file into the target application. See ``Algorithm::create()`` for details.
|
||||
|
||||
|
||||
@@ -195,6 +195,29 @@ Stores coordinates of a rectangle.
|
||||
|
||||
.. seealso:: :ocv:class:`Rect\_`
|
||||
|
||||
|
||||
CvBox2D
|
||||
------
|
||||
|
||||
.. ocv:struct:: CvBox2D
|
||||
|
||||
Stores coordinates of a rotated rectangle.
|
||||
|
||||
.. ocv:member:: CvPoint2D32f center
|
||||
|
||||
Center of the box
|
||||
|
||||
.. ocv:member:: CvSize2D32f size
|
||||
|
||||
Box width and height
|
||||
|
||||
.. ocv:member:: float angle
|
||||
|
||||
Angle between the horizontal axis and the first side (i.e. length) in degrees
|
||||
|
||||
.. seealso:: :ocv:class:`RotatedRect`
|
||||
|
||||
|
||||
CvScalar
|
||||
--------
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 4.5 KiB |
Reference in New Issue
Block a user