A blocproc function for scikits-image

process.py

"""My thoughts on what a skimage version of Matlab's blockproc [1] function could look like.

[1] http://www.mathworks.com/help/images/ref/blockproc.html 
"""

def process_windows(arr_in, window_shape, proc_func=None, step_size=(0,0),
        border_size=(0,0), border_fill_mode='overlap', pad_mode='edge',
        **kwargs):
    """Map image windows for (optional) parallel according to specified
    windowing rule.

    Parameters
    ----------
    arr_in: ndarray
        The 2-dimensional input array.

    window_shape: tuple
        The 2-dimensional shape of the rolling window view.

    proc_func: function
        This function will be called for each resulting window. The
        function should be of the form:
            function(arr_window, window_def)
        where arr_window is the view of arr_in based on the window and
        border as specified and window_def is a tuple with:
            window_def = (window_shape, border_size, window_bbox)
        where window_bbox is the 2-dimensional bounding box of the
        resulting window.

    step_size: tuple
        Step size (2-dimensional). Defaults to window_shape so that
        default behaviour gives non-overlapping windows.

    border_size: tuple
        The amount (V,H) of border pixels to add to each window. The
        function adds V rows above and below each window and H columns
        left and right of each window.
        The size of each resulting window will be:
            [M + 2*V, N + 2*H]

    border_fill_mode: {str, function}
        Can be 'overlap' or any mode as accepted by skimage.util.pad.
        The 'overlap' mode will fill the border with the border values
        from arr_in itself, while skimage.util.pad will pad with values
        as defined by the pad mode. When 'overlap' is used, border value
        coordinates that fall outside of arr_in will be padded according
        to pad_mode.

    pad_mode: {str, function}
        Any mode that is accepted by skimage.util.pad. Will be used to
        fill border if border overlap falls outside of arr_in.

    Returns
    -------
    arr_out: ndarray
        (rolling) window view of the input array.
        See skimage.util.view_as_windows.

    return_values: tuple
        The window result as returned by each window's proc_func.

    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)
    >>> proc_func = lambda arr_window, window_def: np.sum(arr_window)
    >>> B, results = process_windows(A, window_shape, proc_func)
    >>> B[0, 0]
    array([[0, 1],
           [4, 5]])
    >>> results[0,0]
    10
    >>> B[0, 1]
    array([[1, 2],
           [5, 6]])
    >>> results[0,1]
    14
    """