API: disk vs circle vs circle_perimeter

[sciunto]

Description

In morphology disk means a full circle
In Hough transform circle means the edge of a circle
In draw.circle means a full circle
In draw.circle_perimeter and draw.circle_perimeter_aa circle perimeter means the edge of a circle.
In measure circleModel, circle means edge of a circle
In measure circle_level_set circle is a full circle.

I admit this can be disturbing.

I recommend to rename

• draw.circle -> draw.disk (MAINT: rename draw.circle() to draw.disk() #4428)
• draw.circle_perimeter -> draw.circle
• draw.circle_perimeter_aa -> draw.circle_aa
• skimage.segmentation.circle_level_set -> skimage.segmentation.disk_level_set (MAINT: replace circle_level_set by disk_level_set #4421)

In my mind, disk = circle filled up with pixels, circle = mathematical line.

What do you think @scikit-image/core

[jni]

@sciunto I'm 👍 on this proposal! Great catch(es)!

[hmaarrfk]

How will you handle the deprecation cycle for the new circle? Will you do it in a single shot or two?

[alexdesiqueira]

Great catches indeed @sciunto, one more step for our consistency!

[sciunto]

@hmaarrfk Good question. The number/type of arguments for the new disk and the new circle functions are the same. Therefore, it's hard to detect users who have an outdated code, embarrassing for a single shot.

I would suggest:

• Step 1: warn that draw.circle is deprecated. Implement draw.disk. (For 2 versions).
• Step 2: move the code in draw.circle_perimeter in draw.circle. Deprecated the old function. (For 2 versions).

I think this will give the best user experience.

[hmaarrfk]

See PR #4462 por favor! Which addresses a few warnings introduced by the first few PRs.

[stefanv]

What is the plan for implementing perimeter drawing now?

[hmaarrfk]

I think it is:

1. Keep the status quo until 2021
2. In 2021 deprecate circle_perimeer in favor of circle

[alexdesiqueira]

See PR #4462 por favor!

I guess this comment was written specifically for me :)

[stefanv]

I think it is:

1. Keep the status quo until 2021

2. In 2021 deprecate circle_perimeer in favor of circle

And, there will be a keyword parameter on circle?