Quantcast

Documentation Center

  • Trial Software
  • Product Updates

patch

Create one or more filled polygons

Syntax

patch(X,Y,C)
patch(X,Y,Z,C)
patch(FV)
patch(X,Y,C,'PropertyName',propertyvalue...)
patch('PropertyName',propertyvalue,...)
handle = patch(...)

Properties

For a list of properties, see Patch Properties.

Description

patch(X,Y,C) adds a filled 2-D patch object to the current axes. A patch object is one or more polygons defined by the coordinates of its vertices. The elements of X and Y specify the vertices of a polygon . If X and Y are m-by-n matrices, MATLAB® draws n polygons with m vertices. C determines the color of the patch. For more information on color input requirements, see Coloring Patches.

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

See Introduction to Patch Objects for more information on using patch objects.

patch(X,Y,Z,C) creates a patch in 3-D coordinates. 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 might be only partly filled. In that case, it is better to divide the face into smaller polygons.

patch(FV) creates a patch using structure FV, which contains the fields vertices, faces, and optionally facevertexcdata. These fields correspond to the Vertices, Faces, and FaceVertexCData patch properties. Specifying only unique vertices and their connection matrix can reduce the size of the data for patches having many faces. For an example of how to specify patches with this method, see Specifying Patch Object Shapes.

patch(X,Y,C,'PropertyName',propertyvalue...) follows the X, Y, (Z), and C arguments with property name/property value pairs to specify additional patch properties. For a description of the properties, see 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).

patch('PropertyName',propertyvalue,...) specifies all properties using property name/property value pairs. This form lets you 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 lets you specify the patch using the Faces and Vertices properties instead of x-, y-, and z-coordinates. See Specifying Patch Object Shapes for more information.

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

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.

Examples

Specifying Patch Object Shapes

The next two examples create a patch object using two 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, and FaceVertexCData properties)

Create five triangular faces, each having three vertices, by specifying the x-, y-, and z-coordinates of each vertex:

xdata = [2 2 0 2 5;
         2 8 2 4 5;
         8 8 2 4 8];
ydata = [4 4 4 2 0;
         8 4 6 2 2;
         4 0 4 0 0];
zdata = ones(3,5);

% Red numbers denote the vertex indices.
% For this example:  
% xindices = [1 4 7 10 13;
%             2 5 8 11 14;
%             3 6 9 12 15];
% Blue numbers denote the face numbers.
patch(xdata,ydata,zdata,'w')

Create the five triangular faces, specifying faces and vertices:

% 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. More than one face may 
% use a given vertex.
% For this example, five triangles have 11 total vertices, 
% instead of 15. Each row contains 
% the x- and y-coordinates 
% of each vertex.
verts = [2 4; ...
        2 8; ...
        8 4; ...
        8 0; ...
        0 4; ...
        2 6; ...
        2 2; ...
        4 2; ...
        4 0; ...
        5 2; ...
        5 0 ];

% There are five faces, defined by connecting the 
% vertices in the order indicated.
faces = [ ...
        1  2  3; ...
        1  3  4; ...
        5  6  1; ...
        7  8  9; ...
        11 10 4 ];

% Create the patch by specifying the Faces, Vertices,
% and FaceVertexCData properties as well as the
% FaceColor property. Red numbers denote the vertex 
% numbers, as defined in faces. Blue indicate face numbers.
p = patch('Faces',faces,'Vertices',verts,'FaceColor','w');

% Using the previous values for verts and faces, you can 
% create the same patch object using a structure: 
patchinfo.Vertices = verts;
patchinfo.Faces = faces;
patchinfo.FaceColor = 'w';

patch(patchinfo);

Coloring Patches

There are many ways to customize your patch objects using colors. The appropriate input depends on:

  • Whether you want to change the edge colors

  • How you specified the patch faces:

    • Using face/vertex values

    • Using x-, y-, and z-coordinates

The following sections present the various options available.

Specifying Edge Colors

The following options apply to the edge colors of your patch object. The settings are independent of the face colors, but the colors themselves depend on the colors specified at each vertex. Markers show the color at each vertex. Specify the colors using the EdgeColor property. To explore the options using the Sample Input Code, create a base patch object:

xdata = [2     2     0     2     5;
         2     8     2     4     5;
         8     8     2     4     8];
ydata = [4     4     4     2     0;
         8     4     6     2     2;
         4     0     4     0     0];
cdata = [15     0     4     6    10;
         1     2     5     7     9;
         2     3     0     8     3];
p = patch(xdata,ydata,cdata,'Marker','o',...
          'MarkerFaceColor','flat',...
          'FaceColor','none')

For more detailed information on how the EdgeColor property works, see the Patch Properties page.

Desired LookEdgeColor ValueSample Code
All edges have the same color, around all faces. This option does not rely on the FaceColor value.

ColorSpec
set(p,'EdgeColor','g')
Each edge corresponds to the color of the vertex that precedes the edge, with one color per edge. This option requires that the FaceColor property be flat or interp. By default, if you specify CData when creating the patch object, its FaceColor property is interp.

'flat'
set(p,'EdgeColor','flat',...
    'LineWidth',3)
Each edge corresponds to the vertex colors, interpolated between vertices. This option requires that the FaceColor property be flat or interp. By default, if you specify CData when creating the patch object, its FaceColor property is interp.

'interp'
set(gcf,'Renderer','zbuffer')
set(p,'EdgeColor','interp',...
'LineWidth',5)
Edges have no color. This option does not rely on the FaceColor value. If set, markers retain vertex colors.

'none'
set(p,'EdgeColor','none')

Specifying Face Colors Using Face/Vertex Input Matrices

The following options apply to the face colors of your patch object when you specify the faces using face/vertex input matrices. To explore the options, start with a base patch object:

% For this example, there are five triangles (m = 5) 
% sharing eleven unique vertices (k = 11).  
verts = [2 4; ...
        2 8; ...
        8 4; ...
        8 0; ...
        0 4; ...
        2 6; ...
        2 2; ...
        4 2; ...
        4 0; ...
        5 2; ...
        5 0 ];
faces = [1  2  3; ...
         1  3  4; ...
         5  6  1; ...
         7  8  9; ...
         11 10 4];
p = patch('Faces',faces,'Vertices',verts,'FaceColor','b');

For more information on the relevant properties, see FaceColor, FaceVertexCData, and CDataMapping.

Desired LookParameter ValuesSample Code
All faces have the same color.

  • FaceColor: ColorSpec

  • FaceVertexCData: [] (no input)

    An empty array is the default value, and patch ignores any input until you set FaceColor to 'flat' or 'interp'.

  • Color source: truecolor

  • CDataMapping: 'direct' or 'scaled'.

    'scaled' is the default value, but neither affects the outcome.

set(p,'FaceColor','r')

or

set(p,'FaceColor',[1 0 0])
Each face has a single, unique color, indexed from a selected section of the colormap.

  • FaceColor: 'flat'

  • FaceVertexCData: m-by-1 matrix of index values

  • Color source: A selected portion of the colormap

  • CDataMapping: 'scaled'

clear cdata
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 60]';
set(p,'FaceColor','flat',...
'FaceVertexCData',cdata,...
'CDataMapping','scaled')
Each face has a single, unique color, indexed from the whole colormap.

  • FaceColor: 'flat'

  • FaceVertexCData: m-by-1 matrix of index values

  • Color source: colormap

  • CDataMapping: 'direct'

    'scaled' is the default value when you input CData values. If you want to change the axes CLim property, but want your patch object to index the entire colormap, use 'CDataMapping','direct'.

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 60]';
set(p,'FaceColor','flat',...
'FaceVertexCData',cdata,...
'CDataMapping','direct')
Each face has a single, unique color, determined by truecolor value input.

  • FaceColor: 'flat'

  • FaceVertexCData: m-by-3 matrix of truecolor values, from 0 to 1

  • Color source: truecolor

  • CDataMapping: 'direct' or 'scaled'.

    'scaled' is the default value, but neither affects the outcome.

clear cdata 
cdata = [0 0 1 0 0.8;
         0 1 0 0 0.8;
         1 0 1 0 0.8]';
set(p,'FaceColor','flat',...
'FaceVertexCData',cdata)
Each unique vertex has a single, unique color, indexed from a selected section of the colormap. Faces each have a single, unique color, but edges may have 'flat' or 'interp' color.

  • FaceColor: 'flat'

  • FaceVertexCData: k-by-1 matrix of index values

  • Color source: A selected portion of the colormap

  • CDataMapping: 'scaled'

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 ...
60 12 23 40 13 26 24]';
set(p,'FaceColor','flat',...
'FaceVertexCData',cdata,...
'EdgeColor','flat',...
'LineWidth',5,...
'CDataMapping','scaled')
Each unique vertex has a single, unique color, indexed from the whole colormap. Faces each have a single, unique color, but edges may have 'flat' or 'interp' color.

  • FaceColor: 'flat'

  • FaceVertexCData: k-by-1 matrix of index values

  • Color source: colormap

  • CDataMapping: 'direct'

    'scaled' is the default value when you input CData values. If you want to change the axes CLim property, but want your patch object to index the entire colormap, use 'CDataMapping','direct'.

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 ...
60 12 23 40 13 26 24]';
set(p,'FaceColor','flat',...
'FaceVertexCData',cdata,...
'CDataMapping','direct',...
'EdgeColor','flat',...
'LineWidth',5)
Each unique vertex has a single, unique color, determined by truecolor value input. Faces each have a single, unique color, but edges may have 'flat' or 'interp' color.

  • FaceColor: 'flat'

  • FaceVertexCData: k-by-3 matrix of truecolor values, from 0 to 1

  • Color source: truecolor

  • CDataMapping: 'direct' or 'scaled'.

    'scaled' is the default value, but neither affects the outcome.

clear cdata 
cdata = [0 0 1; 
         0 1 0;
         0 1 1;
         1 0 0;
         1 0 1;
         1 1 0;
         0 0 0;
         0.2 0.2 0.2;
         0.4 0.4 0.4;
         0.6 0.6 0.6;
         0.8 0.8 0.8];
set(p,'FaceColor','flat',...
'FaceVertexCData',cdata,...
'EdgeColor','interp',...
'LineWidth',5)
Each unique vertex has a single, unique color, indexed from a selected section of the colormap. Edges may have 'flat' or 'interp' color.

  • FaceColor: 'interp'

  • FaceVertexCData: k-by-1 matrix of index values

  • Color source: A selected portion of the colormap

  • CDataMapping: 'scaled'

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 ...
60 12 23 40 13 26 24]';
set(p,'FaceColor','interp',...
'FaceVertexCData',cdata,...
'EdgeColor','flat',...
'LineWidth',5,...
'CDataMapping','scaled')
Each unique vertex has a single, unique color, indexed from the whole colormap. Edges may have 'flat' or 'interp' color.

  • FaceColor: 'interp'

  • FaceVertexCData: k-by-1 matrix of index values

  • Color source: colormap

  • CDataMapping: 'direct'

    'scaled' is the default value when you input CData values. If you want to change the axes CLim property, but want your patch object to index the entire colormap, use 'CDataMapping','direct'.

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 ...
 60 12 23 40 13 26 24]';
set(p,'FaceColor','interp',...
'FaceVertexCData',cdata,...
'CDataMapping','direct',...
'EdgeColor','flat',...
'LineWidth',5)
Each unique vertex has a single, unique color, determined by truecolor value input. Edges may have 'flat' or 'interp' color.

  • FaceColor: 'interp'

  • FaceVertexCData: k-by-3 matrix of truecolor values, from 0 to 1

  • Color source: truecolor

  • CDataMapping: 'direct' or 'scaled'.

    'scaled' is the default value, but neither affects the outcome.

clear cdata 
cdata = [0 0 1; 
         0 1 0;
         0 1 1;
         1 0 0;
         1 0 1;
         1 1 0;
         0 0 0;
         0.2 0.2 0.2;
         0.4 0.4 0.4;
         0.6 0.6 0.6;
         0.8 0.8 0.8];
set(p,'FaceColor','interp',...
'FaceVertexCData',cdata,...
'EdgeColor','interp',...
'LineWidth',5)

Specifying Face Colors Using x-, y-, and z-Coordinate Input

The following options apply to the face colors of your patch object when you specify the faces using x-, y-, and z-coordinates. To explore the options, start with a base patch object:

% For this example, there are five (m=5) triangles (n=3). 
% The total number of vertices is mxn, or k = 15. 
xdata = [2 2 0 2 5;
         2 8 2 4 5;
         8 8 2 4 8];
ydata = [4 4 4 2 0;
         8 4 6 2 2;
         4 0 4 0 0];
zdata = ones(3,5);
p = patch(xdata,ydata,zdata,'b')

For more information on the relevant properties, see FaceColor, CData, and CDataMapping.

Desired LookParameter ValuesSample Code
All faces have the same color.

  • FaceColor: ColorSpec

  • CData: [] (no input)

  • Color source: truecolor

  • CDataMapping: 'direct' or 'scaled'.

    'scaled' is the default value, but neither affects the outcome.

set(p,'FaceColor','r')

or

set(p,'FaceColor',[1 0 0])
Each face has a single, unique color, indexed from a selected section of the colormap.

  • FaceColor: 'flat'

  • CData: m-by-1 matrix of index values

  • Color source: A selected portion of the colormap

  • CDataMapping: 'scaled'

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 60];
set(p,'FaceColor','flat',...
'CData',cdata,...
'CDataMapping','scaled')
Each face has a single, unique color, indexed from the whole colormap.

  • FaceColor: 'flat'

  • CData: m-by-1 matrix of index values

  • Color source: colormap

  • CDataMapping: 'direct'

    'scaled' is the default value when you input CData values. If you want to change the axes CLim property, but want your patch object to index the entire colormap, use 'CDataMapping','direct'.

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 60];
set(p,'FaceColor','flat',...
'CData',cdata,...
'CDataMapping','direct')
Each face has a single, unique color, determined by truecolor value input.

  • FaceColor: 'flat'

  • CData: m-by-1-by-3 matrix of truecolor values, from 0 to 1

  • Color source: truecolor

  • CDataMapping: 'direct' or 'scaled'.

    'scaled' is the default value, but neither affects the outcome.

clear cdata 
cdata(:,:,1) = [0 0 1 0 0.8];
cdata(:,:,2) = [0 0 0 0 0.8];
cdata(:,:,3) = [1 1 1 0 0.8];
set(p,'FaceColor','flat',...
'CData',cdata)
Each unique vertex has a single, unique color, indexed from a selected section of the colormap. Faces each have a single, unique color, but edges may have 'flat' or 'interp' color.

  • FaceColor: 'flat'

  • CData: m-by-n matrix of index values

  • Color source: A selected portion of the colormap

  • CDataMapping: 'scaled'

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 60;
         12 23 40 13 26;
         24 8 1 65 42];
set(p,'FaceColor','flat',...
'CData',cdata,...
'EdgeColor','flat',...
'LineWidth',5,...
'CDataMapping','scaled')
Each unique vertex has a single, unique color, indexed from the whole colormap. Faces each have a single, unique color, but edges may have 'flat' or 'interp' color.

  • FaceColor: 'flat'

  • CData: m-by-n matrix of index values

  • Color source: colormap

  • CDataMapping: 'direct'

    'scaled' is the default value when you input CData values. If you want to change the axes CLim property, but want your patch object to index the entire colormap, use 'CDataMapping','direct'.

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 60;
         12 23 40 13 26;
         24 8 1 65 42];
set(p,'FaceColor','flat',...
'CData',cdata,...
'CDataMapping','direct',...
'EdgeColor','flat',...
'LineWidth',5)
Each vertex has a single, unique color, determined by truecolor value input. Faces each have a single, unique color, but edges may have 'flat' or 'interp' color.

  • FaceColor: 'flat'

  • CData: m-by-n-by-3 matrix of truecolor values, from 0 to 1

  • Color source: truecolor

  • CDataMapping: 'direct' or 'scaled'.

    'scaled' is the default value, but neither affects the outcome.

clear cdata 
cdata(:,:,1) = [0 0 1 0 0.8;
                0 0 1 0.2 0.6;
                0 1 0 0.4 1];

cdata(:,:,2) = [0 0 0 0 0.8;
                1 1 1 0.2 0.6;
                1 0 0 0.4 0];

cdata(:,:,3) = [1 1 1 0 0.8;
                0 1 0 0.2 0.6;
                1 0 1 0.4 0];
set(p,'FaceColor','flat',...
'CData',cdata,...
'EdgeColor','interp',...
'LineWidth',5)
Each vertex has a single, unique color, indexed from a selected section of the colormap. Edges may have 'flat' or 'interp' color.

  • FaceColor: 'interp'

  • CData: m-by-n matrix of index values

  • Color source: A selected portion of the colormap

  • CDataMapping: 'scaled'

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 60;
         12 23 40 13 26;
         24 8 1 65 42];
set(p,'FaceColor','interp',...
'CData',cdata,...
'EdgeColor','flat',...
'LineWidth',5,...
'CDataMapping','scaled')
Each vertex has a single, unique color, indexed from the whole colormap. Edges may have 'flat' or 'interp' color.

  • FaceColor: 'interp'

  • CData: m-by-n matrix of index values

  • Color source: colormap

  • CDataMapping: 'direct'

    'scaled' is the default value when you input CData values. If you want to change the axes CLim property, but want your patch object to index the entire colormap, use 'CDataMapping','direct'.

clear cdata 
set(gca,'CLim',[0 40])
cdata = [15 30 25 2 60;
        12 23 40 13 26;
        24 8 1 65 42];
set(p,'FaceColor','interp',...
'CData',cdata,...
'CDataMapping','direct',...
'EdgeColor','flat',...
'LineWidth',5)
Each vertex has a single, unique color, determined by truecolor value input. Edges may have 'flat' or 'interp' color.

  • FaceColor: 'interp'

  • CData: m-by-n-by-3 matrix of truecolor values, from 0 to 1

  • Color source: truecolor

  • CDataMapping: 'direct' or 'scaled'.

    'scaled' is the default value, but neither affects the outcome.

clear cdata 
cdata(:,:,1) = [0.8 0.1 0.2
    0.9 0.3 1;
    0.1 0.5 0.9;
    0.9 1 0.5;
    0.6 0.9 0.8];

cdata(:,:,2) =[0.1 0.6 0.7;
    0.4 0.1 0.7;
    0.9 0.8 0.3;
    0.7 0.9 0.6;
    0.9 0.6 0.1];

cdata(:,:,3) =[0.7 0.8 0.4;
    0.1 0.6 0.3;
    0.2 0.3 0.7;
    0.0 0.9 0.7;
    0.0 0.0 0.1];
set(p,'FaceColor','interp',...
'CData',cdata,...
'EdgeColor','interp',...
'LineWidth',5)

See Also

| | | | | | | | | |

Tutorials

Was this topic helpful?