Add `prescale` parameter to "blob functions" by lagru · Pull Request #7858 · scikit-image/scikit-image

lagru · 2025-07-24T17:44:23Z

Description

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.

Checklist

A descriptive but concise pull request title
Docstrings for all functions
Unit tests
A gallery example in ./doc/examples for new features
Contribution guide is followed

Release note

For maintainers and optionally contributors, please refer to the instructions on how to document this PR for the release notes.

In `skimage.feature`, add a new parameter `prescale` to the functions 
`blob_doh`, blob_dog`, and `blob_log`. This parameter controls the internal
rescaling behavior which makes it easier to set the `threshold` parameter 
correctly.
{label="New feature"}

In `skimage.feature`, deprecate the parameter `threshold_rel` in 
`blob_doh`, blob_dog`, and `blob_log`. The behavior of the parameters
effects were difficult to reason about. Instead, use `threshold` in
conjunction with the new parameter `prescale`.
{label="API"}

This makes heavy use of the scaling implementation that was proposed in [1]. Furthermore, `ski._shared.utils` seesm like a more fitting place. [1] https://www.github.com/scikit-image/scikit-image/pull/7697

matthew-brett

A few comments in passing.

I'm wondering about the divide by two heuristic. Will that always work?

src/skimage/_shared/utils.py

src/skimage/feature/blob.py

Co-authored-by: Matthew Brett <matthew.brett@gmail.com>

@stefanv

As pointed out by @stefanv, substraction with small floats can be problematic – so do that before division by peak_to_peak. Also handle NaNs and Infs in input value range explicitly. Cover everything with tests.

That keyword is new in version 2 which isn't our minimal dependency yet. However, going forward `strict=True` should probably be the default at some point. It avoids unepexted suprises.

tests/skimage/_shared/test_utils.py

We are not sure yet if it is worth supporting and committing to this option. We can always add it later if it is requested.

We are not really clear what behavior would be expected for NaN and inf values. So instead, it's easier to just raise a ValueError for now, encouraging users to handle this manually.

`_prescale_value_range` is really more of a helper function that ties our old legacy scaling behavior and the new min-max scaling together. It is meant as a convenience function to use in a few places where our API needs to work with a well-behaved output range. We very probably don't want to the slightly awkward API of `_prescale_value_range` public. Instead, if we want to later make something public. It's probably something closer to a fresh API like `_minmax_scale_value_range`.

coderabbitai

Actionable comments posted: 1

src/skimage/_shared/utils.py

stefanv

Some minor outstanding comments to address, but I'd say go ahead, fix what you can and merge.

src/skimage/_shared/utils.py

stefanv · 2026-02-03T01:01:59Z

src/skimage/_shared/utils.py

+
+    See Also
+    --------
+    _rescale_value_range


Suggested change

_rescale_value_range

_rescale

Undecided if I want to take you up on this suggestion. I don't think it hurts at all to have _value_range in there to make it clear what is scaled?

But for now, I'll take you up on it and postpone the naming discussion for if we decide to make this function public.

Actually, scratch that. I propose to leave this more specific name for now to help differentiate it from:

rescale in skimage.transform

rescale_intensity in skimage.exposure

_rescale_sigma_rgb2ycbcr in skimage.restoration

I'm also in favor of keeping the more specific name _rescale_value_range.

src/skimage/_shared/utils.py

src/skimage/feature/blob.py

mkcor

Thanks, @lagru! Just an extra round of iteration to agree on (user-facing) terms.

src/skimage/_shared/utils.py

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

coderabbitai

Actionable comments posted: 3

🧹 Nitpick comments (1)

src/skimage/_shared/utils.py (1)

1279-1281: Consider returning the input directly for mode="none".

Currently mode="none" returns image.copy(). If the intent is truly "do nothing," returning the original array without copying could be more efficient. However, if the copy is intentional to prevent mutation of the input, this is fine.

src/skimage/_shared/utils.py

stefanv · 2026-02-04T21:28:02Z

src/skimage/feature/blob.py

+        internally computed stack of Difference-of-Gaussian (DoG) images. This
+        in turn affects the effect of the `threshold` parameter.
+
+        ``'minmax'``


Test is OK, but I think simplest is just to make the scaling function public API and refer to it. Future PR is fine.

stefanv · 2026-02-04T21:29:38Z

tests/skimage/_shared/test_utils.py

        fe.params
+
+
+class Test_minmax_scale_value_range:


Suggested change

class Test_minmax_scale_value_range:

class TestMinmaxScaleValueRange:

Personally, I think the better "grep-ability" is totally worth breaking the camelCase convention here. But I don't care enough to block it, and since you both are in favor... 🤷

Actually, the rest of that module already uses snake case in class names. So leaving it for now for local consistency. But I'll open a thread on Zulip where I propose that for skimage2 as a convention. Otherwise I'm happy to clean that up in our code base.

Edit: #development > skimage2 style guide @ 💬

stefanv · 2026-02-04T21:31:23Z

Approved, feel free to merge when ready.

mkcor

Thanks, @lagru! Leaving the nitpick to your judgement. Committing the trivial fixes now.

mkcor · 2026-02-05T10:11:15Z

src/skimage/_shared/utils.py

+    Rescaling values between [0, 1], or *min-max normalization* [1]_,
+    is a simple method to ensure that data is inside a range.


Suggested change

Rescaling values between [0, 1], or *min-max normalization* [1]_,

is a simple method to ensure that data is inside a range.

Rescaling or *min-max normalization* [1]_

is a simple method to ensure that all data values lie in a certain range.

(based on cited reference https://en.wikipedia.org/wiki/Feature_scaling#Rescaling_(min-max_normalization))

src/skimage/_shared/utils.py

src/skimage/feature/blob.py

Was applied in other cases, so apply here too.

Co-authored-by: Marianne Corvellec <marianne.corvellec@ens-lyon.org>

lagru · 2026-02-05T20:03:19Z

Merging if the CI stays green. 🤞

* origin/main: (27 commits) Move `_shared` to `_skimage2` (#8102) Port `pad_footprint` & `mirror_footprint` to `skimage2` (#8094) Add rescaling API to skimage2 (#8075) Move `skimage2` implementation into `_skimage2` (#8093) Undo (double) mirroring in `ski2.morphology.dilation` (#8060) Grammar (#8091) Move `ensure_spacing` into `skimage2` (#8067) Ensure that `skimage2` does not eagerly import `skimage` (#8087) Use lazy-loader 0.5 (#8080) MAINT: make ellipse fitting forward compatible (#8054) Avoid deprecated assign to ndarray.shape (#8020) Avoid circular import in `feature/corner.py` (#8077) Turn off coderabbit auto-labeling & label checks (#8070) Fix GIL being re-enabled by C++ extensions (#8059) Fix conventions following docstub and misc. (#8055) Port grayscale morphology operators to skimage2 (#8046) Add revised `peak_local_max` to `skimage2` (#8039) Allow read-only arrays as input to remap (#7535) Add `prescale` parameter to "blob functions" (#7858) Try to make coderabbit respect exisiting type labels (#8042) ...

WIP Draft prescaling "blob_funcs"

03d0802

lagru added ⏩ type: Enhancement Improve existing features 📜 type: API Involves API change(s) 🥾 Path to skimage2 A step towards the new "API 2.0" labels Jul 24, 2025

lagru mentioned this pull request Jul 24, 2025

Deprecate range scaling threshold in feature.blob_ functions #7797

Closed

lagru added 2 commits August 15, 2025 16:16

Merge branch 'main' into prescale-blob-funcs

7a337ca

Expand _prescale_value_range

9f3bc42

This makes heavy use of the scaling implementation that was proposed in [1]. Furthermore, `ski._shared.utils` seesm like a more fitting place. [1] https://www.github.com/scikit-image/scikit-image/pull/7697

lagru marked this pull request as ready for review August 28, 2025 16:54

lagru removed the ⏩ type: Enhancement Improve existing features label Aug 28, 2025

lagru changed the title ~~Add prescale parameter to "blob functions"~~ Add prescale function and similar parameter to "blob functions" Aug 28, 2025

lagru changed the title ~~Add prescale function and similar parameter to "blob functions"~~ Add prescale parameter to "blob functions" Aug 28, 2025

lagru requested review from matthew-brett and stefanv August 28, 2025 17:03

matthew-brett reviewed Sep 2, 2025

View reviewed changes

src/skimage/_shared/utils.py Outdated Show resolved Hide resolved

src/skimage/_shared/utils.py Outdated Show resolved Hide resolved

src/skimage/_shared/utils.py Outdated Show resolved Hide resolved

stefanv reviewed Sep 2, 2025

View reviewed changes

lagru and others added 5 commits September 4, 2025 15:57

Apply suggestions from code review

04374a2

Co-authored-by: Matthew Brett <matthew.brett@gmail.com>

Use 'none' in _prescale_value_range instead of False

8d9ad21

Scale after substraction; handle NaN & inf

8a0df22

As pointed out by @stefanv, substraction with small floats can be problematic – so do that before division by peak_to_peak. Also handle NaNs and Infs in input value range explicitly. Cover everything with tests.

Account for deprecated threshold_rel in blob_dog tests

4e89c1f

Merge branch 'main' into prescale-blob-funcs

29eb9e2

lagru requested a review from stefanv September 22, 2025 16:59

lagru added 2 commits September 23, 2025 17:48

Don't use strict for numpy's assert_equal (yet)

c1d97ab

That keyword is new in version 2 which isn't our minimal dependency yet. However, going forward `strict=True` should probably be the default at some point. It avoids unepexted suprises.

Fix typo in Sphinx directive & docstring

fde89a1

lagru commented Sep 23, 2025

View reviewed changes

tests/skimage/_shared/test_utils.py Outdated Show resolved Hide resolved

lagru added 6 commits September 26, 2025 11:41

Remove tuple[float, float] option from _prescale_value_range

9c5db02

We are not sure yet if it is worth supporting and committing to this option. We can always add it later if it is requested.

Raise ValueError on NaN and inf in _prescale_value_range

f643d24

We are not really clear what behavior would be expected for NaN and inf values. So instead, it's easier to just raise a ValueError for now, encouraging users to handle this manually.

Tweak blob_dog docstring

4296583

Refactor to _scale_value_range

41ffeb4

Add minimal tests for prescale='minmax' and overflow warning

7b7a0ef

lagru requested a review from stefanv February 2, 2026 20:30

coderabbitai bot reviewed Feb 2, 2026

View reviewed changes

src/skimage/_shared/utils.py Show resolved Hide resolved

stefanv reviewed Feb 3, 2026

View reviewed changes

mkcor reviewed Feb 3, 2026

View reviewed changes

lagru and others added 2 commits February 3, 2026 14:13

Mention *min-max normalization* in docstring

60b7257

Apply rewording suggestions from code review

d571eb1

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

coderabbitai bot reviewed Feb 3, 2026

View reviewed changes

src/skimage/_shared/utils.py Outdated Show resolved Hide resolved

src/skimage/_shared/utils.py Show resolved Hide resolved

src/skimage/_shared/utils.py Show resolved Hide resolved

lagru added 4 commits February 3, 2026 14:52

Reword warning message again

88d1bfe

Fix typo

756edd6

Fix another typo

63739a7

Expand tests for rescale_value_range

eeeb1d4

lagru mentioned this pull request Feb 3, 2026

Clarify use of "sigma" in docstring of .feature.blob_* functions #8048

Open

lagru requested review from mkcor and stefanv February 3, 2026 14:10

Merge branch 'main' into prescale-blob-funcs

4825c4b

stefanv approved these changes Feb 4, 2026

View reviewed changes

mkcor approved these changes Feb 5, 2026

View reviewed changes

mkcor and others added 6 commits February 5, 2026 11:23

Update src/skimage/_shared/utils.py

7a6b9bb

Update src/skimage/_shared/utils.py

d847bae

Update src/skimage/feature/blob.py

ccd9eeb

Update src/skimage/feature/blob.py

ee727ef

Add wording tweak to blob_dog too

d15a7e5

Was applied in other cases, so apply here too.

Remove redundant info sentence in docstring

5f6b588

Co-authored-by: Marianne Corvellec <marianne.corvellec@ens-lyon.org>

lagru merged commit 5d0aded into scikit-image:main Feb 5, 2026
26 checks passed

github-project-automation bot moved this from To Review to Done in skimage2 Feb 5, 2026

lagru deleted the prescale-blob-funcs branch February 5, 2026 20:34

stefanv added this to the 0.27 milestone Feb 5, 2026

	class Test_minmax_scale_value_range:
	class TestMinmaxScaleValueRange:

		Rescaling values between [0, 1], or min-max normalization [1]_,
		is a simple method to ensure that data is inside a range.

Uh oh!

Conversation

lagru commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Release note

Uh oh!

matthew-brett left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

stefanv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mkcor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lagru Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stefanv commented Feb 4, 2026

Uh oh!

mkcor left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lagru commented Jul 24, 2025 •

edited

Loading

lagru Feb 5, 2026 •

edited

Loading