apply
Syntax
Description
[
processes the array of blocked images bimArrayProc
1,bimArrayProc
2,...] = apply(bimArray
,fcn
)bimArray
by applying the function
handle fcn
to each block of each blocked image. The function returns
one or more arrays of blocked images containing the processed data. The specified function
handle, fcn
, must point to a user function that returns the same number
of output arguments.
[___] = apply(___,
modifies aspects of the block processing using name-value arguments.Name,Value
)
Examples
Enhance Image Details to Better Visualize Region Boundaries
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])
Improve Efficiency By Using Mask to Limit Processed Region
Create a blocked image.
bim = blockedImage("tumor_091R.tif");
Create a mask at the coarsest level and display it.
bmask = apply(bim, @(bs)im2gray(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]);
Process Array of Blocked Images
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
bim
— Blocked image
blockedImage
object
Blocked image, specified as a blockedImage
object.
bimArray
— Blocked images
array of blockedImage
objects
Blocked images, specified as an array of blockedImage
objects.
fcn
— Processing function
function handle
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:
Field | Description |
---|---|
Data | Block of data from bim |
Start | Subscripts of the first element in the block. If
BorderSize is specified, this subscript can be
out-of-bounds for edge blocks. |
End | Subscripts of the last element in the block. If
BorderSize is specified, this subscript can be
out-of-bounds for edge blocks. |
Blocksub | Block subscripts of the current block |
BorderSize | Value of the BorderSize argument. |
BlockSize | Value of the BlockSize argument. Note:
size(data) can be less than this value for border blocks
when PadPartialValue is false. |
BatchSize | Value of the BatchSize parameter |
ImageNumber | Index into bim array for the current image. |
Level | The 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 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.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: "Level",3
Adapter
— Adapter used for writing blocked image data
adapter object
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 that support writing.
Adapter | Description |
---|---|
BINBlocks | Store each block as a binary file in a folder |
GenericImage
| Store blocks in a single image |
GenericImageBlocks | Store each block as an image file in a folder |
H5 | Store blocks in a single HDF5 image |
H5Blocks | Store each block as an HDF5 file in a folder |
InMemory | Store blocks in a variable in main memory |
JPEGBlocks | Store each block as a JPEG file in a folder |
MATBlocks | Store each block as a MAT file in a folder |
PNGBlocks | Store each block as a PNG file in a folder |
TIFF | Store 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
.
BatchSize
— Batch size
1
(default) | numeric scalar
Batch size, specified as a numeric scalar. BatchSize
is the
last dimension of input to fcn
. All outputs of
fcn
must have the last dimension be the same as
BatchSize
.
The batch size is the maximum number of blocks supplied to the processing function
fcn
in each batch. On the first call to
fcn
, the apply
function sends only one
block. On subsequent calls, the apply
function sends
BatchSize
blocks. On the last call to fcn
,
the apply
function sends all remaining blocks, which can be fewer
than BatchSize
.
Set BatchSize
greater than 1 to optimally load GPUs when
applying deep learning inference calls. When BatchSize
is greater
than 1, PadPartialBlocks
must be true
.
BlockLocationSet
— Set of blocks to process
all non-overlapping BlockSize
-sized
blocks (default) | blockLocationSet
object
Set of blocks to process, specified as a blockLocationSet
object. The ImageNumber
property of
the blockLocationSet
object indexes into the
bimArray
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.
BlockSize
— Block size
value of BlockSize
property of blocked
image (default) | integer-valued vector
BorderSize
— Border size
0
(default) | integer-valued vector
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
function uses the PadMethod
argument. If BorderSize
contains fewer elements, the
apply
function pads the border with 0s.
DisplayWaitbar
— Display wait bar
true
(default) | false
Display wait bar, specified as a logical scalar. When set to
true
, the apply
function displays a wait bar
for long-running operations. If you cancel the wait bar, the
apply
function returns partial output, if available.
Data Types: logical
ExtraImages
— Additional inputs to fcn
array of blockedImage
objects
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
function extracts these blocks from the same world region as the main block from
bim
, represented in bstruct
.
ExtraLevels
— Resolution level
vector of integers
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
.
Level
— Resolution level to use
1
(default) | integer scalar
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.
OutputLocation
— Location of output folder
string scalar | character vector
Location of output folder, specified as a string scalar or character vector. If
there is a single output, the apply
function writes it directly
to this location. For multiple outputs, the apply
function
creates subfolders of the format output<N>/
for the
Nth output. If the input is an array, the
apply
function derives the output name from the
Source
property of the corresponding element. If the input is
in-memory, the apply
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.
PadMethod
— Method used for padding incomplete blocks
"replicate"
(default) | "symmetric"
| numeric scalar | logical scalar | categorical scalar
Method used for padding incomplete blocks, specified as one of the values in the
table. The pad method specifies how to obtain padding pixels to honor the
BorderSize
or the PadPartialBlocks
arguments.
Value | Meaning |
---|---|
numeric, logical, or categorical scalar | Pad array with elements of the specified value. The data type of
|
| Pad by repeating border elements of the block. |
"symmetric" | Pad with mirror reflections of pixels from within the same block. |
PadPartialBlocks
— Pad partial blocks
false
(default) | true
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 BatchSize
is greater than 1, set
PadPartialBlocks
to true
Data Types: logical
Resume
— Continue processing from where previous run stopped
false
(default) | true
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
function deletes the previous content.
UseParallel
— Use parallel processing
false
(default) | true
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
bimProc
— Processed blocked image
blockedImage
object
New blocked image, returned as a blockedImage
object.
bimArrayProc
— Processed blocked images
array of blockedImage
objects
Processed blocked images, returned as an array of blockedImage
objects.
Tips
The
apply
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
function sets theInitialValue
property of the output based on the type of the output:Numeric or logical outputs –
InitialValue
is set to0
.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.
Version History
Introduced in R2021aR2023a: Support for symmetric padding
You can now specify the PadMethod
argument as
"symmetric"
. Symmetric padding consists of mirror reflections of pixels
from within the same block.
See Also
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)