(To be removed) Process blocks of
apply function of the
bigimage object will be
removed in a future release. Use the
associated with the
instead. For more information, see Compatibility Considerations.
Apply Filter to Big Image
bigimage using 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');
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 original image on the left side of a figure window using the
figure ha1 = subplot(1,2,1); bigimageshow(bim,'ResolutionLevel',1); title("Original Image")
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.
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.
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 syntaxes 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
Specify optional pairs of arguments as
the argument name and
Value is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name in quotes.
BatchSize — Number of blocks supplied to
1 (default) | positive integer
BatchSize is greater than 1,
supplies blocks as a
apply to return a
fun must return an array of the same size. For
apply to return a cell array or table,
must return a cell array of length
BatchSize with one element for
BlockSize — Block size
1-by-2 vector of positive integers
Block size, specified as 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 a 1-by-2 vector of nonnegative integers of the form
[numrows numcols]. The function adds
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
default, no border is added to blocks.
DisplayWaitbar — Display wait bar
true (default) |
Display wait bar, specified as
function displays a wait bar for long running operations. If you close the wait bar,
apply returns a partial output, if available.
IncludeBlockInfo — Include block information
false (default) |
Include block information, specified as
includes a struct as the last input to the processing function,
fun. The struct has these fields that describe spatial
referencing information about the block.
|World coordinates of the center of the top-left pixel of the block, excluding any border or padding.|
|World coordinates of the center of the bottom-right pixel of the block, excluding any border or padding.|
|World coordinates of the center of the top-left pixel of the block, including any border or padding.|
|World coordinates of the center of the bottom-right pixel of the block, including any border or padding.|
BatchSize is greater than 1, then the values
in the struct are arrays of length
InclusionThreshold — Inclusion threshold
0.5 (default) | number in the range [0, 1]
Inclusion threshold for mask blocks, specified as 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
applyprocesses a block when at least one pixel in the corresponding mask block is nonzero.
When the inclusion threshold is
applyonly processes a block when all pixels in the mask block are nonzero.
Mask — Mask
 (default) | single-resolution
apply function only processes blocks that overlap with
nonzero blocks of the mask. If you also specify
InclusionThreshold, 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
apply sends the entire image block to
the processing function
processes all pixels within the block.
fun cannot access the mask
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.
OutputFolder — Location to save output
Location to save output
bigimages, specified as
true. Parallel processing requires
Parallel Computing Toolbox™.
PadMethod — Pad method
numeric scalar | string scalar |
Pad method of incomplete edge blocks, specified as one of these values. By
apply pads numeric blocks with
categorical blocks with
Pad numeric array with elements of constant value.
Pad categorical array with the specified class in the Classes
property of the
Pad by repeating border elements of array.
Pad array with mirror reflections of itself.
PadPartialBlocks — Pad partial blocks
false (default) |
Pad partial blocks, specified as
true. Partial blocks arise when the image size is not exactly
BlockSize. If they exist, partial blocks lie along
the right and bottom edge of the image.
BatchSize is greater than 1.
UseParallel — Use parallel processing
false (default) |
Use parallel processing, specified as
true. Parallel processing requires Parallel Computing Toolbox.
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,
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
bigimage object | 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.
Version HistoryIntroduced in R2019b
apply will be removed
To update your code, first create a
blockedImage object to read your
image data. Then, in the call to the
Replace the first input argument with the
Delete the second input argument. By default, the
applyfunction applies the operations in
funat the finest resolution level. If you want to perform the operations at a resolution level other than level 1, then specify that level by adding a
Update the function handle
applyfunction always passes a structure to
fun, and you can access the image data through the
apply function of
blockedImage object supports
some different name-value arguments than the
apply function of
bigimage. For example, if you want to specify a mask, first select the
blocks using the
selectBlockLocations function, and then specify those blocks using the
BlockLocationSet name-value argument instead of the
Mask name-value argument.
|Discouraged Usage||Recommended Replacement|
This example uses the
filename = "tumor_091R.tif"; bim = bigimage(filename); bim_enhanced = apply(bim,1,@(block)im2gray(block));
Here is equivalent code using a
filename = "tumor_091R.tif"; bim = blockedImage(filename); bim_enhanced = apply(bim,@(block)im2gray(block.Data));
This example performs the same operation at the second resolution level.
bim_enhanced2 = apply(bim,2,@(block)im2gray(block));
Here is equivalent code using a
bim_enhanced2 = apply(bim,@(block)im2gray(block.Data),Level=2);