List of block locations in big images


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 blockLocationSet to specify the blocks to be read by a boxLabelDatastore.

Use a blockLocationSet to perform class balancing in semantic segmentation and object detection workflows.


You can create a blockLocationSet object by using the blockLocationSet function described here.

If you have Computer Vision Toolbox, then you can create a blockLocationSet object with balanced pixel labels or balanced box labels by using the balancePixelLabels and balanceBoxLabels functions, respectively.



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.


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.


collapse all

Load a bigimage. This examples uses 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]';
locationSet = blockLocationSet(imageNumber,xyLocations,blockSize);

Create a bigimageDatastore using the blockLocationSet.

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

Read two blocks at a time and display them in a montage. The datastore reads the blocks from positions specified by the blockLocationSet.

bimds.ReadSize = 2;
while hasdata(bimds)
    blocks = read(bimds);


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

Introduced in R2020a