bigimageshow

Display 2-D blockedImage object

Since R2019b

Description

A bigimageshow object displays data from a blockedImage object. The bigimageshow object progressively loads image data based on image extents and screen resolution.

Creation

Syntax

bigimageshow(bim)

bigimageshow(ax,bim)

b = bigimageshow(___)

b = bigimageshow(___,Name=Value)

Description

bigimageshow(bim) displays the 2-D blocked image bim.

For categorical data, bigimageshow sets the axis colormap to parula. For numeric data, gray is the default colormap.

bigimageshow(ax,bim) displays the blocked image, bim, in the axes specified by ax.

b = bigimageshow(___) returns the bigimageshow object b. Use b to modify the display settings after you display the blocked image.

b = bigimageshow(___,Name=Value) sets initial display properties using name-value arguments. You can specify multiple name-value arguments.

For example, bigimageshow(bim,GridVisible="on",GridLineStyle=":") displays the blocked image, bim, and overlays dotted grid lines.

Input Arguments

bim — Blocked image

blockedImage object

Blocked image, specified as a blockedImage object.

ax — Parent axes

axes object

Parent axes of bigimageshow object, specified as an axes object.

Properties

Parent — Parent axes of bigimageshow object

gca (default) | axes object

Parent axes of the bigimageshow object, specified as an axes object. If you do not specify a parent, bigimageshow uses the handle to the current figure, gca. If a figure does not exist, bigimageshow creates a new figure.

CData — 2-D blockedImage object to display

blockedImage object

2-D blockedImage object to display, specified as a blockedImage object.

CDataMapping — Color data mapping method

"direct" (default) | "scaled"

Color data mapping method, specified as "direct" or "scaled". Use this property to control the mapping of color data values in CData into the colormap. CData must be a vector or a matrix defining indexed colors. This property has no effect if CData is a 3-D array defining RGB colors.

The methods have these effects:

• "direct" — Interpret the values as indices into the current colormap. Values with a decimal portion are fixed to the nearest lower integer.

  • If the values are of type double or single, values of 1 or less map to the first color in the colormap. Values equal to or greater than the length of the colormap map to the last color in the colormap.

  • If the values are of type uint8, uint16, uint32, uint64, int8, int16, int32, or int64, values of 0 or less map to the first color in the colormap. Values equal to or greater than the length of the colormap map to the last color in the colormap (or up to the range limits of the type).

  • If the values are of type logical, values of 0 map to the first color in the colormap and values of 1 map to the second color in the colormap.

• "scaled" — Scale the values to range between the minimum and maximum color limits. The CLim property of the axes contains the color limits.

AlphaData — Transparency data

1 (default) | numeric scalar | blockedImage object

Transparency data, specified in one of these forms:

• Numeric scalar — Use a consistent transparency across the entire image.

• 2-D blockedImage object — Transparency data must have the same rows and columns extent as the CData 2-D blockedImage object. The blocked image can have multiple resolution levels, in which case, bigimageshow selects the level closest to the current ResolutionLevel for display.

The AlphaDataMapping property controls how MATLAB^® interprets the alpha data transparency values.

Example: 0.5

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

AlphaDataMapping — Interpretation of AlphaData values

"none" (default) | "scaled" | "direct"

Interpretation of AlphaData values, specified as one of these values:

• "none" — Interpret the values as transparency values. A value of 1 or greater is completely opaque, a value of 0 or less is completely transparent, and a value between 0 and 1 is semitransparent.

• "scaled" — Map the values into the figure’s alphamap. The minimum and maximum alpha limits of the axes determine the alpha data values that map to the first and last elements in the alphamap, respectively. For example, if the alpha limits are [3 5], alpha data values less than or equal to 3 map to the first element in the alphamap. Alpha data values greater than or equal to 5 map to the last element in the alphamap. The ALim property of the axes contains the alpha limits. The Alphamap property of the figure contains the alphamap.

• "direct" — Interpret the values as indices into the figure’s alphamap. Values with a decimal portion are fixed to the nearest lower integer:

  • If the values are of type double or single, values of 1 or less map to the first element in the alphamap. Values equal to or greater than the length of the alphamap map to the last element in the alphamap.

  • If the values are of type integer, then values of 0 or less map to the first element in the alphamap. Values equal to or greater than the length of the alphamap map to the last element in the alphamap (or up to the range limits of the type). The integer types are uint8, uint16, uint32, uint64, int8, int16, int32, and int64.

  • If the values are of type logical, values of 0 map to the first element in the alphamap and values of 1 map to the second element in the alphamap.

ResolutionLevel — Resolution level

positive integer | "fine" | "coarse"

Resolution level of the 2-D blockedImage object to display, specified as a positive integer that identifies a resolution level of the 2-D blockedImage object in the CData property. Resolution level can also be specified as "fine" or "coarse" corresponding to these two limits. The default value is computed based on available screen space and resolution.

ResolutionLevelMode — Selection mode for resolution level

"auto" (default) | "manual"

Selection mode for resolution level, specified as one of these values:

• "auto" — Automatically select resolution level based on parent axes and available screen size.

• "manual" — Manually specify resolution level by setting the ResolutionLevel property.

GridVisible — Grid visibility

"off" (default) | "on"

Grid visibility, specified as "off" or "on". bigimageshow spaces the grid in world units to include as many pixels as specified by CData.BlockSize at the current GridResolutionLevel.

GridLevel — Resolution level of blocked image at which to show grid

positive integer | "fine" | "coarse"

Resolution level of blocked image at which to show grid, specified as one of these values:

• positive integer — Display the grid specified as a numeric scalar that identifies a resolution level of the 2-D blockedImage object in CData property. Value is between 1 and the value of the NumLevels property of the blocked image in the bigimageshow CData property.

• "fine" — Display the grid at the finest resolution level.

• "coarse" — Display the grid at the coarsest resolution level.

By default, GridLevel has the same value as ResolutionLevel property.

GridLevelMode — Selection mode for grid level

"auto" (default) | "manual"

Selection mode for grid level, specified as one of these values:

• "auto" — Select the grid resolution level to match the image data resolution level ResolutionLevel.

• "manual" — Manually specify the grid resolution level by setting the GridLevel property.

GridColor — Grid line color

"blue" (default) | RGB triplet | hexadecimal color code | color name | short color name

Grid line color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name. To display the grid lines, set the GridVisible property to "on".

For a custom color, specify an RGB triplet or a hexadecimal color code.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].

• A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
"red"	"r"	[1 0 0]	"#FF0000"
"green"	"g"	[0 1 0]	"#00FF00"
"blue"	"b"	[0 0 1]	"#0000FF"
"cyan"	"c"	[0 1 1]	"#00FFFF"
"magenta"	"m"	[1 0 1]	"#FF00FF"
"yellow"	"y"	[1 1 0]	"#FFFF00"
"black"	"k"	[0 0 0]	"#000000"
"white"	"w"	[1 1 1]	"#FFFFFF"

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	"#0072BD"
[0.8500 0.3250 0.0980]	"#D95319"
[0.9290 0.6940 0.1250]	"#EDB120"
[0.4940 0.1840 0.5560]	"#7E2F8E"
[0.4660 0.6740 0.1880]	"#77AC30"
[0.3010 0.7450 0.9330]	"#4DBEEE"
[0.6350 0.0780 0.1840]	"#A2142F"

Example: GridColor = [1 0 0]

Example: GridColor = "r"

Example: GridColor = "red"

Example: GridColor = "#FF0000"

GridAlpha — Grid line transparency

0.8 (default) | number in the range [0, 1]

Grid line transparency, specified as a number in the range [0, 1]. A value of 1 means completely opaque and a value of 0 means completely transparent. To display the grid lines, set the GridVisible property to "on".

GridLineWidth — Grid line width

1 (default) | positive number

Grid line width, specified as a positive number, measured in points. To display the grid lines, set the GridVisible property to "on".

GridLineStyle — Grid line style

"-" (default) | "--" | ":" | "-."

Grid line style, specified as one of the line styles in this table.

Line Style	Description	Resulting Line
"-"	Solid line
"--"	Dashed line
":"	Dotted line
"-."	Dash-dot line

To display the grid lines, set the GridVisible property to "on".

Interpolation — Interpolation method

"linear" (default) | "nearest"

Interpolation method used to resample pixels, specified as "linear" for bilinear interpolation, or "nearest" for nearest neighbor interpolation.

For categorical data, bigimageshow supports only nearest neighbor interpolation. For logical data, the default value is "nearest".

On Windows systems with a software version of OpenGL, the only supported interpolation option is "nearest".

Visible — Control image visibility

"on" (default) | "off"

Control image visibility, specified as one of these values:

• "on" — Display the bigimageshow object.

• "off" — Hide the object without deleting it. You still can access the properties of an invisible object.

Object Functions

showmask	Show mask overlay at specified inclusion threshold
hidemask	Hide mask overlay in bigimageshow object
showlabels	Display label overlay on bigimageshow object
hidelabels	Hide label overlay on bigimageshow object

Examples

Visualize 2-D Blocked Image at Different Resolution Levels

This example uses a modified version of a training image of a lymph node containing tumor tissue (tumor_091.tif) from the CAMELYON16 data set. The modified image has three coarse resolution levels and has been adjusted to enforce a consistent aspect ratio and to register features at each level.

Create a blocked image from the sample image.

bim = blockedImage('tumor_091R.tif');

Display the blocked image.

h = bigimageshow(bim);

Zoom in on a region in the image.

xlim([2100, 2600])
ylim([1800 2300])

To view the image at the three resolution levels, specify a new value for the ResolutionLevel property. As you view each resolution level, note that the axis limits remain the same, but bigimageshow ensures that the images from other levels are correctly sized. When you set ResolutionLevel , the ResolutionLevelMode value changes to 'manual' automatically.

h.ResolutionLevel = 3;
pause(1);
h.ResolutionLevel = 2;
pause(1);
h.ResolutionLevel = 1;
pause(1);

Visualize Blocked Image with Grid Lines Indicating Blocks

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','BlockSize', [128 128]);

Display the blocked image with bigimageshow. Specify that you want the grid to be visible at the finest resolution level (level 1). Also specify the color, width, and transparency of the grid lines.

 h = bigimageshow(bim,...
      'GridVisible','on','GridLevel',1,...
      'GridLineWidth', 2,'GridColor','k','GridAlpha',0.3);

Validate Mask using Alpha Layer

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

Create a coarse mask using the blockedImage apply object function.

bmask = apply(bim, @(bs)im2gray(bs.Data)<120, "Level", 3);

Overlay the mask as an alpha layer.

ha1 = subplot(1,2,1);
h = bigimageshow(bim);
h.AlphaData = bmask;
h.AlphaDataMapping = 'direct';
alphamap([0.4 1])
h.Parent.Color = 'r';

Independently visualize the mask.

ha2 = subplot(1,2,2);
bigimageshow(bmask);
linkaxes([ha1, ha2]);
%

Improve Mask Creation Using InclusionThreshold and BlockSize

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

Create a mask using the coarsest resolution level of the blocked image.

bmask = apply(bim,@(im)im2gray(im.Data)<120,Level=3);

Display the blocked image with the mask.

h = bigimageshow(bim);
showmask(h,bmask);

Experiment with different inclusion thresholds to get a better fit of the mask over the stained area. By default, the inclusion threshold is 0.5.

showmask(h,bmask,InclusionThreshold=0.2);
showmask(h,bmask,InclusionThreshold=0);
showmask(h,bmask,InclusionThreshold=0.06);

Experiment with different block sizes, in conjunction with different inclusion thresholds, to get a better fit of the mask over the stained area. By default, the block size for the coarsest resolution level is 625-by-670.

showmask(h,bmask,InclusionThreshold=0.06,BlockSize=[256 256]);
showmask(h,bmask,InclusionThreshold=0.14,BlockSize=[256 256]);

When you are satisfied with the mask, use it to segment the lymph node.

bls = selectBlockLocations(bim,BlockSize=[256 256], ...
    Mask=bmask,InclusionThreshold=0.14);
bregion = apply(bim, @(bs)bs.Data,BlockLocationSet=bls);
figure
bigimageshow(bregion);
%

Display Blocked Image with Label Overlay

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

Create a label image at a coarse resolution level.

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

cim = gather(bim);

Convert the image to grayscale. Use multithresh to calculate three threshold values to convert the image into a four-level image.

cgim = im2gray(cim);
numClasses = 4;
thresh = multithresh(cgim,numClasses-1);

Segment the image into four regions using imquantize, specifying the threshold levels returned by multithresh.

labels = imquantize(cgim,thresh);
imagesc(labels)
axis square
title("Coarse Label Image")

Convert the labels image back to a blockedImage object, using the same spatial referencing as the original image at the coarsest resolution level.

blabels = blockedImage(labels,WorldStart=bim.WorldStart(3,1:2),...
    WorldEnd=bim.WorldEnd(3,1:2));

Display the original blocked image.

figure
hB = bigimageshow(bim);

Overlay the labels image on the original blocked image.

showlabels(hB,blabels)

More About

Events

To receive notification from the bigimageshow object when certain events happen, set up listeners for these events. You can specify a callback function that executes when one of these events occurs. When the bigimageshow object notifies your application through the listener, it returns data specific to the event. Look at the event class for the specific event to see what is returned.

Event Name	Trigger	Event Data	Event Attributes
DataReadStarted (since R2023a)	The bigimageshow view is changing. Additional image data is being read from the blockedImage	event.EventData	NotifyAccess: private ListenAccess: public
DataReadFinished (since R2023a)	The bigimageshow view has stopped changing. New image data is finished being read and rendered.	event.EventData	NotifyAccess: private ListenAccess: public

For example, this code adds listeners that change the title of the parent figure. The title displays "Reading image data" while you zoom. The title displays "Resolution level: " with the current resolution level after you complete zooming.

bim = blockedImage("tumor_091R.tif");
h = bigimageshow(bim);
listenerStarted = addlistener(h,"DataReadStarted", ...
    @(h,~)title("Reading image data",Parent=h.Parent));
listenerFinished = addlistener(h,"DataReadFinished", ...
    @(h,~)title("Resolution level: "+num2str(h.ResolutionLevel),Parent=h.Parent));

References

[1] Bejnordi, Babak Ehteshami, Mitko Veta, Paul Johannes van Diest, Bram van Ginneken, Nico Karssemeijer, Geert Litjens, Jeroen A. W. M. van der Laak, et al. “Diagnostic Assessment of Deep Learning Algorithms for Detection of Lymph Node Metastases in Women With Breast Cancer.” JAMA 318, no. 22 (December 12, 2017): 2199–2210. https://doi.org/10.1001/jama.2017.14585.

[2] Grand Challenge. https://camelyon17.grand-challenge.org/Data/.

Version History

Introduced in R2019b

R2023a: Support for events

The bigimageshow function now supports DataReadStarted and DataReadFinished events.

R2021a: Support for blocked images

The bigimageshow function now accepts blockedImage objects as input for display.