W3cubDocs

/scikit-image

Module: util

skimage.util.img_as_float32(image[, force_copy]) Convert an image to single-precision (32-bit) floating point format.
skimage.util.img_as_float64(image[, force_copy]) Convert an image to double-precision (64-bit) floating point format.
skimage.util.img_as_float(image[, force_copy]) Convert an image to floating point format.
skimage.util.img_as_int(image[, force_copy]) Convert an image to 16-bit signed integer format.
skimage.util.img_as_uint(image[, force_copy]) Convert an image to 16-bit unsigned integer format.
skimage.util.img_as_ubyte(image[, force_copy]) Convert an image to 8-bit unsigned integer format.
skimage.util.img_as_bool(image[, force_copy]) Convert an image to boolean format.
skimage.util.dtype_limits(image[, clip_negative]) Return intensity limits, i.e.
skimage.util.view_as_blocks(arr_in, block_shape) Block view of the input n-dimensional array (using re-striding).
skimage.util.view_as_windows(arr_in, …[, step]) Rolling window view of the input n-dimensional array.
skimage.util.pad(array, pad_width, mode, …) Pads an array.
skimage.util.crop(ar, crop_width[, copy, order]) Crop array ar by crop_width along each dimension.
skimage.util.montage(arr_in[, fill, …]) Create a montage of several single- or multichannel images.
skimage.util.montage2d(arr_in[, fill, …]) Deprecated function.
skimage.util.random_noise(image[, mode, …]) Function to add random noise of various types to a floating-point image.
skimage.util.regular_grid(ar_shape, n_points) Find n_points regularly spaced along ar_shape.
skimage.util.regular_seeds(ar_shape, n_points) Return an image with ~`n_points` regularly-spaced nonzero pixels.
skimage.util.apply_parallel(function, array) Map a function in parallel across an array.
skimage.util.invert(image[, signed_float]) Invert an image.
skimage.util.unique_rows(ar) Remove repeated rows from a 2D array.

img_as_float32

skimage.util.img_as_float32(image, force_copy=False) [source]

Convert an image to single-precision (32-bit) floating point format.

Parameters:
image : ndarray

Input image.

force_copy : bool, optional

Force a copy of the data, irrespective of its current dtype.

Returns:
out : ndarray of float32

Output image.

Notes

The range of a floating point image is [0.0, 1.0] or [-1.0, 1.0] when converting from unsigned or signed datatypes, respectively. If the input image has a float type, intensity values are not modified and can be outside the ranges [0.0, 1.0] or [-1.0, 1.0].

img_as_float64

skimage.util.img_as_float64(image, force_copy=False) [source]

Convert an image to double-precision (64-bit) floating point format.

Parameters:
image : ndarray

Input image.

force_copy : bool, optional

Force a copy of the data, irrespective of its current dtype.

Returns:
out : ndarray of float64

Output image.

Notes

The range of a floating point image is [0.0, 1.0] or [-1.0, 1.0] when converting from unsigned or signed datatypes, respectively. If the input image has a float type, intensity values are not modified and can be outside the ranges [0.0, 1.0] or [-1.0, 1.0].

img_as_float

skimage.util.img_as_float(image, force_copy=False) [source]

Convert an image to floating point format.

This function is similar to img_as_float64, but will not convert lower-precision floating point arrays to float64.

Parameters:
image : ndarray

Input image.

force_copy : bool, optional

Force a copy of the data, irrespective of its current dtype.

Returns:
out : ndarray of float

Output image.

Notes

The range of a floating point image is [0.0, 1.0] or [-1.0, 1.0] when converting from unsigned or signed datatypes, respectively. If the input image has a float type, intensity values are not modified and can be outside the ranges [0.0, 1.0] or [-1.0, 1.0].

img_as_int

skimage.util.img_as_int(image, force_copy=False) [source]

Convert an image to 16-bit signed integer format.

Parameters:
image : ndarray

Input image.

force_copy : bool, optional

Force a copy of the data, irrespective of its current dtype.

Returns:
out : ndarray of uint16

Output image.

Notes

The values are scaled between -32768 and 32767. If the input data-type is positive-only (e.g., uint8), then the output image will still only have positive values.

img_as_uint

skimage.util.img_as_uint(image, force_copy=False) [source]

Convert an image to 16-bit unsigned integer format.

Parameters:
image : ndarray

Input image.

force_copy : bool, optional

Force a copy of the data, irrespective of its current dtype.

Returns:
out : ndarray of uint16

Output image.

Notes

Negative input values will be clipped. Positive values are scaled between 0 and 65535.

img_as_ubyte

skimage.util.img_as_ubyte(image, force_copy=False) [source]

Convert an image to 8-bit unsigned integer format.

Parameters:
image : ndarray

Input image.

force_copy : bool, optional

Force a copy of the data, irrespective of its current dtype.

Returns:
out : ndarray of ubyte (uint8)

Output image.

Notes

Negative input values will be clipped. Positive values are scaled between 0 and 255.

img_as_bool

skimage.util.img_as_bool(image, force_copy=False) [source]

Convert an image to boolean format.

Parameters:
image : ndarray

Input image.

force_copy : bool, optional

Force a copy of the data, irrespective of its current dtype.

Returns:
out : ndarray of bool (bool_)

Output image.

Notes

The upper half of the input dtype’s positive range is True, and the lower half is False. All negative values (if present) are False.

dtype_limits

skimage.util.dtype_limits(image, clip_negative=None) [source]

Return intensity limits, i.e. (min, max) tuple, of the image’s dtype.

Parameters:
image : ndarray

Input image.

clip_negative : bool, optional

If True, clip the negative range (i.e. return 0 for min intensity) even if the image dtype allows negative values. The default behavior (None) is equivalent to True.

Returns:
imin, imax : tuple

Lower and upper intensity limits.

view_as_blocks

skimage.util.view_as_blocks(arr_in, block_shape) [source]

Block view of the input n-dimensional array (using re-striding).

Blocks are non-overlapping views of the input array.

Parameters:
arr_in : ndarray

N-d input array.

block_shape : tuple

The shape of the block. Each dimension must divide evenly into the corresponding dimensions of arr_in.

Returns:
arr_out : ndarray

Block view of the input array. If arr_in is non-contiguous, a copy is made.

Examples

>>> import numpy as np
>>> from skimage.util.shape import view_as_blocks
>>> A = np.arange(4*4).reshape(4,4)
>>> A
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11],
       [12, 13, 14, 15]])
>>> B = view_as_blocks(A, block_shape=(2, 2))
>>> B[0, 0]
array([[0, 1],
       [4, 5]])
>>> B[0, 1]
array([[2, 3],
       [6, 7]])
>>> B[1, 0, 1, 1]
13
>>> A = np.arange(4*4*6).reshape(4,4,6)
>>> A  # doctest: +NORMALIZE_WHITESPACE
array([[[ 0,  1,  2,  3,  4,  5],
        [ 6,  7,  8,  9, 10, 11],
        [12, 13, 14, 15, 16, 17],
        [18, 19, 20, 21, 22, 23]],
       [[24, 25, 26, 27, 28, 29],
        [30, 31, 32, 33, 34, 35],
        [36, 37, 38, 39, 40, 41],
        [42, 43, 44, 45, 46, 47]],
       [[48, 49, 50, 51, 52, 53],
        [54, 55, 56, 57, 58, 59],
        [60, 61, 62, 63, 64, 65],
        [66, 67, 68, 69, 70, 71]],
       [[72, 73, 74, 75, 76, 77],
        [78, 79, 80, 81, 82, 83],
        [84, 85, 86, 87, 88, 89],
        [90, 91, 92, 93, 94, 95]]])
>>> B = view_as_blocks(A, block_shape=(1, 2, 2))
>>> B.shape
(4, 2, 3, 1, 2, 2)
>>> B[2:, 0, 2]  # doctest: +NORMALIZE_WHITESPACE
array([[[[52, 53],
         [58, 59]]],
       [[[76, 77],
         [82, 83]]]])

view_as_windows

skimage.util.view_as_windows(arr_in, window_shape, step=1) [source]

Rolling window view of the input n-dimensional array.

Windows are overlapping views of the input array, with adjacent windows shifted by a single row or column (or an index of a higher dimension).

Parameters:
arr_in : ndarray

N-d input array.

window_shape : integer or tuple of length arr_in.ndim

Defines the shape of the elementary n-dimensional orthotope (better know as hyperrectangle [1]) of the rolling window view. If an integer is given, the shape will be a hypercube of sidelength given by its value.

step : integer or tuple of length arr_in.ndim

Indicates step size at which extraction shall be performed. If integer is given, then the step is uniform in all dimensions.

Returns:
arr_out : ndarray

(rolling) window view of the input array. If arr_in is non-contiguous, a copy is made.

Notes

One should be very careful with rolling views when it comes to memory usage. Indeed, although a ‘view’ has the same memory footprint as its base array, the actual array that emerges when this ‘view’ is used in a computation is generally a (much) larger array than the original, especially for 2-dimensional arrays and above.

For example, let us consider a 3 dimensional array of size (100, 100, 100) of float64. This array takes about 8*100**3 Bytes for storage which is just 8 MB. If one decides to build a rolling view on this array with a window of (3, 3, 3) the hypothetical size of the rolling view (if one was to reshape the view for example) would be 8*(100-3+1)**3*3**3 which is about 203 MB! The scaling becomes even worse as the dimension of the input array becomes larger.

References

[1] (1, 2) http://en.wikipedia.org/wiki/Hyperrectangle

Examples

>>> import numpy as np
>>> from skimage.util.shape import view_as_windows
>>> A = np.arange(4*4).reshape(4,4)
>>> A
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11],
       [12, 13, 14, 15]])
>>> window_shape = (2, 2)
>>> B = view_as_windows(A, window_shape)
>>> B[0, 0]
array([[0, 1],
       [4, 5]])
>>> B[0, 1]
array([[1, 2],
       [5, 6]])
>>> A = np.arange(10)
>>> A
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> window_shape = (3,)
>>> B = view_as_windows(A, window_shape)
>>> B.shape
(8, 3)
>>> B
array([[0, 1, 2],
       [1, 2, 3],
       [2, 3, 4],
       [3, 4, 5],
       [4, 5, 6],
       [5, 6, 7],
       [6, 7, 8],
       [7, 8, 9]])
>>> A = np.arange(5*4).reshape(5, 4)
>>> A
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11],
       [12, 13, 14, 15],
       [16, 17, 18, 19]])
>>> window_shape = (4, 3)
>>> B = view_as_windows(A, window_shape)
>>> B.shape
(2, 2, 4, 3)
>>> B  # doctest: +NORMALIZE_WHITESPACE
array([[[[ 0,  1,  2],
         [ 4,  5,  6],
         [ 8,  9, 10],
         [12, 13, 14]],
        [[ 1,  2,  3],
         [ 5,  6,  7],
         [ 9, 10, 11],
         [13, 14, 15]]],
       [[[ 4,  5,  6],
         [ 8,  9, 10],
         [12, 13, 14],
         [16, 17, 18]],
        [[ 5,  6,  7],
         [ 9, 10, 11],
         [13, 14, 15],
         [17, 18, 19]]]])

pad

skimage.util.pad(array, pad_width, mode, **kwargs) [source]

Pads an array.

Parameters:
array : array_like of rank N

Input array

pad_width : {sequence, array_like, int}

Number of values padded to the edges of each axis. ((before_1, after_1), … (before_N, after_N)) unique pad widths for each axis. ((before, after),) yields same before and after pad for each axis. (pad,) or int is a shortcut for before = after = pad width for all axes.

mode : str or function

One of the following string values or a user supplied function.

‘constant’

Pads with a constant value.

‘edge’

Pads with the edge values of array.

‘linear_ramp’

Pads with the linear ramp between end_value and the array edge value.

‘maximum’

Pads with the maximum value of all or part of the vector along each axis.

‘mean’

Pads with the mean value of all or part of the vector along each axis.

‘median’

Pads with the median value of all or part of the vector along each axis.

‘minimum’

Pads with the minimum value of all or part of the vector along each axis.

‘reflect’

Pads with the reflection of the vector mirrored on the first and last values of the vector along each axis.

‘symmetric’

Pads with the reflection of the vector mirrored along the edge of the array.

‘wrap’

Pads with the wrap of the vector along the axis. The first values are used to pad the end and the end values are used to pad the beginning.

<function>

Padding function, see Notes.

stat_length : sequence or int, optional

Used in ‘maximum’, ‘mean’, ‘median’, and ‘minimum’. Number of values at edge of each axis used to calculate the statistic value.

((before_1, after_1), … (before_N, after_N)) unique statistic lengths for each axis.

((before, after),) yields same before and after statistic lengths for each axis.

(stat_length,) or int is a shortcut for before = after = statistic length for all axes.

Default is None, to use the entire axis.

constant_values : sequence or int, optional

Used in ‘constant’. The values to set the padded values for each axis.

((before_1, after_1), … (before_N, after_N)) unique pad constants for each axis.

((before, after),) yields same before and after constants for each axis.

(constant,) or int is a shortcut for before = after = constant for all axes.

Default is 0.

end_values : sequence or int, optional

Used in ‘linear_ramp’. The values used for the ending value of the linear_ramp and that will form the edge of the padded array.

((before_1, after_1), … (before_N, after_N)) unique end values for each axis.

((before, after),) yields same before and after end values for each axis.

(constant,) or int is a shortcut for before = after = end value for all axes.

Default is 0.

reflect_type : {‘even’, ‘odd’}, optional

Used in ‘reflect’, and ‘symmetric’. The ‘even’ style is the default with an unaltered reflection around the edge value. For the ‘odd’ style, the extented part of the array is created by subtracting the reflected values from two times the edge value.

Returns:
pad : ndarray

Padded array of rank equal to array with shape increased according to pad_width.

Notes

New in version 1.7.0.

For an array with rank greater than 1, some of the padding of later axes is calculated from padding of previous axes. This is easiest to think about with a rank 2 array where the corners of the padded array are calculated by using padded values from the first axis.

The padding function, if used, should return a rank 1 array equal in length to the vector argument with padded values replaced. It has the following signature:

padding_func(vector, iaxis_pad_width, iaxis, kwargs)

where

vector : ndarray
A rank 1 array already padded with zeros. Padded values are vector[:pad_tuple[0]] and vector[-pad_tuple[1]:].
iaxis_pad_width : tuple
A 2-tuple of ints, iaxis_pad_width[0] represents the number of values padded at the beginning of vector where iaxis_pad_width[1] represents the number of values padded at the end of vector.
iaxis : int
The axis currently being calculated.
kwargs : dict
Any keyword arguments the function requires.

Examples

>>> a = [1, 2, 3, 4, 5]
>>> np.pad(a, (2,3), 'constant', constant_values=(4, 6))
array([4, 4, 1, 2, 3, 4, 5, 6, 6, 6])
>>> np.pad(a, (2, 3), 'edge')
array([1, 1, 1, 2, 3, 4, 5, 5, 5, 5])
>>> np.pad(a, (2, 3), 'linear_ramp', end_values=(5, -4))
array([ 5,  3,  1,  2,  3,  4,  5,  2, -1, -4])
>>> np.pad(a, (2,), 'maximum')
array([5, 5, 1, 2, 3, 4, 5, 5, 5])
>>> np.pad(a, (2,), 'mean')
array([3, 3, 1, 2, 3, 4, 5, 3, 3])
>>> np.pad(a, (2,), 'median')
array([3, 3, 1, 2, 3, 4, 5, 3, 3])
>>> a = [[1, 2], [3, 4]]
>>> np.pad(a, ((3, 2), (2, 3)), 'minimum')
array([[1, 1, 1, 2, 1, 1, 1],
       [1, 1, 1, 2, 1, 1, 1],
       [1, 1, 1, 2, 1, 1, 1],
       [1, 1, 1, 2, 1, 1, 1],
       [3, 3, 3, 4, 3, 3, 3],
       [1, 1, 1, 2, 1, 1, 1],
       [1, 1, 1, 2, 1, 1, 1]])
>>> a = [1, 2, 3, 4, 5]
>>> np.pad(a, (2, 3), 'reflect')
array([3, 2, 1, 2, 3, 4, 5, 4, 3, 2])
>>> np.pad(a, (2, 3), 'reflect', reflect_type='odd')
array([-1,  0,  1,  2,  3,  4,  5,  6,  7,  8])
>>> np.pad(a, (2, 3), 'symmetric')
array([2, 1, 1, 2, 3, 4, 5, 5, 4, 3])
>>> np.pad(a, (2, 3), 'symmetric', reflect_type='odd')
array([0, 1, 1, 2, 3, 4, 5, 5, 6, 7])
>>> np.pad(a, (2, 3), 'wrap')
array([4, 5, 1, 2, 3, 4, 5, 1, 2, 3])
>>> def pad_with(vector, pad_width, iaxis, kwargs):
...     pad_value = kwargs.get('padder', 10)
...     vector[:pad_width[0]] = pad_value
...     vector[-pad_width[1]:] = pad_value
...     return vector
>>> a = np.arange(6)
>>> a = a.reshape((2, 3))
>>> np.pad(a, 2, pad_with)
array([[10, 10, 10, 10, 10, 10, 10],
       [10, 10, 10, 10, 10, 10, 10],
       [10, 10,  0,  1,  2, 10, 10],
       [10, 10,  3,  4,  5, 10, 10],
       [10, 10, 10, 10, 10, 10, 10],
       [10, 10, 10, 10, 10, 10, 10]])
>>> np.pad(a, 2, pad_with, padder=100)
array([[100, 100, 100, 100, 100, 100, 100],
       [100, 100, 100, 100, 100, 100, 100],
       [100, 100,   0,   1,   2, 100, 100],
       [100, 100,   3,   4,   5, 100, 100],
       [100, 100, 100, 100, 100, 100, 100],
       [100, 100, 100, 100, 100, 100, 100]])

crop

skimage.util.crop(ar, crop_width, copy=False, order='K') [source]

Crop array ar by crop_width along each dimension.

Parameters:
ar : array-like of rank N

Input array.

crop_width : {sequence, int}

Number of values to remove from the edges of each axis. ((before_1, after_1),(before_N, after_N)) specifies unique crop widths at the start and end of each axis. ((before, after),) specifies a fixed start and end crop for every axis. (n,) or n for integer n is a shortcut for before = after = n for all axes.

copy : bool, optional

If True, ensure the returned array is a contiguous copy. Normally, a crop operation will return a discontiguous view of the underlying input array.

order : {‘C’, ‘F’, ‘A’, ‘K’}, optional

If copy==True, control the memory layout of the copy. See np.copy.

Returns:
cropped : array

The cropped array. If copy=False (default), this is a sliced view of the input array.

montage

skimage.util.montage(arr_in, fill='mean', rescale_intensity=False, grid_shape=None, padding_width=0, multichannel=False) [source]

Create a montage of several single- or multichannel images.

Create a rectangular montage from an input array representing an ensemble of equally shaped single- (gray) or multichannel (color) images.

For example, montage(arr_in) called with the following arr_in

1 2 3

will return

1 2
3

where the ‘*’ patch will be determined by the fill parameter.

Parameters:
arr_in : (K, M, N[, C]) ndarray

An array representing an ensemble of K images of equal shape.

fill : float or array-like of floats or ‘mean’, optional

Value to fill the padding areas and/or the extra tiles in the output array. Has to be float for single channel collections. For multichannel collections has to be an array-like of shape of number of channels. If mean, uses the mean value over all images.

rescale_intensity : bool, optional

Whether to rescale the intensity of each image to [0, 1].

grid_shape : tuple, optional

The desired grid shape for the montage (ntiles_row, ntiles_column). The default aspect ratio is square.

padding_width : int, optional

The size of the spacing between the tiles and between the tiles and the borders. If non-zero, makes the boundaries of individual images easier to perceive.

multichannel : boolean, optional

If True, the last arr_in dimension is threated as a color channel, otherwise as spatial.

Returns:
arr_out : (K*(M+p)+p, K*(N+p)+p[, C]) ndarray

Output array with input images glued together (including padding p).

Examples

>>> import numpy as np
>>> from skimage.util import montage
>>> arr_in = np.arange(3 * 2 * 2).reshape(3, 2, 2)
>>> arr_in  # doctest: +NORMALIZE_WHITESPACE
array([[[ 0,  1],
        [ 2,  3]],
       [[ 4,  5],
        [ 6,  7]],
       [[ 8,  9],
        [10, 11]]])
>>> arr_out = montage(arr_in)
>>> arr_out.shape
(4, 4)
>>> arr_out
array([[ 0,  1,  4,  5],
       [ 2,  3,  6,  7],
       [ 8,  9,  5,  5],
       [10, 11,  5,  5]])
>>> arr_in.mean()
5.5
>>> arr_out_nonsquare = montage(arr_in, grid_shape=(1, 3))
>>> arr_out_nonsquare
array([[ 0,  1,  4,  5,  8,  9],
       [ 2,  3,  6,  7, 10, 11]])
>>> arr_out_nonsquare.shape
(2, 6)

montage2d

skimage.util.montage2d(arr_in, fill='mean', rescale_intensity=False, grid_shape=None, padding_width=0) [source]

Deprecated function. Use montage instead.

Create a 2-dimensional ‘montage’ from a 3-dimensional input array representing an ensemble of equally shaped 2-dimensional images.

For example, montage2d(arr_in, fill) with the following arr_in

1 2 3

will return:

1 2
3

Where the ‘*’ patch will be determined by the fill parameter.

Parameters:
arr_in : ndarray, shape=[n_images, height, width]

3-dimensional input array representing an ensemble of n_images of equal shape (i.e. [height, width]).

fill : float or ‘mean’, optional

How to fill the 2-dimensional output array when sqrt(n_images) is not an integer. If ‘mean’ is chosen, then fill = arr_in.mean().

rescale_intensity : bool, optional

Whether to rescale the intensity of each image to [0, 1].

grid_shape : tuple, optional

The desired grid shape for the montage (tiles_y, tiles_x). The default aspect ratio is square.

padding_width : int, optional

The size of the spacing between the tiles to make the boundaries of individual frames easier to see.

Returns:
arr_out : ndarray, shape=[alpha * height, alpha * width]

Output array where ‘alpha’ has been determined automatically to fit (at least) the n_images in arr_in.

Examples

>>> import numpy as np
>>> from skimage.util import montage2d
>>> arr_in = np.arange(3 * 2 * 2).reshape(3, 2, 2)
>>> arr_in  # doctest: +NORMALIZE_WHITESPACE
array([[[ 0,  1],
        [ 2,  3]],
       [[ 4,  5],
        [ 6,  7]],
       [[ 8,  9],
        [10, 11]]])
>>> arr_out = montage2d(arr_in)
>>> arr_out.shape
(4, 4)
>>> arr_out
array([[ 0,  1,  4,  5],
       [ 2,  3,  6,  7],
       [ 8,  9,  5,  5],
       [10, 11,  5,  5]])
>>> arr_in.mean()
5.5
>>> arr_out_nonsquare = montage2d(arr_in, grid_shape=(1, 3))
>>> arr_out_nonsquare
array([[ 0,  1,  4,  5,  8,  9],
       [ 2,  3,  6,  7, 10, 11]])
>>> arr_out_nonsquare.shape
(2, 6)

random_noise

skimage.util.random_noise(image, mode='gaussian', seed=None, clip=True, **kwargs) [source]

Function to add random noise of various types to a floating-point image.

Parameters:
image : ndarray

Input image data. Will be converted to float.

mode : str

One of the following strings, selecting the type of noise to add:

  • ‘gaussian’ Gaussian-distributed additive noise.
  • ‘localvar’ Gaussian-distributed additive noise, with specified
    local variance at each point of image
  • ‘poisson’ Poisson-distributed noise generated from the data.
  • ‘salt’ Replaces random pixels with 1.
  • ‘pepper’ Replaces random pixels with 0 (for unsigned images) or
    -1 (for signed images).
  • ‘s&p’ Replaces random pixels with either 1 or low_val, where
    low_val is 0 for unsigned images or -1 for signed images.
  • ‘speckle’ Multiplicative noise using out = image + n*image, where
    n is uniform noise with specified mean & variance.
seed : int

If provided, this will set the random seed before generating noise, for valid pseudo-random comparisons.

clip : bool

If True (default), the output will be clipped after noise applied for modes ‘speckle’, ‘poisson’, and ‘gaussian’. This is needed to maintain the proper image data range. If False, clipping is not applied, and the output may extend beyond the range [-1, 1].

mean : float

Mean of random distribution. Used in ‘gaussian’ and ‘speckle’. Default : 0.

var : float

Variance of random distribution. Used in ‘gaussian’ and ‘speckle’. Note: variance = (standard deviation) ** 2. Default : 0.01

local_vars : ndarray

Array of positive floats, same shape as image, defining the local variance at every image point. Used in ‘localvar’.

amount : float

Proportion of image pixels to replace with noise on range [0, 1]. Used in ‘salt’, ‘pepper’, and ‘salt & pepper’. Default : 0.05

salt_vs_pepper : float

Proportion of salt vs. pepper noise for ‘s&p’ on range [0, 1]. Higher values represent more salt. Default : 0.5 (equal amounts)

Returns:
out : ndarray

Output floating-point image data on range [0, 1] or [-1, 1] if the input image was unsigned or signed, respectively.

Notes

Speckle, Poisson, Localvar, and Gaussian noise may generate noise outside the valid image range. The default is to clip (not alias) these values, but they may be preserved by setting clip=False. Note that in this case the output may contain values outside the ranges [0, 1] or [-1, 1]. Use this option with care.

Because of the prevalence of exclusively positive floating-point images in intermediate calculations, it is not possible to intuit if an input is signed based on dtype alone. Instead, negative values are explicity searched for. Only if found does this function assume signed input. Unexpected results only occur in rare, poorly exposes cases (e.g. if all values are above 50 percent gray in a signed image). In this event, manually scaling the input to the positive domain will solve the problem.

The Poisson distribution is only defined for positive integers. To apply this noise type, the number of unique values in the image is found and the next round power of two is used to scale up the floating-point result, after which it is scaled back down to the floating-point image range.

To generate Poisson noise against a signed image, the signed image is temporarily converted to an unsigned image in the floating point domain, Poisson noise is generated, then it is returned to the original range.

regular_grid

skimage.util.regular_grid(ar_shape, n_points) [source]

Find n_points regularly spaced along ar_shape.

The returned points (as slices) should be as close to cubically-spaced as possible. Essentially, the points are spaced by the Nth root of the input array size, where N is the number of dimensions. However, if an array dimension cannot fit a full step size, it is “discarded”, and the computation is done for only the remaining dimensions.

Parameters:
ar_shape : array-like of ints

The shape of the space embedding the grid. len(ar_shape) is the number of dimensions.

n_points : int

The (approximate) number of points to embed in the space.

Returns:
slices : tuple of slice objects

A slice along each dimension of ar_shape, such that the intersection of all the slices give the coordinates of regularly spaced points.

Changed in version 0.14.1: In scikit-image 0.14.1 and 0.15, the return type was changed from a list to a tuple to ensure compatibility with Numpy 1.15 and higher. If your code requires the returned result to be a list, you may convert the output of this function to a list with:

>>> result = list(regular_grid(ar_shape=(3, 20, 40), n_points=8))

Examples

>>> ar = np.zeros((20, 40))
>>> g = regular_grid(ar.shape, 8)
>>> g
(slice(5, None, 10), slice(5, None, 10))
>>> ar[g] = 1
>>> ar.sum()
8.0
>>> ar = np.zeros((20, 40))
>>> g = regular_grid(ar.shape, 32)
>>> g
(slice(2, None, 5), slice(2, None, 5))
>>> ar[g] = 1
>>> ar.sum()
32.0
>>> ar = np.zeros((3, 20, 40))
>>> g = regular_grid(ar.shape, 8)
>>> g
(slice(1, None, 3), slice(5, None, 10), slice(5, None, 10))
>>> ar[g] = 1
>>> ar.sum()
8.0

regular_seeds

skimage.util.regular_seeds(ar_shape, n_points, dtype=<class 'int'>) [source]

Return an image with ~`n_points` regularly-spaced nonzero pixels.

Parameters:
ar_shape : tuple of int

The shape of the desired output image.

n_points : int

The desired number of nonzero points.

dtype : numpy data type, optional

The desired data type of the output.

Returns:
seed_img : array of int or bool

The desired image.

Examples

>>> regular_seeds((5, 5), 4)
array([[0, 0, 0, 0, 0],
       [0, 1, 0, 2, 0],
       [0, 0, 0, 0, 0],
       [0, 3, 0, 4, 0],
       [0, 0, 0, 0, 0]])

apply_parallel

skimage.util.apply_parallel(function, array, chunks=None, depth=0, mode=None, extra_arguments=(), extra_keywords={}) [source]

Map a function in parallel across an array.

Split an array into possibly overlapping chunks of a given depth and boundary type, call the given function in parallel on the chunks, combine the chunks and return the resulting array.

Parameters:
function : function

Function to be mapped which takes an array as an argument.

array : numpy array

Array which the function will be applied to.

chunks : int, tuple, or tuple of tuples, optional

A single integer is interpreted as the length of one side of a square chunk that should be tiled across the array. One tuple of length array.ndim represents the shape of a chunk, and it is tiled across the array. A list of tuples of length ndim, where each sub-tuple is a sequence of chunk sizes along the corresponding dimension. If None, the array is broken up into chunks based on the number of available cpus. More information about chunks is in the documentation here.

depth : int, optional

Integer equal to the depth of the added boundary cells. Defaults to zero.

mode : {‘reflect’, ‘symmetric’, ‘periodic’, ‘wrap’, ‘nearest’, ‘edge’}, optional

type of external boundary padding.

extra_arguments : tuple, optional

Tuple of arguments to be passed to the function.

extra_keywords : dictionary, optional

Dictionary of keyword arguments to be passed to the function.

Notes

Numpy edge modes ‘symmetric’, ‘wrap’, and ‘edge’ are converted to the equivalent dask boundary modes ‘reflect’, ‘periodic’ and ‘nearest’, respectively.

invert

skimage.util.invert(image, signed_float=False) [source]

Invert an image.

Invert the intensity range of the input image, so that the dtype maximum is now the dtype minimum, and vice-versa. This operation is slightly different depending on the input dtype:

  • unsigned integers: subtract the image from the dtype maximum
  • signed integers: subtract the image from -1 (see Notes)
  • floats: subtract the image from 1 (if signed_float is False, so we assume the image is unsigned), or from 0 (if signed_float is True).

See the examples for clarification.

Parameters:
image : ndarray

Input image.

signed_float : bool, optional

If True and the image is of type float, the range is assumed to be [-1, 1]. If False and the image is of type float, the range is assumed to be [0, 1].

Returns:
inverted : ndarray

Inverted image.

Notes

Ideally, for signed integers we would simply multiply by -1. However, signed integer ranges are asymmetric. For example, for np.int8, the range of possible values is [-128, 127], so that -128 * -1 equals -128! By subtracting from -1, we correctly map the maximum dtype value to the minimum.

Examples

>>> img = np.array([[100,  0, 200],
...                 [  0, 50,   0],
...                 [ 30,  0, 255]], np.uint8)
>>> invert(img)
array([[155, 255,  55],
       [255, 205, 255],
       [225, 255,   0]], dtype=uint8)
>>> img2 = np.array([[ -2, 0, -128],
...                  [127, 0,    5]], np.int8)
>>> invert(img2)
array([[   1,   -1,  127],
       [-128,   -1,   -6]], dtype=int8)
>>> img3 = np.array([[ 0., 1., 0.5, 0.75]])
>>> invert(img3)
array([[ 1.  ,  0.  ,  0.5 ,  0.25]])
>>> img4 = np.array([[ 0., 1., -1., -0.25]])
>>> invert(img4, signed_float=True)
array([[-0.  , -1.  ,  1.  ,  0.25]])

unique_rows

skimage.util.unique_rows(ar) [source]

Remove repeated rows from a 2D array.

In particular, if given an array of coordinates of shape (Npoints, Ndim), it will remove repeated points.

Parameters:
ar : 2-D ndarray

The input array.

Returns:
ar_out : 2-D ndarray

A copy of the input array with repeated rows removed.

Raises:
ValueError : if ar is not two-dimensional.

Notes

The function will generate a copy of ar if it is not C-contiguous, which will negatively affect performance for large input arrays.

Examples

>>> ar = np.array([[1, 0, 1],
...                [0, 1, 0],
...                [1, 0, 1]], np.uint8)
>>> unique_rows(ar)
array([[0, 1, 0],
       [1, 0, 1]], dtype=uint8)

© 2011 the scikit-image team
Licensed under the BSD 3-clause License.
http://scikit-image.org/docs/0.14.x/api/skimage.util.html