Main Content

viewer3d

Create viewer for 3-D image display

Since R2022b

    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

    Create a 3-D viewer window, 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;

    Add a title and scale bar within the viewer window.

    viewer.Title = "Brain MRI";
    viewer.ScaleBar = "on";

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

    collapse all

    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.

    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 the hexadecimal color codes.

    Color NameShort NameRGB TripletHexadecimal Color CodeAppearance
    "red""r"[1 0 0]"#FF0000"

    Sample of the color red

    "green""g"[0 1 0]"#00FF00"

    Sample of the color green

    "blue""b"[0 0 1]"#0000FF"

    Sample of the color blue

    "cyan" "c"[0 1 1]"#00FFFF"

    Sample of the color cyan

    "magenta""m"[1 0 1]"#FF00FF"

    Sample of the color magenta

    "yellow""y"[1 1 0]"#FFFF00"

    Sample of the color yellow

    "black""k"[0 0 0]"#000000"

    Sample of the color black

    "white""w"[1 1 1]"#FFFFFF"

    Sample of the color white

    "none"Not applicableNot applicableNot applicableNo color

    This table lists the default color palettes for plots in the light and dark themes.

    PalettePalette Colors

    "gem" — Light theme default

    Before R2025a: Most plots use these colors by default.

    Sample of the "gem" color palette

    "glow" — Dark theme default

    Sample of the "glow" color palette

    You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

    RGB = orderedcolors("gem");
    H = rgb2hex(RGB);

    Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

    Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

    Example: BackgroundColor="r"

    Example: BackgroundColor="green"

    Example: BackgroundColor=[0 0.4470 0.7410]

    Example: BackgroundColor="#FF8800"

    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.

    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 the hexadecimal color codes.

    Color NameShort NameRGB TripletHexadecimal Color CodeAppearance
    "red""r"[1 0 0]"#FF0000"

    Sample of the color red

    "green""g"[0 1 0]"#00FF00"

    Sample of the color green

    "blue""b"[0 0 1]"#0000FF"

    Sample of the color blue

    "cyan" "c"[0 1 1]"#00FFFF"

    Sample of the color cyan

    "magenta""m"[1 0 1]"#FF00FF"

    Sample of the color magenta

    "yellow""y"[1 1 0]"#FFFF00"

    Sample of the color yellow

    "black""k"[0 0 0]"#000000"

    Sample of the color black

    "white""w"[1 1 1]"#FFFFFF"

    Sample of the color white

    "none"Not applicableNot applicableNot applicableNo color

    This table lists the default color palettes for plots in the light and dark themes.

    PalettePalette Colors

    "gem" — Light theme default

    Before R2025a: Most plots use these colors by default.

    Sample of the "gem" color palette

    "glow" — Dark theme default

    Sample of the "glow" color palette

    You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

    RGB = orderedcolors("gem");
    H = rgb2hex(RGB);

    Before R2023b: Get the RGB triplets using RGB = get(groot,"FactoryAxesColorOrder").

    Before R2024a: Get the hexadecimal color codes using H = compose("#%02X%02X%02X",round(RGB*255)).

    Example: GradientColor="r"

    Example: GradientColor="green"

    Example: GradientColor=[0 0.4470 0.7410]

    Example: GradientColor="#FF8800"

    Since R2025a

    Title for viewer, specified as a string scalar or character vector. The title appears in the top center of the viewer window.

    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.

    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.

    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

    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

    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