Viewer3D Properties

Display scene in 3-D viewer

Since R2022b

Viewer3D properties control the appearance and behavior of a Viewer3D object. By changing property values, you can manage scene-level controls for volume rendering. Create a Viewer3D object using the viewer3d function.

Use dot notation to query and set properties. For example, these commands show how to create a Viewer3D object, query the value of the BackgroundColor property, and set the value of the BackgroundColor property, respectively.

viewer = viewer3d;
c = viewer.BackgroundColor;
viewer.BackgroundColor = "blue";

Camera Controls

CameraPosition — Camera position

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

Camera position, or viewpoint, 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. Changing the CameraPosition property changes the point from which you view the volume. For an illustration, see Camera Graphics Terminology.

CameraTarget — Camera target

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

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.

CameraUpVector — Upwards direction

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

Upwards direction for the camera, specified as a 3-element vector of the form [x y z]. By default, the z-axis is the up direction ([0 0 1]). For an illustration, see Camera Graphics Terminology.

CameraZoom — Camera zoom level

1 (default) | positive number

Camera zoom level, specified as a positive number.

Color and Lighting

BackgroundColor — Color of background

RGB triplet | hexadecimal color code | color name | short color name

Color of the background, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name. When you select light mode in MATLAB^®, the default color is [0 0.329 0.529]. When you select dark mode in MATLAB, the default color is [0.1 0.1 0.1].

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"
"none"	Not applicable	Not applicable	Not applicable	No color

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: BackgroundColor="r"

Example: BackgroundColor="green"

Example: BackgroundColor=[0 0.4470 0.7410]

Example: BackgroundColor="#FF8800"

BackgroundGradient — Background gradient is present

"on" (default) | on/off logical value

Background gradient is present in the scene, specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

This property specifies whether the background is shaded with a gradient from GradientColor to BackgroundColor. When this property is "off", the GradientColor property has no effect.

GradientColor — Color of background gradient shading

RGB triplet | hexadecimal color code | color name | short color name

Color of the background gradient shading, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name. When BackgroundGradient is true, the background is shaded as a gradient from GradientColor to BackgroundColor. When you select light mode in MATLAB, the default color is [0.0 0.561 1.0]. When you select dark mode in MATLAB, the default color is [0.3 0.3 0.3].

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"
"none"	Not applicable	Not applicable	Not applicable	No color

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: GradientColor="r"

Example: GradientColor="green"

Example: GradientColor=[0 0.4470 0.7410]

Example: GradientColor="#FF8800"

Lighting — Light source is present

"on" (default) | on/off logical value

Light source is present in the scene, specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

This property specifies whether to render the effects of a point light source coming from the same location as the camera.

LightColor — Color of light

[1 1 1] (default) | hexadecimal color code | RGB triplet | color name | short color name

Color of the light source, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name.

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"
"none"	Not applicable	Not applicable	Not applicable	No color

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: LightColor="r"

Example: LightColor="green"

Example: LightColor=[0 0.4470 0.7410]

Example: LightColor="#FF8800"

LightPosition — Location of light source

3-element vector

Location of the light source, specified as a 3-element vector of the form [x y z]. Changing the LightPosition property changes the point from which the light illuminates the scene. Light is emitted from this location in all directions, but shadows are not cast.

LightPositionMode — Mode for light location

"auto" (default) | "manual"

Mode for the light location, specified as

• "auto" — The Viewer3D object automatically changes the LightPosition property when the camera positioning changes.

• "manual" — The LightPosition property does not change when the camera moves.

Setting the LightPosition property changes this property to "manual".

Interactivity

Interactions — Interactivity of volume

"all" (default) | "none" | string array

Interactivity of the volume, specified as "all", "none", or a string array that includes any combination of strings listed in the table. When specified as "all", all interactions are allowed. When specified as "none", no interactions are allowed in the viewer.

Volume Interaction	Description
"zoom"	Zoom in on the scene.
"rotate"	Rotate the scene.
"pan"	Pan across the scene.
"axes"	You can click the labels of the orientation axes to snap to an orthogonal view.
"clip"	You can further customize the supported clipping interactions with the ClippingInteractions property.
"slice"	You can interactively adjust the slice planes of a Volume object when the RenderingStyle property of the object is "SlicePlanes". You can further customize the supported slice plane interactions with the SliceInteractions property.

SliceInteractions — Interactivity of slice planes

"translate" (default) | "all" | "none" | string array

Interactivity of the slice planes, specified as "all", "none", or a string array that includes any combination of the strings listed in the table. When this value is "none", you cannot interact with the slice planes, but you can still update the planes programmatically. To interact with the slices planes, you must set CurrentObject as an object that supports slice planes.

Slice Interaction	Description
"add"	Add new planes by clicking the axes toolbar button.
"remove"	Remove planes using right-click.
"rotate"	Rotate by dragging the ball.
"translate"	Translate planes by dragging the plane surface.

ClippingInteractions — Interactivity of clipping planes

"all" (default) | "none" | string array

Interactivity of the clipping planes, specified as "all", "none", or a string array that includes any combination of strings listed in the table. When specified as "all", all interactions are allowed. When specified as "none", no interactions are allowed.

When this value is "none", you cannot interact with the clipping planes, but you can still update the planes programmatically.

Clipping Interaction	Description
"add"	Add new planes by clicking the axes toolbar button.
"remove"	Remove planes using right-click.
"rotate"	Rotate by dragging the ball.
"translate"	Translate planes by dragging the plane surface.

CurrentObject — Current object

graphics object

Current object, returned as a child object of the viewer. When an object is added as a child of the viewer, MATLAB sets the CurrentObject property to that object. You can change CurrentObject by setting this property to the handle of another object that is a child of the viewer. When GlobalClipping is false, you can use this property to control which object receives clipping plane interactions.

RenderingQuality — Rendering quality

"auto" (default) | "low" | "medium" | "high"

Rendering quality, specified as one of the values in the table.

Value	Description
"auto"	Rendering quality automatically adjusts during interactions to improve performance. After the interaction, the rendering quality is restored.
"low"	Low rendering quality with high performance. Use this value when setting properties rapidly and repeatedly.
"medium"	Medium rendering quality, suitable for static and interactive visualization depending on the volume size and GPU capabilities.
"high"	High rendering quality, at the expense of reduced performance. Use this value when generating high-quality static images.

ContextMenu — Context menu

empty GraphicsPlaceholder array (default) | ContextMenu object

Context menu, specified as a ContextMenu object created using the uicontextmenu function. Use this property to display a context menu when you right-click an area of the 3-D viewer that does not contain any underlying UI components or graphics objects.

To display a context menu when you right-click any portion of 3-D viewer, write code to set the ContextMenu property of all underlying UI components and graphics objects whenever the ContextMenu property of the viewer is set.

For example, this code shows how to create a Viewer3D object and specify a context menu. The context menu appears when you right-click the 3-D viewer.

fig = uifigure;
cm = uicontextmenu(fig);
m1 = uimenu(cm);
viewer = viewer3d(fig,ContextMenu=cm);

Clipping Planes

ClippingPlanes — Clipping planes in scene

[] (default) | N-by-4 matrix

Clipping planes in the scene, specified as an N-by-4 matrix, where each row corresponds to the equation for a clipping plane. The maximum number of clipping planes, N, is six. When GlobalClipping is true, these clipping planes are applied to all objects in the scene, irrespective of any clipping planes set locally on each object. Each clipping plane is specified as a 1-by-4 vector, in world coordinates, following the Hessian normal form where the first three values represent the normal vector of the plane and the fourth value is the signed distance from the origin to the plane.

GlobalClipping — Use global clipping planes

"off" (default) | on/off logical value

Use global clipping planes, specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

When this value is "on", the planes specified by the ClippingPlanes property are applied to all objects. When this value is "off", the ClippingPlanes property has no effect and the clipping planes from each object are individually applied.

ClipIntersection — Clipping plane behavior

"off" (default) | on/off logical value

Clipping plane behavior with multiple planes, specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

When this value is "on", only intersecting or overlapping regions of all clipping planes are clipped. When this value is "off", a region is clipped if it is clipped by any clipping plane. Set ClipIntersection to "on" to use multiple planes to remove a single quadrant of an object.

Position

Position — Size and location of viewer excluding margins

[0 0 561 421] (default) | 4-element vector

Size and location of the viewer, excluding the margins for decorations such as axis labels and tick marks, specified as a 4-element vector of the form [left bottom width height].

Note

Setting this property has no effect when the parent of the 3-D viewer is a GridLayout object.

Units — Units of measurement

'pixels' (default)

Units of measurement, specified as 'pixels'.

Layout — Layout options

empty LayoutOptions array (default) | GridLayoutOptions object

Layout options, specified as a GridLayoutOptions object. This property specifies layout options only when the parent of the 3-D viewer is a GridLayout object. If the parent of the 3-D viewer is not a grid layout (for example, when the parent is a figure or panel), then this property is empty and has no effect.

You can place the 3-D viewer in the desired row and column of the grid by setting the Row and Column properties of the GridLayoutOptions object. For example, this code places a 3-D viewer in the third row and second column of its parent grid.

g = uigridlayout([4 3]);
viewer = viewer3d(g);
viewer.Layout.Row = 3;
viewer.Layout.Column = 2;

To make the 3-D viewer span multiple rows or columns, specify the Row or Column property as a 2-element vector. For example, this 3-D viewer spans columns 2 through 3.

viewer.Layout.Column = [2 3];

Annotations

Toolbar — Toolbar visibility

"on" (default) | on/off logical value

Toolbar visibility when hovering over the viewer, specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

When this value is "on", the toolbar is visible and contains the interactions specified by the Interactions property. When this value is "off", the toolbar is not visible. You can still use the interactions specified by the Interactions property when the toolbar is not visible. To prevent all interaction on the viewer, set Interactions to "none".

Tooltip — Tooltip

string scalar | string array | character vector | cell array of character vectors | categorical vector

Tooltip, specified as a string scalar, string array, character vector, cell array of character vectors, or categorical vector. Use this property to display a message when the user hovers the pointer over the component at run time. To display multiple lines of text, specify a cell array of character vectors or a string array. Each element in the array becomes a separate line of text. If you specify this property as a categorical vector, MATLAB uses the values in the vector, not the full set of categories.

OrientationAxes — Display orientation axes

"on" (default) | on/off logical value

Display the orientation axes, specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

When this value is "on", the orientation axes is displayed in the lower-left corner of the viewer. If no 3-D objects are loaded in the viewer, the orientation axes is not visible.

Box — Display box outline around scene boundary

"off" (default) | on/off logical value

Display box outline around scene boundary,specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

When this value is "on", a box is displayed that fits around every object in the scene. If no 3-D objects are loaded in the viewer, the box is not visible.

ScaleBar — Display scale bar

"off" (default) | on/off logical value

Display scale bar in the lower right corner, specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

When this value is "on", the scale bar is displayed along with units specified by ScaleBarUnits.

ScaleBarUnits — Units for scale bar

"Voxels" (default) | string

Units for scale bar, specified as a string. These units are for display to convert from the pixel coordinate to the world coordinate system.

Parent/Child

Parent — Parent of 3-D viewer

Figure object (default) | Panel object | GridLayout object | Tab object

Parent of the 3-D viewer, specified as a Figure object created using the uifigure function, or a Panel, GridLayout, or Tab object whose parent is a figure created using the uifigure function. You can use the uipanel, uigridlayout, and uitab functions to create the corresponding objects.

If you do not specify a parent when you create the 3-D viewer, MATLAB calls the uifigure function to create a new Figure object that serves as the parent container.

A GridLayout object is the recommended parent when you want to build an app in App Designer, or when you want to add and position other UI components in a figure with the 3-D viewer. When the parent is a GridLayout object, you can adjust the layout of the 3-D viewer using the Layout property.

Children — Children of 3-D viewer

array of Volume, BlockedVolume, and Surface objects | empty GraphicsPlaceholder array

This property is read-only.

Children of the 3-D viewer, returned as an array of Volume, BlockedVolume, and Surface objects or as an empty GraphicsPlaceholder array. Setting this property has no effect.

Version History

Introduced in R2022b