vpCircleHoughTransform.h

/*
 * ViSP, open source Visual Servoing Platform software.
 * Copyright (C) 2005 - 2023 by Inria. All rights reserved.
 *
 * This software is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * See the file LICENSE.txt at the root directory of this source
 * distribution for additional information about the GNU GPL.
 *
 * For using ViSP with software that can not be combined with the GNU
 * GPL, please contact Inria about acquiring a ViSP Professional
 * Edition License.
 *
 * See https://visp.inria.fr for more information.
 *
 * This software was developed at:
 * Inria Rennes - Bretagne Atlantique
 * Campus Universitaire de Beaulieu
 * 35042 Rennes Cedex
 * France
 *
 * If you have questions regarding the use of this file, please contact
 * Inria at visp@inria.fr
 *
 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 */
 
#ifndef _vpCircleHoughTransform_h_
#define _vpCircleHoughTransform_h_
 
// System includes
#include <utility>
#include <vector>
 
// ViSP includes
#include <visp3/core/vpConfig.h>
#include <visp3/core/vpCannyEdgeDetection.h>
#include <visp3/core/vpImage.h>
#include <visp3/core/vpImageCircle.h>
#include <visp3/core/vpMatrix.h>
 
// 3rd parties inclue
#ifdef VISP_HAVE_NLOHMANN_JSON
#include <nlohmann/json.hpp>
#endif
 
#if (VISP_CXX_STANDARD >= VISP_CXX_STANDARD_17)
#include <optional>
#endif
 
class VISP_EXPORT vpCircleHoughTransform
{
public:
  class vpCircleHoughTransformParameters
  {
  private:
    // // Filtering + gradient operators to use
    vpImageFilter::vpCannyFilteringAndGradientType m_filteringAndGradientType; 
    // // Gaussian smoothing attributes
    int m_gaussianKernelSize; 
    float m_gaussianStdev;   
    // // Gradient computation attributes
    int m_gradientFilterKernelSize; 
    // // Edge detection attributes
    float m_lowerCannyThresh; 
    float m_upperCannyThresh; 
    int m_edgeMapFilteringNbIter; 
    vpImageFilter::vpCannyBackendType m_cannyBackendType; 
    float m_lowerCannyThreshRatio; 
    float m_upperCannyThreshRatio; 
    // // Center candidates computation attributes
    std::pair<int, int> m_centerXlimits; 
    std::pair<int, int> m_centerYlimits; 
    float m_minRadius; 
    float m_maxRadius; 
    int m_dilatationKernelSize; 
    int m_averagingWindowSize; 
    float m_centerMinThresh;  
    int m_expectedNbCenters; 
    // // Circle candidates computation attributes
    float m_circleProbaThresh;  
    float m_circlePerfectness; 
    float m_circleVisibilityRatioThresh; 
    bool m_recordVotingPoints; 
    // // Circle candidates merging attributes
    float m_centerMinDist; 
    float m_mergingRadiusDiffThresh; 
    friend class vpCircleHoughTransform;
  public:
    vpCircleHoughTransformParameters()
      : m_filteringAndGradientType(vpImageFilter::CANNY_GBLUR_SOBEL_FILTERING)
      , m_gaussianKernelSize(5)
      , m_gaussianStdev(1.f)
      , m_gradientFilterKernelSize(3)
      , m_lowerCannyThresh(-1.f)
      , m_upperCannyThresh(-1.f)
      , m_edgeMapFilteringNbIter(1)
      , m_cannyBackendType(vpImageFilter::CANNY_OPENCV_BACKEND)
      , m_lowerCannyThreshRatio(0.6f)
      , m_upperCannyThreshRatio(0.8f)
      , m_centerXlimits(std::pair<int, int>(std::numeric_limits<int>::min(), std::numeric_limits<int>::max()))
      , m_centerYlimits(std::pair<int, int>(std::numeric_limits<int>::min(), std::numeric_limits<int>::max()))
      , m_minRadius(0.f)
      , m_maxRadius(1000.f)
      , m_dilatationKernelSize(3)
      , m_averagingWindowSize(5)
      , m_centerMinThresh(50.f)
      , m_expectedNbCenters(-1)
      , m_circleProbaThresh(0.9f)
      , m_circlePerfectness(0.9f)
      , m_circleVisibilityRatioThresh(0.1f)
      , m_recordVotingPoints(false)
      , m_centerMinDist(15.f)
      , m_mergingRadiusDiffThresh(1.5f * m_centerMinDist)
    {
 
    }
 
    vpCircleHoughTransformParameters(
      const int &gaussianKernelSize
      , const float &gaussianStdev
      , const int &gradientFilterKernelSize
      , const float &lowerCannyThresh
      , const float &upperCannyThresh
      , const int &edgeMapFilterNbIter
      , const std::pair<int, int> &centerXlimits
      , const std::pair<int, int> &centerYlimits
      , const float &minRadius
      , const float &maxRadius
      , const int &dilatationKernelSize
      , const int &averagingWindowSize
      , const float &centerThresh
      , const float &circleProbabilityThresh
      , const float &circlePerfectness
      , const float &centerMinDistThresh
      , const float &mergingRadiusDiffThresh
      , const vpImageFilter::vpCannyFilteringAndGradientType &filteringAndGradientMethod = vpImageFilter::CANNY_GBLUR_SOBEL_FILTERING
      , const vpImageFilter::vpCannyBackendType &backendType = vpImageFilter::CANNY_OPENCV_BACKEND
      , const float &lowerCannyThreshRatio = 0.6f
      , const float &upperCannyThreshRatio = 0.8f
      , const int &expectedNbCenters = -1
      , const bool &recordVotingPoints = false
      , const float &visibilityRatioThresh = 0.1f
    )
      : m_filteringAndGradientType(filteringAndGradientMethod)
      , m_gaussianKernelSize(gaussianKernelSize)
      , m_gaussianStdev(gaussianStdev)
      , m_gradientFilterKernelSize(gradientFilterKernelSize)
      , m_lowerCannyThresh(lowerCannyThresh)
      , m_upperCannyThresh(upperCannyThresh)
      , m_edgeMapFilteringNbIter(edgeMapFilterNbIter)
      , m_cannyBackendType(backendType)
      , m_lowerCannyThreshRatio(lowerCannyThreshRatio)
      , m_upperCannyThreshRatio(upperCannyThreshRatio)
      , m_centerXlimits(centerXlimits)
      , m_centerYlimits(centerYlimits)
      , m_minRadius(std::min<float>(minRadius, maxRadius))
      , m_maxRadius(std::max<float>(minRadius, maxRadius))
      , m_dilatationKernelSize(dilatationKernelSize)
      , m_averagingWindowSize(averagingWindowSize)
      , m_centerMinThresh(centerThresh)
      , m_expectedNbCenters(expectedNbCenters)
      , m_circleProbaThresh(circleProbabilityThresh)
      , m_circlePerfectness(circlePerfectness)
      , m_circleVisibilityRatioThresh(visibilityRatioThresh)
      , m_recordVotingPoints(recordVotingPoints)
      , m_centerMinDist(centerMinDistThresh)
      , m_mergingRadiusDiffThresh(mergingRadiusDiffThresh)
    { }
 
    inline int getGaussianKernelSize() const
    {
      return m_gaussianKernelSize;
    }
 
    inline float getGaussianStdev() const
    {
      return m_gaussianStdev;
    }
 
    inline int getGradientKernelSize() const
    {
      return m_gradientFilterKernelSize;
    }
 
    inline float getLowerCannyThreshold() const
    {
      return m_lowerCannyThresh;
    }
 
    inline float getUpperCannyThreshold() const
    {
      return m_upperCannyThresh;
    }
 
    inline int getEdgeMapFilteringNbIter() const
    {
      return m_edgeMapFilteringNbIter;
    }
 
    inline std::pair<int, int> getCenterXLimits() const
    {
      return m_centerXlimits;
    }
 
    inline std::pair<int, int> getCenterYLimits() const
    {
      return m_centerYlimits;
    }
 
    inline float getMinRadius() const
    {
      return m_minRadius;
    }
 
    inline float getMaxRadius() const
    {
      return m_maxRadius;
    }
 
    inline int getDilatationKernelSize() const
    {
      return m_dilatationKernelSize;
    }
 
    inline int getAveragingWindowSize() const
    {
      return m_averagingWindowSize;
    }
 
    inline float getCenterMinThreshold() const
    {
      return m_centerMinThresh;
    }
 
    inline int getExpectedNbCenters() const
    {
      return m_expectedNbCenters;
    }
 
    inline float getProbabilityThreshold() const
    {
      return m_circleProbaThresh;
    }
 
    inline float getVisibilityRatioThreshold() const
    {
      return m_circleVisibilityRatioThresh;
    }
 
    inline float getCirclePerfectness() const
    {
      return m_circlePerfectness;
    }
 
    inline bool getRecordVotingPoints() const
    {
      return m_recordVotingPoints;
    }
 
    inline float getCenterMinDist() const
    {
      return m_centerMinDist;
    }
 
    inline float getMergingRadiusDiff() const
    {
      return m_mergingRadiusDiffThresh;
    }
 
    std::string toString() const
    {
      std::stringstream txt;
      txt << "Hough Circle Transform Configuration:\n";
      txt <<  "\tFiltering + gradient operators = " << vpImageFilter::vpCannyFilteringAndGradientTypeToString(m_filteringAndGradientType) << "\n";
      txt <<  "\tGaussian filter kernel size = " << m_gaussianKernelSize << "\n";
      txt <<  "\tGaussian filter standard deviation = " << m_gaussianStdev << "\n";
      txt <<  "\tGradient filter kernel size = " << m_gradientFilterKernelSize << "\n";
      txt <<  "\tCanny backend = " << vpImageFilter::vpCannyBackendTypeToString(m_cannyBackendType) << "\n";
      txt <<  "\tCanny edge filter thresholds = [" << m_lowerCannyThresh << " ; " << m_upperCannyThresh << "]\n";
      txt <<  "\tCanny edge filter thresholds ratio (for auto-thresholding) = [" << m_lowerCannyThreshRatio << " ; " << m_upperCannyThreshRatio << "]\n";
      txt <<  "\tEdge map 8-neighbor connectivity filtering number of iterations = " << m_edgeMapFilteringNbIter << "\n";
      txt <<  "\tCenter horizontal position limits: min = " << m_centerXlimits.first << "\tmax = " << m_centerXlimits.second << "\n";
      txt <<  "\tCenter vertical position limits: min = " << m_centerYlimits.first << "\tmax = " << m_centerYlimits.second << "\n";
      txt <<  "\tRadius limits: min = " << m_minRadius << "\tmax = " << m_maxRadius << "\n";
      txt <<  "\tKernel size of the dilatation filter = " << m_dilatationKernelSize << "\n";
      txt <<  "\tAveraging window size for center detection = " << m_averagingWindowSize << "\n";
      txt <<  "\tCenters votes threshold = " << m_centerMinThresh << "\n";
      txt <<  "\tExpected number of centers = ";
      if (m_expectedNbCenters > 0) {
        txt << m_expectedNbCenters;
      }
      else {
        txt << "no limits";
      }
      txt << "\n";
      txt <<  "\tCircle probability threshold = " << m_circleProbaThresh << "\n";
      txt <<  "\tCircle visibility ratio threshold = " << m_circleVisibilityRatioThresh << "\n";
      txt <<  "\tCircle perfectness threshold = " << m_circlePerfectness << "\n";
      txt <<  "\tRecord voting points = " + (m_recordVotingPoints ? std::string("true") : std::string("false")) << "\n";
      txt <<  "\tCenters minimum distance = " << m_centerMinDist << "\n";
      txt <<  "\tRadius difference merging threshold = " << m_mergingRadiusDiffThresh << "\n";
      return txt.str();
    }
 
    // // Configuration from files
#ifdef VISP_HAVE_NLOHMANN_JSON
    inline static vpCircleHoughTransformParameters createFromJSON(const std::string &jsonFile)
    {
      using json = nlohmann::json;
 
      std::ifstream file(jsonFile);
      if (!file.good()) {
        std::stringstream ss;
        ss << "Problem opening file " << jsonFile << ". Make sure it exists and is readable" << std::endl;
        throw vpException(vpException::ioError, ss.str());
      }
      json j;
      try {
        j = json::parse(file);
      }
      catch (json::parse_error &e) {
        std::stringstream msg;
        msg << "Could not parse JSON file : \n";
 
        msg << e.what() << std::endl;
        msg << "Byte position of error: " << e.byte;
        throw vpException(vpException::ioError, msg.str());
      }
      vpCircleHoughTransformParameters params = j; // Call from_json(const json& j, vpDetectorDNN& *this) to read json
      file.close();
      return params;
    }
 
    inline void saveConfigurationInJSON(const std::string &jsonPath) const
    {
      using json = nlohmann::json;
      std::ofstream file(jsonPath);
      const json j = *this;
      file << j.dump(4);
      file.close();
    }
 
    friend inline void from_json(const nlohmann::json &j, vpCircleHoughTransformParameters &params)
    {
      std::string filteringAndGradientName = vpImageFilter::vpCannyFilteringAndGradientTypeToString(params.m_filteringAndGradientType);
      filteringAndGradientName = j.value("filteringAndGradientType", filteringAndGradientName);
      params.m_filteringAndGradientType = vpImageFilter::vpCannyFilteringAndGradientTypeFromString(filteringAndGradientName);
 
      params.m_gaussianKernelSize = j.value("gaussianKernelSize", params.m_gaussianKernelSize);
      if ((params.m_gaussianKernelSize % 2) != 1) {
        throw vpException(vpException::badValue, "Gaussian Kernel size should be odd.");
      }
 
      params.m_gaussianStdev = j.value("gaussianStdev", params.m_gaussianStdev);
      if (params.m_gaussianStdev <= 0) {
        throw vpException(vpException::badValue, "Standard deviation should be > 0");
      }
 
      params.m_gradientFilterKernelSize = j.value("gradientFilterKernelSize", params.m_gradientFilterKernelSize);
      if ((params.m_gradientFilterKernelSize % 2) != 1) {
        throw vpException(vpException::badValue, "Gradient filter kernel (Sobel or Scharr) size should be odd.");
      }
 
      std::string cannyBackendName = vpImageFilter::vpCannyBackendTypeToString(params.m_cannyBackendType);
      cannyBackendName = j.value("cannyBackendType", cannyBackendName);
      params.m_cannyBackendType = vpImageFilter::vpCannyBackendTypeFromString(cannyBackendName);
      params.m_lowerCannyThresh = j.value("lowerCannyThresh", params.m_lowerCannyThresh);
      params.m_lowerCannyThreshRatio = j.value("lowerThresholdRatio", params.m_lowerCannyThreshRatio);
      params.m_upperCannyThresh = j.value("upperCannyThresh", params.m_upperCannyThresh);
      params.m_upperCannyThreshRatio = j.value("upperThresholdRatio", params.m_upperCannyThreshRatio);
      params.m_edgeMapFilteringNbIter = j.value("edgeMapFilteringNbIter", params.m_edgeMapFilteringNbIter);
 
      params.m_centerXlimits = j.value("centerXlimits", params.m_centerXlimits);
      params.m_centerYlimits = j.value("centerYlimits", params.m_centerYlimits);
      std::pair<float, float> radiusLimits = j.value("radiusLimits", std::pair<float, float>(params.m_minRadius, params.m_maxRadius));
      params.m_minRadius = std::min<float>(radiusLimits.first, radiusLimits.second);
      params.m_maxRadius = std::max<float>(radiusLimits.first, radiusLimits.second);
 
      params.m_dilatationKernelSize = j.value("dilatationKernelSize", params.m_dilatationKernelSize);
      params.m_averagingWindowSize = j.value("averagingWindowSize", params.m_averagingWindowSize);
      if (params.m_averagingWindowSize <= 0 || (params.m_averagingWindowSize % 2) == 0) {
        throw vpException(vpException::badValue, "Averaging window size must be positive and odd.");
      }
 
      params.m_centerMinThresh = j.value("centerThresh", params.m_centerMinThresh);
      if (params.m_centerMinThresh <= 0) {
        throw vpException(vpException::badValue, "Votes thresholds for center detection must be positive.");
      }
 
      params.m_expectedNbCenters = j.value("expectedNbCenters", params.m_expectedNbCenters);
 
 
      params.m_circleProbaThresh = j.value("circleProbabilityThreshold", params.m_circleProbaThresh);
      params.m_circleVisibilityRatioThresh = j.value("circleVisibilityRatioThreshold", params.m_circleVisibilityRatioThresh);
 
      params.m_circlePerfectness = j.value("circlePerfectnessThreshold", params.m_circlePerfectness);
 
      if (params.m_circlePerfectness <= 0 || params.m_circlePerfectness > 1) {
        throw vpException(vpException::badValue, "Circle perfectness must be in the interval ] 0; 1].");
      }
 
      params.m_recordVotingPoints = j.value("recordVotingPoints", params.m_recordVotingPoints);
 
      params.m_centerMinDist = j.value("centerMinDistance", params.m_centerMinDist);
      if (params.m_centerMinDist <= 0) {
        throw vpException(vpException::badValue, "Centers minimum distance threshold must be positive.");
      }
 
      params.m_mergingRadiusDiffThresh = j.value("mergingRadiusDiffThresh", params.m_mergingRadiusDiffThresh);
      if (params.m_mergingRadiusDiffThresh <= 0) {
        throw vpException(vpException::badValue, "Radius difference merging threshold must be positive.");
      }
    }
 
    friend inline void to_json(nlohmann::json &j, const vpCircleHoughTransformParameters &params)
    {
      std::pair<float, float> radiusLimits = { params.m_minRadius, params.m_maxRadius };
 
      j = nlohmann::json {
          {"filteringAndGradientType", vpImageFilter::vpCannyFilteringAndGradientTypeToString(params.m_filteringAndGradientType)},
          {"gaussianKernelSize", params.m_gaussianKernelSize},
          {"gaussianStdev", params.m_gaussianStdev},
          {"gradientFilterKernelSize", params.m_gradientFilterKernelSize},
          {"cannyBackendType", vpImageFilter::vpCannyBackendTypeToString(params.m_cannyBackendType)},
          {"lowerCannyThresh", params.m_lowerCannyThresh},
          {"lowerThresholdRatio", params.m_lowerCannyThreshRatio},
          {"upperCannyThresh", params.m_upperCannyThresh},
          {"upperThresholdRatio", params.m_upperCannyThreshRatio},
          {"edgeMapFilteringNbIter", params.m_edgeMapFilteringNbIter},
          {"centerXlimits", params.m_centerXlimits},
          {"centerYlimits", params.m_centerYlimits},
          {"radiusLimits", radiusLimits},
          {"dilatationKernelSize", params.m_dilatationKernelSize},
          {"averagingWindowSize", params.m_averagingWindowSize},
          {"centerThresh", params.m_centerMinThresh},
          {"expectedNbCenters", params.m_expectedNbCenters},
          {"circleProbabilityThreshold", params.m_circleProbaThresh},
          {"circleVisibilityRatioThreshold", params.m_circleVisibilityRatioThresh},
          {"circlePerfectnessThreshold", params.m_circlePerfectness},
          {"recordVotingPoints", params.m_recordVotingPoints},
          {"centerMinDistance", params.m_centerMinDist},
          {"mergingRadiusDiffThresh", params.m_mergingRadiusDiffThresh} };
    }
#endif
  };
 
  vpCircleHoughTransform();
 
  vpCircleHoughTransform(const vpCircleHoughTransformParameters &algoParams);
 
  virtual ~vpCircleHoughTransform();
 
#ifdef HAVE_OPENCV_CORE
  virtual std::vector<vpImageCircle> detect(const cv::Mat &cv_I);
#endif
 
  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);
 
#if (VISP_CXX_STANDARD >= VISP_CXX_STANDARD_17)
  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;
#else
  void computeVotingMask(const vpImage<unsigned char> &I, const std::vector<vpImageCircle> &detections,
                         vpImage<bool> **mask, std::vector<std::vector<std::pair<unsigned int, unsigned int> > > **opt_votingPoints) const;
#endif
 
#ifdef VISP_HAVE_NLOHMANN_JSON
  vpCircleHoughTransform(const std::string &jsonPath);
 
  virtual void initFromJSON(const std::string &jsonPath);
 
  virtual void saveConfigurationInJSON(const std::string &jsonPath) const;
 
  friend inline void from_json(const nlohmann::json &j, vpCircleHoughTransform &detector)
  {
    detector.m_algoParams = j;
  }
 
  friend inline void to_json(nlohmann::json &j, const vpCircleHoughTransform &detector)
  {
    j = detector.m_algoParams;
  }
#endif
 
  void init(const vpCircleHoughTransformParameters &algoParams);
 
  inline void setFilteringAndGradientType(const vpImageFilter::vpCannyFilteringAndGradientType &type)
  {
    m_algoParams.m_filteringAndGradientType = type;
    m_cannyVisp.setFilteringAndGradientType(type);
    initGradientFilters();
  }
 
  inline void setGaussianParameters(const int &kernelSize, const float &stdev)
  {
    m_algoParams.m_gaussianKernelSize = kernelSize;
    m_algoParams.m_gaussianStdev = stdev;
 
    if ((m_algoParams.m_gaussianKernelSize % 2) != 1) {
      throw vpException(vpException::badValue, "Gaussian Kernel size should be odd.");
    }
 
    if (m_algoParams.m_gaussianStdev <= 0) {
      throw vpException(vpException::badValue, "Standard deviation should be > 0");
    }
 
    initGaussianFilters();
  }
 
  inline void setGradientFilterAperture(const unsigned int &apertureSize)
  {
    m_algoParams.m_gradientFilterKernelSize = apertureSize;
 
    if ((m_algoParams.m_gradientFilterKernelSize % 2) != 1) {
      throw vpException(vpException::badValue, "Gradient filter (Sobel or Scharr) Kernel size should be odd.");
    }
 
    initGradientFilters();
  }
 
  inline void setCannyBackend(const vpImageFilter::vpCannyBackendType &type)
  {
    m_algoParams.m_cannyBackendType = type;
  }
 
  inline void setCannyThreshold(const float &lowerCannyThreshold, const float &upperCannyThreshold)
  {
    m_algoParams.m_lowerCannyThresh = lowerCannyThreshold;
    m_algoParams.m_upperCannyThresh = upperCannyThreshold;
  }
 
  inline void setCannyThresholdRatio(const float &lowerThreshRatio, const float &upperThreshRatio)
  {
    m_algoParams.m_lowerCannyThreshRatio = lowerThreshRatio;
    m_algoParams.m_upperCannyThreshRatio = upperThreshRatio;
    m_cannyVisp.setCannyThresholdsRatio(lowerThreshRatio, upperThreshRatio);
  }
 
  inline void setCircleCenterMinDist(const float &center_min_dist)
  {
    m_algoParams.m_centerMinDist = center_min_dist;
 
    if (m_algoParams.m_centerMinDist <= 0) {
      throw vpException(vpException::badValue, "Circles center min distance  must be positive.");
    }
  }
 
  void setCircleCenterBoundingBox(const int &center_min_x, const int &center_max_x,
                                  const int &center_min_y, const int &center_max_y)
  {
    m_algoParams.m_centerXlimits.first = center_min_x;
    m_algoParams.m_centerXlimits.second = center_max_x;
    m_algoParams.m_centerYlimits.first = center_min_y;
    m_algoParams.m_centerYlimits.second = center_max_y;
  }
 
  inline void setCircleMinRadius(const float &circle_min_radius)
  {
    m_algoParams.m_minRadius = circle_min_radius;
  }
 
  inline void setCircleMaxRadius(const float &circle_max_radius)
  {
    m_algoParams.m_maxRadius = circle_max_radius;
  }
 
  void setCirclePerfectness(const float &circle_perfectness)
  {
    m_algoParams.m_circlePerfectness = circle_perfectness;
    if (m_algoParams.m_circlePerfectness <= 0 || m_algoParams.m_circlePerfectness > 1) {
      throw vpException(vpException::badValue, "Circle perfectness must be in the interval ] 0; 1].");
    }
  }
 
  inline void setCenterComputationParameters(const int &dilatationSize, const float &centerThresh,
                                             const int &averagingWindowSize = 5, const int expectedNbCenters = -1)
  {
    m_algoParams.m_dilatationKernelSize = dilatationSize;
    m_algoParams.m_centerMinThresh = centerThresh;
    m_algoParams.m_averagingWindowSize = averagingWindowSize;
    m_algoParams.m_expectedNbCenters = expectedNbCenters;
 
    if (m_algoParams.m_dilatationKernelSize < 3) {
      throw vpException(vpException::badValue, "Dilatation kernel size for center detection must be greater or equal to 3.");
    }
    else if ((m_algoParams.m_dilatationKernelSize % 2) == 0) {
      throw vpException(vpException::badValue, "Dilatation kernel size for center detection must be odd.");
    }
 
    if (m_algoParams.m_centerMinThresh <= 0.f) {
      throw vpException(vpException::badValue, "Votes thresholds for center detection must be positive.");
    }
 
    if ((m_algoParams.m_averagingWindowSize <= 0) || ((m_algoParams.m_averagingWindowSize % 2) == 0)) {
      throw vpException(vpException::badValue, "Averaging window size must be positive and odd.");
    }
  }
 
  inline void setRadiusRatioThreshold(const float &radiusRatioThresh)
  {
    m_algoParams.m_circleProbaThresh = radiusRatioThresh;
 
    if (m_algoParams.m_circleProbaThresh <= 0) {
      throw vpException(vpException::badValue, "Radius ratio threshold must be > 0.");
    }
  }
 
  inline void setRadiusMergingThresholds(const float &radiusDifferenceThresh)
  {
    m_algoParams.m_mergingRadiusDiffThresh = radiusDifferenceThresh;
 
    if (m_algoParams.m_mergingRadiusDiffThresh <= 0) {
      throw vpException(vpException::badValue, "Radius difference merging threshold must be positive.");
    }
  }
 
  inline void setMask(const vpImage<bool> &mask)
  {
    mp_mask = &mask;
  }
 
  inline std::vector<std::pair<float, float> > getCenterCandidatesList() const
  {
    return m_centerCandidatesList;
  }
 
  inline std::vector<int> getCenterCandidatesVotes() const
  {
    return m_centerVotes;
  }
 
  inline std::vector<vpImageCircle> getCircleCandidates() const
  {
    return m_circleCandidates;
  }
 
  inline std::vector<float> getCircleCandidatesProbabilities() const
  {
    return m_circleCandidatesProbabilities;
  }
 
  inline std::vector<unsigned int> getCircleCandidatesVotes() const
  {
    return m_circleCandidatesVotes;
  }
 
  inline vpImage<float> getGradientX() const
  {
    return m_dIx;
  }
 
  inline vpImage<float> getGradientY() const
  {
    return m_dIy;
  }
 
  inline vpImage<unsigned char> getEdgeMap() const
  {
    return m_edgeMap;
  }
 
  inline float getCannyThreshold() const
  {
    return m_algoParams.m_upperCannyThresh;
  }
 
  inline float getCircleCenterMinDist() const
  {
    return m_algoParams.m_centerMinDist;
  }
 
  inline float getCircleMinRadius() const
  {
    return m_algoParams.m_minRadius;
  }
 
  inline float getCircleMaxRadius() const
  {
    return m_algoParams.m_maxRadius;
  }
 
  inline std::vector<float> getDetectionsProbabilities() const
  {
    return m_finalCirclesProbabilities;
  }
 
  inline std::vector<unsigned int> getDetectionsVotes() const
  {
    return m_finalCircleVotes;
  }
 
  std::string toString() const;
 
  friend VISP_EXPORT std::ostream &operator<<(std::ostream &os, const vpCircleHoughTransform &detector);
 
  static const unsigned char edgeMapOn;
  static const unsigned char edgeMapOff;
 
protected:
  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();
 
  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);
 
  vpCircleHoughTransformParameters m_algoParams; 
  // // Gaussian smoothing attributes
  vpArray2D<float> m_fg;
 
  // // Gradient computation attributes
  const vpImage<bool> *mp_mask; 
  vpArray2D<float> m_gradientFilterX; 
  vpArray2D<float> m_gradientFilterY; 
  vpImage<float> m_dIx; 
  vpImage<float> m_dIy; 
  // // Edge detection attributes
  vpCannyEdgeDetection m_cannyVisp; 
  vpImage<unsigned char> m_edgeMap; 
  // // Center candidates computation attributes
  std::vector<std::pair<unsigned int, unsigned int> > m_edgePointsList; 
  std::vector<std::pair<float, float> > m_centerCandidatesList; 
  std::vector<int> m_centerVotes; 
  // // Circle candidates computation attributes
  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; 
  // // Circle candidates merging attributes
  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; 
};
#endif