From 9b110d6c6e7d6d8261dcd0cd5acec11ea476d73b Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Mon, 16 Jun 2014 22:50:49 -0500 Subject: [PATCH 1/8] Tweak range definition in `rescale_intensity` --- skimage/_shared/utils.py | 10 ++++ skimage/exposure/exposure.py | 94 ++++++++++++++++++++++++++---------- 2 files changed, 79 insertions(+), 25 deletions(-) diff --git a/skimage/_shared/utils.py b/skimage/_shared/utils.py index 612a2b63..6f121955 100644 --- a/skimage/_shared/utils.py +++ b/skimage/_shared/utils.py @@ -19,6 +19,16 @@ class skimage_deprecation(Warning): pass +def deprecation_warning(msg, **kwargs): + """Emit deprecation warning for scikit-image. + + Unlike default deprecation warnings, this is not silenced by default. + Additional keyword arguments are passed to `warnings.warn_explicit`. + """ + warnings.simplefilter('always', skimage_deprecation) + warnings.warn(msg, category=skimage_deprecation, **kwargs) + + class deprecated(object): """Decorator to mark deprecated functions with warning. diff --git a/skimage/exposure/exposure.py b/skimage/exposure/exposure.py index 14379f6b..d86caf13 100644 --- a/skimage/exposure/exposure.py +++ b/skimage/exposure/exposure.py @@ -3,7 +3,7 @@ import numpy as np from skimage import img_as_float from skimage.util.dtype import dtype_range, dtype_limits -from skimage._shared.utils import deprecated +from skimage._shared.utils import deprecated, deprecation_warning __all__ = ['histogram', 'cumulative_distribution', 'equalize', @@ -136,25 +136,72 @@ def equalize_hist(image, nbins=256): return out.reshape(image.shape) -def rescale_intensity(image, in_range=None, out_range=None): +def _intensity_range(image, range_values, zero_min=None): + """Return image intensity range (min, max) based on desired value type. + + Parameters + ---------- + image : array + Input image. + range_values : {'image' | 'dtype'} or dtype-name or 2-tuple + The image intensity range is configured by this parameter. + + 'image' + Return image min/max as the range. + 'dtype' + Return min/max of the image's dtype as the range. + dtype-name + Valid key in `DTYPE_RANGE`. + 2-tuple + Explicit values for the min/max intensities. + + zero_min : bool + If True, the image dtype's min is truncated to 0. Note that this only + applies the output range if `range_values` specifies a dtype. + """ + if range_values == 'dtype': + range_values = image.dtype.type + + if range_values == 'image': + i_min = np.min(image) + i_max = np.max(image) + elif range_values in DTYPE_RANGE: + i_min, i_max = DTYPE_RANGE[range_values] + if zero_min: + i_min = 0 + else: + i_min, i_max = range_values + return i_min, i_max + + +def rescale_intensity(image, in_range='image', out_range='dtype'): """Return image after stretching or shrinking its intensity levels. The image intensities are uniformly rescaled such that the minimum and - maximum values given by `in_range` match those given by `out_range`. + maximum values given by `in_range` match those given by `out_range`. Thus, + `in_range` values within the input-image's range will clip intensities, + and values outside the input image will tend to push limiting values + (e.g. white and black) toward mean values (e.g. gray). + + The minimum and maximum possible values of the output image is determined + by `out_range`. The actual min/max of the output could lie within this + range if `in_range` lies outside the input-image's intensity range. Parameters ---------- image : array Image array. - in_range : 2-tuple (float, float) or str - Min and max *allowed* intensity values of input image. If None, the - *allowed* min/max values are set to the *actual* min/max values in the - input image. Intensity values outside this range are clipped. - If string, use data limits of dtype specified by the string. - out_range : 2-tuple (float, float) or str - Min and max intensity values of output image. If None, use the min/max - intensities of the image data type. See `skimage.util.dtype` for - details. If string, use data limits of dtype specified by the string. + in_range, out_range : {'image' | 'dtype'} or dtype-name or 2-tuple + Min and max intensity values of input and output image. + + 'image' + Return image min/max as the range. + 'dtype' + Return min/max of the image's dtype as the range. + dtype-name + Valid key in `DTYPE_RANGE`. + 2-tuple + Explicit values for the min/max intensities. Returns ------- @@ -203,20 +250,17 @@ def rescale_intensity(image, in_range=None, out_range=None): dtype = image.dtype.type if in_range is None: - imin = np.min(image) - imax = np.max(image) - elif in_range in DTYPE_RANGE: - imin, imax = DTYPE_RANGE[in_range] - else: - imin, imax = in_range + in_range = 'image' + msg = "`in_range` should not be set to None. Use {!r} instead." + deprecation_warning(msg.format(in_range)) - if out_range is None or out_range in DTYPE_RANGE: - out_range = dtype if out_range is None else out_range - omin, omax = DTYPE_RANGE[out_range] - if imin >= 0: - omin = 0 - else: - omin, omax = out_range + if out_range is None: + out_range = 'dtype' + msg = "`out_range` should not be set to None. Use {!r} instead." + deprecation_warning(msg.format(out_range)) + + imin, imax = _intensity_range(image, in_range) + omin, omax = _intensity_range(image, out_range, zero_min=(imin >= 0)) image = np.clip(image, imin, imax) From 423207e07caea53d021bf847ceba3684e8bc4db3 Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Mon, 16 Jun 2014 22:54:51 -0500 Subject: [PATCH 2/8] Make `intensity_range` a public function --- skimage/exposure/exposure.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skimage/exposure/exposure.py b/skimage/exposure/exposure.py index d86caf13..249e4bab 100644 --- a/skimage/exposure/exposure.py +++ b/skimage/exposure/exposure.py @@ -136,7 +136,7 @@ def equalize_hist(image, nbins=256): return out.reshape(image.shape) -def _intensity_range(image, range_values, zero_min=None): +def intensity_range(image, range_values='image', zero_min=False): """Return image intensity range (min, max) based on desired value type. Parameters @@ -259,8 +259,8 @@ def rescale_intensity(image, in_range='image', out_range='dtype'): msg = "`out_range` should not be set to None. Use {!r} instead." deprecation_warning(msg.format(out_range)) - imin, imax = _intensity_range(image, in_range) - omin, omax = _intensity_range(image, out_range, zero_min=(imin >= 0)) + imin, imax = intensity_range(image, in_range) + omin, omax = intensity_range(image, out_range, zero_min=(imin >= 0)) image = np.clip(image, imin, imax) From ec9198c58e550ad12ffa78a538c96ca9777024e2 Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Mon, 16 Jun 2014 23:00:12 -0500 Subject: [PATCH 3/8] Edit wording of docstrings --- skimage/_shared/utils.py | 2 +- skimage/exposure/exposure.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skimage/_shared/utils.py b/skimage/_shared/utils.py index 6f121955..40703206 100644 --- a/skimage/_shared/utils.py +++ b/skimage/_shared/utils.py @@ -23,7 +23,7 @@ def deprecation_warning(msg, **kwargs): """Emit deprecation warning for scikit-image. Unlike default deprecation warnings, this is not silenced by default. - Additional keyword arguments are passed to `warnings.warn_explicit`. + Additional keyword arguments are passed to `warnings.warn`. """ warnings.simplefilter('always', skimage_deprecation) warnings.warn(msg, category=skimage_deprecation, **kwargs) diff --git a/skimage/exposure/exposure.py b/skimage/exposure/exposure.py index 249e4bab..1350e61a 100644 --- a/skimage/exposure/exposure.py +++ b/skimage/exposure/exposure.py @@ -157,7 +157,7 @@ def intensity_range(image, range_values='image', zero_min=False): zero_min : bool If True, the image dtype's min is truncated to 0. Note that this only - applies the output range if `range_values` specifies a dtype. + applies to the output range if `range_values` specifies a dtype. """ if range_values == 'dtype': range_values = image.dtype.type From 8e539cc12a93658ae9677442cdc554294e0de898 Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Mon, 16 Jun 2014 23:17:31 -0500 Subject: [PATCH 4/8] Clarify docstrings --- skimage/exposure/exposure.py | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/skimage/exposure/exposure.py b/skimage/exposure/exposure.py index 1350e61a..2b473fea 100644 --- a/skimage/exposure/exposure.py +++ b/skimage/exposure/exposure.py @@ -151,9 +151,13 @@ def intensity_range(image, range_values='image', zero_min=False): 'dtype' Return min/max of the image's dtype as the range. dtype-name - Valid key in `DTYPE_RANGE`. + Return intensity range based on desired `dtype`. Must be valid key + in `DTYPE_RANGE`. Note: `image` is ignored for this range type. 2-tuple - Explicit values for the min/max intensities. + Return `range_values` as min/max intensities. Note that there's no + reason to use this function if you just want to specify the + intensity range explicitly. This option is included for functions + that use `intensity_range` to support all desired range types. zero_min : bool If True, the image dtype's min is truncated to 0. Note that this only @@ -195,13 +199,14 @@ def rescale_intensity(image, in_range='image', out_range='dtype'): Min and max intensity values of input and output image. 'image' - Return image min/max as the range. + Use image min/max as the intensity range. 'dtype' - Return min/max of the image's dtype as the range. + Use min/max of the image's dtype as the intensity range. dtype-name - Valid key in `DTYPE_RANGE`. + Use intensity range based on desired `dtype`. Must be valid key + in `DTYPE_RANGE`. 2-tuple - Explicit values for the min/max intensities. + Use `range_values` as explicit min/max intensities. Returns ------- From b066a143b9c00c1a5c5be6448db3c4b69540442e Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Tue, 17 Jun 2014 22:57:20 -0500 Subject: [PATCH 5/8] Clarify docstrings --- skimage/exposure/exposure.py | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/skimage/exposure/exposure.py b/skimage/exposure/exposure.py index 2b473fea..12161c4e 100644 --- a/skimage/exposure/exposure.py +++ b/skimage/exposure/exposure.py @@ -143,8 +143,9 @@ def intensity_range(image, range_values='image', zero_min=False): ---------- image : array Input image. - range_values : {'image' | 'dtype'} or dtype-name or 2-tuple + range_values : str or 2-tuple The image intensity range is configured by this parameter. + The possible values for this parameter are enumerated below. 'image' Return image min/max as the range. @@ -181,22 +182,17 @@ def intensity_range(image, range_values='image', zero_min=False): def rescale_intensity(image, in_range='image', out_range='dtype'): """Return image after stretching or shrinking its intensity levels. - The image intensities are uniformly rescaled such that the minimum and - maximum values given by `in_range` match those given by `out_range`. Thus, - `in_range` values within the input-image's range will clip intensities, - and values outside the input image will tend to push limiting values - (e.g. white and black) toward mean values (e.g. gray). - - The minimum and maximum possible values of the output image is determined - by `out_range`. The actual min/max of the output could lie within this - range if `in_range` lies outside the input-image's intensity range. + The desired intensity range of the input and output, `in_range` and + `out_range` respectively, are used to stretch or shrink the intensity range + of the input image. See examples below. Parameters ---------- image : array Image array. - in_range, out_range : {'image' | 'dtype'} or dtype-name or 2-tuple + in_range, out_range : str or 2-tuple Min and max intensity values of input and output image. + The possible values for this parameter are enumerated below. 'image' Use image min/max as the intensity range. @@ -216,7 +212,9 @@ def rescale_intensity(image, in_range='image', out_range='dtype'): Examples -------- - By default, intensities are stretched to the limits allowed by the dtype: + By default, the min/max intensities of the input image are stretched to + the limits allowed by the image's dtype, since `in_range` defaults to + 'image' and `out_range` defaults to 'dtype': >>> image = np.array([51, 102, 153], dtype=np.uint8) >>> rescale_intensity(image) From 4c0befed6290b34b32991e63fb090106e0824062 Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Tue, 17 Jun 2014 22:59:04 -0500 Subject: [PATCH 6/8] Add TODO for deprecation removal --- TODO.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/TODO.txt b/TODO.txt index adc70f48..e2fc4218 100644 --- a/TODO.txt +++ b/TODO.txt @@ -1,5 +1,9 @@ Remember to list any API changes below in `doc/source/api_changes.txt`. +Version 0.13 +------------ +* Remove deprecated `None` defaults for `skimage.exposure.rescale_intensity` + Version 0.12 ------------ * Change `label` to mark background as 0, not -1, which is consistent with @@ -7,7 +11,7 @@ Version 0.12 * Remove `skimage.morphology.label` from `skimage.morphology.__init__`--it now lives in `skimage.measure.label`. * Remove deprecated `reverse_map` parameter of `skimage.transform.warp` -* Change depecrated `enforce_connectivity=False` on skimage.segmentation.slic +* Change deprecated `enforce_connectivity=False` on skimage.segmentation.slic and set it to True as default * Remove deprecated `skimage.measure.fit.BaseModel._params` attribute * Remove deprecated `skimage.measure.fit.BaseModel._params`, From 879c2c7f36d1819b580e4977617ec40bb9e44cc4 Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Fri, 11 Jul 2014 16:30:18 -0500 Subject: [PATCH 7/8] Add tests for intensity_range and rename parameter --- skimage/exposure/exposure.py | 14 +++++----- skimage/exposure/tests/test_exposure.py | 36 +++++++++++++++++++++++-- 2 files changed, 41 insertions(+), 9 deletions(-) diff --git a/skimage/exposure/exposure.py b/skimage/exposure/exposure.py index 12161c4e..ad21fa9b 100644 --- a/skimage/exposure/exposure.py +++ b/skimage/exposure/exposure.py @@ -3,7 +3,7 @@ import numpy as np from skimage import img_as_float from skimage.util.dtype import dtype_range, dtype_limits -from skimage._shared.utils import deprecated, deprecation_warning +from skimage._shared.utils import deprecation_warning __all__ = ['histogram', 'cumulative_distribution', 'equalize', @@ -136,7 +136,7 @@ def equalize_hist(image, nbins=256): return out.reshape(image.shape) -def intensity_range(image, range_values='image', zero_min=False): +def intensity_range(image, range_values='image', clip_negative=False): """Return image intensity range (min, max) based on desired value type. Parameters @@ -160,9 +160,9 @@ def intensity_range(image, range_values='image', zero_min=False): intensity range explicitly. This option is included for functions that use `intensity_range` to support all desired range types. - zero_min : bool - If True, the image dtype's min is truncated to 0. Note that this only - applies to the output range if `range_values` specifies a dtype. + clip_negative : bool + If True, clip the negative range (i.e. return 0 for min intensity) + even if the image dtype allows negative values. """ if range_values == 'dtype': range_values = image.dtype.type @@ -172,7 +172,7 @@ def intensity_range(image, range_values='image', zero_min=False): i_max = np.max(image) elif range_values in DTYPE_RANGE: i_min, i_max = DTYPE_RANGE[range_values] - if zero_min: + if clip_negative: i_min = 0 else: i_min, i_max = range_values @@ -263,7 +263,7 @@ def rescale_intensity(image, in_range='image', out_range='dtype'): deprecation_warning(msg.format(out_range)) imin, imax = intensity_range(image, in_range) - omin, omax = intensity_range(image, out_range, zero_min=(imin >= 0)) + omin, omax = intensity_range(image, out_range, clip_negative=(imin >= 0)) image = np.clip(image, imin, imax) diff --git a/skimage/exposure/tests/test_exposure.py b/skimage/exposure/tests/test_exposure.py index 6471ff59..dcaf6837 100644 --- a/skimage/exposure/tests/test_exposure.py +++ b/skimage/exposure/tests/test_exposure.py @@ -3,9 +3,11 @@ import warnings import numpy as np from numpy.testing import assert_array_almost_equal as assert_close from numpy.testing import assert_array_equal, assert_raises + import skimage from skimage import data from skimage import exposure +from skimage.exposure.exposure import intensity_range from skimage.color import rgb2gray from skimage.util.dtype import dtype_range @@ -41,6 +43,36 @@ def check_cdf_slope(cdf): assert 0.9 < slope < 1.1 +# Test intensity range +# ==================== + + +def test_intensity_range_uint8(): + image = np.array([0, 1], dtype=np.uint8) + input_and_expected = [('image', [0, 1]), + ('dtype', [0, 255]), + ((10, 20), [10, 20])] + for range_values, expected_values in input_and_expected: + out = intensity_range(image, range_values=range_values) + yield assert_array_equal, out, expected_values + + +def test_intensity_range_float(): + image = np.array([0.1, 0.2], dtype=np.float64) + input_and_expected = [('image', [0.1, 0.2]), + ('dtype', [-1, 1]), + ((0.3, 0.4), [0.3, 0.4])] + for range_values, expected_values in input_and_expected: + out = intensity_range(image, range_values=range_values) + yield assert_array_equal, out, expected_values + + +def test_intensity_range_clipped_float(): + image = np.array([0.1, 0.2], dtype=np.float64) + out = intensity_range(image, range_values='dtype', clip_negative=True) + assert_array_equal(out, (0, 1)) + + # Test rescale intensity # ====================== @@ -134,7 +166,7 @@ def test_adapthist_grayscale(): img = rgb2gray(img) img = np.dstack((img, img, img)) adapted = exposure.equalize_adapthist(img, 10, 9, clip_limit=0.01, - nbins=128) + nbins=128) assert_almost_equal = np.testing.assert_almost_equal assert img.shape == adapted.shape assert_almost_equal(peak_snr(img, adapted), 97.531, 3) @@ -374,6 +406,6 @@ def test_adjust_inv_sigmoid_cutoff_half(): assert_array_equal(result, expected) -def test_neggative(): +def test_negative(): image = np.arange(-10, 245, 4).reshape(8, 8).astype(np.double) assert_raises(ValueError, exposure.adjust_gamma, image) From 4c000c4d89a3a0458353b79c05f719456595c320 Mon Sep 17 00:00:00 2001 From: Tony S Yu Date: Fri, 11 Jul 2014 17:01:54 -0500 Subject: [PATCH 8/8] Use normal deprecation warning --- skimage/_shared/utils.py | 10 ---------- skimage/exposure/exposure.py | 5 ++--- 2 files changed, 2 insertions(+), 13 deletions(-) diff --git a/skimage/_shared/utils.py b/skimage/_shared/utils.py index 40703206..612a2b63 100644 --- a/skimage/_shared/utils.py +++ b/skimage/_shared/utils.py @@ -19,16 +19,6 @@ class skimage_deprecation(Warning): pass -def deprecation_warning(msg, **kwargs): - """Emit deprecation warning for scikit-image. - - Unlike default deprecation warnings, this is not silenced by default. - Additional keyword arguments are passed to `warnings.warn`. - """ - warnings.simplefilter('always', skimage_deprecation) - warnings.warn(msg, category=skimage_deprecation, **kwargs) - - class deprecated(object): """Decorator to mark deprecated functions with warning. diff --git a/skimage/exposure/exposure.py b/skimage/exposure/exposure.py index ad21fa9b..3a2accbc 100644 --- a/skimage/exposure/exposure.py +++ b/skimage/exposure/exposure.py @@ -3,7 +3,6 @@ import numpy as np from skimage import img_as_float from skimage.util.dtype import dtype_range, dtype_limits -from skimage._shared.utils import deprecation_warning __all__ = ['histogram', 'cumulative_distribution', 'equalize', @@ -255,12 +254,12 @@ def rescale_intensity(image, in_range='image', out_range='dtype'): if in_range is None: in_range = 'image' msg = "`in_range` should not be set to None. Use {!r} instead." - deprecation_warning(msg.format(in_range)) + warnings.warn(msg.format(in_range)) if out_range is None: out_range = 'dtype' msg = "`out_range` should not be set to None. Use {!r} instead." - deprecation_warning(msg.format(out_range)) + warnings.warn(msg.format(out_range)) imin, imax = intensity_range(image, in_range) omin, omax = intensity_range(image, out_range, clip_negative=(imin >= 0))