selectBlockLocations

Select blocks from blocked images

Syntax

blset = selectBlockLocations(bims)

blset = selectBlockLocations(bims,Name=Value)

Description

blset = selectBlockLocations(bims) selects a set of nonoverlapping unique blocks from one or more blocked images bims at the finest resolution available in each image. The function returns the locations of the blocks, blset.

blset = selectBlockLocations(bims,Name=Value) specifies additional options about the blocks to select, such as the overlap and spacing between blocks, using one or more name-value arguments.

Examples

Create blockedImageDatastore Using Non-overlapping Blocks

Create a blocked image.

bim = blockedImage("tumor_091R.tif");

Create a block location set excluding incomplete blocks.

 bls = selectBlockLocations(bim,ExcludeIncompleteBlocks=true);

Create a blockedImageDatastore from this set of blocks.

bimds = blockedImageDatastore(bim,BlockLocationSet=bls);

Visualize the block locations.

bigimageshow(bim)
% Block size is in row-col (height-width) order.
blockedWH = fliplr(bls.BlockSize(1,1:2));
for ind = 1:size(bls.BlockOrigin,1)
    % BlockOrigin is already in x,y order.
    drawrectangle(Position=[bls.BlockOrigin(ind,1:2) blockedWH]);
end

Create blockedImageDatastore with Overlapping Blocks

Create a blocked image.

bim = blockedImage("tumor_091R.tif");

Create a blockLocationSet object.

blockSize = [2048 3072];
overlapPct = 0.5;
blockOffsets = round(blockSize.*overlapPct);
bls = selectBlockLocations(bim,BlockSize=blockSize, ...
    BlockOffSets=blockOffsets,ExcludeIncompleteBlocks=true);

Create a blockedImageDatastore from this set of blocks.

bimds = blockedImageDatastore(bim,BlockLocationSet=bls);

Visualize the blocked locations.

bigimageshow(bim)
% Block size is in row-col (height-width) order
blockedWH = fliplr(bls.BlockSize(1,1:2));
colors = prism(size(bls.BlockOrigin,1));
for ind = 1:size(bls.BlockOrigin,1)
     blockedColor = colors(ind,:);
     % BlockOrigin is already in x-y order
     drawrectangle(Position=[bls.BlockOrigin(ind,1:2) blockedWH], ...
         Color=blockedColor);
end

Create blockedImageDatastore with Sparse Blocks

Create a blocked image.

bim = blockedImage("tumor_091R.tif");

Create a blockLocationSet object.

blockedSize = [1024 512];
spacePct = 0.5;
blockedOffsets = blockedSize + blockedSize.*spacePct;
bls = selectBlockLocations(bim,BlockSize=blockedSize, ...
    BlockOffSets=blockedOffsets,ExcludeIncompleteBlocks=true);

Create a blockedImageDatastore object from this set of blocks.

bimds = blockedImageDatastore(bim,BlockLocationSet=bls);

Visualize the block locations.

bigimageshow(bim)
% Block size is in row-col (height-width) order
blockedWH = fliplr(bls.BlockSize(1,1:2));
for ind = 1:size(bls.BlockOrigin,1)
     % BlockOrigin is already in x-y order
     drawrectangle(Position=[bls.BlockOrigin(ind,1:2) blockedWH]);
end

Create blockedImageDatastore Using Coarse Level Mask

Create a blocked image.

bim = blockedImage("tumor_091R.tif");

Display the blocked image.

h = bigimageshow(bim);

Create a mask at the coarsest level.

clevel = bim.NumLevels;
bmask = apply(bim,@(b)~imbinarize(im2gray(b.Data)),Level=clevel);

Use showMask to estimate an InclusionThreshold value.

showmask(h,bmask,BlockSize=[256 256],InclusionThreshold=0.9)

Create a blockedImagedatastore for blocks in which at least 90% of pixels are true in the stained region as defined by the mask.

mbls = selectBlockLocations(bim,Levels=1,BlockSize=[256 256], ...
    Masks=bmask,InclusionThreshold=0.90);

Create a blockedImageDatastore from this set of blocks.

bimds = blockedImageDatastore(bim,BlockLocationSet=mbls);

Read the blocks from the datastore.

bimds.ReadSize = 10;
blocks = read(bimds);

To verify that the datastore reads the correct blocks, display the blocks in a montage.

figure
montage(blocks,BorderSize=5,BackgroundColor="b"); 

Input Arguments

bims — Blocked images

blockedImage object | b-element vector of blockedImage objects

Blocked images, specified as a blockedImage object or b-element vector of blockedImage objects. All blocked images must have the same number of dimensions at the resolution levels from which blocks are selected.

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: bls = selectBlockLocations(bim,BlockSize=[224 224]) selects blocks of size 224-by-224 pixels.

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

Example: bls = selectBlockLocations(bim,"BlockSize",[224 224]) selects blocks of size 224-by-224 pixels.

BlockOffsets — Offset of adjacent blocks

vector of positive integers

Offset of adjacent blocks, in pixels, specified as a vector of positive integers. The length of BlockOffsets is less than or equal to the number of dimensions of the input blocked images. The first two elements specify the offset in the order (rows, columns).

The default value is equal to BlockSize, which results in non-overlapping blocks that completely sample the image. To overlap blocks, specify a smaller value. To add a gap between blocks, specify a larger value. If you specify block offsets of lower dimensionality than the input blocked image, then the selectBlockLocations function sets the block offset in the remaining dimensions equal to the image size in those dimensions.

Example: BlockOffsets=[100 200] specifies a block offset of 100 pixels vertically and 200 pixels horizontally

BlockSize — Block size

vector of positive integers

Block size, in pixels, specified as a vector of positive integers. The length of BlockSize is less than or equal to the number of dimensions of the input blocked images.

If you do not specify the BlockSize argument, the default value is equal to the BlockSize property of the first blocked image in bims at the finest resolution level. If you specify a block size of lower dimensionality, then the selectBlockLocations function sets the block size in the remaining dimensions equal to the image size in those dimensions.

Example: BlockSize=[1024 512] specifies blocks with a height of 1024 pixels and a width of 512 pixels

ExcludeIncompleteBlocks — Exclude incomplete blocks

false or 0 (default) | true or 1

Exclude incomplete blocks that are smaller than BlockSize, specified as a numeric or logical 0 (false) or 1 (true).

InclusionThreshold — Inclusion threshold for mask blocks

0.5 (default) | numeric scalar | b-element numeric vector

Inclusion threshold for mask blocks, specified as a numeric scalar or a b-element numeric vector with values in the range [0, 1]. The InclusionThreshold argument must have the same number of elements as the Masks argument. The selectBlockLocations function selects blocks that overlap the foreground of the corresponding mask block by a percentage greater than or equal to the value specified by InclusionThreshold.

• When the inclusion threshold is 0, the selectBlockLocations function selects a block when at least one pixel in the corresponding mask block is nonzero.

• When the inclusion threshold is 1, the selectBlockLocations function selects a block only when all pixels in the mask block are nonzero.

Levels — Resolution level

positive integer | b-element vector of positive integers

Resolution level of blocks from each blocked image in bims, specified as a positive integer or b-element vector of positive integers. If you specify a scalar value, the selectBlockLocations function selects blocks from all blocked images at the same resolution level. The default value is a b-element vector of 1s, which selects blocks from the finest resolution level of each image in bims.

Data Types: double

Masks — Mask images

blockedImage object | array of blockedImage objects

Mask images, specified as an array the same size as bims. The underlying data type of the mask images is logical. The selectBlockLocations function selects blocks that overlap the foreground of the corresponding mask block by an amount specified by InclusionThreshold. Masks are expected to be in the same world coordinate system as the corresponding blockedImage in the bims array.

UseParallel — Use parallel processing

false or 0 (default) | true or 1

Use parallel processing to evaluate mask blocks, specified as a numeric or logical 0 (false) or 1 (true). Parallel evaluation of masks is beneficial when the masks do not fit in memory.

Use of parallel processing requires Parallel Computing Toolbox™. The selectBlockLocations function uses an existing parallel pool of workers, or opens a new pool when no parallel pool is active. The Source property of each blocked image in bims must be a valid path on all of the parallel workers.

Output Arguments

blset — Block locations

blockLocationSet object

Block locations, returned as a blockLocationSet object.

References

[1] Bejnordi, Babak Ehteshami, Mitko Veta, Paul Johannes van Diest, Bram van Ginneken, Nico Karssemeijer, Geert Litjens, Jeroen A. W. M. van der Laak, et al. “Diagnostic Assessment of Deep Learning Algorithms for Detection of Lymph Node Metastases in Women With Breast Cancer.” JAMA 318, no. 22 (December 12, 2017): 2199–2210. https://doi.org/10.1001/jama.2017.14585.

Version History

Introduced in R2020b