Visual Servoing Platform version 3.7.0
Loading...
Searching...
No Matches
vpCircleHoughTransform Class Reference
imgproc: Image processing module » Hough-transform-based image detection

#include <vpCircleHoughTransform.h>

Classes

class  vpCircleHoughTransformParams

Public Types

typedef vpCircleHoughTransformParams vpCircleHoughTransformParameters

Public Member Functions

 vpCircleHoughTransform ()
VP_EXPLICIT vpCircleHoughTransform (const vpCircleHoughTransformParams &algoParams)
virtual ~vpCircleHoughTransform ()
Detection methods
virtual std::vector< vpImageCircle > detect (const vpImage< vpRGBa > &I)
virtual std::vector< vpImageCircle > detect (const vpImage< unsigned char > &I)
virtual std::vector< vpImageCircle > detect (const vpImage< unsigned char > &I, const int &nbCircles)
void computeVotingMask (const vpImage< unsigned char > &I, const std::vector< vpImageCircle > &detections, std::optional< vpImage< bool > > &mask, std::optional< std::vector< std::vector< std::pair< unsigned int, unsigned int > > > > &opt_votingPoints) const
Setters
void init (const vpCircleHoughTransformParams &algoParams)
void setFilteringAndGradientType (const vpImageFilter::vpCannyFilteringAndGradientType &type)
void setGaussianParameters (const int &kernelSize, const float &stdev)
void setGradientFilterAperture (const unsigned int &apertureSize)
void setCannyBackend (const vpImageFilter::vpCannyBackendType &type)
void setCannyThreshold (const float &lowerCannyThreshold, const float &upperCannyThreshold)
void setCannyThresholdRatio (const float &lowerThreshRatio, const float &upperThreshRatio)
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 &dilatationSize, const float &centerThresh, const int &averagingWindowSize=5, const int expectedNbCenters=-1)
void setRadiusRatioThreshold (const float &radiusRatioThresh)
void setRadiusMergingThresholds (const float &radiusDifferenceThresh)
void setMask (const vpImage< bool > &mask)
void setMask (const vpImage< bool > *mask)
void setRecordVotingPoints (const bool &record)

Getters

static const unsigned char edgeMapOn = 255
static const unsigned char edgeMapOff = 0
vpCircleHoughTransformParams m_algoParams
vpArray2D< float > m_fg
const vpImage< bool > * mp_mask
vpArray2D< float > m_gradientFilterX
vpArray2D< float > m_gradientFilterY
vpImage< float > m_dIx
vpImage< float > m_dIy
vpCannyEdgeDetection m_cannyVisp
vpImage< unsigned char > m_edgeMap
std::vector< std::pair< unsigned int, unsigned int > > m_edgePointsList
std::vector< std::pair< float, float > > m_centerCandidatesList
std::vector< int > m_centerVotes
std::vector< vpImageCircle > m_circleCandidates
std::vector< float > m_circleCandidatesProbabilities
std::vector< unsigned int > m_circleCandidatesVotes
std::vector< std::vector< std::pair< unsigned int, unsigned int > > > m_circleCandidatesVotingPoints
std::vector< vpImageCircle > m_finalCircles
std::vector< float > m_finalCirclesProbabilities
std::vector< unsigned int > m_finalCircleVotes
std::vector< std::vector< std::pair< unsigned int, unsigned int > > > m_finalCirclesVotingPoints
std::vector< std::pair< float, float > > getCenterCandidatesList () const
std::vector< int > getCenterCandidatesVotes () const
std::vector< vpImageCircle > getCircleCandidates () const
std::vector< float > getCircleCandidatesProbabilities () const
std::vector< unsigned int > getCircleCandidatesVotes () const
vpImage< float > getGradientX () const
vpImage< float > getGradientY () const
vpImage< unsigned char > getEdgeMap () const
float getCannyThreshold () const
float getCircleCenterMinDist () const
float getCircleMinRadius () const
float getCircleMaxRadius () const
std::vector< float > getDetectionsProbabilities () const
std::vector< unsigned int > getDetectionsVotes () const
std::vector< std::vector< std::pair< unsigned int, unsigned int > > > getDetectionsVotingPoints () const
bool getRecordVotingPoints () const
std::string toString () const
VISP_EXPORT std::ostream & operator<< (std::ostream &os, const vpCircleHoughTransform &detector)
virtual void initGaussianFilters ()
virtual void initGradientFilters ()
virtual void computeGradients (const vpImage< unsigned char > &I)
virtual void edgeDetection (const vpImage< unsigned char > &I)
virtual void filterEdgeMap ()
virtual void computeCenterCandidates ()
void updateAccumulator (const vpCoordinatesForAccumStep &coord, const vpDataForAccumLoop &data, vpImage< float > &accum, bool &hasToStop)
void updateAccumAlongGradientDir (const vpDataForAccumLoop &data, float &sx, float &sy, vpImage< float > &centersAccum)
virtual void workOnAccumulator (vpDataForAccumLoop &data, vpImage< float > &centersAccum)
virtual void filterCenterCandidates (const std::vector< vpCenterVotes > &peak_positions_votes)
virtual vpCentersBarycenter mergeSimilarCenters (const unsigned int &idPeak, const unsigned int &nbPeaks, const float &squared_distance_max, const std::vector< vpCenterVotes > &peak_positions_votes, std::vector< bool > &has_been_merged)
virtual float computeCircleProbability (const vpImageCircle &circle, const unsigned int &nbVotes)
virtual void computeCircleCandidates ()
virtual void mergeCircleCandidates ()
virtual void mergeCandidates (std::vector< vpImageCircle > &circleCandidates, std::vector< unsigned int > &circleCandidatesVotes, std::vector< float > &circleCandidatesProba, std::vector< std::vector< std::pair< unsigned int, unsigned int > > > &votingPoints)

Configuration from files

VP_EXPLICIT vpCircleHoughTransform (const std::string &jsonPath)
virtual void initFromJSON (const std::string &jsonPath)
virtual void saveConfigurationInJSON (const std::string &jsonPath) const
void from_json (const nlohmann::json &j, vpCircleHoughTransform &detector)
void to_json (nlohmann::json &j, 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.

Examples
tutorial-circle-hough.cpp.

Definition at line 64 of file vpCircleHoughTransform.h.

Member Typedef Documentation

◆ vpCircleHoughTransformParameters

typedef vpCircleHoughTransformParams vpCircleHoughTransform::vpCircleHoughTransformParameters

Definition at line 668 of file vpCircleHoughTransform.h.

Constructor & Destructor Documentation

◆ vpCircleHoughTransform() [1/3]

BEGIN_VISP_NAMESPACE vpCircleHoughTransform::vpCircleHoughTransform ( )

Construct a new vpCircleHoughTransform object with default parameters.

Definition at line 63 of file vpCircleHoughTransform_common.cpp.

References initGaussianFilters(), initGradientFilters(), m_algoParams, and mp_mask.

Referenced by from_json, operator<<, and to_json.

◆ vpCircleHoughTransform() [2/3]

vpCircleHoughTransform::vpCircleHoughTransform ( const vpCircleHoughTransformParams & algoParams)

Construct a new vpCircleHoughTransform object from a vpCircleHoughTransformParams object.

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

Definition at line 71 of file vpCircleHoughTransform_common.cpp.

References initGaussianFilters(), initGradientFilters(), m_algoParams, and mp_mask.

◆ ~vpCircleHoughTransform()

vpCircleHoughTransform::~vpCircleHoughTransform ( )
virtual

Destroy the vp Circle Hough Transform object.

Definition at line 87 of file vpCircleHoughTransform_common.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 93 of file vpCircleHoughTransform_common.cpp.

References initFromJSON(), and mp_mask.

Member Function Documentation

◆ computeCenterCandidates()

void vpCircleHoughTransform::computeCenterCandidates ( )
protectedvirtual

Determine the image points that are circle center candidates. Increment the center accumulator based on the edge points and gradient information. Perform thresholding to keep only the center candidates that exceed the threshold.

< Votes for the center candidates.

Definition at line 164 of file vpCircleHoughTransform_centers.cpp.

References vpException::badValue, vpImageFilter::CANNY_VISP_BACKEND, vpImageMorphology::dilatation(), vpException::dimensionError, edgeMapOn, vpMath::equal(), filterCenterCandidates(), vpImage< Type >::getCols(), vpImage< Type >::getRows(), m_algoParams, m_cannyVisp, m_edgeMap, m_edgePointsList, and workOnAccumulator().

Referenced by detect().

◆ computeCircleCandidates()

BEGIN_VISP_NAMESPACE void vpCircleHoughTransform::computeCircleCandidates ( )
protectedvirtual

For each center candidate CeC_i, do:

  • For each edge point EP_j, compute the distance d_ij = distance(CeC_i; EP_j)
  • Determine to which radius candidate bin RCB_k the distance d_ij belongs to
  • Increment the radius candidate accumulator accum_rc[CeC_i][RCB_k]
  • If accum_rc[CeC_i][RCB_k] > radius_count_thresh, add the circle candidate (CeC_i, RCB_k) to the list of circle candidates

Definition at line 135 of file vpCircleHoughTransform_circles.cpp.

References computeCircleProbability(), m_algoParams, m_centerCandidatesList, m_circleCandidates, m_circleCandidatesProbabilities, m_circleCandidatesVotes, m_circleCandidatesVotingPoints, m_dIx, m_dIy, and m_edgePointsList.

Referenced by detect().

◆ computeCircleProbability()

float vpCircleHoughTransform::computeCircleProbability ( const vpImageCircle & circle,
const unsigned int & nbVotes )
protectedvirtual

Compute the probability of circle given the number of pixels voting for it nbVotes. The probability is defined as the ratio of nbVotes by the theoretical number of pixel that should be visible in the image.

Parameters
[in]circleThe circle for which we want to evaluate the probability.
[in]nbVotesThe number of visible pixels of the given circle.
Returns
float The probability of the circle.

Definition at line 276 of file vpCircleHoughTransform_circles.cpp.

References vpImageCircle::computeArcLengthInRoI(), vpImageCircle::computePixelsInMask(), m_edgeMap, and mp_mask.

Referenced by computeCircleCandidates().

◆ computeGradients()

void vpCircleHoughTransform::computeGradients ( const vpImage< unsigned char > & I)
protectedvirtual

Perform Gaussian smoothing on the input image to reduce the noise that would perturbate the edge detection. Then, compute the x-gradient and y-gradient of the input images.

Parameters
[in]IThe input gray scale image.

Definition at line 57 of file vpCircleHoughTransform_centers.cpp.

References vpImageFilter::CANNY_GBLUR_SCHARR_FILTERING, vpImageFilter::CANNY_GBLUR_SOBEL_FILTERING, vpImageFilter::filter(), vpImageFilter::filterX(), vpImageFilter::filterY(), m_algoParams, m_dIx, m_dIy, m_fg, m_gradientFilterX, m_gradientFilterY, mp_mask, vpException::notImplementedError, and vpImageFilter::vpCannyFiltAndGradTypeToStr().

Referenced by detect().

◆ computeVotingMask()

void vpCircleHoughTransform::computeVotingMask ( const vpImage< unsigned char > & I,
const std::vector< vpImageCircle > & detections,
std::optional< vpImage< bool > > & mask,
std::optional< std::vector< std::vector< std::pair< unsigned int, unsigned int > > > > & opt_votingPoints ) const
inline

Compute the mask containing pixels that voted for the detections.

Parameters
[in]IThe image for which we want to have the information.
[in]detectionsVector containing the list of vpImageCircle for which we want to know the voting points.
[out]maskOptional mask where pixels to exclude have a value set to false.
[out]opt_votingPointsOptional vector of pairs of pixel coordinates that voted for the detections.
Examples
tutorial-circle-hough.cpp.

Definition at line 748 of file vpCircleHoughTransform.h.

References computeVotingMask(), m_algoParams, m_finalCircles, and m_finalCirclesVotingPoints.

Referenced by computeVotingMask().

◆ detect() [1/3]

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

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 262 of file vpCircleHoughTransform_common.cpp.

References computeCenterCandidates(), computeCircleCandidates(), computeGradients(), edgeDetection(), m_algoParams, m_centerCandidatesList, m_centerVotes, m_circleCandidates, m_circleCandidatesProbabilities, m_circleCandidatesVotes, m_circleCandidatesVotingPoints, m_edgePointsList, m_finalCircles, m_finalCirclesProbabilities, m_finalCirclesVotingPoints, m_finalCircleVotes, and mergeCircleCandidates().

Referenced by visp.python.rbt.xfeat.XFeatTrackingBackend.XFeatTrackingBackend::process_frame().

◆ detect() [2/3]

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

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 209 of file vpCircleHoughTransform_common.cpp.

References detect(), m_algoParams, m_finalCircles, m_finalCirclesProbabilities, m_finalCirclesVotingPoints, and m_finalCircleVotes.

Referenced by visp.python.rbt.xfeat.XFeatTrackingBackend.XFeatTrackingBackend::process_frame().

◆ detect() [3/3]

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

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.
Examples
tutorial-circle-hough.cpp.

Definition at line 191 of file vpCircleHoughTransform_common.cpp.

References vpImageConvert::convert(), and detect().

Referenced by detect(), detect(), and visp.python.rbt.xfeat.XFeatTrackingBackend.XFeatTrackingBackend::process_frame().

◆ edgeDetection()

void vpCircleHoughTransform::edgeDetection ( const vpImage< unsigned char > & I)
protectedvirtual

Perform edge detection based on the computed gradients. Stores the edge points and the edge points connectivity.

Parameters
[in]IThe input gray scale image.

Definition at line 79 of file vpCircleHoughTransform_centers.cpp.

References vpImageFilter::canny(), vpImageFilter::CANNY_VISP_BACKEND, filterEdgeMap(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), m_algoParams, m_cannyVisp, m_dIx, m_dIy, m_edgeMap, and mp_mask.

Referenced by detect().

◆ filterCenterCandidates()

void vpCircleHoughTransform::filterCenterCandidates ( const std::vector< vpCenterVotes > & peak_positions_votes)
protectedvirtual

Aggregate center candidates that are close to each other.

Parameters
[in]peak_positions_votesVector containing raw center candidates.

Definition at line 440 of file vpCircleHoughTransform_centers.cpp.

References m_algoParams, m_centerCandidatesList, m_centerVotes, and mergeSimilarCenters().

Referenced by computeCenterCandidates().

◆ filterEdgeMap()

void vpCircleHoughTransform::filterEdgeMap ( )
protectedvirtual

Filter the edge map in order to remove isolated edge points.

Definition at line 127 of file vpCircleHoughTransform_centers.cpp.

References edgeMapOff, edgeMapOn, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and m_edgeMap.

Referenced by edgeDetection().

◆ 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 1231 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ getCenterCandidatesList()

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

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

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

Definition at line 1151 of file vpCircleHoughTransform.h.

References m_centerCandidatesList.

◆ getCenterCandidatesVotes()

std::vector< int > vpCircleHoughTransform::getCenterCandidatesVotes ( ) const
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 1161 of file vpCircleHoughTransform.h.

References m_centerVotes.

◆ getCircleCandidates()

std::vector< vpImageCircle > vpCircleHoughTransform::getCircleCandidates ( ) const
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 1172 of file vpCircleHoughTransform.h.

References m_circleCandidates.

◆ getCircleCandidatesProbabilities()

std::vector< float > vpCircleHoughTransform::getCircleCandidatesProbabilities ( ) const
inline

Get the probabilities of the Circle Candidates.

Returns
std::vector<float> The votes accumulator.

Definition at line 1182 of file vpCircleHoughTransform.h.

References m_circleCandidatesProbabilities.

◆ getCircleCandidatesVotes()

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

Get the votes of the circle candidates.

Returns
std::vector<unsigned int> The votes of the circle candidates.

Definition at line 1192 of file vpCircleHoughTransform.h.

References m_circleCandidatesVotes.

◆ getCircleCenterMinDist()

float vpCircleHoughTransform::getCircleCenterMinDist ( ) const
inline

Get circles center min distance in pixels.

Definition at line 1239 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ getCircleMaxRadius()

float vpCircleHoughTransform::getCircleMaxRadius ( ) const
inline

Get circles max radius in pixels.

Definition at line 1255 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ getCircleMinRadius()

float vpCircleHoughTransform::getCircleMinRadius ( ) const
inline

Get circles min radius in pixels.

Definition at line 1247 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ getDetectionsProbabilities()

std::vector< float > vpCircleHoughTransform::getDetectionsProbabilities ( ) const
inline

Get the probabilities of the detections that are outputed by vpCircleHoughTransform::detect()

Examples
tutorial-circle-hough.cpp.

Definition at line 1263 of file vpCircleHoughTransform.h.

References m_finalCirclesProbabilities.

◆ getDetectionsVotes()

std::vector< unsigned int > vpCircleHoughTransform::getDetectionsVotes ( ) const
inline

Get the number of votes for the detections that are outputed by vpCircleHoughTransform::detect()

Definition at line 1271 of file vpCircleHoughTransform.h.

References m_finalCircleVotes.

◆ getDetectionsVotingPoints()

std::vector< std::vector< std::pair< unsigned int, unsigned int > > > vpCircleHoughTransform::getDetectionsVotingPoints ( ) const
inline

Get the points that voted for the detections that are outputed by vpCircleHoughTransform::detect().

Definition at line 1279 of file vpCircleHoughTransform.h.

References vpException::fatalError, m_algoParams, and m_finalCirclesVotingPoints.

◆ getEdgeMap()

vpImage< unsigned char > vpCircleHoughTransform::getEdgeMap ( ) const
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.
Examples
tutorial-circle-hough.cpp.

Definition at line 1222 of file vpCircleHoughTransform.h.

References m_edgeMap.

◆ getGradientX()

vpImage< float > vpCircleHoughTransform::getGradientX ( ) const
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 1202 of file vpCircleHoughTransform.h.

References m_dIx.

◆ getGradientY()

vpImage< float > vpCircleHoughTransform::getGradientY ( ) const
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 1212 of file vpCircleHoughTransform.h.

References m_dIy.

◆ getRecordVotingPoints()

bool vpCircleHoughTransform::getRecordVotingPoints ( ) const
inline

Returns true if it was asked to record the points that voted for the detections.

Definition at line 1290 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ init()

void vpCircleHoughTransform::init ( const vpCircleHoughTransformParams & algoParams)

Initialize all the algorithm parameters.

Parameters
[in]algoParamsThe algorithm parameters.
Examples
tutorial-circle-hough.cpp.

Definition at line 80 of file vpCircleHoughTransform_common.cpp.

References initGaussianFilters(), initGradientFilters(), and m_algoParams.

◆ initFromJSON()

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

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.
Examples
tutorial-circle-hough.cpp.

Definition at line 100 of file vpCircleHoughTransform_common.cpp.

References initGaussianFilters(), initGradientFilters(), vpException::ioError, and m_algoParams.

Referenced by vpCircleHoughTransform().

◆ initGaussianFilters()

void vpCircleHoughTransform::initGaussianFilters ( )
protectedvirtual

Initialize the Gaussian filters used to blur the image and compute the gradient images.

Definition at line 134 of file vpCircleHoughTransform_common.cpp.

References vpImageFilter::getGaussianKernel(), m_algoParams, m_cannyVisp, and m_fg.

Referenced by init(), initFromJSON(), setGaussianParameters(), vpCircleHoughTransform(), and vpCircleHoughTransform().

◆ initGradientFilters()

void vpCircleHoughTransform::initGradientFilters ( )
protectedvirtual

Initialize the gradient filters used to compute the gradient images.

Definition at line 143 of file vpCircleHoughTransform_common.cpp.

References vpException::badValue, vpImageFilter::CANNY_GBLUR_SCHARR_FILTERING, vpImageFilter::CANNY_GBLUR_SOBEL_FILTERING, vpArray2D< Type >::getCols(), vpArray2D< Type >::getRows(), vpImageFilter::getScharrKernelX(), vpImageFilter::getScharrKernelY(), vpImageFilter::getSobelKernelX(), vpImageFilter::getSobelKernelY(), m_algoParams, m_cannyVisp, m_gradientFilterX, m_gradientFilterY, vpException::notImplementedError, and vpImageFilter::vpCannyFiltAndGradTypeToStr().

Referenced by init(), initFromJSON(), setFilteringAndGradientType(), setGradientFilterAperture(), vpCircleHoughTransform(), and vpCircleHoughTransform().

◆ mergeCandidates()

void vpCircleHoughTransform::mergeCandidates ( std::vector< vpImageCircle > & circleCandidates,
std::vector< unsigned int > & circleCandidatesVotes,
std::vector< float > & circleCandidatesProba,
std::vector< std::vector< std::pair< unsigned int, unsigned int > > > & votingPoints )
protectedvirtual

For each circle candidate CiC_i do:

  • For each other circle candidate CiC_j do: +- Compute the similarity between CiC_i and CiC_j +- If the similarity exceeds a threshold, merge the circle candidates CiC_i and CiC_j and remove CiC_j of the list
  • Add the circle candidate CiC_i to the final list of detected circles
    Parameters
    [out]circleCandidatesList of circle candidates in which we want to merge the similar circles.
    [out]circleCandidatesVotesList of votes of the circle candidates.
    [out]circleCandidatesProbaList of probabilities of the circle candidates.
    [out]votingPointsList of edge-map points having voted of the circle candidates.

Definition at line 317 of file vpCircleHoughTransform_circles.cpp.

References vpImagePoint::distance(), vpImageCircle::getCenter(), vpImageCircle::getRadius(), and m_algoParams.

Referenced by mergeCircleCandidates().

◆ mergeCircleCandidates()

void vpCircleHoughTransform::mergeCircleCandidates ( )
protectedvirtual

For each circle candidate CiC_i, check if similar circles have also been detected and if so merges them.

Definition at line 297 of file vpCircleHoughTransform_circles.cpp.

References m_circleCandidates, m_circleCandidatesProbabilities, m_circleCandidatesVotes, m_circleCandidatesVotingPoints, m_finalCircles, m_finalCirclesProbabilities, m_finalCirclesVotingPoints, m_finalCircleVotes, and mergeCandidates().

Referenced by detect().

◆ mergeSimilarCenters()

vpCircleHoughTransform::vpCentersBarycenter vpCircleHoughTransform::mergeSimilarCenters ( const unsigned int & idPeak,
const unsigned int & nbPeaks,
const float & squared_distance_max,
const std::vector< vpCenterVotes > & peak_positions_votes,
std::vector< bool > & has_been_merged )
protectedvirtual

Look in the list containing the raw center candidates if one is closed to the center candidate that is currently of interest.

Parameters
[in]idPeakThe ID of the center candidate that is currently of interest.
[in]nbPeaksThe number of center candidates.
[in]squared_distance_maxThe maximum squared distance between to center candidates to merge them.
[in]peak_positions_votesThe list containing the raw center candidates.
[out]has_been_mergedVector indicating if the center candidates have already been merged.
Returns
vpCentersBarycenter The barycenter between the center candidate that is currently of interest and similar center candidates.

Definition at line 492 of file vpCircleHoughTransform_centers.cpp.

References m_algoParams.

Referenced by filterCenterCandidates().

◆ saveConfigurationInJSON()

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

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 127 of file vpCircleHoughTransform_common.cpp.

References m_algoParams.

◆ setCannyBackend()

void vpCircleHoughTransform::setCannyBackend ( const vpImageFilter::vpCannyBackendType & type)
inline

Set the backend to use to perform the Canny edge detection.

Parameters
[in]typeThe backend that must be used.

Definition at line 939 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ 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 953 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ setCannyThresholdRatio()

void vpCircleHoughTransform::setCannyThresholdRatio ( const float & lowerThreshRatio,
const float & upperThreshRatio )
inline

Set the Canny thresholds ratio that are used to automatically compute the Canny thresholds in case the user asks to.

See also
vpCircleHoughTransform::setCannyThreshold(const float&, const float&)
Parameters
[in]lowerThreshRatioThe ratio of the upper threshold the lower threshold will be equal to.
[in]upperThreshRatioThe ratio of pixels that must have a gradient lower than the upper threshold.

Definition at line 968 of file vpCircleHoughTransform.h.

References m_algoParams, and m_cannyVisp.

◆ setCenterComputationParameters()

void vpCircleHoughTransform::setCenterComputationParameters ( const int & dilatationSize,
const float & centerThresh,
const int & averagingWindowSize = 5,
const int expectedNbCenters = -1 )
inline

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

Parameters
[in]dilatationSizeKernel size of the dilatation operation used to detect the maxima in the center accumulator.
[in]centerThreshMinimum number of votes a point must exceed to be considered as center candidate.
[in]averagingWindowSizeSize of the averaging window around the maximum number of votes to compute the center candidate such as it is the barycenter of the window. Must be odd.
[in]expectedNbCentersExpected number of centers in the image. If the number is negative, all the centers are kept. Otherwise, maximum up to this number of centers are kept.

Definition at line 1054 of file vpCircleHoughTransform.h.

References vpException::badValue, and m_algoParams.

◆ 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 1002 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ 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 981 of file vpCircleHoughTransform.h.

References vpException::badValue, and m_algoParams.

◆ 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 1024 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ 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 1015 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ setCirclePerfectness()

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

Set circles perfectness, which corresponds to the threshold of the colinearity between the gradient of a point and the radius it would form with a center candidate to be able to vote. The formula to get the equivalent angle is: angle = acos(circle_perfectness).

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

Definition at line 1036 of file vpCircleHoughTransform.h.

References vpException::badValue, and m_algoParams.

◆ setFilteringAndGradientType()

void vpCircleHoughTransform::setFilteringAndGradientType ( const vpImageFilter::vpCannyFilteringAndGradientType & type)
inline

Permits to choose the filtering + gradient operators to use.

Parameters
[in]typeThe type of filtering + gradient operators to use.

Definition at line 886 of file vpCircleHoughTransform.h.

References initGradientFilters(), m_algoParams, and m_cannyVisp.

◆ setGaussianParameters()

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

Set the parameters of the Gaussian filter, that permits to blur 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 900 of file vpCircleHoughTransform.h.

References vpException::badValue, initGaussianFilters(), and m_algoParams.

◆ setGradientFilterAperture()

void vpCircleHoughTransform::setGradientFilterAperture ( const unsigned int & apertureSize)
inline

Set the parameters of the gradient filter (Sobel or Scharr) kernel size filters.

Parameters
[in]apertureSizeThe size of the gradient filters kernel. Must be an odd value.

Definition at line 922 of file vpCircleHoughTransform.h.

References vpException::badValue, initGradientFilters(), and m_algoParams.

◆ setMask() [1/2]

void vpCircleHoughTransform::setMask ( const vpImage< bool > & mask)
inline

Set the mask that permits to ignore some pixels when performing the circle detection.

Parameters
[in]maskA boolean image where pixels set to true means that the pixel must be considered and set to false means that the pixel must be ignored.

Definition at line 1115 of file vpCircleHoughTransform.h.

References mp_mask.

◆ setMask() [2/2]

void vpCircleHoughTransform::setMask ( const vpImage< bool > * mask)
inline

Set the mask that permits to ignore some pixels when performing the circle detection.

Parameters
[in]maskEither a boolean image where pixels set to true means that the pixel must be considered and set to false means that the pixel must be ignored, or nullptr to deactivate the mask.

Definition at line 1127 of file vpCircleHoughTransform.h.

References mp_mask.

◆ 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 1100 of file vpCircleHoughTransform.h.

References vpException::badValue, and m_algoParams.

◆ 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 1085 of file vpCircleHoughTransform.h.

References vpException::badValue, and m_algoParams.

◆ setRecordVotingPoints()

void vpCircleHoughTransform::setRecordVotingPoints ( const bool & record)
inline

Permits to either activate or deactivate the memorization of the points that voted for the detected circles.

Parameters
[in]recordTrue to activate the feature, false to deactivate it.

Definition at line 1138 of file vpCircleHoughTransform.h.

References m_algoParams.

◆ toString()

std::string vpCircleHoughTransform::toString ( ) const

Create a string with all Hough transform parameters.

Definition at line 341 of file vpCircleHoughTransform_common.cpp.

References m_algoParams.

Referenced by operator<<.

◆ updateAccumAlongGradientDir()

void vpCircleHoughTransform::updateAccumAlongGradientDir ( const vpDataForAccumLoop & data,
float & sx,
float & sy,
vpImage< float > & centersAccum )
protected

Update the center accumulator along the positive and negative gradient direction starting from an edge-point of interest.

Parameters
[in]dataThe data required for the algorithm.
[out]sxThe gradient along x.
[out]syThe gradient along y.
[out]centersAccumThe center candidates accumulator.

Definition at line 321 of file vpCircleHoughTransform_centers.cpp.

References updateAccumulator().

Referenced by workOnAccumulator().

◆ updateAccumulator()

void vpCircleHoughTransform::updateAccumulator ( const vpCoordinatesForAccumStep & coord,
const vpDataForAccumLoop & data,
vpImage< float > & accum,
bool & hasToStop )
protected

Definition at line 302 of file vpCircleHoughTransform_centers.cpp.

Referenced by updateAccumAlongGradientDir().

◆ workOnAccumulator()

void vpCircleHoughTransform::workOnAccumulator ( vpDataForAccumLoop & data,
vpImage< float > & centersAccum )
protectedvirtual

Voting for points in both direction of the gradient.

Parameters
[in]dataThe data required for the algorithm.
[in]centersAccumThe center candidates accumulator.

Definition at line 422 of file vpCircleHoughTransform_centers.cpp.

References m_dIx, m_dIy, m_edgePointsList, and updateAccumAlongGradientDir().

Referenced by computeCenterCandidates().

◆ from_json

void from_json ( const nlohmann::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 854 of file vpCircleHoughTransform.h.

References m_algoParams, and vpCircleHoughTransform().

◆ operator<<

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

Create a ostream with all Hough transform parameters.

Definition at line 346 of file vpCircleHoughTransform_common.cpp.

References mp_mask, operator<<, toString(), and vpCircleHoughTransform().

Referenced by operator<<.

◆ to_json

void to_json ( nlohmann::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 865 of file vpCircleHoughTransform.h.

References m_algoParams, and vpCircleHoughTransform().

Member Data Documentation

◆ edgeMapOff

const unsigned char vpCircleHoughTransform::edgeMapOff = 0
static

Definition at line 1307 of file vpCircleHoughTransform.h.

Referenced by filterEdgeMap().

◆ edgeMapOn

BEGIN_VISP_NAMESPACE const unsigned char vpCircleHoughTransform::edgeMapOn = 255
static

Definition at line 1306 of file vpCircleHoughTransform.h.

Referenced by computeCenterCandidates(), and filterEdgeMap().

◆ m_algoParams

vpCircleHoughTransformParams vpCircleHoughTransform::m_algoParams
protected

Attributes containing all the algorithm parameters.

Definition at line 1475 of file vpCircleHoughTransform.h.

Referenced by computeCenterCandidates(), computeCircleCandidates(), computeGradients(), computeVotingMask(), detect(), detect(), edgeDetection(), filterCenterCandidates(), from_json, getCannyThreshold(), getCircleCenterMinDist(), getCircleMaxRadius(), getCircleMinRadius(), getDetectionsVotingPoints(), getRecordVotingPoints(), init(), initFromJSON(), initGaussianFilters(), initGradientFilters(), mergeCandidates(), mergeSimilarCenters(), saveConfigurationInJSON(), setCannyBackend(), setCannyThreshold(), setCannyThresholdRatio(), setCenterComputationParameters(), setCircleCenterBoundingBox(), setCircleCenterMinDist(), setCircleMaxRadius(), setCircleMinRadius(), setCirclePerfectness(), setFilteringAndGradientType(), setGaussianParameters(), setGradientFilterAperture(), setRadiusMergingThresholds(), setRadiusRatioThreshold(), setRecordVotingPoints(), to_json, toString(), vpCircleHoughTransform(), and vpCircleHoughTransform().

◆ m_cannyVisp

vpCannyEdgeDetection vpCircleHoughTransform::m_cannyVisp
protected

Edge detector ViSP implementation, used if ViSP has not been compiled with OpenCV imgproc module

Definition at line 1487 of file vpCircleHoughTransform.h.

Referenced by computeCenterCandidates(), edgeDetection(), initGaussianFilters(), initGradientFilters(), setCannyThresholdRatio(), and setFilteringAndGradientType().

◆ m_centerCandidatesList

std::vector<std::pair<float, float> > vpCircleHoughTransform::m_centerCandidatesList
protected

Vector that contains the list of center candidates. They are stored as pair <row, col>.

Definition at line 1492 of file vpCircleHoughTransform.h.

Referenced by computeCircleCandidates(), detect(), filterCenterCandidates(), and getCenterCandidatesList().

◆ m_centerVotes

std::vector<int> vpCircleHoughTransform::m_centerVotes
protected

Number of votes for the center candidates that are kept.

Definition at line 1493 of file vpCircleHoughTransform.h.

Referenced by detect(), filterCenterCandidates(), and getCenterCandidatesVotes().

◆ m_circleCandidates

std::vector<vpImageCircle> vpCircleHoughTransform::m_circleCandidates
protected

List of the candidate circles.

Definition at line 1496 of file vpCircleHoughTransform.h.

Referenced by computeCircleCandidates(), detect(), getCircleCandidates(), and mergeCircleCandidates().

◆ m_circleCandidatesProbabilities

std::vector<float> vpCircleHoughTransform::m_circleCandidatesProbabilities
protected

Probabilities of each candidate circle that is kept.

Definition at line 1497 of file vpCircleHoughTransform.h.

Referenced by computeCircleCandidates(), detect(), getCircleCandidatesProbabilities(), and mergeCircleCandidates().

◆ m_circleCandidatesVotes

std::vector<unsigned int> vpCircleHoughTransform::m_circleCandidatesVotes
protected

Number of pixels voting for each candidate circle that is kept.

Definition at line 1498 of file vpCircleHoughTransform.h.

Referenced by computeCircleCandidates(), detect(), getCircleCandidatesVotes(), and mergeCircleCandidates().

◆ m_circleCandidatesVotingPoints

std::vector<std::vector<std::pair<unsigned int, unsigned int> > > vpCircleHoughTransform::m_circleCandidatesVotingPoints
protected

Points that voted for each circle candidate.

Definition at line 1499 of file vpCircleHoughTransform.h.

Referenced by computeCircleCandidates(), detect(), and mergeCircleCandidates().

◆ m_dIx

vpImage<float> vpCircleHoughTransform::m_dIx
protected

Gradient along the x-axis of the input image.

Definition at line 1483 of file vpCircleHoughTransform.h.

Referenced by computeCircleCandidates(), computeGradients(), edgeDetection(), getGradientX(), and workOnAccumulator().

◆ m_dIy

vpImage<float> vpCircleHoughTransform::m_dIy
protected

Gradient along the y-axis of the input image.

Definition at line 1484 of file vpCircleHoughTransform.h.

Referenced by computeCircleCandidates(), computeGradients(), edgeDetection(), getGradientY(), and workOnAccumulator().

◆ m_edgeMap

vpImage<unsigned char> vpCircleHoughTransform::m_edgeMap
protected

Edge map resulting from the edge detection algorithm.

Definition at line 1488 of file vpCircleHoughTransform.h.

Referenced by computeCenterCandidates(), computeCircleProbability(), edgeDetection(), filterEdgeMap(), and getEdgeMap().

◆ m_edgePointsList

std::vector<std::pair<unsigned int, unsigned int> > vpCircleHoughTransform::m_edgePointsList
protected

Vector that contains the list of edge points, to make faster some parts of the algo. They are stored as pair <row, col>.

Definition at line 1491 of file vpCircleHoughTransform.h.

Referenced by computeCenterCandidates(), computeCircleCandidates(), detect(), and workOnAccumulator().

◆ m_fg

vpArray2D<float> vpCircleHoughTransform::m_fg
protected

Definition at line 1477 of file vpCircleHoughTransform.h.

Referenced by computeGradients(), and initGaussianFilters().

◆ m_finalCircles

std::vector<vpImageCircle> vpCircleHoughTransform::m_finalCircles
protected

List of the final circles, i.e. the ones resulting from the merge of the circle candidates.

Definition at line 1502 of file vpCircleHoughTransform.h.

Referenced by computeVotingMask(), detect(), detect(), and mergeCircleCandidates().

◆ m_finalCirclesProbabilities

std::vector<float> vpCircleHoughTransform::m_finalCirclesProbabilities
protected

Probabilities of each final circle, i.e. resulting from the merge of the circle candidates.

Definition at line 1503 of file vpCircleHoughTransform.h.

Referenced by detect(), detect(), getDetectionsProbabilities(), and mergeCircleCandidates().

◆ m_finalCirclesVotingPoints

std::vector<std::vector<std::pair<unsigned int, unsigned int> > > vpCircleHoughTransform::m_finalCirclesVotingPoints
protected

Points that voted for each final circle.

Definition at line 1505 of file vpCircleHoughTransform.h.

Referenced by computeVotingMask(), detect(), detect(), getDetectionsVotingPoints(), and mergeCircleCandidates().

◆ m_finalCircleVotes

std::vector<unsigned int> vpCircleHoughTransform::m_finalCircleVotes
protected

Number of votes for the final circles.

Definition at line 1504 of file vpCircleHoughTransform.h.

Referenced by detect(), detect(), getDetectionsVotes(), and mergeCircleCandidates().

◆ m_gradientFilterX

vpArray2D<float> vpCircleHoughTransform::m_gradientFilterX
protected

Contains the coefficients of the gradient kernel along the X-axis

Definition at line 1481 of file vpCircleHoughTransform.h.

Referenced by computeGradients(), and initGradientFilters().

◆ m_gradientFilterY

vpArray2D<float> vpCircleHoughTransform::m_gradientFilterY
protected

Contains the coefficients of the gradient kernel along the Y-axis

Definition at line 1482 of file vpCircleHoughTransform.h.

Referenced by computeGradients(), and initGradientFilters().

◆ mp_mask

const vpImage<bool>* vpCircleHoughTransform::mp_mask
protected

Mask that permits to avoid to compute gradients on some regions of the image.

Definition at line 1480 of file vpCircleHoughTransform.h.

Referenced by computeCircleProbability(), computeGradients(), edgeDetection(), operator<<, setMask(), setMask(), vpCircleHoughTransform(), vpCircleHoughTransform(), and vpCircleHoughTransform().