Examples

This example creates a patch object using two different methods:

• Specifying x-, y-, and z-coordinates and color data (XData, YData, ZData, and CData properties).
• Specifying vertices, the connection matrix, and color data (Vertices, Faces, FaceVertexCData, and FaceColor properties).

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.

x = [0 0;0 1;1 1];
y = [1 1;2 2;2 1];
z = [1 1;1 1;1 1];
tcolor(1,1,1:3) = [1 1 1];
tcolor(1,2,1:3) = [.7 .7 .7];
patch(x,y,z,tcolor)

Notice that each face shares two vertices with the other face (V₁-V₄ and V₃-V₅).

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.

vert = [0 1 1;0 2 1;1 2 1;1 1 1];

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

fac = [1 2 3;1 3 4];

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

tcolor = [1 1 1;.7 .7 .7];

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.

patch('Faces',fac,'Vertices',vert,'FaceVertexCData',tcolor,...
      'FaceColor','flat')

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.

set(0,'DefaultPatchPropertyName',PropertyValue...)
set(gcf,'DefaultPatchPropertyName',PropertyValue...)
set(gca,'DefaultPatchPropertyName',PropertyValue...)

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