Main Content

read

(To be removed) Read data from bigimageDatastore

Since R2019b

The read function of the bigimageDatastore object will be removed in a future release. Use the read function associated with the blockedImageDatastore object instead. For more information, see Compatibility Considerations.

Description

data = read(bigds) returns a batch of data from a big image datastore, bigds. Subsequent calls to the read function continue reading from the endpoint of the previous call.

example

[data,info] = read(bigds) also returns information about the extracted data, including metadata, in info.

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

Create a bigimageDatastore that manages blocks of the big image at the finest resolution level.

bimds = bigimageDatastore(bim,1)
bimds = 
  bigimageDatastore with properties:

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

Change the 'ReadSize' property of the datastore to 3.

bimds.ReadSize = 3;

Read one batch of image data from the datastore.

[data,info] = read(bimds);

Display the returned image data in a montage with a black border around each image. The montage shows that the datastore reads blocks of the big image in row-major order.

montage(data,'Size',[1 3],"BorderSize",10)

Display the information about the returned data.

info
info = struct with fields:
              Level: [1 1 1]
        ImageNumber: [1 1 1]
    BlockStartWorld: [3x2 double]
      BlockEndWorld: [3x2 double]
     DataStartWorld: [3x2 double]
       DataEndWorld: [3x2 double]

Inspect the (x,y) coordinates of the center of the top-left pixel of each returned block of data.

info.BlockStartWorld
ans = 3×2

           1           1
        1025           1
        2049           1

Input Arguments

collapse all

Big image datastore, specified as a bigimageDatastore object.

  • The datastore contains one or more big images, Images, each with Channels number of channels.

  • The datastore reads blocks from each big image at specified resolution levels, Levels.

  • The datastore specifies the number of blocks to read in each batch, ReadSize.

  • The datastore specifies the m-by-n pixel size of blocks to read, BlockSize.

Output Arguments

collapse all

Output data, returned as a cell array with ReadSize elements. Each cell contains an m-by-n-by-Channels numeric array.

Information about output data, returned as a struct containing these fields.

Field NameDescription
LevelResolution level of the data, specified as a 1-by-ReadSize vector of positive integers.
ImageNumberIndex of the big image providing the data, specified as a 1-by-ReadSize vector of positive integers.
BlockStartWorld(x,y) coordinates of the center of the top-left pixel of the data, excluding padding, specified as a ReadSize-by-2 numeric vector. Values are in world-coordinates.
BlockEndWorld(x,y) coordinates of the center of the bottom-right pixel of the data, excluding padding, specified as a ReadSize-by-2 numeric vector. Values are in world-coordinates.
DataStartWorld(x,y) coordinates of the center of the top-left pixel of the data, including padding, specified as a ReadSize-by-2 numeric vector. Values are in world-coordinates.
DataEndWorld(x,y) coordinates of the center of the bottom-right pixel of the data, including padding, specified as a ReadSize-by-2 numeric vector. Values are in world-coordinates.

Version History

Introduced in R2019b

expand all

R2023b: read will be removed

The bigimageDatastore object and this function will be removed in a future release. Use the read function of the blockedImageDatastore object instead.

To update your code, first create a blockedImage object to read your image data. Then, follow these steps to create a blockedImageDatastore object and read a block of data:

  • If you want to read data at a resolution level other than 1, then create a block location set using the selectBlockLocations function. Specify the level using the Level name-value argument.

  • Create a blockedImageDatastore, specifying the blockedImage object. If you want to read data at a resolution level other than 1, then specify the block location set using the BlockLocationSet name-value argument.

  • In the call to the read function, replace the input argument with the blockedImageDatastore object.

If you return block metadata using the info argument, then some fields of the metadata structure differ.

Discouraged UsageRecommended Replacement

This example reads a block from a bigimageDatastore object.

bigIm = bigimage("tumor_091R.tif");
bigDS = bigimageDatastore(bigIm);
[block,info] = read(bigDS);

Here is equivalent code that reads a block from a blockedImageDatastore object.

blockedIm = blockedImage("tumor_091R.tif");
blockedDS = blockedImageDatastore(blockedIm);
[block,info] = read(blockedDS);

This example reads a block at resolution level 2.

bigIm = bigimage("tumor_091R.tif");
level = 2;
bigDS = bigimageDatastore(bigIm,level);
[block,info] = read(bigDS);

Here is equivalent code using a blockedImageDatastore object.

blockedIm = blockedImage("tumor_091R.tif");
level = 2;
bls = selectBlockLocations(blockedIm,Levels=level);
blockedDS = blockedImageDatastore(blockedIm,BlockLocationSet=bls);
[block,info] = read(blockedDS);