Visual Servoing Platform  version 3.5.1 under development (2023-09-22)

#include <visp3/imgproc/vpCircleHoughTransform.h>

Classes

class  vpCircleHoughTransformParameters
 

Public Member Functions

 vpCircleHoughTransform ()
 
 vpCircleHoughTransform (const vpCircleHoughTransformParameters &algoParams)
 
virtual ~vpCircleHoughTransform ()
 
std::vector< vpImageCircledetect (const vpImage< vpRGBa > &I)
 
std::vector< vpImageCircledetect (const vpImage< unsigned char > &I)
 
std::vector< vpImageCircledetect (const vpImage< unsigned char > &I, const int &nbCircles)
 
 vpCircleHoughTransform (const std::string &jsonPath)
 
void initFromJSON (const std::string &jsonPath)
 
void saveConfigurationInJSON (const std::string &jsonPath) const
 
void init (const vpCircleHoughTransformParameters &algoParams)
 
void setGaussianParameters (const int &kernelSize, const float &stdev)
 
void setCannyThreshold (const float &lowerCannyThreshold, const float &upperCannyThreshold)
 
void setCircleCenterMinDist (const float &center_min_dist)
 
void setCircleCenterBoundingBox (const int &center_min_x, const int &center_max_x, const int &center_min_y, const int &center_max_y)
 
void setCircleMinRadius (const float &circle_min_radius)
 
void setCircleMaxRadius (const float &circle_max_radius)
 
void setCirclePerfectness (const float &circle_perfectness)
 
void setCenterComputationParameters (const int &dilatationRepet, const float &centerThresh)
 
void setRadiusRatioThreshold (const float &radiusRatioThresh)
 
void setRadiusMergingThresholds (const float &radiusDifferenceThresh)
 
std::vector< std::pair< int, int > > getCenterCandidatesList ()
 
std::vector< int > getCenterCandidatesVotes ()
 
std::vector< vpImageCirclegetCircleCandidates ()
 
std::vector< unsigned int > getCircleCandidatesVotes ()
 
vpImage< float > getGradientX ()
 
vpImage< float > getGradientY ()
 
vpImage< unsigned char > getEdgeMap ()
 
float getCannyThreshold () const
 
float getCircleCenterMinDist () const
 
unsigned int getCircleMinRadius () const
 
unsigned int getCircleMaxRadius () const
 
std::string toString () const
 

Friends

void from_json (const json &j, vpCircleHoughTransform &detector)
 
void to_json (json &j, const vpCircleHoughTransform &detector)
 
VISP_EXPORT std::ostream & operator<< (std::ostream &os, const vpCircleHoughTransform &detector)
 

Detailed Description

Class that permits to detect 2D circles in a image using the gradient-based Circle Hough transform. Please find more information on the algorithm here

Definition at line 66 of file vpCircleHoughTransform.h.

Constructor & Destructor Documentation

◆ vpCircleHoughTransform() [1/3]

vpCircleHoughTransform::vpCircleHoughTransform ( )

Construct a new vpCircleHoughTransform object with default parameters.

Definition at line 38 of file vpCircleHoughTransform.cpp.

◆ vpCircleHoughTransform() [2/3]

vpCircleHoughTransform::vpCircleHoughTransform ( const vpCircleHoughTransformParameters algoParams)

Construct a new vpCircleHoughTransform object from a vpCircleHoughTransformParameters object.

Parameters
[in]algoParamsThe parameters of the Circle Hough Transform.

Definition at line 44 of file vpCircleHoughTransform.cpp.

◆ ~vpCircleHoughTransform()

vpCircleHoughTransform::~vpCircleHoughTransform ( )
virtual

Destroy the vp Circle Hough Transform object.

Definition at line 57 of file vpCircleHoughTransform.cpp.

◆ vpCircleHoughTransform() [3/3]

vpCircleHoughTransform::vpCircleHoughTransform ( const std::string &  jsonPath)

Construct a new vpCircleHoughTransform object configured according to the JSON file whose path is jsonPath. Throw a vpException error if the file does not exist.

Parameters
[in]jsonPathThe path towards the JSON configuration file.

Definition at line 61 of file vpCircleHoughTransform.cpp.

References initFromJSON().

Member Function Documentation

◆ detect() [1/3]

std::vector< vpImageCircle > vpCircleHoughTransform::detect ( const vpImage< unsigned char > &  I)

Perform Circle Hough Transform to detect the circles in a gray-scale image.

Parameters
[in]IThe input gray scale image.
Returns
std::vector<vpImageCircle> The list of 2D circles detected in the image.

Definition at line 162 of file vpCircleHoughTransform.cpp.

◆ detect() [2/3]

std::vector< vpImageCircle > vpCircleHoughTransform::detect ( const vpImage< unsigned char > &  I,
const int &  nbCircles 
)

Perform Circle Hough Transform to detect the circles in in a gray-scale image. Get only the nbCircles circles having the greatest number of votes.

Parameters
[in]IThe input gray scale image.
[in]nbCirclesThe number of circles we want to get. If negative, all the circles will be returned, sorted such as result[0] has the highest number of votes and result[end -1] the lowest.
Returns
std::vector<vpImageCircle> The list of 2D circles with the most number of votes detected in the image.

Definition at line 128 of file vpCircleHoughTransform.cpp.

References detect().

◆ detect() [3/3]

std::vector< vpImageCircle > vpCircleHoughTransform::detect ( const vpImage< vpRGBa > &  I)

Convert the input image in a gray-scale image and then perform Circle Hough Transform to detect the circles in it.

Parameters
[in]IThe input color image.
Returns
std::vector<vpImageCircle> The list of 2D circles detected in the image.

Definition at line 110 of file vpCircleHoughTransform.cpp.

References vpImageConvert::convert().

Referenced by detect().

◆ getCannyThreshold()

float vpCircleHoughTransform::getCannyThreshold ( ) const
inline

Get internal Canny filter upper threshold. When value is equal to -1 (default), it means that the threshold is computed automatically.

Definition at line 698 of file vpCircleHoughTransform.h.

◆ getCenterCandidatesList()

std::vector<std::pair<int, int> > vpCircleHoughTransform::getCenterCandidatesList ( )
inline

Get the list of Center Candidates, stored as pair <idRow, idCol>

Returns
std::vector<std::pair<unsigned int, unsigned int> > The list of Center Candidates, stored as pair <idRow, idCol>

Definition at line 628 of file vpCircleHoughTransform.h.

◆ getCenterCandidatesVotes()

std::vector<int> vpCircleHoughTransform::getCenterCandidatesVotes ( )
inline

Get the number of votes of each Center Candidates.

Returns
std::vector<int> The number of votes of each Center Candidates, ordered in the same way than m_centerCandidatesList.

Definition at line 638 of file vpCircleHoughTransform.h.

◆ getCircleCandidates()

std::vector<vpImageCircle> vpCircleHoughTransform::getCircleCandidates ( )
inline

Get the Circle Candidates before merging step.

Returns
std::vector<vpImageCircle> The list of circle candidates that were obtained before the merging step.

Definition at line 649 of file vpCircleHoughTransform.h.

◆ getCircleCandidatesVotes()

std::vector<unsigned int> vpCircleHoughTransform::getCircleCandidatesVotes ( )
inline

Get the votes accumulator of the Circle Candidates.

Returns
std::vector<unsigned int> The votes accumulator.

Definition at line 659 of file vpCircleHoughTransform.h.

◆ getCircleCenterMinDist()

float vpCircleHoughTransform::getCircleCenterMinDist ( ) const
inline

Get circles center min distance in pixels.

Definition at line 706 of file vpCircleHoughTransform.h.

◆ getCircleMaxRadius()

unsigned int vpCircleHoughTransform::getCircleMaxRadius ( ) const
inline

Get circles max radius in pixels.

Definition at line 722 of file vpCircleHoughTransform.h.

◆ getCircleMinRadius()

unsigned int vpCircleHoughTransform::getCircleMinRadius ( ) const
inline

Get circles min radius in pixels.

Definition at line 714 of file vpCircleHoughTransform.h.

◆ getEdgeMap()

vpImage<unsigned char> vpCircleHoughTransform::getEdgeMap ( )
inline

Get the Edge Map computed thanks to the Canny edge filter.

Returns
vpImage<unsigned char> The edge map computed during the edge detection step.

Definition at line 689 of file vpCircleHoughTransform.h.

◆ getGradientX()

vpImage<float> vpCircleHoughTransform::getGradientX ( )
inline

Get the gradient along the horizontal axis of the image.

Returns
vpImage<float> The gradient along the horizontal axis of the image.

Definition at line 669 of file vpCircleHoughTransform.h.

◆ getGradientY()

vpImage<float> vpCircleHoughTransform::getGradientY ( )
inline

Get the gradient along the vertical axis of the image.

Returns
vpImage<float> The gradient along the vertical axis of the image.

Definition at line 679 of file vpCircleHoughTransform.h.

◆ init()

void vpCircleHoughTransform::init ( const vpCircleHoughTransformParameters algoParams)

Initialize all the algorithm parameters.

Parameters
[in]algoParamsThe algorithm parameters.

Definition at line 51 of file vpCircleHoughTransform.cpp.

◆ initFromJSON()

void vpCircleHoughTransform::initFromJSON ( const std::string &  jsonPath)

Initialize all the algorithm parameters using the JSON file whose path is jsonPath. Throw a vpException error if the file does not exist.

Parameters
[in]jsonPathThe path towards the JSON configuration file.

Definition at line 67 of file vpCircleHoughTransform.cpp.

References vpException::ioError.

Referenced by vpCircleHoughTransform().

◆ saveConfigurationInJSON()

void vpCircleHoughTransform::saveConfigurationInJSON ( const std::string &  jsonPath) const

Save the configuration of the detector in a JSON file described by the path jsonPath. Throw a vpException is the file cannot be created.

Parameters
[in]jsonPathThe path towards the JSON output file.

Definition at line 93 of file vpCircleHoughTransform.cpp.

References vpCircleHoughTransform::vpCircleHoughTransformParameters::saveConfigurationInJSON().

◆ setCannyThreshold()

void vpCircleHoughTransform::setCannyThreshold ( const float &  lowerCannyThreshold,
const float &  upperCannyThreshold 
)
inline

Set the threshold for the Canny operator. Only value greater than this value are marked as an edge. If negative, the threshold is automatically computed.

Parameters
[in]lowerCannyThreshold: Canny filter lower threshold. When set to -1 (default), compute automatically this threshold.
[in]upperCannyThreshold: Canny filter upper threshold. When set to -1 (default), compute automatically this threshold.

Definition at line 504 of file vpCircleHoughTransform.h.

◆ setCenterComputationParameters()

void vpCircleHoughTransform::setCenterComputationParameters ( const int &  dilatationRepet,
const float &  centerThresh 
)
inline

Set the parameters of the computation of the circle center candidates.

Parameters
[in]dilatationRepetNumber of repetition of the dilatation operation to detect the maxima in the center accumulator.
[in]centerThreshMinimum number of votes a point must exceed to be considered as center candidate.

Definition at line 582 of file vpCircleHoughTransform.h.

References vpException::badValue.

◆ setCircleCenterBoundingBox()

void vpCircleHoughTransform::setCircleCenterBoundingBox ( const int &  center_min_x,
const int &  center_max_x,
const int &  center_min_y,
const int &  center_max_y 
)
inline

Set circles center min and max location in the image. If one value is equal to std::numeric_limits<int>::min or std::numeric_limits<int>::max(), the algorithm will set it either to -maxRadius or +maxRadius depending on if it is the lower or upper limit that is missing.

Parameters
[in]center_min_x: Center min location on the horizontal axis, expressed in pixels.
[in]center_max_x: Center max location on the horizontal axis, expressed in pixels.
[in]center_min_y: Center min location on the vertical axis, expressed in pixels.
[in]center_max_y: Center max location on the vertical axis, expressed in pixels.

Definition at line 537 of file vpCircleHoughTransform.h.

◆ setCircleCenterMinDist()

void vpCircleHoughTransform::setCircleCenterMinDist ( const float &  center_min_dist)
inline

Set circles center min distance. Change this value to detect circles with different distances to each other.

Parameters
[in]center_min_dist: Center min distance in pixels.

Definition at line 516 of file vpCircleHoughTransform.h.

References vpException::badValue.

◆ setCircleMaxRadius()

void vpCircleHoughTransform::setCircleMaxRadius ( const float &  circle_max_radius)
inline

Set circles max radius.

Parameters
[in]circle_max_radius: Max radius in pixels.

Definition at line 559 of file vpCircleHoughTransform.h.

◆ setCircleMinRadius()

void vpCircleHoughTransform::setCircleMinRadius ( const float &  circle_min_radius)
inline

Set circles min radius.

Parameters
[in]circle_min_radius: Min radius in pixels.

Definition at line 550 of file vpCircleHoughTransform.h.

◆ setCirclePerfectness()

void vpCircleHoughTransform::setCirclePerfectness ( const float &  circle_perfectness)
inline

Set circles perfectness. The scalar product radius RC_ij . gradient(Ep_j) >= m_circlePerfectness * || RC_ij || * || gradient(Ep_j) || to add a vote for the radius RC_ij.

Parameters
[in]circle_perfectness: Circle perfectness. Value between 0 and 1. A perfect circle has value 1.

Definition at line 568 of file vpCircleHoughTransform.h.

References vpException::badValue.

◆ setGaussianParameters()

void vpCircleHoughTransform::setGaussianParameters ( const int &  kernelSize,
const float &  stdev 
)
inline

Set the parameters of the Gaussian filter, that computes the gradients of the image.

Parameters
[in]kernelSizeThe size of the Gaussian kernel. Must be an odd value.
[in]stdevThe standard deviation of the Gaussian function.

Definition at line 479 of file vpCircleHoughTransform.h.

References vpException::badValue.

◆ setRadiusMergingThresholds()

void vpCircleHoughTransform::setRadiusMergingThresholds ( const float &  radiusDifferenceThresh)
inline

Set the radius merging threshold used during the merging step in order to merge the circles that are similar.

Parameters
[in]radiusDifferenceThreshMaximum radius difference between two circle candidates to consider merging them.

Definition at line 612 of file vpCircleHoughTransform.h.

References vpException::badValue.

◆ setRadiusRatioThreshold()

void vpCircleHoughTransform::setRadiusRatioThreshold ( const float &  radiusRatioThresh)
inline

Set the parameters of the computation of the circle radius candidates.

Parameters
[in]radiusRatioThreshMinimum number of votes per radian a radius candidate RC_ij of a center candidate CeC_i must have in order that the circle of center CeC_i and radius RC_ij must be considered as circle candidate.

Definition at line 597 of file vpCircleHoughTransform.h.

References vpException::badValue.

◆ toString()

std::string vpCircleHoughTransform::toString ( ) const

Create a string with all Hough transform parameters.

Definition at line 574 of file vpCircleHoughTransform.cpp.

References vpCircleHoughTransform::vpCircleHoughTransformParameters::toString().

Friends And Related Function Documentation

◆ from_json

void from_json ( const json &  j,
vpCircleHoughTransform detector 
)
friend

Read the detector configuration from JSON. All values are optional and if an argument is not present, the default value defined in the constructor is kept.

Parameters
[in]jThe JSON object, resulting from the parsing of a JSON file.
[out]detectorThe detector, that will be initialized from the JSON data.

Definition at line 447 of file vpCircleHoughTransform.h.

◆ operator<<

VISP_EXPORT std::ostream& operator<< ( std::ostream &  os,
const vpCircleHoughTransform detector 
)
friend

Create a ostream with all Hough transform parameters.

Definition at line 579 of file vpCircleHoughTransform.cpp.

◆ to_json

void to_json ( json &  j,
const vpCircleHoughTransform detector 
)
friend

Parse a vpCircleHoughTransform into JSON format.

Parameters
[out]jA JSON parser object.
[in]detectorThe vpCircleHoughTransform that must be parsed into JSON format.

Definition at line 458 of file vpCircleHoughTransform.h.