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`, diff --git a/skimage/exposure/exposure.py b/skimage/exposure/exposure.py index 14379f6b..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 deprecated __all__ = ['histogram', 'cumulative_distribution', 'equalize', @@ -136,25 +135,73 @@ 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='image', clip_negative=False): + """Return image intensity range (min, max) based on desired value type. + + Parameters + ---------- + image : array + Input image. + 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. + 'dtype' + Return min/max of the image's dtype as the range. + dtype-name + Return intensity range based on desired `dtype`. Must be valid key + in `DTYPE_RANGE`. Note: `image` is ignored for this range type. + 2-tuple + 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. + + 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 + + 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 clip_negative: + 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`. + 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 : 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 : 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. + 'dtype' + Use min/max of the image's dtype as the intensity range. + dtype-name + Use intensity range based on desired `dtype`. Must be valid key + in `DTYPE_RANGE`. + 2-tuple + Use `range_values` as explicit min/max intensities. Returns ------- @@ -164,7 +211,9 @@ def rescale_intensity(image, in_range=None, out_range=None): 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) @@ -203,20 +252,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." + warnings.warn(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." + warnings.warn(msg.format(out_range)) + + imin, imax = intensity_range(image, in_range) + 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)