Structural Analysis and Shape Descriptors#

Detailed Description#

Namespaces#

Classes#

Name

Description

class cv::GeneralizedHough

finds arbitrary template in the grayscale image using Generalized Hough Transform View details

class cv::GeneralizedHoughBallard

finds arbitrary template in the grayscale image using Generalized Hough Transform View details

class cv::GeneralizedHoughGuil

finds arbitrary template in the grayscale image using Generalized Hough Transform View details

class cv::Moments

struct returned by cv::moments View details

Enumerations#

enum cv::ConnectedComponentsAlgorithmsTypes {
    cv::CCL_DEFAULT = -1,
    cv::CCL_WU = 0,
    cv::CCL_GRANA = 1,
    cv::CCL_BOLELLI = 2,
    cv::CCL_SAUF = 3,
    cv::CCL_BBDT = 4,
    cv::CCL_SPAGHETTI = 5
}

connected components algorithm View details

enum cv::ConnectedComponentsTypes {
    cv::CC_STAT_LEFT = 0,
    cv::CC_STAT_TOP = 1,
    cv::CC_STAT_WIDTH = 2,
    cv::CC_STAT_HEIGHT = 3,
    cv::CC_STAT_AREA = 4
}

connected components statistics View details

enum cv::ContourApproximationModes {
    cv::CHAIN_CODE = 0,
    cv::CHAIN_APPROX_NONE = 1,
    cv::CHAIN_APPROX_SIMPLE = 2,
    cv::CHAIN_APPROX_TC89_L1 = 3,
    cv::CHAIN_APPROX_TC89_KCOS = 4,
    cv::LINK_RUNS = 5
}

the contour approximation algorithm View details

enum cv::RetrievalModes {
    cv::RETR_EXTERNAL = 0,
    cv::RETR_LIST = 1,
    cv::RETR_CCOMP = 2,
    cv::RETR_TREE = 3,
    cv::RETR_FLOODFILL = 4
}

mode of the contour retrieval algorithm View details

enum cv::ShapeMatchModes {
    cv::CONTOURS_MATCH_I1 =1,
    cv::CONTOURS_MATCH_I2 =2,
    cv::CONTOURS_MATCH_I3 =3
}

Shape matching methods. View details

Enumeration Type Documentation#

ConnectedComponentsAlgorithmsTypes#

enum cv::ConnectedComponentsAlgorithmsTypes

#include <opencv2/imgproc.hpp>

connected components algorithm

Enumerator:

CCL_DEFAULT
Python: cv.CCL_DEFAULT

Spaghetti [36] algorithm for 8-way connectivity, Spaghetti4C [37] algorithm for 4-way connectivity.

CCL_WU
Python: cv.CCL_WU

SAUF [337] algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity. The parallel implementation described in [35] is available for SAUF.

CCL_GRANA
Python: cv.CCL_GRANA

BBDT [122] algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity. The parallel implementation described in [35] is available for both BBDT and SAUF.

CCL_BOLELLI
Python: cv.CCL_BOLELLI

Spaghetti [36] algorithm for 8-way connectivity, Spaghetti4C [37] algorithm for 4-way connectivity. The parallel implementation described in [35] is available for both Spaghetti and Spaghetti4C.

CCL_SAUF
Python: cv.CCL_SAUF

Same as CCL_WU. It is preferable to use the flag with the name of the algorithm (CCL_SAUF) rather than the one with the name of the first author (CCL_WU).

CCL_BBDT
Python: cv.CCL_BBDT

Same as CCL_GRANA. It is preferable to use the flag with the name of the algorithm (CCL_BBDT) rather than the one with the name of the first author (CCL_GRANA).

CCL_SPAGHETTI
Python: cv.CCL_SPAGHETTI

Same as CCL_BOLELLI. It is preferable to use the flag with the name of the algorithm (CCL_SPAGHETTI) rather than the one with the name of the first author (CCL_BOLELLI).

ConnectedComponentsTypes#

enum cv::ConnectedComponentsTypes

#include <opencv2/imgproc.hpp>

connected components statistics

Enumerator:

CC_STAT_LEFT
Python: cv.CC_STAT_LEFT

The leftmost (x) coordinate which is the inclusive start of the bounding box in the horizontal direction.

CC_STAT_TOP
Python: cv.CC_STAT_TOP

The topmost (y) coordinate which is the inclusive start of the bounding box in the vertical direction.

CC_STAT_WIDTH
Python: cv.CC_STAT_WIDTH

The horizontal size of the bounding box.

CC_STAT_HEIGHT
Python: cv.CC_STAT_HEIGHT

The vertical size of the bounding box.

CC_STAT_AREA
Python: cv.CC_STAT_AREA

The total area (in pixels) of the connected component.

ContourApproximationModes#

enum cv::ContourApproximationModes

#include <opencv2/imgproc.hpp>

the contour approximation algorithm

Enumerator:

CHAIN_CODE
Python: cv.CHAIN_CODE

TBD

CHAIN_APPROX_NONE
Python: cv.CHAIN_APPROX_NONE

stores absolutely all the contour points. That is, any 2 subsequent points (x1,y1) and (x2,y2) of the contour will be either horizontal, vertical or diagonal neighbors, that is, max(abs(x1-x2),abs(y2-y1))==1.

CHAIN_APPROX_SIMPLE
Python: cv.CHAIN_APPROX_SIMPLE

compresses horizontal, vertical, and diagonal segments and leaves only their end points. For example, an up-right rectangular contour is encoded with 4 points.

CHAIN_APPROX_TC89_L1
Python: cv.CHAIN_APPROX_TC89_L1

applies one of the flavors of the Teh-Chin chain approximation algorithm [300]

CHAIN_APPROX_TC89_KCOS
Python: cv.CHAIN_APPROX_TC89_KCOS

applies one of the flavors of the Teh-Chin chain approximation algorithm [300]

LINK_RUNS
Python: cv.LINK_RUNS

TBD

RetrievalModes#

enum cv::RetrievalModes

#include <opencv2/imgproc.hpp>

mode of the contour retrieval algorithm

Enumerator:

RETR_EXTERNAL
Python: cv.RETR_EXTERNAL

retrieves only the extreme outer contours. It sets hierarchy[i][2]=hierarchy[i][3]=-1 for all the contours.

RETR_LIST
Python: cv.RETR_LIST

retrieves all of the contours without establishing any hierarchical relationships.

RETR_CCOMP
Python: cv.RETR_CCOMP

retrieves all of the contours and organizes them into a two-level hierarchy. At the top level, there are external boundaries of the components. At the second level, there are boundaries of the holes. If there is another contour inside a hole of a connected component, it is still put at the top level.

RETR_TREE
Python: cv.RETR_TREE

retrieves all of the contours and reconstructs a full hierarchy of nested contours.

RETR_FLOODFILL
Python: cv.RETR_FLOODFILL

ShapeMatchModes#

enum cv::ShapeMatchModes

#include <opencv2/imgproc.hpp>

Shape matching methods.

\(A\) denotes object1, \(B\) denotes object2

\(\begin{array}{l} m^A_i = \mathrm{sign} (h^A_i) \cdot \log{h^A_i} \\ m^B_i = \mathrm{sign} (h^B_i) \cdot \log{h^B_i} \end{array}\)

and \(h^A_i, h^B_i\) are the Hu moments of \(A\) and \(B\) , respectively.

Enumerator:

CONTOURS_MATCH_I1
Python: cv.CONTOURS_MATCH_I1
\[ I_1(A,B) = \sum _{i=1...7} \left | \frac{1}{m^A_i} - \frac{1}{m^B_i} \right | \]

CONTOURS_MATCH_I2
Python: cv.CONTOURS_MATCH_I2
\[ I_2(A,B) = \sum _{i=1...7} \left | m^A_i - m^B_i \right | \]

CONTOURS_MATCH_I3
Python: cv.CONTOURS_MATCH_I3
\[ I_3(A,B) = \max _{i=1...7} \frac{ \left| m^A_i - m^B_i \right| }{ \left| m^A_i \right| } \]

Function Documentation#

connectedComponents()#

int cv::connectedComponents(
InputArray image,
OutputArray labels,
int connectivity,
int ltype,
int ccltype )

#include <opencv2/imgproc.hpp>

Python:

cv.connectedComponents(image[, labels[, connectivity[, ltype]]]) -> retval, labels

cv.connectedComponentsWithAlgorithm(image, connectivity, ltype, ccltype[, labels]) -> retval, labels

computes the connected components labeled image of boolean image

image with 4 or 8 way connectivity - returns N, the total number of labels [0, N-1] where 0 represents the background label. ltype specifies the output label image type, an important consideration based on the total number of labels or alternatively the total number of pixels in the source image. ccltype specifies the connected components labeling algorithm to use, currently Bolelli (Spaghetti) [36], Grana (BBDT) [122] and Wu’s (SAUF) [337] algorithms are supported, see the ConnectedComponentsAlgorithmsTypes for details. Note that SAUF algorithm forces a row major ordering of labels while Spaghetti and BBDT do not. This function uses parallel version of the algorithms if at least one allowed parallel framework is enabled and if the rows of the image are at least twice the number returned by getNumberOfCPUs.

Parameters

  • image — the 8-bit single-channel image to be labeled

  • labels — destination labeled image

  • connectivity — 8 or 4 for 8-way or 4-way connectivity respectively

  • ltype — output image label type. Currently CV_32S and CV_16U are supported.

  • ccltype — connected components algorithm type (see the ConnectedComponentsAlgorithmsTypes).

connectedComponents()#

int cv::connectedComponents(
InputArray image,
OutputArray labels,
int connectivity = 8,
int ltype = CV_32S )

#include <opencv2/imgproc.hpp>

Python:

cv.connectedComponents(image[, labels[, connectivity[, ltype]]]) -> retval, labels

cv.connectedComponentsWithAlgorithm(image, connectivity, ltype, ccltype[, labels]) -> retval, labels

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

  • image — the 8-bit single-channel image to be labeled

  • labels — destination labeled image

  • connectivity — 8 or 4 for 8-way or 4-way connectivity respectively

  • ltype — output image label type. Currently CV_32S and CV_16U are supported.

connectedComponentsWithStats()#

int cv::connectedComponentsWithStats(
InputArray image,
OutputArray labels,
OutputArray stats,
OutputArray centroids,
int connectivity,
int ltype,
int ccltype )

#include <opencv2/imgproc.hpp>

Python:

cv.connectedComponentsWithStats(image[, labels[, stats[, centroids[, connectivity[, ltype]]]]]) -> retval, labels, stats, centroids

cv.connectedComponentsWithStatsWithAlgorithm(image, connectivity, ltype, ccltype[, labels[, stats[, centroids]]]) -> retval, labels, stats, centroids

computes the connected components labeled image of boolean image and also produces a statistics output for each label

image with 4 or 8 way connectivity - returns N, the total number of labels [0, N-1] where 0 represents the background label. ltype specifies the output label image type, an important consideration based on the total number of labels or alternatively the total number of pixels in the source image. ccltype specifies the connected components labeling algorithm to use, currently Bolelli (Spaghetti) [36], Grana (BBDT) [122] and Wu’s (SAUF) [337] algorithms are supported, see the ConnectedComponentsAlgorithmsTypes for details. Note that SAUF algorithm forces a row major ordering of labels while Spaghetti and BBDT do not. This function uses parallel version of the algorithms (statistics included) if at least one allowed parallel framework is enabled and if the rows of the image are at least twice the number returned by getNumberOfCPUs.

Parameters

  • image — the 8-bit single-channel image to be labeled

  • labels — destination labeled image

  • stats — statistics output for each label, including the background label. Statistics are accessed via stats(label, COLUMN) where COLUMN is one of ConnectedComponentsTypes, selecting the statistic. The data type is CV_32S.

  • centroids — centroid output for each label, including the background label. Centroids are accessed via centroids(label, 0) for x and centroids(label, 1) for y. The data type CV_64F.

  • connectivity — 8 or 4 for 8-way or 4-way connectivity respectively

  • ltype — output image label type. Currently CV_32S and CV_16U are supported.

  • ccltype — connected components algorithm type (see ConnectedComponentsAlgorithmsTypes).

connectedComponentsWithStats()#

int cv::connectedComponentsWithStats(
InputArray image,
OutputArray labels,
OutputArray stats,
OutputArray centroids,
int connectivity = 8,
int ltype = CV_32S )

#include <opencv2/imgproc.hpp>

Python:

cv.connectedComponentsWithStats(image[, labels[, stats[, centroids[, connectivity[, ltype]]]]]) -> retval, labels, stats, centroids

cv.connectedComponentsWithStatsWithAlgorithm(image, connectivity, ltype, ccltype[, labels[, stats[, centroids]]]) -> retval, labels, stats, centroids

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

  • image — the 8-bit single-channel image to be labeled

  • labels — destination labeled image

  • stats — statistics output for each label, including the background label. Statistics are accessed via stats(label, COLUMN) where COLUMN is one of ConnectedComponentsTypes, selecting the statistic. The data type is CV_32S.

  • centroids — centroid output for each label, including the background label. Centroids are accessed via centroids(label, 0) for x and centroids(label, 1) for y. The data type CV_64F.

  • connectivity — 8 or 4 for 8-way or 4-way connectivity respectively

  • ltype — output image label type. Currently CV_32S and CV_16U are supported.

createGeneralizedHoughBallard()#

Ptr< GeneralizedHoughBallard > cv::createGeneralizedHoughBallard()

#include <opencv2/imgproc.hpp>

Python:

cv.createGeneralizedHoughBallard() -> retval

Creates a smart pointer to a cv::GeneralizedHoughBallard class and initializes it.

createGeneralizedHoughGuil()#

Ptr< GeneralizedHoughGuil > cv::createGeneralizedHoughGuil()

#include <opencv2/imgproc.hpp>

Python:

cv.createGeneralizedHoughGuil() -> retval

Creates a smart pointer to a cv::GeneralizedHoughGuil class and initializes it.

findContours()#

void cv::findContours(
InputArray image,
OutputArrayOfArrays contours,
int mode,
int method,
Point offset = Point() )

#include <opencv2/imgproc.hpp>

Python:

cv.findContours(image, mode, method[, contours[, hierarchy[, offset]]]) -> contours, hierarchy

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

findContours()#

void cv::findContours(
InputArray image,
OutputArrayOfArrays contours,
OutputArray hierarchy,
int mode,
int method,
Point offset = Point() )

#include <opencv2/imgproc.hpp>

Python:

cv.findContours(image, mode, method[, contours[, hierarchy[, offset]]]) -> contours, hierarchy

Finds contours in a binary image.

The function retrieves contours from the binary image. The contours are a useful tool for shape analysis and object detection and recognition. See squares.cpp in the OpenCV sample directory.

Note

Since OpenCV 4.14, when mode is RETR_LIST and no hierarchy is requested, this function automatically uses the TRUCO parallel algorithm [224], a scalable lock-free method for contour extraction. In all other cases, the sequential [287] algorithm is used.

Since opencv 3.2 source image is not modified by this function.

In Python, hierarchy is nested inside a top level array. Use hierarchy[0][i] to access hierarchical elements of i-th contour.

Parameters

  • image — Source, an 8-bit single-channel image. Non-zero pixels are treated as 1’s. Zero pixels remain 0’s, so the image is treated as binary . You can use compare, inRange, threshold , adaptiveThreshold, Canny, and others to create a binary image out of a grayscale or color one. If mode equals to RETR_CCOMP or RETR_FLOODFILL, the input can also be a 32-bit integer image of labels (CV_32SC1).

  • contours — Detected contours. Each contour is stored as a vector of points (e.g. std::vector<std::vector<cv::Point> >).

  • hierarchy — Optional output vector (e.g. std::vector<cv::Vec4i>), containing information about the image topology. It has as many elements as the number of contours. For each i-th contour contours[i], the elements hierarchy[i][0] , hierarchy[i][1] , hierarchy[i][2] , and hierarchy[i][3] are set to 0-based indices in contours of the next and previous contours at the same hierarchical level, the first child contour and the parent contour, respectively. If for the contour i there are no next, previous, parent, or nested contours, the corresponding elements of hierarchy[i] will be negative.

  • mode — Contour retrieval mode, see RetrievalModes

  • method — Contour approximation method, see ContourApproximationModes

  • offset — Optional offset by which every contour point is shifted. This is useful if the contours are extracted from the image ROI and then they should be analyzed in the whole image context.

findContoursLinkRuns()#

void cv::findContoursLinkRuns(
InputArray image,
OutputArrayOfArrays contours )

#include <opencv2/imgproc.hpp>

Python:

cv.findContoursLinkRuns(image[, contours[, hierarchy]]) -> contours, hierarchy

cv.findContoursLinkRuns(image[, contours]) -> contours

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

findContoursLinkRuns()#

void cv::findContoursLinkRuns(
InputArray image,
OutputArrayOfArrays contours,
OutputArray hierarchy )

#include <opencv2/imgproc.hpp>

Python:

cv.findContoursLinkRuns(image[, contours[, hierarchy]]) -> contours, hierarchy

cv.findContoursLinkRuns(image[, contours]) -> contours

Find contours using link runs algorithm.

This function implements an algorithm different from cv::findContours:

  • doesn’t allocate temporary image internally, thus it has reduced memory consumption

  • supports CV_8UC1 images only

  • outputs 2-level hierarhy only (RETR_CCOMP mode)

  • doesn’t support approximation change other than CHAIN_APPROX_SIMPLE In all other aspects this function is compatible with cv::findContours.