readRelative

(To be removed) Read neighboring block from bigimageDatastore using relative position

The readRelative function of the bigimageDatastore object will be removed in a future release. Use the getBlock function of the blockedImage object instead. For more information, see Version History.

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.

example

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

Examples

collapse all

Read Neighboring Big Image Blocks

Open Live Script

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 object. The axes object contains an object of type image.

Input Arguments

collapse all

`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

collapse all

`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

Version History

Introduced in R2019b

expand all

R2024b: Warns

The readRelative 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. Use the getBlock function of the blockedImage object instead. The getBlock function does not support reading neighboring blocks outside the bounds of the image.

To update your code, first create a blockedImage object to read your image data, then create a blockedImageDatastore to manage blocks of the data. Then, follow these steps to read a neighboring block using a relative position:

Read a block and return the block metadata from the blockedImageDatastore using the read function.
Get the subscripts and resolution level by querying the Blocksub and Level properties of the block metadata structure, respectively.
Get the subscripts of the neighboring block by adding the relative offset of the neighboring block. If the block of data is an RGB image, then specify the offset as a 3-element vector with a value of 0 for the last element.
Call the getBlock function, specifying the blocked image and the subscripts of the neighboring block. If the resolution level is a value other than 1, also specify the resolution level by using the Level name-value argument.

Discouraged Usage Recommended Replacement

Discouraged Usage	Recommended Replacement
This example reads the neighboring block to the right of a specified block from a `bigimageDatastore` object. bigIm = bigimage("tumor_091R.tif"); bigImds = bigimageDatastore(bigIm); [block,info] = read(bigDS); blockRightOffset = [0 1]; blockRight = readRelative(bigDS,info,blockRightOffset);	Here is equivalent code that reads the neighboring block to the right of a specified block using a `blockedImage` object. blockedIm = blockedImage("tumor_091R.tif"); blockedDS = blockedImageDatastore(blockedIm); [block,info] = read(blockedDS); blockSub = info.BlockSub; blockRightOffset = [0 1 0]; blockRightSub = blockSub + blockRightOffset; blockRight = getBlock(blockedIm,blockRightSub);
This example reads the neighboring block at resolution level `2`. bigIm = bigimage("tumor_091R.tif"); level = 2; bigDS = bigimageDatastore(bigIm,level); [block,info] = read(bigDS); blockRightOffset = [0 1]; blockRight = readRelative(bigDS,info,blockRightOffset);	Here is equivalent code using a `blockedImage` object. blockedIm = blockedImage("tumor_091R.tif"); level = 2; blockedDS = blockedImageDatastore(blockedIm); [block,info] = read(blockedDS); blockSub = info.BlockSub; blockRightOffset = [0 1 0]; blockRightSub = blockSub + blockRightOffset; blockRight = getBlock(blockedIm,blockRightSub,Level=level);

This example reads the neighboring block to the right of a specified block from a bigimageDatastore object.

bigIm = bigimage("tumor_091R.tif");
bigImds = bigimageDatastore(bigIm);
[block,info] = read(bigDS);
blockRightOffset = [0 1];
blockRight = readRelative(bigDS,info,blockRightOffset);

Here is equivalent code that reads the neighboring block to the right of a specified block using a blockedImage object.

blockedIm = blockedImage("tumor_091R.tif");
blockedDS = blockedImageDatastore(blockedIm);
[block,info] = read(blockedDS);
blockSub = info.BlockSub;
blockRightOffset = [0 1 0];
blockRightSub = blockSub + blockRightOffset;
blockRight = getBlock(blockedIm,blockRightSub);

This example reads the neighboring block at resolution level 2.

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

Here is equivalent code using a blockedImage object.

blockedIm = blockedImage("tumor_091R.tif");
level = 2;
blockedDS = blockedImageDatastore(blockedIm);
[block,info] = read(blockedDS);
blockSub = info.BlockSub;
blockRightOffset = [0 1 0];
blockRightSub = blockSub + blockRightOffset;
blockRight = getBlock(blockedIm,blockRightSub,Level=level);

R2021a: `readRelative` function is 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.

readRelative

Syntax

Description

Examples

Read Neighboring Big Image Blocks

Input Arguments

bigds — Big image datastore bigimageDatastore object

sourceInfo — Information about source block struct

blockOffset — Block offset 1-by-2 vector of integers

Output Arguments

data — Output data numeric array

info — Information about output data struct

Tips

Version History

R2024b: Warns

R2023b: To be removed

R2021a: readRelative function is not recommended

See Also

`bigds` — Big image datastore
`bigimageDatastore` object

`sourceInfo` — Information about source block
struct

`blockOffset` — Block offset
1-by-2 vector of integers

`data` — Output data
numeric array

`info` — Information about output data
struct

R2021a: `readRelative` function is not recommended