Repository: scikit-image/scikit-image

Issue:
morphology.extrema.h_maxima and h_minima: slightly confusing function descriptions
## Description

Consider this very short piece of code:

```python
testimg = np.array([0, 1, 2, 3, 4, 3.5, 4, 5, 4, 3, 2, 1, 0])
morphology.h_maxima(testimg, 1)
morphology.h_maxima(testimg, 2)
morphology.h_maxima(testimg, 3)
```

The results show that the element with value 5 is always picked up by this function, even though it is not a local maximum with height h for any h; rather it is the global maximum, so will always satisfy the condition tested for by this function.

The function description should therefore mention that the global maximum is also included.  The same goes for the h_minima function.

Best wishes,

Julian

## Version information

As at GitHub commit https://github.com/scikit-image/scikit-image/commit/9fcb6c9d9cadb8efa6426f29c94ab59928f41761



Discussion:
thanks for reporting @juliangilbey In my mind, a global extremum is also a local extremum. (This page, randomly chosen from a search engine, is supporting it: https://brilliant.org/wiki/extrema/ )

Nevertheless, I agree, it would be helpful to add a note to these function to clarify this point. Would you like to submit a PR?
OK; shall do!  Indeed, a global extremum is also a local extremum, but the global maximum does not satisfy the definition of "local maximum of height h".

Resolving patch:
diff --git a/skimage/morphology/extrema.py b/skimage/morphology/extrema.py
--- a/skimage/morphology/extrema.py
+++ b/skimage/morphology/extrema.py
@@ -53,10 +53,13 @@ def h_maxima(image, h, selem=None):
     neighborhood of the set.
 
     A local maximum M of height h is a local maximum for which
-    there is at least one path joining M with a higher maximum on which the
-    minimal value is f(M) - h (i.e. the values along the path are not
-    decreasing by more than h with respect to the maximum's value) and no
-    path for which the minimal value is greater.
+    there is at least one path joining M with an equal or higher local maximum
+    on which the minimal value is f(M) - h (i.e. the values along the path
+    are not decreasing by more than h with respect to the maximum's value)
+    and no path to an equal or higher local maximum for which the minimal
+    value is greater.
+
+    The global maxima of the image are also found by this function.
 
     Parameters
     ----------
@@ -72,9 +75,9 @@ def h_maxima(image, h, selem=None):
     Returns
     -------
     h_max : ndarray
-       The maxima of height >= h. The resulting image is a binary image, where
-       pixels belonging to the selected maxima take value 1, the others
-       take value 0.
+       The local maxima of height >= h and the global maxima.
+       The resulting image is a binary image, where pixels belonging to
+       the determined maxima take value 1, the others take value 0.
 
     See also
     --------
@@ -178,10 +181,13 @@ def h_minima(image, h, selem=None):
     neighborhood of the set.
 
     A local minimum M of depth h is a local minimum for which
-    there is at least one path joining M with a deeper minimum on which the
-    maximal value is f(M) + h (i.e. the values along the path are not
-    increasing by more than h with respect to the minimum's value) and no
-    path for which the maximal value is smaller.
+    there is at least one path joining M with an equal or lower local minimum
+    on which the maximal value is f(M) + h (i.e. the values along the path
+    are not increasing by more than h with respect to the minimum's value)
+    and no path to an equal or lower local minimum for which the maximal
+    value is smaller.
+
+    The global minima of the image are also found by this function.
 
     Parameters
     ----------
@@ -197,9 +203,9 @@ def h_minima(image, h, selem=None):
     Returns
     -------
     h_min : ndarray
-       The minima of depth >= h. The resulting image is a binary image, where
-       pixels belonging to the selected minima take value 1, the other pixels
-       take value 0.
+       The local minima of depth >= h and the global minima.
+       The resulting image is a binary image, where pixels belonging to
+       the determined minima take value 1, the others take value 0.
 
     See also
     --------


Test patch: