patch

Purpose

Create a patch object.

Synopsis

patch(x,y,c)
patch(x,y,z,c)
patch('PropertyName',PropertyValue,...)
h = patch(...)

Description

patch is the low-level graphics function for creating patch objects. Patch objects are children of axes objects. A patch is a filled polygonal area that optionally accepts color data to use for shading. The patch function allows you to specify property name/property value pairs as input arguments. These properties, which control various aspects of the patch object, are described under "Object Properties." You can also set and query property values after creating the object using the set and get functions.

Unlike high-level area creating functions such as fill, patch does not clear the axes, set viewing parameters, nor perform any actions other than to generate a patch object in the current axes. If points (x,y) do not define a closed polygon, patch closes the polygon. The points in x and y can define a concave or self-intersecting polygon.

patch(x,y,c) adds the filled two-dimensional polygon defined by vectors x and y to the current axes. c specifies the color used to fill the polygon. The vertices of the polygon are specified by pairs of components of x and y.

If c is a scalar, it simply specifies the color of the polygon ("flat" coloring). If it is a vector the same length as x and y, its elements are scaled by caxis and used as indices into the current colormap to specify colors at the vertices; the color within the polygon is obtained by bilinear interpolation in the vertex colors.

If c is a string, the polygon(s) are filled with the specified color. The string can be either the letter: r, g, b, c, m, y, w, or k, or the names of the colors: red, green, blue, cyan, magenta, yellow, white, or black. In either case, the string must be enclosed in single quotes.

If x and y are matrices of the same size, patch draws one polygon per column. In this case, c can be one of the following:

  • A row vector whose size equals size(x,2) (i.e., equal to the number of columns in x or y) for flat shading.
  • A matrix the same size as x and y for interpolated shading.
  • A column vector having the same number of rows as x and y, in which case each patch uses this column to obtain vertex colors for interpolated shading.
    patch sets its FaceColor property to flat, interp, or a ColorSpec depending on the value of c.

    patch(x,y,z,c) creates patches in three-dimensional coordinates.

    h = patch(...) returns a column vector of handles corresponding to each patch object it creates.

    The x, y pair (x, y, z triple for three-dimensional space) can be followed by property name/property value pairs to specify additional patch properties. You can omit the x, y, pair (x, y, z triple for three-dimensional space) entirely and specify all properties using property name/property value pairs.

    patch is a low-level function that, ordinarily, is not used directly. Use fill and fill3 instead.

    Object Properties

    This section lists property names along with the type of values each accepts.

    ButtonDownFcn
    Callback string, object selection.
    Any legal MATLAB expression, including the name of an M-file or function. When you select the object, the string is passed to the eval function to execute the specified function. Initially the empty matrix.
    CData
    Color data.
    A vector of values that specifies the color at every point along the edge of the patch. MATLAB uses these values only if EdgeColor or FaceColor is set to interp or flat.
    Children
    Children of patch.
    Always the empty matrix; patch objects have no children.
    Clipping
    Clipping mode.
    on (Default.) Any portion of the patch outside the axes rectangle is not displayed.
    off Patch data is not clipped.
    EdgeColor
    Patch edge color.
    ColorSpec A three-element RGB vector or one of MATLAB's predefined names, specifying a single color for edges. The default edge color is black. See the ColorSpec reference page for more information on specifying color.
    none Edges are not drawn.
    flat Edges are a single color determined by the average of the color data for that patch.
    interp Edge color is determined by linear interpolation through the values at the patch vertices.
    EraseMode
    Erase mode.
    This property controls the technique MATLAB uses to draw and erase patch objects. This property is useful in creating animated sequences, where control of individual object redraw is necessary to improve performance and obtain the desired effect.
    normal (Default.) Redraws the affected region of the display, performing the three-dimensional analysis necessary to ensure that all objects are rendered correctly. This mode produces the most accurate picture, but is the slowest. The other modes are faster, but do not perform a complete redraw and are therefore less accurate.
    none The patch is not erased when it is moved or destroyed.
    xor The patch is drawn and erased by performing an exclusive OR (XOR) with the color of the screen beneath it. When the patch is erased, it does not damage the objects beneath it. Patch objects are dependent on the color of the screen beneath them, however, and are correctly colored only when over the figure background color.
    background The patch is erased by drawing it in the figure's background color. This damages objects that are behind the erased patch, but patch objects are always properly colored.
    FaceColor
    Patch face color.
    ColorSpec A three-element RGB vector or one of MATLAB's predefined names, specifying a single color for faces. See the ColorSpec reference page for more information on specifying color.
    none Faces are not drawn. You can still draw edges, however.
    flat (Default.) The values in c determine the face color for each patch.
    interp Face color is determined by linear interpolation through the values specified in the CData property.
    Interruptible
    Callback interruptibility.
    yes The callback specified by ButtonDownFcn is interruptible by other callbacks.
    no (Default.) The ButtonDownFcn callback is not interruptible.
    LineWidth
    Line width for patch edges.
    A scalar specifying the width, in points, of the patch edges. The default line width is 0.5.
    Parent
    Handle of the patch's parent object.
    A read-only property that contains the handle of the patch's parent object. The parent of a patch object is the axes in which it is displayed.
    Type
    Type of object.
    A read-only string; always 'patch' for a patch object.
    UserData
    User-specified data.
    Any matrix you want to associate with the patch object. The object does not use this data, but you can retrieve it using the get command.
    Visible
    Patch visibility.
    on (Default.) Patch is visible on the screen.
    off Patch is not drawn.
    XData
    Patch vertices x-coordinates.
    X-coordinates of the points along the edge of the patch. If a matrix, each column represents the x-coordinates for a separate patch. In this case, XData, YData, and ZData must all have the same number of rows.
    YData
    Patch vertices y-coordinates.
    Y-coordinates of the points along the edge of the patch. If a matrix, each column represents the y-coordinates for a separate patch. In this case, XData, YData, and ZData must all have the same number of rows.
    ZData
    Patch vertices z-coordinates.
    Z-coordinates of the points along the edge of the patch. If a matrix, each column represents the z-coordinates for a separate patch. In this case, XData, YData, and ZData must all have the same number of rows.

    Examples

    patch replicates a single column of vertex data to match the number of columns specified in other arguments. For example, this statement reuses the one column of data specified for ZData to produce two patches, each having four vertices.

    patch(rand(4,2),rand(4,2),rand(4,1))
    If all the data has the same number of columns and one row each, MATLAB transposes the matrices to produce plotable data. For example,

    patch(rand(1,4),rand(1,4),rand(1,4))
    is changed to

    patch(rand(4,1),rand(4,1),rand(4,1))
    This also applies to the case when just one or two matrices have one column. For example, this statement,

    patch(rand(2,4),rand(2,4),rand(1,4))
    is equivalent to

    patch(rand(4,2),rand(4,2),rand(4,1))

    See Also

    fill, fill3, line, text

    (c) Copyright 1994 by The MathWorks, Inc.