Viewer Properties

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 image or 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

expand all

`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.9608 0.9608 0.9608] if you create the viewer using the viewer2d function and [0 0.251 0.451] if you create the viewer using the viewer3d function. When you select dark mode in MATLAB, the default color is [0.1 0.1 0.1], regardless of the function you use to create the viewer.

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/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.

If you create the viewer using the viewer2d function, the default value is "off" to display the image against a solid background.
If you create the viewer using the viewer3d function, the default value is "on" to help visualize the volume in 3-D space.

`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.0667 0.4431 0.7451]. 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

expand all

`Lighting` — Light source is enabled
`"on"` (default) | on/off logical value

Light source is enabled, 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 the light source or sources in the Lights property.

`Lights` — Light sources
`Light` object | array of `Light` objects

Since R2023b

Light sources, specified as a Light object or array of Light objects. Each Light object defines a light source in the scene. By default, Lights specifies one light source above and to the right of the camera.

If you have multiple light sources in a scene, use the Light object properties to specify the state (on or off), position, intensity, and size of each light source. You can enable or disable all light sources simultaneously by specifying the Lighting property.

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

Since R2023b

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

Since R2023b

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.

Specify the DiffuseLight property 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.

`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. The Viewer object applies the specified color to all light sources in the viewer.

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` — Position of light sources
3-element vector

Position of the light source or sources, specified as a 3-element vector of the form [x y z]. Changing the LightPosition property changes the point from which the lights illuminates the scene.

Specify the LightPosition property 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 Position property of the corresponding Light object in the Lights property.

`LightPositionMode` — Mode for light positions
`"right"` (default) | `"manual"` | `"auto"` | `"headlight"` | `"left"` | `"camera-above"` | ...

Mode for the light positions, specified as one of these values.

"headlight" — Light is at the camera location and moves with the camera.
"right" — Light is above and to the right of the camera and moves with the camera. This is the default value.
"left" — Light is above and to the left of the camera and moves with the camera.
"camera-above" — Light is above the camera and moves with the camera.
"target-right" — Light is to the right of the camera target and moves with the camera.
"target-left" — Light is to the left of the camera target and moves with the camera.
"target-above" — Light is above the camera target and moves with the camera.
"target-below" — Light is below the camera target and moves with the camera.
"target-behind" — Light is behind the camera target and moves with the camera.
"manual" — The light is at the position specified by the LightPosition property. The light does not move with the camera.
"auto" — The light moves with the camera.

Setting the LightPosition property changes this property to "manual". Specify the LightPositionMode property 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 PositionMode property of the corresponding Light object in the Lights property.

Denoising

expand all

`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".

`DenoisingDegreeOfSmoothing` — Denoising degree of smoothing
`0.1` (default) | numeric scalar

Since R2023b

Denoising degree of smoothing, specified as a numeric scalar in the range [0, 1]. This property affects the visualization only when the Denoising property value is "on". A smaller value preserves details with lower intensity variance, and a larger value smooths neighborhoods with higher intensity variance, such as strong edges.

`DenoisingSigma` — Standard deviation of smoothing filter
`2` (default) | positive integer scalar

Since R2023b

Standard deviation of the smoothing filter kernel, specified as a positive integer scalar. This property affects the visualization only when the Denoising property value is "on". A larger value increases the contribution of more distant neighboring pixels, effectively increasing the neighborhood size.

Interactivity

expand all

`Interactions` — Interactivity of volume
`"all"` | `"none"` | string array

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

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.
`"crop"`	You can interactively crop the scene using a rectangular, spherical, or cylindrical 3-D crop region. You can further customize the supported crop interactions with the `CropInteractions` property.
`"scissors"`	You can interactively crop regions out of the scene using the 3-D scissors tool. The viewer supports this tool when the viewer contains `Volume` objects. The viewer does not support this tool when the viewer contains one or more `Surface` or `BlockedVolume` objects.
`"annotate"`	You can interactively add, edit, and remove 3-D point and line annotations. You can control the placement of annotations with the `Annotations` property.

If you create the viewer using the viewer2d function, the default value is ["zoom" "pan"] to support 2-D zoom and pan interactions.
If you create the viewer using the viewer3d function, the default value is "all" to support all interactions.

`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.

This property affects the visualization only when Interactions is "all" or a string array that contains "clip".

`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.

This property affects the visualization only when Interactions is "all" or a string array that contains "slice".

`CropInteractions` — Interactivity of crop region
`"all"` (default) | `"none"` | string array

Since R2023b

Interactivity of the crop region, specified as "all", "none", or a string array that includes any combination of the strings listed in the table. When specified as "all", the viewer supports all interactions in the table. When specified as "none", you cannot interact with the crop region, but you can still update the crop region programmatically by specifying the CropRegion property.

Crop Interaction Description

Crop Interaction	Description
`"add"`	Add a new rectangular crop region from the viewer toolstrip by selecting the crop box icon . You can only have one crop region in a viewer at a time. While you can add a rectangular crop region either from the toolstrip or programmatically, to add a spherical or cylindrical crop region, you must programmatically specify the `CropRegion` property.
`"remove"`	Remove crop region using right-click.
`"move"`	Resize and move the crop region. Resize the crop region by dragging the surface of the crop region. Move the crop region by holding Ctrl while you drag the faces of the crop region.

"add"

Add a new rectangular crop region from the viewer toolstrip by selecting the crop box icon . You can only have one crop region in a viewer at a time.

While you can add a rectangular crop region either from the toolstrip or programmatically, to add a spherical or cylindrical crop region, you must programmatically specify the CropRegion property.

"remove" Remove crop region using right-click.

"move" Resize and move the crop region. Resize the crop region by dragging the surface of the crop region. Move the crop region by holding Ctrl while you drag the faces of the crop region.

This property affects the visualization only when Interactions is "all" or a string array that contains "crop".

`CropRegion` — Position of crop box
`[]` (default) | 2-by-3 numeric matrix | 4-element numeric row vector | 5-element numeric row vector

Since R2023b

Position of the crop box in world coordinates, specified as one of the options in the table. Use the CropInteractions property to specify whether you can change this region interactively. This property affects the visualization only when Interactions is "all" or a string array that contains "crop".

Shape	Value
Rectangular	2-by-3 numeric matrix of the form `[xmin ymin zmin; xmax ymax zmax]`, where the first and second rows specify the minimum and maximum coordinates of the crop box, respectively.
Spherical (since R2024b)	4-element numeric row vector of the form `[x y z radius]`, where (x, y, z) and radius specify the center and radius of the sphere, respectively.
Cylindrical (since R2024b)	5-element numeric row vector of the form `[x y z radius height]`, where (x, y, z), radius, and height specify the center, radius, and height of the cylinder, respectively.

`CropMode` — Crop mode
`"inclusive"` (default) | `"exclusive"`

Since R2024b

Crop mode for the crop region defined by CropRegion, specified as "inclusive" or "exclusive". When set to "inclusive", objects inside the crop region are visible and objects outside the crop region are hidden. When set to "exclusive", objects outside the crop region are visible and objects inside the crop region are hidden.

Data Types: char | string

`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"` | `"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. This is the default value when you create the viewer using the `viewer3d` function.
`"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 image data size and GPU capabilities. This is the default value when you create the viewer using the `viewer2d` function.
`"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 viewer that does not contain any underlying UI components or graphics objects.

To display a context menu when you right-click any portion of a 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 Viewer object for 3-D display and specify a context menu. The context menu appears when you right-click the viewer.

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

Clipping Planes

expand all

`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.

Viewer Annotations

expand all

`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".

`Annotations` — Annotations in scene
`[]` (default) | array of `Point` and `Line` objects

Since R2024a

Annotations in the scene, specified as an array of Point and Line objects. Each Point object specifies a point annotation, and each Line object specifies a line annotation.

`OrientationAxes` — Display orientation axes
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.

If you create the viewer using the viewer2d function, the default value is "off".
If you create the viewer using the viewer3d function, the default value is "on".

`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
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.

If you create the viewer using the viewer2d function, the default value is "on". The viewer displays a scale bar with the zoom level of the image. The zoom level is based on a combination of available screen size, the image size, and the viewer camera zoom level. A scale bar zoom level of 100% indicates that one screen pixel displays one data pixel, or one unit in world coordinates if you specify the Transformation property.
If you create the viewer using the viewer3d function, the default value is "off". If you specify the value as "on", the viewer displays a measurement scale bar along with units specified by SpatialUnits.

`SpatialUnits` — Spatial units for viewer
string scalar

Spatial units for the viewer, specified as a string scalar. Use this value to change the units label associated with viewer display tools, such as the scale bar and point and line annotations. For example, if you specify the Transformation property of a Volume object to display an object in millimeters, you can optionally specify SpatialUnits as "mm".

If you create the viewer using the viewer2d function, the default value is "pixels".
If you create the viewer using the viewer3d function, the default value is "voxels".

Parent/Child

expand all

`Parent` — Parent of viewer
`Figure` object (default) | `Panel` object | `GridLayout` object | `Tab` object

Parent of the 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 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 viewer. When the parent is a GridLayout object, you can adjust the layout of the viewer using the Layout property.

`Children` — Children of viewer
array of `Image`, `Volume`, `BlockedVolume`, and `Surface` objects | empty `GraphicsPlaceholder` array

This property is read-only.

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

Position

expand all

`Position` — Size and location of viewer excluding margins
`[0 0 561 421]` (default) | 4-element vector

Size and location of the viewer relative to the parent object, 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 viewer is a GridLayout object.

`Units` — Position units
`'pixels'` (default) | `'normalized'` | `'inches'` | `'centimeters'` | `'points'` | `'characters'`

Position units, specified as 'pixels', 'normalized', 'inches', 'centimeters', 'points', or 'characters'. This value specifies units for the Position property. The recommended value is 'pixels'. To manage the position of multiple UI components in a parent, create a GridLayout object using uigridlayout.

To specify units for the viewer display tools, such as the scale bar and point and line annotations, see SpatialUnits.

`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 viewer is a GridLayout object. If the parent of the 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 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 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 viewer span multiple rows or columns, specify the Row or Column property as a 2-element vector. For example, this viewer spans columns 2 through 3.

viewer.Layout.Column = [2 3];

Version History

Introduced in R2022b

expand all

R2024b: Renamed from Viewer3D, new default background color

To reflect new support for 2-D image display, the Viewer3D object is now the Viewer object. 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, new property for spatial units

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.

Specify the units label for display tools such as the scale bar and annotations using the SpatialUnits property, which replaces the ScaleBarUnits property from previous releases. If you have existing code that specifies units using ScaleBarUnits, you do not need to update your code, as Viewer3D passes the specified value to SpatialUnits automatically.

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

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, click and drag on the faces of the crop box. To move the crop box, press Ctrl while you click and 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.

Viewer Properties

Camera Controls

CameraPosition — Camera position [1 1 1] (default) | 3-element vector

CameraTarget — Camera target [0 0 0] (default) | 3-element vector

CameraUpVector — Upwards direction [0 0 1] (default) | 3-element vector

CameraZoom — Camera zoom level 1 (default) | positive number

Color

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

BackgroundGradient — Background gradient is present on/off logical value

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

Lighting

Lighting — Light source is enabled "on" (default) | on/off logical value

Lights — Light sources Light object | array of Light objects

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

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

LightColor — Color of light [1 1 1] (default) | hexadecimal color code | RGB triplet | color name | short color name

LightPosition — Position of light sources 3-element vector

LightPositionMode — Mode for light positions "right" (default) | "manual" | "auto" | "headlight" | "left" | "camera-above" | ...

Denoising

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

DenoisingDegreeOfSmoothing — Denoising degree of smoothing 0.1 (default) | numeric scalar

DenoisingSigma — Standard deviation of smoothing filter 2 (default) | positive integer scalar

Interactivity

Interactions — Interactivity of volume "all" | "none" | string array

ClippingInteractions — Interactivity of clipping planes "all" (default) | "none" | string array

SliceInteractions — Interactivity of slice planes "translate" (default) | "all" | "none" | string array

CropInteractions — Interactivity of crop region "all" (default) | "none" | string array

CropRegion — Position of crop box [] (default) | 2-by-3 numeric matrix | 4-element numeric row vector | 5-element numeric row vector

CropMode — Crop mode "inclusive" (default) | "exclusive"

CurrentObject — Current object graphics object

RenderingQuality — Rendering quality "auto" | "low" | "medium" | "high"

ContextMenu — Context menu empty GraphicsPlaceholder array (default) | ContextMenu object

Clipping Planes

ClippingPlanes — Clipping planes in scene [] (default) | N-by-4 matrix

GlobalClipping — Use global clipping planes "off" (default) | on/off logical value

ClipIntersection — Clipping plane behavior "off" (default) | on/off logical value

Viewer Annotations

Toolbar — Toolbar visibility "on" (default) | on/off logical value

Annotations — Annotations in scene [] (default) | array of Point and Line objects

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

OrientationAxes — Display orientation axes on/off logical value

Box — Display box outline around scene boundary "off" (default) | on/off logical value

ScaleBar — Display scale bar on/off logical value

SpatialUnits — Spatial units for viewer string scalar

Parent/Child

Parent — Parent of viewer Figure object (default) | Panel object | GridLayout object | Tab object

Children — Children of viewer array of Image, Volume, BlockedVolume, and Surface objects | empty GraphicsPlaceholder array

Position

Position — Size and location of viewer excluding margins [0 0 561 421] (default) | 4-element vector

Units — Position units 'pixels' (default) | 'normalized' | 'inches' | 'centimeters' | 'points' | 'characters'

Layout — Layout options empty LayoutOptions array (default) | GridLayoutOptions object

Version History

R2024b: Renamed from Viewer3D, new default background color

R2024b: Specify additional cropping options

R2024a: 3-D point and line annotations, new property for spatial units

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

See Also

Topics

`CameraPosition` — Camera position
`[1 1 1]` (default) | 3-element vector

`CameraTarget` — Camera target
`[0 0 0]` (default) | 3-element vector

`CameraUpVector` — Upwards direction
`[0 0 1]` (default) | 3-element vector

`CameraZoom` — Camera zoom level
`1` (default) | positive number

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

`BackgroundGradient` — Background gradient is present
on/off logical value

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

`Lighting` — Light source is enabled
`"on"` (default) | on/off logical value

`Lights` — Light sources
`Light` object | array of `Light` objects

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

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

`LightColor` — Color of light
`[1 1 1]` (default) | hexadecimal color code | RGB triplet | color name | short color name

`LightPosition` — Position of light sources
3-element vector

`LightPositionMode` — Mode for light positions
`"right"` (default) | `"manual"` | `"auto"` | `"headlight"` | `"left"` | `"camera-above"` | ...

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

`DenoisingDegreeOfSmoothing` — Denoising degree of smoothing
`0.1` (default) | numeric scalar

`DenoisingSigma` — Standard deviation of smoothing filter
`2` (default) | positive integer scalar

`Interactions` — Interactivity of volume
`"all"` | `"none"` | string array

`ClippingInteractions` — Interactivity of clipping planes
`"all"` (default) | `"none"` | string array

`SliceInteractions` — Interactivity of slice planes
`"translate"` (default) | `"all"` | `"none"` | string array

`CropInteractions` — Interactivity of crop region
`"all"` (default) | `"none"` | string array

`CropRegion` — Position of crop box
`[]` (default) | 2-by-3 numeric matrix | 4-element numeric row vector | 5-element numeric row vector

`CropMode` — Crop mode
`"inclusive"` (default) | `"exclusive"`

`CurrentObject` — Current object
graphics object

`RenderingQuality` — Rendering quality
`"auto"` | `"low"` | `"medium"` | `"high"`

`ContextMenu` — Context menu
empty `GraphicsPlaceholder` array (default) | `ContextMenu` object

`ClippingPlanes` — Clipping planes in scene
`[]` (default) | N-by-4 matrix

`GlobalClipping` — Use global clipping planes
`"off"` (default) | on/off logical value

`ClipIntersection` — Clipping plane behavior
`"off"` (default) | on/off logical value

`Toolbar` — Toolbar visibility
`"on"` (default) | on/off logical value

`Annotations` — Annotations in scene
`[]` (default) | array of `Point` and `Line` objects

`Tooltip` — Tooltip
string scalar | string array | character vector | cell array of character vectors | categorical vector

`OrientationAxes` — Display orientation axes
on/off logical value

`Box` — Display box outline around scene boundary
`"off"` (default) | on/off logical value

`ScaleBar` — Display scale bar
on/off logical value

`SpatialUnits` — Spatial units for viewer
string scalar

`Parent` — Parent of viewer
`Figure` object (default) | `Panel` object | `GridLayout` object | `Tab` object

`Children` — Children of viewer
array of `Image`, `Volume`, `BlockedVolume`, and `Surface` objects | empty `GraphicsPlaceholder` array

`Position` — Size and location of viewer excluding margins
`[0 0 561 421]` (default) | 4-element vector

`Units` — Position units
`'pixels'` (default) | `'normalized'` | `'inches'` | `'centimeters'` | `'points'` | `'characters'`

`Layout` — Layout options
empty `LayoutOptions` array (default) | `GridLayoutOptions` object