read

(Removed) Read data from bigimageDatastore

The read function of the bigimageDatastore object has been removed (since R2026a). Use the read function associated with the blockedImageDatastore object instead. For more information, see Version History.

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 Blocks from Big Image Datastore

Create a bigimage from the sample image "tumor_091R.tif".

bim = bigimage("tumor_091R.tif");

Create a bigimageDatastore object at resolution level 1. Specify a nondefault block size. Set the datastore to read four blocks at a time.

bimds = bigimageDatastore(bim,2,"BlockSize",[512 512],"ReadSize",4)

bimds = 
  bigimageDatastore with properties:

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

Read one batch of data from the datastore. Notice that the third block is a partial edge block and has a smaller size than interior blocks

blocks = read(bimds);

blocks=4×1 cell array
    {512x512x3 uint8}
    {512x512x3 uint8}
    {512x316x3 uint8}
    {512x512x3 uint8}

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.

Version History

Introduced in R2019b

R2026a: Removed

The read function has been removed. Use the read function of the blockedImageDatastore object instead.

Code Updates

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 Usage	Recommended 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);

R2024b: Warns

The read function issues a warning that it will be removed in a future release.

R2023b: To be removed

The bigimageDatastore object and this function will be removed in a future release.

R2021a: Not recommended

Starting in R2021a, the bigimageDatastore object and its object functions, which operate on data from bigimage objects, are no longer recommended. Instead, use the blockedImageDatastore object and its object functions, which operate on data from blockedImage objects. The blockedImage object offers several advantages including extension to N-D processing, a simpler interface, and custom support for reading and writing nonstandard image formats.