Trait opencv::core::prelude::MatTrait

source · 
pub trait MatTrait: MatTraitConst {

Show 34 methods    fn as_raw_mut_Mat(&mut self) -> *mut c_void;

    fn set_flags(&mut self, val: i32) { ... }
    fn set_dims(&mut self, val: i32) { ... }
    fn set_rows(&mut self, val: i32) { ... }
    fn set_cols(&mut self, val: i32) { ... }
    fn data_mut(&mut self) -> *mut u8 { ... }
    unsafe fn set_data(&mut self, val: *mut u8) { ... }
    fn u(&mut self) -> UMatData { ... }
    fn set_u(&mut self, val: &mut UMatData) { ... }
    fn set_to(
        &mut self,
        value: &dyn ToInputArray,
        mask: &dyn ToInputArray
    ) -> Result<Mat> { ... }
    unsafe fn create_rows_cols(
        &mut self,
        rows: i32,
        cols: i32,
        typ: i32
    ) -> Result<()> { ... }
    unsafe fn create_size(&mut self, size: Size, typ: i32) -> Result<()> { ... }
    unsafe fn create_nd(&mut self, sizes: &[i32], typ: i32) -> Result<()> { ... }
    unsafe fn create_nd_vec(
        &mut self,
        sizes: &Vector<i32>,
        typ: i32
    ) -> Result<()> { ... }
    fn addref(&mut self) -> Result<()> { ... }
    fn release(&mut self) -> Result<()> { ... }
    fn deallocate(&mut self) -> Result<()> { ... }
    fn reserve(&mut self, sz: size_t) -> Result<()> { ... }
    fn reserve_buffer(&mut self, sz: size_t) -> Result<()> { ... }
    fn resize(&mut self, sz: size_t) -> Result<()> { ... }
    fn resize_with_default(&mut self, sz: size_t, s: Scalar) -> Result<()> { ... }
    fn push_back(&mut self, m: &Mat) -> Result<()> { ... }
    fn pop_back(&mut self, nelems: size_t) -> Result<()> { ... }
    fn adjust_roi(
        &mut self,
        dtop: i32,
        dbottom: i32,
        dleft: i32,
        dright: i32
    ) -> Result<Mat> { ... }
    fn ptr_mut(&mut self, i0: i32) -> Result<*mut u8> { ... }
    fn ptr_2d_mut(&mut self, row: i32, col: i32) -> Result<*mut u8> { ... }
    fn ptr_3d_mut(&mut self, i0: i32, i1: i32, i2: i32) -> Result<*mut u8> { ... }
    fn ptr_nd_mut(&mut self, idx: &[i32]) -> Result<*mut u8> { ... }
    fn at_mut<T: DataType>(&mut self, i0: i32) -> Result<&mut T> { ... }
    fn at_2d_mut<T: DataType>(&mut self, row: i32, col: i32) -> Result<&mut T> { ... }
    fn at_3d_mut<T: DataType>(
        &mut self,
        i0: i32,
        i1: i32,
        i2: i32
    ) -> Result<&mut T> { ... }
    fn at_nd_mut<T: DataType>(&mut self, idx: &[i32]) -> Result<&mut T> { ... }
    fn at_pt_mut<T: DataType>(&mut self, pt: Point) -> Result<&mut T> { ... }
    fn update_continuity_flag(&mut self) -> Result<()> { ... }

}

Required Methods

Provided Methods

! includes several bit-fields:

  • the magic signature
  • continuity flag
  • depth
  • number of channels

the matrix dimensionality, >= 2

the number of rows and columns or (-1, -1) when the matrix has more than 2 dimensions

the number of rows and columns or (-1, -1) when the matrix has more than 2 dimensions

pointer to the data

pointer to the data

interaction with UMat

interaction with UMat

Sets all or some of the array elements to the specified value.

This is an advanced variant of the Mat::operator=(const Scalar& s) operator.

Parameters
  • value: Assigned scalar converted to the actual array type.
  • mask: Operation mask of the same size as *this. Its non-zero elements indicate which matrix elements need to be copied. The mask has to be of type CV_8U and can have 1 or multiple channels
C++ default parameters
  • mask: noArray()

Allocates new array data if needed.

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:

-# 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 data of total()*elemSize() bytes. -# Allocate the new, associated with the data, reference counter and set it to 1.

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:

ⓘ
   Mat color;
   ...
   Mat gray(color.rows, color.cols, color.depth());
   cvtColor(color, gray, COLOR_BGR2GRAY);

you can simply write:

ⓘ
   Mat color;
   ...
   Mat gray;
   cvtColor(color, gray, COLOR_BGR2GRAY);

because cvtColor, as well as the most of OpenCV functions, calls Mat::create() for the output array internally.

Parameters
  • rows: New number of rows.
  • cols: New number of columns.
  • type: New matrix type.

Allocates new array data if needed.

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:

-# 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 data of total()*elemSize() bytes. -# Allocate the new, associated with the data, reference counter and set it to 1.

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:

ⓘ
   Mat color;
   ...
   Mat gray(color.rows, color.cols, color.depth());
   cvtColor(color, gray, COLOR_BGR2GRAY);

you can simply write:

ⓘ
   Mat color;
   ...
   Mat gray;
   cvtColor(color, gray, COLOR_BGR2GRAY);

because cvtColor, as well as the most of OpenCV functions, calls Mat::create() for the output array internally.

Parameters
  • rows: New number of rows.
  • cols: New number of columns.
  • type: New matrix type.
Overloaded parameters
  • size: Alternative new matrix size specification: Size(cols, rows)
  • type: New matrix type.

Allocates new array data if needed.

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:

-# 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 data of total()*elemSize() bytes. -# Allocate the new, associated with the data, reference counter and set it to 1.

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:

ⓘ
   Mat color;
   ...
   Mat gray(color.rows, color.cols, color.depth());
   cvtColor(color, gray, COLOR_BGR2GRAY);

you can simply write:

ⓘ
   Mat color;
   ...
   Mat gray;
   cvtColor(color, gray, COLOR_BGR2GRAY);

because cvtColor, as well as the most of OpenCV functions, calls Mat::create() for the output array internally.

Parameters
  • rows: New number of rows.
  • cols: New number of columns.
  • type: New matrix type.
Overloaded parameters
  • ndims: New array dimensionality.
  • sizes: Array of integers specifying a new array shape.
  • type: New matrix type.

Allocates new array data if needed.

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:

-# 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 data of total()*elemSize() bytes. -# Allocate the new, associated with the data, reference counter and set it to 1.

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:

ⓘ
   Mat color;
   ...
   Mat gray(color.rows, color.cols, color.depth());
   cvtColor(color, gray, COLOR_BGR2GRAY);

you can simply write:

ⓘ
   Mat color;
   ...
   Mat gray;
   cvtColor(color, gray, COLOR_BGR2GRAY);

because cvtColor, as well as the most of OpenCV functions, calls Mat::create() for the output array internally.

Parameters
  • rows: New number of rows.
  • cols: New number of columns.
  • type: New matrix type.
Overloaded parameters
  • sizes: Array of integers specifying a new array shape.
  • type: New matrix type.

Increments the reference counter.

The method increments the reference counter associated with the matrix data. If the matrix header points to an external data set (see Mat::Mat ), the reference counter is NULL, and the method has no effect in this case. Normally, to avoid memory leaks, the method should not be called explicitly. It is called implicitly by the matrix assignment operator. The reference counter increment is an atomic operation on the platforms that support it. Thus, it is safe to operate on the same matrices asynchronously in different threads.

Decrements the reference counter and deallocates the matrix if needed.

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. If the matrix header points to an external data set (see Mat::Mat ), the reference counter is NULL, and the method has no effect in this case.

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. Thus, it is safe to operate on the same matrices asynchronously in different threads.

internal use function, consider to use ‘release’ method instead; deallocates the matrix data

Reserves space for the certain number of rows.

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.

Parameters
  • sz: Number of rows.

Reserves space for the certain number of bytes.

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.

Parameters
  • sz: Number of bytes.

Changes the number of matrix rows.

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.

Parameters
  • sz: New number of rows.

Changes the number of matrix rows.

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.

Parameters
  • sz: New number of rows.
Overloaded parameters
  • sz: New number of rows.
  • s: Value assigned to the newly added elements.

Adds elements to the bottom of the matrix.

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.

Parameters
  • elem: Added element(s).
Overloaded parameters
  • m: Added line(s).

Removes elements from the bottom of the matrix.

The method removes one or more rows from the bottom of the matrix.

Parameters
  • nelems: Number of removed rows. If it is greater than the total number of rows, an exception is thrown.
C++ default parameters
  • nelems: 1

Adjusts a submatrix size and position within the parent matrix.

The method is complimentary to Mat::locateROI . The typical use of these functions is to determine the submatrix position within the parent matrix and then shift the position somehow. Typically, it can be required for filtering operations when pixels outside of the ROI should be taken into account. When all the method parameters are positive, the ROI needs to grow in all directions by the specified amount, for example:

ⓘ
   A.adjustROI(2, 2, 2, 2);

In this example, the matrix size is increased by 4 elements in each direction. The matrix is shifted by 2 elements to the left and 2 elements up, which brings in all the necessary pixels for the filtering with the 5x5 kernel.

adjustROI forces the adjusted ROI to be inside of the parent matrix that is boundaries of the adjusted ROI are constrained by boundaries of the parent matrix. For example, if the submatrix A is located in the first row of a parent matrix and you called A.adjustROI(2, 2, 2, 2) then A will not be increased in the upward direction.

The function is used internally by the OpenCV filtering functions, like filter2D , morphological operations, and so on.

Parameters
  • dtop: Shift of the top submatrix boundary upwards.
  • dbottom: Shift of the bottom submatrix boundary downwards.
  • dleft: Shift of the left submatrix boundary to the left.
  • dright: Shift of the right submatrix boundary to the right.
See also

copyMakeBorder

Returns a pointer to the specified matrix row.

The methods return uchar* or typed pointer to the specified matrix row. See the sample in Mat::isContinuous to know how to use these methods.

Parameters
  • i0: A 0-based row index.
C++ default parameters
  • i0: 0

Returns a pointer to the specified matrix row.

The methods return uchar* or typed pointer to the specified matrix row. See the sample in Mat::isContinuous to know how to use these methods.

Parameters
  • i0: A 0-based row index.
Overloaded parameters
  • row: Index along the dimension 0
  • col: Index along the dimension 1

Returns a pointer to the specified matrix row.

The methods return uchar* or typed pointer to the specified matrix row. See the sample in Mat::isContinuous to know how to use these methods.

Parameters
  • i0: A 0-based row index.
Overloaded parameters

Returns a pointer to the specified matrix row.

The methods return uchar* or typed pointer to the specified matrix row. See the sample in Mat::isContinuous to know how to use these methods.

Parameters
  • i0: A 0-based row index.
Overloaded parameters

Returns a reference to the specified array element.

The template methods return a reference to the specified array element. For the sake of higher performance, the index range checks are only performed in the Debug configuration.

Note that the variants with a single index (i) can be used to access elements of single-row or single-column 2-dimensional arrays. That is, if, for example, A is a 1 x N floating-point matrix and B is an M x 1 integer matrix, you can simply write A.at<float>(k+4) and B.at<int>(2*i+1) instead of A.at<float>(0,k+4) and B.at<int>(2*i+1,0), respectively.

The example below initializes a Hilbert matrix:

ⓘ
   Mat H(100, 100, CV_64F);
   for(int i = 0; i < H.rows; i++)
       for(int j = 0; j < H.cols; j++)
           H.at<double>(i,j)=1./(i+j+1);

Keep in mind that the size identifier used in the at operator cannot be chosen at random. It depends on the image from which you are trying to retrieve the data. The table below gives a better insight in this:

  • If matrix is of type CV_8U then use Mat.at<uchar>(y,x).
  • If matrix is of type CV_8S then use Mat.at<schar>(y,x).
  • If matrix is of type CV_16U then use Mat.at<ushort>(y,x).
  • If matrix is of type CV_16S then use Mat.at<short>(y,x).
  • If matrix is of type CV_32S then use Mat.at<int>(y,x).
  • If matrix is of type CV_32F then use Mat.at<float>(y,x).
  • If matrix is of type CV_64F then use Mat.at<double>(y,x).
Parameters
  • i0: Index along the dimension 0
C++ default parameters
  • i0: 0

Returns a reference to the specified array element.

The template methods return a reference to the specified array element. For the sake of higher performance, the index range checks are only performed in the Debug configuration.

Note that the variants with a single index (i) can be used to access elements of single-row or single-column 2-dimensional arrays. That is, if, for example, A is a 1 x N floating-point matrix and B is an M x 1 integer matrix, you can simply write A.at<float>(k+4) and B.at<int>(2*i+1) instead of A.at<float>(0,k+4) and B.at<int>(2*i+1,0), respectively.

The example below initializes a Hilbert matrix:

ⓘ
   Mat H(100, 100, CV_64F);
   for(int i = 0; i < H.rows; i++)
       for(int j = 0; j < H.cols; j++)
           H.at<double>(i,j)=1./(i+j+1);

Keep in mind that the size identifier used in the at operator cannot be chosen at random. It depends on the image from which you are trying to retrieve the data. The table below gives a better insight in this:

  • If matrix is of type CV_8U then use Mat.at<uchar>(y,x).
  • If matrix is of type CV_8S then use Mat.at<schar>(y,x).
  • If matrix is of type CV_16U then use Mat.at<ushort>(y,x).
  • If matrix is of type CV_16S then use Mat.at<short>(y,x).
  • If matrix is of type CV_32S then use Mat.at<int>(y,x).
  • If matrix is of type CV_32F then use Mat.at<float>(y,x).
  • If matrix is of type CV_64F then use Mat.at<double>(y,x).
Parameters
  • i0: Index along the dimension 0
Overloaded parameters
  • row: Index along the dimension 0
  • col: Index along the dimension 1

Returns a reference to the specified array element.

The template methods return a reference to the specified array element. For the sake of higher performance, the index range checks are only performed in the Debug configuration.

Note that the variants with a single index (i) can be used to access elements of single-row or single-column 2-dimensional arrays. That is, if, for example, A is a 1 x N floating-point matrix and B is an M x 1 integer matrix, you can simply write A.at<float>(k+4) and B.at<int>(2*i+1) instead of A.at<float>(0,k+4) and B.at<int>(2*i+1,0), respectively.

The example below initializes a Hilbert matrix:

ⓘ
   Mat H(100, 100, CV_64F);
   for(int i = 0; i < H.rows; i++)
       for(int j = 0; j < H.cols; j++)
           H.at<double>(i,j)=1./(i+j+1);

Keep in mind that the size identifier used in the at operator cannot be chosen at random. It depends on the image from which you are trying to retrieve the data. The table below gives a better insight in this:

  • If matrix is of type CV_8U then use Mat.at<uchar>(y,x).
  • If matrix is of type CV_8S then use Mat.at<schar>(y,x).
  • If matrix is of type CV_16U then use Mat.at<ushort>(y,x).
  • If matrix is of type CV_16S then use Mat.at<short>(y,x).
  • If matrix is of type CV_32S then use Mat.at<int>(y,x).
  • If matrix is of type CV_32F then use Mat.at<float>(y,x).
  • If matrix is of type CV_64F then use Mat.at<double>(y,x).
Parameters
  • i0: Index along the dimension 0
Overloaded parameters
  • i0: Index along the dimension 0
  • i1: Index along the dimension 1
  • i2: Index along the dimension 2

Returns a reference to the specified array element.

The template methods return a reference to the specified array element. For the sake of higher performance, the index range checks are only performed in the Debug configuration.

Note that the variants with a single index (i) can be used to access elements of single-row or single-column 2-dimensional arrays. That is, if, for example, A is a 1 x N floating-point matrix and B is an M x 1 integer matrix, you can simply write A.at<float>(k+4) and B.at<int>(2*i+1) instead of A.at<float>(0,k+4) and B.at<int>(2*i+1,0), respectively.

The example below initializes a Hilbert matrix:

ⓘ
   Mat H(100, 100, CV_64F);
   for(int i = 0; i < H.rows; i++)
       for(int j = 0; j < H.cols; j++)
           H.at<double>(i,j)=1./(i+j+1);

Keep in mind that the size identifier used in the at operator cannot be chosen at random. It depends on the image from which you are trying to retrieve the data. The table below gives a better insight in this:

  • If matrix is of type CV_8U then use Mat.at<uchar>(y,x).
  • If matrix is of type CV_8S then use Mat.at<schar>(y,x).
  • If matrix is of type CV_16U then use Mat.at<ushort>(y,x).
  • If matrix is of type CV_16S then use Mat.at<short>(y,x).
  • If matrix is of type CV_32S then use Mat.at<int>(y,x).
  • If matrix is of type CV_32F then use Mat.at<float>(y,x).
  • If matrix is of type CV_64F then use Mat.at<double>(y,x).
Parameters
  • i0: Index along the dimension 0
Overloaded parameters
  • idx: Array of Mat::dims indices.

Returns a reference to the specified array element.

The template methods return a reference to the specified array element. For the sake of higher performance, the index range checks are only performed in the Debug configuration.

Note that the variants with a single index (i) can be used to access elements of single-row or single-column 2-dimensional arrays. That is, if, for example, A is a 1 x N floating-point matrix and B is an M x 1 integer matrix, you can simply write A.at<float>(k+4) and B.at<int>(2*i+1) instead of A.at<float>(0,k+4) and B.at<int>(2*i+1,0), respectively.

The example below initializes a Hilbert matrix:

ⓘ
   Mat H(100, 100, CV_64F);
   for(int i = 0; i < H.rows; i++)
       for(int j = 0; j < H.cols; j++)
           H.at<double>(i,j)=1./(i+j+1);

Keep in mind that the size identifier used in the at operator cannot be chosen at random. It depends on the image from which you are trying to retrieve the data. The table below gives a better insight in this:

  • If matrix is of type CV_8U then use Mat.at<uchar>(y,x).
  • If matrix is of type CV_8S then use Mat.at<schar>(y,x).
  • If matrix is of type CV_16U then use Mat.at<ushort>(y,x).
  • If matrix is of type CV_16S then use Mat.at<short>(y,x).
  • If matrix is of type CV_32S then use Mat.at<int>(y,x).
  • If matrix is of type CV_32F then use Mat.at<float>(y,x).
  • If matrix is of type CV_64F then use Mat.at<double>(y,x).
Parameters
  • i0: Index along the dimension 0
Overloaded parameters

special versions for 2D arrays (especially convenient for referencing image pixels)

  • pt: Element position specified as Point(j,i) .

internal use method: updates the continuity flag

Implementors