selectBlockLocations

Select blocks from big images

Syntax

blset = selectBlockLocations(bigimgs)

blset = selectBlockLocations(bigimgs,Name,Value)

Description

blset = selectBlockLocations(bigimgs) selects a set of nonoverlapping unique blocks from one or more bigimage objects bigimgs at the finest resolution available in each image.

blset = selectBlockLocations(bigimgs,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

Select All Complete Nonoverlapping Blocks in Big Image

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

Specify the location of all complete blocks of size 768-by-1024.

bls = selectBlockLocations(bim,'BlockSize',[768 1024], ...
    'ExcludeIncompleteBlocks',true);

Visualize the block locations as rectangular ROIs overlaid on the big image. The drawrectangle function expects the size of the ROI to be specified in (width,height) form, so horizontally flip the block size of the blockLocationSet, which is specified in (height,width) form.

bigimageshow(bim)
blockWH = fliplr(bls.BlockSize);
for ind = 1:size(bls.BlockOrigin,1)
    drawrectangle('Position',[bls.BlockOrigin(ind,:),blockWH]);
end

Select Overlapping Blocks in Big Image

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

Specify the size of blocks to read.

blockSize = [1500 1500];

To overlap blocks, specify a block offset distance that is less than the block size.

blockOffsets = blockSize - 150;

Specify the location of complete blocks in the image using the block size and block offset distance.

bls = selectBlockLocations(bim,...
      'BlockSize',blockSize,...
      'BlockOffSets',blockOffsets,...
      'ExcludeIncompleteBlocks',true);

Visualize the block locations as rectangular ROIs overlaid on the big image. Display each ROI in a different color.

bigimageshow(bim)
blockWH = fliplr(bls.BlockSize);
colors = prism(size(bls.BlockOrigin,1));
for ind = 1:size(bls.BlockOrigin,1)
    blockColor = colors(ind,:);
    drawrectangle('Position',[bls.BlockOrigin(ind,:),blockWH],'Color',blockColor);
end

Create Big Image Datastore From Sparse Blocks

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

Specify the size of blocks to read.

blockSize = [1024 512];

Specify the block offset distance as 1.5 times the block size.

blockOffsets = 1.5*blocksize;

Specify the location of complete blocks in the image using the block size and block offset distance. The resulting blockLocationSet object has 21 blocks.

bls = selectBlockLocations(bim,...
      'BlockSize',blockSize,...
      'BlockOffSets',blockOffsets,...
      'ExcludeIncompleteBlocks',true);

Visualize the block locations as rectangular ROIs overlaid on the big image.

bigimageshow(bim)
blockWH = fliplr(bls.BlockSize);
for ind = 1:size(bls.BlockOrigin,1)
    drawrectangle('Position',[bls.BlockOrigin(ind,:),blockWH]);
end

Create a bigimageDatastore that reads blocks from the locations specified in the blockLocationSet object.

numBlocks = length(bls.BlockOrigin);
bimds = bigimageDatastore(bim,'BlockLocationSet',bls, ...
    'ReadSize',numBlocks);

Read all blocks in the datastore and display the blocks as a montage. The block data agrees with the block location ROIs overlaid on the bigimage.

blocks = read(bimds);
figure
montage(blocks,'Size',[3 7],'BorderSize',5,'BackgroundColor','k');

Create Big Image Datastore and Specify Mask

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

Display the bigimage by using the bigimageshow function.

h = bigimageshow(bim);

Create a mask at the coarsest resolution level, retaining the original spatial referencing information.

clevel = bim.CoarsestResolutionLevel;
imcoarse = getFullLevel(bim,clevel);
stainMask = ~imbinarize(rgb2gray(imcoarse));
bmask = bigimage(stainMask,'SpatialReferencing',bim.SpatialReferencing(clevel));

Specify the location of blocks to read from the bigimage by using the selectBlockLocations function. Set the block size as 256-by-256 pixels. Select blocks that are at least 75% within the ROI defined by the mask by specifying the 'InclusionThreshold' name-value pair argument. By default, selectBlockLocations selects blocks from the finest resolution level of the big image.

t = 0.75;
blockSize = [256 256];
blockSet = selectBlockLocations(bim,"BlockSize",blockSize, ...
    "Masks",bmask,"InclusionThreshold",t);

Create a bigimageDatastore that reads four blocks at a time from the locations specified by the blockLocationSet.

bimds = bigimageDatastore(bim,"BlockLocationSet",blockSet,"ReadSize",4);

To preview which patches are read by the datastore, display the mask over the original bigimage using the same block size and inclusion threshold. The overlay highlights in green the patches that are at least 75% within the ROI defined by the mask.

showmask(h,bmask,'BlockSize',blockSize,'InclusionThreshold',t)

Read the first batch of data from the datastore and display the returned image patches as a montage. The content of these patches matches the green blocks of the overlay.

blocks = read(bimds);
montage(blocks,'Size',[1 bimds.ReadSize],'BorderSize',5,'BackgroundColor','k');

Input Arguments

bigimgs — Big images

bigimage object | b-element vector of bigimage objects

Big images, specified as a bigimage object or b-element vector of bigimage 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 the comma-separated pair consisting of 'BlockOffsets' and a 2-element row vector of positive integers of the form [numrows numcols].

The default value is equal to 'BlockSize'. 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 the comma-separated pair consisting of 'BlockSize' and a 2-element row vector of positive integers of the form [rows cols]. The default value is equal to the BlockSize property at the finest resolution level of the first big image in bigimgs.

'ExcludeIncompleteBlocks' — Exclude incomplete blocks

false or 0 (default) | true or 1

Exclude incomplete blocks that are smaller than 'BlockSize', specified as the comma-separated pair consisting of 'ExcludeIncompleteBlocks' and 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 the comma-separated pair consisting of 'InclusionThreshold' and 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 big image in bigimgs, specified as the comma-separated pair consisting of 'Levels' and a positive integer or a b-element vector of positive integers. If you specify a scalar value, then the selectBlockLocations function selects blocks from all big images at the same resolution level.

Data Types: double

'Masks' — Mask images

bigimage object | b-element vector of bigimage objects

Mask images, specified as the comma-separated pair consisting of 'Masks' and a bigimage object or a b-element vector of bigimage objects. 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'.

'UseParallel' — Use parallel processing

false or 0 (default) | true or 1

Use parallel processing to evaluate mask blocks, specified as the comma-separated pair consisting of 'UseParallel' and 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 DataSource property of each big image in bigimgs 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.