Main Content

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

    Description

    example

    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.

    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

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

    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.

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

    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.

    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, 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 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

    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)

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

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

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

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

    Version History

    Introduced in R2021a

    expand all