blockedImageDatastore

Datastore for use with blocks from blockedImage objects

Since R2021a

expand all in page

    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) sets writable properties using one or more name-value arguments. For example, blockedImageDatastore(images,ReadSize=8) returns eight blocks from the datastore in each call to the read function.

    Input Arguments

    expand all

    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.

    This argument sets the Images property.

    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.

    Name-Value Arguments

    expand all

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Example: bimds = blockedImageDatastore(images,ReadSize=8) returns eight blocks from the datastore in each call to the read function.

    Blocks to include in the datastore, specified as a blockLocationSet object. The object specifies which blocks to include from the blocked images. You can repeat or omit individual blocks.

    You can specify only one of the BlockLocationSet and BlockSize name-value arguments. When you specify the BlockLocationSet argument, the blockedImageDatastore function:

    • Sets the BlockLocationSet property as the blockLocationSet object.

    • Sets the BlockSize property as the block size of the blockLocationSet object.

    When you specify neither the BlockLocationSet nor the BlockSize input arguments, then the blockedImageDatastore uses the default value of the BlockLocationSet property. The default value is the blockLocationSet object returned by calling the selectBlockLocations function without specifying a block size.

    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 can specify only one of the BlockLocationSet and BlockSize name-value arguments. When you specify the BlockSize argument, the blockedImageDatastore function:

    When you specify neither the BlockLocationSet nor the BlockSize name-value arguments, then the blockedImageDatastore uses the default value of the BlockSize property. The default value is the block size of the first blocked image in Images at the finest resolution level.

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

    This argument sets the BorderSize property.

    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.

    This argument sets the PadMethod property.

    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 name-value argument.

    This argument sets the PadPartialBlocks 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 argument sets the ReadSize property.

    Properties

    expand all

    This property is read-only after object creation.

    Blocks to include in the datastore, returned as a blockLocationSet object. The object specifies which blocks to include from the blocked image Images.

    This property is read-only after object creation.

    Block size, returned 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.

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

    This property is read-only after object creation.

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

    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.

    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, returned 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 blocked image datastore
    numpartitionsNumber of datastore partitions
    partitionReturn partitioned part of blocked image datastore
    previewPreview subset of data in datastore
    readRead data and metadata from blocked image datastore
    readallRead all data from blocked image datastore
    resetReset datastore to initial state
    shuffleShuffle data in datastore
    subsetCreate subset of datastore or FileSet
    transformTransform datastore
    writeallWrite blocked image datastore to files

    Examples

    collapse all

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

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

    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.

    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.

    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.

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

    See Also

    | |