#### 15.3.2.1 Creating Graphics Objects ¶

You can create any graphics object primitive by calling the function of the same name as the object; In other words, `figure`, `axes`, `line`, `text`, `image`, `patch`, `surface`, and `light` functions. These fundamental graphic objects automatically become children of the current axes object as if `hold on` was in place. Separately, axes will automatically become children of the current figure object and figures will become children of the root object.

If this auto-joining feature is not desired then it is important to call `newplot` first to prepare a new figure and axes for plotting. Alternatively, the easier way is to call a high-level graphics routine which will both create the plot and then populate it with low-level graphics objects. Instead of calling `line`, use `plot`. Or use `surf` instead of `surface`. Or use `fill` or `fill3` instead of `patch`.

axes `()` ¶
axes `(property, value, …)` ¶
axes `(hpar, property, value, …)` ¶
axes `(hax)` ¶
`h =` axes `(…)` ¶

  Create a Cartesian axes object and return a handle to it, or set the current axes to hax.

  Called without any arguments, or with property/value pairs, construct a new axes. The optional argument hpar is a graphics handle specifying the parent for the new axes and may be a figure, uipanel, or uitab.

  Called with a single axes handle argument hax, the function makes hax the current axes (as returned by `gca`). It also makes the figure which contains hax the current figure (as returned by `gcf`). Finally, it restacks the parent object’s `children` property so that the axes hax appears before all other axes handles in the list. This causes hax to be displayed on top of any other axes objects (Z-order stacking). In addition it restacks any legend or colorbar objects associated with hax so that they are also visible.

  Programming Note: The full list of properties is documented at Axes Properties.

  See also: gca, set, get.

line `()` ¶
line `(x, y)` ¶
line `(x, y, z)` ¶
line `("xdata", x, "ydata", y)` ¶
line `("xdata", x, "ydata", y, "zdata", z)` ¶
line `(…, property, value)` ¶
line `(hax, …)` ¶
`h =` line `(…)` ¶

  Create a line object from x and y (and possibly z) and insert it in the current axes.

  In the standard calling form the data x, y, and z may be scalars, vectors, or matrices. In the case of matrix inputs, `line` will attempt to orient scalars and vectors so the results can be plotted. This requires that one of the dimensions of the vector match either the number of rows or the number of columns of the matrix.

  In the low-level calling form (50% higher performance) where the data is specified by name (`line ("xdata", x, …)`) the data must be vectors. If no data is specified (`line ()`) then `x == y = [0, 1]`.

  Multiple property-value pairs may be specified for the line object, but they must appear in pairs.

  If called with only property/value pairs then any unspecified properties use their default values as specified on the root object.

  If the first argument hax is an axes handle, then plot into this axes, rather than the current axes returned by `gca`.

  The optional return value h is a graphics handle (or vector of handles) to the line objects created.

  Programming Note: The full list of properties is documented at Line Properties.

  The function `line` differs from `plot` in that line objects are inserted in to the current axes without first clearing the plot.

  See also: image, patch, rectangle, surface, text.

patch `()` ¶
patch `(x, y, c)` ¶
patch `(x, y, z, c)` ¶
patch `("Faces", faces, "Vertices", verts, …)` ¶
patch `(…, "prop", val, …)` ¶
patch `(…, propstruct, …)` ¶
patch `(hax, …)` ¶
`h =` patch `(…)` ¶

  Create patch object in the current axes with vertices at locations (x, y) and of color c.

  If the vertices are matrices of size MxN then each polygon patch has M vertices and a total of N polygons will be created. If some polygons do not have M vertices use NaN to represent "no vertex". If the z input is present then 3-D patches will be created.

  The color argument c can take many forms. To create polygons which all share a single color use a string value (e.g., `"r"` for red), a scalar value which is scaled by `clim` and indexed into the current colormap, or a 3-element RGB vector with the precise TrueColor.

  If c is a vector of length N then the ith polygon will have a color determined by scaling entry c(i) according to `clim` and then indexing into the current colormap. More complicated coloring situations require directly manipulating patch property/value pairs.

  Instead of specifying polygons by matrices x and y, it is possible to present a unique list of vertices and then a list of polygon faces created from those vertices. In this case the `"Vertices"` matrix will be an Nx2 (2-D patch) or Nx3 (3-D patch). The MxN `"Faces"` matrix describes M polygons having N vertices—each row describes a single polygon and each column entry is an index into the `"Vertices"` matrix to identify a vertex. The patch object can be created by directly passing the property/value pairs `"Vertices"`/verts, `"Faces"`/faces as inputs.

  Instead of using property/value pairs, any property can be set by passing a structure propstruct with the respective field names.

  If the first argument hax is an axes handle, then plot into this axes, rather than the current axes returned by `gca`.

  The optional return value h is a graphics handle to the created patch object.

  Programming Notes:

  1. The full list of properties is documented at Patch Properties. Useful patch properties include: `"edgecolor"`, `"facecolor"`, `"faces"`, `"vertices"`, and `"facevertexcdata"`.
  2. Unexpected geometry results can occur from mixing x-y-z and face-vertex forms of defining geometry.
  3. Unexpected patch color results can occur from using `"cdata"` color definitions with face-vertex defined geometry or `"facevertexcdata"` color definitions with x-y-z defined geometry.

  See also: fill, get, set.

surface `(x, y, z, c)` ¶
surface `(x, y, z)` ¶
surface `(z, c)` ¶
surface `(z)` ¶
surface `(…, prop, val, …)` ¶
surface `(hax, …)` ¶
`h =` surface `(…)` ¶

  Create a surface graphic object given matrices x and y from `meshgrid` and a matrix of values z corresponding to the x and y coordinates of the surface.

  If x and y are vectors, then a typical vertex is (x(j), y(i), z(i,j)). Thus, columns of z correspond to different x values and rows of z correspond to different y values. If only a single input z is given then x is taken to be `1:columns (z)` and y is `1:rows (z)`.

  Any property/value input pairs are assigned to the surface object.

  If the first argument hax is an axes handle, then plot into this axes, rather than the current axes returned by `gca`.

  The optional return value h is a graphics handle to the created surface object.

  Programming Note: The full list of properties is documented at Surface Properties.

  See also: surf, mesh, patch, line.

light `()` ¶
light `(…, "prop", val, …)` ¶
light `(hax, …)` ¶
`h =` light `(…)` ¶

  Create a light object in the current axes or for axes hax.

  When a light object is present in an axes object, and the properties `"EdgeLighting"` or `"FaceLighting"` of a `patch` or `surface` object are set to a value other than `"none"`, these objects are drawn with lighting effects. Supported values for Lighting properties are `"none"` (no lighting effects), `"flat"` (faceted look of the objects), and `"gouraud"` (linear interpolation of the lighting effects between the vertices). If the lighting mode is set to `"flat"`, the `"FaceNormals"` property is used for lighting. For `"gouraud"`, the `"VertexNormals"` property is used.

  Up to eight light objects are supported per axes. (Implementation dependent)

  Lighting is only supported for OpenGL graphic toolkits (i.e., `"fltk"` and `"qt"`).

  A light object has the following properties which alter the appearance of the plot.

  `"Color":` The color of the light can be passed as an

    RGB-vector (e.g., `[1 0 0]` for red) or as a string (e.g., `"r"` for red). The default color is white (`[1 1 1]`).

  `"Position":` The direction from which the light emanates as a

    1x3-vector. The default direction is `[1 0 1]`.

  `"Style":` This string defines whether the light emanates from a

    light source at infinite distance (`"infinite"`) or from a local point source (`"local"`). The default is `"infinite"`.

  If the first argument hax is an axes handle, then add the light object to this axes, rather than the current axes returned by `gca`.

  The optional return value h is a graphics handle to the created light object.

  Programming Note: The full list of properties is documented at Light Properties.

  See also: lighting, material, patch, surface.