Process blocks of big image
bigimage. This examples uses a modified version of image "tumor_091.tif" from the CAMELYON16 data set. The original image is a training image of a lymph node containing tumor tissue. The original image has eight resolution levels, and the finest level has resolution 53760-by-61440. The modified image has only three coarse resolution levels. The spatial referencing of the modified image has been adjusted to enforce a consistent aspect ratio and to register features at each level.
bim = bigimage('tumor_091R.tif');
Display the big image by using the
bigimageshow function. Display the finest resolution level on the left side of a figure window.
figure ha1 = subplot(1,2,1); bigimageshow(bim,'ResolutionLevel',1); title("Original Image")
Enhance structures in the image by applying an edge-preserving non-local means filter to each block at the finest resolution level, 1. For this example, the
apply function performs these operations on each block of the input
Convert the block to the L*a*b* color space.
Filter the block using
Convert the block back to the RGB color space.
apply function recombines the output blocks to form a new
bim_enhanced = apply(bim,1, ... @(block)lab2rgb(imnlmfilt(rgb2lab(block),'DegreeOfSmoothing',15)));
Display the enhanced image on the right side of the figure window.
ha2 = subplot(1,2,2); bigimageshow(bim_enhanced); title("Enhanced Image")
Ensure that both displays show the same extents, then zoom in on a feature.
linkaxes([ha1,ha2]); xlim([1600,2300]) ylim([1900,2600])
fun— Function handle
Function handle, specified as a handle. For more information, see Create Function Handle (MATLAB).
fun must accept at least one block as
Optionally, the function can accept additional inputs that are not blocks. To
perform processing with non-block inputs, you must call the
function and specify
fun as an anonymous function. For more
information, see Anonymous Functions (MATLAB).
The table shows sample function signatures for different types of input to
fun. The table also shows sample syntax to use when calling
|Input Type||Function Signature||Example of Calling |
function outblock = myfun(inblock) ... end
newbig = apply(bigimg,level,@myfun);
function outblock = myfun(inblock1,inblock2) ... end
Specify the second
newbig = apply(bigimg,level,@myfun,otherbig);
|One block and one non-block||
function outblock = myfun(inblock,nonblock) ... end
This example passes a scalar value
c = 37; mynewbig = apply(mybigimg,level,@(x) myfun(x,c));
fun typically returns one or more image blocks
of the same size as the input block. In this case,
the blocks and returns a
bigimage. If you specify the
BorderSize argument of
apply and desire a
bigimage output, then
apply will crop the
border from the output blocks. You can also crop the block directly within
All of the examples in the above table demonstrate a function signature that
returns a single block. However, the function
fun can also return
structs or other non-image outputs.
The table shows sample function signatures for different types of output of
fun. The table also shows sample syntax to use when calling
|Output Type||Sample Processing Function||Example of Calling |
|Block of the same size as the input block||
function sameSizedBlock = myfun(inblock) sameSizedBlock = imgaussfilt(inblock); end
bigimageOutput = apply(bigimg,level,@myfun);
|Multiple blocks of the same size as the input block||
function [sameSizedBlock,maskBlock] = myfun(inblock) sameSizedBlock = rgb2lightness(inblock); maskBlock = imbinarize(sameSizedBlock); end
[bigimageOutput1,bigimageOutput2] = apply(bigimgRGB,level,@myfun);
function nonimageOutput = myfun(inblock) nonimageOutput = mean(inblock(:)) end
cellArrayOutput = apply(bigimg,level,@myfun);
function structOutput = myfun(inblock) structOutput.num = numel(inblock); structOutput.mean = mean(inblock(:)); structOutput.max = max(inblock(:)); end
tableOutput = apply(mybigimg,level,@myfun);
function [out1,out2,out3,out4,out5] = myfun(inblock) % non-image output out1 = min(inblock(:)); % image output of same size as input block out2 = imgaussfilt(out2); out3 = imbinarize(inblock); % struct output out4.originalMean = mean(inblock(:)); out4.filteredMean = mean(out2(:)); out4.fractionTrue = sum(out3(:))/numel(out3); % non-image output out5 = out4.fractionTrue; end
[c1,b2,b3,t4] = apply(mybigimg,level,@myfun);
extraImages— Additional input big images
comma-separated pairs of
the argument name and
Value is the corresponding value.
Name must appear inside quotes. You can specify several name and value
pair arguments in any order as
newbig = apply(bigimg,level,@myfun,'UseParallel',true);
'UseParallel'— Use parallel processing
Use parallel processing, specified as the comma-separated pair consisting of
true. Parallel processing requires Parallel
When you specify
MATLAB® automatically opens a parallel pool based on default parallel settings.
apply processes the
bigimage blocks across the
available workers. The
DataSource property of all input
bigimages should be valid paths on each of the parallel workers.
If relative paths are used, then ensure workers and the client process are on the same
working directory. If workers do not share the same file system as the client process,
'OutputFolder'— Location to save output
Location to save output
bigimages, specified as the
comma-separated pair consisting of
true. Parallel processing requires
'BlockSize'— Block size
Block size, specified as the comma-separated pair consisting of
'BlockSize' and a 1-by-2 vector of positive integers of the form
[numrows numcols]. If you specify
apply passes blocks of size
numcols] to the processing function,
apply passes all channels of the block to
'BorderSize'— Border size
[0 0](default) | 1-by-2 vector of nonnegative integers
Border size, specified as the comma-separated pair consisting of
'BorderSize' and a 1-by-2 vector of nonnegative integers of the
[numrows numcols]. The function adds
numrows rows above and below each block and
numcols columns to the left and right of each block with data
from the neighboring blocks. For blocks that lie on the edge of an image, data is
padded according to
PadMethod. By default, no border is added to
'PadMethod'— Pad method
0(default) | numeric scalar |
Pad method, specified as the comma-separated pair consisting of
'PadMethod' and one of these values.
Pad array with elements of constant value.
Pad by repeating border elements of array.
Pad array with mirror reflections of itself.
(default) | single-resolution
apply function only processes blocks that overlap with
nonzero blocks of the mask. If you also specify
', then the block to
process must overlap with a minimum percentage of nonzero pixels in a mask block. If
an image block sufficiently overlaps a mask block, then
the entire image block to the processing function
fun processes all pixels within the block.
fun cannot access the mask directly.
An input block can overlap multiple mask blocks when the image is coarser than the
mask or when the edge of the block does not align with the mask blocks. If an input
block overlaps multiple mask blocks, then
apply selects the mask
that overlaps with the center of the input block.
'InclusionThreshold'— Inclusion threshold
0.5(default) | number in the range [0, 1]
Inclusion threshold for mask blocks, specified as the comma-separated pair
'InclusionThreshold' and a number in the range [0,
1]. The inclusion threshold indicates the minimum fraction of nonzero pixels in a mask
block required to process the image block.
When the inclusion threshold is
apply processes a block when at least one pixel in the
corresponding mask block is nonzero.
When the inclusion threshold is
apply only processes a block when all pixels in the mask
block are nonzero.
'DisplayWaitbar'— Display wait bar
Display wait bar, specified as the comma-separated pair consisting of
function displays a wait bar for long running operations. If you close the wait bar,
apply returns a partial output, if available.
newbig— Processed big image
Processed big image, returned as a
bigimage object with a single
resolution level. The number of rows and columns of
newbig is equal
to the number of rows and columns of the input big image
the specified resolution
newbig can have a different number of channels and a different
other— Additional output
bigimageobject | table | cell array
Additional output from processing function
fun, returned as one
of the following. If
fun returns multiple output arguments, then
apply can return the same number or fewer output arguments.
apply passes data to the processing function,
one block at a time in the most efficient order to traverse the data (often row-major block
apply processes each block only once.
It is inefficient to perform many processing operations by making multiple calls to
apply because the data must be traversed multiple times. To optimize
processing time, define
fun such that it performs multiple processing
operations. This minimizes reading and writing overhead and ensures data locality. You can
further reduce processing time at a particular level by using masks created at coarser
resolution levels to exclude regions of the image from processing.