Opencv reference manual 2.3

It's a long-awaited update to OpenCV 3. Big thanks to everyone who participated! If you contributed something but your name is missing, please, let us know. The detailed list of changes since 3. Here is the short summary:. We would like to sincerely thank everybody who helped us to prepare the release, who submitted new functionality, patches, who submitted bug reports, who mentored the students, who donated to OpenCV. Win pack. Android pack.

May 19, Leave a Comment. April 25, Leave a Comment. August 5, Leave a Comment. Merry Christmas and Happy New Year! This is an O 1 operation, regardless of the matrix size.

The underlying data of the new matrix is shared with the original matrix. See also the Mat::row description. The method makes a new header for the specified column span of the matrix.

Similarly to Mat::row and Mat::col , this is an O 1 operation. The method converts source pixel values to the target data type. The method copies the matrix data to another matrix. Before copying the data, the method invokes :. While m. When the operation mask is specified, if the Mat::create call shown above reallocates the matrix, the newly allocated matrix is initialized with all zeros before copying the data. This is one of the key Mat methods. Most new-style OpenCV functions and methods that produce arrays call this method for each output array.

The method uses the following algorithm:. Such a scheme makes the memory management robust and efficient at the same time and helps avoid extra typing for you. This means that usually there is no need to explicitly allocate output arrays. That is, instead of writing:. The method computes a cross-product of two 3-element vectors. The vectors must be 3-element floating-point vectors of the same shape and size.

The result is another 3-element vector of the same shape and type as operands. The method returns the identifier of the matrix element depth the type of each individual channel. A complete list of matrix types contains the following values:. The method makes a new header for the specified matrix diagonal. The new matrix is represented as a single-column matrix. The method computes a dot-product of two matrices. If the matrices are not single-column or single-row vectors, the top-to-bottom left-to-right scan ordering is used to treat them as 1D vectors.

The vectors must have the same size and type. If the matrices have more than one channel, the dot products from all the channels are summed together.

The method returns the matrix element size in bytes. The method returns the matrix element channel size in bytes, that is, it ignores the number of channels. The methods return the matrix read-only or read-write iterators, set to the point following the last matrix element. The method returns a Matlab-style identity matrix initializer, similarly to Mat::zeros.

Similarly to Mat::ones , you can use a scale operation to create a scaled identity matrix efficiently:. The method performs a matrix inversion by means of matrix expressions. This means that a temporary matrix inversion object is returned by the method and can be used further as a part of more complex matrix expressions or can be assigned to a matrix. The method returns true if the matrix elements are stored continuously without gaps at the end of each row.

Otherwise, it returns false. Obviously, 1x1 or 1xN matrices are always continuous. Matrices created with Mat::create are always continuous. But if you extract a part of the matrix using Mat::col , Mat::diag , and so on, or constructed a matrix header for externally allocated data, such matrices may no longer have this property. The continuity flag is stored as a bit in the Mat::flags field and is computed automatically when you construct a matrix header.

Thus, the continuity check is a very fast operation, though theoretically it could be done as follows:. The method is used in quite a few of OpenCV functions. The point is that element-wise operations such as arithmetic and logical operations, math functions, alpha blending, color space transformations, and others do not depend on the image geometry.

Thus, if all the input and output arrays are continuous, the functions can process them as very long single-row vectors. The example below illustrates how an alpha-blending function can be implemented:. This approach, while being very simple, can boost the performance of a simple element-operation by percents, especially if the image is rather small and the operation is quite simple. Another OpenCV idiom in this function, a call of Mat::create for the destination array, that allocates the destination array unless it already has the proper size and type.

And while the newly allocated arrays are always continuous, you still need to check the destination array because Mat::create does not always allocate a new matrix. After you extracted a submatrix from a matrix using Mat::row , Mat::col , Mat::rowRange , Mat::colRange , and others, the resultant submatrix points just to the part of the original big matrix. However, each submatrix contains information represented by datastart and dataend fields that helps reconstruct the original matrix size and the position of the extracted submatrix within the original matrix.

The method locateROI does exactly that. The method returns a temporary object encoding per-element array multiplication, with optional scale. The method returns a Matlab-style 1's array initializer, similarly to Mat::zeros. Note that using this method you can initialize an array with an arbitrary value, using the following Matlab idiom:. The above operation does not form a x matrix of 1's and then multiply it by 3. Instead, it just remembers the scale factor 3 in this case and use it when actually invoking the matrix initializer.

For example, A Range 0, 10 , Range::all is equivalent to A. Similarly to all of the above, the operators are O 1 operations, that is, no matrix data is copied. These are available assignment operators. Since they all are very different, make sure to read the operator parameters description. See the sample in Mat::isContinuous to know how to use these methods. The methods add one or more elements to the bottom of the matrix. They emulate the corresponding method of the STL vector class.

When elem is Mat , its type and the number of columns must be the same as in the container matrix. The method decrements the reference counter associated with the matrix data. When the reference counter reaches 0, the matrix data is deallocated and the data and the reference counter pointers are set to NULL's. This method can be called manually to force the matrix data deallocation.

But since this method is automatically called in the destructor, or by any other method that changes the data pointer, it is usually not needed. The reference counter decrement and check for 0 is an atomic operation on the platforms that support it.

The method reserves space for sz rows. If the matrix already has enough space to store sz rows, nothing happens. If the matrix is reallocated, the first Mat::rows rows are preserved. The method emulates the corresponding method of the STL vector class. The method reserves space for sz bytes. If the matrix already has enough space to store sz bytes, nothing happens.

If matrix has to be reallocated its previous content could be lost. Any combination is possible if:. For example, if there is a set of 3D points stored as an STL vector, and you want to represent the points as a 3xN matrix, do the following:. The methods change the number of matrix rows. If the matrix is reallocated, the first min Mat::rows, sz rows are preserved.

The methods emulate the corresponding methods of the STL vector class. The method makes a new header for the specified matrix row and returns it. Here is the example of one of the classical basic matrix processing operations, axpy, used by LU and many other algorithms:. The method makes a new header for the specified row span of the matrix. The method returns a matrix step divided by Mat::elemSize1.

It can be useful to quickly access an arbitrary matrix element. The method performs matrix transposition by means of matrix expressions. It does not perform the actual transposition but returns a temporary matrix transposition object that can be further used as a part of more complex matrix expressions or can be assigned to a matrix:.

The method returns the number of array elements a number of pixels if the array represents an image. The method returns a matrix element type. The method returns a Matlab-style zero array initializer. It can be used to quickly form a constant array as a function parameter, part of a matrix expression, or as a matrix initializer:.

In the example above, a new matrix is allocated only if A is not a 3x3 floating-point matrix. Otherwise, the existing matrix A is filled with zeros. OpenCV 3. The most popular options are listed below: Use the create nrows, ncols, type method or the similar Mat nrows, ncols, type[, fillValue] constructor. A new array of the specified size and type is allocated. Mat roi img, Rect 10,10,, ;. Size size ; Point ofs;. Mat result;.

GaussianBlur img, result, Size 7, 7 , 1. Parameters rows Number of rows in a 2D array. Parameters size 2D array size: Size cols, rows. In the Size constructor, the number of rows and the number of columns go in the reverse order. Parameters ndims Array dimensionality. Parameters sizes Array of integers specifying an n-dimensional array shape.

Parameters m Array that as a whole or partly is assigned to the constructed matrix. No data is copied by these constructors. Instead, the header pointing to m data or its sub-array is constructed and associated with it. The reference counter, if any, is incremented.

So, when you modify the matrix formed using such a constructor, you also modify the corresponding elements of m. If you want to have an independent copy of the sub-array, use Mat::clone. Matrix constructors that take data and step parameters do not allocate matrix data. Instead, they just initialize the matrix header that points to the specified data, which means that no data is copied.

This operation is very efficient and can be used to process external data using OpenCV functions. The external data is not automatically deallocated, so you should take care of it. The value should include the padding bytes at the end of each row, if any. See Mat::elemSize. If not specified, the matrix is assumed to be continuous. As usual, the range start is inclusive and the range end is exclusive.

Use Range::all to take all the rows. Use Range::all to take all the columns. Parameters vec STL vector whose elements form the matrix. The matrix has a single column and the number of rows equal to the number of vector elements. Type of the matrix matches the type of vector elements. The constructor can handle arbitrary types, for which there is a properly declared DataType. This means that the vector elements must be primitive numbers or uni-type numerical tuples of numbers.

Mixed-type structures are not supported. The corresponding constructor is explicit. Since STL vectors are not automatically converted to Mat instances, you should write Mat vec explicitly. When the data is copied, the allocated buffer is managed using Mat reference counting mechanism. While the data is shared, the reference counter is NULL, and you should not deallocate the data until the matrix is not destructed. Increments the reference counter.

Adjusts a submatrix size and position within the parent matrix. When all the method parameters are positive, the ROI needs to grow in all directions by the specified amount, for example: A. Provides a functional form of convertTo. Parameters m Destination array. Returns a reference to the specified array element. Parameters i0 Index along the dimension 0.

Parameters row Index along the dimension 0 col Index along the dimension 1. Parameters i0 Index along the dimension 0 i1 Index along the dimension 1 i2 Index along the dimension 2. Parameters idx Array of Mat::dims indices. Returns the matrix iterator and sets it to the first matrix element. Returns the number of matrix channels. The method returns the number of matrix channels. Parameters elemChannels Number of channels or number of columns the matrix should have.

For a 2-D matrix, when the matrix has only 1 column, then it should have elemChannels channels; When the matrix has only 1 channel, then it should have elemChannels columns. For a 3-D matrix, it should have only one channel. Furthermore, if the number of planes is not one, then the number of rows within every plane has to be 1; if the number of rows within every plane is not 1, then the number of planes has to be 1.

Set it to -1 when any depth is fine. Otherwise, it returns the number of elements in the matrix. Note that an element may have multiple channels. Creates a full copy of the array and the underlying data.

Mat cv::Mat::col int x const. Creates a matrix header for the specified matrix column. Parameters x A 0-based column index. Mat cv::Mat::colRange int startcol , int endcol const. Creates a matrix header for the specified column span. Parameters startcol An inclusive 0-based start index of the column span. Parameters r Range structure containing both the start and the end indices.

Converts an array to another data type with optional scaling. Copies the matrix to another one. Before copying the data, the method invokes : m. Parameters m Destination matrix. If it does not have a proper size or type before the operation, it is reallocated.

Its non-zero elements indicate which matrix elements need to be copied. Allocates new array data if needed. The method uses the following algorithm: If the current array shape and the type match the new ones, return immediately. Otherwise, de-reference the previous data by calling Mat::release. Initialize the new header. Allocate the new, associated with the data, reference counter and set it to 1.