blockedImageDatastore

Datastore for use with blocks from blockedImage objects

Description

A blockedImageDatastore object manages a collection of image blocks that belong to one or more blockedImage objects. A blockedImageDatastore is analogous to an imageDatastore, which manages a collection of unrelated images.

Creation

Syntax

bimds = blockedImageDatastore(Images)

bimds = blockedImageDatastore(sources)

bimds = blockedImageDatastore(___,Name,Value)

Description

bimds = blockedImageDatastore(Images) creates a blockedImageDatastore object that manages a collection of image blocks of one or more blockedImage objects, Images.

If Images contains an object with multiple resolution levels, then blockedImageDatastore chooses only blocks from the finest resolution level. The BlockSize property of the first element in Images is the default datastore block size.

bimds = blockedImageDatastore(sources) creates a datastore from the files specified by sources.

bimds = blockedImageDatastore(___,Name,Value) also uses name-value pairs to set one or more properties, except for Images and TotalNumBlocks. You can specify multiple name-value pairs. Enclose each property name in quotes.

Input Arguments

sources — Name of blocked image files

cell array of character vectors | string array | FileSet object

Name of the blocked image files, specified as a cell array of character vectors, a string scalar, or a FileSet object. The blockedImageDatastore object converts the images in the files into blocked images and sets those images as the Images property.

Properties

BlockLocationSet — Blocks to include in datastore

blockLocationSet object

Blocks to include in the datastore, specified as a blockLocationSet object. The object specifies which blocks to include from the blocked image bims. You can repeat or omit individual blocks. To obtain the default value, blockedImageDatastore calls the selectBlockLocations function.

You cannot change the BlockLocationSet property after creating the blockedImageDatastore.

BlockSize — Block size

1-by-D numeric vector

Block size, specified as a 1-by-D numeric vector, where D is the number of dimensions of the first blocked image in Images, at the first resolution level in Levels.

You cannot change the BlockSize property after creating the blockedImageDatastore.

BorderSize — Size of additional block border elements

1-by-D vector of nonnegative integers

Size of additional block border elements in each dimension, specified as a 1-by-D numeric vector, where D is the number of dimensions of the first blocked image in Images, at the first resolution level in Levels. The default value is zeros(1,D).

Images — Blocked images

array of blockedImage objects

Blocked images that supply blocks for the blockedImageDatastore, specified as an array of blockedImage objects. All elements of Images must have the same number of dimensions and be of the same type.

You cannot change the Images property after creating the blockedImageDatastore.

PadMethod — Method used for padding incomplete blocks

numeric scalar | 'replicate'

Method used for padding incomplete blocks, specified as one of the values in this table. By default, the datastore pads numeric blocks with the value of the InitialValue property of the first blocked image in the array of blocked images, Images.

Value	Meaning
numeric scalar	Pad incomplete blocks with the specified scalar value. The type of the value depends on the ClassUnderlying of the blocked images in Images.
'replicate'	Pad by repeating border elements of array.

PadPartialBlocks — Pad partial blocks

true (default) | false

Pad partial blocks that exist on the edge, specified as a logical scalar true or false. When true, the blocked image datastore add padding according to the padding method specified in the PadMethod property.

ReadSize — Number of blocks to return in each call to read function

1 (default) | positive integer

Number of blocks to return in each call to the read function, specified as a positive integer. Each call to the read function reads at most ReadSize blocks

TotalNumBlocks — Total number of blocks available

numeric scalar

This property is read-only.

Total number of blocks available, specified as a numeric scalar.

Object Functions

combine	Combine data from multiple datastores
countEachLabel	Counts number of pixel labels for each class
hasdata	Returns true if more data is available in blockedImageDatastore
numpartitions	Number of datastore partitions
partition	Return partitioned part of blockedImageDatastore
preview	Preview subset of data in datastore
read	Read data and metadata from blockedImageDatastore
readall	Read all data from the blockedImageDatastore
reset	Reset datastore to initial state
shuffle	Shuffle data in datastore
subset	Create subset of datastore or file-set
transform	Transform datastore

Examples

Create blockedImageDatastore at Specific level and Block Size

Create a blockedImage.

bim = blockedImage('tumor_091R.tif');

Create a datastore, specifying the resolution level and the blocksize.

bls = selectBlockLocations(bim,"Levels",2,"BlockSize",[512, 512]);
bimds = blockedImageDatastore(bim, "BlockLocationSet", bls);

Read all the blocks in the datastore.

b = readall(bimds)

b=9×1 cell array
    {512×512×3 uint8}
    {512×512×3 uint8}
    {512×512×3 uint8}
    {512×512×3 uint8}
    {512×512×3 uint8}
    {512×512×3 uint8}
    {512×512×3 uint8}
    {512×512×3 uint8}
    {512×512×3 uint8}

Display the blocked image

montage(b)

Create blockedImageDatastore from Multiple Files

Create a FileSet object containing multiple image files of the PNG file format.

fs = matlab.io.datastore.FileSet( ...
     fullfile(matlabroot,"toolbox","images","imdata"), ...
    "FileExtensions",".png");

Create a blockedImage object, specifying an adapter. This saves time by skipping the need to inspect each file to pick a suitable adapter.

readAdapter = images.blocked.GenericImage;
bims = blockedImage(fs,"Adapter",readAdapter);

All images must have the same number of dimensions, so only retain RGB images.

bims = bims([bims.NumDimensions]==3);
bimds = blockedImageDatastore(bims,"BlockSize",[300 500], ...
     "PadMethod","replicate");

Display all of the blocks in the blockedImageDatastore.

montage(readall(bimds),"Border",2,"BackgroundColor","w");

Create blockedImageDatastore with Overlapping Blocks

Create a blockedImage.

bim = blockedImage('tumor_091R.tif');

Specify overlapping blocks.

blockSize = [512 512];
overlapPct = 0.5;
blockOffsets = round(blockSize.*overlapPct);
bls = selectBlockLocations(bim,...
      'BlockSize', blockSize,...
      'BlockOffSets', blockOffsets,...
      'ExcludeIncompleteBlocks', true);

Create the blockedImageDatastore.

bimds = blockedImageDatastore(bim, "BlockLocationSet", bls);

Display the overlapping blocks.

bimds.ReadSize = 6;
blocks = read(bimds);
montage(blocks, "BorderSize", 5, "BackgroundColor", 'b');

Create blockedImageDatastore using Coarse Level Mask

Create a blockedImage.

bim = blockedImage('tumor_091R.tif');

Create a mask at the coarsest level.

bmask = apply(bim, @(bs)~imbinarize(im2gray(bs.Data)),"Level",3);

Create a blockedImageDatastore for blocks which have at least 90% pixels 'on' in the stained region as defined by the mask.

mbls = selectBlockLocations(bim,...
     'Levels', 1, ...
     'Masks', bmask, 'InclusionThreshold', 0.90,...
     'BlockSize', [256 256]);
bimds = blockedImageDatastore(bim, 'BlockLocationSet', mbls);

Read blocks and display them.

bimds.ReadSize = 5;
blocks = read(bimds);
montage(blocks, "BorderSize", 5, "BackgroundColor", 'b')

Create Categorical Data from Labelled Numeric Data

Create blocked images from numeric and labeled data.

bim = blockedImage('yellowlily.jpg', 'BlockSize', [512 512]);
lbim = blockedImage('yellowlily-segmented.png', 'BlockSize', [512 512]);

Create blockedImageDatastore objects for each blocked image.

bimds = blockedImageDatastore(bim);
lbimds = blockedImageDatastore(lbim);

Transform the labeled numeric data into categorical data.

catbimds = transform(lbimds,...
      @(bs){categorical(bs{1}, [0,1, 2, 3], ["Unknown", "Flower", "Leaf", "Background"])});

Combine the original blockedImageDatastore with the categorical datastore.

cbimds = combine(bimds,catbimds);  

Read data from the datastore and display it. The first cell is image data, second is categorical labels.

data = read(cbimds);
imshow(labeloverlay(data{1},data{2}));