Main Content

apply

Process blocks of blocked image

Description

example

bres = apply(bim,fcn) processes the entire blocked image bim by applying the function handle fcn to each block. Returns bres, a new blocked image containing the processed data.

[bres1,bres2,...] = apply(bim,fcn) returns multiple output arguments. The specified function handle, fcn, must point to a user function which returns the same number of arguments.

[bres1s,bres2s,...] = apply(bims,fcn) processes the array of blocked images bims by applying the function handle fcn to each block of each blocked image. Returns an array of blocked images containing the processed data.

[___] = apply(___,Name,Value) modifies aspects of the block processing using name-value arguments.

Examples

collapse all

Create blocked image.

bim = blockedImage("tumor_091R.tif");

Create a smoothing filter and apply it to the blocks in the blocked image.

smoothing = 2000;

imguidedfilter operates on a default neighborhood of 5 pixels. Add a border to the input to read additional data. This border pixels automatically get trimmed from the output since its the same size as the input.

benh= apply(bim,...
    @(bs)imguidedfilter(bs.Data,bs.Data,"DegreeOfSmoothing", smoothing),...
    "BorderSize", [5 5]);

Display the original image and the enhanced image.

ha1 = subplot(1,2,1);
bigimageshow(bim,"ResolutionLevel",1);
ha2 = subplot(1,2,2);
bigimageshow(benh);
linkaxes([ha1, ha2]);
xlim([2100, 2600])
ylim([1800 2300])

Create a blocked image.

bim = blockedImage("tumor_091R.tif");

Create a mask at the coarsest level and display it.

bmask = apply(bim, @(bs)rgb2gray(bs.Data)<80, "Level",3);
figure
bigimageshow(bmask)

Use the mask to limit regions processed by the call to the apply object function.

bls = selectBlockLocations(bim, "Mask", bmask,"InclusionThreshold", 0.005);
benh = apply(bim, @(bs)imguidedfilter(bs.Data,bs.Data,"DegreeOfSmoothing", 2000),...
    "BorderSize", [5 5],...
    "BlockLocationSet", bls); 

Display the original image and the enhanced image.

figure
ha1 = subplot(1,2,1);
bigimageshow(bim,"ResolutionLevel",1);
ha2 = subplot(1,2,2);
bigimageshow(benh);
linkaxes([ha1, ha2]);      

Create a file set of all the JPEG images in the toolbox sample images folder.

fs = matlab.io.datastore.FileSet( ...
    fullfile(matlabroot,"toolbox","images","imdata"), ...
    "FileExtensions",".jpg");

Create an array of blocked images from the file set.

bims = blockedImage(fs);

Create an adapter that saves a blocked image to disk as a single image file.

outputFolder = tempname;
outputAdapter = images.blocked.GenericImage;
outputAdapter.Extension = "jpg";

Convert the images to binary images on disk.

bos = apply(bims, @(b)imbinarize(im2gray(b.Data)), ...
    "OutputLocation",outputFolder,"Adapter",outputAdapter);

View the contents of the output folder using the Image Browser app by running this command: imageBrowser(outputFolder)

Input Arguments

collapse all

Blocked image, specified as a blockedImage object.

Blocked images, specified as an array of blockedImage objects.

Processing function, specified as a function handle. For more information, see Create Function Handle.The processing function fcn must accept a bstruct as input. To pass additional arguments, specify fcn as an anonymous function. For more information, see Anonymous Functions.

bstruct is a struct with these fields:

FieldDescription
DataBlock of data from bim
StartSubscripts of the first element in the block. If BorderSize is specified, this subscript can be out-of-bounds for edge blocks.
EndSubscripts of the last element in the block. If BorderSize is specified, this subscript can be out-of-bounds for edge blocks.
BlocksubBlock subscripts of the current block
BorderSizeValue of the BorderSize parameter.
BlockSizeValue of the BlockSize parameter. Note: size(data) can be less than this value for border blocks when PadPartialValue is false.
BatchSizeValue of the BatchSize parameter
ImageNumberIndex into bim array for the current image.
LevelThe resolution level from which the data is being read.

The function fcn typically returns the results for one block. The results can be numeric, a struct, or categorical.

Name-Value 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: "Level",3

Adapter used for writing blocked image data, specified as an adapter object. To specify different adapters for different outputs, use a cell array. Scalar values are expanded.

This table lists the adapters included with the toolbox.

AdapterDescription
BINBlocksStore each block as a binary file in a folder
GenericImage Store blocks in a single image
GenericImageBlocksStore each block as an image file in a folder
H5Store blocks in a single HDF5 image
H5BlocksStore each block as an HDF5 file in a folder
InMemoryStore blocks in a variable in main memory
JPEGBlocksStore each block as a JPEG file in a folder
MATBlocksStore each block as a MAT file in a folder
PNGBlocksStore each block as a PNG file in a folder
TIFFStore blocks in a single TIFF file

You can also specify a custom adapter that performs custom writing operations. For more information, see images.blocked.Adapter.

Number of blocks supplied to the processing function fcn in each batch, specified as a numeric scalar. The BatchSize is the last dimension of input to fcn. All outputs of fcn must have the last dimension be the same as BatchSize. BatchSize greater than 1 is useful to optimally load GPUs when applying deep learning inference calls. When BatchSize is greater than 1, PadPartialBlocks must be true.

Set of blocks to process, specified as a blockLocationSet object. The ImageNumber property indexes into bims array. Specifying the blocks to process can improve efficiency by limiting the number of blocks processed. For example, use selectBlockLocations with a mask to limit applying the processing function to certain regions. Blocks contained must be on a regular grid.

Block size, specified as an integer-valued vector of length equal to the NumDimensions property of bim. Specifies the size of a block supplied as the input to fcn. If BlockSize contains fewer elements, the apply object function pads the missing dimensions with elements from the Size property.

Border size, specified as an integer-valued vector of length equal to the NumDimensions property of bim. Specifies additional data from neighboring region to be included in a block. For edge blocks, the apply object function uses 'PadMethod'. If BorderSize contains fewer elements, the apply object function pads the border with 0s.

Display wait bar, specified as a logical scalar. When set to true,the apply object function displays a wait bar for long-running operations. If you cancel the wait bar, the apply object function returns partial output, if available.

Data Types: logical

Additional inputs to fcn, specified as an array of blockedImage objects. Blocks from this array are provided to fcn as additional inputs after bstruct: __ = fcn(bstruct, extrablock1,...). The apply object function extracts these blocks from the same world region as the main block from bim, represented in bstruct.

Resolution level, specified as a vector of integers of the same length as 'ExtraImages'. Each value specifies the resolution level to use from the corresponding blockedImage object in ExtraImages.

Resolution level to use, specified as an integer scalar. For a multiresolution blockedImage object, this value determines the resolution level to use to obtain blocks for processing.

Location of output folder, specified as a string scalar or char vector. If there is a single output, the apply object function writes it directly to this location. For multiple outputs, the apply object function creates subfolders of the format output<N>/ for the N'th output. If the input is an array, the apply object function derives the output name from the Source property of the corresponding element. If the input is in-memory, the apply object function uses a numeric index. When the UseParallel property is true, OutputLocation should be a valid path on the client session. Use the AlternateFileSystemRoots property of the input to specify the required mapping for worker sessions. All outputs inherit this value.

Pad method of incomplete edge blocks, specified as one of these values. The method specifies how to obtain padding pixels to honor 'BorderSize' or the 'PadPartialBlocks' parameters.

Value

Meaning

numeric scalar

Pad numeric array with elements of a constant value of type specified by the ClassUnderlying property of the blocked image.

'replicate'

Pad by repeating border elements of array.

Pad partial blocks, specified as logical scalar. Specifies if partial blocks that may exist on the edges need to be padded out to the specified block size. The apply object function uses the method specified in PadMethod to perform the padding operation.

  • When false, the processing function fcn 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 fcn operates on and returns full-sized blocks.

When BatchSize is greater than 1, set PadPartialBlocks to true

Data Types: logical

Continue processing from where the previous run stopped, specified as a logical scalar. If true, and the specified 'OutputLocation' has content from a previous run, the current run will continue processing from where the previous run stopped. This support depends on the output adapter used. If false, the apply object function deletes the previous content.

Use parallel processing, specified as a logical scalar. Determines if a new or existing parallel pool should be used. If no parallel pool is active, a new pool is opened based on the default parallel settings. All adapters specified by the Adapter property must support parallel processing. You must specify a valid OutputLocation. This argument requires Parallel Computing Toolbox™.

Data Types: logical

Output Arguments

collapse all

New blocked image, returned as a blockedImage object.

Tips

  • The apply object function determines the output size by processing the first block. If processing the first block yields an output block of the same size as the input, then the final output size is set to match the input. Otherwise, the last block is processed to determine the final output size. The first block must not be a partial block.

  • The apply object function sets the InitialValue property of the output based on the type of the output:

    • Numeric or logical outputs – InitialValue is set to 0.

    • Categorical outputs – InitialValue is set to the <undefined> value of the corresponding type.

    • struct outputs – InitialValue is derived from the first block's output. All fields are set to empty.

Introduced in R2021a