cv::_InputArray Class Reference

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

#include <mat.hpp>

Inheritance diagram for cv::_InputArray:

Public Types
enum	KindFlag {   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 }

Public Member Functions
	_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 > > &)=delete
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)
template<typename _Tp , std::size_t _Nm>
	_InputArray (const std::array< _Tp, _Nm > &arr)
template<std::size_t _Nm>
	_InputArray (const std::array< Mat, _Nm > &arr)
Mat	getMat (int idx=-1) const
Mat	getMat_ (int idx=-1) const
UMat	getUMat (int idx=-1) const
void	getMatVector (std::vector< Mat > &mv) const
void	getUMatVector (std::vector< UMat > &umv) const
void	getGpuMatVector (std::vector< cuda::GpuMat > &gpumv) const
cuda::GpuMat	getGpuMat () const
ogl::Buffer	getOGlBuffer () const
int	getFlags () const
void *	getObj () const
Size	getSz () const
_InputArray::KindFlag	kind () const
int	dims (int i=-1) const
int	cols (int i=-1) const
int	rows (int i=-1) const
Size	size (int i=-1) const
int	sizend (int *sz, int i=-1) const
bool	sameSize (const _InputArray &arr) const
size_t	total (int i=-1) const
int	type (int i=-1) const
int	depth (int i=-1) const
int	channels (int i=-1) const
bool	isContinuous (int i=-1) const
bool	isSubmatrix (int i=-1) const
bool	empty () const
void	copyTo (const _OutputArray &arr) const
void	copyTo (const _OutputArray &arr, const _InputArray &mask) const
size_t	offset (int i=-1) const
size_t	step (int i=-1) const
bool	isMat () const
bool	isUMat () const
bool	isMatVector () const
bool	isUMatVector () const
bool	isMatx () const
bool	isVector () const
bool	isGpuMat () const
bool	isGpuMatVector () const
	~_InputArray ()

Static Public Member Functions
template<typename _Tp >
static _InputArray	rawIn (const std::vector< _Tp > &vec)
template<typename _Tp , std::size_t _Nm>
static _InputArray	rawIn (const std::array< _Tp, _Nm > &arr)

Protected Member Functions
void	init (int _flags, const void *_obj)
void	init (int _flags, const void *_obj, Size _sz)

Protected Attributes
int	flags
void *	obj
Size	sz

Detailed Description

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.

In general, type support is limited to cv::Mat types. Other types are forbidden. But in some cases we need to support passing of custom non-general Mat types, like arrays of cv::KeyPoint, cv::DMatch, etc. This data is not intended to be interpreted as an image data, or processed somehow like regular cv::Mat. To pass such custom type use rawIn() / rawOut() / rawInOut() wrappers. Custom type is wrapped as Mat-compatible CV_8UC<N> values (N = sizeof(T), N <= CV_CN_MAX).

Member Enumeration Documentation

KindFlag

enum cv::_InputArray::KindFlag

Enumerator
KIND_SHIFT
FIXED_TYPE
FIXED_SIZE
KIND_MASK
NONE
MAT
MATX
STD_VECTOR
STD_VECTOR_VECTOR
STD_VECTOR_MAT
EXPR	removed: https://github.com/opencv/opencv/pull/17046
OPENGL_BUFFER
CUDA_HOST_MEM
CUDA_GPU_MAT
UMAT
STD_VECTOR_UMAT
STD_BOOL_VECTOR
STD_VECTOR_CUDA_GPU_MAT
STD_ARRAY	removed: https://github.com/opencv/opencv/issues/18897
STD_ARRAY_MAT

Constructor & Destructor Documentation

_InputArray() [1/23]

cv::_InputArray::_InputArray

(

)

_InputArray() [2/23]

cv::_InputArray::_InputArray	(	int	_flags,
		void *	_obj
	)

_InputArray() [3/23]

cv::_InputArray::_InputArray

(

const Mat &

m

)

_InputArray() [4/23]

cv::_InputArray::_InputArray

(

const MatExpr &

expr

)

_InputArray() [5/23]

cv::_InputArray::_InputArray

(

const std::vector< Mat > &

vec

)

_InputArray() [6/23]

template<typename _Tp >

cv::_InputArray::_InputArray

(

const Mat_< _Tp > &

m

)

_InputArray() [7/23]

template<typename _Tp >

cv::_InputArray::_InputArray

(

const std::vector< _Tp > &

vec

)

_InputArray() [8/23]

cv::_InputArray::_InputArray

(

const std::vector< bool > &

vec

)

_InputArray() [9/23]

template<typename _Tp >

cv::_InputArray::_InputArray

(

const std::vector< std::vector< _Tp > > &

vec

)

_InputArray() [10/23]

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

delete

_InputArray() [11/23]

template<typename _Tp >

cv::_InputArray::_InputArray

(

const std::vector< Mat_< _Tp > > &

vec

)

_InputArray() [12/23]

template<typename _Tp >

cv::_InputArray::_InputArray	(	const _Tp *	vec,
		int	n
	)

_InputArray() [13/23]

template<typename _Tp , int m, int n>

cv::_InputArray::_InputArray

(

const Matx< _Tp, m, n > &

matx

)

_InputArray() [14/23]

cv::_InputArray::_InputArray

(

const double &

val

)

_InputArray() [15/23]

cv::_InputArray::_InputArray

(

const cuda::GpuMat &

d_mat

)

_InputArray() [16/23]

cv::_InputArray::_InputArray

(

const std::vector< cuda::GpuMat > &

d_mat_array

)

_InputArray() [17/23]

cv::_InputArray::_InputArray

(

const ogl::Buffer &

buf

)

_InputArray() [18/23]

cv::_InputArray::_InputArray

(

const cuda::HostMem &

cuda_mem

)

_InputArray() [19/23]

template<typename _Tp >

cv::_InputArray::_InputArray

(

const cudev::GpuMat_< _Tp > &

m

)

_InputArray() [20/23]

cv::_InputArray::_InputArray

(

const UMat &

um

)

_InputArray() [21/23]

cv::_InputArray::_InputArray

(

const std::vector< UMat > &

umv

)

_InputArray() [22/23]

template<typename _Tp , std::size_t _Nm>

cv::_InputArray::_InputArray

(

const std::array< _Tp, _Nm > &

arr

)

_InputArray() [23/23]

template<std::size_t _Nm>

cv::_InputArray::_InputArray

(

const std::array< Mat, _Nm > &

arr

)

~_InputArray()

cv::_InputArray::~_InputArray

(

)

Member Function Documentation

channels()

int cv::_InputArray::channels

(

int

i = -1

)

const

cols()

int cv::_InputArray::cols

(

int

i = -1

)

const

copyTo() [1/2]

void cv::_InputArray::copyTo

(

const _OutputArray &

arr

)

const

copyTo() [2/2]

void cv::_InputArray::copyTo	(	const _OutputArray &	arr,
		const _InputArray &	mask
	)		const

depth()

int cv::_InputArray::depth

(

int

i = -1

)

const

dims()

int cv::_InputArray::dims

(

int

i = -1

)

const

empty()

bool cv::_InputArray::empty

(

)

const

getFlags()

int cv::_InputArray::getFlags

(

)

const

getGpuMat()

cuda::GpuMat cv::_InputArray::getGpuMat

(

)

const

getGpuMatVector()

void cv::_InputArray::getGpuMatVector

(

std::vector< cuda::GpuMat > &

gpumv

)

const

getMat()

Mat cv::_InputArray::getMat

(

int

idx = -1

)

const

getMat_()

Mat cv::_InputArray::getMat_

(

int

idx = -1

)

const

getMatVector()

void cv::_InputArray::getMatVector

(

std::vector< Mat > &

mv

)

const

getObj()

void* cv::_InputArray::getObj

(

)

const

getOGlBuffer()

ogl::Buffer cv::_InputArray::getOGlBuffer

(

)

const

getSz()

Size cv::_InputArray::getSz

(

)

const

getUMat()

UMat cv::_InputArray::getUMat

(

int

idx = -1

)

const

getUMatVector()

void cv::_InputArray::getUMatVector

(

std::vector< UMat > &

umv

)

const

init() [1/2]

void cv::_InputArray::init ( int  _flags, const void *  _obj  )

protected

init() [2/2]

void cv::_InputArray::init ( int  _flags, const void *  _obj, Size  _sz  )

protected

isContinuous()

bool cv::_InputArray::isContinuous

(

int

i = -1

)

const

isGpuMat()

bool cv::_InputArray::isGpuMat

(

)

const

isGpuMatVector()

bool cv::_InputArray::isGpuMatVector

(

)

const

isMat()

bool cv::_InputArray::isMat

(

)

const

isMatVector()

bool cv::_InputArray::isMatVector

(

)

const

isMatx()

bool cv::_InputArray::isMatx

(

)

const

isSubmatrix()

bool cv::_InputArray::isSubmatrix

(

int

i = -1

)

const

isUMat()

bool cv::_InputArray::isUMat

(

)

const

isUMatVector()

bool cv::_InputArray::isUMatVector

(

)

const

isVector()

bool cv::_InputArray::isVector

(

)

const

kind()

_InputArray::KindFlag cv::_InputArray::kind

(

)

const

offset()

size_t cv::_InputArray::offset

(

int

i = -1

)

const

rawIn() [1/2]

template<typename _Tp , std::size_t _Nm>

static _InputArray cv::_InputArray::rawIn ( const std::array< _Tp, _Nm > &  arr )

static

rawIn() [2/2]

template<typename _Tp >

static _InputArray cv::_InputArray::rawIn ( const std::vector< _Tp > &  vec )

static

rows()

int cv::_InputArray::rows

(

int

i = -1

)

const

sameSize()

bool cv::_InputArray::sameSize

(

const _InputArray &

arr

)

const

size()

Size cv::_InputArray::size

(

int

i = -1

)

const

sizend()

int cv::_InputArray::sizend	(	int *	sz,
		int	i = -1
	)		const

step()

size_t cv::_InputArray::step

(

int

i = -1

)

const

total()

size_t cv::_InputArray::total

(

int

i = -1

)

const

type()

int cv::_InputArray::type

(

int

i = -1

)

const

Member Data Documentation

flags

int cv::_InputArray::flags

protected

obj

void* cv::_InputArray::obj

protected

sz

Size cv::_InputArray::sz

protected

---

The documentation for this class was generated from the following file:

• build/release/_deps/opencv-src/include/opencv4/opencv2/core/mat.hpp