read

Read data from bigimageDatastore

Syntax

data = read(bigds)

[data,info] = read(bigds)

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.

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

Examples

Read Data from Big Image Datastore

Create a bigimage. This examples uses 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
    InclusionThreshold: []
                 Masks: [0x0 bigimage]
                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

bigds — Big image datastore

bigimageDatastore

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

data — Output data

cell array

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

info — Information about output data

struct

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

Field Name	Description
Level	Resolution level of the data, specified as a 1-by-ReadSize vector of positive integers.
ImageNumber	Index 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.