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 blockedImage objects bims at the finest resolution available in each image. Returns blset, a blockLocationsSet object.

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 pair 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 blocked 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');

Visualize 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 which have at least 90% of pixels 'on' in the stained region as defined by the mask.

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

Create a blockedImageDatastore from this set of blocks.

bimds = blockedImageDatastore(bim,'BlockLocationSet', mbls);

Verify.

bimds.ReadSize = 10;
blocks = read(bimds);
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.

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: 'BlockSize',[224 224] sets the block size to 224-by-224.

'BlockOffsets' — Offset of adjacent blocks

2-element row vector of positive integers

Offset of adjacent blocks, specified as a 2-element row vector of positive integers of the form [rows columns ].

The default value is equal to BlockSize, resulting in non-overlapping blocks. To overlap blocks, specify a smaller value. To add a gap between blocks, specify a larger value.

'BlockSize' — Block size

2-element row vector of positive integers

Block size, specified as a 2-element row vector of positive integers of the form [rows columns]. The default value is equal to the BlockSize property at the finest resolution level of the first blocked image in bims.

'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 scalar positive integer or an array of the same size as bims. If you specify a scalar value, the selectBlockLocations function selects blocks from all blocked images at the same resolution level. Default value is the finest level of each image in the array of blocked images, 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.