# 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 `EdgeColo`r 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.