Main Content

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

    Description

    example

    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

    expand all

    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

    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.

    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.

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

    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.

    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.

    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.

    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

    This property is read-only.

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

    Object Functions

    combineCombine data from multiple datastores
    countEachLabelCounts number of pixel labels for each class
    hasdataReturns true if more data is available in blockedImageDatastore
    numpartitionsNumber of datastore partitions
    partitionReturn partitioned part of blockedImageDatastore
    previewPreview subset of data in datastore
    readRead data and metadata from blockedImageDatastore
    readallRead all data from the blockedImageDatastore
    resetReset datastore to initial state
    shuffleShuffle data in datastore
    subsetCreate subset of datastore or file-set
    transformTransform datastore

    Examples

    collapse all

    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 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 axes object contains an object of type image.

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

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

    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 axes object contains an object of type image.

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

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

    Introduced in R2021a