'BorderSize' and 'TrimBorder' in MATLAB blockproc function

Question

Blockproc is a really useful function for "gridding" an image in MATLAB. It's pretty well documented, and it even comes complete with a tutorial page. However, when you want some sort of overlap between blocks, things get trickier. The Mathworks forums have some explanations, including this one and this one, and there's an attempt at an explanation here (Question #1), but nobody really explains anywhere why certain flags need to be set with other ones. Can someone please explain what the purpose of the 'BorderSize' parameter is? It seems that when 'Trim Borders' is set to false, the 'BorderSize' parameter does exactly what the documentation says (and what you'd expect):

'BorderSize': A two-element vector, [V H], specifying the amount of border pixels to add to each block. The function adds V rows above and below each block and H columns left and right of each block. The size of each resulting block will be: [M + 2*V, N + 2*H]

By default, the function automatically removes the border from the result of fun. See the 'TrimBorder' parameter for more information. The function pads blocks with borders extending beyond the image edges with zeros.

But when you read the 'TrimBorder' details, it doesn't clear up much:

'TrimBorder': A logical scalar. When set to true, the blockproc function trims off border pixels from the output of the user function, fun. The function removes V rows from the top and bottom of the output of fun, and H columns from the left and right edges. The 'BorderSize' parameter defines V and H. The default is true, meaning that the blockproc function automatically removes borders from the fun output.

Why would I want to include a 'BorderSize' (i.e. overlap tiles) but not apply it to the output? Is this just a poorly explained flag: 'TrimBorder' must be off in order to use 'BorderSize', or is there something bigger I'm missing? I guess the gist of my confusion is: when would I want 'TrimBorder' set to false?

Examples:

% Non-overlapping
A = ones(10);
B = blockproc(A, [2,2], @(x)sum(sum(x.data)));
% B = 
% [ 4 4 4 4 4 ]
% [ 4 4 4 4 4 ]
% [ 4 4 4 4 4 ]
% [ 4 4 4 4 4 ]
% [ 4 4 4 4 4 ]

% GOOD Overlapping--one-pixel border
B = blockproc(A, [2,2], @(x)sum(sum(x.data)), 'BorderSize', [1,1], 'TrimBorder', false);
% B =
% [ 9  12 12 12 9  ]
% [ 12 16 16 16 12 ]
% [ 12 16 16 16 12 ]
% [ 12 16 16 16 12 ]
% [ 9  12 12 12 9  ]

% BAD Overlapping--one-pixel border
B = blockproc(A, [2,2], @(x)sum(sum(x.data)), 'BorderSize', [1,1]);
% B = []

Answer 1

Why would I want to include a 'BorderSize' (i.e. overlap tiles) but not apply it to the output?

Consider all the workflows where you want to apply a function fun on each block of size MxN in an image, but for the result to be valid you actually need the border pixels around the MxN block. (filtering, morphology, any function where a single output pixel value depends on a mxn surrounding neighborhood). i.e you need (M+m, N+n) block of input to compute one MxN output block.

Simple (aka madeup) example:

h = fspecial('gaussian', 3);
im = imread('peppers.png');
B1 = blockproc(im, [20 20], @(bs)imfilter(bs.data,h));
imshowpair(im, B1,'montage');

Notice the grid lines? In this particular case, you would just call imfilter on the full image. But blockproc lets you work with images which are larger than your physical memory. So for this discussion, imagine im is a huge tiff file.

For this workflow - if you just used BorderSize to include the 3 pixels border around each 20x20 block and did not trim the output border:

h = fspecial('gaussian');
im = imread('peppers.png');
B1 = blockproc(im, [20 20], @(bs)imfilter(bs.data,h), 'BorderSize', [3 3], 'TrimBorder', false);
imshowpair(im, B1,'montage');

So - you really need to trim the border (the default)

h = fspecial('gaussian');
im = imread('peppers.png');
B1 = blockproc(im, [20 20], @(bs)imfilter(bs.data,h), 'BorderSize', [3 3], 'TrimBorder', true);
imshowpair(im, B1,'montage');

Note - I used IMFILTER as an example. For small images, one would use IMFITLER directly. Only for images that are large would one consider using IMFITLER in BLOCPROC.