apply

(To be removed) Process blocks of bigimage object

The apply function of the bigimage object will be removed in a future release. Use the apply function associated with the blockedImage object instead. For more information, see Version History.

Syntax

newbig = apply(bigimg,level,fun)

newbig = apply(bigimg,level,fun,extraImages)

newbig = apply(___,Name,Value)

[newbig,other1,other2,...] = apply(___)

Description

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.

example

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

Apply Filter to Big Image

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

`bigimg` — Big image
`bigimage` object

Big image, specified as a bigimage object.

`level` — Resolution level
positive integer

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

`fun` — Function handle
handle

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 Type Function Signature Example of Calling apply

Single block

Input Type	Function Signature	Example 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 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 Type	Sample Processing Function	Example 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 `bigimage`s 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`.

`extraImages` — Additional input big images
vector of `bigimage` objects

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 Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is 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.

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

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

`BatchSize` — Number of blocks supplied to `fun`
`1` (default) | positive integer

Number of blocks supplied to the processing function fun in each batch, specified as 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.

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

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

`DisplayWaitbar` — Display wait bar
`true` (default) | `false`

Display wait bar, specified as 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

`IncludeBlockInfo` — Include block information
`false` (default) | `true`

Include block information, specified as 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.

Field	Description
`BlockStartWorld`	World coordinates of the center of the top-left pixel of the block, excluding any border or padding.
`BlockEndWorld`	World coordinates of the center of the bottom-right pixel of the block, excluding any border or padding.
`DataStartWorld`	World coordinates of the center of the top-left pixel of the block, including any border or padding.
`DataEndWorld`	World 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

`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 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` — Mask
`[]` (default) | single-resolution `bigimage` object

Mask, specified as 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.

`OutputFolder` — Location to save output `bigimage`s
character vector

Location to save output bigimages, specified as false or true. Parallel processing requires Parallel Computing Toolbox™.

`PadMethod` — Pad method
numeric scalar | string scalar | `'replicate'` | `'symmetric'`

Pad method of incomplete edge blocks, specified as 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.

`PadPartialBlocks` — Pad partial blocks
`false` (default) | `true`

Pad partial blocks, specified as 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

`UseParallel` — Use parallel processing
`false` (default) | `true`

Use parallel processing, specified as 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

`newbig` — Processed big image
`bigimage` object

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.

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

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.

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.

Version History

Introduced in R2019b

expand all

R2024b: Warns

The apply function issues a warning that it will be removed in a future release.

R2023b: To be removed

The bigimage object and this function will be removed in a future release. Use the apply function of the blockedImage object instead.

To update your code, first create a blockedImage object to read your image data. Then, in the call to the apply function:

Replace the first input argument with the blockedImage object.
Delete the second input argument. By default, the blockedImage apply function applies the operations in fun at 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 Level name-value argument.
Update the function handle fun. The blockedImage apply function always passes a structure to fun, and you can access the image data through the Data field.

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

Discouraged Usage	Recommended Replacement
This example uses the `apply` function with a `bigimage` object to convert a color image to grayscale. filename = "tumor_091R.tif"; bim = bigimage(filename); bim_enhanced = apply(bim,1,@(block)im2gray(block));	Here is equivalent code using a `blockedImage` object. Access the image data of `block` using the `Data` field: `block.Data`. 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 `blockedImage` object, and specifying the second resolution level using the `Level` name-value argument. bim_enhanced2 = apply(bim,@(block)im2gray(block.Data),Level=2);

This example uses the apply function with a bigimage object to convert a color image to grayscale.

filename = "tumor_091R.tif";
bim = bigimage(filename);
bim_enhanced = apply(bim,1,@(block)im2gray(block));

Here is equivalent code using a blockedImage object. Access the image data of block using the Data field: block.Data.

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 blockedImage object, and specifying the second resolution level using the Level name-value argument.

bim_enhanced2 = apply(bim,@(block)im2gray(block.Data),Level=2);

R2021a: `apply` function is not recommended

The apply function of the bigimage object is not recommended. Use the apply function of the blockedImage object instead. The blockedImage object offers several advantages including extension to N-D processing, a simpler interface, and custom support for reading and writing nonstandard image formats.

apply

Syntax

Description

Examples

Apply Filter to Big Image

Input Arguments

bigimg — Big image bigimage object

level — Resolution level positive integer

fun — Function handle handle

Function Inputs

Function Outputs

extraImages — Additional input big images vector of bigimage objects

Name-Value Arguments

BatchSize — Number of blocks supplied to fun 1 (default) | positive integer

BlockSize — Block size 1-by-2 vector of positive integers

BorderSize — Border size [0 0] (default) | 1-by-2 vector of nonnegative integers

DisplayWaitbar — Display wait bar true (default) | false

IncludeBlockInfo — Include block information false (default) | true

InclusionThreshold — Inclusion threshold 0.5 (default) | number in the range [0, 1]

Mask — Mask [] (default) | single-resolution bigimage object

OutputFolder — Location to save output bigimages character vector

PadMethod — Pad method numeric scalar | string scalar | 'replicate' | 'symmetric'

PadPartialBlocks — Pad partial blocks false (default) | true

UseParallel — Use parallel processing false (default) | true

Output Arguments

newbig — Processed big image bigimage object

other — Additional output bigimage object | table | cell array

Tips

Algorithms

Version History

R2024b: Warns

R2023b: To be removed

R2021a: apply function is not recommended

See Also

`bigimg` — Big image
`bigimage` object

`level` — Resolution level
positive integer

`fun` — Function handle
handle

`extraImages` — Additional input big images
vector of `bigimage` objects

`BatchSize` — Number of blocks supplied to `fun`
`1` (default) | positive integer

`BlockSize` — Block size
1-by-2 vector of positive integers

`BorderSize` — Border size
`[0 0]` (default) | 1-by-2 vector of nonnegative integers

`DisplayWaitbar` — Display wait bar
`true` (default) | `false`

`IncludeBlockInfo` — Include block information
`false` (default) | `true`

`InclusionThreshold` — Inclusion threshold
`0.5` (default) | number in the range [0, 1]

`Mask` — Mask
`[]` (default) | single-resolution `bigimage` object

`OutputFolder` — Location to save output `bigimage`s
character vector

`PadMethod` — Pad method
numeric scalar | string scalar | `'replicate'` | `'symmetric'`

`PadPartialBlocks` — Pad partial blocks
`false` (default) | `true`

`UseParallel` — Use parallel processing
`false` (default) | `true`

`newbig` — Processed big image
`bigimage` object

`other` — Additional output
`bigimage` object | table | cell array

R2021a: `apply` function is not recommended