MATLAB Function Reference    
patch

Create patch graphics object

Syntax

Description

patch is the low-level graphics function for creating patch graphics objects. A patch object is one or more polygons defined by the coordinates of its vertices. You can specify the coloring and lighting of the patch. See the Creating 3-D Models with Patches for more information on using patch objects.

patch(X,Y,C) adds the filled two-dimensional patch to the current axes. The elements of X and Y specify the vertices of a polygon. If X and Y are matrices, MATLAB draws one polygon per column. C determines the color of the patch. It can be a single ColorSpec, one color per face, or one color per vertex (see "Remarks"). If C is a 1-by-3 vector, it is assumed to be an RGB triplet, specifying a color directly.

patch(X,Y,Z,C) creates a patch in three-dimensional coordinates.

patch(FV) creates a patch using structure FV, which contains the fields vertices, faces, and optionally facevertecdata. These fields correspond to the Vertices, Faces, and FaceVertexCData patch properties.

patch(...'PropertyName',PropertyValue...) follows the X, Y, (Z), and C arguments with property name/property value pairs to specify additional patch properties.

patch('PropertyName',PropertyValue,...) specifies all properties using property name/property value pairs. This form enables you to omit the color specification because MATLAB uses the default face color and edge color, unless you explicitly assign a value to the FaceColor and EdgeColor properties. This form also allows you to specify the patch using the Faces and Vertices properties instead of x-, y-, and z-coordinates. See the "Examples" section for more information.

handle = patch(...) returns the handle of the patch object it creates.

Remarks

Unlike high-level area creation functions, such as fill or area, patch does not check the settings of the figure and axes NextPlot properties. It simply adds the patch object to the current axes.

If the coordinate data does not define closed polygons, patch closes the polygons. The data can define concave or intersecting polygons. However, if the edges of an individual patch face intersect themselves, the resulting face may or may not be completely filled. In that case, it is better to break up the face into smaller polygons.

Specifying Patch Properties

You can specify properties as property name/property value pairs, structure arrays, and cell arrays (see the set and get reference pages for examples of how to specify these data types).

There are two patch properties that specify color:

The CData and FaceVertexCData properties accept color data as indexed or true color (RGB) values. See the CData and FaceVertexCData property descriptions for information on how to specify color.

Indexed color data can represent either direct indices into the colormap or scaled values that map the data linearly to the entire colormap (see the caxis function for more information on this scaling). The CDataMapping property determines how MATLAB interprets indexed color data.

Color Data Interpretation

You can specify patch colors as:

The following tables summarize how MATLAB interprets color data defined by the CData and FaceVertexCData properties.

Interpretation of the CData Property

[X,Y,Z]Data
CData Required for
Results Obtained
Dimensions
Indexed
True Color

m-by-n
scalar
1-by-1-by-3
Use the single color specified for all patch faces. Edges can be only a single color.
m-by-n
1-by-n
(n >= 4)
1-by-n-by-3
Use one color for each patch face. Edges can be only a single color.
m-by-n
m-by-n
m-by-n-3
Assign a color to each vertex. patch faces can be flat (a single color) or interpolated. Edges can be flat or interpolated.

Interpretation of the FaceVertexCData Property

Vertices
Faces
FaceVertexCData Required for
Results Obtained
Dimensions
Dimensions
Indexed
True Color

m-by-n
k-by-3
scalar
1-by-3
Use the single color specified for all patch faces. Edges can be only a single color.
m-by-n
k-by-3
k-by-1
k-by-3
Use one color for each patch face. Edges can be only a single color.
m-by-n
k-by-3
m-by-1
m-by-3
Assign a color to each vertex. patch faces can be flat (a single color) or interpolated. Edges can be flat or interpolated.

Examples

This example creates a patch object using two different methods:

Specifying X, Y, and Z Coordinates

The first approach specifies the coordinates of each vertex. In this example, the coordinate data defines two triangular faces, each having three vertices. Using true color, the top face is set to white and the bottom face to gray.

Notice that each face shares two vertices with the other face (V1-V4 and V3-V5).

Specifying Vertices and Faces

The Vertices property contains the coordinates of each unique vertex defining the patch. The Faces property specifies how to connect these vertices to form each face of the patch. For this example, two vertices share the same location so you need to specify only four of the six vertices. Each row contains the x, y, and z-coordinates of each vertex.

There are only two faces, defined by connecting the vertices in the order indicated.

To specify the face colors, define a 2-by-3 matrix containing two RGB color definitions.

With two faces and two colors, MATLAB can color each face with flat shading. This means you must set the FaceColor property to flat, since the faces/vertices technique is available only as a low-level function call (i.e., only by specifying property name/property value pairs).

Create the patch by specifying the Faces, Vertices, and FaceVertexCData properties as well as the FaceColor property.

Specifying only unique vertices and their connection matrix can reduce the size of the data for patches having many faces. See the descriptions of the Faces, Vertices, and FaceVertexCData properties for information on how to define them.

MATLAB does not require each face to have the same number of vertices. In cases where they do not, pad the Faces matrix with NaNs. To define a patch with faces that do not close, add one or more NaN to the row in the Vertices matrix that defines the vertex you do not want connected.

Object Hierarchy

Setting Default Properties

You can set default patch properties on the axes, figure, and root levels.

PropertyName is the name of the patch property and PropertyValue is the value you are specifying. Use set and get to access patch properties.

Property List

The following table lists all patch properties and provides a brief description of each. The property name links take you to an expanded description of the properties.

Property Name
Property Description
Property Value
Data Defining the Object
Faces
Connection matrix for Vertices
Values: m-by-n matrix
Default: [1,2,3]
Vertices
Matrix of x-, y-, and z-coordinates of the vertices (used with Faces)
Values: matrix
Default: [0,1;1,1;0,0]
XData
The x-coordinates of the vertices of the patch
Values: vector or matrix
Default: [0;1;0]
YData
The y-coordinates of the vertices of the patch
Values: vector or matrix
Default: [1;1;0]
ZData
The z-coordinates of the vertices of the patch
Values: vector or matrix
Default: [] empty matrix
Specifying Color
CData
Color data for use with the XData/YData/ZData method
Values: scalar, vector, or matrix
Default: [] empty matrix
CDataMapping
Controls mapping of CData to colormap
Values: scaled, direct
Default: scaled
EdgeColor
Color of face edges
Values: ColorSpec, none, flat, interp
Default: ColorSpec
FaceColor
Color of face
Values: ColorSpec, none, flat, interp
Default: ColorSpec
FaceVertexCData
Color data for use with Faces/Vertices method
Values: matrix
Default: [] empty matrix
MarkerEdgeColor
Color of marker or the edge color for filled markers
Values: ColorSpec, none, auto
Default: auto
MarkerFaceColor
Fill color for markers that are closed shapes
Values: ColorSpec, none, auto
Default: none
Controlling the Effects of Lights
AmbientStrength
Intensity of the ambient light
Values: scalar >=0 and <=1
Default: 0.3
BackFaceLighting
Controls lighting of faces pointing away from camera
Values: unlit, lit, reverselit
Default: reverselit
DiffuseStrength
Intensity of diffuse light
Values: scalar >=0 and <=1
Default: 0.6
EdgeLighting
Method used to light edges
Values: none, flat, gouraud, phong
Default: none
FaceLighting
Method used to light edges
Values: none, flat, gouraud, phong
Default: none
NormalMode
MATLAB-generated or user-specified normal vectors
Values: auto, manual
Default: auto
SpecularColorReflectance
Composite color of specularly reflected light
Values: scalar 0 to 1
Default: 1
SpecularExponent
Harshness of specular reflection
Values: scalar >= 1
Default: 10
SpecularStrength
Intensity of specular light
Values: scalar >=0 and <=1
Default: 0.9
VertexNormals
Vertex normal vectors
Values: matrix
Defining Edges and Markers
LineStyle
Select from five line styles.
Values: -, --, :, -., none
Default: -
LineWidth
The width of the edge in points
Values: scalar
Default: 0.5 points
Marker
Marker symbol to plot at data points
Values: see Marker property
Default: none
MarkerSize
Size of marker in points
Values: size in points
Default: 6
Specifying Transparency


AlphaDataMapping
Transparency mapping method
none, direct, scaled
Default: scaled
EdgeAlpha
Transparency of the edges of patch faces
scalar, flat, interp
Default: 1 (opaque)
FaceAlpha
Transparency of the patch face
scalar, flat, interp
Default: 1 (opaque)
FaceVertexAlphaData
Face and vertex transparency data
m-by-1 matrix
Controlling the Appearance
Clipping
Clipping to axes rectangle
Values: on, off
Default: on
EraseMode
Method of drawing and erasing the patch (useful for animation)
Values: normal, none, xor, background
Default: normal
SelectionHighlight
Highlight patch when selected (Selected property set to on)
Values: on, off
Default: on
Visible
Make the patch visible or invisible
Values: on, off
Default: on
Controlling Access to Objects
HandleVisibility
Determines if and when the the patch's handle is visible to other functions
Values: on, callback, off
Default: on
HitTest
Determines if the patch can become the current object (see the figure CurrentObject property)
Values: on, off
Default: on
Controlling Callback Routine Execution
BusyAction
Specify how to handle callback routine interruption
Values: cancel, queue
Default: queue
ButtonDownFcn
Define a callback routine that executes when a mouse button is pressed on over the patch
Values: string
Default: '' (empty string)
CreateFcn
Define a callback routine that executes when an patch is created
Values: string
Default: '' (empty string)
DeleteFcn
Define a callback routine that executes when the patch is deleted (via close or delete)
Values: string
Default: '' (empty string)
Interruptible
Determine if callback routine can be interrupted
Values: on, off
Default: on (can be interrupted)
UIContextMenu
Associate a context menu with the patch
Values: handle of a Uicontrextmenu
General Information About the Patch
Children
Patch objects have no children
Values: [] (empty matrix)
Parent
The parent of a patch object is always an axes object
Value: axes handle
Selected
Indicate whether the patch is in a "selected" state.
Values: on, off
Default: on
Tag
User-specified label
Value: any string
Default: '' (empty string)
Type
The type of graphics object (read only)
Value: the string 'patch'
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)

See Also

area, caxis, fill, fill3, isosurface, surface


 pascal Patch Properties