viewer3d

Create 3-D viewer object

Since R2022b

Syntax

viewer = viewer3d

viewer = viewer3d(parent)

viewer = viewer3d(___,Name=Value)

Description

viewer = viewer3d creates a Viewer3D object in a new web figure. Use viewer to query and modify properties of the Viewer3D object after you create the object. For a list of properties, see Viewer3D Properties.

viewer = viewer3d(parent) creates a Viewer3D object in the specified parent container.

viewer = viewer3d(___,Name=Value) creates a Viewer3D object and sets properties of the object using one or more name-value arguments.

For example, viewer3d(BackgroundColor="green",BackgroundGradient=false) creates a Viewer3D object in a new web figure with a green background and no background gradient.

Examples

Change Appearance of 3-D Scene

Create a scene, and specify the appearance of the background and lighting using name-value arguments.

viewer = viewer3d(BackgroundColor="white", ...
    GradientColor=[0.5 0.5 0.5],Lighting="on")

viewer = 
  Viewer3D with properties:

                Parent: [1×1 Figure]
              Position: [0 0 561 421]
              Children: [0×0 GraphicsPlaceholder]

       BackgroundColor: [1 1 1]
    BackgroundGradient: on
         GradientColor: [0.5000 0.5000 0.5000]
       OrientationAxes: on
        ClippingPlanes: [0×4 single]
              Lighting: on
         LightPosition: [1 1 1]

        CameraPosition: [1 1 1]
          CameraTarget: [0 0 0]
        CameraUpVector: [0 0 1]
            CameraZoom: 1

  Show all properties

Display a volumetric image in the scene.

load(fullfile(toolboxdir("images"),"imdata", ...
    "BrainMRILabeled","images","vol_001.mat"));
mriVol = volshow(vol,Parent=viewer);

Change the camera perspective of the scene by setting scene properties using dot notation.

viewer.CameraPosition = [120 120 200];
viewer.CameraTarget = [120 120 -10];
viewer.CameraUpVector = [0 1 0];
viewer.CameraZoom = 1.5;

Create Scene in UI Container

Create a grid layout manager whose parent is a figure created using the uifigure function.

fig = uifigure(Name="MRI Volume");
g = uigridlayout(fig,[1 1],Padding=[0 0 0 0]);

Create a scene with the default appearance in the grid layout manager.

viewer = viewer3d(g);

Display a volumetric image in the scene.

load(fullfile(toolboxdir("images"),"imdata", ...
    "BrainMRILabeled","images","vol_001.mat"));
mriVol = volshow(vol,Parent=viewer);

Input Arguments

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.

Tip

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.

Example: parent = uifigure; viewer = viewer3d(parent); creates a parent figure using the uifigure function

Example: f = uifigure; parent = uipanel(f); viewer = viewer3d(parent); creates a parent Panel object whose parent is a figure created using the uifigure function.

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.

Example: viewer3d(BackgroundColor="green",BackgroundGradient=false) creates a Viewer3D object in a new figure with a green background and no background gradient.

Note

The properties listed here are only a subset. For a full list, see Viewer3D Properties.

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, 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 false, 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"

Output Arguments

viewer — 3-D viewer

Viewer3D object

3-D viewer, returned as a Viewer3D object.

More About

Events

To receive notification from the Viewer3D 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 Viewer3D 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
CameraMoving	The camera is being interactively moved. This event does not execute if the camera is programmatically moved.	images.ui.graphics3d.events.CameraMovedEventData	NotifyAccess: private ListenAccess: public
CameraMoved	The camera stops being interactively moved. This event does not execute if the camera is programmatically moved.	images.ui.graphics3d.events.CameraMovedEventData	NotifyAccess: private ListenAccess: public
ClippingPlanesChanging	A global clipping plane is being interactively moved. This event does not execute if the clipping plane is programmatically moved.	images.ui.graphics3d.events.ClippingPlanesChangedEventData	NotifyAccess: private ListenAccess: public
ClippingPlanesChanged	A global clipping plane stops being interactively moved. This event does not execute if the clipping plane is programmatically moved.	images.ui.graphics3d.events.ClippingPlanesChangedEventData	NotifyAccess: private ListenAccess: public
ViewerRefreshed	The viewer has been refreshed. You can refresh a viewer either by reparenting the viewer or by modifying the ancestor hierarchy of the parent object. When you refresh a viewer, the viewer is cleared and no longer contains any child objects. To recreate the scene, you can listen to this event and reconstruct any objects that were parented to the viewer.	event.EventData	NotifyAccess: private ListenAccess: public

Tips

• To clear all objects from the scene and delete all data containers previously added to the 3-D viewer, viewer, use the command:

  clear(viewer)

• To delete all objects in the scene and the 3-D viewer, viewer, use the command:

  delete(viewer)

Version History

Introduced in R2022b