getRegion

(To be removed) Read arbitrary region of bigimage object

The getRegion function of the bigimage object will be removed in a future release. Use the getRegion function associated with the blockedImage object instead. For more information, see Version History.

Syntax

data = getRegion(bigimg,level,regionStartWorld,regionEndWorld)

Description

data = getRegion(bigimg,level,regionStartWorld,regionEndWorld) reads the big image data in bigimg at the specified resolution level. The function returns all pixels whose extents touch or lie within the bounds of the rectangular region specified by regionStartWorld and regionEndWorld, inclusive.

example

Examples

collapse all

Get Region of Big Image at Different Resolution Levels

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

Display the entire bigimage at the finest resolution level.

bshow = bigimageshow(bim);

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

Define a rectangular region by specifying the starting and ending coordinates in the horizontal and vertical direction relative to the finest resolution level.

xyStart = [2100,1800];
xyEnd = [2600,2300];

Get the region of the bigimage at each resolution level.

imL1 = getRegion(bim,1,xyStart,xyEnd);
imL2 = getRegion(bim,2,xyStart,xyEnd);
imL3 = getRegion(bim,3,xyStart,xyEnd);

Display the three regions in a montage. The finest resolution level is on the left and the coarsest resolution level is on the right.

montage({imL1,imL2,imL3},'Size',[1 3], ...
    'BorderSize',5,'BackgroundColor','w');

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

Input Arguments

collapse all

`bigimg` — Big image
`bigimage` object

Big image, specified as a bigimage object.

`level` — Resolution level
positive integer

Resolution level, specified as a positive integer that is less than or equal to the number of resolution levels of bigimg.

`regionStartWorld` — Top-left coordinates of rectangular region
1-by-2 numeric vector

Top-left coordinates of the rectangular region to read, specified as a 1-by-2 numeric vector of the form [x y]. The location is specified in world coordinates, which are the pixel locations relative to the highest resolution level.

`regionEndWorld` — Bottom-right coordinates of rectangular region
1-by-2 numeric vector

Bottom-right coordinates of the rectangular region to read, specified as a 1-by-2 numeric vector of the form [x y]. The location is specified in world coordinates, which are the pixel locations relative to the highest resolution level.

Output Arguments

collapse all

`data` — Pixel data
numeric array

Pixel data, returned as a numeric array of the same data type as the big image, bigimg.ClassUnderlying.

Version History

Introduced in R2019b

expand all

R2024b: Warns

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

R2023b: To be removed

The bigimage object and this function will be removed in a future release. Use the getRegion function of the blockedImage object instead.

To update your code, first create a blockedImage object to read your image data. Then, follow these steps:

Convert from (x, y) world coordinates to (row, column) world coordinates by switching the order of the two elements.
Convert the world coordinates to pixel subscripts using the world2sub function. If you want to get the region at a resolution level other than level 1, then specify that level by using the Level name-value argument.
Pass the blocked image and the pixel subscripts to the getRegion function. If you want to get the region at a resolution level other than level 1, then specify that level by using the Level name-value argument.

Discouraged Usage Recommended Replacement

Discouraged Usage	Recommended Replacement
This example uses the `getRegion` function with a `bigimage` object to get the image data in a region at the highest resolution level. filename = "tumor_091R.tif"; bim = bigimage(filename); xyStart = [2100 1800]; xyEnd = [2600 2300]; region = getRegion(bim,1,xyStart,xyEnd);	Here is equivalent code using a `blockedImage` object. filename = "tumor_091R.tif"; blockedIm = blockedImage(filename); xyStart = [2100 1800]; xyEnd = [2600 2300]; rcStart = flip(xyStart); rcEnd = flip(xyEnd); pixelStart = world2sub(blockedIm,rcStart); pixelEnd = world2sub(blockedIm,rcEnd); region = getRegion(blockedIm,pixelStart,pixelEnd);
This example repeats the operation at resolution level 2. lvl = 2; region = getRegion(bim,lvl,xyStart,xyEnd);	This example repeats the final operations at resolution level 2 by specifying the `Level` name-value argument. lvl = 2; pixelStart = world2sub(blockedIm,rcStart,Level=lvl); pixelEnd = world2sub(blockedIm,rcEnd,Level=lvl); region = getRegion(blockedIm,subBlock,Level=lvl);

This example uses the getRegion function with a bigimage object to get the image data in a region at the highest resolution level.

filename = "tumor_091R.tif";
bim = bigimage(filename);
xyStart = [2100 1800];
xyEnd = [2600 2300];
region = getRegion(bim,1,xyStart,xyEnd);

Here is equivalent code using a blockedImage object.

filename = "tumor_091R.tif";
blockedIm = blockedImage(filename);
xyStart = [2100 1800];
xyEnd = [2600 2300];
rcStart = flip(xyStart);
rcEnd = flip(xyEnd);
pixelStart = world2sub(blockedIm,rcStart);
pixelEnd = world2sub(blockedIm,rcEnd);
region = getRegion(blockedIm,pixelStart,pixelEnd);

This example repeats the operation at resolution level 2.

lvl = 2;
region = getRegion(bim,lvl,xyStart,xyEnd);

This example repeats the final operations at resolution level 2 by specifying the Level name-value argument.

lvl = 2;
pixelStart = world2sub(blockedIm,rcStart,Level=lvl);
pixelEnd = world2sub(blockedIm,rcEnd,Level=lvl);
region = getRegion(blockedIm,subBlock,Level=lvl);

R2021a: `getRegion` function is not recommended

The getRegion function of the bigimage object is not recommended. Use the getRegion function of the blockedImage object instead. 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.

getRegion

Syntax

Description

Examples

Get Region of Big Image at Different Resolution Levels

Input Arguments

bigimg — Big image bigimage object

level — Resolution level positive integer

regionStartWorld — Top-left coordinates of rectangular region 1-by-2 numeric vector

regionEndWorld — Bottom-right coordinates of rectangular region 1-by-2 numeric vector

Output Arguments

data — Pixel data numeric array

Version History

R2024b: Warns

R2023b: To be removed

R2021a: getRegion function is not recommended

See Also

`bigimg` — Big image
`bigimage` object

`level` — Resolution level
positive integer

`regionStartWorld` — Top-left coordinates of rectangular region
1-by-2 numeric vector

`regionEndWorld` — Bottom-right coordinates of rectangular region
1-by-2 numeric vector

`data` — Pixel data
numeric array

R2021a: `getRegion` function is not recommended