scikit-image

1
import numpy as np
2
from ..util import view_as_blocks
3

4

5
def block_reduce(image, block_size=2, func=np.sum, cval=0, func_kwargs=None):
6
    """Downsample image by applying function `func` to local blocks.
7

8
    This function is useful for max and mean pooling, for example.
9

10
    Parameters
11
    ----------
12
    image : (M[, ...]) ndarray
13
        N-dimensional input image.
14
    block_size : array_like or int
15
        Array containing down-sampling integer factor along each axis.
16
        Default block_size is 2.
17
    func : callable
18
        Function object which is used to calculate the return value for each
19
        local block. This function must implement an ``axis`` parameter.
20
        Primary functions are ``numpy.sum``, ``numpy.min``, ``numpy.max``,
21
        ``numpy.mean`` and ``numpy.median``.  See also `func_kwargs`.
22
    cval : float
23
        Constant padding value if image is not perfectly divisible by the
24
        block size.
25
    func_kwargs : dict
26
        Keyword arguments passed to `func`. Notably useful for passing dtype
27
        argument to ``np.mean``. Takes dictionary of inputs, e.g.:
28
        ``func_kwargs={'dtype': np.float16})``.
29

30
    Returns
31
    -------
32
    image : ndarray
33
        Down-sampled image with same number of dimensions as input image.
34

35
    Examples
36
    --------
37
    >>> from skimage.measure import block_reduce
38
    >>> image = np.arange(3*3*4).reshape(3, 3, 4)
39
    >>> image # doctest: +NORMALIZE_WHITESPACE
40
    array([[[ 0,  1,  2,  3],
41
            [ 4,  5,  6,  7],
42
            [ 8,  9, 10, 11]],
43
           [[12, 13, 14, 15],
44
            [16, 17, 18, 19],
45
            [20, 21, 22, 23]],
46
           [[24, 25, 26, 27],
47
            [28, 29, 30, 31],
48
            [32, 33, 34, 35]]])
49
    >>> block_reduce(image, block_size=(3, 3, 1), func=np.mean)
50
    array([[[16., 17., 18., 19.]]])
51
    >>> image_max1 = block_reduce(image, block_size=(1, 3, 4), func=np.max)
52
    >>> image_max1 # doctest: +NORMALIZE_WHITESPACE
53
    array([[[11]],
54
           [[23]],
55
           [[35]]])
56
    >>> image_max2 = block_reduce(image, block_size=(3, 1, 4), func=np.max)
57
    >>> image_max2 # doctest: +NORMALIZE_WHITESPACE
58
    array([[[27],
59
            [31],
60
            [35]]])
61
    """
62

63
    if np.isscalar(block_size):
64
        block_size = (block_size,) * image.ndim
65
    elif len(block_size) != image.ndim:
66
        raise ValueError(
67
            "`block_size` must be a scalar or have " "the same length as `image.shape`"
68
        )
69

70
    if func_kwargs is None:
71
        func_kwargs = {}
72

73
    pad_width = []
74
    for i in range(len(block_size)):
75
        if block_size[i] < 1:
76
            raise ValueError(
77
                "Down-sampling factors must be >= 1. Use "
78
                "`skimage.transform.resize` to up-sample an "
79
                "image."
80
            )
81
        if image.shape[i] % block_size[i] != 0:
82
            after_width = block_size[i] - (image.shape[i] % block_size[i])
83
        else:
84
            after_width = 0
85
        pad_width.append((0, after_width))
86

87
    if np.any(np.asarray(pad_width)):
88
        image = np.pad(
89
            image, pad_width=pad_width, mode='constant', constant_values=cval
90
        )
91

92
    blocked = view_as_blocks(image, block_size)
93

94
    return func(blocked, axis=tuple(range(image.ndim, blocked.ndim)), **func_kwargs)
95