apply

Process blocks of big image

collapse all in page

Syntax

newbig = apply(bigimg,level,fun)
newbig = apply(bigimg,level,fun,extraImages)
newbig = apply(___,Name,Value)
[newbig,other1,other2,...] = apply(___)

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

Open Live Script

Create a 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 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 original image on the left side of a figure window using the bigimageshow function.

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

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.

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.

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

Number of blocks supplied to the processing function fun in each batch, specified as the comma-separated pair consisting of 'BatchSize' and a positive integer. When BatchSize is greater than 1, PadPartialBlocks must be true.

When BatchSize is greater than 1, apply supplies blocks as a numrows-by-numcols-by-channels-by-BatchSize array. For apply to return a bigimage, fun must return an array of the same size. For apply to return a cell array or table, fun must return a cell array of length BatchSize with one element for each block.

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.

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

Include block information, specified as the comma-separated pair consisting of 'IncludeBlockInfo' and false or true. When true, apply 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.

FieldDescription
BlockStartWorld World coordinates of the center of the top-left pixel of the block, excluding any border or padding.
BlockEndWorldWorld coordinates of the center of the bottom-right pixel of the block, excluding any border or padding.
DataStartWorldWorld coordinates of the center of the top-left pixel of the block, including any border or padding.
DataEndWorldWorld coordinates of the center of the bottom-right pixel of the block, including any border or padding.

If BatchSize is greater than 1, then the values in the struct are arrays of length BatchSize.

Data Types: logical

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.

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.

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

Pad method of incomplete edge blocks, specified as the comma-separated pair consisting of 'PadMethod' and one of these values. By default, apply pads numeric blocks with 0 and categorical blocks with missing.

Value

Meaning

numeric scalar

Pad numeric array with elements of constant value.

string scalar

Pad categorical array with the specified class in the Classes property of the bigimage.

'replicate'

Pad by repeating border elements of array.

'symmetric'

Pad array with mirror reflections of itself.

Pad partial blocks, specified as the comma-separated pair consisting of 'PadPartialBlocks' and false or true. Partial blocks arise when the image size is not exactly divisible by BlockSize. If they exist, partial blocks lie along the right and bottom edge of the image.

  • When false, the processing function fun operates on partial blocks without padding and can return blocks smaller than BlockSize.

  • When true, the apply function pads partial blocks using the specified PadMethod. The processing function fun operates on and returns full-sized blocks.

Set PadPartialBlocks to true when BatchSize is greater than 1.

Data Types: logical

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

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

Tips

  • Setting BatchSize as greater than 1 is useful to optimally load GPUs when running inference deep learning networks inside the processing function fun.

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.

See Also

| |

Topics

Introduced in R2019b

Image Processing Toolbox Documentation

Support