blockLocationSet

List of block locations in large images

Since R2020a

Description

A blockLocationSet object provides locations of blocks used for class balancing in semantic segmentation and object detection training workflows. It is used by blockedImageDatastore and boxLabelDatastore objects to specify block locations to read data.

Creation

You can create a blockLocationSet object in these ways.

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

• balancePixelLabels (Computer Vision Toolbox) — Select blocks from labeled blocked 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 blocked images with bounding box data (requires Computer Vision Toolbox). Use this function to perform class balancing in object detection workflows.

• mergeBlockLocationSets — Merge two sets of block locations into a single set of block locations. Use this function when you want to combine block locations selected from a set of images using different criteria, or when you want to combine block locations selected from two different sets of images.

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

Syntax

locationSet = blockLocationSet(ImageNumber,BlockOrigin,BlockSize)

locationSet = blockLocationSet(ImageNumber,BlockOrigin,BlockSize,Levels)

Description

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 blocked image files indexed by ImageNumber.

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

Properties

ImageNumber — Image number

n-by-1 vector of positive integers

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. Values cannot exceed the number of blocked images in the blockedImageDatastore.

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

Data Types: double

BlockOrigin — Block origin

n-by-d numeric matrix

Block origin, specified as an n-by-d numeric matrix, where n is the number of blocks. d is the dimensionality of the blocks, which must be less than or equal to the number of dimensions of the blockedImage object. Each row specifies the [x y ... dimD] coordinate of the top left corner of a block.

Example: BlockOrigin=[200 100] specifies a block whose top left corner is at (x, y) coordinate (200, 100)

Data Types: double

BlockSize — Block size

1-by-d vector of positive integers

Block size, specified as a 1-by-d vector of positive integers. d is the dimensionality of the blocks, which must be less than or equal to the number of dimensions of the blockedImage object. The block size is the same for all blocks in the blockLocationSet.

Levels — Resolution levels

1 (default) | positive integer | vector of positive integers

Resolution level of each blockedImage in a blockedImageDatastore, specified as a positive integer or a vector of positive integers.

• When you specify Levels as a positive integer scalar, the blockedImageDatastore 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 blockedImageDatastore reads blocks from the corresponding blockedImage. The length of Levels must equal the number of blockedImage objects in the blockedImageDatastore.

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

Examples

Specify Locations to Select Blocks from Blocked Images

Create a blocked image.

bim = blockedImage("tumor_091R.tif");
bigimageshow(bim)

Since all the blocks are from the same image, imageNumber is 1 for all the blocks. For resolution level, choose the finest resolution. Specify block locations in x,y coordinates.

imageNumber = [1, 1, 1, 1]';
levels = 1;
xyLocations = [2000 3000; 2000 3500; 3000 3000; 3000 3500]

xyLocations = 4×2

        2000        3000
        2000        3500
        3000        3000
        3000        3500

blockSize = [300 300];
locationSet = blockLocationSet(imageNumber,xyLocations,blockSize,levels);

Use the block location set to create a blockedImageDatastore containing just the specified blocks.

bimds = blockedImageDatastore(bim,BlockLocationSet=locationSet);

Read two blocks at a time from the blockedImageDatastore. and display the blocks as a montage.

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

Tips

• The blockLocationSet object does not read or store data from blocked image files.

Version History

Introduced in R2020a

R2023a: Write all blocks to file

You can create a block location set that merges two other block location sets using the mergeBlockLocationSets function. This function merges information about the location of the blocks, but does not merge the image data.

R2023a: Support for symmetric padding

You can now specify the PadMethod property as "symmetric". Symmetric padding consists of mirror reflections of pixels from within the same block.