Trait opencv::prelude::MatTraitConst

pub trait MatTraitConst {
    // Required method
    fn as_raw_Mat(&self) -> *const c_void;

    // Provided methods
    fn flags(&self) -> i32 { ... }
    fn dims(&self) -> i32 { ... }
    fn rows(&self) -> i32 { ... }
    fn cols(&self) -> i32 { ... }
    fn data(&self) -> *const u8 { ... }
    fn datastart(&self) -> *const u8 { ... }
    fn dataend(&self) -> *const u8 { ... }
    fn datalimit(&self) -> *const u8 { ... }
    fn mat_size(&self) -> MatSize { ... }
    fn mat_step(&self) -> MatStep { ... }
    fn get_umat(
        &self,
        access_flags: AccessFlag,
        usage_flags: UMatUsageFlags
    ) -> Result<UMat> { ... }
    fn get_umat_def(&self, access_flags: AccessFlag) -> Result<UMat> { ... }
    fn row(&self, y: i32) -> Result<BoxedRef<'_, Mat>> { ... }
    fn col(&self, x: i32) -> Result<BoxedRef<'_, Mat>> { ... }
    fn row_bounds(
        &self,
        startrow: i32,
        endrow: i32
    ) -> Result<BoxedRef<'_, Mat>> { ... }
    fn row_range(&self, r: &impl RangeTraitConst) -> Result<BoxedRef<'_, Mat>> { ... }
    fn col_bounds(
        &self,
        startcol: i32,
        endcol: i32
    ) -> Result<BoxedRef<'_, Mat>> { ... }
    fn col_range(&self, r: &impl RangeTraitConst) -> Result<BoxedRef<'_, Mat>> { ... }
    fn diag(&self, d: i32) -> Result<BoxedRef<'_, Mat>> { ... }
    fn diag_def(&self) -> Result<BoxedRef<'_, Mat>> { ... }
    fn try_clone(&self) -> Result<Mat> { ... }
    fn copy_to(&self, m: &mut impl ToOutputArray) -> Result<()> { ... }
    fn copy_to_masked(
        &self,
        m: &mut impl ToOutputArray,
        mask: &impl ToInputArray
    ) -> Result<()> { ... }
    fn convert_to(
        &self,
        m: &mut impl ToOutputArray,
        rtype: i32,
        alpha: f64,
        beta: f64
    ) -> Result<()> { ... }
    fn convert_to_def(
        &self,
        m: &mut impl ToOutputArray,
        rtype: i32
    ) -> Result<()> { ... }
    fn assign_to(&self, m: &mut impl MatTrait, typ: i32) -> Result<()> { ... }
    fn assign_to_def(&self, m: &mut impl MatTrait) -> Result<()> { ... }
    fn reshape(&self, cn: i32, rows: i32) -> Result<BoxedRef<'_, Mat>> { ... }
    fn reshape_def(&self, cn: i32) -> Result<BoxedRef<'_, Mat>> { ... }
    fn reshape_nd(&self, cn: i32, newsz: &[i32]) -> Result<BoxedRef<'_, Mat>> { ... }
    fn reshape_nd_vec(
        &self,
        cn: i32,
        newshape: &Vector<i32>
    ) -> Result<BoxedRef<'_, Mat>> { ... }
    fn t(&self) -> Result<MatExpr> { ... }
    fn inv(&self, method: i32) -> Result<MatExpr> { ... }
    fn inv_def(&self) -> Result<MatExpr> { ... }
    fn mul(&self, m: &impl ToInputArray, scale: f64) -> Result<MatExpr> { ... }
    fn mul_def(&self, m: &impl ToInputArray) -> Result<MatExpr> { ... }
    fn cross(&self, m: &impl ToInputArray) -> Result<Mat> { ... }
    fn dot(&self, m: &impl ToInputArray) -> Result<f64> { ... }
    fn locate_roi(&self, whole_size: &mut Size, ofs: &mut Point) -> Result<()> { ... }
    fn rowscols(
        &self,
        row_range: impl RangeTrait,
        col_range: impl RangeTrait
    ) -> Result<BoxedRef<'_, Mat>> { ... }
    fn roi(&self, roi: Rect) -> Result<BoxedRef<'_, Mat>> { ... }
    fn ranges(&self, ranges: &Vector<Range>) -> Result<BoxedRef<'_, Mat>> { ... }
    fn is_continuous(&self) -> bool { ... }
    fn is_submatrix(&self) -> bool { ... }
    fn elem_size(&self) -> Result<size_t> { ... }
    fn elem_size1(&self) -> size_t { ... }
    fn typ(&self) -> i32 { ... }
    fn depth(&self) -> i32 { ... }
    fn channels(&self) -> i32 { ... }
    fn step1(&self, i: i32) -> Result<size_t> { ... }
    fn step1_def(&self) -> Result<size_t> { ... }
    fn empty(&self) -> bool { ... }
    fn total(&self) -> size_t { ... }
    fn total_slice(&self, start_dim: i32, end_dim: i32) -> Result<size_t> { ... }
    fn total_slice_def(&self, start_dim: i32) -> Result<size_t> { ... }
    fn check_vector(
        &self,
        elem_channels: i32,
        depth: i32,
        require_continuous: bool
    ) -> Result<i32> { ... }
    fn check_vector_def(&self, elem_channels: i32) -> Result<i32> { ... }
    fn ptr(&self, i0: i32) -> Result<*const u8> { ... }
    fn ptr_def(&self) -> Result<*const u8> { ... }
    fn ptr_2d(&self, row: i32, col: i32) -> Result<*const u8> { ... }
    fn ptr_3d(&self, i0: i32, i1: i32, i2: i32) -> Result<*const u8> { ... }
    fn ptr_nd(&self, idx: &[i32]) -> Result<*const u8> { ... }
    fn at<T: DataType>(&self, i0: i32) -> Result<&T> { ... }
    fn at_2d<T: DataType>(&self, row: i32, col: i32) -> Result<&T> { ... }
    fn at_3d<T: DataType>(&self, i0: i32, i1: i32, i2: i32) -> Result<&T> { ... }
    fn at_nd<T: DataType>(&self, idx: &[i32]) -> Result<&T> { ... }
    fn at_pt<T: DataType>(&self, pt: Point) -> Result<&T> { ... }
    fn size(&self) -> Result<Size> { ... }
}

Constant methods for core::Mat

Required Methods

fn as_raw_Mat(&self) -> *const c_void

Provided Methods

fn flags(&self) -> i32

! includes several bit-fields:

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

fn dims(&self) -> i32

the matrix dimensionality, >= 2

fn rows(&self) -> i32

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

fn cols(&self) -> i32

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

fn data(&self) -> *const u8

pointer to the data

fn datastart(&self) -> *const u8

helper fields used in locateROI and adjustROI

fn dataend(&self) -> *const u8

fn datalimit(&self) -> *const u8

fn mat_size(&self) -> MatSize

fn mat_step(&self) -> MatStep

fn get_umat( &self, access_flags: AccessFlag, usage_flags: UMatUsageFlags ) -> Result<UMat>

retrieve UMat from Mat

C++ default parameters

• usage_flags: USAGE_DEFAULT

fn get_umat_def(&self, access_flags: AccessFlag) -> Result<UMat>

retrieve UMat from Mat

Note

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

• usage_flags: USAGE_DEFAULT

fn row(&self, y: i32) -> Result<BoxedRef<'_, 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(&self, x: i32) -> Result<BoxedRef<'_, 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(&self, startrow: i32, endrow: i32) -> Result<BoxedRef<'_, 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(&self, r: &impl RangeTraitConst) -> Result<BoxedRef<'_, 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.

Overloaded parameters

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

fn col_bounds(&self, startcol: i32, endcol: i32) -> Result<BoxedRef<'_, 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(&self, r: &impl RangeTraitConst) -> Result<BoxedRef<'_, 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.

Overloaded parameters

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

fn diag(&self, d: i32) -> Result<BoxedRef<'_, 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 diag_def(&self) -> Result<BoxedRef<'_, 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 try_clone(&self) -> Result<Mat>

Creates a full copy of the array and the underlying data.

The method creates a full copy of the array. The original step[] is not taken into account. So, the array copy is a continuous array occupying total()*elemSize() bytes.

fn copy_to(&self, m: &mut impl ToOutputArray) -> Result<()>

Copies the matrix to another one.

The method copies the matrix data to another matrix. Before copying the data, the method invokes :

   m.create(this->size(), this->type());

so that the destination matrix is reallocated if needed. While m.copyTo(m); works flawlessly, the function does not handle the case of a partial overlap between the source and the destination matrices.

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.

Parameters

• m: Destination matrix. If it does not have a proper size or type before the operation, it is reallocated.

fn copy_to_masked( &self, m: &mut impl ToOutputArray, mask: &impl ToInputArray ) -> Result<()>

Copies the matrix to another one.

The method copies the matrix data to another matrix. Before copying the data, the method invokes :

   m.create(this->size(), this->type());

so that the destination matrix is reallocated if needed. While m.copyTo(m); works flawlessly, the function does not handle the case of a partial overlap between the source and the destination matrices.

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.

Parameters

• m: Destination matrix. If it does not have a proper size or type before the operation, it is reallocated.

Overloaded parameters

• m: Destination matrix. If it does not have a proper size or type before the operation, it is reallocated.
• 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.

fn convert_to( &self, m: &mut impl ToOutputArray, rtype: i32, alpha: f64, beta: f64 ) -> Result<()>

Converts an array to another data type with optional scaling.

The method converts source pixel values to the target data type. saturate_cast<> is applied at the end to avoid possible overflows:

Parameters

• m: output matrix; if it does not have a proper size or type before the operation, it is reallocated.
• rtype: desired output matrix type or, rather, the depth since the number of channels are the same as the input has; if rtype is negative, the output matrix will have the same type as the input.
• alpha: optional scale factor.
• beta: optional delta added to the scaled values.

C++ default parameters

• alpha: 1
• beta: 0

fn convert_to_def(&self, m: &mut impl ToOutputArray, rtype: i32) -> Result<()>

Converts an array to another data type with optional scaling.

The method converts source pixel values to the target data type. saturate_cast<> is applied at the end to avoid possible overflows:

Parameters

• m: output matrix; if it does not have a proper size or type before the operation, it is reallocated.
• rtype: desired output matrix type or, rather, the depth since the number of channels are the same as the input has; if rtype is negative, the output matrix will have the same type as the input.
• alpha: optional scale factor.
• beta: optional delta added to the scaled values.

Note

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

• alpha: 1
• beta: 0

fn assign_to(&self, m: &mut impl MatTrait, typ: i32) -> Result<()>

Provides a functional form of convertTo.

This is an internally used method called by the [MatrixExpressions] engine.

Parameters

• m: Destination array.
• type: Desired destination array depth (or -1 if it should be the same as the source type).

C++ default parameters

• typ: -1

fn assign_to_def(&self, m: &mut impl MatTrait) -> Result<()>

Provides a functional form of convertTo.

This is an internally used method called by the [MatrixExpressions] engine.

Parameters

• m: Destination array.
• type: Desired destination array depth (or -1 if it should be the same as the source type).

Note

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

• typ: -1

fn reshape(&self, cn: i32, rows: i32) -> Result<BoxedRef<'_, 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_def(&self, cn: i32) -> Result<BoxedRef<'_, 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_nd(&self, cn: i32, newsz: &[i32]) -> Result<BoxedRef<'_, 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.

Overloaded 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( &self, cn: i32, newshape: &Vector<i32> ) -> Result<BoxedRef<'_, 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.

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

fn t(&self) -> Result<MatExpr>

Transposes a matrix.

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:

   Mat A1 = A + Mat::eye(A.size(), A.type())*lambda;
   Mat C = A1.t()*A1; // compute (A + lambda*I)^t * (A + lamda*I)

fn inv(&self, method: i32) -> Result<MatExpr>

Inverses a matrix.

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.

Parameters

• method: Matrix inversion method. One of cv::DecompTypes

C++ default parameters

• method: DECOMP_LU

fn inv_def(&self) -> Result<MatExpr>

Inverses a matrix.

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.

Parameters

• method: Matrix inversion method. One of cv::DecompTypes

Note

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

• method: DECOMP_LU

fn mul(&self, m: &impl ToInputArray, scale: f64) -> Result<MatExpr>

Performs an element-wise multiplication or division of the two matrices.

The method returns a temporary object encoding per-element array multiplication, with optional scale. Note that this is not a matrix multiplication that corresponds to a simpler “*” operator.

Example:

   Mat C = A.mul(5/B); // equivalent to divide(A, B, C, 5)

Parameters

• m: Another array of the same type and the same size as *this, or a matrix expression.
• scale: Optional scale factor.

C++ default parameters

• scale: 1

fn mul_def(&self, m: &impl ToInputArray) -> Result<MatExpr>

Performs an element-wise multiplication or division of the two matrices.

The method returns a temporary object encoding per-element array multiplication, with optional scale. Note that this is not a matrix multiplication that corresponds to a simpler “*” operator.

Example:

   Mat C = A.mul(5/B); // equivalent to divide(A, B, C, 5)

Parameters

• m: Another array of the same type and the same size as *this, or a matrix expression.
• scale: Optional scale factor.

Note

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

• scale: 1

fn cross(&self, m: &impl ToInputArray) -> Result<Mat>

Computes a cross-product of two 3-element vectors.

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.

Parameters

• m: Another cross-product operand.

fn dot(&self, m: &impl ToInputArray) -> Result<f64>

Computes a dot-product of two vectors.

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.

Parameters

• m: another dot-product operand.

fn locate_roi(&self, whole_size: &mut Size, ofs: &mut Point) -> Result<()>

Locates the matrix header within a parent 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.

Parameters

• wholeSize: Output parameter that contains the size of the whole matrix containing this as a part.
• ofs: Output parameter that contains an offset of this inside the whole matrix.

fn rowscols( &self, row_range: impl RangeTrait, col_range: impl RangeTrait ) -> Result<BoxedRef<'_, 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(&self, roi: Rect) -> Result<BoxedRef<'_, 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().

Overloaded parameters

• roi: Extracted submatrix specified as a rectangle.

fn ranges(&self, ranges: &Vector<Range>) -> Result<BoxedRef<'_, 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().

Overloaded parameters

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

fn is_continuous(&self) -> bool

Reports whether the matrix is continuous or not.

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:

   // alternative implementation of Mat::isContinuous()
   bool myCheckMatContinuity(const Mat& m)
   {
       //return (m.flags & Mat::CONTINUOUS_FLAG) != 0;
       return m.rows == 1 || m.step == m.cols*m.elemSize();
   }

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:

   template<typename T>
   void alphaBlendRGBA(const Mat& src1, const Mat& src2, Mat& dst)
   {
       const float alpha_scale = (float)std::numeric_limits<T>::max(),
                   inv_scale = 1.f/alpha_scale;
 
       CV_Assert( src1.type() == src2.type() &&
                   src1.type() == CV_MAKETYPE(traits::Depth<T>::value, 4) &&
                   src1.size() == src2.size());
       Size size = src1.size();
       dst.create(size, src1.type());
 
       // here is the idiom: check the arrays for continuity and,
       // if this is the case,
       // treat the arrays as 1D vectors
       if( src1.isContinuous() && src2.isContinuous() && dst.isContinuous() )
       {
           size.width *= size.height;
           size.height = 1;
       }
       size.width *= 4;
 
       for( int i = 0; i < size.height; i++ )
       {
           // when the arrays are continuous,
           // the outer loop is executed only once
           const T* ptr1 = src1.ptr<T>(i);
           const T* ptr2 = src2.ptr<T>(i);
           T* dptr = dst.ptr<T>(i);
 
           for( int j = 0; j < size.width; j += 4 )
           {
               float alpha = ptr1[j+3]*inv_scale, beta = ptr2[j+3]*inv_scale;
               dptr[j] = saturate_cast<T>(ptr1[j]*alpha + ptr2[j]*beta);
               dptr[j+1] = saturate_cast<T>(ptr1[j+1]*alpha + ptr2[j+1]*beta);
               dptr[j+2] = saturate_cast<T>(ptr1[j+2]*alpha + ptr2[j+2]*beta);
               dptr[j+3] = saturate_cast<T>((1 - (1-alpha)*(1-beta))*alpha_scale);
           }
       }
   }

This approach, while being very simple, can boost the performance of a simple element-operation by 10-20 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.

fn is_submatrix(&self) -> bool

returns true if the matrix is a submatrix of another matrix

fn elem_size(&self) -> Result<size_t>

Returns the matrix element size in bytes.

The method returns the matrix element size in bytes. For example, if the matrix type is CV_16SC3 , the method returns 3*sizeof(short) or 6.

fn elem_size1(&self) -> size_t

Returns the size of each matrix element channel in bytes.

The method returns the matrix element channel size in bytes, that is, it ignores the number of channels. For example, if the matrix type is CV_16SC3 , the method returns sizeof(short) or 2.

fn typ(&self) -> i32

Returns the type of a matrix element.

The method returns a matrix element type. This is an identifier compatible with the CvMat type system, like CV_16SC3 or 16-bit signed 3-channel array, and so on.

fn depth(&self) -> i32

Returns the depth of a matrix element.

The method returns the identifier of the matrix element depth (the type of each individual channel). For example, for a 16-bit signed element array, the method returns CV_16S . A complete list of matrix types contains the following values:

• CV_8U - 8-bit unsigned integers ( 0..255 )
• CV_8S - 8-bit signed integers ( -128..127 )
• CV_16U - 16-bit unsigned integers ( 0..65535 )
• CV_16S - 16-bit signed integers ( -32768..32767 )
• CV_32S - 32-bit signed integers ( -2147483648..2147483647 )
• CV_32F - 32-bit floating-point numbers ( -FLT_MAX..FLT_MAX, INF, NAN )
• CV_64F - 64-bit floating-point numbers ( -DBL_MAX..DBL_MAX, INF, NAN )

fn channels(&self) -> i32

Returns the number of matrix channels.

The method returns the number of matrix channels.

fn step1(&self, i: i32) -> Result<size_t>

Returns a normalized step.

The method returns a matrix step divided by Mat::elemSize1() . It can be useful to quickly access an arbitrary matrix element.

C++ default parameters

• i: 0

fn step1_def(&self) -> Result<size_t>

Returns a normalized step.

The method returns a matrix step divided by Mat::elemSize1() . It can be useful to quickly access an arbitrary matrix element.

Note

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

• i: 0

fn empty(&self) -> bool

Returns true if the array has no elements.

The method returns true if Mat::total() is 0 or if Mat::data is NULL. Because of pop_back() and resize() methods M.total() == 0 does not imply that M.data == NULL.

fn total(&self) -> size_t

Returns the total number of array elements.

The method returns the number of array elements (a number of pixels if the array represents an image).

fn total_slice(&self, start_dim: i32, end_dim: i32) -> Result<size_t>

Returns the total number of array elements.

The method returns the number of elements within a certain sub-array slice with startDim <= dim < endDim

C++ default parameters

• end_dim: INT_MAX

fn total_slice_def(&self, start_dim: i32) -> Result<size_t>

Returns the total number of array elements.

The method returns the number of elements within a certain sub-array slice with startDim <= dim < endDim

Note

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

• end_dim: INT_MAX

fn check_vector( &self, elem_channels: i32, depth: i32, require_continuous: bool ) -> Result<i32>

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.
• depth: The depth the matrix should have. Set it to -1 when any depth is fine.
• requireContinuous: Set it to true to require the matrix to be continuous

Returns

-1 if the requirement is not satisfied. Otherwise, it returns the number of elements in the matrix. Note that an element may have multiple channels.

The following code demonstrates its usage for a 2-d matrix: example-2d

The following code demonstrates its usage for a 3-d matrix: example-3d

C++ default parameters

• depth: -1
• require_continuous: true

fn check_vector_def(&self, elem_channels: i32) -> Result<i32>

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.
• depth: The depth the matrix should have. Set it to -1 when any depth is fine.
• requireContinuous: Set it to true to require the matrix to be continuous

Returns

-1 if the requirement is not satisfied. Otherwise, it returns the number of elements in the matrix. Note that an element may have multiple channels.

The following code demonstrates its usage for a 2-d matrix: example-2d

The following code demonstrates its usage for a 3-d matrix: example-3d

Note

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

• depth: -1
• require_continuous: true

fn ptr(&self, i0: i32) -> Result<*const 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

C++ default parameters

• i0: 0

fn ptr_def(&self) -> Result<*const u8>

@overload

Note

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

• i0: 0

fn ptr_2d(&self, row: i32, col: i32) -> Result<*const 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(&self, i0: i32, i1: i32, i2: i32) -> Result<*const 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(&self, idx: &[i32]) -> Result<*const 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<T: DataType>(&self, i0: i32) -> Result<&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

C++ default parameters

• i0: 0

fn at_2d<T: DataType>(&self, row: i32, col: i32) -> Result<&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<T: DataType>(&self, i0: i32, i1: i32, i2: i32) -> Result<&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<T: DataType>(&self, idx: &[i32]) -> Result<&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<T: DataType>(&self, pt: Point) -> Result<&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 size(&self) -> Result<Size>

Object Safety

This trait is not object safe.

Implementors

impl MatTraitConst for BoxedRef<'_, Mat>

impl MatTraitConst for BoxedRefMut<'_, Mat>

impl MatTraitConst for Mat

impl<T> MatTraitConst for Mat_<T>