Trait opencv::prelude::MatTrait

pub trait MatTrait: MatTraitConst {
    // Required method
    fn as_raw_mut_Mat(&mut self) -> *mut c_void;

    // Provided methods
    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: *const u8) { ... }
    fn u(&mut self) -> UMatData { ... }
    fn set_u(&mut self, val: &impl UMatDataTraitConst) { ... }
    fn set_size(&mut self, val: MatSize) { ... }
    fn set_matexpr(&mut self, expr: &impl MatExprTraitConst) -> Result<()> { ... }
    fn row_mut(&mut self, y: i32) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn col_mut(&mut self, x: i32) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn row_bounds_mut(
        &mut self,
        startrow: i32,
        endrow: i32
    ) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn row_range_mut(
        &mut self,
        r: &impl RangeTraitConst
    ) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn col_bounds_mut(
        &mut self,
        startcol: i32,
        endcol: i32
    ) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn col_range_mut(
        &mut self,
        r: &impl RangeTraitConst
    ) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn diag_def_mut(&mut self) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn diag_mut(&mut self, d: i32) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn set_scalar(&mut self, s: Scalar) -> Result<()> { ... }
    fn set_to(
        &mut self,
        value: &impl ToInputArray,
        mask: &impl ToInputArray
    ) -> Result<Mat> { ... }
    fn set_to_def(&mut self, value: &impl ToInputArray) -> Result<Mat> { ... }
    fn reshape_def_mut(&mut self, cn: i32) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn reshape_mut(
        &mut self,
        cn: i32,
        rows: i32
    ) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn reshape_nd_mut(
        &mut self,
        cn: i32,
        newsz: &[i32]
    ) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn reshape_nd_vec_mut(
        &mut self,
        cn: i32,
        newshape: &Vector<i32>
    ) -> Result<BoxedRefMut<'_, 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<()> { ... }
    unsafe fn addref(&mut self) -> Result<()> { ... }
    unsafe 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: &impl MatTraitConst) -> Result<()> { ... }
    fn pop_back(&mut self, nelems: size_t) -> Result<()> { ... }
    fn pop_back_def(&mut self) -> Result<()> { ... }
    fn adjust_roi(
        &mut self,
        dtop: i32,
        dbottom: i32,
        dleft: i32,
        dright: i32
    ) -> Result<Mat> { ... }
    fn rowscols_mut(
        &mut self,
        row_range: impl RangeTrait,
        col_range: impl RangeTrait
    ) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn roi_mut(&mut self, roi: Rect) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn ranges_mut(
        &mut self,
        ranges: &Vector<Range>
    ) -> Result<BoxedRefMut<'_, Mat>> { ... }
    fn ptr_mut(&mut self, i0: i32) -> Result<*mut u8> { ... }
    fn ptr_mut_def(&mut self) -> 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 set(&mut self, m: Mat) -> Result<()> { ... }
    fn update_continuity_flag(&mut self) -> Result<()> { ... }
}

Mutable methods for core::Mat

Required Methods

fn as_raw_mut_Mat(&mut self) -> *mut c_void

Provided Methods

fn set_flags(&mut self, val: i32)

! includes several bit-fields:

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

fn set_dims(&mut self, val: i32)

the matrix dimensionality, >= 2

fn set_rows(&mut self, val: i32)

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

fn set_cols(&mut self, val: i32)

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

fn data_mut(&mut self) -> *mut u8

pointer to the data

unsafe fn set_data(&mut self, val: *const u8)

pointer to the data

fn u(&mut self) -> UMatData

interaction with UMat

fn set_u(&mut self, val: &impl UMatDataTraitConst)

interaction with UMat

fn set_size(&mut self, val: MatSize)

fn set_matexpr(&mut self, expr: &impl MatExprTraitConst) -> Result<()>

assignment operators

These are available assignment operators. Since they all are very different, make sure to read the operator parameters description.

Parameters

• m: Assigned, right-hand-side matrix. Matrix assignment is an O(1) operation. This means that no data is copied but the data is shared and the reference counter, if any, is incremented. Before assigning new data, the old data is de-referenced via Mat::release .

Overloaded parameters

• expr: Assigned matrix expression object. As opposite to the first form of the assignment operation, the second form can reuse already allocated matrix if it has the right size and type to fit the matrix expression result. It is automatically handled by the real function that the matrix expressions is expanded to. For example, C=A+B is expanded to add(A, B, C), and add takes care of automatic C reallocation.

fn row_mut(&mut self, y: i32) -> Result<BoxedRefMut<'_, Mat>>

Creates a matrix header for the specified matrix row.

The method makes a new header for the specified matrix row and returns it. This is an O(1) operation, regardless of the matrix size. The underlying data of the new matrix is shared with the original matrix. Here is the example of one of the classical basic matrix processing operations, axpy, used by LU and many other algorithms:

   inline void matrix_axpy(Mat& A, int i, int j, double alpha)
   {
       A.row(i) += A.row(j)*alpha;
   }

Note: In the current implementation, the following code does not work as expected:

   Mat A;
   ...
   A.row(i) = A.row(j); // will not work

This happens because A.row(i) forms a temporary header that is further assigned to another header. Remember that each of these operations is O(1), that is, no data is copied. Thus, the above assignment is not true if you may have expected the j-th row to be copied to the i-th row. To achieve that, you should either turn this simple assignment into an expression or use the Mat::copyTo method:

   Mat A;
   ...
   // works, but looks a bit obscure.
   A.row(i) = A.row(j) + 0;
   // this is a bit longer, but the recommended method.
   A.row(j).copyTo(A.row(i));

Parameters

• y: A 0-based row index.

fn col_mut(&mut self, x: i32) -> Result<BoxedRefMut<'_, Mat>>

Creates a matrix header for the specified matrix column.

The method makes a new header for the specified matrix column and returns it. 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.

Parameters

• x: A 0-based column index.

fn row_bounds_mut( &mut self, startrow: i32, endrow: i32 ) -> Result<BoxedRefMut<'_, Mat>>

Creates a matrix header for the specified row span.

The method makes a new header for the specified row span of the matrix. Similarly to Mat::row and Mat::col , this is an O(1) operation.

Parameters

• startrow: An inclusive 0-based start index of the row span.
• endrow: An exclusive 0-based ending index of the row span.

fn row_range_mut( &mut self, r: &impl RangeTraitConst ) -> Result<BoxedRefMut<'_, Mat>>

@overload

Parameters

• r: Range structure containing both the start and the end indices.

fn col_bounds_mut( &mut self, startcol: i32, endcol: i32 ) -> Result<BoxedRefMut<'_, Mat>>

Creates a matrix header for the specified column span.

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.

Parameters

• startcol: An inclusive 0-based start index of the column span.
• endcol: An exclusive 0-based ending index of the column span.

fn col_range_mut( &mut self, r: &impl RangeTraitConst ) -> Result<BoxedRefMut<'_, Mat>>

@overload

Parameters

• r: Range structure containing both the start and the end indices.

fn diag_def_mut(&mut self) -> Result<BoxedRefMut<'_, Mat>>

Extracts a diagonal from a matrix

The method makes a new header for the specified matrix diagonal. The new matrix is represented as a single-column matrix. Similarly to Mat::row and Mat::col, this is an O(1) operation.

Parameters

• d: index of the diagonal, with the following values:

• d=0 is the main diagonal.
• d<0 is a diagonal from the lower half. For example, d=-1 means the diagonal is set immediately below the main one.
• d>0 is a diagonal from the upper half. For example, d=1 means the diagonal is set immediately above the main one. For example:

   Mat m = (Mat_<int>(3,3) <<
               1,2,3,
               4,5,6,
               7,8,9);
   Mat d0 = m.diag(0);
   Mat d1 = m.diag(1);
   Mat d_1 = m.diag(-1);

The resulting matrices are

 d0 =
   [1;
   5;
   9]
 d1 =
   [2;
   6]
 d_1 =
   [4;
   8]

Note

This alternative version of MatTraitConst::diag function uses the following default values for its arguments:

• d: 0

fn diag_mut(&mut self, d: i32) -> Result<BoxedRefMut<'_, Mat>>

Extracts a diagonal from a matrix

The method makes a new header for the specified matrix diagonal. The new matrix is represented as a single-column matrix. Similarly to Mat::row and Mat::col, this is an O(1) operation.

Parameters

• d: index of the diagonal, with the following values:

• d=0 is the main diagonal.
• d<0 is a diagonal from the lower half. For example, d=-1 means the diagonal is set immediately below the main one.
• d>0 is a diagonal from the upper half. For example, d=1 means the diagonal is set immediately above the main one. For example:

   Mat m = (Mat_<int>(3,3) <<
               1,2,3,
               4,5,6,
               7,8,9);
   Mat d0 = m.diag(0);
   Mat d1 = m.diag(1);
   Mat d_1 = m.diag(-1);

The resulting matrices are

 d0 =
   [1;
   5;
   9]
 d1 =
   [2;
   6]
 d_1 =
   [4;
   8]

C++ default parameters

• d: 0

fn set_scalar(&mut self, s: Scalar) -> Result<()>

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

Parameters

• s: Assigned scalar converted to the actual array type.

fn set_to( &mut self, value: &impl ToInputArray, mask: &impl ToInputArray ) -> Result<Mat>

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()

fn set_to_def(&mut self, value: &impl ToInputArray) -> Result<Mat>

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

Note

This alternative version of MatTrait::set_to function uses the following default values for its arguments:

• mask: noArray()

fn reshape_def_mut(&mut self, cn: i32) -> Result<BoxedRefMut<'_, Mat>>

Changes the shape and/or the number of channels of a 2D matrix without copying the data.

The method makes a new matrix header for *this elements. The new matrix may have a different size and/or different number of channels. Any combination is possible if:

• No extra elements are included into the new matrix and no elements are excluded. Consequently, the product rows*cols*channels() must stay the same after the transformation.
• No data is copied. That is, this is an O(1) operation. Consequently, if you change the number of rows, or the operation changes the indices of elements row in some other way, the matrix must be continuous. See Mat::isContinuous .

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:

   std::vector<Point3f> vec;
   ...
   Mat pointMat = Mat(vec). // convert vector to Mat, O(1) operation
                      reshape(1). // make Nx3 1-channel matrix out of Nx1 3-channel.
                                  // Also, an O(1) operation
                         t(); // finally, transpose the Nx3 matrix.
                              // This involves copying all the elements

3-channel 2x2 matrix reshaped to 1-channel 4x3 matrix, each column has values from one of original channels:

Mat m(Size(2, 2), CV_8UC3, Scalar(1, 2, 3));
vector<int> new_shape {4, 3};
m = m.reshape(1, new_shape);

or:

Mat m(Size(2, 2), CV_8UC3, Scalar(1, 2, 3));
const int new_shape[] = {4, 3};
m = m.reshape(1, 2, new_shape);

Parameters

• cn: New number of channels. If the parameter is 0, the number of channels remains the same.
• rows: New number of rows. If the parameter is 0, the number of rows remains the same.

Note

This alternative version of MatTraitConst::reshape function uses the following default values for its arguments:

• rows: 0

fn reshape_mut(&mut self, cn: i32, rows: i32) -> Result<BoxedRefMut<'_, Mat>>

Changes the shape and/or the number of channels of a 2D matrix without copying the data.

The method makes a new matrix header for *this elements. The new matrix may have a different size and/or different number of channels. Any combination is possible if:

• No extra elements are included into the new matrix and no elements are excluded. Consequently, the product rows*cols*channels() must stay the same after the transformation.
• No data is copied. That is, this is an O(1) operation. Consequently, if you change the number of rows, or the operation changes the indices of elements row in some other way, the matrix must be continuous. See Mat::isContinuous .

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:

   std::vector<Point3f> vec;
   ...
   Mat pointMat = Mat(vec). // convert vector to Mat, O(1) operation
                      reshape(1). // make Nx3 1-channel matrix out of Nx1 3-channel.
                                  // Also, an O(1) operation
                         t(); // finally, transpose the Nx3 matrix.
                              // This involves copying all the elements

3-channel 2x2 matrix reshaped to 1-channel 4x3 matrix, each column has values from one of original channels:

Mat m(Size(2, 2), CV_8UC3, Scalar(1, 2, 3));
vector<int> new_shape {4, 3};
m = m.reshape(1, new_shape);

or:

Mat m(Size(2, 2), CV_8UC3, Scalar(1, 2, 3));
const int new_shape[] = {4, 3};
m = m.reshape(1, 2, new_shape);

Parameters

• cn: New number of channels. If the parameter is 0, the number of channels remains the same.
• rows: New number of rows. If the parameter is 0, the number of rows remains the same.

C++ default parameters

• rows: 0

fn reshape_nd_mut( &mut self, cn: i32, newsz: &[i32] ) -> Result<BoxedRefMut<'_, Mat>>

@overload

Parameters

• cn: New number of channels. If the parameter is 0, the number of channels remains the same.
• newndims: New number of dimentions.
• newsz: Array with new matrix size by all dimentions. If some sizes are zero, the original sizes in those dimensions are presumed.

fn reshape_nd_vec_mut( &mut self, cn: i32, newshape: &Vector<i32> ) -> Result<BoxedRefMut<'_, Mat>>

@overload

Parameters

• cn: New number of channels. If the parameter is 0, the number of channels remains the same.
• newshape: Vector with new matrix size by all dimentions. If some sizes are zero, the original sizes in those dimensions are presumed.

unsafe fn create_rows_cols( &mut self, rows: i32, cols: i32, typ: i32 ) -> Result<()>

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.

unsafe fn create_size(&mut self, size: Size, typ: i32) -> Result<()>

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.

unsafe fn create_nd(&mut self, sizes: &[i32], typ: i32) -> Result<()>

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.

unsafe fn create_nd_vec(&mut self, sizes: &Vector<i32>, typ: i32) -> Result<()>

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.

unsafe fn addref(&mut self) -> Result<()>

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.

unsafe fn release(&mut self) -> Result<()>

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.

fn deallocate(&mut self) -> Result<()>

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

fn reserve(&mut self, sz: size_t) -> Result<()>

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.

fn reserve_buffer(&mut self, sz: size_t) -> Result<()>

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.

fn resize(&mut self, sz: size_t) -> Result<()>

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.

fn resize_with_default(&mut self, sz: size_t, s: Scalar) -> Result<()>

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.

fn push_back(&mut self, m: &impl MatTraitConst) -> Result<()>

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).

fn pop_back(&mut self, nelems: size_t) -> Result<()>

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

fn pop_back_def(&mut self) -> Result<()>

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.

Note

This alternative version of MatTrait::pop_back function uses the following default values for its arguments:

• nelems: 1

fn adjust_roi( &mut self, dtop: i32, dbottom: i32, dleft: i32, dright: i32 ) -> Result<Mat>

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

fn rowscols_mut( &mut self, row_range: impl RangeTrait, col_range: impl RangeTrait ) -> Result<BoxedRefMut<'_, Mat>>

Extracts a rectangular submatrix.

The operators make a new header for the specified sub-array of *this . They are the most generalized forms of Mat::row, Mat::col, Mat::rowRange, and Mat::colRange . For example, A(Range(0, 10), Range::all()) is equivalent to A.rowRange(0, 10). Similarly to all of the above, the operators are O(1) operations, that is, no matrix data is copied.

Parameters

• rowRange: Start and end row of the extracted submatrix. The upper boundary is not included. To select all the rows, use Range::all().
• colRange: Start and end column of the extracted submatrix. The upper boundary is not included. To select all the columns, use Range::all().

fn roi_mut(&mut self, roi: Rect) -> Result<BoxedRefMut<'_, Mat>>

@overload

Parameters

• roi: Extracted submatrix specified as a rectangle.

fn ranges_mut(&mut self, ranges: &Vector<Range>) -> Result<BoxedRefMut<'_, Mat>>

@overload

Parameters

• ranges: Array of selected ranges along each array dimension.

fn ptr_mut(&mut self, i0: i32) -> Result<*mut u8>

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

fn ptr_mut_def(&mut self) -> Result<*mut u8>

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.

Note

This alternative version of MatTrait::ptr_mut function uses the following default values for its arguments:

• i0: 0

fn ptr_2d_mut(&mut self, row: i32, col: i32) -> Result<*mut u8>

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

fn ptr_3d_mut(&mut self, i0: i32, i1: i32, i2: i32) -> Result<*mut u8>

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

fn ptr_nd_mut(&mut self, idx: &[i32]) -> Result<*mut u8>

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

fn at_mut<T: DataType>(&mut self, i0: i32) -> Result<&mut T>

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

fn at_2d_mut<T: DataType>(&mut self, row: i32, col: i32) -> Result<&mut T>

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

fn at_3d_mut<T: DataType>( &mut self, i0: i32, i1: i32, i2: i32 ) -> Result<&mut T>

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

fn at_nd_mut<T: DataType>(&mut self, idx: &[i32]) -> Result<&mut T>

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.

fn at_pt_mut<T: DataType>(&mut self, pt: Point) -> Result<&mut T>

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) .

fn set(&mut self, m: Mat) -> Result<()>

fn update_continuity_flag(&mut self) -> Result<()>

internal use method: updates the continuity flag

Object Safety

This trait is not object safe.

Implementors

impl MatTrait for BoxedRefMut<'_, Mat>

impl MatTrait for Mat

impl<T> MatTrait for Mat_<T>