Deprecate threshold_(abs|rel) in favor of threshold

lagru · lagru · commit e822781bf0f4 · 2026-02-09T19:48:44.000+01:00
Note, that `threshold_rel=0` is equivalent to `threshold=0`, since
`image.max() * 0 == 0`.
diff --git a/TODO.txt b/TODO.txt
@@ -27,6 +27,8 @@ Version 0.27
 Version 0.29
 ------------
 * Complete deprecation of `threshold_rel` in `skimage.feature.blob_*` functions
+* Complete deprecation of `threshold_abs` and `threshold_rel` in
+  `skimage.feature.peak_local_max`. Remove `skimage.feature.peak._get_threshold`.
 
 Other
 -----
diff --git a/src/skimage/feature/blob.py b/src/skimage/feature/blob.py
@@ -14,7 +14,7 @@
 )
 from ..transform import integral_image
 from ._hessian_det_appx import _hessian_matrix_det
-from .peak import peak_local_max
+from .peak import peak_local_max, _get_threshold
 
 # This basic blob detection algorithm is based on:
 # http://www.cs.utah.edu/~jfishbau/advimproc/project1/ (04.04.2013)
@@ -381,8 +381,9 @@ def blob_dog(
     The radius of each blob is approximately :math:`\sqrt{2}\sigma` for
     a 2-D image and :math:`\sqrt{3}\sigma` for a 3-D image.
     """
-    if threshold_rel is DEPRECATED:
-        threshold_rel = None
+    if threshold_rel is not DEPRECATED:
+        # Maintain backwards-compatible behavior of `threshold_rel` during deprecation
+        threshold = _get_threshold(image, threshold, threshold_rel)
 
     image = _rescale_value_range(image, mode=prescale)
     float_dtype = _supported_float_type(image.dtype)
@@ -428,8 +429,7 @@ def blob_dog(
     exclude_border = _format_exclude_border(image.ndim, exclude_border)
     local_maxima = peak_local_max(
         dog_image_cube,
-        threshold_abs=threshold,
-        threshold_rel=threshold_rel,
+        threshold=threshold,
         exclude_border=exclude_border,
         footprint=np.ones((3,) * (image.ndim + 1)),
     )
@@ -595,8 +595,9 @@ def blob_log(
     The radius of each blob is approximately :math:`\sqrt{2}\sigma` for
     a 2-D image and :math:`\sqrt{3}\sigma` for a 3-D image.
     """
-    if threshold_rel is DEPRECATED:
-        threshold_rel = None
+    if threshold_rel is not DEPRECATED:
+        # Maintain backwards-compatible behavior of `threshold_rel` during deprecation
+        threshold = _get_threshold(image, threshold, threshold_rel)
 
     image = _rescale_value_range(image, mode=prescale)
     float_dtype = _supported_float_type(image.dtype)
@@ -632,8 +633,7 @@ def blob_log(
     exclude_border = _format_exclude_border(image.ndim, exclude_border)
     local_maxima = peak_local_max(
         image_cube,
-        threshold_abs=threshold,
-        threshold_rel=threshold_rel,
+        threshold=threshold,
         exclude_border=exclude_border,
         footprint=np.ones((3,) * (image.ndim + 1)),
     )
@@ -794,8 +794,9 @@ def blob_doh(
     this method can't be used for detecting blobs of radius less than `3px`
     due to the box filters used in the approximation of Hessian Determinant.
     """
-    if threshold_rel is DEPRECATED:
-        threshold_rel = None
+    if threshold_rel is not DEPRECATED:
+        # Maintain backwards-compatible behavior of `threshold_rel` during deprecation
+        threshold = _get_threshold(image, threshold, threshold_rel)
 
     check_nD(image, 2)
 
@@ -817,8 +818,7 @@ def blob_doh(
 
     local_maxima = peak_local_max(
         image_cube,
-        threshold_abs=threshold,
-        threshold_rel=threshold_rel,
+        threshold=threshold,
         exclude_border=False,
         footprint=np.ones((3,) * image_cube.ndim),
     )
diff --git a/src/skimage/feature/corner.py b/src/skimage/feature/corner.py
@@ -12,7 +12,7 @@
 from ..util import img_as_float
 from ._hessian_det_appx import _hessian_matrix_det
 from .corner_cy import _corner_fast, _corner_moravec, _corner_orientations
-from .peak import peak_local_max
+from .peak import peak_local_max, _get_threshold
 from .util import _prepare_grayscale_input_2D, _prepare_grayscale_input_nD
 
 
@@ -1204,12 +1204,14 @@ def corner_peaks(
     if np.isinf(num_peaks_per_label):
         num_peaks_per_label = None
 
+    # Maintain backwards-compatible behavior of `threshold_rel` during deprecation
+    threshold = _get_threshold(image, threshold_abs, threshold_rel)
+
     # Get the coordinates of the detected peaks
     coords = peak_local_max(
         image,
         min_distance=min_distance,
-        threshold_abs=threshold_abs,
-        threshold_rel=threshold_rel,
+        threshold=threshold,
         exclude_border=exclude_border,
         num_peaks=None,  # Limiting to `num_peaks` is done in this function
         footprint=footprint,
diff --git a/src/skimage/feature/peak.py b/src/skimage/feature/peak.py
@@ -6,21 +6,52 @@
 from .. import measure
 from ..util import PendingSkimage2Change
 from .._shared._warnings import warn_external
+from .._shared.utils import deprecate_parameter, DEPRECATED
 
 import skimage2 as ski2
 
 
+def _get_threshold(image, threshold_abs, threshold_rel):
+    """Return the threshold value according to an absolute and a relative
+    value.
+
+    """
+    threshold = threshold_abs if threshold_abs is not None else image.min()
+
+    if threshold_rel is not None:
+        threshold = max(threshold, threshold_rel * image.max())
+
+    return threshold
+
+
+@deprecate_parameter(
+    "threshold_rel",
+    start_version="0.27",
+    stop_version="0.29",
+    template="Parameter `{deprecated_name}` is deprecated since version "
+    "{deprecated_version} and will be removed in {changed_version} (or later). "
+    "To avoid this warning, use `threshold=image.max() * threshold_rel` instead. "
+    "For more details, see the documentation of `{func_name}`.",
+)
+@deprecate_parameter(
+    "threshold_abs",
+    new_name="threshold",
+    start_version="0.27",
+    stop_version="0.29",
+)
 def peak_local_max(
     image,
     min_distance=1,
-    threshold_abs=None,
-    threshold_rel=None,
+    threshold_abs=DEPRECATED,
+    threshold_rel=DEPRECATED,
     exclude_border=True,
     num_peaks=None,
     footprint=None,
     labels=None,
     num_peaks_per_label=None,
     p_norm=np.inf,
+    *,
+    threshold=None,
 ):
     """Find peaks in an image as coordinate list.
 
@@ -43,12 +74,16 @@ def peak_local_max(
     min_distance : int, optional
         The minimal allowed distance separating peaks. To find the
         maximum number of peaks, use `min_distance=1`.
-    threshold_abs : float or None, optional
-        Minimum intensity of peaks. By default, the absolute threshold is
-        the minimum intensity of the image.
-    threshold_rel : float or None, optional
-        Minimum intensity of peaks, calculated as
-        ``max(image) * threshold_rel``.
+    threshold_abs : DEPRECATED
+
+        .. deprecated:: 0.27
+            Use `threshold` instead.
+
+    threshold_rel : DEPRECATED
+
+        .. deprecated:: 0.27
+             Use `threshold=image.max() * threshold_rel` instead.
+
     exclude_border : int, tuple of ints, or bool, optional
         Control peak detection close to the border of `image`.
 
@@ -79,6 +114,9 @@ def peak_local_max(
         A finite large p may cause a ValueError if overflow can occur.
         ``inf`` corresponds to the Chebyshev distance and 2 to the
         Euclidean distance.
+    threshold : float, optional
+        Minimum intensity of peaks. By default, the absolute threshold is
+        the minimum intensity of the image.
 
     Returns
     -------
@@ -176,6 +214,11 @@ def peak_local_max(
             category=FutureWarning,
         )
 
+    assert threshold_abs in (DEPRECATED, deprecate_parameter.DEPRECATED_GOT_VALUE)
+    if threshold_rel is not DEPRECATED:
+        # Maintain backwards-compatible behavior of `threshold_rel` during deprecation
+        threshold = _get_threshold(image, threshold, threshold_rel)
+
     if exclude_border is False:
         exclude_border = 0
     elif exclude_border is True:
@@ -184,8 +227,7 @@ def peak_local_max(
     coordinates = ski2.feature.peak_local_max(
         image,
         min_distance=min_distance,
-        threshold_abs=threshold_abs,
-        threshold_rel=threshold_rel,
+        threshold=threshold,
         exclude_border=exclude_border,
         num_peaks=num_peaks,
         footprint=footprint,
diff --git a/src/skimage2/feature/_peaks.py b/src/skimage2/feature/_peaks.py
@@ -62,19 +62,6 @@ def _exclude_border(label, border_width):
     return label
 
 
-def _get_threshold(image, threshold_abs, threshold_rel):
-    """Return the threshold value according to an absolute and a relative
-    value.
-
-    """
-    threshold = threshold_abs if threshold_abs is not None else image.min()
-
-    if threshold_rel is not None:
-        threshold = max(threshold, threshold_rel * image.max())
-
-    return threshold
-
-
 def _validate_exclude_border(exclude_border, *, ndim):
     """Return border_width values relative to a min_distance if requested."""
 
@@ -110,8 +97,7 @@ def peak_local_max(
     image,
     *,
     min_distance=1,
-    threshold_abs=None,
-    threshold_rel=None,
+    threshold=None,
     exclude_border=0,
     num_peaks=None,
     footprint=None,
@@ -134,12 +120,9 @@ def peak_local_max(
     min_distance : int, optional
         The minimal allowed distance separating peaks. To find the
         maximum number of peaks, use `min_distance=1`. See also `p_norm`.
-    threshold_abs : float, optional
-        Minimum intensity of peaks. By default, the absolute threshold is
-        the minimum intensity of the image.
-    threshold_rel : float, optional
-        Minimum intensity of peaks, calculated as
-        ``max(image) * threshold_rel``.
+    threshold : float, optional
+        Minimum intensity of peaks. By default, the threshold is the minimum
+        intensity of the image.
     exclude_border : int or tuple of (int, ...), optional
         Control peak detection close to the border of `image`.
 
@@ -225,7 +208,8 @@ def peak_local_max(
 
     border_width = _validate_exclude_border(exclude_border, ndim=image.ndim)
 
-    threshold = _get_threshold(image, threshold_abs, threshold_rel)
+    if threshold is None:
+        threshold = image.min()
 
     if footprint is None:
         size = 2 * min_distance + 1
diff --git a/tests/skimage/feature/test_corner.py b/tests/skimage/feature/test_corner.py
@@ -460,19 +460,19 @@ def test_square_image():
 
     # Harris
     results = peak_local_max(
-        corner_harris(im, method='k'), min_distance=10, threshold_rel=0
+        corner_harris(im, method='k'), min_distance=10, threshold=0
     )
     # interest at corner
     assert len(results) == 1
 
     results = peak_local_max(
-        corner_harris(im, method='eps'), min_distance=10, threshold_rel=0
+        corner_harris(im, method='eps'), min_distance=10, threshold=0
     )
     # interest at corner
     assert len(results) == 1
 
     # Shi-Tomasi
-    results = peak_local_max(corner_shi_tomasi(im), min_distance=10, threshold_rel=0)
+    results = peak_local_max(corner_shi_tomasi(im), min_distance=10, threshold=0)
     # interest at corner
     assert len(results) == 1
 
@@ -510,23 +510,23 @@ def test_noisy_square_image():
     im = im + rng.uniform(size=im.shape) * 0.2
 
     # Moravec
-    results = peak_local_max(corner_moravec(im), min_distance=10, threshold_rel=0)
+    results = peak_local_max(corner_moravec(im), min_distance=10, threshold=0)
     # undefined number of interest points
     assert results.any()
 
     # Harris
     results = peak_local_max(
-        corner_harris(im, method='k'), min_distance=10, threshold_rel=0
+        corner_harris(im, method='k'), min_distance=10, threshold=0
     )
     assert len(results) == 1
     results = peak_local_max(
-        corner_harris(im, method='eps'), min_distance=10, threshold_rel=0
+        corner_harris(im, method='eps'), min_distance=10, threshold=0
     )
     assert len(results) == 1
 
     # Shi-Tomasi
     results = peak_local_max(
-        corner_shi_tomasi(im, sigma=1.5), min_distance=10, threshold_rel=0
+        corner_shi_tomasi(im, sigma=1.5), min_distance=10, threshold=0
     )
     assert len(results) == 1
 
@@ -539,11 +539,11 @@ def test_squared_dot():
     # Moravec fails
 
     # Harris
-    results = peak_local_max(corner_harris(im), min_distance=10, threshold_rel=0)
+    results = peak_local_max(corner_harris(im), min_distance=10, threshold=0)
     assert (results == np.array([[6, 6]])).all()
 
     # Shi-Tomasi
-    results = peak_local_max(corner_shi_tomasi(im), min_distance=10, threshold_rel=0)
+    results = peak_local_max(corner_shi_tomasi(im), min_distance=10, threshold=0)
     assert (results == np.array([[6, 6]])).all()
 
 
@@ -580,7 +580,7 @@ def test_subpix_edge(dtype):
     img[:25, :25] = 255
     img[25:, 25:] = 255
     corner = peak_local_max(
-        corner_harris(img), min_distance=10, threshold_rel=0, num_peaks=1
+        corner_harris(img), min_distance=10, threshold=0, num_peaks=1
     )
     subpix = corner_subpix(img, corner)
     assert subpix.dtype == _supported_float_type(dtype)
@@ -591,7 +591,7 @@ def test_subpix_dot():
     img = np.zeros((50, 50))
     img[25, 25] = 255
     corner = peak_local_max(
-        corner_harris(img), min_distance=10, threshold_rel=0, num_peaks=1
+        corner_harris(img), min_distance=10, threshold=0, num_peaks=1
     )
     subpix = corner_subpix(img, corner)
     assert_array_equal(subpix[0], (25, 25))
@@ -604,7 +604,7 @@ def test_subpix_no_class():
 
     img[25, 25] = 1e-10
     corner = peak_local_max(
-        corner_harris(img), min_distance=10, threshold_rel=0, num_peaks=1
+        corner_harris(img), min_distance=10, threshold=0, num_peaks=1
     )
     subpix = corner_subpix(img, corner)
     assert_array_equal(subpix[0], (np.nan, np.nan))
@@ -642,9 +642,7 @@ def test_num_peaks():
 
     for i in range(20):
         n = np.random.randint(1, 21)
-        results = peak_local_max(
-            img_corners, min_distance=10, threshold_rel=0, num_peaks=n
-        )
+        results = peak_local_max(img_corners, min_distance=10, threshold=0, num_peaks=n)
         assert results.shape[0] == n
 
 
diff --git a/tests/skimage/feature/test_peak.py b/tests/skimage/feature/test_peak.py
