viewer3d

Create viewer for 3-D image display

Since R2022b

Syntax

viewer = viewer3d

viewer = viewer3d(parent)

viewer = viewer3d(___,Name=Value)

Description

viewer = viewer3d creates a Viewer object in a new figure window that is configured for 3-D image display. Use viewer to query and modify properties of the Viewer object after you create the object. For a list of properties, see Viewer Properties.

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

example

viewer = viewer3d(___,Name=Value) creates a Viewer object and sets properties of the object using one or more name-value arguments, in addition to any of the input arguments from previous syntaxes.

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

example

Examples

collapse all

Change Appearance of 3-D Scene

Open Live Script

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 = 
  Viewer with properties:

                Parent: [1×1 Figure]
              Position: [1 1 560 420]
              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: [0 0 0]

        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

Open Live Script

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

collapse all

`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 Viewer object for 3-D display 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 Viewer 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"

`AmbientLight` — Strength of ambient light
`0.4` (default) | numeric scalar

Strength of ambient light in the scene, specified as a numeric scalar in the range [0, 1]. This property specifies the amount of ambient light in the scene.

`DiffuseLight` — Strength of diffuse light
`0.6` (default) | numeric scalar

Strength of diffuse light, specified as a numeric scalar in the range [0, 1]. This property specifies the amount of diffuse light provided by the light sources in the Lights property of Viewer.

Specify the DiffuseLight name-value argument if you have one light source in a scene, or to update all light sources in a multilight scene to the same value. To adjust an individual light in a multilight scene, set the Intensity property of the corresponding Light object in the Lights property.

`Denoising` — Apply edge-preserving denoising
`"off"` (default) | on/off logical value

Since R2023b

Apply edge-preserving denoising, 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 viewer applies edge-preserving denoising to all objects in the viewer. By default, the value is "off". If the viewer contains a Volume object displayed using cinematic rendering, meaning the RenderingStyle property value is "CinematicRendering", the Denoising value automatically changes to "on".

Output Arguments

collapse all

`viewer` — 3-D viewer
`Viewer` object

3-D viewer, returned as a Viewer object configured for 3-D image display. When you create a Viewer by using the viewer3d function, the function sets certain properties to support 3-D visualization. For details about which properties have different defaults when created by viewer3d instead of viewer2d, see Viewer Properties.

More About

collapse all

Events

To receive notification from the Viewer 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 Viewer 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
`AnnotationAdded`	A point or line annotation has been interactively added to the viewer. This event does not execute if an annotation is programmatically added.	`images.ui.graphics.events.AnnotationAddedEventData`	`NotifyAccess`: `private` `ListenAccess`: `public`
`AnnotationEdited`	The label of a point or line annotation has been interactively edited. This event does not execute if an annotation label is programmatically edited.	`images.ui.graphics.events.AnnotationEditedEventData`	`NotifyAccess`: `private` `ListenAccess`: `public`
`AnnotationMoved`	A point or line annotation has been interactively moved within the viewer. This event does not execute if an annotation is programmatically moved.	`images.ui.graphics.events.AnnotationMovedEventData`	`NotifyAccess`: `private` `ListenAccess`: `public`
`AnnotationRemoved`	A point or line annotation has been interactively removed from the viewer. This event does not execute if an annotation is programmatically removed.	`images.ui.graphics.events.AnnotationRemovedEventData`	`NotifyAccess`: `private` `ListenAccess`: `public`
`CameraMoving`	The camera is being interactively moved. This event does not execute if the camera is programmatically moved.	`images.ui.graphics.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.graphics.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.graphics.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.graphics.events.ClippingPlanesChangedEventData`	`NotifyAccess`: `private` `ListenAccess`: `public`
`CropRegionChanged`	The crop region stops being interactively changed. This event does not execute if the crop region is programmatically changed.	`images.ui.graphics.events.CropRegionChangedEventData`	`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

expand all

R2024b: Returns `Viewer` object, new default background color

The function now returns a Viewer object, because the Viewer3D object has been renamed to reflect support for displaying 2-D images. The Viewer object has the same properties and default behavior as Viewer3D. Existing instances of the Viewer3D object continue to work as expected, and there are no plans to remove support for references to Viewer3D.
The default background color for a viewer created using viewer3d in light mode has changed from [0 0.329 0.529] to [0 0.251 0.451]. The default background gradient color in light mode has changed from [0.0 0.561 1.0] to[0.0667 0.4431 0.7451].

R2024b: Specify additional cropping options

Crop the objects in a viewer to a spherical or cylindrical region, in addition to the rectangular crop region supported in prior releases. To add a spherical or cylindrical crop region, specify the CropRegion property as a 4-element or 5-element row vector, respectively. Modify the crop region interactively in the viewer window.
Specify whether to view the region inside or outside a crop region by specifying the new CropMode property.

R2024a: 3-D point and line annotations

Label 3-D points and lines in a scene using annotations. Add annotations interactively from the Viewer3D toolbar. By default, the viewer labels point annotations with their 3-D coordinates, and line annotations with their length.

Programmatically query or update annotations using the new Annotations property of Viewer3D. The new Point and Line objects and their properties define the position, color, and label of point and line annotations, respectively.

R2023b: New lighting and denoising options, interactive crop box and 3-D scissors tools

The Viewer3D object has new properties and tools to control the lighting and remove objects in a scene. To set any of these property values at object creation, specify them to the viewer3d function as name-value arguments.

Control the strength of ambient and diffuse light within a viewer using the new AmbientLight and DiffuseLight properties, respectively.
Apply denoising to the objects in a viewer using the new Denoising property. Specify the amount of smoothing and standard deviation of the Gaussian smoothing kernel using the new DenoisingDegreeOfSmoothing and DenoisingSigma properties, respectively.
Use a crop box to crop the objects in a viewer to a rectangular subregion. To interactively add a crop box, click the crop box button in the Viewer3D axes toolbar. To crop the display, drag the faces of the crop box. To move the crop box, hold Ctrl while you drag. You can programmatically define the crop region by setting the new CropRegion property.
Use the 3-D scissors tool to remove regions from of a viewer. To enable the tool, click the scissors button in the Viewer3D axes toolbar. Draw a 2-D polygon that contains the object you want to remove. The tool removes everything from the 3-D cut region, which it defines by extruding the polygon along the axis normal to the drawing plane.

viewer3d

Syntax

Description

Examples

Change Appearance of 3-D Scene

Create Scene in UI Container

Input Arguments

`parent` — Parent of 3-D viewer
`Figure` object (default) | `Panel` object | `GridLayout` object | `Tab` object

Name-Value Arguments

`BackgroundColor` — Color of background
RGB triplet | hexadecimal color code | color name | short color name

`BackgroundGradient` — Background gradient is present
`"on"` (default) | on/off logical value

`GradientColor` — Color of background gradient shading
RGB triplet | hexadecimal color code | color name | short color name

`AmbientLight` — Strength of ambient light
`0.4` (default) | numeric scalar

`DiffuseLight` — Strength of diffuse light
`0.6` (default) | numeric scalar

`Denoising` — Apply edge-preserving denoising
`"off"` (default) | on/off logical value

Output Arguments

`viewer` — 3-D viewer
`Viewer` object

More About

Events

Tips

Version History

R2024b: Returns `Viewer` object, new default background color

R2024b: Specify additional cropping options

R2024a: 3-D point and line annotations

R2023b: New lighting and denoising options, interactive crop box and 3-D scissors tools

See Also

Topics

viewer3d

Syntax

Description

Examples

Change Appearance of 3-D Scene

Create Scene in UI Container

Input Arguments

parent — Parent of 3-D viewer Figure object (default) | Panel object | GridLayout object | Tab object

Name-Value Arguments

BackgroundColor — Color of background RGB triplet | hexadecimal color code | color name | short color name

BackgroundGradient — Background gradient is present "on" (default) | on/off logical value

GradientColor — Color of background gradient shading RGB triplet | hexadecimal color code | color name | short color name

AmbientLight — Strength of ambient light 0.4 (default) | numeric scalar

DiffuseLight — Strength of diffuse light 0.6 (default) | numeric scalar

Denoising — Apply edge-preserving denoising "off" (default) | on/off logical value

Output Arguments

viewer — 3-D viewer Viewer object

More About

Events

Tips

Version History

R2024b: Returns Viewer object, new default background color

R2024b: Specify additional cropping options

R2024a: 3-D point and line annotations

R2023b: New lighting and denoising options, interactive crop box and 3-D scissors tools

See Also

Topics

`parent` — Parent of 3-D viewer
`Figure` object (default) | `Panel` object | `GridLayout` object | `Tab` object

`BackgroundColor` — Color of background
RGB triplet | hexadecimal color code | color name | short color name

`BackgroundGradient` — Background gradient is present
`"on"` (default) | on/off logical value

`GradientColor` — Color of background gradient shading
RGB triplet | hexadecimal color code | color name | short color name

`AmbientLight` — Strength of ambient light
`0.4` (default) | numeric scalar

`DiffuseLight` — Strength of diffuse light
`0.6` (default) | numeric scalar

`Denoising` — Apply edge-preserving denoising
`"off"` (default) | on/off logical value

`viewer` — 3-D viewer
`Viewer` object

R2024b: Returns `Viewer` object, new default background color