Main Content


Show mask overlay at specified inclusion threshold

Since R2019b



showmask(b,mask) displays the mask, mask, as an overlay on the blocked image displayed in the bigimageshow object, b. The overlay shows the blocks that the blockedImage apply object function processes with the specified mask. mask is a 2-D blocked image object the same size as the displayed image. If mask has multiple resolution levels, bigimageshow uses the finest level.

  • bigimageshow displays blocks of the mask that exceed a minimum percentage of nonzero pixels (by default, 50%) with a green tint. These blocks are considered regions of interest and would be selected for processing by the apply object function of the blockedImage object.

  • bigimageshow displays blocks of the mask below the minimum percentage of nonzero pixels with a red tint. These blocks are considered background and would not be processed by the apply object function.

showmask(b,mask,level) overlays a mask on a bigimageshow object, b, at the specified resolution level of the blocked image data.

showmask(___,Name,Value) modifies the appearance of the mask blocks by using name-value pair arguments.


collapse all

Create a blocked image from the sample image tumor_091R.tif. This sample image is a training image of a lymph node containing tumor tissue from the CAMELYON16 data set. The image has been modified to have three coarse resolution levels, and has been adjusted to enforce a consistent aspect ratio and to register features at each level.

bim = blockedImage("tumor_091R.tif");

Display the entire blocked image at the finest resolution level, including a grid of the block boundaries.

bshow = bigimageshow(bim,ResolutionLevel="fine", ...

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

Create a mask at the coarsest resolution level.

First create a single-resolution image of the coarsest resolution level. By default, the gather function gets data from the coarsest resolution level.

imcoarse = gather(bim);

Convert the coarse image to grayscale.

graycoarse = im2gray(imcoarse);

Binarize the grayscale image. In the binarized image, the object of interest is black and the background is white.

bwcoarse = imbinarize(graycoarse);

Take the complement of the binarized image. The resulting mask follows the convention in which the object of interest is white and the background is black.

mask = imcomplement(bwcoarse);

Create a blocked image containing the mask.

Use the same spatial referencing as the original blocked image. Determine the coarsest resolution level and capture the spatial referencing information of the blocked image at the first two dimensions at that level.

coarsestLevel = bim.NumLevels;
originalWorldStartCoarsest = bim.WorldStart(coarsestLevel,1:2);
originalWorldEndCoarsest = bim.WorldEnd(coarsestLevel,1:2);

Create the blocked image for the mask.

bmask = blockedImage(mask,WorldStart=originalWorldStartCoarsest, ...

Display the mask image.


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

Overlay the mask on the display of the original blocked image using the showmask function. To highlight all blocks that contain at least one nonzero mask pixel, specify an inclusion threshold of 0.


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

Input Arguments

collapse all

bigimageshow object displaying blocked image data, specified as a bigimageshow object. The CData property of the bigimageshow object specifies the blocked image data that is being displayed.

Mask, specified as a single-resolution blockedImage object with a ClassUnderlying property value of logical. The spatial extents of the mask must be the same as the blocked image data at the displayed resolution level.

Resolution level at which to display the bocked image data, specified as a positive integer.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: showmask(b,mask,"InclusionThreshold",0.4)

Mask transparency, specified as a scalar value in the range [0, 1]. A value of 1 means the mask is completely opaque and a value of 0 means the mask is completely transparent.

Block size used with the apply function, specified as a 1-by-2 vector of positive integers of the form [numrows numcols]. The default value is equal to the BlockSize property of the blockedimageobject in b.

Inclusion threshold, specified as a number in the range [0, 1]. The inclusion threshold indicates the minimum fraction of nonzero pixels in a mask block required to consider the mask block as a region of interest.

  • When the inclusion threshold is 0, the showmask function displays a mask block when at least one pixel in the mask block is nonzero.

  • When the inclusion threshold is 1, the showmask function displays a mask block only when all pixels in the mask block are nonzero.


  • When you call showmask for the first time, bigimageshow calculates the ratio of nonzero to zero mask pixels for each block at the finest level of the displayed blockedImage. This calculation takes some time to complete, so there can be some delay displaying the mask. When you make subsequent calls to showmask, the function reuses the computed inclusion values and updates the displayed mask more quickly.

Version History

Introduced in R2019b