Improve docstring of Hough transform function

[emmanuelle]

The docstring of the hough transform functions does not mention that the Hough transform should be applied to a gradient / contour image, so that one often has to perform first a Canny filter or a gaussian gradient magnitude operation. The doc example https://scikit-image.org/docs/dev/auto_examples/edges/plot_circular_elliptical_hough_transform.html?highlight=hough%20transform could also comment on this preprocessing operation (which is performed in the example with a Canny filter).

This issue was inspired by a question on the user forum https://forum.image.sc/t/elliptical-hough-transform-doesnt-work-on-own-images/47052

[alexdesiqueira]

Thank you for checking that issue, @emmanuelle.
I think this could go on a Notes section in each function. How does that sound?

[grlee77]

I think this could go on a Notes section in each function. How does that sound?

It sounds good, but I think the Image parameter itself, should be updated to make it clearer right up front for those who may not read all the way through to the Notes section. I.e. change the current

Input image with nonzero values representing edges.

to something like

Binary input image with nonzero values representing edges (skimage.feature.canny can be used to produce this type of binary edge map).).

[alexdesiqueira]

skimage.feature.canny can be used to produce this type of binary edge map.

I'd think it's nicer to maybe having something like that on the Notes as well, Greg. I think it'd clutter the docs too much there. I agree this would be nice to have:

Binary input image with nonzero values representing edges.

But I won't oppose if y'all prefer it like Greg suggested 🙂

[alessandro-giusti]

Also note that the Notes section of the hough_line function, two sentences are quite unclear. In paricular:

• X and Y axis are horizontal and vertical edges respectively.
• The distance is the minimal algebraic distance from the origin to the detected line.

In particular, the latter should make it clear that the distance might be negative.

scikit-image/skimage/transform/hough_transform.py

Line 192 in 8acad22

X and Y axis are horizontal and vertical edges respectively.

[mkcor]

I don't have a clear preference between @alexdesiqueira's and @grlee77's suggestions. I think it's even clearer to describe the image parameter as:

Binary input image where nonzero values represent edges.

[alexdesiqueira]

Thanks for that @alessandro-giusti, we'll check it out as well!
Works for me as well, @mkcor. Thank you!