class cv::_InputArray

Overview

This is the proxy class for passing read-only input arrays into OpenCV functions. More…

#include <mat.hpp>

class _InputArray
{
public:
    // enums

    enum
    {
        KIND_SHIFT              = 16,
        FIXED_TYPE              = 0x8000 <<KIND_SHIFT,
        FIXED_SIZE              = 0x4000 <<KIND_SHIFT,
        KIND_MASK               = 31 <<KIND_SHIFT,
        NONE                    = 0 <<KIND_SHIFT,
        MAT                     = 1 <<KIND_SHIFT,
        MATX                    = 2 <<KIND_SHIFT,
        STD_VECTOR              = 3 <<KIND_SHIFT,
        STD_VECTOR_VECTOR       = 4 <<KIND_SHIFT,
        STD_VECTOR_MAT          = 5 <<KIND_SHIFT,
        EXPR                    = 6 <<KIND_SHIFT,
        OPENGL_BUFFER           = 7 <<KIND_SHIFT,
        CUDA_HOST_MEM           = 8 <<KIND_SHIFT,
        CUDA_GPU_MAT            = 9 <<KIND_SHIFT,
        UMAT                    =10 <<KIND_SHIFT,
        STD_VECTOR_UMAT         =11 <<KIND_SHIFT,
        STD_BOOL_VECTOR         =12 <<KIND_SHIFT,
        STD_VECTOR_CUDA_GPU_MAT = 13 <<KIND_SHIFT,
        STD_ARRAY               =14 <<KIND_SHIFT,
        STD_ARRAY_MAT           =15 <<KIND_SHIFT,
    };

    // construction

    _InputArray();

    _InputArray(
        int _flags,
        void* _obj
        );

    _InputArray(const Mat& m);
    _InputArray(const MatExpr& expr);
    _InputArray(const std::vector<Mat>& vec);

    template <typename _Tp>
    _InputArray(const Mat_<_Tp>& m);

    template <typename _Tp>
    _InputArray(const std::vector<_Tp>& vec);

    _InputArray(const std::vector<bool>& vec);

    template <typename _Tp>
    _InputArray(const std::vector<std::vector<_Tp>>& vec);

    _InputArray(const std::vector<std::vector<bool>>&);

    template <typename _Tp>
    _InputArray(const std::vector<Mat_<_Tp>>& vec);

    template <typename _Tp>
    _InputArray(
        const _Tp* vec,
        int n
        );

    template <
        typename _Tp,
        int m,
        int n
        >
    _InputArray(const Matx<_Tp, m, n>& matx);

    _InputArray(const double& val);
    _InputArray(const cuda::GpuMat& d_mat);
    _InputArray(const std::vector<cuda::GpuMat>& d_mat_array);
    _InputArray(const ogl::Buffer& buf);
    _InputArray(const cuda::HostMem& cuda_mem);

    template <typename _Tp>
    _InputArray(const cudev::GpuMat_<_Tp>& m);

    _InputArray(const UMat& um);
    _InputArray(const std::vector<UMat>& umv);

    // methods

    int
    channels(int i = -1) const;

    int
    cols(int i = -1) const;

    void
    copyTo(const _OutputArray& arr) const;

    void
    copyTo(
        const _OutputArray& arr,
        const _InputArray& mask
        ) const;

    int
    depth(int i = -1) const;

    int
    dims(int i = -1) const;

    bool
    empty() const;

    int
    getFlags() const;

    cuda::GpuMat
    getGpuMat() const;

    void
    getGpuMatVector(std::vector<cuda::GpuMat>& gpumv) const;

    Mat
    getMat(int idx = -1) const;

    Mat
    getMat_(int idx = -1) const;

    void
    getMatVector(std::vector<Mat>& mv) const;

    void*
    getObj() const;

    ogl::Buffer
    getOGlBuffer() const;

    Size
    getSz() const;

    UMat
    getUMat(int idx = -1) const;

    void
    getUMatVector(std::vector<UMat>& umv) const;

    bool
    isContinuous(int i = -1) const;

    bool
    isGpuMatVector() const;

    bool
    isMat() const;

    bool
    isMatVector() const;

    bool
    isMatx() const;

    bool
    isSubmatrix(int i = -1) const;

    bool
    isUMat() const;

    bool
    isUMatVector() const;

    bool
    isVector() const;

    int
    kind() const;

    size_t
    offset(int i = -1) const;

    int
    rows(int i = -1) const;

    bool
    sameSize(const _InputArray& arr) const;

    Size
    size(int i = -1) const;

    int
    sizend(
        int* sz,
        int i = -1
        ) const;

    size_t
    step(int i = -1) const;

    size_t
    total(int i = -1) const;

    int
    type(int i = -1) const;

protected:
    // fields

    int flags;
    void* obj;
    Size sz;

    // methods

    void
    init(
        int _flags,
        const void* _obj
        );

    void
    init(
        int _flags,
        const void* _obj,
        Size _sz
        );
};

// direct descendants

class _OutputArray;

Detailed Documentation

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> >, std::vector<Mat>, std::vector<Mat_<T> >, UMat, std::vector<UMat> or double. 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.

Table of Contents

Previous topic

Next topic

class cv::_InputArray

Overview

Detailed Documentation