vpCircleHoughTransform.h

/*
 * ViSP, open source Visual Servoing Platform software.
 * Copyright (C) 2005 - 2025 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 VP_CIRCLE_HOUGH_TRANSFORM_H
#define VP_CIRCLE_HOUGH_TRANSFORM_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 VISP_NLOHMANN_JSON(json.hpp)
#endif
 
#if ((__cplusplus >= 201703L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201703L))) // Check if cxx17 or higher
#include <optional>
#endif
 
BEGIN_VISP_NAMESPACE

class VISP_EXPORT vpCircleHoughTransform
{
public:
  class vpCircleHoughTransformParams
  {
  public:
    vpCircleHoughTransformParams()
      : m_filteringAndGradientType(vpImageFilter::CANNY_GBLUR_SOBEL_FILTERING)
      , m_gaussianStdev(1.f)
      , 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_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)
    {
      const unsigned int gaussianKernelSize_default = 5;
      const unsigned int gradientFilterKernelSize_default = 3;
      const unsigned int dilatationKernelSize_default = 3;
      const unsigned int averagingWindowSize_default = 5;
 
      m_gaussianKernelSize = gaussianKernelSize_default;
      m_gradientFilterKernelSize = gradientFilterKernelSize_default;
      m_dilatationKernelSize = dilatationKernelSize_default;
      m_averagingWindowSize = averagingWindowSize_default;
    }

    vpCircleHoughTransformParams(
      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::vpCannyFiltAndGradTypeToStr(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 = ";
      txt << (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 vpCircleHoughTransformParams 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());
      }
      vpCircleHoughTransformParams 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;
      const int indent = 4;
      file << j.dump(indent);
      file.close();
    }

    friend inline void from_json(const nlohmann::json &j, vpCircleHoughTransformParams &params)
    {
      std::string filteringAndGradientName = vpImageFilter::vpCannyFiltAndGradTypeToStr(params.m_filteringAndGradientType);
      filteringAndGradientName = j.value("filteringAndGradientType", filteringAndGradientName);
      params.m_filteringAndGradientType = vpImageFilter::vpCannyFiltAndGradTypeFromStr(filteringAndGradientName);
 
      params.m_gaussianKernelSize = j.value("gaussianKernelSize", params.m_gaussianKernelSize);
      const int checkEvenModulo = 2;
      if ((params.m_gaussianKernelSize % checkEvenModulo) != 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 % checkEvenModulo) != 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 % checkEvenModulo) == 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 vpCircleHoughTransformParams &params)
    {
      std::pair<float, float> radiusLimits = { params.m_minRadius, params.m_maxRadius };
 
      j = nlohmann::json {
          {"filteringAndGradientType", vpImageFilter::vpCannyFiltAndGradTypeToStr(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
    friend VISP_EXPORT bool operator==(const vpImageCircle &a, const vpImageCircle &b);
 
  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;
  };
 
#ifdef VISP_BUILD_DEPRECATED_FUNCTIONS
  typedef vpCircleHoughTransformParams vpCircleHoughTransformParameters;
#endif
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS
  typedef struct vpCenterVotes
  {
    std::pair<float, float> m_position;
    float m_votes;
  } vpCenterVotes;
#endif

  vpCircleHoughTransform();

  VP_EXPLICIT vpCircleHoughTransform(const vpCircleHoughTransformParams &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 ((__cplusplus >= 201703L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201703L))) // Check if cxx17 or higher
  inline 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
  inline 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
  {
    if (!m_algoParams.m_recordVotingPoints) {
      // We weren't asked to remember the voting points
#if ((__cplusplus >= 201703L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201703L))) // Check if cxx17 or higher
      mask = std::nullopt;
      opt_votingPoints = std::nullopt;
#else
      *mask = nullptr;
      *opt_votingPoints = nullptr;
#endif
      return;
    }
 
#if ((__cplusplus >= 201703L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201703L))) // Check if cxx17 or higher
    mask = vpImage<bool>(I.getHeight(), I.getWidth(), false);
    opt_votingPoints = std::vector<std::vector<std::pair<unsigned int, unsigned int>>>();
#else
    *mask = new vpImage<bool>(I.getHeight(), I.getWidth(), false);
    *opt_votingPoints = new std::vector<std::vector<std::pair<unsigned int, unsigned int> > >();
#endif
 
#if ((__cplusplus >= 201703L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201703L))) // Check if cxx17 or higher
    for (const auto &detection : detections)
#else
    const size_t nbDetections = detections.size();
    for (size_t i = 0; i < nbDetections; ++i)
#endif
    {
      bool hasFoundSimilarCircle = false;
      unsigned int nbPreviouslyDetected = static_cast<unsigned int>(m_finalCircles.size());
      unsigned int id = 0;
      // Looking for a circle that was detected and is similar to the one given to the function
      while ((id < nbPreviouslyDetected) && (!hasFoundSimilarCircle)) {
        const vpImageCircle previouslyDetected = m_finalCircles[id];
#if ((__cplusplus >= 201703L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201703L))) // Check if cxx17 or higher
        if (previouslyDetected == detection)
#else
        if (previouslyDetected == detections[i])
#endif
        {
          hasFoundSimilarCircle = true;
          // We found a circle that is similar to the one given to the function => updating the mask
          const unsigned int nbVotingPoints = static_cast<unsigned int>(m_finalCirclesVotingPoints[id].size());
          for (unsigned int idPoint = 0; idPoint < nbVotingPoints; ++idPoint) {
            const std::pair<unsigned int, unsigned int> &votingPoint = m_finalCirclesVotingPoints[id][idPoint];
#if ((__cplusplus >= 201703L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201703L))) // Check if cxx17 or higher
            (*mask)[votingPoint.first][votingPoint.second] = true;
#else
            (**mask)[votingPoint.first][votingPoint.second] = true;
#endif
          }
#if ((__cplusplus >= 201703L) || (defined(_MSVC_LANG) && (_MSVC_LANG >= 201703L))) // Check if cxx17 or higher
          opt_votingPoints->push_back(m_finalCirclesVotingPoints[id]);
#else
          (**opt_votingPoints).push_back(m_finalCirclesVotingPoints[id]);
#endif
        }
        ++id;
      }
    }
  }

#ifdef VISP_HAVE_NLOHMANN_JSON
  VP_EXPLICIT 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 vpCircleHoughTransformParams &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;
 
    const unsigned int checkEvenModulo = 2;
    if ((m_algoParams.m_gaussianKernelSize % checkEvenModulo) != 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;
 
    const unsigned int checkEvenModulo = 2;
    if ((m_algoParams.m_gradientFilterKernelSize % checkEvenModulo) != 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;
 
    const int minDilatationKernel = 3;
    const unsigned int checkEvenModulo = 2;
    if (m_algoParams.m_dilatationKernelSize < minDilatationKernel) {
      throw vpException(vpException::badValue, "Dilatation kernel size for center detection must be greater or equal to 3.");
    }
    else if ((m_algoParams.m_dilatationKernelSize % checkEvenModulo) == 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 % checkEvenModulo) == 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 void setMask(const vpImage<bool> *mask)
  {
    mp_mask = mask;
  }

  inline void setRecordVotingPoints(const bool &record)
  {
    m_algoParams.m_recordVotingPoints = record;
  }



  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;
  }

  inline std::vector<std::vector<std::pair<unsigned int, unsigned int> > > getDetectionsVotingPoints() const
  {
    if (!m_algoParams.m_recordVotingPoints) {
      throw(vpException(vpException::fatalError, "Asking voting points when it was not asked to remember them."));
    }
    return m_finalCirclesVotingPoints;
  }

  inline bool getRecordVotingPoints() const
  {
    return m_algoParams.getRecordVotingPoints();
  }


  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:
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS
  typedef struct vpCentersBarycenter
  {
    std::pair<float, float> m_position; 
    float m_totalVotes; 
    float m_nbElectors; 
  }vpCentersBarycenter;

  typedef struct vpCoordinatesForAccumStep
  {
    float x_orig;
    float y_orig;
    int x;
    int y;
  }vpCoordinatesForAccumStep;

  typedef struct vpDataForAccumLoop
  {
    unsigned int r; 
    unsigned int c; 
    float minRadius; 
    float maxRadius; 
    float minimumXpositionFloat; 
    float minimumYpositionFloat; 
    float maximumXpositionFloat; 
    float maximumYpositionFloat; 
    int offsetX; 
    int offsetY; 
    int accumulatorWidth; 
    int accumulatorHeight; 
  }vpDataForAccumLoop;
#endif

  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);
 
  vpCircleHoughTransformParams 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; 
};
 
END_VISP_NAMESPACE
 
#endif