Main Content

readRelative

Read neighboring block from bigimageDatastore using relative position

Description

example

data = readRelative(bigds,sourceInfo,blockOffset) returns the block from big image datastore bigds that neighbors the source block sourceInfo with offset blockOffset.

[data,info] = readRelative(bigds,sourceInfo,blockOffset) 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);

Read the first block from the datastore.

[b,binfo] = read(bimds);
b = b{1};

Read the neighboring blocks to the left and right of the block. The left neighboring block is empty because the block is out of the bounds of bim.

bLeft = readRelative(bimds,binfo,[0 -1]);
bRight = readRelative(bimds,binfo,[0 1]);

Display the blocks as a montage. The left neighboring block appears black because it is empty.

montage({bLeft,b,bRight},'Size',[1 3],'BorderSize',5,'BackgroundColor','b')

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

Input Arguments

collapse all

Big image datastore, specified as a bigimageDatastore object.

Information about source block, specified as a struct containing at least these fields. The value of info returned by read is a valid input for sourceInfo.

Field NameDescription
LevelResolution level of the data, specified as a positive integers.
ImageNumberIndex of the big image providing the data, specified as a positive integer.
BlockStartWorld(x,y) world coordinates of the top-left corner of the data, specified as a 1-by-2 numeric vector. The coordinates correspond to a position on the boundary of the block, not the center of the top-left pixel.

Block offset, specified as a 1-by-2 vector of integers in units of blocks. The two elements specify the vertical and horizontal offset from the source block. respectively.

Output Arguments

collapse all

Output data, returned as a numeric array. If the requested block is outside the bounds of the source image, then readRelative returns an empty block, []

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.

Tips

  • readRelative ignores masks.

  • readRelative respects the PadMethod and BorderSize properties of the big image datastore.

  • If the requested block is incomplete and bigds.IncompleteBlocks has a value of 'exclude', then readRelative returns an empty block

Introduced in R2019b