Main Content

blockLocationSet

List of block locations in big images

Description

A blockLocationSet object stores the size and location of blocks to be read by a bigimageDatastore. If you have Computer Vision Toolbox™, then you can use a blockLocationSet object to specify the blocks to be read by a boxLabelDatastore (Computer Vision Toolbox).

Creation

You can create a blockLocationSet object in these ways.

  • selectBlockLocations — Select blocks from an entire big image or within the masked region of a big image. Optionally specify the overlap and spacing between blocks.

  • balancePixelLabels (Computer Vision Toolbox) — Select blocks from labeled big images with pixel label data (requires Computer Vision Toolbox). Use this function to perform class balancing in semantic segmentation workflows.

  • balanceBoxLabels (Computer Vision Toolbox) — Select blocks from labeled big images with bounding box data (requires Computer Vision Toolbox). Use this function to perform class balancing in object detection workflows.

  • The blockLocationSet function described here. Use this function when you know the coordinates of blocks within the big images.

Description

example

locationSet = blockLocationSet(ImageNumber,BlockOrigin,BlockSize) creates a blockLocationSet object that stores the locations BlockOrigin and size BlockSize of blocks to be read from a set of big image files indexed by ImageNumber.

locationSet = blockLocationSet(ImageNumber,BlockOrigin,BlockSize,Levels) also specifies the resolution level at which to read blocks from the big images.

Properties

expand all

Image number of image files containing the read blocks, specified as an n-by-1 vector of positive integers where n is the number of blocks specified by the blockLocationSet. Values cannot exceed the number of bigimages in the bigimageDatastore.

Example: [1 1 1 2] specifies that a bigimageDatastore reads four blocks total, with the first three blocks coming from the first bigimage and the fourth block coming from the second bigimage in the datastore.

Data Types: double

Block origin, specified as an n-by-2 numeric matrix where n is the number of blocks specified by the blockLocationSet. Each row specifies the [x y] coordinate of the upper left corner of a block.

Data Types: double

Block size, specified as a 1-by-2 vector of positive integers of the form [numrows numcols]. The block size is the same for all blocks in the blockLocationSet.

Resolution level of each bigimage in a bigimageDatastore, specified as a positive integer or a vector of positive integers.

  • When you specify Levels as a positive integer scalar, the bigimageDatastore reads all blocks from the same resolution level.

  • When you specify Levels as a vector of positive integers, each element indicates the resolution level at which the bigimageDatastore reads blocks from the corresponding bigimage. The length of Levels must equal the number of bigimages in the bigimageDatastore.

Example: [1 1 2 2 1] specifies that a bigimageDatastore containing five bigimages reads blocks at the first resolution level from the first, second, and fifth bigimage and blocks at the second resolution level from the third and fourth bigimage.

Examples

collapse all

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 entire bigimage at the finest resolution level.

bshow = bigimageshow(bim);

Specify four [x y] block locations from the finest level. The first two blocks overlap in the vertical direction. The second two blocks are adjacent horizontally.

xyLocations = [ ...
    2800 1300; ...
    2800 1400; ...
    1500 2400; ...
    1800 2400];
blockSize = [300,300];

All blocks are from the same image. Specify the image number as 1 for all blocks.

imageNumber = [1 1 1 1]';

Create a blockLocationSet object that stores block locations.

locationSet = blockLocationSet(imageNumber,xyLocations,blockSize);

Create a bigimageDatastore object that reads blocks from big image bim at locations specified by the blockLocationSet object.

bimds = bigimageDatastore(bim,'BlockLocationSet',locationSet);

Read two blocks at a time from the datastore and display them in a montage.

bimds.ReadSize = 2;
while hasdata(bimds)
    figure
    blocks = read(bimds);
    montage(blocks,'BorderSize',5,'BackgroundColor','b');
end

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

Tips

  • The blockLocationSet function and object do not read or store data from big image files.

See Also

| | | | (Computer Vision Toolbox) | (Computer Vision Toolbox) | (Computer Vision Toolbox)

Introduced in R2020a