Structural Analysis and Shape Descriptors

Detailed Description

Namespaces
namespace	cv::traits

Classes
class	cv::GeneralizedHough
	finds arbitrary template in the grayscale image using Generalized Hough Transform More...
class	cv::GeneralizedHoughBallard
	finds arbitrary template in the grayscale image using Generalized Hough Transform More...
class	cv::GeneralizedHoughGuil
	finds arbitrary template in the grayscale image using Generalized Hough Transform More...
class	cv::Moments
	struct returned by cv::moments More...

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 More...
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 More...
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 More...
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 More...
enum	cv::ShapeMatchModes {   cv::CONTOURS_MATCH_I1 =1 ,   cv::CONTOURS_MATCH_I2 =2 ,   cv::CONTOURS_MATCH_I3 =3 }
	Shape matching methods. More...

Functions
int	cv::connectedComponents (InputArray image, OutputArray labels, int connectivity, int ltype, int ccltype)
	computes the connected components labeled image of boolean image
int	cv::connectedComponents (InputArray image, OutputArray labels, int connectivity=8, int ltype=CV_32S)
int	cv::connectedComponentsWithStats (InputArray image, OutputArray labels, OutputArray stats, OutputArray centroids, int connectivity, int ltype, int ccltype)
	computes the connected components labeled image of boolean image and also produces a statistics output for each label
int	cv::connectedComponentsWithStats (InputArray image, OutputArray labels, OutputArray stats, OutputArray centroids, int connectivity=8, int ltype=CV_32S)
Ptr< GeneralizedHoughBallard >	cv::createGeneralizedHoughBallard ()
	Creates a smart pointer to a cv::GeneralizedHoughBallard class and initializes it.
Ptr< GeneralizedHoughGuil >	cv::createGeneralizedHoughGuil ()
	Creates a smart pointer to a cv::GeneralizedHoughGuil class and initializes it.
void	cv::findContours (InputArray image, OutputArrayOfArrays contours, int mode, int method, Point offset=Point())
void	cv::findContours (InputArray image, OutputArrayOfArrays contours, OutputArray hierarchy, int mode, int method, Point offset=Point())
	Finds contours in a binary image.
void	cv::findContoursLinkRuns (InputArray image, OutputArrayOfArrays contours)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void	cv::findContoursLinkRuns (InputArray image, OutputArrayOfArrays contours, OutputArray hierarchy)
	Find contours using link runs algorithm.

Enumeration Type Documentation

ConnectedComponentsAlgorithmsTypes

enum cv::ConnectedComponentsAlgorithmsTypes

#include <opencv2/imgproc.hpp>

connected components algorithm

Enumerator
CCL_DEFAULT  Python: cv.CCL_DEFAULT	Spaghetti [Bolelli2019] algorithm for 8-way connectivity, Spaghetti4C [Bolelli2021] algorithm for 4-way connectivity.
CCL_WU  Python: cv.CCL_WU	SAUF [Wu2009] algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity. The parallel implementation described in [Bolelli2017] is available for SAUF.
CCL_GRANA  Python: cv.CCL_GRANA	BBDT [Grana2010] algorithm for 8-way connectivity, SAUF algorithm for 4-way connectivity. The parallel implementation described in [Bolelli2017] is available for both BBDT and SAUF.
CCL_BOLELLI  Python: cv.CCL_BOLELLI	Spaghetti [Bolelli2019] algorithm for 8-way connectivity, Spaghetti4C [Bolelli2021] algorithm for 4-way connectivity. The parallel implementation described in [Bolelli2017] 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 [TehChin89]
CHAIN_APPROX_TC89_KCOS  Python: cv.CHAIN_APPROX_TC89_KCOS	applies one of the flavors of the Teh-Chin chain approximation algorithm [TehChin89]
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() [1/2]

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

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

#include <opencv2/imgproc.hpp>

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) [Bolelli2019], Grana (BBDT) [Grana2010] and Wu's (SAUF) [Wu2009] 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).

Examples

samples/cpp/connected_components.cpp.

connectedComponents() [2/2]

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

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

#include <opencv2/imgproc.hpp>

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() [1/2]

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

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

#include <opencv2/imgproc.hpp>

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) [Bolelli2019], Grana (BBDT) [Grana2010] and Wu's (SAUF) [Wu2009] 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() [2/2]

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

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

#include <opencv2/imgproc.hpp>

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

(

)

Python:
	cv.createGeneralizedHoughBallard(		) ->	retval

#include <opencv2/imgproc.hpp>

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

createGeneralizedHoughGuil()

Ptr< GeneralizedHoughGuil > cv::createGeneralizedHoughGuil

(

)

Python:
	cv.createGeneralizedHoughGuil(		) ->	retval

#include <opencv2/imgproc.hpp>

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

findContours() [1/2]

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

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

#include <opencv2/imgproc.hpp>

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

findContours() [2/2]

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

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

#include <opencv2/imgproc.hpp>

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 [TRUCO2026], a scalable lock-free method for contour extraction. In all other cases, the sequential [Suzuki85] algorithm is used.

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

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.

Note

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

Parameters

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.

Examples

modules/shape/samples/shape_example.cpp, samples/cpp/geometry.cpp, samples/cpp/snippets/segment_objects.cpp, samples/cpp/snippets/watershed.cpp, and samples/cpp/tutorial_code/ml/introduction_to_pca/introduction_to_pca.cpp.

findContoursLinkRuns() [1/2]

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

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

#include <opencv2/imgproc.hpp>

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

findContoursLinkRuns() [2/2]

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

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

#include <opencv2/imgproc.hpp>

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.