vpImageFilter_canny.cpp

/*
 * 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.
 *
 * Description:
 * Image Canny filtering.
 */
 
#include <visp3/core/vpConfig.h>
#include <visp3/core/vpImageFilter.h>
#include <visp3/core/vpIoTools.h>
#include <visp3/core/vpCannyEdgeDetection.h>
 
BEGIN_VISP_NAMESPACE

std::string vpImageFilter::vpCannyBackendTypeList(const std::string &pref, const std::string &sep,
                                                  const std::string &suf)
{
  std::string list(pref);
  for (unsigned int i = 0; i < (CANNY_COUNT_BACKEND - 1); ++i) {
    vpCannyBackendType type = static_cast<vpCannyBackendType>(i);
    list += vpCannyBackendTypeToString(type);
    list += sep;
  }
  vpCannyBackendType type = static_cast<vpCannyBackendType>(CANNY_COUNT_BACKEND - 1);
  list += vpCannyBackendTypeToString(type);
  list += suf;
  return list;
}

std::string vpImageFilter::vpCannyBackendTypeToString(const vpImageFilter::vpCannyBackendType &type)
{
  std::string name;
  switch (type) {
  case CANNY_OPENCV_BACKEND:
    name = "opencv-backend";
    break;
  case CANNY_VISP_BACKEND:
    name = "visp-backend";
    break;
  case CANNY_COUNT_BACKEND:
    return "unknown-backend";
  default: {
    throw(vpException(vpException::fatalError, "Unsupported canny backend type in vpImageFilter::vpCannyBackendTypeToString()"));
  }
  }
  return name;
}

vpImageFilter::vpCannyBackendType vpImageFilter::vpCannyBackendTypeFromString(const std::string &name)
{
  vpCannyBackendType type(CANNY_COUNT_BACKEND);
  std::string nameLowerCase = vpIoTools::toLowerCase(name);
  unsigned int count = static_cast<unsigned int>(CANNY_COUNT_BACKEND);
  bool notFound = true;
  unsigned int i = 0;
  while ((i < count) && notFound) {
    vpCannyBackendType temp = static_cast<vpCannyBackendType>(i);
    if (nameLowerCase == vpCannyBackendTypeToString(temp)) {
      type = temp;
      notFound = false;
    }
    ++i;
  }
  return type;
}

std::string vpImageFilter::vpGetCannyFiltAndGradTypes(const std::string &pref, const std::string &sep,
                                                               const std::string &suf)
{
  std::string list(pref);
  for (unsigned int i = 0; i < (CANNY_COUNT_FILTERING - 1); ++i) {
    vpCannyFilteringAndGradientType type = static_cast<vpCannyFilteringAndGradientType>(i);
    list += vpCannyFiltAndGradTypeToStr(type);
    list += sep;
  }
  vpCannyFilteringAndGradientType type = static_cast<vpCannyFilteringAndGradientType>(CANNY_COUNT_FILTERING - 1);
  list += vpCannyFiltAndGradTypeToStr(type);
  list += suf;
  return list;
}

std::string vpImageFilter::vpCannyFiltAndGradTypeToStr(const vpImageFilter::vpCannyFilteringAndGradientType &type)
{
  std::string name;
  switch (type) {
  case CANNY_GBLUR_SOBEL_FILTERING:
    name = "gaussianblur+sobel-filtering";
    break;
  case CANNY_GBLUR_SCHARR_FILTERING:
    name = "gaussianblur+scharr-filtering";
    break;
  case CANNY_COUNT_FILTERING:
    return "unknown-filtering";
  default: {
    throw(vpException(vpException::fatalError, "Unsupported canny backend type in vpImageFilter::vpCannyFiltAndGradTypeToStr()"));
  }
  }
  return name;
}

vpImageFilter::vpCannyFilteringAndGradientType vpImageFilter::vpCannyFiltAndGradTypeFromStr(const std::string &name)
{
  vpCannyFilteringAndGradientType type(CANNY_COUNT_FILTERING);
  std::string nameLowerCase = vpIoTools::toLowerCase(name);
  unsigned int count = static_cast<unsigned int>(CANNY_COUNT_FILTERING);
  bool notFound = true;
  unsigned int i = 0;
  while ((i < count) && notFound) {
    vpCannyFilteringAndGradientType temp = static_cast<vpCannyFilteringAndGradientType>(i);
    if (nameLowerCase == vpCannyFiltAndGradTypeToStr(temp)) {
      type = temp;
      notFound = false;
    }
    ++i;
  }
  return type;
}
 
#if defined(VISP_HAVE_OPENCV) && defined(HAVE_OPENCV_IMGPROC)
float vpImageFilter::computeCannyThreshold(const cv::Mat &cv_I, const cv::Mat *p_cv_dIx, const cv::Mat *p_cv_dIy,
                                           float &lowerThresh, const unsigned int &gaussianKernelSize,
                                           const float &gaussianStdev, const unsigned int &apertureGradient,
                                           const float &lowerThresholdRatio, const float &upperThresholdRatio,
                                           const vpImageFilter::vpCannyFilteringAndGradientType &filteringType)
{
  if ((lowerThresholdRatio <= 0.f) || (lowerThresholdRatio >= 1.f)) {
    std::stringstream errMsg;
    errMsg << "Lower ratio (" << lowerThresholdRatio << ") " << (lowerThresholdRatio < 0.f ? "should be greater than 0 !" : "should be lower than 1 !");
    throw(vpException(vpException::fatalError, errMsg.str()));
  }
 
  if ((upperThresholdRatio <= 0.f) || (upperThresholdRatio >= 1.f)) {
    std::stringstream errMsg;
    errMsg << "Upper ratio (" << upperThresholdRatio << ") " << (upperThresholdRatio < 0.f ? "should be greater than 0 !" : "should be lower than 1 !");
    throw(vpException(vpException::fatalError, errMsg.str()));
  }
 
  if (lowerThresholdRatio  >= upperThresholdRatio) {
    std::stringstream errMsg;
    errMsg << "Lower ratio (" << lowerThresholdRatio << ") should be lower than the upper ratio (" << upperThresholdRatio << ")";
    throw(vpException(vpException::fatalError, errMsg.str()));
  }
 
  double w = cv_I.cols;
  double h = cv_I.rows;
  int bins = 256;
  cv::Mat dI, dIx, dIy, dIx_abs, dIy_abs;
 
  if ((p_cv_dIx == nullptr) || (p_cv_dIy == nullptr)) {
    computePartialDerivatives(cv_I, dIx, dIy, true, true, true, gaussianKernelSize, gaussianStdev, apertureGradient,
                              filteringType);
  }
  else {
    dIx = *p_cv_dIx;
    dIy = *p_cv_dIy;
  }
 
  // Compute the absolute gradient of the blurred image G = |dIx| + |dIy|
  cv::convertScaleAbs(dIx, dIx_abs);
  cv::convertScaleAbs(dIy, dIy_abs);
  cv::addWeighted(dIx_abs, 1, dIy_abs, 1, 0, dI);
  dI.convertTo(dI, CV_8U);
 
  // Compute the upper threshold from the equalized histogram
  cv::Mat hist;
  const float range[] = { 0.f, 256.f }; // The upper boundary is exclusive
  const float *ranges[] = { range };
  int channels[] = { 0 };
  int dims = 1; // The number of dimensions of the histogram
  int histSize[] = { bins };
  bool uniform = true;
  bool accumulate = false; // Clear the histogram at the beginning of calcHist if false, does not clear it otherwise
  cv::calcHist(&dI, 1, channels, cv::Mat(), hist, dims, histSize, ranges, uniform, accumulate);
  float accu = 0;
  float t = static_cast<float>(upperThresholdRatio * w * h);
  float tLow = static_cast<float>(lowerThresholdRatio * w * h);
  float bon = 0;
  int i = 0;
  bool notFound = true, notFoundLower = true;
  while ((i < bins) && notFound) {
    float tf = hist.at<float>(i);
    accu = accu + tf;
    if ((accu > tLow) && notFoundLower) {
      lowerThresh = static_cast<float>(i);
      notFoundLower = false;
    }
    if (accu > t) {
      bon = static_cast<float>(i);
      notFound = false;
    }
    ++i;
  }
  if (notFound) {
    std::stringstream errMsg;
    errMsg << "Could not find a bin for which " << upperThresholdRatio * 100.f << " percents of the pixels had a gradient lower than the upper threshold.";
    throw(vpException(vpException::fatalError, errMsg.str()));
  }
  float upperThresh = std::max<float>(bon, 1.f);
  return upperThresh;
}
#endif

void vpImageFilter::canny(const vpImage<unsigned char> &Isrc, vpImage<unsigned char> &Ires,
                          const unsigned int &gaussianFilterSize, const float &thresholdCanny,
                          const unsigned int &apertureSobel)
{
  vpImageFilter::canny(Isrc, Ires, gaussianFilterSize, thresholdCanny / 3.f, thresholdCanny, apertureSobel);
}

void vpImageFilter::canny(const vpImage<unsigned char> &Isrc, vpImage<unsigned char> &Ires,
                          const unsigned int &gaussianFilterSize,
                          const float &lowerThreshold, const float &upperThreshold,
                          const unsigned int &apertureSobel)
{
  const float gaussianStdev = 2.f;
  const float upperThresholdRatio = 0.8f;
  const float lowerThresholdRatio = 0.6f;
#if defined(HAVE_OPENCV_IMGPROC)
  const vpCannyBackendType cannyBackend = CANNY_OPENCV_BACKEND;
#else
  const vpCannyBackendType cannyBackend = CANNY_VISP_BACKEND;
#endif
  const vpCannyFilteringAndGradientType cannyFilteringSteps = CANNY_GBLUR_SOBEL_FILTERING;
  canny(Isrc, Ires, gaussianFilterSize, lowerThreshold, upperThreshold, apertureSobel,
        gaussianStdev, lowerThresholdRatio, upperThresholdRatio, false, cannyBackend, cannyFilteringSteps);
}

void vpImageFilter::canny(const vpImage<unsigned char> &Isrc, vpImage<unsigned char> &Ires,
                          const unsigned int &gaussianFilterSize,
                          const float &lowerThreshold, const float &upperThreshold, const unsigned int &apertureGradient,
                          const float &gaussianStdev, const float &lowerThresholdRatio, const float &upperThresholdRatio,
                          const bool &normalizeGradients,
                          const vpCannyBackendType &cannyBackend, const vpCannyFilteringAndGradientType &cannyFilteringSteps,
                          const vpImage<bool> *p_mask)
{
  if (cannyBackend == CANNY_OPENCV_BACKEND) {
#if defined(HAVE_OPENCV_IMGPROC)
    cv::Mat img_cvmat, cv_dx, cv_dy, edges_cvmat;
    vpImageConvert::convert(Isrc, img_cvmat);
    computePartialDerivatives(img_cvmat, cv_dx, cv_dy, true, true, normalizeGradients, gaussianFilterSize,
                              gaussianStdev, apertureGradient, cannyFilteringSteps);
    float upperCannyThresh = upperThreshold;
    float lowerCannyThresh = lowerThreshold;
    if (upperCannyThresh < 0.f) {
      upperCannyThresh = computeCannyThreshold(img_cvmat, &cv_dx, &cv_dy, lowerCannyThresh, gaussianFilterSize,
                                               gaussianStdev, apertureGradient, lowerThresholdRatio, upperThresholdRatio,
                                               cannyFilteringSteps);
    }
    else if (lowerCannyThresh < 0.f) {
      lowerCannyThresh = upperCannyThresh / 3.f;
    }
#if (VISP_HAVE_OPENCV_VERSION >= 0x030200)
    cv::Canny(cv_dx, cv_dy, edges_cvmat, lowerCannyThresh, upperCannyThresh, false);
#else
    cv::GaussianBlur(img_cvmat, img_cvmat, cv::Size(static_cast<int>(gaussianFilterSize), static_cast<int>(gaussianFilterSize)),
                     gaussianStdev, gaussianStdev);
    cv::Canny(img_cvmat, edges_cvmat, lowerCannyThresh, upperCannyThresh);
#endif
    vpImageConvert::convert(edges_cvmat, Ires);
#else
    std::string errMsg("[vpImageFilter::canny]You asked for CANNY_OPENCV_BACKEND but ViSP has not been compiled with OpenCV");
    throw(vpException(vpException::badValue, errMsg));
#endif
  }
  else if (cannyBackend == CANNY_VISP_BACKEND) {
    float upperCannyThresh = upperThreshold;
    float lowerCannyThresh = lowerThreshold;
 
    vpImage<float> dIx, dIy;
    computePartialDerivatives(Isrc, dIx, dIy, true, true, normalizeGradients, gaussianFilterSize,
                              gaussianStdev, apertureGradient, cannyFilteringSteps, cannyBackend, p_mask);
 
    if (upperCannyThresh < 0.f) {
      upperCannyThresh = computeCannyThreshold(Isrc, lowerCannyThresh, &dIx, &dIy, gaussianFilterSize, gaussianStdev,
                                               apertureGradient, lowerThresholdRatio, upperThresholdRatio,
                                               cannyFilteringSteps, p_mask);
    }
    else if (lowerCannyThresh < 0.f) {
      lowerCannyThresh = upperCannyThresh / 3.f;
    }
    vpCannyEdgeDetection edgeDetector(gaussianFilterSize, gaussianStdev, apertureGradient, lowerCannyThresh, upperCannyThresh,
                                      lowerThresholdRatio, upperThresholdRatio, cannyFilteringSteps);
    edgeDetector.setGradients(dIx, dIy);
    edgeDetector.setMask(p_mask);
    Ires = edgeDetector.detect(Isrc);
  }
}
 
END_VISP_NAMESPACE