blockLocationSet

List of block locations in large images

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.

• 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 specified by the blockLocationSet. 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-2 numeric matrix

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

Data Types: double

BlockSize — Block size

1-by-N vector of positive integers

Block size, specified as a 1-by-N vector of positive integers. The block size is the same for all blocks in the blockLocationSet. N matches the NumDimensions property of the blockedImage object.

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 = [[20 30 1]; [30 40 1]; [40 50 1]; [50 60 1]]

xyLocations = 4×3

    20    30     1
    30    40     1
    40    50     1
    50    60     1

blockSize = [300,300, 3];
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.

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

blocks=2×1 cell array
    {300×300×3 uint8}
    {300×300×3 uint8}

blocks=2×1 cell array
    {300×300×3 uint8}
    {300×300×3 uint8}

Display the read blocks.

montage(blocks,'BorderSize',5,'BackgroundColor','b');

Tips

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