diff --git a/skimage/filter/rank/_percentile.py b/skimage/filter/rank/_percentile.py index f2b5e7f4..f8ace8a4 100644 --- a/skimage/filter/rank/_percentile.py +++ b/skimage/filter/rank/_percentile.py @@ -50,17 +50,19 @@ def autolevel_percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, p0=0, p1=1): """Return greyscale local autolevel of an image. - Autolevel is computed on the given structuring element. Only levels between - percentiles [p0, p1] are used. + This filter locally stretches the histogram of greyvalues to cover the + entire range of values from "white" to "black". + + Only greyvalues between percentiles [p0, p1] are considered in the filter. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -74,7 +76,7 @@ def autolevel_percentile(image, selem, out=None, mask=None, shift_x=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. """ @@ -86,19 +88,18 @@ def autolevel_percentile(image, selem, out=None, mask=None, shift_x=False, def gradient_percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, p0=0, p1=1): - """Return greyscale local gradient of an image. + """Return local gradient of an image (i.e. local maximum - local minimum). - gradient is computed on the given structuring element. Only - levels between percentiles [p0, p1] are used. + Only greyvalues between percentiles [p0, p1] are considered in the filter. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -112,7 +113,7 @@ def gradient_percentile(image, selem, out=None, mask=None, shift_x=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. """ @@ -124,19 +125,18 @@ def gradient_percentile(image, selem, out=None, mask=None, shift_x=False, def mean_percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, p0=0, p1=1): - """Return greyscale local mean of an image. + """Return local mean of an image. - Mean is computed on the given structuring element. Only levels between - percentiles [p0, p1] are used. + Only greyvalues between percentiles [p0, p1] are considered in the filter. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -150,7 +150,7 @@ def mean_percentile(image, selem, out=None, mask=None, shift_x=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. """ @@ -162,19 +162,18 @@ def mean_percentile(image, selem, out=None, mask=None, shift_x=False, def subtract_mean_percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, p0=0, p1=1): - """Return greyscale local subtract_mean of an image. + """Return image subtracted from its local mean. - subtract_mean is computed on the given structuring element. Only levels - between percentiles [p0, p1] are used. + Only greyvalues between percentiles [p0, p1] are considered in the filter. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -188,7 +187,7 @@ def subtract_mean_percentile(image, selem, out=None, mask=None, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. """ @@ -200,19 +199,22 @@ def subtract_mean_percentile(image, selem, out=None, mask=None, def enhance_contrast_percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, p0=0, p1=1): - """Return greyscale local enhance_contrast of an image. + """Enhance contrast of an image. - enhance_contrast is computed on the given structuring element. Only levels - between percentiles [p0, p1] are used. + This replaces each pixel by the local maximum if the pixel greyvalue is + closer to the local maximum than the local minimum. Otherwise it is + replaced by the local minimum. + + Only greyvalues between percentiles [p0, p1] are considered in the filter. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -226,7 +228,7 @@ def enhance_contrast_percentile(image, selem, out=None, mask=None, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. """ @@ -238,19 +240,21 @@ def enhance_contrast_percentile(image, selem, out=None, mask=None, def percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, p0=0): - """Return greyscale local percentile of an image. + """Return local percentile of an image. - percentile is computed on the given structuring element. Returns the value - of the p0 lower percentile of the neighborhood value distribution. + Returns the value of the p0 lower percentile of the local greyvalue + distribution. + + Only greyvalues between percentiles [p0, p1] are considered in the filter. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -263,7 +267,7 @@ def percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. """ @@ -275,19 +279,21 @@ def percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, def pop_percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, p0=0, p1=1): - """Return greyscale local pop of an image. + """Return the local number (population) of pixels. - pop is computed on the given structuring element. Only levels between - percentiles [p0, p1] are used. + The number of pixels is defined as the number of pixels which are included + in the structuring element and the mask. + + Only greyvalues between percentiles [p0, p1] are considered in the filter. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -301,7 +307,7 @@ def pop_percentile(image, selem, out=None, mask=None, shift_x=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. """ @@ -310,21 +316,24 @@ def pop_percentile(image, selem, out=None, mask=None, shift_x=False, image, selem, out=out, mask=mask, shift_x=shift_x, shift_y=shift_y, p0=p0, p1=p1) + def sum_percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, p0=0, p1=1): - """Return greyscale local sum of an image. + """Return the local sum of pixels. - sum is computed on the given structuring element. Only levels between - percentiles [p0, p1] are used. Result is truncated (8bit or 16bit). + Only greyvalues between percentiles [p0, p1] are considered in the filter. + + Note that the sum may overflow depending on the data type of the input + array. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -338,7 +347,7 @@ def sum_percentile(image, selem, out=None, mask=None, shift_x=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. """ @@ -347,23 +356,24 @@ def sum_percentile(image, selem, out=None, mask=None, shift_x=False, image, selem, out=out, mask=mask, shift_x=shift_x, shift_y=shift_y, p0=p0, p1=p1) + def threshold_percentile(image, selem, out=None, mask=None, shift_x=False, shift_y=False, p0=0): - """Return greyscale local threshold of an image. + """Local threshold of an image. - threshold is computed on the given structuring element. Returns - thresholded image such that pixels having a higher value than the the p0 - percentile of the neighborhood value distribution are set to 2^nbit-1 - (e.g. 255 for 8bit image). + The resulting binary mask is True if the greyvalue of the center pixel is + greater than the local mean. + + Only greyvalues between percentiles [p0, p1] are considered in the filter. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -374,7 +384,7 @@ def threshold_percentile(image, selem, out=None, mask=None, shift_x=False, p0 : float in [0, ..., 1] Set the percentile value. - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. local threshold : ndarray (same dtype as input) The result of the local threshold. diff --git a/skimage/filter/rank/bilateral.py b/skimage/filter/rank/bilateral.py index 4509e06b..d01680db 100644 --- a/skimage/filter/rank/bilateral.py +++ b/skimage/filter/rank/bilateral.py @@ -53,21 +53,22 @@ def mean_bilateral(image, selem, out=None, mask=None, shift_x=False, pixels based on their spatial closeness and radiometric similarity. Spatial closeness is measured by considering only the local pixel - neighborhood given by a structuring element (selem). + neighborhood given by a structuring element. Radiometric similarity is defined by the greylevel interval [g-s0, g+s1] - where g is the current pixel greylevel. Only pixels belonging to the - structuring element AND having a greylevel inside this interval are - averaged. Return greyscale local bilateral_mean of an image. + where g is the current pixel greylevel. + + Only pixels belonging to the structuring element and having a greylevel + inside this interval are averaged. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -81,22 +82,20 @@ def mean_bilateral(image, selem, out=None, mask=None, shift_x=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. See also -------- - skimage.filter.denoise_bilateral for a gaussian bilateral filter. + skimage.filter.denoise_bilateral for a Gaussian bilateral filter. Examples -------- >>> from skimage import data >>> from skimage.morphology import disk - >>> from skimage.filter.rank import bilateral_mean - >>> # Load test image / cast to uint16 - >>> ima = data.camera().astype(np.uint16) - >>> # bilateral filtering of cameraman image using a flat kernel - >>> bilat_ima = bilateral_mean(ima, disk(20), s0=10,s1=10) + >>> from skimage.filter.rank import mean_bilateral + >>> img = data.camera().astype(np.uint16) + >>> bilat_img = mean_bilateral(img, disk(20), s0=10,s1=10) """ @@ -106,18 +105,22 @@ def mean_bilateral(image, selem, out=None, mask=None, shift_x=False, def pop_bilateral(image, selem, out=None, mask=None, shift_x=False, shift_y=False, s0=10, s1=10): - """Return the number (population) of pixels actually inside the bilateral - neighborhood, i.e. being inside the structuring element AND having a gray - level inside the interval [g-s0, g+s1]. + """Return the local number (population) of pixels. + + + The number of pixels is defined as the number of pixels which are included + in the structuring element and the mask. Additionally the must have a + greylevel inside the interval [g-s0, g+s1] where g is the greyvalue of the + center pixel. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -131,20 +134,19 @@ def pop_bilateral(image, selem, out=None, mask=None, shift_x=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. Examples -------- - >>> # Local mean >>> from skimage.morphology import square >>> import skimage.filter.rank as rank - >>> ima16 = 255 * np.array([[0, 0, 0, 0, 0], - ... [0, 1, 1, 1, 0], - ... [0, 1, 1, 1, 0], - ... [0, 1, 1, 1, 0], - ... [0, 0, 0, 0, 0]], dtype=np.uint16) - >>> rank.bilateral_pop(ima16, square(3), s0=10,s1=10) + >>> img = 255 * np.array([[0, 0, 0, 0, 0], + ... [0, 1, 1, 1, 0], + ... [0, 1, 1, 1, 0], + ... [0, 1, 1, 1, 0], + ... [0, 0, 0, 0, 0]], dtype=np.uint16) + >>> rank.pop_bilateral(img, square(3), s0=10, s1=10) array([[3, 4, 3, 4, 3], [4, 4, 6, 4, 4], [3, 6, 9, 6, 3], @@ -167,19 +169,22 @@ def sum_bilateral(image, selem, out=None, mask=None, shift_x=False, neighborhood given by a structuring element (selem). Radiometric similarity is defined by the greylevel interval [g-s0, g+s1] - where g is the current pixel greylevel. Only pixels belonging to the - structuring element AND having a greylevel inside this interval are - summed. Return greyscale local bilateral sum of an image. - Result is truncated (8bit or 16bit). + where g is the current pixel greylevel. + + Only pixels belonging to the structuring element AND having a greylevel + inside this interval are summed. + + Note that the sum may overflow depending on the data type of the input + array. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -193,22 +198,20 @@ def sum_bilateral(image, selem, out=None, mask=None, shift_x=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. See also -------- - skimage.filter.denoise_bilateral for a gaussian bilateral filter. + skimage.filter.denoise_bilateral for a Gaussian bilateral filter. Examples -------- >>> from skimage import data >>> from skimage.morphology import disk >>> from skimage.filter.rank import sum_bilateral - >>> # Load test image / cast to uint16 - >>> ima = data.camera().astype(np.uint16) - >>> # bilateral filtering of cameraman image using a flat kernel - >>> bilat_ima = sum_bilateral(ima, disk(20), s0=10,s1=10) + >>> img = data.camera().astype(np.uint16) + >>> bilat_img = sum_bilateral(img, disk(10), s0=10, s1=10) """ diff --git a/skimage/filter/rank/generic.py b/skimage/filter/rank/generic.py index 703b66b3..ccc1166e 100644 --- a/skimage/filter/rank/generic.py +++ b/skimage/filter/rank/generic.py @@ -77,16 +77,19 @@ def _apply(func, image, selem, out, mask, shift_x, shift_y, out_dtype=None): def autolevel(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Autolevel image using local histogram. + """Auto-level image using local histogram. + + This filter locally stretches the histogram of greyvalues to cover the + entire range of values from "white" to "black". Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -97,7 +100,7 @@ def autolevel(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. Examples @@ -105,10 +108,8 @@ def autolevel(image, selem, out=None, mask=None, shift_x=False, shift_y=False): >>> from skimage import data >>> from skimage.morphology import disk >>> from skimage.filter.rank import autolevel - >>> # Load test image - >>> ima = data.camera() - >>> # Stretch image contrast locally - >>> auto = autolevel(ima, disk(20)) + >>> img = data.camera() + >>> auto = autolevel(img, disk(5)) """ @@ -117,17 +118,20 @@ def autolevel(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def bottomhat(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Returns greyscale local bottomhat of an image. + """Local bottom-hat of an image. + + This filter computes the morphological closing of the image and then + subtracts the result from the original image. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. - mask : ndarray + out : 2-D array (same dtype as input) + If None, a new array is allocated. + mask : 2-D array Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). shift_x, shift_y : int @@ -137,8 +141,16 @@ def bottomhat(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - bottomhat : ndarray (same dtype as input image) - The result of the local bottomhat. + out : 2-D array (same dtype as input image) + Output image. + + Examples + -------- + >>> from skimage import data + >>> from skimage.morphology import disk + >>> from skimage.filter.rank import bottomhat + >>> img = data.camera() + >>> out = bottomhat(img, disk(5)) """ @@ -151,12 +163,12 @@ def equalize(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -167,7 +179,7 @@ def equalize(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. Examples @@ -175,10 +187,8 @@ def equalize(image, selem, out=None, mask=None, shift_x=False, shift_y=False): >>> from skimage import data >>> from skimage.morphology import disk >>> from skimage.filter.rank import equalize - >>> # Load test image - >>> ima = data.camera() - >>> # Local equalization - >>> equ = equalize(ima, disk(20)) + >>> img = data.camera() + >>> equ = equalize(img, disk(5)) """ @@ -187,18 +197,16 @@ def equalize(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def gradient(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Return greyscale local gradient of an image (i.e. local maximum - local - minimum). - + """Return local gradient of an image (i.e. local maximum - local minimum). Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -209,9 +217,17 @@ def gradient(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. + Examples + -------- + >>> from skimage import data + >>> from skimage.morphology import disk + >>> from skimage.filter.rank import gradient + >>> img = data.camera() + >>> out = gradient(img, disk(5)) + """ return _apply(generic_cy._gradient, image, selem, @@ -219,17 +235,16 @@ def gradient(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def maximum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Return greyscale local maximum of an image. - + """Return local maximum of an image. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -240,7 +255,7 @@ def maximum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. See also @@ -249,8 +264,16 @@ def maximum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Notes ----- - * the lower algorithm complexity makes the rank.maximum() more efficient - for larger images and structuring elements + The lower algorithm complexity makes the `skimage.filter.rank.maximum` + more efficient for larger images and structuring elements. + + Examples + -------- + >>> from skimage import data + >>> from skimage.morphology import disk + >>> from skimage.filter.rank import maximum + >>> img = data.camera() + >>> out = maximum(img, disk(5)) """ @@ -259,16 +282,16 @@ def maximum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def mean(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Return greyscale local mean of an image. + """Return local mean of an image. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -279,7 +302,7 @@ def mean(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. Examples @@ -287,10 +310,8 @@ def mean(image, selem, out=None, mask=None, shift_x=False, shift_y=False): >>> from skimage import data >>> from skimage.morphology import disk >>> from skimage.filter.rank import mean - >>> # Load test image - >>> ima = data.camera() - >>> # Local mean - >>> avg = mean(ima, disk(20)) + >>> img = data.camera() + >>> avg = mean(img, disk(5)) """ @@ -304,12 +325,12 @@ def subtract_mean(image, selem, out=None, mask=None, shift_x=False, Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -320,9 +341,17 @@ def subtract_mean(image, selem, out=None, mask=None, shift_x=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. + Examples + -------- + >>> from skimage import data + >>> from skimage.morphology import disk + >>> from skimage.filter.rank import subtract_mean + >>> img = data.camera() + >>> out = subtract_mean(img, disk(5)) + """ return _apply(generic_cy._subtract_mean, image, selem, @@ -330,16 +359,16 @@ def subtract_mean(image, selem, out=None, mask=None, shift_x=False, def median(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Return greyscale local median of an image. + """Return local median of an image. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -350,7 +379,7 @@ def median(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. Examples @@ -358,10 +387,8 @@ def median(image, selem, out=None, mask=None, shift_x=False, shift_y=False): >>> from skimage import data >>> from skimage.morphology import disk >>> from skimage.filter.rank import median - >>> # Load test image - >>> ima = data.camera() - >>> # Local mean - >>> avg = median(ima, disk(20)) + >>> img = data.camera() + >>> med = median(img, disk(5)) """ @@ -370,16 +397,16 @@ def median(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def minimum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Return greyscale local minimum of an image. + """Return local minimum of an image. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -390,7 +417,7 @@ def minimum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. See also @@ -399,8 +426,16 @@ def minimum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Notes ----- - * the lower algorithm complexity makes the rank.minimum() more efficient - for larger images and structuring elements + The lower algorithm complexity makes the `skimage.filter.rank.minimum` more + efficient for larger images and structuring elements. + + Examples + -------- + >>> from skimage import data + >>> from skimage.morphology import disk + >>> from skimage.filter.rank import minimum + >>> img = data.camera() + >>> out = minimum(img, disk(5)) """ @@ -409,16 +444,18 @@ def minimum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def modal(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Return greyscale local mode of an image. + """Return local mode of an image. + + The mode is the value that appears most often in the local histogram. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -429,9 +466,17 @@ def modal(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. + Examples + -------- + >>> from skimage import data + >>> from skimage.morphology import disk + >>> from skimage.filter.rank import modal + >>> img = data.camera() + >>> out = modal(img, disk(5)) + """ return _apply(generic_cy._modal, image, selem, @@ -440,18 +485,20 @@ def modal(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def enhance_contrast(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Enhance an image replacing each pixel by the local maximum if pixel - greylevel is closest to maximimum than local minimum OR local minimum - otherwise. + """Enhance contrast of an image. + + This replaces each pixel by the local maximum if the pixel greyvalue is + closer to the local maximum than the local minimum. Otherwise it is + replaced by the local minimum. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -462,7 +509,7 @@ def enhance_contrast(image, selem, out=None, mask=None, shift_x=False, Returns Output image. - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) The result of the local enhance_contrast. Examples @@ -470,10 +517,8 @@ def enhance_contrast(image, selem, out=None, mask=None, shift_x=False, >>> from skimage import data >>> from skimage.morphology import disk >>> from skimage.filter.rank import enhance_contrast - >>> # Load test image - >>> ima = data.camera() - >>> # Local mean - >>> avg = enhance_contrast(ima, disk(20)) + >>> img = data.camera() + >>> out = enhance_contrast(img, disk(5)) """ @@ -482,17 +527,19 @@ def enhance_contrast(image, selem, out=None, mask=None, shift_x=False, def pop(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Return the number (population) of pixels actually inside the - neighborhood. + """Return the local number (population) of pixels. + + The number of pixels is defined as the number of pixels which are included + in the structuring element and the mask. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -503,19 +550,19 @@ def pop(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. Examples -------- >>> from skimage.morphology import square >>> import skimage.filter.rank as rank - >>> ima = 255 * np.array([[0, 0, 0, 0, 0], + >>> img = 255 * np.array([[0, 0, 0, 0, 0], ... [0, 1, 1, 1, 0], ... [0, 1, 1, 1, 0], ... [0, 1, 1, 1, 0], ... [0, 0, 0, 0, 0]], dtype=np.uint8) - >>> rank.pop(ima, square(3)) + >>> rank.pop(img, square(3)) array([[4, 6, 6, 6, 4], [6, 9, 9, 9, 6], [6, 9, 9, 9, 6], @@ -527,17 +574,21 @@ def pop(image, selem, out=None, mask=None, shift_x=False, shift_y=False): return _apply(generic_cy._pop, image, selem, out=out, mask=mask, shift_x=shift_x, shift_y=shift_y) + def sum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Return the sum of pixels inside the neighborhood (truncated to uint8 or uint16). + """Return the local sum of pixels. + + Note that the sum may overflow depending on the data type of the input + array. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -548,19 +599,19 @@ def sum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. Examples -------- >>> from skimage.morphology import square >>> import skimage.filter.rank as rank - >>> ima = np.array([[0, 0, 0, 0, 0], + >>> img = np.array([[0, 0, 0, 0, 0], ... [0, 1, 1, 1, 0], ... [0, 1, 1, 1, 0], ... [0, 1, 1, 1, 0], ... [0, 0, 0, 0, 0]], dtype=np.uint8) - >>> rank.sum(ima, square(3)) + >>> rank.sum(img, square(3)) array([[1, 2, 3, 2, 1], [2, 4, 6, 4, 2], [3, 6, 9, 6, 3], @@ -574,16 +625,19 @@ def sum(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def threshold(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Return greyscale local threshold of an image. + """Local threshold of an image. + + The resulting binary mask is True if the greyvalue of the center pixel is + greater than the local mean. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -594,20 +648,19 @@ def threshold(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. Examples -------- - >>> # Local threshold >>> from skimage.morphology import square >>> from skimage.filter.rank import threshold - >>> ima = 255 * np.array([[0, 0, 0, 0, 0], + >>> img = 255 * np.array([[0, 0, 0, 0, 0], ... [0, 1, 1, 1, 0], ... [0, 1, 1, 1, 0], ... [0, 1, 1, 1, 0], ... [0, 0, 0, 0, 0]], dtype=np.uint8) - >>> threshold(ima, square(3)) + >>> threshold(img, square(3)) array([[0, 0, 0, 0, 0], [0, 1, 1, 1, 0], [0, 1, 0, 1, 0], @@ -621,16 +674,19 @@ def threshold(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def tophat(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Return greyscale local tophat of an image. + """Local top-hat of an image. + + This filter computes the morphological opening of the image and then + subtracts the result from the original image. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -641,9 +697,17 @@ def tophat(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. + Examples + -------- + >>> from skimage import data + >>> from skimage.morphology import disk + >>> from skimage.filter.rank import tophat + >>> img = data.camera() + >>> out = tophat(img, disk(5)) + """ return _apply(generic_cy._tophat, image, selem, @@ -652,16 +716,16 @@ def tophat(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def noise_filter(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Returns the noise feature as described in [Hashimoto12]_ + """Noise feature as described in [Hashimoto12]_. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -677,9 +741,17 @@ def noise_filter(image, selem, out=None, mask=None, shift_x=False, Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. + Examples + -------- + >>> from skimage import data + >>> from skimage.morphology import disk + >>> from skimage.filter.rank import noise_filter + >>> img = data.camera() + >>> out = noise_filter(img, disk(5)) + """ # ensure that the central pixel in the structuring element is empty @@ -694,18 +766,19 @@ def noise_filter(image, selem, out=None, mask=None, shift_x=False, def entropy(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Returns the entropy [1]_ computed locally. Entropy is computed - using base 2 logarithm i.e. the filter returns the minimum number of - bits needed to encode local greylevel distribution. + """Local entropy [1]_. + + The entropy is computed using base 2 logarithm i.e. the filter returns the + minimum number of bits needed to encode the local greylevel distribution. Parameters ---------- - image : ndarray (uint8, uint16) - Image array. - selem : ndarray + image : 2-D array (uint8, uint16) + Input image. + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. - out : ndarray (same dtype as input) - If None, a new array will be allocated. + out : 2-D array (same dtype as input) + If None, a new array is allocated. mask : ndarray Mask array that defines (>0) area of the image included in the local neighborhood. If None, the complete image is used (default). @@ -721,16 +794,15 @@ def entropy(image, selem, out=None, mask=None, shift_x=False, shift_y=False): References ---------- - .. [1] http://en.wikipedia.org/wiki/Entropy_(information_theory)> + .. [1] http://en.wikipedia.org/wiki/Entropy_(information_theory) Examples -------- - >>> # Local entropy >>> from skimage import data >>> from skimage.filter.rank import entropy >>> from skimage.morphology import disk - >>> a8 = data.camera() - >>> ent8 = entropy(a8, disk(5)) + >>> img = data.camera() + >>> ent = entropy(img, disk(5)) """ @@ -740,13 +812,13 @@ def entropy(image, selem, out=None, mask=None, shift_x=False, shift_y=False): def otsu(image, selem, out=None, mask=None, shift_x=False, shift_y=False): - """Returns the Otsu's threshold value for each pixel. + """Local Otsu's threshold value for each pixel. Parameters ---------- image : ndarray Image array (uint8 array). - selem : ndarray + selem : 2-D array The neighborhood expressed as a 2-D array of 1's and 0's. out : ndarray If None, a new array will be allocated. @@ -760,7 +832,7 @@ def otsu(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Returns ------- - out : ndarray (same dtype as input image) + out : 2-D array (same dtype as input image) Output image. References @@ -769,14 +841,12 @@ def otsu(image, selem, out=None, mask=None, shift_x=False, shift_y=False): Examples -------- - >>> # Local entropy >>> from skimage import data >>> from skimage.filter.rank import otsu >>> from skimage.morphology import disk - >>> # defining a 8-bit test images - >>> a8 = data.camera() - >>> loc_otsu = otsu(a8, disk(5)) - >>> thresh_image = a8 >= loc_otsu + >>> img = data.camera() + >>> local_otsu = otsu(img, disk(5)) + >>> thresh_image = img >= local_otsu """ diff --git a/skimage/filter/rank/generic_cy.pyx b/skimage/filter/rank/generic_cy.pyx index 2a1a8455..1c26cf53 100644 --- a/skimage/filter/rank/generic_cy.pyx +++ b/skimage/filter/rank/generic_cy.pyx @@ -221,6 +221,7 @@ cdef inline double _kernel_pop(Py_ssize_t* histo, double pop, dtype_t g, return pop + cdef inline double _kernel_sum(Py_ssize_t* histo, double pop,dtype_t g, Py_ssize_t max_bin, Py_ssize_t mid_bin, double p0, double p1,