blockedImageDatastore

Datastore for use with blocks from blockedImage objects

Since R2021a

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.

By default, if Images contains a blocked image with multiple resolution levels, then blockedImageDatastore chooses only blocks from the finest resolution level. By default, the block size of the datastore is equal to the BlockSize property of the first element in Images at the finest resolution level.

example

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

bimds = blockedImageDatastore(___,Name,Value) also uses name-value arguments to set one or more properties, except for Images and TotalNumBlocks.

Input Arguments

expand all

`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

expand all

`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 Images. You can repeat or omit individual blocks.

You cannot specify the BlockLocationSet property when you specify the BlockSize property. If you specify the BlockSize property, then the default value of BlockLocationSet is the blockLocationSet object returned by calling the selectBlockLocations function with the specified block size. Otherwise, the default value is the blockLocationSet object returned by calling the selectBlockLocations function without specifying a block size.

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. D is the number of dimensions of the first blocked image in Images, at the first resolution level in Levels.

You cannot specify the BlockSize property when you specify the BlockLocationSet property. If you specify the BlockLocationSet property, then the default value of BlockSize is equal to the block size of the blockLocationSet object. Otherwise, the default value is equal to the block size of the first blocked image in Images at the finest resolution level.

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 vector of nonnegative integers. 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 data type.

You cannot change the Images property after creating the blockedImageDatastore.

`PadMethod` — Method used for padding incomplete blocks
numeric scalar | logical scalar | categorical scalar | `"replicate"` | `"symmetric"`

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

Value	Meaning
numeric, logical, or categorical scalar	Pad array with elements of the specified value. The data type of `PadMethod` must match the `ClassUnderlying` property of the blocked image.
`"replicate"`	Pad by repeating border elements of the block.
`"symmetric"` (since R2023a)	Pad with mirror reflections of pixels from within the same block.

`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 blocked image datastore
`numpartitions`	Number of datastore partitions
`partition`	Return partitioned part of blocked image datastore
`preview`	Preview subset of data in datastore
`read`	Read data and metadata from blocked image datastore
`readall`	Read all data from blocked image datastore
`reset`	Reset datastore to initial state
`shuffle`	Shuffle data in datastore
`subset`	Create subset of datastore or FileSet
`transform`	Transform datastore
`writeall`	Write blocked image datastore to files

Examples

collapse all

Create Blocked Image Datastore Specifying Level and Block Size

Open Live Script

Create a blocked image.

bim = blockedImage("tumor_091R.tif");

Create a datastore, specifying the resolution level and the block size.

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
    {512x512x3 uint8}
    {512x512x3 uint8}
    {512x512x3 uint8}
    {512x512x3 uint8}
    {512x512x3 uint8}
    {512x512x3 uint8}
    {512x512x3 uint8}
    {512x512x3 uint8}
    {512x512x3 uint8}

Display the blocked image.

montage(b)

Figure contains an axes object. The hidden axes object contains an object of type image.

Create blockedImageDatastore from Multiple Files

Open Live Script

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

Figure contains an axes object. The hidden axes object contains an object of type image.

Create `blockedImageDatastore` with Overlapping Blocks

Open Live Script

Create a blocked image.

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 blocked image datastore.

bimds = blockedImageDatastore(bim,BlockLocationSet=bls);

Display the overlapping blocks.

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

Figure contains an axes object. The hidden axes object contains an object of type image.

Create blockedImageDatastore using Coarse Level Mask

Open Live Script

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

Figure contains an axes object. The hidden axes object contains an object of type image.

Create Categorical Data from Labeled Numeric Data

Open Live Script

Create blocked images from numeric and labeled data.

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

Create blockedImageDatastore objects for each blocked image.

bimds = blockedImageDatastore(bim);
bimdsLabels = blockedImageDatastore(bimLabels);

Transform the labeled numeric data into categorical data.

classes = ["Unknown","Flower","Leaf","Background"];
classIDs = [0 1 2 3];
bimdsCategorical = transform(bimdsLabels, ...
      @(bs){categorical(bs{1},classIDs,classes)});

Combine the original blockedImageDatastore with the categorical datastore.

bimdsCombined = combine(bimds,bimdsCategorical);

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

data = read(bimdsCombined)

data=1×2 cell array
    {512x512x3 uint8}    {512x512 categorical}

imshow(labeloverlay(data{1},data{2}));

Figure contains an axes object. The hidden axes object contains an object of type image.

Version History

Introduced in R2021a

expand all

R2023a: Write all blocks to file

You can now write all blocks of a blocked image datastore to files using the writeall function.

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.

R2022b: Specify block location sets of lower dimensionality

When you create a blockedImageDatastore, you can now specify the BlockLocationSet property as a blockLocationSet object with blocks of lower dimensionality than the input blocked images. In this case, the blockedImageDatastore sets the block size in the remaining dimensions equal to the image size in those dimensions.

Before, you specified the BlockLocationSet property as a blockLocationSet with blocks of equal dimensionality to the input blocked images.

blockedImageDatastore

Description

Creation

Syntax

Description

Input Arguments

sources — Name of blocked image files cell array of character vectors | string array | FileSet object

Properties

BlockLocationSet — Blocks to include in datastore blockLocationSet object

BlockSize — Block size 1-by-D numeric vector

BorderSize — Size of additional block border elements 1-by-D vector of nonnegative integers

Images — Blocked images array of blockedImage objects

PadMethod — Method used for padding incomplete blocks numeric scalar | logical scalar | categorical scalar | "replicate" | "symmetric"

PadPartialBlocks — Pad partial blocks true (default) | false

ReadSize — Number of blocks to return in each call to read function 1 (default) | positive integer

TotalNumBlocks — Total number of blocks available numeric scalar

Object Functions

Examples

Create Blocked Image Datastore Specifying Level and Block Size

Create blockedImageDatastore from Multiple Files

Create blockedImageDatastore with Overlapping Blocks

Create blockedImageDatastore using Coarse Level Mask

Create Categorical Data from Labeled Numeric Data

Version History

R2023a: Write all blocks to file

R2023a: Support for symmetric padding

R2022b: Specify block location sets of lower dimensionality

See Also

`sources` — Name of blocked image files
cell array of character vectors | string array | `FileSet` object

`BlockLocationSet` — Blocks to include in datastore
`blockLocationSet` object

`BlockSize` — Block size
1-by-D numeric vector

`BorderSize` — Size of additional block border elements
1-by-D vector of nonnegative integers

`Images` — Blocked images
array of `blockedImage` objects

`PadMethod` — Method used for padding incomplete blocks
numeric scalar | logical scalar | categorical scalar | `"replicate"` | `"symmetric"`

`PadPartialBlocks` — Pad partial blocks
`true` (default) | `false`

`ReadSize` — Number of blocks to return in each call to `read` function
`1` (default) | positive integer

`TotalNumBlocks` — Total number of blocks available
numeric scalar

Create `blockedImageDatastore` with Overlapping Blocks