readRelative

Read neighboring block from bigimageDatastore using relative position

Syntax

data = readRelative(bigds,sourceInfo,blockOffset)

[data,info] = readRelative(bigds,sourceInfo,blockOffset)

Description

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

Read Neighboring Big Image Blocks

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

Input Arguments

bigds — Big image datastore

bigimageDatastore object

Big image datastore, specified as a bigimageDatastore object.

sourceInfo — Information about source block

struct

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

blockOffset — Block offset

1-by-2 vector of integers

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

data — Output data

numeric array

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

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.

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