Main Content

bigimageDatastore

Datastore to manage blocks of big image data

Description

A bigimageDatastore object 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

Create Datastore that Reads Blocks Over Entire Image

bigds = bigimageDatastore(images) creates a datastore that manages a collection of image blocks at the finest resolution level of one or more bigimage objects, Images.

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

example

bigds = bigimageDatastore(images,levels,Name,Value) also uses name-value pairs to set one or more Properties except for BlockLocationSet. You can specify multiple name-value pairs. Enclose each property name in quotes.

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.

Create Datastore that Reads Blocks at Specified Locations

example

bigds = bigimageDatastore(images,'BlockLocationSet',blockLocationSet) creates a datastore that reads blocks from bigimage objects, Images, using the resolution level, block size, and block positions specified by BlockLocationSet.

bigds = bigimageDatastore(images,'BlockLocationSet',blockLocationSet,Name,Value) also uses name-value pairs to set one or more of the BorderSize, IncompleteBlocks, PadMethod, and ReadSize properties. You can specify multiple name-value pairs. Enclose each property name in quotes.

Example: bigimageDatastore(bigimg,'BlockLocationSet',bls,'ReadSize',4) creates a datastore that reads four blocks at a time from big images bigimg according to the position, block size, and resolution level specified by bls.

Properties

expand all

Block locations, specified as a blockLocationSet object.

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

The default value is equal to BlockSize. To overlap blocks during calls to read, specify a smaller value. To add a gap between blocks, specify a larger value.

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 big image in Images at the first resolution level in Levels.

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 to the 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, the datastore does not add a border to blocks.

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.

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.

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 datastore at the same resolution level.

Data Types: double

Pad method of incomplete edge blocks, specified as one of these values. By default, the datastore pads numeric blocks with 0 and categorical blocks with missing.

Value

Meaning

numeric scalar

Pad numeric array with elements of constant value.

string scalar

Pad categorical array with the specified class in the Classes property of the underlying bigimage.

"replicate"

Pad by repeating border elements of array.

"symmetric"

Pad array with mirror reflections of itself.

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

Object Functions

combineCombine data from multiple datastores
countEachLabelCount number of pixel labels for each class of bigimageDatastore
hasdataDetermine if data is available to read
numpartitionsNumber of datastore partitions
partitionPartition bigimageDatastore
previewPreview subset of data in datastore
readRead data from bigimageDatastore
readRelativeRead neighboring block from bigimageDatastore using relative position
resetReset datastore to initial state
shuffleShuffle data in datastore
transformTransform datastore
isPartitionableDetermine whether datastore is partitionable
isShuffleableDetermine whether datastore is shuffleable

Examples

collapse all

Create a bigimage using 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],'ReadSize',4)
bimds = 
  bigimageDatastore with properties:

            ReadSize: 4
          BorderSize: [0 0]
           PadMethod: 0
              Images: [1x1 bigimage]
              Levels: 2
           BlockSize: [512 512]
        BlockOffsets: [512 512]
    IncompleteBlocks: 'same'
    BlockLocationSet: [1x1 blockLocationSet]

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 array
    {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 array
    {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 a bigimage using 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));

Specify the location of blocks to read from the bigimage by using the selectBlockLocations function. Set the block size as 256-by-256 pixels. Select blocks that are at least 75% within the ROI defined by the mask by specifying the 'InclusionThreshold' name-value pair argument. By default, selectBlockLocations selects blocks from the finest resolution level of the big image.

t = 0.75;
blockSize = [256 256];
blockSet = selectBlockLocations(bim,"BlockSize",blockSize, ...
    "Masks",bmask,"InclusionThreshold",t);

Create a bigimageDatastore that reads four blocks at a time from the locations specified by the blockLocationSet.

bimds = bigimageDatastore(bim,"BlockLocationSet",blockSet,"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',blockSize,'InclusionThreshold',t)

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

Create a bigimage using 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 entire bigimage at the finest resolution level.

bshow = bigimageshow(bim);

Specify four [x y] block locations from the finest level. The first two blocks overlap in the vertical direction. The second two blocks are adjacent horizontally.

xyLocations = [ ...
    2800 1300; ...
    2800 1400; ...
    1500 2400; ...
    1800 2400];
blockSize = [300,300];

All blocks are from the same image. Specify the image number as 1 for all blocks.

imageNumber = [1 1 1 1]';

Create a blockLocationSet object that stores block locations.

locationSet = blockLocationSet(imageNumber,xyLocations,blockSize);

Create a bigimageDatastore object that reads blocks from big image bim at locations specified by the blockLocationSet object.

bimds = bigimageDatastore(bim,'BlockLocationSet',locationSet);

Read two blocks at a time from the datastore and display them in a montage.

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

Compatibility Considerations

expand all

References

[1] Bejnordi, Babak Ehteshami, Mitko Veta, Paul Johannes van Diest, Bram van Ginneken, Nico Karssemeijer, Geert Litjens, Jeroen A. W. M. van der Laak, et al. “Diagnostic Assessment of Deep Learning Algorithms for Detection of Lymph Node Metastases in Women With Breast Cancer.” JAMA 318, no. 22 (December 12, 2017): 2199–2210. https://doi.org/10.1001/jama.2017.14585.

Introduced in R2019b