OpenCV  4.2.0
Open Source Computer Vision
Mask operations on matrices

.2.0+dfsg_doc_tutorials_core_mat-mask-operations_mat_mask_operations

Prev Tutorial: How to scan images, lookup tables and time measurement with OpenCV
Next Tutorial: Operations with images
Mask operations on matrices are quite simple. The idea is that we recalculate each pixel's value in an image according to a mask matrix (also known as kernel). This mask holds values that will adjust how much influence neighboring pixels (and the current pixel) have on the new pixel value. From a mathematical point of view we make a weighted average, with our specified values.

Our test case

Let's consider the issue of an image contrast enhancement method. Basically we want to apply for every pixel of the image the following formula:

\[I(i,j) = 5*I(i,j) - [ I(i-1,j) + I(i+1,j) + I(i,j-1) + I(i,j+1)]\]

\[\iff I(i,j)*M, \text{where } M = \bordermatrix{ _i\backslash ^j & -1 & 0 & +1 \cr -1 & 0 & -1 & 0 \cr 0 & -1 & 5 & -1 \cr +1 & 0 & -1 & 0 \cr }\]

The first notation is by using a formula, while the second is a compacted version of the first by using a mask. You use the mask by putting the center of the mask matrix (in the upper case noted by the zero-zero index) on the pixel you want to calculate and sum up the pixel values multiplied with the overlapped matrix values. It's the same thing, however in case of large matrices the latter notation is a lot easier to look over.

Code

The Basic Method

Now let us see how we can make this happen by using the basic pixel access method or by using the filter2D() function.

Here's a function that will do this:

We create an output image with the same size and the same type as our input. As you can see in the storing section, depending on the number of channels we may have one or more subcolumns.

The filter2D function

Applying such filters are so common in image processing that in OpenCV there is a function that will take care of applying the mask (also called a kernel in some places). For this you first need to define an object that holds the mask:

Then call the filter2D() function specifying the input, the output image and the kernel to use:

The function even has a fifth optional argument to specify the center of the kernel, a sixth for adding an optional value to the filtered pixels before storing them in K and a seventh one for determining what to do in the regions where the operation is undefined (borders).

This function is shorter, less verbose and, because there are some optimizations, it is usually faster than the hand-coded method. For example in my test while the second one took only 13 milliseconds the first took around 31 milliseconds. Quite some difference.

For example:

cv::Mat::rows
int rows
the number of rows and columns or (-1, -1) when the matrix has more than 2 dimensions
Definition: mat.hpp:2086
cv::String
std::string String
Definition: cvstd.hpp:150
cv::imread
CV_EXPORTS_W Mat imread(const String &filename, int flags=IMREAD_COLOR)
Loads an image from a file.
cv::IMREAD_COLOR
@ IMREAD_COLOR
If set, always convert image to the 3 channel BGR color image.
Definition: imgcodecs.hpp:67
cv::filter2D
void filter2D(InputArray src, OutputArray dst, int ddepth, InputArray kernel, Point anchor=Point(-1,-1), double delta=0, int borderType=BORDER_DEFAULT)
Convolves an image with the kernel.
cv::cvtColor
void cvtColor(InputArray src, OutputArray dst, int code, int dstCn=0)
Converts an image from one color space to another.
cv::samples::findFile
cv::String findFile(const cv::String &relative_path, bool required=true, bool silentMode=false)
Try to find requested data file.
cv::saturate_cast< uchar >
uchar saturate_cast< uchar >(schar v)
Definition: saturate.hpp:100
cv::Mat::ptr
uchar * ptr(int i0=0)
Returns a pointer to the specified matrix row.
cv::waitKey
int waitKey(int delay=0)
Waits for a pressed key.
CV_8U
#define CV_8U
Definition: interface.h:73
cv::sum
Scalar sum(InputArray src)
Calculates the sum of array elements.
cv::Mat::setTo
Mat & setTo(InputArray value, InputArray mask=noArray())
Sets all or some of the array elements to the specified value.
highgui.hpp
cv::IMREAD_GRAYSCALE
@ IMREAD_GRAYSCALE
If set, always convert image to the single channel grayscale image (codec internal conversion).
Definition: imgcodecs.hpp:66
cv::namedWindow
void namedWindow(const String &winname, int flags=WINDOW_AUTOSIZE)
Creates a window.
cv::Mat::row
Mat row(int y) const
Creates a matrix header for the specified matrix row.
cv::Mat::empty
bool empty() const
Returns true if the array has no elements.
cv::Mat::cols
int cols
Definition: mat.hpp:2086
cv::gapi::own::saturate
static DST saturate(SRC x)
Definition: saturate.hpp:26
cv::Mat::size
MatSize size
Definition: mat.hpp:2108
imgcodecs.hpp
cv::Mat::col
Mat col(int x) const
Creates a matrix header for the specified matrix column.
cv::dnn::print
static void print(const MatShape &shape, const String &name="")
Definition: shape_utils.hpp:188
cv::getTickCount
int64 getTickCount()
Returns the number of ticks.
uchar
unsigned char uchar
Definition: interface.h:51
cv::imshow
void imshow(const String &winname, InputArray mat)
Displays an image in the specified window.
cv::getTickFrequency
double getTickFrequency()
Returns the number of ticks per second.
cv::Scalar
Scalar_< double > Scalar
Definition: types.hpp:669
CV_Assert
#define CV_Assert(expr)
Checks a condition at runtime and throws exception if it fails.
Definition: base.hpp:342
cv::Mat
n-dimensional dense array class
Definition: mat.hpp:792
cv::imshow
void imshow(const String &winname, const ogl::Texture2D &tex)
Displays OpenGL 2D texture in the specified window.
cv::Mat::type
int type() const
Returns the type of a matrix element.
cv::hal::filter2D
void filter2D(int stype, int dtype, int kernel_type, uchar *src_data, size_t src_step, uchar *dst_data, size_t dst_step, int width, int height, int full_width, int full_height, int offset_x, int offset_y, uchar *kernel_data, size_t kernel_step, int kernel_width, int kernel_height, int anchor_x, int anchor_y, double delta, int borderType, bool isSubmatrix)
cv
"black box" representation of the file storage associated with a file on disk.
Definition: affine.hpp:52
imgproc.hpp
cv::destroyAllWindows
void destroyAllWindows()
Destroys all of the HighGUI windows.
cv::WINDOW_AUTOSIZE
@ WINDOW_AUTOSIZE
the user cannot resize the window, the size is constrainted by the image displayed.
Definition: highgui.hpp:184
cv::Mat::create
void create(int rows, int cols, int type)
Allocates new array data if needed.
cv::Mat::channels
int channels() const
Returns the number of matrix channels.
cv::Mat_
Template matrix class derived from Mat.
Definition: mat.hpp:2178
cv::Mat::depth
int depth() const
Returns the depth of a matrix element.