Add prescale parameter to "blob functions" (scikit-image#7858)

Implementation of the new strategy around value range scaling in our
library that we extensively discussed in the recent sprint and meeting.
We will add more detailed descriptions of this strategy but in short:

- introduce a new `prescale` parameter for functions that actually need
/ benefit from prescaling the input image.
- Add a dedicated private (for now) function for that. I plan to use
this elsewhere in the future.

Co-authored-by: Matthew Brett <matthew.brett@gmail.com>
Co-authored-by: Marianne Corvellec <marianne.corvellec@ens-lyon.org>
Co-authored-by: Stefan van der Walt <stefan@mentat.za.net>

Author: 4 people

TODO.txt

@@ -24,6 +24,10 @@ Version 0.27
   - Remove `doc/source/user_guide/plugins.rst`
 * Complete deprecation of `square`, `rectangle` and `cube` in `skimage.morphology`.
 
+Version 0.29
+------------
+* Complete deprecation of `threshold_rel` in `skimage.feature.blob_*` functions
+
 Other
 -----
 * Once NumPy 1.25.0 is minimal required version:
@@ -60,6 +64,7 @@ Post numpy 2
 - Remove references to `numpy.bool8` once NumPy 2.0 is minimal required version.
 - scipy>=1.12: remove SCIPY_CG_TOL_PARAM_NAME in `_shared.compat.py`.
 - Remove `np2` check in `skimage/feature/brief.py`.
+- Consider using `numpy.testing.assert_equal()` with `strict=True` everywhere.
 
 Version 2.0
 -----------

src/skimage/_shared/utils.py

@@ -6,7 +6,8 @@
 
 import numpy as np
 
-from ._warnings import all_warnings, warn
+from ._warnings import all_warnings, warn, warn_external
+
 
 __all__ = [
     'deprecate_func',
@@ -968,6 +969,7 @@ def convert_to_float(image, preserve_range):
         if image.dtype.char not in 'df':
             image = image.astype(float)
     else:
+        # Avoid circular import
         from ..util.dtype import img_as_float
 
         image = img_as_float(image)
@@ -1113,3 +1115,174 @@ def as_binary_ndarray(array, *, variable_name):
                 f"safely cast to boolean array."
             )
     return np.asarray(array, dtype=bool)
+
+
+def _minmax_scale_value_range(image):
+    """Rescale `image` to the value range [0, 1].
+
+    Rescaling values between [0, 1], or *min-max normalization* [1]_,
+    is a simple method to ensure that data is inside a range.
+
+    Parameters
+    ----------
+    image : ndarray
+        Input image.
+
+    Returns
+    -------
+    rescaled_image : ndarray
+        Rescaled image, of same shape as input `image` but with a
+        floating dtype (according to :func:`_supported_float_type`).
+
+    Raises
+    ------
+    ValueError
+        Rescaling an image that contains NaN or infinity is not supported for
+        now. In those cases, consider replacing the unsupported values manually.
+
+    See Also
+    --------
+    _rescale_value_range
+        Rescale the value range of `image` according to the selected `mode`.
+
+    References
+    ----------
+    .. [1]: https://en.wikipedia.org/wiki/Feature_scaling#Rescaling_(min-max_normalization)
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> image = np.array([-10, 45, 100], dtype=np.int8)
+    >>> _minmax_scale_value_range(image)
+    array([0. , 0.5, 1. ])
+    """
+    # Prepare `out` array, `lower` and `higher` with exact dtype to avoid
+    # unexpected promotion and / or precision problems during normalization
+    dtype = _supported_float_type(image.dtype, allow_complex=False)
+    out = image.astype(dtype)
+
+    lower = out.min()
+    higher = out.max()
+
+    # Deal with unexpected or invalid `lower` and `higher` early
+    if np.isnan(lower) or np.isnan(higher):
+        msg = (
+            "`image` contains NaN. "
+            "Min-max normalization with NaN is not supported. "
+            "Replace NaNs manually before rescaling."
+        )
+        raise ValueError(msg)
+
+    if np.isinf(lower) or np.isinf(higher):
+        msg = (
+            "`image` contains inf. "
+            "Min-max normalization with inf is not supported. "
+            "Replace inf manually before rescaling."
+        )
+        raise ValueError(msg)
+
+    if lower == higher:
+        msg = "`image` is uniform, returning uniform array of 0's"
+        warn_external(msg, category=RuntimeWarning)
+        out = np.zeros_like(out)
+        return out
+    assert lower < higher
+
+    # Actual normalization
+    with np.errstate(all="raise"):
+        try:
+            peak_to_peak = higher - lower
+            out -= lower
+        except FloatingPointError as e:
+            if "overflow" in e.args[0]:
+                warn_external(
+                    "Overflow while attempting to rescale. This could be due to "
+                    "`image` containing unexpectedly large values. Dividing all "
+                    "values by 2 before rescaling to avoid overflow.",
+                    category=RuntimeWarning,
+                )
+                out /= 2
+                lower /= 2
+                higher /= 2
+                peak_to_peak = higher - lower
+                out -= lower
+            else:
+                raise
+
+        out /= peak_to_peak
+
+    return out
+
+
+def _rescale_value_range(image, *, mode):
+    """Rescale the value range of `image` according to the selected `mode`.
+
+    For now, this private function handles *prescaling* for public API that
+    needs a value range to be known and well-defined.
+
+    Parameters
+    ----------
+    image : ndarray
+        Image to rescale.
+    mode : {'minmax', 'none', 'legacy'}, optional
+        Controls the rescaling behavior for `image`.
+
+        ``'minmax'``
+            Normalize `image` between 0 and 1 regardless of dtype. After
+            normalization, `rescaled_image` will have a floating dtype
+            (according to :func:`_supported_float_type`).
+
+        ``'none'``
+            Don't rescale the value range of `image` at all and return a
+            copy of `image`. Useful when `image` has already been rescaled.
+
+        ``'legacy'``
+            Normalize only if `image` has an integer dtype. If `image` is of
+            floating dtype, it is left alone. See :func:`.img_as_float` for
+            more details.
+
+    Returns
+    -------
+    rescaled_image : ndarray
+        The rescaled `image` of the same shape but possibly with a different
+        dtype.
+
+    Raises
+    ------
+    ValueError
+        Rescaling an `image` with `mode='minmax'` that contains NaN or
+        infinity is not supported for now. In those cases, consider replacing
+        the unsupported values manually.
+
+    See Also
+    --------
+    _minmax_scale_value_range
+        Rescale `image` to the value range [0, 1]. Internally used in
+        this function.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> image = np.array([-10, 45, 100], dtype=np.int8)
+
+    >>> _rescale_value_range(image, mode="minmax")
+    array([0. , 0.5, 1. ])
+
+    >>> _rescale_value_range(image, mode="legacy")
+    array([-0.07874016,  0.35433071,  0.78740157])
+
+    >>> _rescale_value_range(image, mode="none")
+    array([-10, 45, 100], dtype=int8)
+    """
+    if mode == "none":
+        # Exit early
+        return image.copy()
+    if mode == "legacy":
+        # Avoid circular import
+        from ..util.dtype import img_as_float
+
+        return img_as_float(image)
+    if mode == "minmax":
+        return _minmax_scale_value_range(image)
+    else:
+        raise ValueError("unsupported mode")