bigimageDatastore

Datastore to manage blocks of big image data

Description

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

Creation

Description

bigds = bigimageDatastore(Images,Levels) creates a datastore that manages a collection of image blocks that belong to one or more bigimage objects, Images, at the specified resolution levels, Levels.

bigds = bigimageDatastore(Images,Levels,Name,Value) also uses name-value pairs to set one or more of the BlockSize, BlockOffsets, Masks, InclusionThreshold, or IncompleteBlocks properties. You can specify multiple name-value pairs. Enclose each property name in quotes.

For example, bigimageDatastore(bigimg,3,'BlockSize',[128 128],'IncompleteBlocks','pad') creates a datastore that reads blocks of size 128-by-128 at resolution level 3 from big image bigimg and zero-pads partial edge blocks.

Properties

Images — Big images

b-element vector of bigimage objects

Big images that supply blocks for the bigimageDatastore, specified as a b-element vector of bigimage objects. To read different resolution levels from the same big image, specify the same image multiple times in the vector.

Levels — Resolution level

positive integer | b-element vector of positive integers

Resolution level of blocks from each big image in Images, specified as a positive integer scalar or a b-element vector of positive integers. If you specify a scalar value, then all big images supply blocks to the bigimageDatastore at the same resolution level.

Data Types: double

BlockSize — Block size

1-by-2 vector of positive integers

Block size of read data, specified as a 1-by-2 vector of positive integers of the form [numrows numcols]. The default value is equal to the BlockSize property of the first bigimage object in Images at the first resolution level in Levels.

Masks — Mask images

scalar bigimage object | b-element vector of bigimage objects

Mask images, specified as a scalar bigimage object or a b-element vector of bigimage objects with an underlying class of data type logical. The Masks property determines which blocks to include when you call read. By default, bigimageDatastore reads all blocks.

InclusionThreshold — Inclusion threshold for mask blocks

numeric scalar | b-element numeric vector

Inclusion threshold for mask blocks, specified as a numeric scalar or a b-element numeric vector with values in the range [0, 1]. The inclusion threshold specifies the minimum percentage of nonzero (true) pixels in a mask block required to read the image block.

• When the inclusion threshold is 0, the bigimageDatastore reads a block when at least one pixel in the corresponding mask block is nonzero.

• When the inclusion threshold is 1, the bigimageDatastore reads a block when all pixels in the mask block are nonzero.

BorderSize — Border size

[0 0] (default) | 1-by-2 vector of nonnegative integers

Border size, specified as a 1-by-2 vector of nonnegative integers of the form [m n]. The function adds m rows above and below each block and n columns left and right of each block with data from the neighboring blocks. For blocks that lie on the edge of an image, data is padded according to IncompleteBlocks. By default, no border is added to blocks.

BlockOffsets — Block offsets

1-by-2 vector of positive integers

Block offsets, specified as 1-by-2 vector of positive integers of the form [numrows numcols].

The default value is equal to BlockSize. Use a smaller value to obtain overlapping blocks during calls to read. Use a larger value to add a gap between blocks.

IncompleteBlocks — Method to handle edge blocks

"same" (default) | "exclude" | "pad"

Method to handle edge blocks that are smaller than BlockSize, specified as one of these values.

Value	Meaning
"same"	Return data of the same size as the edge block.
"exclude"	Do not include edge blocks in calls to read.
"pad"	Pad incomplete blocks to the same size as BlockSize using the pad method specified by PadMethod.

PadMethod — Pad method

0 (default) | numeric scalar | 'replicate' | 'symmetric'

Pad method of incomplete edge blocks, specified as one of these values. By default, bigimageDatastore zero-pads incomplete blocks.

Value	Meaning
numeric scalar	Pad array with elements of constant value.
'replicate'	Pad by repeating border elements of array.
'symmetric'	Pad array with mirror reflections of itself.

ReadSize — Number of blocks to return

positive integer

Number of blocks to return in each call to read, specified as a positive integer.

Object Functions

combine	Combine data from multiple datastores
hasdata	Determine if data is available to read
numpartitions	Number of datastore partitions
partition	Partition bigimageDatastore
preview	Subset of data in datastore
read	Read data from bigimageDatastore
readRelative	Read neighboring block from bigimageDatastore using relative position
reset	Reset datastore to initial state
shuffle	Shuffle data in datastore
transform	Transform datastore

Examples

Create Big Image Datastore and Specify Block Size

Create 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 default block size of the bigimage at each resolution level. The block size is a 2-element vector of the form [numrows, numcols].

t = table((1:3)',bim.BlockSize,'VariableNames',["Level" "Block Size"]);
disp(t)

    Level     Block Size 
    _____    ____________

      1      1024    1024
      2      1024    1024
      3      1024    1024

Display the bigimage by using the bigimageshow function.

bigimageshow(bim);

Create a bigimageDatastore at resolution level 1. Specify a nondefault block size. Set the datastore to read four blocks at a time.

bimds = bigimageDatastore(bim,2,'BlockSize',[512 512])

bimds = 
  bigimageDatastore with properties:

              ReadSize: 1
            BorderSize: [0 0]
             PadMethod: 0
    InclusionThreshold: 0.5000
                 Masks: [0x0 bigimage]
                Images: [1x1 bigimage]
                Levels: 2
             BlockSize: [512 512]
          BlockOffsets: [512 512]
      IncompleteBlocks: 'same'

bimds.ReadSize = 4;

Read one batch of data from the datastore. Notice that the third block is a partial edge block and has a smaller size than interior blocks. Display the returned image patches as a montage. The montage displays the third block with a thicker border because the width of the block is smaller than the width of the complete blocks.

blocks = read(bimds)

blocks=4×1 cell
    {512x512x3 uint8}
    {512x512x3 uint8}
    {512x316x3 uint8}
    {512x512x3 uint8}

montage(blocks,'Size',[1 bimds.ReadSize],'BorderSize',5,'BackgroundColor','k');

Read the next batch of data from the datastore and display the returned image patches as a montage. The montage displays partial blocks with a thicker border because the dimensions of the blocks are smaller than the dimensions of the full block.

blocks = read(bimds)

blocks=4×1 cell
    {512x512x3 uint8}
    {512x316x3 uint8}
    {226x512x3 uint8}
    {226x512x3 uint8}

montage(blocks,'Size',[1 bimds.ReadSize],'BorderSize',5,'BackgroundColor','k');

Read the last batch of data from the datastore. The read operation returns a partial batch that contains the only remaining patch. Display the patch.

blocks = read(bimds)

blocks = 1x1 cell array
    {226x316x3 uint8}

montage(blocks,'Size',[1 bimds.ReadSize],'BorderSize',5,'BackgroundColor','k');

Create Big Image Datastore and Specify Mask

Create 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 bigimage by using the bigimageshow function.

h = bigimageshow(bim);

Create a mask at the coarsest resolution level, retaining the original spatial referencing information.

clevel = bim.CoarsestResolutionLevel;
imcoarse = getFullLevel(bim,clevel);
stainMask = ~imbinarize(rgb2gray(imcoarse));
bmask = bigimage(stainMask,'SpatialReferencing',bim.SpatialReferencing(clevel));

Create a bigimageDatastore from image data at the finest resolution level. Specify the InclusionThreshold property as 0.75 so that the datastore reads patches that are at least 75% within the ROI defined by the mask.

bimds = bigimageDatastore(bim,1,'BlockSize',[256 256], ...
    'Masks',bmask,'InclusionThreshold',0.75);
bimds.ReadSize = 4;

To preview which patches are read by the datastore, display the mask over the original bigimage using the same block size and inclusion threshold. The overlay highlights in green the patches that are at least 75% within the ROI defined by the mask.

showmask(h,bmask,'BlockSize',[256 256],'InclusionThreshold',0.75)

Read the first batch of data from the datastore and display the returned image patches as a montage. The content of these patches matches the green blocks of the overlay.

blocks = read(bimds);
montage(blocks,'Size',[1 bimds.ReadSize],'BorderSize',5,'BackgroundColor','k');