Clarified use of Hough functions, and added example program comparing Hough and Radon for circles.

Author: crisluengo

examples/CMakeLists.txt

@@ -136,6 +136,10 @@ if(DIP_BUILD_DIPVIEWER)
    target_compile_definitions(blend_images PRIVATE DIP_EXAMPLES_DIR="${CMAKE_CURRENT_LIST_DIR}")
    target_link_libraries(blend_images DIP DIPviewer)
 
+   # An example program that shows how to use dip::FindHoughCircles and dip::RadonTransformCircles, and use dip::viewer::Show
+   add_executable(detect_circles cpp/detect_circles.cpp)
+   target_link_libraries(detect_circles DIP DIPviewer)
+
    add_dependencies(examples
                     viewer
                     display

examples/cpp/detect_circles.cpp

@@ -0,0 +1,71 @@
+/*
+ * This program shows how to use dip::FindHoughCircles and dip::RadonTransformCircles.
+ * It displays some images using dip::viewer::Show, and sets display properties.
+ */
+
+#include "diplib.h"
+#include "diplib/analysis.h"
+#include "diplib/detection.h"
+#include "diplib/generation.h"
+#include "diplib/linear.h"
+#include "diplib/mapping.h"
+#include "diplib/math.h"
+
+#include "dipviewer.h"
+#include "diplib/viewer/slice.h"
+#include "diplib/viewer/viewer.h"
+
+
+int main() {
+   // Create a test image
+   dip::Image img = dip::Image( { 256, 256 }, 1 );
+   std::cout << "Ground-truth:\n";
+   dip::FloatArray center = { 117.73, 133.10 };
+   double radius = 100.72;
+   std::cout << "  - circle at (" << center[ 0 ] << ", " << center[ 1 ] << "), radius " << radius << '\n';
+   dip::DrawBandlimitedBall( img, radius * 2, center, { 255 } );
+   dip::Random rng;
+   dip::GaussianNoise( img, img, rng, 5 ); // A small amount of noise
+   dip::viewer::Show( img, "input image" );
+
+   // Compute gradient and mask
+   dip::Image gv = dip::Gradient( img );
+   dip::viewer::Show( gv, "gradient image" );
+   dip::Image gm = dip::Norm( gv );
+   dip::Image mask = gm > 40;
+   dip::viewer::Show( mask, "mask image" );
+
+   // Compute Hough circles
+   auto hough = dip::FindHoughCircles( mask, gv, { 50, 150 } );
+
+   // Compose output
+   dip::Image out = img.Similar();
+   out.Fill( 0 );
+   std::cout << "Detected by Hough:\n";
+   for( auto v : hough ) {
+      std::cout << "  - circle at (" << v[ 0 ] << ", " << v[ 1 ] << "), radius " << v[ 2 ] << '\n';
+      dip::DrawBandlimitedBall( out, v[ 2 ] * 2, { v[ 0 ], v[ 1 ] }, { 255 } );
+   }
+   dip::viewer::Show( out, "Hough detected circles" );
+   auto h = dip::viewer::Show( out - img, "difference Hough - input" );
+   h->options().lut_ = dip::viewer::ViewingOptions::LookupTable::Divergent;
+   h->options().mapping_range_ = { -100, 100 };
+
+   // Compute Radon circles
+   // NOTE! `out` is not used in the call below because we added "no parameter space" to the options.
+   auto radon = dip::RadonTransformCircles( gm, out, { 50, 150, 1 }, 1.0, 100.0, "full", { "normalize", "correct", "no parameter space" } );
+
+   // Compose output
+   out.Fill( 0 );
+   std::cout << "Detected by Radon:\n";
+   for( auto v : radon ) {
+      std::cout << "  - circle at (" << v.origin[ 0 ] << ", " << v.origin[ 1 ] << "), radius " << v.radius << '\n';
+      dip::DrawBandlimitedBall( out, v.radius * 2, v.origin, { 255 } );
+   }
+   dip::viewer::Show( out, "Radon detected circles" );
+   h = dip::viewer::Show( out - img, "difference Radon - input" );
+   h->options().lut_ = dip::viewer::ViewingOptions::LookupTable::Divergent;
+   h->options().mapping_range_ = { -100, 100 };
+
+   dip::viewer::Spin();
+}

include/diplib/detection.h

@@ -1,5 +1,6 @@
 /*
- * (c)2018-2021, Cris Luengo.
+ * (c)2017, Wouter Caarls.
+ * (c)2018-2025, Cris Luengo.
  * Based on original DIPlib code: (c)1995-2014, Delft University of Technology.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -53,12 +54,19 @@ namespace dip {
 
 /// \brief Hough transform for circles in 2D binary images.
 ///
-/// Computes the Hough parameter space for circles in 2D images, with the radius dimension collapsed.
-/// The parameter space `out` has the same sizes as the binary input image `in`. `gv` is a vector image
-/// of the same sizes as `in`, with the gradient vector for each pixel of `in`.
+/// Computes the Hough parameter space for circles in 2D binary images, with the radius dimension collapsed.
+/// The parameter space `out` has the same sizes as the input image `in`.
+///
+/// `gv` is a vector image of the same sizes as `in`, with 2D vectors that point normal to the circle at
+/// each pixel in `in`.
+/// This version of the algorithm does not draw a full cone in a 3D parameter space (x, y, r) for each
+/// set pixel in the input, but draws a line along the normal in a 2D parameter space (x, y).
+/// The magnitude of the vector is used as weight, meaning that the length of the vector can be used
+/// to encode confidence in the direction. See \ref dip::FindHoughCircles for an example how to generate
+/// the input images.
 ///
 /// `range` must be empty, or have exactly two elements representing the minimum and maximum radius to
-/// be considered. If empty, the minimum radius is 0, and the maximum is the length of the image diagonal.
+//. be considered. If empty, the minimum radius is 0, and the maximum is the length of the image diagonal.
 DIP_EXPORT void HoughTransformCircleCenters(
       Image const& in,
       Image const& gv,
@@ -106,14 +114,24 @@ DIP_EXPORT Distribution PointDistanceDistribution(
 /// using \ref dip::HoughTransformCircleCenters, and then a radius is calculated for each center. Note that
 /// only a single radius is returned per center coordinates.
 ///
-/// `gv` is a vector image of the same sizes as `in`, with the gradient vector for each pixel of `in`.
+/// `gv` is a vector image of the same sizes as `in`, with 2D vectors that point normal to the circle at
+/// each pixel in `in`. See \ref dip::HoughTransformCircleCenters for details.
 ///
 /// `range` must be empty, or have exactly two elements representing the minimum and maximum radius to
 /// be considered. If empty, the minimum radius is 0, and the maximum is the length of the image diagonal.
 ///
 /// `distance` is the minimum distance between centers, used to suppress noisy results.
 /// `fraction` is the minimum height of a peak in the Hough transform, with respect to the largest peak,
 /// that should be considered, again to suppress noisy results.
+///
+/// The output array contains three values per circle found: the x and y coordinates, and the radius.
+///
+/// Example usage:
+/// ```cpp
+/// dip::Image gv = dip::Gradient( img );
+/// dip::Image mask = dip::Norm( gv ) > 10; // Some threshold that removes irrelevant gradients, keeping only significant edges
+/// auto hough = dip::FindHoughCircles( mask, gv, { 50, 150 } );
+/// ```
 DIP_EXPORT FloatCoordinateArray FindHoughCircles(
       Image const& in,
       Image const& gv,
@@ -122,6 +140,7 @@ DIP_EXPORT FloatCoordinateArray FindHoughCircles(
       dfloat fraction = 0.1
 );
 
+
 /// \brief Stores the parameters for one hypersphere (circle, sphere).
 struct RadonCircleParameters{
    FloatArray origin;   ///< Coordinates of the origin of the hypersphere
@@ -184,7 +203,7 @@ using RadonCircleParametersArray = std::vector< RadonCircleParameters >;
 ///     - C.L. Luengo Hendriks, M. van Ginkel and L.J. van Vliet,
 ///       "Underestimation of the radius in the Radon transform for circles and spheres",
 ///       Technical Report PH-2003-02, Pattern Recognition Group, Delft University of Technology, The Netherlands, 2003.
-// TODO: If `mode` is `"full"`, then the parameter space is computed chunks to save memory.
+// TODO: If `mode` is `"full"`, then the parameter space is computed in chunks to save memory.
 DIP_EXPORT RadonCircleParametersArray RadonTransformCircles(
       Image const& in,
       Image& out,
@@ -209,9 +228,9 @@ DIP_NODISCARD inline Image RadonTransformCircles(
    return out;
 }
 
-
 /// \endgroup
 
+
 /// \group detection_corners Corner detectors
 /// \ingroup detection
 /// \brief Corner detection algorithms