| OpenCV 4.3.0 Open Source Computer Vision

Functions
Binary morphology on run-length encoded image
Extended Image Processing

## Functions
void | cv::ximgproc::rl::createRLEImage (std::vector< cv::Point3i > &runs, OutputArray res, Size size=Size(0, 0))
| Creates a run-length encoded image from a vector of runs (column begin, column end, row) More...
void | cv::ximgproc::rl::dilate (InputArray rlSrc, OutputArray rlDest, InputArray rlKernel, Point anchor=Point(0, 0))
| Dilates an run-length encoded binary image by using a specific structuring element. More...
void | cv::ximgproc::rl::erode (InputArray rlSrc, OutputArray rlDest, InputArray rlKernel, bool bBoundaryOn=true, Point anchor=Point(0, 0))
| Erodes an run-length encoded binary image by using a specific structuring element. More...
cv::Mat | cv::ximgproc::rl::getStructuringElement (int shape, Size ksize)
| Returns a run length encoded structuring element of the specified size and shape. More...
bool | cv::ximgproc::rl::isRLMorphologyPossible (InputArray rlStructuringElement)
| Check whether a custom made structuring element can be used with run length morphological operations. (It must consist of a continuous array of single runs per row) More...
void | cv::ximgproc::rl::morphologyEx (InputArray rlSrc, OutputArray rlDest, int op, InputArray rlKernel, bool bBoundaryOnForErosion=true, Point anchor=Point(0, 0))
| Applies a morphological operation to a run-length encoded binary image. More...
void | cv::ximgproc::rl::paint (InputOutputArray image, InputArray rlSrc, const cv::Scalar &value)
| Paint run length encoded binary image into an image. More...
void | cv::ximgproc::rl::threshold (InputArray src, OutputArray rlDest, double thresh, int type)
| Applies a fixed-level threshold to each array element. More...

## Detailed Description

These functions support morphological operations on binary images. In order to be fast and space efficient binary images are encoded with a run-length representation. This representation groups continuous horizontal sequences of "on" pixels together in a "run". A run is charactarized by the column position of the first pixel in the run, the column position of the last pixel in the run and the row position. This representation is very compact for binary images which contain large continuous areas of "on" and "off" pixels. A checkerboard pattern would be a good example. The representation is not so suitable for binary images created from random noise images or other images where little correlation between neighboring pixels exists.

The morphological operations supported here are very similar to the operations supported in the imgproc module. In general they are fast. However on several occasions they are slower than the functions from imgproc. The structuring elements of cv::MORPH_RECT and cv::MORPH_CROSS have very good support from the imgproc module. Also small structuring elements are very fast in imgproc (presumably due to opencl support). Therefore the functions from this module are recommended for larger structuring elements (cv::MORPH_ELLIPSE or self defined structuring elements). A sample application (run_length_morphology_demo) is supplied which allows to compare the speed of some morphological operations for the functions using run-length encoding and the imgproc functions for a given image.

Run length encoded images are stored in standard opencv images. Images have a single column of cv::Point3i elements. The number of rows is the number of run + 1. The first row contains the size of the original (not encoded) image. For the runs the following mapping is used (x: column begin, y: column end (last column), z: row).

The size of the original image is required for compatibility with the imgproc functions when the boundary handling requires that pixel outside the image boundary are "on".

## Function Documentation

## ◆ createRLEImage()

void cv::ximgproc::rl::createRLEImage | ( | std::vector< cv::Point3i > & | runs,
|  | OutputArray | res,
|  | Size | size = `Size(0, 0)`
| ) |  |

`#include <opencv2/ximgproc/run_length_morphology.hpp>`

Creates a run-length encoded image from a vector of runs (column begin, column end, row)

Parameters

  runs | vector of runs
  res | result
  size | image size (to be used if an "on" boundary should be used in erosion, using the default means that the size is computed from the extension of the input)

## ◆ dilate()

void cv::ximgproc::rl::dilate | ( | InputArray | rlSrc,
|  | OutputArray | rlDest,
|  | InputArray | rlKernel,
|  | Point | anchor = `Point(0, 0)`
| ) |  |

`#include <opencv2/ximgproc/run_length_morphology.hpp>`

Dilates an run-length encoded binary image by using a specific structuring element.

Parameters

  rlSrc | input image
  rlDest | result
  rlKernel | kernel
  anchor | position of the anchor within the element; default value (0, 0) is usually the element center.

## ◆ erode()

void cv::ximgproc::rl::erode | ( | InputArray | rlSrc,
|  | OutputArray | rlDest,
|  | InputArray | rlKernel,
|  | bool | bBoundaryOn = `true`,
|  | Point | anchor = `Point(0, 0)`
| ) |  |

`#include <opencv2/ximgproc/run_length_morphology.hpp>`

Erodes an run-length encoded binary image by using a specific structuring element.

Parameters

  rlSrc | input image
  rlDest | result
  rlKernel | kernel
  bBoundaryOn | indicates whether pixel outside the image boundary are assumed to be on (True: works in the same way as the default of cv::erode, False: is a little faster)
  anchor | position of the anchor within the element; default value (0, 0) is usually the element center.

## ◆ getStructuringElement()

cv::Mat cv::ximgproc::rl::getStructuringElement | ( | int | shape,
|  | Size | ksize
| ) |  |

`#include <opencv2/ximgproc/run_length_morphology.hpp>`

Returns a run length encoded structuring element of the specified size and shape.

Parameters

  shape | Element shape that can be one of cv::MorphShapes
  ksize | Size of the structuring element.

## ◆ isRLMorphologyPossible()

bool cv::ximgproc::rl::isRLMorphologyPossible | ( | InputArray | rlStructuringElement | ) |

`#include <opencv2/ximgproc/run_length_morphology.hpp>`

Check whether a custom made structuring element can be used with run length morphological operations. (It must consist of a continuous array of single runs per row)

Parameters

  rlStructuringElement | mask to be tested

## ◆ morphologyEx()

void cv::ximgproc::rl::morphologyEx | ( | InputArray | rlSrc,
|  | OutputArray | rlDest,
|  | int | op,
|  | InputArray | rlKernel,
|  | bool | bBoundaryOnForErosion = `true`,
|  | Point | anchor = `Point(0, 0)`
| ) |  |

`#include <opencv2/ximgproc/run_length_morphology.hpp>`

Applies a morphological operation to a run-length encoded binary image.

Parameters

  rlSrc | input image
  rlDest | result
  op | all operations supported by cv::morphologyEx (except cv::MORPH_HITMISS)
  rlKernel | kernel
  bBoundaryOnForErosion | indicates whether pixel outside the image boundary are assumed to be on for erosion operations (True: works in the same way as the default of cv::erode, False: is a little faster)
  anchor | position of the anchor within the element; default value (0, 0) is usually the element center.

## ◆ paint()

void cv::ximgproc::rl::paint | ( | InputOutputArray | image,
|  | InputArray | rlSrc,
|  | const cv::Scalar & | value
| ) |  |

`#include <opencv2/ximgproc/run_length_morphology.hpp>`

Paint run length encoded binary image into an image.

Parameters

  image | image to paint into (currently only single channel images).
  rlSrc | run length encoded image
  value | all foreground pixel of the binary image are set to this value

## ◆ threshold()

void cv::ximgproc::rl::threshold | ( | InputArray | src,
|  | OutputArray | rlDest,
|  | double | thresh,
|  | int | type
| ) |  |

`#include <opencv2/ximgproc/run_length_morphology.hpp>`

Applies a fixed-level threshold to each array element.

Parameters

  src | input array (single-channel).
  rlDest | resulting run length encoded image.
  thresh | threshold value.
  type | thresholding type (only cv::THRESH_BINARY and cv::THRESH_BINARY_INV are supported)