labelvolshow

(To be removed) Display labeled volume

labelvolshow will be removed in a future release. Use the viewer3d and volshow functions instead. For more information, see Version History.

Description

A labelvolshow object displays labeled volumetric data and enables you to modify the appearance of the display. You can embed the intensity volume with the labeled volume and display both volumes at once.

Creation

Syntax

labelvolshow(L)

labelvolshow(L,V)

labelvolshow(___,Name,Value)

h = labelvolshow(___)

Description

labelvolshow(L) displays 3-D labeled volume L in a figure.

labelvolshow(L,V) displays 3-D labeled volume L and 3-D intensity volume V in a figure. L and V must be the same size.

labelvolshow(___,Name,Value) uses one or more name-value pairs to set Properties that control visualization of the volumes. Enclose each property name in quotes.

Example: labelvolshow(L,V,"BackgroundColor","w","VolumeThreshold",0.2) displays 3-D labeled volume L and grayscale volume V in a figure with a white background color. All pixels of V that have a value less than 0.2 are fully transparent.

h = labelvolshow(___) returns a labelvolshow object, h, with properties that can be used to control visualization of the volumes. Use input arguments from any of the previous syntaxes.

Input Arguments

L — Labeled volume

3-D numeric array

Labeled volume, specified as a 3-D numeric array.

Data Types: single | double | int8 | int16 | int32 | uint8 | uint16 | uint32 | categorical

V — Intensity volume

3-D numeric array

Intensity volume, specified as a 3-D numeric array of the same size as the labeled volume, L.

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

Properties

BackgroundColor — Background color

[0.3 0.75 0.93] (default) | RGB triplet | color name | short color name

Background color, specified as an RGB triplet, a color name, or a short color name.

You can specify any color using an RGB triplet. An RGB triplet is a 3-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].

You can specify some common colors by name as a string scalar or character vector. This table lists the named color options and the equivalent RGB triplets.

Color Name	Short Name	RGB Triplet	Appearance
"red"	"r"	[1 0 0]
"green"	"g"	[0 1 0]
"blue"	"b"	[0 0 1]
"cyan"	"c"	[0 1 1]
"magenta"	"m"	[1 0 1]
"yellow"	"y"	[1 1 0]
"black"	"k"	[0 0 0]
"white"	"w"	[1 1 1]

Here are the RGB triplets for the default colors that MATLAB^® uses in many types of plots.

RGB Triplet	Appearance
[0 0.4470 0.7410]
[0.8500 0.3250 0.0980]
[0.9290 0.6940 0.1250]
[0.4940 0.1840 0.5560]
[0.4660 0.6740 0.1880]
[0.3010 0.7450 0.9330]
[0.6350 0.0780 0.1840]

Example: "BackgroundColor","r"

Example: "BackgroundColor","green"

Example: "BackgroundColor",[0 0.4470 0.7410]

CameraPosition — Location of camera

[4 4 2.5] (default) | 3-element vector

Location of the camera, or the viewpoint, specified as a 3-element vector of the form [x y z]. This vector defines the axes coordinates of the camera location, which is the point from which you view the axes. The camera is oriented along the view axis, which is a straight line that connects the camera position and the camera target. Changing the CameraPosition property changes the point from which you view the volume. For an illustration, see Camera Graphics Terminology. Interactively rotating the volume modifies the value of this property.

CameraUpVector — Vector defining upwards direction

[0 0 1] (default) | 3-element vector

Vector defining upwards direction, specified as a 3-element vector of the form [x y z]. By default, labelvolshow defines the z-axis as the up direction ([0 0 1]). For an illustration, see Camera Graphics Terminology. Interactively rotating the volume modifies the value of this property.

CameraTarget — Point used as camera target

[0 0 0] (default) | 3-element vector

Point used as the camera target, specified as a 3-element vector of the form [x y z]. The camera is oriented along the view axis, which is a straight line that connects the camera position and the camera target. For an illustration, see Camera Graphics Terminology.

CameraViewAngle — Field of view

15 (default) | numeric scalar

Field of view, specified as a scalar angle in the range [0, 180). The greater the angle, the larger the field of view. Also, with bigger angles, objects appear smaller in the scene. For an illustration, see Camera Graphics Terminology.

InteractionsEnabled — Volume is interactive

true (default) | false

Volume is interactive, specified as true (1) or false (0). When true (default), you can zoom in and out on the labeled volume using the mouse scroll wheel, and rotate the volume by clicking and dragging. Rotation and zoom are performed about the value specified by CameraTarget. When this value is false, you cannot interact with the volume.

LabelColor — Label colors

numLabels-by-3 numeric matrix

Label colors, specified as a numLabels-by-3 numeric matrix with values in the range [0, 1]. numLabels is the number of labels in the labeled volume. By default, labelvolshow specifies the label colors using a random colormap.

LabelOpacity — Label opacity

numLabels-by-1 numeric vector

Label opacity, specified as a numLabels-by-1 numeric vector with values in the range [0, 1]. numLabels is the number of labels in the labeled volume. By default, labels are opaque (1) for all labels except label 0. LabelOpacity is not supported when embedding volumes together.

LabelsPresent — Label values

numLabels-by-1 numeric vector

This property is read-only.

Label values, specified as a numLabels-by-1 numeric vector. numLabels is the number of labels in the labeled volume.

LabelVisibility — Label visibility

numLabels-by-1 logical vector

Label visibility, specified as a numLabels-by-1 logical vector. numLabels is the number of labels in the labeled volume. By default, all labels are visible (true) for all labels except label 0.

Parent — Parent of labelvolshow object

gcf (default) | uipanel | figure

Parent of the labelvolshow object, specified as a handle to a uipanel or figure. If you do not specify a parent, the parent of the labelvolshow object is gcf.

ScaleFactors — Scale factors used to rescale volume

[1 1 1] (default) | 1-by-3 vector of positive numbers

Scale factors used to rescale volumes, specified as a 1-by-3 vector of positive numbers. The values in the array correspond to the scale factor applied in the x-, y-, and z-direction.

ShowIntensityVolume — Display intensity volume

true | false

Display intensity volume, specified as true (1) or false (0). When the value is true, the function displays both the labeled volume and the intensity volume. When the value is false, the function only displays the labeled volume. The default is true when the labelvolshow object contains both a labeled volume and an intensity volume. The default is false when the object contains only a labeled volume.

VolumeOpacity — Volume opacity

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

Volume opacity, specified as a number in the range [0, 1]. This value defines the opacity of volume data when both labeled and intensity volumes are embedded together. All of the embedded volume intensities above the VolumeThreshold value have the opacity of VolumeOpacity.

VolumeThreshold — Threshold of volume intensities

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

Threshold of volume intensities, specified as a normalized number in the range [0, 1]. All of the volume intensities below this threshold value have an opacity of 0.

Object Functions

setVolume

(To be removed) Set new volume in labelvolshow object

Examples

View Labeled Volume With and Without Intensity Volume

Read a grayscale image of a brain MRI. The image is stored in the workspace variable vol.

load(fullfile(toolboxdir('images'),'imdata','BrainMRILabeled', ...
    'images','vol_001.mat'));

Read the corresponding labeled image into the workspace variable label.

load(fullfile(toolboxdir('images'),'imdata','BrainMRILabeled', ...
    'labels','label_001.mat'));

Customize the display panel.

ViewPnl = uipanel(figure,'Title','Labeled Volume');

View the labeled volume and the intensity volume.

h = labelvolshow(label,vol,'Parent',ViewPnl);

Hide the intensity volume. Only the labels appear.

h.ShowIntensityVolume = false;

View Labeled Volume and Change Color and Opacity

Read a grayscale volume of a brain MRI. The image is stored in the workspace variable vol.

load(fullfile(toolboxdir('images'),'imdata','BrainMRILabeled', ...
    'images','vol_001.mat'));

Read the corresponding labeled volume into the workspace variable label. The volume has three labels, excluding the background label 0.

load(fullfile(toolboxdir('images'),'imdata','BrainMRILabeled', ...
    'labels','label_001.mat'));

Customize the display panel.

ViewPnl = uipanel(figure,'Title','Labeled Volume');

Display the labeled volume.

h = labelvolshow(label,vol,'Parent',ViewPnl);

Make the first non-background label (the second label) fully transparent. Change the color of the second non-background label to red and the third non-background label to yellow.

h.LabelOpacity(2) = 0;
h.LabelColor(3,:) = [1 0 0];
h.LabelColor(4,:) = [1 1 0];

Version History

Introduced in R2019a

R2022b: labelvolshow will be removed

labelvolshow will be removed in a future release. Use the viewer3d and volshow functions instead. The viewer3d function creates a Viewer3D object that you can use to modify aspects of the scene such as the camera, background colors, and lighting. The volshow object creates a Volume object that you can use to modify the labels and the appearance of the volumetric data, such as the rendering style, colormap, and transparency map. Specify and change the labels and intensity data by setting the OverlayData and Data properties of the Volume object, respectively.

Some of the properties of the labelvolshow object have a different name with the Viewer3D and Volume objects. In particular, use the Overlay properties of the Volume object to adjust the appearance of the volume labels. For more information, see Viewer Properties and Volume Properties.

Discouraged Usage	Recommended Replacement
This example uses the labelvolshow function to display labeled volume data. vol = labelvolshow(labels,volume);	Here is equivalent code, creating a Volume object using the volshow function. vol = volshow(volume,OverlayData=labels);
This example displays a labeled volume on a blue background and specifies the label colors. vol = labelvolshow(labels,volume, ... BackgroundColor="b",LabelColor=cmap); Change the background color and label colors by setting properties of the labelvolshow object. vol.BackgroundColor = "g"; vol.LabelColor = cmap2;	Here is equivalent code, setting the background color using a Viewer3D object and the label colors using a Volume object. viewer = viewer3d(BackgroundColor="b"); vol = volshow(V,OverlayData=labels, ... OverlayColormap=cmap,Parent=viewer); Change the background color by setting properties of the Viewer3D object and change the label colors by setting properties of the Volume object. viewer.BackgroundColor = "g"; vol.OverlayColormap = cmap2;