Main Content


Display surface in 3-D viewer

Since R2022b


    A Surface object displays a 3-D surface within a scene. Properties of the object control the appearance and behavior of the surface.



    s = images.ui.graphics3d.Surface(viewer) creates a Surface object and sets the Parent property as the specified 3-D viewer viewer. Use s to query and modify properties of the Surface object after you create the object.


    s = images.ui.graphics3d.Surface(viewer,Name=Value) also sets properties of the object using one or more name-value arguments.

    For example, images.ui.graphics3d.Surface(viewer,Alpha=0.5) creates a Surface object with a transparency of 0.5.


    expand all

    Parent of the Surface object, specified as a Viewer3D object. To create a Viewer3D object, use the viewer3d function. A Surface object cannot be reparented.

    Surface grayscale data displayed in the viewer, specified as a 3-D logical array with nonsingleton dimensions or as a triangulation object containing 3-D points.

    Object is visible in the 3-D 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.

    Transformation applied to the surface in the 3-D scene, specified as an affinetform3d, rigidtform3d, simtform3d, or transltform3d object. Use the Transformation property to increase the size of the surface, rotate the surface, or perform other affine transformations. The default value is an affinetform3d object that performs an identity transformation.

    Transparency of the surface, specified as a number in the range [0, 1].

    Color of the surface, specified as one of these values.

    • RGB triplet, color name, or short color name — Use the same color for all the vertices on the surface.

    • n-by-3 numeric matrix representing n RGB triplets — Use a different color for each vertex on the surface. Each row of the matrix defines one color. The number of rows must equal the number of vertices.

    You can specify any color using an RGB triplet. An RGB triplet is a 3-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].

    You can specify some common colors by name as a string scalar or character vector. This table lists the named color options and the equivalent RGB triplets.

    Color NameShort NameRGB TripletAppearance
    "red""r"[1 0 0]

    A rectangle colored pure red

    "green""g"[0 1 0]

    A rectangle colored pure green

    "blue""b"[0 0 1]

    A rectangle colored pure blue

    "cyan" "c"[0 1 1]

    A rectangle colored pure cyan

    "magenta""m"[1 0 1]

    A rectangle colored pure magenta

    "yellow""y"[1 1 0]

    A rectangle colored pure yellow

    "black""k"[0 0 0]

    A rectangle colored black

    "white""w"[1 1 1]

    A rectangle colored white

    Here are the RGB triplets for the default colors that MATLAB® uses in many types of plots.

    RGB TripletAppearance
    [0 0.4470 0.7410]

    A rectangle colored medium blue

    [0.8500 0.3250 0.0980]

    A rectangle colored reddish-orange

    [0.9290 0.6940 0.1250]

    A rectangle colored dark yellow

    [0.4940 0.1840 0.5560]

    A rectangle colored dark purple

    [0.4660 0.6740 0.1880]

    A rectangle colored light green

    [0.3010 0.7450 0.9330]

    A rectangle colored light blue

    [0.6350 0.0780 0.1840]

    A rectangle colored dark red

    Example: Color="r"

    Example: Color="green"

    Example: Color=[0 0.4470 0.7410]

    Clipping planes applied locally to the object, 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. 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.

    Display surface as wireframe mesh, 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 surface is rendered as a wireframe mesh. When this value is "off", the faces are rendered according to the color and transparency of the object.


    collapse all

    Load a 3-D image and corresponding label data.

    datadir = fullfile(toolboxdir("images"),"imdata","BrainMRILabeled");

    The label data has three classes. Create binary masks for each class.

    mask1 = (label == 1);
    mask2 = (label == 2);
    mask3 = (label == 3);

    Display the scene using a Viewer3D object.

    viewer = viewer3d;

    Display the image data using a Volume object. Render the image data using maximum intensity projection.

    obj = volshow(vol,Parent=viewer, ...

    Create three Surface objects, one for each class. Display the surfaces using the lines colormap. Skip the first color, which is a shade of blue that is similar to the color of the scene. The three surfaces appear red, yellow, and purple, respectively.

    cmap = lines;
    surf1 = images.ui.graphics3d.Surface(viewer,Color=cmap(2,:),Data=mask1);
    surf2 = images.ui.graphics3d.Surface(viewer,Color=cmap(3,:),Data=mask2);
    surf3 = images.ui.graphics3d.Surface(viewer,Color=cmap(4,:),Data=mask3);

    More About

    expand all

    Version History

    Introduced in R2022b