apply

Process blocks of big image

Description

example

newbig = apply(bigimg,level,fun) processes all blocks of the big image bigimg at the specified resolution level using the function fun and returns a new big image newbig containing the processed data.

newbig = apply(bigimg,level,fun,extraImages) processes all blocks of big image bigimg and one or more extra big images extraImages. Use this syntax when the function fun accepts multiple image inputs, such as an image and a mask.

newbig = apply(___,Name,Value) controls aspects of the processing, such as processing data in parallel or padding blocks on the edge of the image, using name-value pair arguments.

[newbig,other1,other2,...] = apply(___) returns multiple outputs. Use this syntax when the function fun returns multiple outputs, including image and non-image output.

Examples

collapse all

Create a 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 bigimage:

  • Convert the block to the L*a*b* color space.

  • Filter the block using imnlmfilt.

  • Convert the block back to the RGB color space.

The apply function recombines the output blocks to form a new bigimage.

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])

Input Arguments

collapse all

Big image, specified as a bigimage object.

Resolution level, specified as a positive integer that is less than or equal to the number of resolution levels of bigimg.

Function handle, specified as a handle. For more information, see Create Function Handle (MATLAB).

Function Inputs

The function fun must accept at least one block as input.

Optionally, the function can accept additional inputs that are not blocks. To perform processing with non-block inputs, you must call the apply 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 apply.

Input TypeFunction SignatureExample of Calling apply
Single block
function outblock = myfun(inblock)
  ...
end
newbig = apply(bigimg,level,@myfun);
Two blocks
function outblock = myfun(inblock1,inblock2)
  ...
end

Specify the second bigimage after the handle to the function myfun.

newbig = apply(bigimg,level,@myfun,otherbig);

One block and one non-block
function outblock = myfun(inblock,nonblock)
  ...
end

This example passes a scalar value 37 to the function myfun:

c = 37;
mynewbig = apply(mybigimg,level,@(x) myfun(x,c));

Function Outputs

The function fun typically returns one or more image blocks of the same size as the input block. In this case, apply recombines 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 fun.

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 apply.

Output TypeSample Processing FunctionExample of Calling apply
Block of the same size as the input block
function sameSizedBlock = myfun(inblock)
  sameSizedBlock = imgaussfilt(inblock);
end
bigimageOutput = apply(bigimg,level,@myfun);

bigimageOutput is a single-resolution bigimage. In this example, bigimageOutput has the same number of channels and data type as the input bigimg.

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);

bigimageOutput1 is a single-resolution bigimage. In this example, if bigimgRGB contains a color image, then bigimageOutput1 has a different number of channels than the input bigimgRGB.

bigimageOutput2 is a single-resolution bigimage that has a different number of channels and a different data type than bigimgRGB.

Non-image
function nonimageOutput = myfun(inblock)
  nonimageOutput = mean(inblock(:))
end

cellArrayOutput = apply(bigimg,level,@myfun);

cellArrayOutput is a cell array whose elements are the non-image output of each block. cellArrayOutput has one additional column that specifies the (x,y) origin of each block as a 1-by-2 vector.

Struct
function structOutput = myfun(inblock)
  structOutput.num = numel(inblock);
  structOutput.mean = mean(inblock(:));
  structOutput.max = max(inblock(:));
end

tableOutput = apply(mybigimg,level,@myfun);
tableOutput is a table with four variables: num, mean, max, and BlockOrigin. The BlockOrigin variable specifies the (x,y) origin of each block as a 1-by-2 vector.

Multiple outputs
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);

c1 is a cell array because the first output of myfun is a non-image. b2 and b3 are bigimages because the second and third outputs of myfun are image blocks of the same size as the input block. t4 is a table because the fourth output of myfun is a struct.

The apply function ignores the fifth output argument of myfcn because only four output arguments are specified in the call to apply.

Additional input big images, specified as a vector of bigimage objects. Each big image must have the same spatial extents as bigimg, but the blocks do not need to have the same size. The big images may have different values of the ClassUnderlying and Channels properties.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is 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 Name1,Value1,...,NameN,ValueN.

Example: newbig = apply(bigimg,level,@myfun,'UseParallel',true);

Use parallel processing, specified as the comma-separated pair consisting of 'UseParallel' and false or true. Parallel processing requires Parallel Computing Toolbox™.

When you specify UseParallel as true, then 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, then specify OutputFolder.

Data Types: logical

Location to save output bigimages, specified as the comma-separated pair consisting of 'OutputFolder' and false or true. Parallel processing requires Parallel Computing Toolbox.

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 'BlockSize', then apply passes blocks of size [numrows numcols] to the processing function, fun. apply passes all channels of the block to fun.

Border size, specified as the comma-separated pair consisting of 'BorderSize' and a 1-by-2 vector of nonnegative integers of the form [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 blocks.

Pad method, specified as the comma-separated pair consisting of 'PadMethod' and one of these values.

Value

Meaning

numeric scalar

Pad array with elements of constant value.

'replicate'

Pad by repeating border elements of array.

'symmetric'

Pad array with mirror reflections of itself.

Mask, specified as the comma-separated pair consisting of 'Mask' and a bigimage object of the same size as bigimg and with a ClassUnderlying property value of logical.

The 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 fun, and 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.

Inclusion threshold for mask blocks, specified as the comma-separated pair consisting of '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 0, then apply processes a block when at least one pixel in the corresponding mask block is nonzero.

  • When the inclusion threshold is 1, then apply only processes a block when all pixels in the mask block are nonzero.

Display wait bar, specified as the comma-separated pair consisting of 'DisplayWaitbar' and true or false. When true, the apply function displays a wait bar for long running operations. If you close the wait bar, then apply returns a partial output, if available.

Data Types: logical

Output Arguments

collapse all

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 bigimg at the specified resolution level. However, newbig can have a different number of channels and a different underlying class.

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.

Value

Occurrence

bigimage object

apply returns a bigimage when the corresponding output argument of fcn returns data as a numeric or logical array of the same size as the input block, or the padded size of the input block when you specify the BorderSize argument.

The returned bigimage has a single resolution level, but it can have a different number of channels and underlying class.

table

apply returns a table when the corresponding output argument of fcn returns data as a struct. The table has an additional BlockOrigin variable that specifies the (x,y) origin of each block as a 1-by-2 vector in world coordinates.

cell array

apply returns a cell array when the corresponding output argument of fcn returns data as a non-image. The cell array has an additional column that specifies the (x,y) origin of each block as a 1-by-2 vector in world coordinates.

Algorithms

apply passes data to the processing function, fun, one block at a time in the most efficient order to traverse the data (often row-major block order). 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.

Introduced in R2019b